@sequence0/sdk 2.0.1 → 2.1.1

package/dist/chains/nervos.js

@@ -0,0 +1,913 @@
+"use strict";
+/**
+ * Nervos CKB (Common Knowledge Base) Chain Adapter
+ *
+ * Builds CKB transactions using the Cell model, computes signing payloads
+ * with Blake2b-256 hashing, attaches secp256k1 ECDSA signatures from the
+ * FROST threshold signing network, and broadcasts via CKB JSON-RPC.
+ *
+ * Nervos CKB uses:
+ * - Cell model (generalized UTXO) instead of account-based state
+ * - Blake2b-256 for transaction hashing (with CKB-specific personalization)
+ * - secp256k1 ECDSA with 65-byte recoverable signatures (r + s + recovery_id)
+ * - Molecule binary serialization for on-chain data structures
+ *
+ * No external dependencies beyond @noble/hashes/blake2b (transitive dep).
+ *
+ * @example
+ * ```typescript
+ * import { NervosAdapter } from '@sequence0/sdk';
+ *
+ * const ckb = new NervosAdapter('mainnet');
+ *
+ * // Build a CKB transfer transaction
+ * const unsignedTx = await ckb.buildTransaction(
+ *   { to: 'ckb1qzda0cr08m85hc8jlnfp3zer7xulejywt49kt2rr0vthywaa50xwsq...', amount: '10000000000' },
+ *   'ckb1qzda0cr08m85hc8jlnfp3zer7xulejywt49kt2rr0vthywaa50xwsq...'
+ * );
+ *
+ * // ... sign via FROST secp256k1 ...
+ * const signedTx = await ckb.attachSignature(unsignedTx, signatureHex);
+ * const txHash = await ckb.broadcast(signedTx);
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NervosAdapter = void 0;
+exports.createNervosAdapter = createNervosAdapter;
+exports.createNervosTestnetAdapter = createNervosTestnetAdapter;
+const errors_1 = require("../utils/errors");
+const blake2b_1 = require("@noble/hashes/blake2b");
+// ── Network Configuration ──
+const DEFAULT_RPC_URLS = {
+    'mainnet': 'https://mainnet.ckb.dev/rpc',
+    'testnet': 'https://testnet.ckb.dev/rpc',
+};
+/**
+ * CKB personalization string for Blake2b hashing.
+ * CKB uses "ckb-default-hash" as the personalization parameter
+ * for all Blake2b-256 hashes in the protocol.
+ */
+const CKB_HASH_PERSONALIZATION = 'ckb-default-hash';
+/** Minimum cell capacity in shannons (61 CKB = 6100000000 shannons for a basic cell) */
+const MIN_CELL_CAPACITY = BigInt(6100000000);
+/** Shannon per CKB (1 CKB = 1e8 shannons) */
+const SHANNONS_PER_CKB = BigInt(100000000);
+/**
+ * Default secp256k1_blake160 cell dep for mainnet (genesis block dep group).
+ * This references the system script cell dep group in the genesis block.
+ */
+const SECP256K1_BLAKE160_CELL_DEPS = {
+    'mainnet': {
+        outPoint: {
+            txHash: '0x71a7ba8fc96349fea0ed3a5c47992e3b4084b031a42264a018e0072e8172e46c',
+            index: '0x0',
+        },
+        depType: 'dep_group',
+    },
+    'testnet': {
+        outPoint: {
+            txHash: '0xf8de3bb47d055cdf460d93a2a6e1b05f7432f9777c8c474abf4eec1d4aee5d37',
+            index: '0x0',
+        },
+        depType: 'dep_group',
+    },
+};
+/**
+ * secp256k1_blake160 lock script code hash (type ID).
+ * This is the same on both mainnet and testnet.
+ */
+const SECP256K1_BLAKE160_CODE_HASH = '0x9bd7e06f3ecf4be0f2fcd2188b23f1b9fcc88e5d4b65a8637b17723bbda3cce8';
+// ── Blake2b-256 with CKB Personalization ──
+/**
+ * Compute Blake2b-256 with the CKB-specific personalization string.
+ *
+ * CKB uses Blake2b with:
+ * - 32-byte output (256 bits)
+ * - personalization: "ckb-default-hash" (UTF-8 encoded, zero-padded to 16 bytes)
+ *
+ * @param data - Input data as Uint8Array
+ * @returns 32-byte Blake2b-256 hash
+ */
+function ckbBlake2b(data) {
+    return (0, blake2b_1.blake2b)(data, {
+        dkLen: 32,
+        personalization: CKB_HASH_PERSONALIZATION,
+    });
+}
+/**
+ * Compute Blake2b-256 hash incrementally for multiple data chunks.
+ *
+ * @param chunks - Array of Uint8Array data chunks
+ * @returns 32-byte Blake2b-256 hash
+ */
+function ckbBlake2bMulti(...chunks) {
+    const totalLength = chunks.reduce((sum, c) => sum + c.length, 0);
+    const combined = new Uint8Array(totalLength);
+    let offset = 0;
+    for (const chunk of chunks) {
+        combined.set(chunk, offset);
+        offset += chunk.length;
+    }
+    return ckbBlake2b(combined);
+}
+// ── Address Encoding/Decoding ──
+const BECH32M_CHARSET = 'qpzry9x8gf2tvdw0s3jn54khce6mua7l';
+const BECH32M_CONST = 0x2bc830a3;
+function bech32mPolymod(values) {
+    const GEN = [0x3b6a57b2, 0x26508e6d, 0x1ea119fa, 0x3d4233dd, 0x2a1462b3];
+    let chk = 1;
+    for (const v of values) {
+        const b = chk >> 25;
+        chk = ((chk & 0x1ffffff) << 5) ^ v;
+        for (let i = 0; i < 5; i++) {
+            if ((b >> i) & 1) {
+                chk ^= GEN[i];
+            }
+        }
+    }
+    return chk;
+}
+function bech32mHrpExpand(hrp) {
+    const ret = [];
+    for (const c of hrp) {
+        ret.push(c.charCodeAt(0) >> 5);
+    }
+    ret.push(0);
+    for (const c of hrp) {
+        ret.push(c.charCodeAt(0) & 31);
+    }
+    return ret;
+}
+function bech32mVerify(hrp, data5bit) {
+    return bech32mPolymod(bech32mHrpExpand(hrp).concat(data5bit)) === BECH32M_CONST;
+}
+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 in bech32m conversion');
+    }
+    return ret;
+}
+/**
+ * Decode a CKB full address (new format, CKB2021).
+ *
+ * CKB full addresses use bech32m encoding with format:
+ * - ckb1... (mainnet)
+ * - ckt1... (testnet)
+ *
+ * The payload encodes: format_type (0x00) + code_hash (32 bytes) + hash_type (1 byte) + args (20 bytes)
+ *
+ * For default secp256k1_blake160 lock:
+ * - code_hash: SECP256K1_BLAKE160_CODE_HASH
+ * - hash_type: 0x01 (type)
+ * - args: 20-byte blake160 hash of the public key
+ */
+function decodeCkbAddress(address) {
+    const parts = address.toLowerCase().split('1');
+    if (parts.length < 2) {
+        throw new Error(`Invalid CKB address format: ${address}`);
+    }
+    const hrp = parts[0];
+    if (hrp !== 'ckb' && hrp !== 'ckt') {
+        throw new Error(`Invalid CKB address prefix: ${hrp} (expected ckb or ckt)`);
+    }
+    // Everything after the first '1' is the data part
+    const dataStr = address.substring(hrp.length + 1).toLowerCase();
+    const data5bit = [];
+    for (const c of dataStr) {
+        const idx = BECH32M_CHARSET.indexOf(c);
+        if (idx < 0)
+            throw new Error(`Invalid character in CKB address: ${c}`);
+        data5bit.push(idx);
+    }
+    // Verify bech32m checksum
+    if (!bech32mVerify(hrp, data5bit)) {
+        throw new Error('Invalid CKB address checksum');
+    }
+    // Remove checksum (6 characters)
+    const payload5bit = data5bit.slice(0, data5bit.length - 6);
+    // Convert from 5-bit to 8-bit
+    const payload8bit = convertBits(payload5bit, 5, 8, false);
+    // CKB2021 full address format:
+    // payload[0] = 0x00 (full format type)
+    // payload[1..33] = code_hash (32 bytes)
+    // payload[33] = hash_type (0x00=data, 0x01=type, 0x02=data1, 0x04=data2)
+    // payload[34..] = args
+    if (payload8bit[0] !== 0x00) {
+        throw new Error(`Unsupported CKB address format type: 0x${payload8bit[0].toString(16)}`);
+    }
+    const codeHash = '0x' + Buffer.from(payload8bit.slice(1, 33)).toString('hex');
+    const hashTypeByte = payload8bit[33];
+    let hashType;
+    switch (hashTypeByte) {
+        case 0x00:
+            hashType = 'data';
+            break;
+        case 0x01:
+            hashType = 'type';
+            break;
+        case 0x02:
+            hashType = 'data1';
+            break;
+        case 0x04:
+            hashType = 'data2';
+            break;
+        default: throw new Error(`Unknown CKB hash type: 0x${hashTypeByte.toString(16)}`);
+    }
+    const args = '0x' + Buffer.from(payload8bit.slice(34)).toString('hex');
+    return { codeHash, hashType, args };
+}
+// ── Molecule Serialization ──
+// CKB uses Molecule for binary serialization of transaction data.
+// We implement the minimum needed for transaction hashing.
+/**
+ * Serialize a byte array in Molecule format (fixed-size vector).
+ * For CKB scripts, Byte32 is just raw 32 bytes without length prefix.
+ */
+function hexToBytes(hex) {
+    const clean = hex.startsWith('0x') ? hex.slice(2) : hex;
+    const bytes = new Uint8Array(clean.length / 2);
+    for (let i = 0; i < bytes.length; i++) {
+        bytes[i] = parseInt(clean.substring(i * 2, i * 2 + 2), 16);
+    }
+    return bytes;
+}
+function bytesToHex(bytes) {
+    return '0x' + Array.from(bytes).map(b => b.toString(16).padStart(2, '0')).join('');
+}
+/** Write a 32-bit little-endian unsigned integer */
+function writeUint32LE(value) {
+    const buf = new Uint8Array(4);
+    buf[0] = value & 0xff;
+    buf[1] = (value >> 8) & 0xff;
+    buf[2] = (value >> 16) & 0xff;
+    buf[3] = (value >> 24) & 0xff;
+    return buf;
+}
+/** Write a 64-bit little-endian unsigned integer from a BigInt */
+function writeUint64LE(value) {
+    const buf = new Uint8Array(8);
+    for (let i = 0; i < 8; i++) {
+        buf[i] = Number((value >> BigInt(i * 8)) & 0xffn);
+    }
+    return buf;
+}
+/**
+ * Serialize a Molecule fixvec (fixed-size element vector).
+ * Format: 4-byte LE length (item count) + concatenated items
+ */
+function serializeFixvec(items) {
+    const count = writeUint32LE(items.length);
+    const totalLen = 4 + items.reduce((sum, item) => sum + item.length, 0);
+    const result = new Uint8Array(totalLen);
+    result.set(count, 0);
+    let offset = 4;
+    for (const item of items) {
+        result.set(item, offset);
+        offset += item.length;
+    }
+    return result;
+}
+/**
+ * Serialize a Molecule dynvec (dynamic-size element vector).
+ * Format: 4-byte LE total_size + 4-byte LE offsets per item + concatenated items
+ */
+function serializeDynvec(items) {
+    const headerSize = 4 + items.length * 4; // total_size + offsets
+    const totalSize = headerSize + items.reduce((sum, item) => sum + item.length, 0);
+    const result = new Uint8Array(totalSize);
+    // Write total size
+    result.set(writeUint32LE(totalSize), 0);
+    // Write offsets
+    let dataOffset = headerSize;
+    for (let i = 0; i < items.length; i++) {
+        result.set(writeUint32LE(dataOffset), 4 + i * 4);
+        dataOffset += items[i].length;
+    }
+    // Write items
+    dataOffset = headerSize;
+    for (const item of items) {
+        result.set(item, dataOffset);
+        dataOffset += item.length;
+    }
+    return result;
+}
+/**
+ * Serialize a Molecule table (struct with dynamic fields).
+ * Same format as dynvec: 4-byte LE total_size + offsets + fields
+ */
+function serializeTable(fields) {
+    return serializeDynvec(fields);
+}
+/**
+ * Serialize a CKB Script in Molecule format.
+ * Script is a table: { code_hash: Byte32, hash_type: byte, args: Bytes }
+ */
+function serializeScript(script) {
+    const codeHash = hexToBytes(script.codeHash); // 32 bytes
+    let hashTypeByte;
+    switch (script.hashType) {
+        case 'data':
+            hashTypeByte = 0x00;
+            break;
+        case 'type':
+            hashTypeByte = 0x01;
+            break;
+        case 'data1':
+            hashTypeByte = 0x02;
+            break;
+        case 'data2':
+            hashTypeByte = 0x04;
+            break;
+        default: hashTypeByte = 0x00;
+    }
+    const hashType = new Uint8Array([hashTypeByte]);
+    // args is a Molecule Bytes (4-byte LE length + data)
+    const argsData = hexToBytes(script.args);
+    const argsBytes = new Uint8Array(4 + argsData.length);
+    argsBytes.set(writeUint32LE(argsData.length), 0);
+    argsBytes.set(argsData, 4);
+    return serializeTable([codeHash, hashType, argsBytes]);
+}
+/**
+ * Serialize a CellOutput in Molecule format.
+ * CellOutput is a table: { capacity: Uint64, lock: Script, type_: ScriptOpt }
+ */
+function serializeCellOutput(output) {
+    const capacity = writeUint64LE(BigInt(output.capacity.startsWith('0x')
+        ? parseInt(output.capacity, 16)
+        : output.capacity));
+    const lock = serializeScript(output.lock);
+    // ScriptOpt: empty (0 bytes) if null, or serialized Script
+    const typeScript = output.type ? serializeScript(output.type) : new Uint8Array(0);
+    return serializeTable([capacity, lock, typeScript]);
+}
+/**
+ * Serialize a CellInput in Molecule format.
+ * CellInput is a struct: { since: Uint64, previous_output: OutPoint }
+ * OutPoint is a struct: { tx_hash: Byte32, index: Uint32 }
+ * Structs are fixed-size, just concatenated fields.
+ */
+function serializeCellInput(input) {
+    const since = writeUint64LE(BigInt(input.since.startsWith('0x')
+        ? parseInt(input.since, 16)
+        : input.since));
+    const txHash = hexToBytes(input.previousOutput.txHash); // 32 bytes
+    const index = writeUint32LE(parseInt(input.previousOutput.index, 16));
+    // Struct: fields concatenated directly (no length prefix)
+    const result = new Uint8Array(8 + 32 + 4);
+    result.set(since, 0);
+    result.set(txHash, 8);
+    result.set(index, 40);
+    return result;
+}
+/**
+ * Serialize a CellDep in Molecule format.
+ * CellDep is a struct: { out_point: OutPoint, dep_type: byte }
+ */
+function serializeCellDep(dep) {
+    const txHash = hexToBytes(dep.outPoint.txHash);
+    const index = writeUint32LE(parseInt(dep.outPoint.index, 16));
+    const depType = new Uint8Array([dep.depType === 'dep_group' ? 1 : 0]);
+    const result = new Uint8Array(32 + 4 + 1);
+    result.set(txHash, 0);
+    result.set(index, 32);
+    result.set(depType, 36);
+    return result;
+}
+/**
+ * Serialize a RawTransaction in Molecule format and compute its hash.
+ *
+ * RawTransaction is a table:
+ * { version: Uint32, cell_deps: CellDepVec, header_deps: Byte32Vec,
+ *   inputs: CellInputVec, outputs: CellOutputVec, outputs_data: BytesVec }
+ */
+function serializeRawTransaction(tx) {
+    const version = writeUint32LE(parseInt(tx.version, 16) || 0);
+    // CellDepVec: fixvec of CellDep structs (each 37 bytes)
+    const cellDeps = serializeFixvec(tx.cellDeps.map(serializeCellDep));
+    // Byte32Vec: fixvec of 32-byte hashes
+    const headerDeps = serializeFixvec(tx.headerDeps.map(h => hexToBytes(h)));
+    // CellInputVec: fixvec of CellInput structs (each 44 bytes)
+    const inputs = serializeFixvec(tx.inputs.map(serializeCellInput));
+    // CellOutputVec: dynvec of CellOutput tables
+    const outputs = serializeDynvec(tx.outputs.map(serializeCellOutput));
+    // BytesVec: dynvec of Bytes (each is 4-byte len + data)
+    const outputsData = serializeDynvec(tx.outputsData.map(d => {
+        const data = hexToBytes(d);
+        const bytes = new Uint8Array(4 + data.length);
+        bytes.set(writeUint32LE(data.length), 0);
+        bytes.set(data, 4);
+        return bytes;
+    }));
+    return serializeTable([version, cellDeps, headerDeps, inputs, outputs, outputsData]);
+}
+/**
+ * Compute the transaction hash (Blake2b-256 of the serialized RawTransaction).
+ */
+function computeTxHash(rawTx) {
+    const serialized = serializeRawTransaction(rawTx);
+    const hash = ckbBlake2b(serialized);
+    return bytesToHex(hash);
+}
+// ── WitnessArgs Serialization ──
+/**
+ * Serialize WitnessArgs in Molecule format.
+ *
+ * WitnessArgs is a table: { lock: BytesOpt, input_type: BytesOpt, output_type: BytesOpt }
+ * BytesOpt: empty (0 bytes) if None, or Bytes (4-byte LE len + data)
+ */
+function serializeWitnessArgs(lock, inputType, outputType) {
+    const fields = [];
+    for (const field of [lock, inputType, outputType]) {
+        if (field === null) {
+            fields.push(new Uint8Array(0));
+        }
+        else {
+            const bytes = new Uint8Array(4 + field.length);
+            bytes.set(writeUint32LE(field.length), 0);
+            bytes.set(field, 4);
+            fields.push(bytes);
+        }
+    }
+    return serializeTable(fields);
+}
+// ── JSON-RPC Helper ──
+async function rpcCall(url, method, params) {
+    const response = await fetch(url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+            id: 1,
+            jsonrpc: '2.0',
+            method,
+            params,
+        }),
+    });
+    if (!response.ok) {
+        throw new Error(`CKB RPC HTTP ${response.status}: ${await response.text()}`);
+    }
+    const json = await response.json();
+    if (json.error) {
+        throw new Error(`CKB RPC error: ${json.error.message} (code ${json.error.code})`);
+    }
+    return json.result;
+}
+// ── Adapter ──
+class NervosAdapter {
+    /**
+     * Create a Nervos CKB adapter.
+     *
+     * @param network - Network to connect to: 'mainnet' or 'testnet'
+     * @param rpcUrl - Custom RPC URL (overrides the default for the network)
+     */
+    constructor(network = 'mainnet', rpcUrl) {
+        this.network = network;
+        this.rpcUrl = rpcUrl || DEFAULT_RPC_URLS[network];
+    }
+    getRpcUrl() {
+        return this.rpcUrl;
+    }
+    // ────────────────────────────────────────────────
+    //  Build Transaction
+    // ────────────────────────────────────────────────
+    /**
+     * Build an unsigned CKB transaction.
+     *
+     * Fetches live cells for the sender, selects inputs to cover the
+     * transfer amount plus minimum change cell capacity, constructs
+     * outputs (recipient cell + change cell), and includes the
+     * secp256k1_blake160 cell dep.
+     *
+     * The witness placeholder reserves 65 zero bytes in the lock field
+     * for the eventual secp256k1 ECDSA signature.
+     *
+     * @param tx - Transaction parameters (to address, amount in shannons)
+     * @param fromAddress - Sender CKB address (ckb1... or ckt1...)
+     * @returns Hex-encoded JSON payload with raw transaction and metadata
+     */
+    async buildTransaction(tx, fromAddress) {
+        try {
+            const recipientLock = decodeCkbAddress(tx.to);
+            const senderLock = decodeCkbAddress(fromAddress);
+            const amount = BigInt(tx.amount);
+            if (amount < MIN_CELL_CAPACITY) {
+                throw new Error(`Amount ${amount} shannons is below minimum cell capacity ` +
+                    `(${MIN_CELL_CAPACITY} shannons / ${Number(MIN_CELL_CAPACITY) / 1e8} CKB)`);
+            }
+            // Fetch live cells for the sender
+            const liveCells = await this.fetchLiveCells(senderLock);
+            if (liveCells.length === 0) {
+                throw new Error(`No live cells found for ${fromAddress}`);
+            }
+            // Select cells to cover amount + minimum change capacity
+            // We need: amount for recipient + MIN_CELL_CAPACITY for change cell
+            const needed = amount + MIN_CELL_CAPACITY;
+            const selectedCells = [];
+            let inputCapacity = 0n;
+            // Sort by capacity descending for efficient selection
+            const sorted = [...liveCells].sort((a, b) => {
+                const capA = BigInt(a.output.capacity.startsWith('0x')
+                    ? parseInt(a.output.capacity, 16)
+                    : a.output.capacity);
+                const capB = BigInt(b.output.capacity.startsWith('0x')
+                    ? parseInt(b.output.capacity, 16)
+                    : b.output.capacity);
+                return Number(capB - capA);
+            });
+            for (const cell of sorted) {
+                selectedCells.push(cell);
+                const cap = BigInt(cell.output.capacity.startsWith('0x')
+                    ? parseInt(cell.output.capacity, 16)
+                    : cell.output.capacity);
+                inputCapacity += cap;
+                if (inputCapacity >= needed)
+                    break;
+            }
+            if (inputCapacity < needed) {
+                throw new Error(`Insufficient capacity: have ${inputCapacity} shannons, ` +
+                    `need ${needed} shannons (${amount} amount + ${MIN_CELL_CAPACITY} min change)`);
+            }
+            const changeCapacity = inputCapacity - amount;
+            // Build the raw transaction
+            const cellDep = SECP256K1_BLAKE160_CELL_DEPS[this.network];
+            if (!cellDep) {
+                throw new Error(`No secp256k1_blake160 cell dep for network: ${this.network}`);
+            }
+            const inputs = selectedCells.map(cell => ({
+                previousOutput: cell.outPoint,
+                since: '0x0',
+            }));
+            const outputs = [
+                // Recipient output
+                {
+                    capacity: '0x' + amount.toString(16),
+                    lock: recipientLock,
+                },
+                // Change output
+                {
+                    capacity: '0x' + changeCapacity.toString(16),
+                    lock: senderLock,
+                },
+            ];
+            const outputsData = ['0x', '0x']; // No data for simple transfers
+            const rawTransaction = {
+                version: '0x0',
+                cellDeps: [cellDep],
+                headerDeps: [],
+                inputs,
+                outputs,
+                outputsData,
+            };
+            // Create witness placeholder with 65 zero bytes for lock
+            // This is needed for signing payload computation
+            const witnessPlaceholder = serializeWitnessArgs(new Uint8Array(65), // 65 zero bytes for secp256k1 signature placeholder
+            null, null);
+            // Empty witnesses for additional inputs
+            const witnesses = [bytesToHex(witnessPlaceholder)];
+            for (let i = 1; i < inputs.length; i++) {
+                witnesses.push('0x');
+            }
+            const payload = {
+                rawTransaction,
+                witnesses,
+                txHash: computeTxHash(rawTransaction),
+                inputCapacity: inputCapacity.toString(),
+                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 CKB transaction: ${e.message}`, 'nervos');
+        }
+    }
+    // ────────────────────────────────────────────────
+    //  Signing Payload
+    // ────────────────────────────────────────────────
+    /**
+     * Extract the signing payload from the buildTransaction output.
+     *
+     * CKB signing payload is computed as:
+     *   Blake2b-256(tx_hash || witness_length || first_witness || other_witnesses...)
+     *
+     * Where tx_hash is Blake2b-256 of the serialized RawTransaction (Molecule format),
+     * witness_length is the 8-byte LE length of the first witness with placeholder,
+     * and the first witness has a 65-byte zero lock field as placeholder.
+     *
+     * @param unsignedTx - Hex-encoded unsigned transaction from buildTransaction
+     * @returns 32-byte signing hash (hex-encoded, without 0x prefix)
+     */
+    getSigningPayload(unsignedTx) {
+        try {
+            const payload = JSON.parse(Buffer.from(unsignedTx, 'hex').toString());
+            const txHash = hexToBytes(payload.txHash);
+            // The first witness is the WitnessArgs with 65-byte zero lock placeholder
+            const firstWitness = hexToBytes(payload.witnesses[0]);
+            const firstWitnessLen = writeUint64LE(BigInt(firstWitness.length));
+            // Build the message to hash:
+            // tx_hash (32 bytes) + first_witness_length (8 bytes LE) + first_witness + other_witnesses
+            const chunks = [txHash, firstWitnessLen, firstWitness];
+            // Include remaining witnesses
+            for (let i = 1; i < payload.witnesses.length; i++) {
+                const witness = hexToBytes(payload.witnesses[i]);
+                const witnessLen = writeUint64LE(BigInt(witness.length));
+                chunks.push(witnessLen);
+                chunks.push(witness);
+            }
+            const signingHash = ckbBlake2bMulti(...chunks);
+            return Array.from(signingHash).map(b => b.toString(16).padStart(2, '0')).join('');
+        }
+        catch {
+            return unsignedTx;
+        }
+    }
+    // ────────────────────────────────────────────────
+    //  Attach Signature
+    // ────────────────────────────────────────────────
+    /**
+     * Attach a secp256k1 ECDSA signature to the CKB transaction.
+     *
+     * CKB expects a 65-byte recoverable signature (r: 32 bytes + s: 32 bytes + recovery_id: 1 byte)
+     * placed in the lock field of the first WitnessArgs.
+     *
+     * @param unsignedTx - Hex-encoded unsigned transaction from buildTransaction
+     * @param signature - 65-byte secp256k1 signature (hex-encoded, r + s + recovery_id)
+     * @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;
+            if (sig.length !== 130) {
+                throw new Error(`Invalid signature length: expected 130 hex chars (65 bytes), got ${sig.length}`);
+            }
+            // Build WitnessArgs with the actual signature in the lock field
+            const signatureBytes = hexToBytes(sig);
+            const witnessArgs = serializeWitnessArgs(signatureBytes, null, null);
+            // Replace the first witness with the signed WitnessArgs
+            const witnesses = [...payload.witnesses];
+            witnesses[0] = bytesToHex(witnessArgs);
+            const signedPayload = {
+                ...payload,
+                witnesses,
+                signed: true,
+            };
+            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 CKB signature: ${e.message}`, 'nervos');
+        }
+    }
+    // ────────────────────────────────────────────────
+    //  Broadcast
+    // ────────────────────────────────────────────────
+    /**
+     * Broadcast a signed CKB transaction.
+     *
+     * Calls the `send_transaction` JSON-RPC method on the CKB node.
+     *
+     * @param signedTx - Hex-encoded signed transaction from attachSignature
+     * @returns Transaction hash (0x-prefixed)
+     */
+    async broadcast(signedTx) {
+        try {
+            const payload = JSON.parse(Buffer.from(signedTx, 'hex').toString());
+            if (!payload.signed) {
+                throw new Error('Transaction is not signed');
+            }
+            const rawTx = payload.rawTransaction;
+            // Build the full transaction object for the RPC
+            const rpcTransaction = {
+                version: rawTx.version,
+                cell_deps: rawTx.cellDeps.map((dep) => ({
+                    out_point: {
+                        tx_hash: dep.outPoint.txHash,
+                        index: dep.outPoint.index,
+                    },
+                    dep_type: dep.depType === 'dep_group' ? 'dep_group' : 'code',
+                })),
+                header_deps: rawTx.headerDeps,
+                inputs: rawTx.inputs.map((input) => ({
+                    previous_output: {
+                        tx_hash: input.previousOutput.txHash,
+                        index: input.previousOutput.index,
+                    },
+                    since: input.since,
+                })),
+                outputs: rawTx.outputs.map((output) => ({
+                    capacity: output.capacity,
+                    lock: {
+                        code_hash: output.lock.codeHash,
+                        hash_type: output.lock.hashType,
+                        args: output.lock.args,
+                    },
+                    type: output.type ? {
+                        code_hash: output.type.codeHash,
+                        hash_type: output.type.hashType,
+                        args: output.type.args,
+                    } : null,
+                })),
+                outputs_data: rawTx.outputsData,
+                witnesses: payload.witnesses,
+            };
+            const txHash = await rpcCall(this.rpcUrl, 'send_transaction', [rpcTransaction, 'passthrough']);
+            return txHash;
+        }
+        catch (e) {
+            if (e instanceof errors_1.ChainError)
+                throw e;
+            throw new errors_1.ChainError(`Failed to broadcast CKB tx: ${e.message}`, 'nervos');
+        }
+    }
+    // ────────────────────────────────────────────────
+    //  Balance
+    // ────────────────────────────────────────────────
+    /**
+     * Get the CKB balance for an address.
+     *
+     * Returns balance in shannons (1 CKB = 1e8 shannons).
+     * Uses the `get_cells_capacity` indexer RPC method to sum
+     * all live cell capacities for the address lock script.
+     *
+     * @param address - CKB address (ckb1... or ckt1...)
+     * @returns Balance in shannons as a string
+     */
+    async getBalance(address) {
+        try {
+            const lock = decodeCkbAddress(address);
+            const result = await rpcCall(this.rpcUrl, 'get_cells_capacity', [{
+                    script: {
+                        code_hash: lock.codeHash,
+                        hash_type: lock.hashType,
+                        args: lock.args,
+                    },
+                    script_type: 'lock',
+                }]);
+            if (!result || !result.capacity) {
+                return '0';
+            }
+            // capacity is returned as a hex string (e.g. "0x174876e800")
+            const capacityBigInt = BigInt(result.capacity);
+            return capacityBigInt.toString();
+        }
+        catch (e) {
+            if (e instanceof errors_1.ChainError)
+                throw e;
+            return '0';
+        }
+    }
+    // ────────────────────────────────────────────────
+    //  Utility Methods
+    // ────────────────────────────────────────────────
+    /**
+     * Fetch live cells for a given lock script using the CKB indexer RPC.
+     *
+     * Uses the `get_cells` JSON-RPC method to query the indexer for
+     * live (unspent) cells matching the given lock script.
+     *
+     * @param lock - Lock script to search for
+     * @returns Array of live cells
+     */
+    async fetchLiveCells(lock) {
+        const cells = [];
+        let cursor;
+        const limit = '0x64'; // 100 cells per page
+        // Paginate through results
+        for (let page = 0; page < 10; page++) {
+            const params = [
+                {
+                    script: {
+                        code_hash: lock.codeHash,
+                        hash_type: lock.hashType,
+                        args: lock.args,
+                    },
+                    script_type: 'lock',
+                },
+                'asc',
+                limit,
+            ];
+            if (cursor) {
+                params[3] = cursor;
+            }
+            const result = await rpcCall(this.rpcUrl, 'get_cells', cursor ? [...params.slice(0, 3), cursor] : params);
+            if (!result || !result.objects || result.objects.length === 0) {
+                break;
+            }
+            for (const obj of result.objects) {
+                const cell = obj;
+                // Skip cells with type scripts (they may be special cells like UDT, NervosDAO, etc.)
+                if (cell.output.type)
+                    continue;
+                cells.push({
+                    outPoint: {
+                        txHash: cell.out_point.tx_hash,
+                        index: cell.out_point.index,
+                    },
+                    output: {
+                        capacity: cell.output.capacity,
+                        lock: {
+                            codeHash: cell.output.lock.code_hash,
+                            hashType: cell.output.lock.hash_type,
+                            args: cell.output.lock.args,
+                        },
+                        type: null,
+                    },
+                    outputData: cell.output_data,
+                });
+            }
+            cursor = result.last_cursor;
+            if (!cursor || result.objects.length < parseInt(limit, 16)) {
+                break;
+            }
+        }
+        return cells;
+    }
+    /**
+     * Derive a CKB address from a compressed secp256k1 public key.
+     *
+     * The default CKB lock script uses blake160 (first 20 bytes of Blake2b-256)
+     * of the public key as the args field.
+     *
+     * @param pubkeyHex - 33-byte compressed secp256k1 public key (hex-encoded)
+     * @returns CKB address (ckb1... for mainnet, ckt1... for testnet)
+     */
+    deriveAddress(pubkeyHex) {
+        const clean = pubkeyHex.startsWith('0x') ? pubkeyHex.slice(2) : pubkeyHex;
+        if (clean.length !== 66) {
+            throw new errors_1.ChainError(`Invalid public key length: expected 33 bytes (compressed secp256k1), got ${clean.length / 2}`, 'nervos');
+        }
+        // Blake160 = first 20 bytes of Blake2b-256(public_key)
+        const pubkeyBytes = hexToBytes(clean);
+        const hash = ckbBlake2b(pubkeyBytes);
+        const blake160 = hash.slice(0, 20);
+        const args = '0x' + Array.from(blake160).map(b => b.toString(16).padStart(2, '0')).join('');
+        // Encode as CKB2021 full address (bech32m)
+        const hrp = this.network === 'mainnet' ? 'ckb' : 'ckt';
+        const codeHashBytes = hexToBytes(SECP256K1_BLAKE160_CODE_HASH);
+        const hashTypeByte = 0x01; // type
+        // Payload: 0x00 (format) + code_hash (32) + hash_type (1) + args (20)
+        const payloadBytes = new Uint8Array(1 + 32 + 1 + 20);
+        payloadBytes[0] = 0x00; // Full format type
+        payloadBytes.set(codeHashBytes, 1);
+        payloadBytes[33] = hashTypeByte;
+        payloadBytes.set(blake160, 34);
+        // Convert to 5-bit groups
+        const data5bit = convertBits(Array.from(payloadBytes), 8, 5, true);
+        // Compute bech32m checksum
+        const checksumInput = bech32mHrpExpand(hrp).concat(data5bit).concat([0, 0, 0, 0, 0, 0]);
+        const mod = bech32mPolymod(checksumInput) ^ BECH32M_CONST;
+        const checksum = [];
+        for (let i = 0; i < 6; i++) {
+            checksum.push((mod >> (5 * (5 - i))) & 31);
+        }
+        let result = hrp + '1';
+        for (const d of data5bit.concat(checksum)) {
+            result += BECH32M_CHARSET[d];
+        }
+        return result;
+    }
+}
+exports.NervosAdapter = NervosAdapter;
+// ── Factory Functions ──
+/**
+ * Create a Nervos CKB mainnet adapter.
+ *
+ * @param rpcUrl - Optional custom RPC URL
+ * @returns NervosAdapter configured for mainnet
+ */
+function createNervosAdapter(rpcUrl) {
+    return new NervosAdapter('mainnet', rpcUrl);
+}
+/**
+ * Create a Nervos CKB testnet adapter.
+ *
+ * @param rpcUrl - Optional custom RPC URL
+ * @returns NervosAdapter configured for testnet
+ */
+function createNervosTestnetAdapter(rpcUrl) {
+    return new NervosAdapter('testnet', rpcUrl);
+}
+//# sourceMappingURL=nervos.js.map