Hoosat Development

Overview

This skill provides comprehensive support for Hoosat blockchain development. Hoosat is a Kaspa fork that uses BLAKE3 and Hoohash consensus algorithms with HTN as its native token.

Key Characteristics:

• Ticker: HTN
• Address Prefix: hoosat: (mainnet), hoosattest: (testnet)
• Consensus: BLAKE3 and Hoohash (not kHash like Kaspa)
• SDKs: hoosat-sdk (Node.js), hoosat-sdk-web (Browser), hoosat-mo (Motoko/IC)
• API: https://proxy.hoosat.net/api/v1 (no auth required)
• Token Standard: HRC20 (KRC20 equivalent, in progress)

GitHub Repositories:

• https://github.com/hoosatnetwork
• https://github.com/Namp88

Quick Start

Check Network Status

To get current network information (block height, supply, hashrate, etc.), see the Checking Network Status section in references/api-reference.md.

Choose Your SDK

Generate a Hoosat Address

Node.js (hoosat-sdk):

import { HoosatCrypto } from 'hoosat-sdk';

const wallet = HoosatCrypto.generateKeyPair('mainnet');
console.log('Address:', wallet.address);
console.log('Private Key:', wallet.privateKey.toString('hex'));

Browser (hoosat-sdk-web):

import { HoosatCrypto } from 'hoosat-sdk-web';

const wallet = HoosatCrypto.generateKeyPair('mainnet');

Python:

python scripts/generate-address.py --network mainnet

Check Balance

Node.js:

import { HoosatClient, HoosatUtils } from 'hoosat-sdk';

const client = new HoosatClient({
  host: '54.38.176.95',
  port: 42420
});

const result = await client.getBalance('hoosat:qz7ulu8mmmul6hdcnssmjnt28h2xfer8dz9nfqamvvh86ngef4q8dvzxcjdqe');
if (result.ok) {
  const htn = HoosatUtils.sompiToAmount(result.result.balance);
  console.log(`Balance: ${htn} HTN`);
}

Browser:

import { HoosatWebClient } from 'hoosat-sdk-web';

const client = new HoosatWebClient({
  baseUrl: 'https://proxy.hoosat.net/api/v1'
});

const balance = await client.getBalance(address);

REST API:

curl https://proxy.hoosat.net/api/v1/address/hoosat:qz7ulu8mmmul6hdcnssmjnt28h2xfer8dz9nfqamvvh86ngef4q8dvzxcjdqe/balance

Send a Transaction

Node.js:

import { HoosatClient, HoosatCrypto, HoosatTxBuilder, HoosatUtils } from 'hoosat-sdk';

const client = new HoosatClient({ host: '54.38.176.95', port: 42420 });
const wallet = HoosatCrypto.importKeyPair(process.env.WALLET_PRIVATE_KEY);

// Get UTXOs
const utxosResult = await client.getUtxosByAddresses([wallet.address]);
const utxos = utxosResult.result.utxos;

// Calculate minimum fee
const minFee = await client.calculateMinFee(wallet.address);

// Build transaction
const builder = new HoosatTxBuilder();
for (const utxo of utxos) {
  builder.addInput(utxo, wallet.privateKey);
}
builder
  .addOutput(recipientAddress, HoosatUtils.amountToSompi('1.0'))
  .setFee(minFee)
  .addChangeOutput(wallet.address);

const signedTx = builder.sign();

// Submit
const result = await client.submitTransaction(signedTx);
if (result.ok) {
  console.log('TX ID:', result.result.transactionId);
}

Sign a Message

Node.js:

import { HoosatSigner } from 'hoosat-sdk';

const signature = HoosatSigner.signMessage(message, wallet.privateKey);
const isValid = HoosatSigner.verifyMessage(message, signature, wallet.publicKey);

Motoko (Internet Computer)

import Wallet "mo:hoosat-mo/wallet";
import Address "mo:hoosat-mo/address";

let wallet = Wallet.createMainnetWallet("key", ?"hoosat");
let result = await wallet.sendTransaction(from, to, amount, null, null);

SDK Modules Overview

HoosatClient (Node.js)

Main client for gRPC connection to Hoosat nodes.

const client = new HoosatClient({
  host: '54.38.176.95',
  port: 42420
});

Key Methods:

