@mr-zwets/bchn-api-wrapper 1.0.1 → 1.0.2

package/dist/interfaces/rpcInterfaces/blockchain.d.ts

@@ -1,10 +1,12 @@
 import type { TokenData, Transaction, TransactionInput } from "../interfaces.js";
+/** Finalize a block by hash (Avalanche post-consensus). */
 export interface FinalizeBlock {
     method: 'finalizeblock';
     params: [
         blockhash: string
     ];
 }
+/** Returns the hash of the best (tip) block in the most-work chain. */
 export interface GetBestBlockHash {
     method: 'getbestblockhash';
     params: [];
@@ -17,6 +19,38 @@ interface GetBlockBase {
         verbosity?: number | boolean
     ];
 }
+/** Adaptive Block Limit Algorithm state (activated May 2024). */
+export interface AblaState {
+    epsilon: number;
+    beta: number;
+    blocksize: number;
+    blocksizelimit: number;
+    nextblocksizelimit: number;
+}
+/**
+ * Base block response fields shared across verbosity levels.
+ * @note `previousblockhash` not present on genesis block (height 0).
+ * @note `nextblockhash` not present on chain tip.
+ */
+interface BlockResponseBase {
+    hash: string;
+    confirmations: number;
+    size: number;
+    height: number;
+    version: number;
+    versionHex: string;
+    merkleroot: string;
+    time: number;
+    mediantime: number;
+    nonce: number;
+    bits: string;
+    difficulty: number;
+    chainwork: string;
+    nTx: number;
+    previousblockhash: string;
+    nextblockhash: string;
+}
+/** Verbosity 0: Returns hex-encoded block data. */
 export interface GetBlockVerbosity0 extends GetBlockBase {
     params: [
         blockhash: string,
@@ -24,73 +58,74 @@ export interface GetBlockVerbosity0 extends GetBlockBase {
     ];
     response: string;
 }
+/** Verbosity 1 response: block with tx IDs as string array. */
+interface BlockResponseVerbosity1 extends BlockResponseBase {
+    tx: string[];
+}
+/** Verbosity 1: Block with tx IDs - works for any block. */
 export interface GetBlockVerbosity1 extends GetBlockBase {
     params: [
         blockhash: string,
         verbosity?: 1 | true
     ];
-    response: {
-        hash: string;
-        confirmations: number;
-        size: number;
-        height: number;
-        version: number;
-        versionHex: string;
-        merkleroot: string;
-        tx: string[];
-        time: number;
-        mediantime: number;
-        nonce: number;
-        bits: string;
-        difficulty: number;
-        chainwork: string;
-        nTx: number;
-        previousblockhash: string;
-        nextblockhash: string;
-        ablastate: {
-            epsilon: number;
-            beta: number;
-            blocksize: number;
-            blocksizelimit: number;
-            nextblocksizelimit: number;
-        };
+    response: BlockResponseVerbosity1 & {
+        ablastate?: AblaState;
     };
 }
+/** Verbosity 1: Block with tx IDs - for blocks before ABLA activation (May 2024). */
+export interface GetBlockVerbosity1PreAbla extends GetBlockBase {
+    params: [
+        blockhash: string,
+        verbosity?: 1 | true
+    ];
+    response: BlockResponseVerbosity1;
+}
+/** Verbosity 1: Block with tx IDs - for blocks after ABLA activation (May 2024). */
+export interface GetBlockVerbosity1PostAbla extends GetBlockBase {
+    params: [
+        blockhash: string,
+        verbosity?: 1 | true
+    ];
+    response: BlockResponseVerbosity1 & {
+        ablastate: AblaState;
+    };
+}
+/** Verbosity 2 response: block with tx objects containing txid and fee. */
+interface BlockResponseVerbosity2 extends BlockResponseBase {
+    tx: {
+        txid: string;
+        fee?: number;
+    }[];
+}
+/** Verbosity 2: Block with txid/fee objects - works for any block. */
 export interface GetBlockVerbosity2 extends GetBlockBase {
     params: [
         blockhash: string,
         verbosity: 2
     ];
-    response: {
-        hash: string;
-        confirmations: number;
-        size: number;
-        height: number;
-        version: number;
-        versionHex: string;
-        merkleroot: string;
-        tx: {
-            txid: string;
-            fee?: number;
-        }[];
-        time: number;
-        mediantime: number;
-        nonce: number;
-        bits: string;
-        difficulty: number;
-        chainwork: string;
-        nTx: number;
-        previousblockhash: string;
-        nextblockhash: string;
-        ablastate?: {
-            epsilon: number;
-            beta: number;
-            blocksize: number;
-            blocksizelimit: number;
-            nextblocksizelimit: number;
-        };
+    response: BlockResponseVerbosity2 & {
+        ablastate?: AblaState;
     };
 }
+/** Verbosity 2: Block with txid/fee objects - for blocks before ABLA activation (May 2024). */
+export interface GetBlockVerbosity2PreAbla extends GetBlockBase {
+    params: [
+        blockhash: string,
+        verbosity: 2
+    ];
+    response: BlockResponseVerbosity2;
+}
+/** Verbosity 2: Block with txid/fee objects - for blocks after ABLA activation (May 2024). */
+export interface GetBlockVerbosity2PostAbla extends GetBlockBase {
+    params: [
+        blockhash: string,
+        verbosity: 2
+    ];
+    response: BlockResponseVerbosity2 & {
+        ablastate: AblaState;
+    };
+}
+/** Transaction input extended with previous output data. */
 export interface TransactionInputWithPrevout extends TransactionInput {
     prevout?: {
         generated: boolean;
@@ -105,41 +140,124 @@ export interface TransactionInputWithPrevout extends TransactionInput {
         tokenData?: TokenData;
     };
 }
+/** Transaction with prevout data on inputs (used by verbosity 3). */
 export interface TransactionWithPrevout extends Omit<Transaction, 'vin'> {
     vin: TransactionInputWithPrevout[];
 }
+/** Verbosity 3 response: full transaction details with prevout. */
+interface BlockResponseVerbosity3 extends BlockResponseBase {
+    tx: TransactionWithPrevout[];
+}
+/** Verbosity 3: Block with full tx objects including prevout - works for any block. */
 export interface GetBlockVerbosity3 extends GetBlockBase {
     params: [
         blockhash: string,
         verbosity: 3
     ];
-    response: {
-        hash: string;
-        confirmations: number;
-        size: number;
+    response: BlockResponseVerbosity3 & {
+        ablastate?: AblaState;
+    };
+}
+/** Verbosity 3: Block with full tx objects including prevout - for blocks before ABLA activation (May 2024). */
+export interface GetBlockVerbosity3PreAbla extends GetBlockBase {
+    params: [
+        blockhash: string,
+        verbosity: 3
+    ];
+    response: BlockResponseVerbosity3;
+}
+/** Verbosity 3: Block with full tx objects including prevout - for blocks after ABLA activation (May 2024). */
+export interface GetBlockVerbosity3PostAbla extends GetBlockBase {
+    params: [
+        blockhash: string,
+        verbosity: 3
+    ];
+    response: BlockResponseVerbosity3 & {
+        ablastate: AblaState;
+    };
+}
+/** Script fingerprint and pattern info for bytecode analysis (v29.0.0+). */
+export interface ByteCodePattern {
+    fingerprint: string;
+    pattern: string;
+    patternArgsInfo?: string[];
+}
+/** Script with optional bytecode pattern metadata (v29.0.0+). */
+export interface ScriptPubKeyWithPattern {
+    asm: string;
+    hex: string;
+    type: 'nonstandard' | 'pubkey' | 'pubkeyhash' | 'scripthash' | 'multisig' | 'nulldata';
+    address?: string;
+    byteCodePattern?: ByteCodePattern;
+}
+/** Transaction input with prevout and pattern info (v29.0.0+). */
+export interface TransactionInputWithPattern extends TransactionInput {
+    prevout?: {
+        generated: boolean;
         height: number;
-        version: number;
-        versionHex: string;
-        merkleroot: string;
-        tx: TransactionWithPrevout[];
-        time: number;
-        mediantime: number;
-        nonce: number;
-        bits: string;
-        difficulty: number;
-        chainwork: string;
-        nTx: number;
-        previousblockhash: string;
-        nextblockhash: string;
-        ablastate?: {
-            epsilon: number;
-            beta: number;
-            blocksize: number;
-            blocksizelimit: number;
-            nextblocksizelimit: number;
-        };
+        value: number;
+        scriptPubKey: ScriptPubKeyWithPattern;
+        tokenData?: TokenData;
+    };
+    redeemScript?: {
+        asm: string;
+        hex: string;
+        type: string;
+        byteCodePattern?: ByteCodePattern;
+        p2shType?: string;
+    };
+}
+/** Transaction output with pattern-enabled scriptPubKey (v29.0.0+). */
+export interface TransactionOutputWithPattern {
+    value: number;
+    n: number;
+    scriptPubKey: ScriptPubKeyWithPattern;
+    tokenData?: TokenData;
+}
+/** Transaction with bytecode patterns (v29.0.0+). */
+export interface TransactionWithPattern {
+    txid: string;
+    hash: string;
+    size: number;
+    version: number;
+    locktime: number;
+    vin: TransactionInputWithPattern[];
+    vout: TransactionOutputWithPattern[];
+    fee?: number;
+}
+/** Verbosity 4 response: includes byteCodePattern (v29.0.0+). */
+interface BlockResponseVerbosity4 extends BlockResponseBase {
+    tx: TransactionWithPattern[];
+}
+/** Verbosity 4: Block with bytecode patterns (v29.0.0+) - works for any block. */
+export interface GetBlockVerbosity4 extends GetBlockBase {
+    params: [
+        blockhash: string,
+        verbosity: 4
+    ];
+    response: BlockResponseVerbosity4 & {
+        ablastate?: AblaState;
     };
 }
+/** Verbosity 4: Block with bytecode patterns (v29.0.0+) - for blocks before ABLA activation (May 2024). */
+export interface GetBlockVerbosity4PreAbla extends GetBlockBase {
+    params: [
+        blockhash: string,
+        verbosity: 4
+    ];
+    response: BlockResponseVerbosity4;
+}
+/** Verbosity 4: Block with bytecode patterns (v29.0.0+) - for blocks after ABLA activation (May 2024). */
+export interface GetBlockVerbosity4PostAbla extends GetBlockBase {
+    params: [
+        blockhash: string,
+        verbosity: 4
+    ];
+    response: BlockResponseVerbosity4 & {
+        ablastate: AblaState;
+    };
+}
+/** Returns blockchain state, sync progress, and upcoming upgrade info. */
 export interface GetBlockchainInfo {
     method: 'getblockchaininfo';
     params: [];
@@ -159,13 +277,25 @@ export interface GetBlockchainInfo {
         automatic_pruning: boolean;
         prune_target_size?: number;
         warnings: string;
+        upgrade_status: {
+            name: string;
+            mempool_activated: boolean;
+            mempool_activation_mtp: number;
+            block_preactivation_height: number;
+            block_preactivation_hash: string;
+            block_postactivation_height: number;
+            block_postactivation_hash: string;
+            software_expiration_time: number;
+        };
     };
 }
+/** Returns the current block height. */
 export interface GetBlockCount {
     method: 'getblockcount';
     params: [];
     response: number;
 }
+/** Returns block hash at given height. */
 export interface GetBlockHash {
     method: 'getblockhash';
     params: [
@@ -180,6 +310,7 @@ export interface GetBlockHeaderBase {
         verbosity?: boolean | number
     ];
 }
+/** Verbosity 0: Returns hex-encoded block header. */
 export interface GetBlockHeaderVerbosity0 extends GetBlockHeaderBase {
     params: [
         hash_or_height: string | number,
@@ -187,36 +318,57 @@ export interface GetBlockHeaderVerbosity0 extends GetBlockHeaderBase {
     ];
     response: string;
 }
+/**
+ * Base header response fields.
+ * @note `previousblockhash` not present on genesis block (height 0).
+ * @note `nextblockhash` not present on chain tip.
+ */
+interface HeaderResponseBase {
+    hash: string;
+    confirmations: number;
+    height: number;
+    version: number;
+    versionHex: string;
+    merkleroot: string;
+    time: number;
+    mediantime: number;
+    nonce: number;
+    bits: string;
+    difficulty: number;
+    chainwork: string;
+    nTx: number;
+    previousblockhash: string;
+    nextblockhash: string;
+}
+/** Verbosity 1: Parsed header object - works for any block. */
 export interface GetBlockHeaderVerbosity1 extends GetBlockHeaderBase {
     params: [
         hash_or_height: string | number,
         verbosity?: true | 1
     ];
-    response: {
-        hash: string;
-        confirmations: number;
-        height: number;
-        version: number;
-        versionHex: string;
-        merkleroot: string;
-        time: number;
-        mediantime: number;
-        nonce: number;
-        bits: string;
-        difficulty: number;
-        chainwork: string;
-        nTx: number;
-        previousblockhash: string;
-        nextblockhash: string;
-        ablastate: {
-            epsilon: number;
-            beta: number;
-            blocksize: number;
-            blocksizelimit: number;
-            nextblocksizelimit: number;
-        };
+    response: HeaderResponseBase & {
+        ablastate?: AblaState;
+    };
+}
+/** Verbosity 1: Parsed header object - for blocks before ABLA activation (May 2024). */
+export interface GetBlockHeaderVerbosity1PreAbla extends GetBlockHeaderBase {
+    params: [
+        hash_or_height: string | number,
+        verbosity?: true | 1
+    ];
+    response: HeaderResponseBase;
+}
+/** Verbosity 1: Parsed header object - for blocks after ABLA activation (May 2024). */
+export interface GetBlockHeaderVerbosity1PostAbla extends GetBlockHeaderBase {
+    params: [
+        hash_or_height: string | number,
+        verbosity?: true | 1
+    ];
+    response: HeaderResponseBase & {
+        ablastate: AblaState;
     };
 }
+/** Returns fee/size statistics for a block. */
 export interface GetBlockStats {
     method: 'getblockheader';
     params: [
@@ -257,6 +409,7 @@ export interface GetBlockStats {
         utxo_size_inc: number;
     };
 }
+/** Returns all known chain tips including forks. */
 export interface GetChainTips {
     method: 'getchaintips';
     params: [];
@@ -267,6 +420,7 @@ export interface GetChainTips {
         status: 'active' | 'parked' | 'headers-only' | 'valid-headers' | 'valid-fork' | 'active';
     }[];
 }
+/** Returns transaction statistics over a block window. */
 export interface GetChainTxStats {
     method: 'getchaintxstats';
     params: [
@@ -283,6 +437,7 @@ export interface GetChainTxStats {
         txrate: number;
     };
 }
+/** Returns current network difficulty. */
 export interface GetDifficulty {
     method: 'getdifficulty';
     params: [];
@@ -299,6 +454,7 @@ interface GetDsProofBase {
         recursive?: boolean
     ];
 }
+/** Verbosity 0: Double-spend proof as hex. */
 export interface GetDsProofVerbosity0 extends GetDsProofBase {
     params: [
         dspid_or_txid_or_outpoint: string | {
@@ -314,6 +470,7 @@ export interface GetDsProofVerbosity0 extends GetDsProofBase {
         path?: string[];
     };
 }
+/** Verbosity 1: Double-spend proof with descendants. */
 export interface GetDsProofVerbosity1 extends GetDsProofBase {
     params: [
         dspid_or_txid_or_outpoint: string | {
@@ -330,6 +487,7 @@ export interface GetDsProofVerbosity1 extends GetDsProofBase {
         descendants?: string[];
     };
 }
+/** Verbosity 2: Double-spend proof with parsed outpoint. */
 export interface GetDsProofVerbosity2 extends GetDsProofBase {
     params: [
         dspid_or_txid_or_outpoint: string | {
@@ -350,6 +508,7 @@ export interface GetDsProofVerbosity2 extends GetDsProofBase {
         path?: string[];
     };
 }
+/** Double-spend proof spender data. */
 interface Spender {
     txversion: number;
     sequence: number;
@@ -362,6 +521,7 @@ interface Spender {
         hex: string;
     };
 }
+/** Verbosity 3: Double-spend proof with full spender details. */
 export interface GetDsProofVerbosity3 extends GetDsProofVerbosity2 {
     response: {
         dspid: string;
@@ -382,6 +542,7 @@ export interface GetDsProofListBase {
         include_orphans?: boolean
     ];
 }
+/** Verbosity 0: List of double-spend proof IDs. */
 export interface GetDsProofListVerbosity0 extends GetDsProofListBase {
     params: [
         verbosity?: 0 | false,
@@ -389,6 +550,7 @@ export interface GetDsProofListVerbosity0 extends GetDsProofListBase {
     ];
     response: string[];
 }
+/** Verbosity 1: List of double-spend proofs as hex with txid. */
 export interface GetDsProofListVerbosity1 extends GetDsProofListBase {
     params: [
         verbosity?: 1,
@@ -399,6 +561,7 @@ export interface GetDsProofListVerbosity1 extends GetDsProofListBase {
         txid: string | null;
     }[];
 }
+/** Verbosity 2: List of double-spend proofs with parsed outpoints. */
 export interface GetDsProofListVerbosity2 extends GetDsProofListBase {
     params: [
         verbosity?: 2 | true,
@@ -413,6 +576,7 @@ export interface GetDsProofListVerbosity2 extends GetDsProofListBase {
         };
     }[];
 }
+/** Verbosity 3: List of double-spend proofs with full spender details. */
 export interface GetDsProofListVerbosity3 extends GetDsProofListBase {
     response: {
         dspid: string;
@@ -424,6 +588,7 @@ export interface GetDsProofListVerbosity3 extends GetDsProofListBase {
         spenders: Spender[];
     }[];
 }
+/** Returns double-spend proof score for a transaction. */
 export interface GetDsProofScore {
     method: 'getdsproofscore';
     params: [
@@ -431,6 +596,7 @@ export interface GetDsProofScore {
     ];
     response: number;
 }
+/** Returns the hash of the last finalized block. */
 export interface GetFinalizedBlockHash {
     method: 'getfinalizedblockhash';
     params: [];
@@ -443,6 +609,7 @@ interface GetMempoolAncestorsBase {
         verbose?: boolean | number
     ];
 }
+/** Verbosity 0: Returns ancestor txids as array. */
 export interface GetMempoolAncestorsVerbosity0 extends GetMempoolAncestorsBase {
     params: [
         txid: string,
@@ -450,6 +617,7 @@ export interface GetMempoolAncestorsVerbosity0 extends GetMempoolAncestorsBase {
     ];
     response: string[];
 }
+/** Verbosity 1: Returns ancestor txids with detailed mempool info. */
 export interface GetMempoolAncestorsVerbosity1 extends GetMempoolAncestorsBase {
     params: [
         txid: string,
@@ -475,6 +643,7 @@ interface GetMempoolDescendantsBase {
         verbose?: boolean | number
     ];
 }
+/** Verbosity 0: Returns descendant txids as array. */
 export interface GetMempoolDescendantsVerbosity0 extends GetMempoolDescendantsBase {
     params: [
         txid: string,
@@ -482,6 +651,7 @@ export interface GetMempoolDescendantsVerbosity0 extends GetMempoolDescendantsBa
     ];
     response: string[];
 }
+/** Verbosity 1: Returns descendant txids with detailed mempool info. */
 export interface GetMempoolDescendantsVerbosity1 extends GetMempoolDescendantsBase {
     params: [
         txid: string,
@@ -500,6 +670,7 @@ export interface GetMempoolDescendantsVerbosity1 extends GetMempoolDescendantsBa
         };
     };
 }
+/** Returns mempool entry for a specific transaction. */
 export interface GetMempoolEntry {
     method: 'getmempoolentry';
     params: [
@@ -516,6 +687,7 @@ export interface GetMempoolEntry {
         spentby: string[];
     };
 }
+/** Returns mempool statistics and configuration. */
 export interface GetMempoolInfo {
     method: 'getmempoolinfo';
     params: [];
@@ -527,6 +699,8 @@ export interface GetMempoolInfo {
         maxmempool: number;
         mempoolminfee: number;
         minrelaytxfee: number;
+        permitbaremultisig: boolean;
+        maxdatacarriersize: number;
     };
 }
 interface GetRawMempoolBase {
@@ -535,12 +709,14 @@ interface GetRawMempoolBase {
         verbose?: boolean | number
     ];
 }
+/** Verbosity 0: Returns all mempool txids as array. */
 export interface GetRawMempoolVerbosity0 extends GetRawMempoolBase {
     params: [
         verbose?: false | 0
     ];
     response: string[];
 }
+/** Verbosity 1: Returns all mempool txids with detailed info. */
 export interface GetRawMempoolVerbosity1 extends GetRawMempoolBase {
     params: [
         verbose?: true | 1
@@ -558,6 +734,7 @@ export interface GetRawMempoolVerbosity1 extends GetRawMempoolBase {
         };
     };
 }
+/** Returns details about an unspent transaction output. */
 export interface GetTxOut {
     method: 'gettxout';
     params: [
@@ -579,6 +756,7 @@ export interface GetTxOut {
         coinbase: boolean;
     };
 }
+/** Returns a merkle proof that transaction(s) are in a block. */
 export interface GetTxOutProof {
     method: 'gettxoutproof';
     params: [
@@ -587,10 +765,13 @@ export interface GetTxOutProof {
     ];
     response: string;
 }
+/** Returns UTXO set statistics. */
 export interface GetTxOutSetInfo {
     method: 'gettxoutsetinfo';
     params: [
-        txid: string
+        hash_type?: 'hash_serialized_3' | 'ecmh' | 'muhash',
+        hash_or_height?: string | number,
+        use_index?: boolean
     ];
     response: {
         height: number;
@@ -598,11 +779,12 @@ export interface GetTxOutSetInfo {
         transactions: number;
         txouts: number;
         bogosize: number;
-        hash_serialized: string;
+        hash_serialized_3: string;
         disk_size: number;
         total_amount: number;
     };
 }
+/** Permanently marks a block as invalid (cannot be part of best chain). */
 export interface InvalidateBlock {
     method: 'invalidateblock';
     params: [
@@ -610,6 +792,7 @@ export interface InvalidateBlock {
     ];
     response: null;
 }
+/** Marks a block as parked (temporarily invalid). */
 export interface ParkBlock {
     method: 'parkblock';
     params: [
@@ -617,6 +800,7 @@ export interface ParkBlock {
     ];
     response: null;
 }
+/** Treats a block as if it were received before others with same work. */
 export interface PreciousBlock {
     method: 'preciousblock';
     params: [
@@ -624,6 +808,7 @@ export interface PreciousBlock {
     ];
     response: null;
 }
+/** Prunes blockchain up to specified height. Returns height of last pruned block. */
 export interface PruneBlockchain {
     method: 'pruneblockchain';
     params: [
@@ -631,6 +816,7 @@ export interface PruneBlockchain {
     ];
     response: number;
 }
+/** Removes invalidity status from a block and its descendants. */
 export interface ReconsiderBlock {
     method: 'reconsiderblock';
     params: [
@@ -638,11 +824,13 @@ export interface ReconsiderBlock {
     ];
     response: null;
 }
+/** Saves mempool to disk. */
 export interface SaveMempool {
     method: 'savemempool';
     params: [];
     response: null;
 }
+/** Scans UTXO set for outputs matching descriptors. */
 export interface ScanTxOutSet {
     method: 'scantxoutset';
     params: [
@@ -667,6 +855,7 @@ export interface ScanTxOutSet {
         };
     } | boolean;
 }
+/** Removes parked status from a block and its descendants. */
 export interface UnparkBlock {
     method: 'unparkblock';
     params: [
@@ -674,6 +863,7 @@ export interface UnparkBlock {
     ];
     response: null;
 }
+/** Verifies blockchain database. */
 export interface VerifyChain {
     method: 'verifychain';
     params: [
@@ -682,6 +872,7 @@ export interface VerifyChain {
     ];
     response: boolean;
 }
+/** Verifies a merkle proof and returns the txids it commits to. */
 export interface VerifyTxOutProof {
     method: 'verifytxoutproof';
     params: [