@sequence0/sdk 1.1.0 → 1.2.0

package/dist/chains/kaspa.js

@@ -0,0 +1,790 @@
+"use strict";
+/**
+ * Kaspa Chain Adapter
+ *
+ * Builds Kaspa UTXO transactions, computes per-input sighashes for
+ * BIP-340 Schnorr signing via the FROST threshold signing network,
+ * and broadcasts via the Kaspa REST API.
+ *
+ * Kaspa uses secp256k1 with BIP-340 Schnorr signatures (64 bytes),
+ * the same signature scheme as Bitcoin Taproot. FROST-secp256k1
+ * produces native BIP-340 compatible Schnorr signatures.
+ *
+ * Key features:
+ * - UTXO-based transaction model (similar to Bitcoin)
+ * - BIP-340 Schnorr signatures (64 bytes, same as Taproot)
+ * - ~1 second block time (BlockDAG architecture)
+ * - Per-input sighash computation for multi-input transactions
+ *
+ * No external dependencies — uses raw HTTP API calls and Node.js crypto.
+ *
+ * @example
+ * ```typescript
+ * import { KaspaAdapter } from '@sequence0/sdk';
+ *
+ * const kaspa = new KaspaAdapter('mainnet');
+ *
+ * // Build a transfer transaction
+ * const unsignedTx = await kaspa.buildTransaction(
+ *   { to: 'kaspa:qr...recipient', amount: 100000000 }, // 1 KAS
+ *   'kaspa:qr...sender'
+ * );
+ *
+ * // ... sign each sighash via FROST Schnorr ...
+ * const signedTx = await kaspa.attachSignature(unsignedTx, signatureHex);
+ * const txId = await kaspa.broadcast(signedTx);
+ * ```
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KaspaAdapter = void 0;
+exports.createKaspaAdapter = createKaspaAdapter;
+exports.createKaspaTestnetAdapter = createKaspaTestnetAdapter;
+const errors_1 = require("../utils/errors");
+const crypto = __importStar(require("crypto"));
+// ── Network Configuration ──
+const DEFAULT_API_URLS = {
+    'mainnet': 'https://api.kaspa.org',
+    'testnet': 'https://api-tn.kaspa.org',
+};
+/** Default fee rate in sompi per gram (mass unit) */
+const DEFAULT_FEE_RATE = 1;
+/** Minimum relay fee in sompi per gram */
+const MIN_FEE_RATE = 1;
+/** Dust threshold in sompi — outputs below this are rejected */
+const DUST_THRESHOLD = 546;
+/** Estimated mass per input (bytes) */
+const MASS_PER_INPUT = 239;
+/** Estimated mass per output (bytes) */
+const MASS_PER_OUTPUT = 34;
+/** Fixed transaction overhead mass */
+const TX_OVERHEAD_MASS = 83;
+/** Sompi per KAS (1 KAS = 1e8 sompi) */
+const SOMPI_PER_KAS = 100000000;
+// ── Address Encoding/Decoding ──
+const CHARSET = 'qpzry9x8gf2tvdw0s3jn54khce6mua7l';
+/**
+ * Polymod for Kaspa's bech32-like address encoding
+ */
+function polymod(values) {
+    const GEN = [
+        0x98f2bc8e61n,
+        0x79b76d99e2n,
+        0xf33e5fb3c4n,
+        0xae2eabe2a8n,
+        0x1e4f43e470n,
+    ];
+    let chk = 1n;
+    for (const v of values) {
+        const b = chk >> 35n;
+        chk = ((chk & 0x07ffffffffn) << 5n) ^ BigInt(v);
+        for (let i = 0; i < 5; i++) {
+            if ((b >> BigInt(i)) & 1n) {
+                chk ^= GEN[i];
+            }
+        }
+    }
+    return chk ^ 1n;
+}
+/**
+ * Expand prefix for checksum computation
+ */
+function prefixExpand(prefix) {
+    const ret = [];
+    for (const c of prefix) {
+        ret.push(c.charCodeAt(0) & 0x1f);
+    }
+    ret.push(0);
+    return ret;
+}
+/**
+ * Convert between bit widths
+ */
+function convertBits(data, fromBits, toBits, pad) {
+    let acc = 0;
+    let bits = 0;
+    const ret = [];
+    const maxv = (1 << toBits) - 1;
+    for (const value of data) {
+        if (value < 0 || value >> fromBits !== 0) {
+            throw new Error('Invalid value for bit conversion');
+        }
+        acc = (acc << fromBits) | value;
+        bits += fromBits;
+        while (bits >= toBits) {
+            bits -= toBits;
+            ret.push((acc >> bits) & maxv);
+        }
+    }
+    if (pad) {
+        if (bits > 0) {
+            ret.push((acc << (toBits - bits)) & maxv);
+        }
+    }
+    else if (bits >= fromBits || ((acc << (toBits - bits)) & maxv)) {
+        throw new Error('Invalid padding');
+    }
+    return ret;
+}
+/**
+ * Decode a kaspa:... address into its components.
+ *
+ * Kaspa addresses use a bech32-like encoding with format:
+ * kaspa:<type><payload><checksum>
+ *
+ * Type 0x00 = P2PK (pay-to-public-key, Schnorr)
+ * Type 0x01 = P2SH (pay-to-script-hash)
+ */
+function decodeKaspaAddress(address) {
+    const parts = address.split(':');
+    if (parts.length !== 2) {
+        throw new Error(`Invalid Kaspa address format: ${address}`);
+    }
+    const prefix = parts[0];
+    if (prefix !== 'kaspa' && prefix !== 'kaspatest') {
+        throw new Error(`Invalid Kaspa address prefix: ${prefix}`);
+    }
+    const dataStr = parts[1];
+    const data5bit = [];
+    for (const c of dataStr) {
+        const idx = CHARSET.indexOf(c);
+        if (idx < 0)
+            throw new Error(`Invalid character in Kaspa address: ${c}`);
+        data5bit.push(idx);
+    }
+    // Verify checksum (last 8 characters = 40 bits)
+    const checksumData = prefixExpand(prefix).concat(data5bit);
+    const mod = polymod(checksumData);
+    if (mod !== 0n) {
+        throw new Error('Invalid Kaspa address checksum');
+    }
+    // Remove checksum (8 characters)
+    const payload5bit = data5bit.slice(0, data5bit.length - 8);
+    // Convert from 5-bit to 8-bit
+    const payload8bit = convertBits(payload5bit, 5, 8, false);
+    // First byte is the address type
+    const type = payload8bit[0];
+    const payloadBytes = Buffer.from(payload8bit.slice(1));
+    return { prefix, type, payload: payloadBytes };
+}
+/**
+ * Encode a public key as a kaspa:... address
+ *
+ * @param prefix - Network prefix ('kaspa' or 'kaspatest')
+ * @param type - Address type (0x00 for P2PK Schnorr)
+ * @param payload - 32-byte public key or script hash
+ */
+function encodeKaspaAddress(prefix, type, payload) {
+    // Prepend type byte to payload
+    const fullPayload = Buffer.concat([Buffer.from([type]), payload]);
+    // Convert to 5-bit groups
+    const data5bit = convertBits(Array.from(fullPayload), 8, 5, true);
+    // Compute checksum
+    const checksumInput = prefixExpand(prefix).concat(data5bit).concat([0, 0, 0, 0, 0, 0, 0, 0]);
+    const mod = polymod(checksumInput);
+    const checksum = [];
+    for (let i = 0; i < 8; i++) {
+        checksum.push(Number((mod >> BigInt(5 * (7 - i))) & 0x1fn));
+    }
+    let result = prefix + ':';
+    for (const d of data5bit.concat(checksum)) {
+        result += CHARSET[d];
+    }
+    return result;
+}
+/**
+ * Build a P2PK ScriptPublicKey for a Schnorr public key.
+ *
+ * Kaspa P2PK Schnorr script: OP_DATA_32 <32-byte-pubkey> OP_CHECKSIG
+ * Hex: 20 <pubkey_hex> ac
+ */
+function buildP2pkScript(pubkeyHex) {
+    return '20' + pubkeyHex + 'ac';
+}
+// ── Sighash Computation ──
+/**
+ * Compute a tagged hash: SHA-256(SHA-256(tag) || SHA-256(tag) || data)
+ *
+ * Kaspa uses tagged hashes similar to BIP-340/BIP-341 for domain separation.
+ */
+function taggedHash(tag, ...data) {
+    const tagHash = crypto.createHash('sha256').update(tag).digest();
+    const hasher = crypto.createHash('sha256');
+    hasher.update(tagHash);
+    hasher.update(tagHash);
+    for (const d of data) {
+        hasher.update(d);
+    }
+    return hasher.digest();
+}
+/**
+ * Write a 64-bit unsigned integer in little-endian format
+ */
+function writeUint64LE(value) {
+    const buf = Buffer.alloc(8);
+    buf.writeBigUInt64LE(BigInt(value));
+    return buf;
+}
+/**
+ * Write a 32-bit unsigned integer in little-endian format
+ */
+function writeUint32LE(value) {
+    const buf = Buffer.alloc(4);
+    buf.writeUInt32LE(value);
+    return buf;
+}
+/**
+ * Write a 16-bit unsigned integer in little-endian format
+ */
+function writeUint16LE(value) {
+    const buf = Buffer.alloc(2);
+    buf.writeUInt16LE(value);
+    return buf;
+}
+/**
+ * Compute the sighash for a Kaspa transaction input.
+ *
+ * Kaspa uses a sighash scheme inspired by BIP-341 (Taproot) with
+ * domain-separated tagged hashes. Each input has its own sighash
+ * that must be independently signed with Schnorr.
+ *
+ * The sighash commits to:
+ * - Transaction version and subnetwork
+ * - Hash of all previous outputs (outpoints)
+ * - Hash of all sequence numbers
+ * - Hash of all outputs
+ * - The specific input being signed (outpoint, script, value, sequence)
+ * - Sighash type
+ */
+function computeKaspaSighash(inputs, outputs, inputIndex) {
+    // Hash all previous outpoints
+    // Kaspa uses blake2b internally, but we use SHA-256 for sighash computation
+    // since the FROST signing protocol operates on the final sighash digest
+    const hashPrevOuts = (() => {
+        const hasher = crypto.createHash('sha256');
+        for (const inp of inputs) {
+            // Transaction ID (32 bytes, already big-endian in Kaspa)
+            hasher.update(Buffer.from(inp.transactionId, 'hex'));
+            // Output index (4 bytes LE)
+            hasher.update(writeUint32LE(inp.index));
+        }
+        return hasher.digest();
+    })();
+    // Hash all sequence numbers
+    const hashSequences = (() => {
+        const hasher = crypto.createHash('sha256');
+        for (let i = 0; i < inputs.length; i++) {
+            // All inputs use max sequence (0xFFFFFFFFFFFFFFFF for Kaspa's u64 sequence)
+            hasher.update(Buffer.from('ffffffffffffffff', 'hex'));
+        }
+        return hasher.digest();
+    })();
+    // Hash sig op counts
+    const hashSigOpCounts = (() => {
+        const hasher = crypto.createHash('sha256');
+        for (let i = 0; i < inputs.length; i++) {
+            // 1 sig op per P2PK input
+            hasher.update(Buffer.from([1]));
+        }
+        return hasher.digest();
+    })();
+    // Hash all outputs
+    const hashOutputs = (() => {
+        const hasher = crypto.createHash('sha256');
+        for (const out of outputs) {
+            // Value (8 bytes LE)
+            hasher.update(writeUint64LE(out.value));
+            // Script version (2 bytes LE)
+            hasher.update(writeUint16LE(0));
+            // Script length (8 bytes LE for Kaspa's u64 length prefix)
+            const scriptBuf = Buffer.from(out.scriptPublicKey, 'hex');
+            hasher.update(writeUint64LE(scriptBuf.length));
+            // Script
+            hasher.update(scriptBuf);
+        }
+        return hasher.digest();
+    })();
+    // Build the sighash preimage
+    const preimage = Buffer.concat([
+        // Version (2 bytes LE)
+        writeUint16LE(0),
+        // Hash previous outputs
+        hashPrevOuts,
+        // Hash sequences
+        hashSequences,
+        // Hash sig op counts
+        hashSigOpCounts,
+        // Current input's outpoint
+        Buffer.from(inputs[inputIndex].transactionId, 'hex'),
+        writeUint32LE(inputs[inputIndex].index),
+        // Current input's script version (2 bytes LE)
+        writeUint16LE(0),
+        // Current input's script length (8 bytes LE)
+        (() => {
+            const scriptBuf = Buffer.from(inputs[inputIndex].scriptPublicKey, 'hex');
+            return Buffer.concat([writeUint64LE(scriptBuf.length), scriptBuf]);
+        })(),
+        // Current input's value (8 bytes LE)
+        writeUint64LE(inputs[inputIndex].amount),
+        // Current input's sequence (8 bytes LE)
+        Buffer.from('ffffffffffffffff', 'hex'),
+        // Current input's sig op count
+        Buffer.from([1]),
+        // Hash outputs
+        hashOutputs,
+        // Lock time (8 bytes LE)
+        writeUint64LE(0),
+        // Subnetwork ID (20 bytes, all zeros for native)
+        Buffer.alloc(20, 0),
+        // Gas (8 bytes LE)
+        writeUint64LE(0),
+        // Payload hash (32 bytes, all zeros for no payload)
+        Buffer.alloc(32, 0),
+        // Sighash type (4 bytes LE) — SigHashAll = 0x01
+        writeUint32LE(1),
+    ]);
+    // Double SHA-256 of the preimage (Kaspa sighash)
+    const first = crypto.createHash('sha256').update(preimage).digest();
+    const sighash = crypto.createHash('sha256').update(first).digest();
+    return sighash.toString('hex');
+}
+// ── Adapter ──
+class KaspaAdapter {
+    /**
+     * Create a Kaspa adapter.
+     *
+     * @param network - Network to connect to: 'mainnet' or 'testnet'
+     * @param apiUrl - Custom API URL (overrides the default for the network)
+     */
+    constructor(network = 'mainnet', apiUrl) {
+        this.network = network;
+        this.apiUrl = apiUrl || DEFAULT_API_URLS[network];
+    }
+    getRpcUrl() {
+        return this.apiUrl;
+    }
+    // ────────────────────────────────────────────────
+    //  Build Transaction
+    // ────────────────────────────────────────────────
+    /**
+     * Build an unsigned Kaspa transaction.
+     *
+     * Fetches UTXOs for the sender, selects inputs to cover the amount
+     * plus fees, builds outputs (payment + change), and computes
+     * per-input sighashes for Schnorr signing.
+     *
+     * Returns hex-encoded JSON containing the TX data and sighashes.
+     * Each sighash must be independently signed via FROST Schnorr.
+     *
+     * @param tx - Transaction parameters (to, amount, feeRate)
+     * @param fromAddress - Sender kaspa:... address
+     * @returns Hex-encoded payload with sighashes and TX structure
+     */
+    async buildTransaction(tx, fromAddress) {
+        try {
+            // Validate addresses
+            this.validateAddress(fromAddress);
+            this.validateAddress(tx.to);
+            // Fetch UTXOs for the sender
+            const utxos = await this.fetchUtxos(fromAddress);
+            if (utxos.length === 0) {
+                throw new Error(`No UTXOs found for ${fromAddress}`);
+            }
+            const feeRate = tx.feeRate || DEFAULT_FEE_RATE;
+            // Sort UTXOs by value (largest first) for efficient selection
+            const sorted = [...utxos].sort((a, b) => b.amount - a.amount);
+            // Select inputs
+            const selectedInputs = [];
+            let inputTotal = 0;
+            for (const utxo of sorted) {
+                selectedInputs.push(utxo);
+                inputTotal += utxo.amount;
+                // Estimate transaction mass (fee = mass * feeRate)
+                const estimatedMass = TX_OVERHEAD_MASS +
+                    selectedInputs.length * MASS_PER_INPUT +
+                    2 * MASS_PER_OUTPUT; // payment + change
+                const estimatedFee = estimatedMass * feeRate;
+                if (inputTotal >= tx.amount + estimatedFee)
+                    break;
+            }
+            // Calculate actual fee
+            const numOutputs = 2; // payment + change (may drop to 1 if change < dust)
+            const txMass = TX_OVERHEAD_MASS +
+                selectedInputs.length * MASS_PER_INPUT +
+                numOutputs * MASS_PER_OUTPUT;
+            const fee = Math.max(txMass * feeRate, MIN_FEE_RATE);
+            if (inputTotal < tx.amount + fee) {
+                throw new Error(`Insufficient funds: have ${inputTotal} sompi, need ${tx.amount + fee} sompi ` +
+                    `(${tx.amount} amount + ${fee} fee)`);
+            }
+            const change = inputTotal - tx.amount - fee;
+            // Decode the recipient address to get the scriptPublicKey
+            const recipientAddr = decodeKaspaAddress(tx.to);
+            const recipientScript = buildP2pkScript(recipientAddr.payload.toString('hex'));
+            // Build outputs
+            const outputs = [
+                {
+                    address: tx.to,
+                    value: tx.amount,
+                    scriptPublicKey: recipientScript,
+                },
+            ];
+            // Add change output if above dust threshold
+            if (change > DUST_THRESHOLD) {
+                const senderAddr = decodeKaspaAddress(fromAddress);
+                const senderScript = buildP2pkScript(senderAddr.payload.toString('hex'));
+                outputs.push({
+                    address: fromAddress,
+                    value: change,
+                    scriptPublicKey: senderScript,
+                });
+            }
+            // Build input descriptors for sighash computation
+            const inputDescs = selectedInputs.map((utxo) => ({
+                transactionId: utxo.transactionId,
+                index: utxo.index,
+                amount: utxo.amount,
+                scriptPublicKey: utxo.scriptPublicKey.scriptPublicKey,
+            }));
+            const outputDescs = outputs.map((out) => ({
+                value: out.value,
+                scriptPublicKey: out.scriptPublicKey,
+            }));
+            // Compute per-input sighashes
+            const sighashes = [];
+            for (let i = 0; i < inputDescs.length; i++) {
+                const sighash = computeKaspaSighash(inputDescs, outputDescs, i);
+                sighashes.push(sighash);
+            }
+            const payload = {
+                sighash: sighashes[0], // Primary sighash (for single-input convenience)
+                sighashes,
+                inputs: inputDescs,
+                outputs: outputs.map((out) => ({
+                    address: out.address,
+                    value: out.value,
+                    scriptPublicKey: out.scriptPublicKey,
+                })),
+                fee,
+                mass: txMass,
+                network: this.network,
+            };
+            return Buffer.from(JSON.stringify(payload)).toString('hex');
+        }
+        catch (e) {
+            if (e instanceof errors_1.ChainError)
+                throw e;
+            throw new errors_1.ChainError(`Failed to build Kaspa transaction: ${e.message}`, 'kaspa');
+        }
+    }
+    /**
+     * Extract the signing payload from the buildTransaction output.
+     *
+     * Returns the primary sighash (first input). For multi-input
+     * transactions, callers should decode the full payload to get
+     * all sighashes from the `sighashes` array.
+     */
+    getSigningPayload(unsignedTx) {
+        try {
+            const payload = JSON.parse(Buffer.from(unsignedTx, 'hex').toString());
+            return payload.sighash;
+        }
+        catch {
+            return unsignedTx;
+        }
+    }
+    // ────────────────────────────────────────────────
+    //  Attach Signature
+    // ────────────────────────────────────────────────
+    /**
+     * Attach BIP-340 Schnorr signature(s) to the Kaspa transaction.
+     *
+     * Each input requires its own 64-byte Schnorr signature. For
+     * multi-input transactions, pass comma-separated signatures or
+     * concatenated 64-byte signatures.
+     *
+     * @param unsignedTx - Hex-encoded unsigned transaction from buildTransaction
+     * @param signature - 64-byte Schnorr signature(s) (hex-encoded)
+     * @returns Hex-encoded signed transaction payload
+     */
+    async attachSignature(unsignedTx, signature) {
+        try {
+            const payload = JSON.parse(Buffer.from(unsignedTx, 'hex').toString());
+            const sig = signature.startsWith('0x') ? signature.slice(2) : signature;
+            // Parse signatures — support comma-separated or concatenated
+            let signatures;
+            if (sig.includes(',')) {
+                signatures = sig.split(',').map((s) => s.trim());
+            }
+            else if (sig.length > 128 && payload.inputs.length > 1) {
+                // Concatenated 64-byte (128 hex char) signatures
+                signatures = [];
+                for (let i = 0; i < payload.inputs.length; i++) {
+                    signatures.push(sig.slice(i * 128, (i + 1) * 128));
+                }
+            }
+            else {
+                // Single signature — reuse for all inputs (common for same-key UTXOs)
+                signatures = [sig];
+            }
+            // Validate signature lengths
+            for (let i = 0; i < signatures.length; i++) {
+                if (signatures[i].length !== 128) {
+                    throw new Error(`Invalid Schnorr signature length for input ${i}: ` +
+                        `expected 128 hex chars (64 bytes), got ${signatures[i].length}`);
+                }
+            }
+            const signedPayload = {
+                ...payload,
+                signatures,
+            };
+            return Buffer.from(JSON.stringify(signedPayload)).toString('hex');
+        }
+        catch (e) {
+            if (e instanceof errors_1.ChainError)
+                throw e;
+            throw new errors_1.ChainError(`Failed to attach Kaspa signature: ${e.message}`, 'kaspa');
+        }
+    }
+    // ────────────────────────────────────────────────
+    //  Broadcast
+    // ────────────────────────────────────────────────
+    /**
+     * Broadcast a signed Kaspa transaction.
+     *
+     * Constructs the RPC-compatible transaction object with inputs,
+     * outputs, and witness signatures, then sends it to the Kaspa
+     * REST API for propagation to the network.
+     *
+     * @param signedTx - Hex-encoded signed transaction from attachSignature
+     * @returns Transaction ID
+     */
+    async broadcast(signedTx) {
+        try {
+            const payload = JSON.parse(Buffer.from(signedTx, 'hex').toString());
+            if (!payload.signatures || payload.signatures.length === 0) {
+                throw new Error('Transaction is not signed (missing signatures)');
+            }
+            // Build the transaction object in Kaspa RPC format
+            const rpcInputs = payload.inputs.map((inp, i) => {
+                const sigIdx = Math.min(i, payload.signatures.length - 1);
+                return {
+                    previousOutpoint: {
+                        transactionId: inp.transactionId,
+                        index: inp.index,
+                    },
+                    signatureScript: payload.signatures[sigIdx], // 64-byte Schnorr sig hex
+                    sequence: '18446744073709551615', // u64 max as string
+                    sigOpCount: 1,
+                };
+            });
+            const rpcOutputs = payload.outputs.map((out) => ({
+                amount: out.value,
+                scriptPublicKey: {
+                    scriptPublicKey: out.scriptPublicKey,
+                    version: 0,
+                },
+            }));
+            const rpcTransaction = {
+                transaction: {
+                    version: 0,
+                    inputs: rpcInputs,
+                    outputs: rpcOutputs,
+                    lockTime: '0',
+                    subnetworkId: '0000000000000000000000000000000000000000',
+                },
+            };
+            const response = await fetch(`${this.apiUrl}/transactions`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify(rpcTransaction),
+            });
+            if (!response.ok) {
+                const errorText = await response.text();
+                throw new Error(`Broadcast failed (HTTP ${response.status}): ${errorText}`);
+            }
+            const result = await response.json();
+            // The API returns the transaction ID
+            return result.transactionId || result.txId || '';
+        }
+        catch (e) {
+            if (e instanceof errors_1.ChainError)
+                throw e;
+            throw new errors_1.ChainError(`Failed to broadcast Kaspa tx: ${e.message}`, 'kaspa');
+        }
+    }
+    // ────────────────────────────────────────────────
+    //  Balance
+    // ────────────────────────────────────────────────
+    /**
+     * Get the KAS balance for an address.
+     *
+     * Returns balance in sompi (1 KAS = 1e8 sompi).
+     *
+     * @param address - Kaspa kaspa:... address
+     * @returns Balance in sompi as a string
+     */
+    async getBalance(address) {
+        try {
+            this.validateAddress(address);
+            const response = await fetch(`${this.apiUrl}/addresses/${address}/balance`);
+            if (!response.ok) {
+                if (response.status === 404)
+                    return '0';
+                throw new Error(`HTTP ${response.status}: ${await response.text()}`);
+            }
+            const data = await response.json();
+            return (data.balance ?? data.address?.balance ?? 0).toString();
+        }
+        catch (e) {
+            if (e instanceof errors_1.ChainError)
+                throw e;
+            // Return '0' for network errors (address may have no history)
+            return '0';
+        }
+    }
+    // ────────────────────────────────────────────────
+    //  Utility Methods
+    // ────────────────────────────────────────────────
+    /**
+     * Fetch UTXOs for a Kaspa address from the REST API.
+     *
+     * @param address - kaspa:... address
+     * @returns Array of UTXOs
+     */
+    async fetchUtxos(address) {
+        try {
+            const response = await fetch(`${this.apiUrl}/addresses/${address}/utxos`);
+            if (!response.ok) {
+                if (response.status === 404)
+                    return [];
+                throw new Error(`HTTP ${response.status}: ${await response.text()}`);
+            }
+            const data = await response.json();
+            return data.map((item) => ({
+                transactionId: item.outpoint?.transactionId || item.transactionId,
+                index: item.outpoint?.index ?? item.index ?? 0,
+                amount: parseInt(item.utxoEntry?.amount ?? item.amount ?? '0', 10),
+                scriptPublicKey: item.utxoEntry?.scriptPublicKey || item.scriptPublicKey || {
+                    scriptPublicKey: '',
+                    version: 0,
+                },
+                isCoinbase: item.utxoEntry?.isCoinbase ?? item.isCoinbase ?? false,
+                blockDaaScore: item.utxoEntry?.blockDaaScore ?? item.blockDaaScore ?? '0',
+            }));
+        }
+        catch (e) {
+            if (e instanceof errors_1.ChainError)
+                throw e;
+            throw new errors_1.ChainError(`Failed to fetch Kaspa UTXOs: ${e.message}`, 'kaspa');
+        }
+    }
+    /**
+     * Validate a Kaspa address format.
+     *
+     * @param address - Address to validate
+     * @throws Error if the address is invalid
+     */
+    validateAddress(address) {
+        const expectedPrefix = this.network === 'mainnet' ? 'kaspa' : 'kaspatest';
+        if (!address.startsWith(expectedPrefix + ':')) {
+            throw new Error(`Invalid Kaspa address for ${this.network}: expected prefix '${expectedPrefix}:', got '${address}'`);
+        }
+        // Will throw if the address is malformed
+        decodeKaspaAddress(address);
+    }
+    /**
+     * Derive a kaspa:... address from a 32-byte x-only public key.
+     *
+     * FROST-secp256k1 produces a group verifying key (compressed point).
+     * Extract the x-only (32-byte) key and encode as a Kaspa P2PK Schnorr address.
+     *
+     * @param pubkeyHex - 32-byte x-only public key (hex-encoded), or 33-byte compressed
+     * @returns kaspa:... address
+     */
+    deriveAddress(pubkeyHex) {
+        const clean = pubkeyHex.startsWith('0x') ? pubkeyHex.slice(2) : pubkeyHex;
+        let xOnlyHex;
+        if (clean.length === 66) {
+            // 33-byte compressed public key — strip the prefix byte
+            xOnlyHex = clean.slice(2);
+        }
+        else if (clean.length === 64) {
+            // Already 32-byte x-only
+            xOnlyHex = clean;
+        }
+        else {
+            throw new errors_1.ChainError(`Invalid public key length: expected 32 or 33 bytes, got ${clean.length / 2}`, 'kaspa');
+        }
+        const prefix = this.network === 'mainnet' ? 'kaspa' : 'kaspatest';
+        const payload = Buffer.from(xOnlyHex, 'hex');
+        return encodeKaspaAddress(prefix, 0x00, payload);
+    }
+    /**
+     * Estimate the fee for a transaction.
+     *
+     * @param numInputs - Number of inputs
+     * @param numOutputs - Number of outputs
+     * @param feeRate - Fee rate in sompi per gram (default: 1)
+     * @returns Estimated fee in sompi
+     */
+    estimateFee(numInputs, numOutputs, feeRate = DEFAULT_FEE_RATE) {
+        const mass = TX_OVERHEAD_MASS + numInputs * MASS_PER_INPUT + numOutputs * MASS_PER_OUTPUT;
+        return Math.max(mass * feeRate, MIN_FEE_RATE);
+    }
+}
+exports.KaspaAdapter = KaspaAdapter;
+// ── Factory Functions ──
+/**
+ * Create a Kaspa mainnet adapter
+ *
+ * @param apiUrl - Optional custom API URL
+ * @returns KaspaAdapter configured for mainnet
+ */
+function createKaspaAdapter(apiUrl) {
+    return new KaspaAdapter('mainnet', apiUrl);
+}
+/**
+ * Create a Kaspa testnet adapter
+ *
+ * @param apiUrl - Optional custom API URL
+ * @returns KaspaAdapter configured for testnet
+ */
+function createKaspaTestnetAdapter(apiUrl) {
+    return new KaspaAdapter('testnet', apiUrl);
+}
+//# sourceMappingURL=kaspa.js.map