• getBalance(address) - Get address balance
• getUtxosByAddresses(addresses) - Get UTXOs
• submitTransaction(tx) - Submit signed transaction
• calculateMinFee(address) - Calculate minimum fee
• events.subscribeToUtxoChanges(addresses) - Real-time UTXO monitoring

HoosatCrypto (Node.js & Browser)

Cryptographic operations with BLAKE3 hashing.

Key Methods:

• generateKeyPair(network) - Generate new wallet
• importKeyPair(privateKey, network) - Import existing wallet
• signTransactionInput(tx, index, privateKey, utxo) - Sign transaction input
• blake3Hash(data) - BLAKE3 hashing

HoosatTxBuilder (Node.js & Browser)

Fluent transaction builder.

const builder = new HoosatTxBuilder();
builder
  .addInput(utxo, privateKey)
  .addOutput(recipientAddress, amount)
  .setFee(fee)
  .addChangeOutput(changeAddress);
  
const signedTx = builder.sign();

HoosatUtils (Node.js & Browser)

Utility functions for validation and conversion.

• amountToSompi(htn) - Convert HTN to sompi (1 HTN = 100M sompi)
• sompiToAmount(sompi) - Convert sompi to HTN
• isValidAddress(address) - Validate address
• getAddressNetwork(address) - Get network from address

HoosatEventManager (Node.js)

Real-time event streaming.

await client.events.subscribeToUtxoChanges([address]);
client.events.on(EventType.UtxoChange, (notification) => {
  console.log('Balance changed!');
});

HoosatQR (Node.js & Browser)

QR code generation for payments.

const qr = await HoosatQR.generatePaymentQR({
  address: merchantAddress,
  amount: HoosatUtils.amountToSompi('1.5'),
  label: 'My Store',
  message: 'Order #12345'
});

HoosatSigner (Node.js & Browser)

Message signing for authentication.

const signature = HoosatSigner.signMessage(message, privateKey);
const isValid = HoosatSigner.verifyMessage(message, signature, publicKey);

Error Handling

All SDK methods use a consistent error handling pattern:

interface BaseResult<T> {
  ok: boolean;
  result?: T;
  error?: string;
}

// Usage
const result = await client.getBalance(address);
if (result.ok) {
  console.log('Balance:', result.result.balance);
} else {
  console.error('Error:', result.error);
}

Network Types

• Mainnet: Production network (prefix: hoosat:)
• Testnet: Testing network (prefix: hoosattest:)

Address Formats

Hoosat uses Bech32 encoding:

• Mainnet: hoosat:qz7ulu8mmmul6hdcnssmjnt28h2xfer8dz9nfqamvvh86ngef4q8dvzxcjdqe
• Testnet: hoosattest:qqkqkzjvr7zwxxmjxjkmxx

Unit Conversion

• 1 HTN = 100,000,000 sompi
• Dust threshold: 1,000 sompi minimum
• Use HoosatUtils.amountToSompi() and HoosatUtils.sompiToAmount() for conversions

SDK References

For detailed SDK documentation:

• Node.js SDK: See references/hoosat-sdk.md
• Browser SDK: See references/hoosat-sdk-web.md
• Motoko Package: See references/hoosat-mo.md
• REST API: See references/api-reference.md

Integration Guides

Wallet Integration

See references/wallet-integration.md for:

• Wallet connection patterns
• Transaction signing flows
• Address management
• Network switching

Node Operations

See references/node-operations.md for:

• Docker deployment
• Binary installation
• Building from source
• RPC node setup

dApp Development

When building a Hoosat dApp:

1. Setup: Use hoosat-sdk-web for browser compatibility
2. Wallet Connection: Implement wallet adapter using HoosatCrypto
3. State Management: Track balances, transactions, and UTXOs
4. Transaction Building: Use HoosatTxBuilder with UTXO selection
5. Error Handling: Handle BaseResult<T> pattern

Use the dapp-template/ asset for a starter React/Next.js dApp.

Block Explorer

To build a block explorer:

1. Data Source: Use Hoosat REST API or run your own node
2. Indexing: Index blocks, transactions, and addresses
3. API Layer: Build REST/GraphQL API using HoosatWebClient
4. Frontend: Display blocks, transactions, addresses

Use the explorer-template/ asset for a starter block explorer.

HRC20 Tokens

HRC20 is Hoosat's token standard (KRC20 equivalent). For token development:

See references/hrc20-tokens.md for:

