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

Environment	Package	Install
Node.js	hoosat-sdk	npm install hoosat-sdk
Browser	hoosat-sdk-web	npm install hoosat-sdk-web
Motoko (IC)	hoosat-mo	mops install hoosat-mo

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 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 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