@sequence0/sdk 2.0.1 → 2.1.0

package/dist/chains/nervos.d.ts

@@ -0,0 +1,148 @@
+/**
+ * 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);
+ * ```
+ */
+import { ChainAdapter } from '../core/types';
+/** Nervos CKB transaction parameters */
+export interface NervosTransaction {
+    /** Recipient CKB address (full address format, ckb1... or ckt1...) */
+    to: string;
+    /** Amount in shannons (1 CKB = 1e8 shannons) */
+    amount: string;
+}
+export declare class NervosAdapter implements ChainAdapter {
+    private network;
+    private rpcUrl;
+    /**
+     * 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' | 'testnet', rpcUrl?: string);
+    getRpcUrl(): string;
+    /**
+     * 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
+     */
+    buildTransaction(tx: NervosTransaction, fromAddress: string): Promise<string>;
+    /**
+     * 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: string): string;
+    /**
+     * 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
+     */
+    attachSignature(unsignedTx: string, signature: string): Promise<string>;
+    /**
+     * 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)
+     */
+    broadcast(signedTx: string): Promise<string>;
+    /**
+     * 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
+     */
+    getBalance(address: string): Promise<string>;
+    /**
+     * 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
+     */
+    private fetchLiveCells;
+    /**
+     * 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: string): string;
+}
+/**
+ * Create a Nervos CKB mainnet adapter.
+ *
+ * @param rpcUrl - Optional custom RPC URL
+ * @returns NervosAdapter configured for mainnet
+ */
+export declare function createNervosAdapter(rpcUrl?: string): NervosAdapter;
+/**
+ * Create a Nervos CKB testnet adapter.
+ *
+ * @param rpcUrl - Optional custom RPC URL
+ * @returns NervosAdapter configured for testnet
+ */
+export declare function createNervosTestnetAdapter(rpcUrl?: string): NervosAdapter;
+//# sourceMappingURL=nervos.d.ts.map

package/dist/chains/nervos.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nervos.d.ts","sourceRoot":"","sources":["../../src/chains/nervos.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAsD7C,wCAAwC;AACxC,MAAM,WAAW,iBAAiB;IAC9B,sEAAsE;IACtE,EAAE,EAAE,MAAM,CAAC;IACX,gDAAgD;IAChD,MAAM,EAAE,MAAM,CAAC;CAClB;AAgeD,qBAAa,aAAc,YAAW,YAAY;IAC9C,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,MAAM,CAAS;IAEvB;;;;;OAKG;gBACS,OAAO,GAAE,SAAS,GAAG,SAAqB,EAAE,MAAM,CAAC,EAAE,MAAM;IAKvE,SAAS,IAAI,MAAM;IAQnB;;;;;;;;;;;;;;OAcG;IACG,gBAAgB,CAAC,EAAE,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IA6HnF;;;;;;;;;;;;OAYG;IACH,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM;IAgC7C;;;;;;;;;OASG;IACG,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAuC7E;;;;;;;OAOG;IACG,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAiElD;;;;;;;;;OASG;IACG,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IA8BlD;;;;;;;;OAQG;YACW,cAAc;IA2E5B;;;;;;;;OAQG;IACH,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;CA8C3C;AAID;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,aAAa,CAElE;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,aAAa,CAEzE"}