• Token contract structure
• Transfer and approval mechanisms
• Integration patterns

Agent Wallet System

PRIMARY: Use agent-wallet.py for ALL wallet operations (create, manage, transact).

Agent Wallet System

Features

• Encrypted Wallet Storage: AES-256 encryption with PBKDF2 key derivation
• Balance Queries: Real-time balance checking via REST API
• Transaction Execution: Transfer HTN with auto-approve or confirmation
• Address Book: Save and label frequently used addresses
• UTXO Consolidation: Optimize wallet by combining small UTXOs

The agent wallet system enables AI agents to actively manage Hoosat wallets and execute transactions.

Features

• Encrypted Wallet Storage: AES-256 encryption with PBKDF2 key derivation
• Balance Queries: Real-time balance checking via REST API
• Transaction Execution: Transfer HTN with auto-approve or confirmation
• Address Book: Save and label frequently used addresses
• UTXO Consolidation: Optimize wallet by combining small UTXOs

Agent Execution Workflows

IMPORTANT: When user gives natural language commands, EXECUTE these workflows using the agent-wallet.py script.

Initialize Wallet System

User says: "Initialize hoosat wallet", "Set up wallet system", "Initialize agent wallets"

Agent actions:

1. Check if already initialized: test -f ~/.hoosat-wallets/wallets.enc
2. If not initialized:
   • Ask user for master password or generate one
   • Execute: python3 {skill_path}/scripts/agent-wallet.py
   • Call manager.initialize(password)
   • Confirm: "Wallet system initialized at ~/.hoosat-wallets/"

Create Wallet

User says: "Create wallet [name] on [network]", "Make a [name] wallet", "Generate wallet for [purpose]", "Give me a wallet"

Agent actions:

1. Check if wallet system is initialized: python3 scripts/agent-wallet.py list
2. If not initialized: python3 scripts/agent-wallet.py init
3. Create wallet: python3 scripts/agent-wallet.py create [name] --network [network]
4. Show result to user

Check Balance

User says: "Check balance of [wallet]", "How much HTN in [wallet]?", "What's the balance?"

Agent actions:

1. Execute: python3 {skill_path}/scripts/agent-transact.py
2. Call: executor.get_balance(wallet_name)
3. Convert sompi to HTN and display
4. If error, explain (wallet not found, network issue, etc.)

Transfer Funds

User says: "Transfer [amount] HTN from [wallet] to [address]", "Send [amount] to [address]"

Agent actions:

1. Resolve recipient (check address book if label used)
2. Check if auto-approve is enabled for this wallet/amount
3. If confirmation needed, ask: "Send [amount] HTN to [recipient]?"
4. Execute: python3 {skill_path}/scripts/agent-transact.py
5. Call: executor.transfer(from_wallet, to_address, amount)
6. Display transaction result (success/failure, tx ID)

List Wallets

User says: "List my wallets", "Show wallets", "What wallets do I have?"

Agent actions:

1. Execute: python3 {skill_path}/scripts/agent-wallet.py
2. Call: manager.list_wallets()
3. Display names, addresses, networks

Add Address to Book

User says: "Save address [label] as [address]", "Add [label] to address book"

Agent actions:

1. Execute: python3 {skill_path}/scripts/agent-wallet.py
2. Call: manager.add_address(label, address)
3. Confirm: "Address saved"

Consolidate UTXOs

User says: "Consolidate UTXOs in [wallet]", "Compound UTXOs", "Optimize [wallet]"

Agent actions:

1. Check current UTXO count
2. If > 10 UTXOs, suggest consolidation
3. Ask for confirmation
4. Execute: python3 {skill_path}/scripts/agent-transact.py
5. Call: executor.consolidate_utxos(wallet_name)

Quick Reference Commands

Initialize: "Initialize hoosat wallet system"
Create:     "Create wallet [name] on [network]"
Balance:    "Check balance of [wallet]"  
Transfer:   "Transfer [amount] HTN from [wallet] to [address]"
List:       "List my wallets"
Address:    "Save address [label] as [address]"
Consolidate:"Consolidate UTXOs in [wallet]"

Security

• Master password required to unlock (stored in HOOSAT_AGENT_PASSWORD env var)
• Session timeout: 1 hour
• Auto-approve: Configurable per-wallet limits
• Dry-run mode: Test transactions without broadcasting

Configuration

Located at: ~/.hoosat-wallets/config.json

{
  "autoApprove": {
    "enabled": false,
    "wallets": {
      "mining": {
        "enabled": true,
        "maxAmount": "1000000000"
      }
    }
  },
  "features": {
    "dryRun": true
  }
}

Scripts

• agent-wallet.py: Main wallet management
• agent-crypto.py: Encryption/decryption utilities
• agent-transact.py: Transaction execution

See references/agent-wallet-guide.md for complete documentation.

Setup and Dependencies

Recommended Installation (Pure Python - No Compilation):

pip3 install ecdsa bech32 blake3 base58

Alternative with secp256k1 (requires compilation):

# Install pkg-config first (macOS)
brew install pkg-config

# Then install Python packages
pip3 install secp256k1 bech32 blake3 base58

For Agent Wallet System (additional dependencies):

pip3 install cryptography requests

macOS Installation (if standard pip fails):

# Option 1: Use --user flag
pip3 install --user ecdsa bech32 blake3 base58 cryptography requests

# Option 2: Use --break-system-packages (not recommended but works)
pip3 install --break-system-packages ecdsa bech32 blake3 base58 cryptography requests

# Option 3: Use Homebrew Python
brew install python
/opt/homebrew/bin/pip3 install ecdsa bech32 blake3 base58 cryptography requests

State Management

The agent maintains wallet state across conversations:

1. Persistent Storage: ~/.hoosat-wallets/ directory

   • wallets.enc - Encrypted wallet data
   • address-book.json - Saved addresses
   • config.json - Agent configuration
   • transactions.log - Transaction history

2. Session State:

   • HOOSAT_AGENT_PASSWORD env var for current session
   • 1-hour timeout (auto-lock)
   • Re-authentication required after timeout

3. Context Awareness:

   • Agent remembers current wallet directory
   • Tracks which wallets are unlocked
   • Maintains address book mappings

Error Handling

Common errors and responses:

"Wallet system locked"

• Ask for password: "Please provide wallet password to unlock"
• Set: export HOOSAT_AGENT_PASSWORD=your_password

"No such file or directory" (dependencies)

• Install: pip3 install cryptography requests

"Insufficient balance"

• Check balance first
• Verify network (mainnet vs testnet)

"Invalid address"

• Check format: must start with hoosat: or hoosattest:
• Verify no typos

"Wallet already exists"

• Use different name
• Or delete existing: "Delete wallet [name] first"

Best Practices for Agents

1. Always confirm high-value transactions (> 1 HTN)
2. Check dry-run mode before real transactions
3. Suggest testnet for new users
4. Remind about backups after wallet creation
5. Lock session when user indicates they're done

Resources

References

• api-reference.md: Hoosat REST API documentation (proxy.hoosat.net)
• hoosat-sdk.md: Node.js SDK documentation
• hoosat-sdk-web.md: Browser SDK documentation
• hoosat-mo.md: Motoko (Internet Computer) documentation
• wallet-integration.md: Wallet integration patterns
• node-operations.md: Node operations guide
• hrc20-tokens.md: HRC20 token standard
• agent-wallet-guide.md: Agent wallet system documentation

Assets

• dapp-template/: React/Next.js dApp starter using hoosat-sdk-web
• explorer-template/: Block explorer starter

Best Practices

1. Always validate addresses before using them (check hoosat: or hoosattest: prefix)
2. Handle UTXO selection carefully to avoid dust outputs (min 1000 sompi)
3. Implement proper error handling using BaseResult<T> pattern
4. Test on testnet before mainnet deployment
5. Use fee estimation via client.calculateMinFee() for proper fees
6. Secure private keys - never expose them in client-side code
7. Use BLAKE3 hashing for any custom cryptographic operations
8. Convert amounts properly using HoosatUtils (1 HTN = 100M sompi)

Getting Help

• Developer Hub: https://hub.hoosat.net/
• REST API Docs: https://proxy.hoosat.net/docs
• GitHub (Network): https://github.com/hoosatnetwork
• GitHub (Developer): https://github.com/Namp88
• GitHub (Organization): https://github.com/Hoosat-Oy
• Discord: https://discord.gg/mFBfNpNA
• Twitter: https://x.com/HoosatNetwork
• Telegram: https://t.me/HoosatNetwork
• Official Website: https://network.hoosat.fi
• Motoko Package: https://mops.one/hoosat-mo