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

package/src/interfaces/rpcInterfaces/blockchain.ts

@@ -1,759 +1,933 @@
-/* --- Blockchain Commands --- */
-// progress 33/33
-
-import type { TokenData, Transaction, TransactionInput } from "../interfaces.js";
-
-export interface FinalizeBlock {
-  method: 'finalizeblock';
-  params: [
-    blockhash: string
-  ];
-}
-
-export interface GetBestBlockHash {
-  method: 'getbestblockhash';
-  params: [];
-  response: string;
-}
-
-interface GetBlockBase {
-  method: 'getblock';
-  params: [
-    blockhash: string,
-    verbosity?: number | boolean
-  ];
-}
-
-// Verbosity = 0 (or false)
-export interface GetBlockVerbosity0 extends GetBlockBase {
-  params: [
-    blockhash: string,
-    verbosity?: 0 | false
-  ];
-  response: string
-}
-
-// Verbosity = 1 (or true)
-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;
-    }
-  }
-}
-
-// Verbosity = 2
-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;
-    };
-  };
-}
-
-export interface TransactionInputWithPrevout extends TransactionInput {
-  prevout?: {
-    generated: boolean;
-    height: number;
-    value: number;
-    scriptPubKey: {
-      asm: string;
-      hex: string;
-      type: 'nonstandard' | 'pubkey' | 'pubkeyhash' | 'scripthash' | 'multisig' | 'nulldata';
-      address?: string;
-    };
-    tokenData?: TokenData;
-  };
-}
-
-// GetBlockVerbosity3 uses enhanced TransactionInputWithPrevout
-export interface TransactionWithPrevout extends Omit<Transaction, 'vin'> {
-  vin: TransactionInputWithPrevout[]; // Use the extended input type with `prevout`
-}
-
-// Verbosity = 3
-export interface GetBlockVerbosity3 extends GetBlockBase {
-  params: [
-    blockhash: string,
-    verbosity: 3
-  ];
-  response: {
-    hash: string;
-    confirmations: number;
-    size: number;
-    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;
-    };
-  };
-}
-
-export interface GetBlockchainInfo {
-  method: 'getblockchaininfo';
-  params: [];
-  response: {
-    chain: 'main' | 'test' | 'regtest';
-    blocks: number;
-    headers: number;
-    bestblockhash: string;
-    difficulty: number;
-    mediantime: number;
-    verificationprogress: number;
-    initialblockdownload: boolean;
-    chainwork: string;
-    size_on_disk: number;
-    pruned: boolean;
-    pruneheight: number;
-    automatic_pruning: boolean;
-    prune_target_size?: number;
-    warnings: string;
-  }
-}
-
-export interface GetBlockCount {
-  method: 'getblockcount';
-  params: [];
-  response: number;
-}
-
-export interface GetBlockHash {
-  method: 'getblockhash';
-  params: [
-    height: number
-  ];
-  response: string;
-}
-
-export interface GetBlockHeaderBase {
-  method: 'getblockheader';
-  params: [
-    hash_or_height: string| number,
-    verbosity?: boolean | number
-  ];
-}
-
-export interface GetBlockHeaderVerbosity0 extends GetBlockHeaderBase {
-  params: [
-    hash_or_height: string| number,
-    verbosity?: false | 0
-  ];
-  response: string;
-}
-
-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;
-    }
-  };
-}
-
-export interface GetBlockStats {
-  method: 'getblockheader';
-  params: [
-    hash_or_height: string| number,
-    stats?: string[]
-  ];
-  response: {
-    avgfee: number;
-    avgfeerate: number;
-    avgtxsize: number;
-    blockhash: string;
-    feerate_percentiles: {
-      "10th_percentile_feerate": number;
-      "25th_percentile_feerate": number;
-      "50th_percentile_feerate": number;
-      "75th_percentile_feerate": number;
-      "90th_percentile_feerate": number;
-    };
-    height: number;
-    ins: number;
-    maxfee: number;
-    maxfeerate: number;
-    maxtxsize: number;
-    medianfee: number;
-    mediantime: number;
-    mediantxsize: number;
-    minfee: number;
-    minfeerate: number;
-    mintxsize: number;
-    outs: number;
-    subsidy: number;
-    time: number;
-    total_out: number;
-    total_size: number;
-    totalfee: number;
-    txs: number;
-    utxo_increase: number;
-    utxo_size_inc: number;
-  }
-  
-}
-
-export interface GetChainTips {
-  method: 'getchaintips';
-  params: [];
-  response: {
-    height: number
-    hash: string
-    branchlen:number
-    status: 'active' | 'parked' | 'headers-only' | 'valid-headers' | 'valid-fork' | 'active'
-  }[]
-}
-
-export interface GetChainTxStats {
-  method: 'getchaintxstats';
-  params: [
-    nblocks?: number,
-    blockhash?: string
-  ];
-  response: {
-    time: number;
-    txcount: number;
-    window_final_block_hash: string;
-    window_block_count: number;
-    window_tx_count: number | undefined;
-    window_interval: number | undefined;
-    txrate: number;
-  }
-}
-
-export interface GetDifficulty {
-  method: 'getdifficulty';
-  params: [];
-  response: number;
-}
-
-interface GetDsProofBase {
-  method: 'getdsproof';
-  params: [
-    dspid_or_txid_or_outpoint: string | { txid: string; vout: number },
-    verbosity?: number | boolean,
-    recursive?: boolean
-  ];
-}
-
-// Verbosity = 0 (or false)
-export interface GetDsProofVerbosity0 extends GetDsProofBase {
-  params: [
-    dspid_or_txid_or_outpoint: string | { txid: string; vout: number },
-    verbosity?: 0 | false,
-    recursive?: boolean
-  ];
-  response: {
-    hex: string;
-    txid: string | null;
-    path?: string[];  // Optional for recursive = true
-  };
-}
-
-// Verbosity = 1
-export interface GetDsProofVerbosity1 extends GetDsProofBase {
-  params: [
-    dspid_or_txid_or_outpoint: string | { txid: string; vout: number },
-    verbosity?: 1,
-    recursive?: boolean
-  ];
-  response: {
-    hex: string;
-    txid: string | null;
-    path?: string[];  // Optional for recursive = true
-    descendants?: string[]
-  };
-}
-
-// Verbosity = 2 (or true)
-export interface GetDsProofVerbosity2 extends GetDsProofBase {
-  params: [
-    dspid_or_txid_or_outpoint: string | { txid: string; vout: number },
-    verbosity?: 2 | true,
-    recursive?: boolean
-  ];
-  response: {
-    dspid: string;
-    txid: string | null;
-    outpoint: {
-      txid: string;
-      vout: number;
-    };
-    descendants?: string[];
-    path?: string[];  // Optional for recursive = true
-  };
-}
-
-interface Spender {
-  txversion: number,
-  sequence: number,
-  locktime: number,
-  hashprevoutputs: string,
-  hashsequence: string,
-  hashoutputs: string,
-  pushdata: {
-    asm: string,
-    hex: string
-  }
-}
-
-// Verbosity = 3
-export interface GetDsProofVerbosity3 extends GetDsProofVerbosity2 {
-  response: {
-    dspid: string;
-    txid: string | null;
-    outpoint: {
-      txid: string;
-      vout: number;
-    };
-    spenders: Spender[];
-    descendants?: string[];
-    path?: string[];  // Optional for recursive = true
-  };
-}
-
-export interface GetDsProofListBase {
-  method: 'getdsprooflist';
-  params: [
-    verbosity?: number | boolean,
-    include_orphans?: boolean
-  ];
-}
-
-// Verbosity = 0 (or false)
-export interface GetDsProofListVerbosity0 extends GetDsProofListBase {
-  params: [
-    verbosity?: 0 | false,
-    include_orphans?: boolean
-  ];
-  response: string[]
-}
-
-// Verbosity = 1
-export interface GetDsProofListVerbosity1 extends GetDsProofListBase {
-  params: [
-    verbosity?: 1,
-    include_orphans?: boolean
-  ];
-  response: {
-    hex: string;
-    txid: string | null;
-  }[]
-}
-
-// Verbosity = 2 (or true)
-export interface GetDsProofListVerbosity2 extends GetDsProofListBase {
-  params: [
-    verbosity?: 2 | true,
-    include_orphans?: boolean
-  ];
-  response: {
-    dspid: string;
-    txid: string | null;
-    outpoint: {
-      txid: string;
-      vout: number;
-    };
-  }[]
-}
-
-// Verbosity = 3
-export interface GetDsProofListVerbosity3 extends GetDsProofListBase {
-  response: {
-    dspid: string;
-    txid: string | null;
-    outpoint: {
-      txid: string;
-      vout: number;
-    };
-    spenders: Spender[]
-  }[]
-}
-
-export interface GetDsProofScore {
-  method: 'getdsproofscore';
-  params: [
-    txid: string
-  ];
-  response: number;
-}
-
-export interface GetFinalizedBlockHash {
-  method: 'getfinalizedblockhash';
-  params: [];
-  response: string;
-}
-
-interface GetMempoolAncestorsBase {
-  method: 'getmempoolancestors';
-  params: [
-    txid: string,
-    verbose?: boolean | number
-  ];
-}
-
-// Verbosity 0 (false)
-export interface GetMempoolAncestorsVerbosity0 extends GetMempoolAncestorsBase {
-  params: [
-    txid: string,
-    verbose?: false | 0
-  ];
-  response: string[];
-}
-
-// Verbosity 1 (true)
-export interface GetMempoolAncestorsVerbosity1 extends GetMempoolAncestorsBase {
-  params: [
-    txid: string,
-    verbose?: true | 1
-  ];
-  response: {
-    [transactionid: string]: {
-      size: number;
-      time: number;
-      fees: {
-        base: number;
-        modified: number;
-      };
-      depends: string[];
-      spentby: string[];
-    };
-  };
-}
-
-interface GetMempoolDescendantsBase {
-  method: 'getmempooldescendants';
-  params: [
-    txid: string,
-    verbose?: boolean | number
-  ];
-}
-
-// Verbosity 0 (false)
-export interface GetMempoolDescendantsVerbosity0 extends GetMempoolDescendantsBase {
-  params: [
-    txid: string,
-    verbose?: false | 0
-  ];
-  response: string[];
-}
-
-// Verbosity 1 (true)
-export interface GetMempoolDescendantsVerbosity1 extends GetMempoolDescendantsBase {
-  params: [
-    txid: string,
-    verbose?: true | 1
-  ];
-  response: {
-    [transactionid: string]: {
-      size: number;
-      time: number;
-      fees: {
-        base: number;
-        modified: number;
-      };
-      depends: string[];
-      spentby: string[];
-    };
-  };
-}
-
-export interface GetMempoolEntry {
-  method: 'getmempoolentry';
-  params: [
-    txid: string
-  ];
-  response: {
-    size: number;
-    time: number;
-    fees: {
-      base: number;
-      modified: number;
-    };
-    depends: string[];
-    spentby: string[];
-  };
-}
-
-export interface GetMempoolInfo {
-  method: 'getmempoolinfo';
-  params: [];
-  response: {
-    loaded: boolean;
-    size: number;
-    bytes: number;
-    usage: number;
-    maxmempool: number;
-    mempoolminfee: number;
-    minrelaytxfee: number;
-  }
-}
-
-interface GetRawMempoolBase {
-  method: 'getrawmempool';
-  params: [
-    verbose?: boolean | number
-  ];
-}
-
-// Verbosity 0 (false)
-export interface GetRawMempoolVerbosity0 extends GetRawMempoolBase {
-  params: [
-    verbose?: false | 0
-  ];
-  response: string[];
-}
-
-// Verbosity 1 (true)
-export interface GetRawMempoolVerbosity1 extends GetRawMempoolBase {
-  params: [
-    verbose?: true | 1
-  ];
-  response: {
-    [transactionid: string]: {
-      size: number;
-      time: number;
-      fees: {
-        base: number;
-        modified: number;
-      };
-      depends: string[];
-      spentby: string[];
-    };
-  };
-}
-
-export interface GetTxOut {
-  method: 'gettxout';
-  params: [
-    txid: string,
-    vout: number,
-    include_mempool?: boolean
-  ];
-  response: {
-    bestblock: string;
-    confirmations: number
-    value: number;
-    scriptPubKey: {
-      asm: string;
-      hex: string;
-      type: string;
-      addresses: string[];
-    }
-    tokenData?: TokenData;
-    coinbase: boolean;
-  }
-}
-
-export interface GetTxOutProof {
-  method: 'gettxoutproof';
-  params: [
-    txids: string[],
-    blockhash?: string
-  ];
-  response: string;
-}
-
-
-export interface GetTxOutSetInfo {
-  method: 'gettxoutsetinfo';
-  params: [
-    txid: string
-  ];
-  response: {
-    height: number;
-    bestblock: string;
-    transactions: number;
-    txouts: number;
-    bogosize: number;
-    hash_serialized: string;
-    disk_size: number;
-    total_amount: number;
-  }
-}
-
-export interface InvalidateBlock {
-  method: 'invalidateblock';
-  params: [
-    blockhash: string
-  ];
-  response: null;
-}
-
-export interface ParkBlock {
-  method: 'parkblock';
-  params: [
-    blockhash: string
-  ];
-  response: null;
-}
-
-export interface PreciousBlock {
-  method: 'preciousblock';
-  params: [
-    blockhash: string
-  ];
-  response: null;
-}
-
-export interface PruneBlockchain {
-  method: 'pruneblockchain';
-  params: [
-    height: number
-  ];
-  response: number;
-}
-
-export interface ReconsiderBlock {
-  method: 'reconsiderblock';
-  params: [
-    blockhash: string
-  ];
-  response: null;
-}
-
-export interface SaveMempool {
-  method: 'savemempool';
-  params: [];
-  response: null;
-}
-
-export interface ScanTxOutSet {
-  method: 'scantxoutset';
-  params: [
-    action: 'start' | 'abort' | 'status',
-    scanobjects?: Array<string | {
-      desc: string;
-      range?: number;
-    }>
-  ];
-  response: {
-    unspents: Array<{
-      txid: string;
-      vout: number;
-      scriptPubKey: string;
-      amount: number;
-      height: number;
-      tokenData?: TokenData;
-    }>;
-    total_amount: number;
-    token_total_amount?: {
-      [category: string]: string;
-    };
-  } | boolean;
-}
-
-export interface UnparkBlock {
-  method: 'unparkblock';
-  params: [
-    blockhash: string
-  ];
-  response: null;
-}
-
-export interface VerifyChain {
-  method: 'verifychain';
-  params: [
-    checklevel?: number,
-    nblocks?: number
-  ];
-  response: boolean;
-}
-
-export interface VerifyTxOutProof {
-  method: 'verifytxoutproof';
-  params: [
-    proof: string
-  ];
-  response: string[];
+/* --- Blockchain Commands --- */
+// progress 33/33
+
+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: [];
+  response: string;
+}
+
+interface GetBlockBase {
+  method: 'getblock';
+  params: [
+    blockhash: string,
+    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,
+    verbosity?: 0 | false
+  ];
+  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: 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: 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;
+    height: number;
+    value: number;
+    scriptPubKey: {
+      asm: string;
+      hex: string;
+      type: 'nonstandard' | 'pubkey' | 'pubkeyhash' | 'scripthash' | 'multisig' | 'nulldata';
+      address?: string;
+    };
+    tokenData?: TokenData;
+  };
+}
+
+/** Transaction with prevout data on inputs (used by verbosity 3). */
+export interface TransactionWithPrevout extends Omit<Transaction, 'vin'> {
+  vin: TransactionInputWithPrevout[];  // Use the extended input type with `prevout`
+}
+
+/** 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: 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;
+    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: [];
+  response: {
+    chain: 'main' | 'test' | 'regtest';
+    blocks: number;
+    headers: number;
+    bestblockhash: string;
+    difficulty: number;
+    mediantime: number;
+    verificationprogress: number;
+    initialblockdownload: boolean;
+    chainwork: string;
+    size_on_disk: number;
+    pruned: boolean;
+    pruneheight: number;
+    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: [
+    height: number
+  ];
+  response: string;
+}
+
+export interface GetBlockHeaderBase {
+  method: 'getblockheader';
+  params: [
+    hash_or_height: string| number,
+    verbosity?: boolean | number
+  ];
+}
+
+/** Verbosity 0: Returns hex-encoded block header. */
+export interface GetBlockHeaderVerbosity0 extends GetBlockHeaderBase {
+  params: [
+    hash_or_height: string| number,
+    verbosity?: false | 0
+  ];
+  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: 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: [
+    hash_or_height: string| number,
+    stats?: string[]
+  ];
+  response: {
+    avgfee: number;
+    avgfeerate: number;
+    avgtxsize: number;
+    blockhash: string;
+    feerate_percentiles: {
+      "10th_percentile_feerate": number;
+      "25th_percentile_feerate": number;
+      "50th_percentile_feerate": number;
+      "75th_percentile_feerate": number;
+      "90th_percentile_feerate": number;
+    };
+    height: number;
+    ins: number;
+    maxfee: number;
+    maxfeerate: number;
+    maxtxsize: number;
+    medianfee: number;
+    mediantime: number;
+    mediantxsize: number;
+    minfee: number;
+    minfeerate: number;
+    mintxsize: number;
+    outs: number;
+    subsidy: number;
+    time: number;
+    total_out: number;
+    total_size: number;
+    totalfee: number;
+    txs: number;
+    utxo_increase: number;
+    utxo_size_inc: number;
+  }
+
+}
+
+/** Returns all known chain tips including forks. */
+export interface GetChainTips {
+  method: 'getchaintips';
+  params: [];
+  response: {
+    height: number
+    hash: string
+    branchlen:number
+    status: 'active' | 'parked' | 'headers-only' | 'valid-headers' | 'valid-fork' | 'active'
+  }[]
+}
+
+/** Returns transaction statistics over a block window. */
+export interface GetChainTxStats {
+  method: 'getchaintxstats';
+  params: [
+    nblocks?: number,
+    blockhash?: string
+  ];
+  response: {
+    time: number;
+    txcount: number;
+    window_final_block_hash: string;
+    window_block_count: number;
+    window_tx_count: number | undefined;
+    window_interval: number | undefined;
+    txrate: number;
+  }
+}
+
+/** Returns current network difficulty. */
+export interface GetDifficulty {
+  method: 'getdifficulty';
+  params: [];
+  response: number;
+}
+
+interface GetDsProofBase {
+  method: 'getdsproof';
+  params: [
+    dspid_or_txid_or_outpoint: string | { txid: string; vout: number },
+    verbosity?: number | boolean,
+    recursive?: boolean
+  ];
+}
+
+/** Verbosity 0: Double-spend proof as hex. */
+export interface GetDsProofVerbosity0 extends GetDsProofBase {
+  params: [
+    dspid_or_txid_or_outpoint: string | { txid: string; vout: number },
+    verbosity?: 0 | false,
+    recursive?: boolean
+  ];
+  response: {
+    hex: string;
+    txid: string | null;
+    path?: string[];  // Optional for recursive = true
+  };
+}
+
+/** Verbosity 1: Double-spend proof with descendants. */
+export interface GetDsProofVerbosity1 extends GetDsProofBase {
+  params: [
+    dspid_or_txid_or_outpoint: string | { txid: string; vout: number },
+    verbosity?: 1,
+    recursive?: boolean
+  ];
+  response: {
+    hex: string;
+    txid: string | null;
+    path?: string[];  // Optional for recursive = true
+    descendants?: string[]
+  };
+}
+
+/** Verbosity 2: Double-spend proof with parsed outpoint. */
+export interface GetDsProofVerbosity2 extends GetDsProofBase {
+  params: [
+    dspid_or_txid_or_outpoint: string | { txid: string; vout: number },
+    verbosity?: 2 | true,
+    recursive?: boolean
+  ];
+  response: {
+    dspid: string;
+    txid: string | null;
+    outpoint: {
+      txid: string;
+      vout: number;
+    };
+    descendants?: string[];
+    path?: string[];  // Optional for recursive = true
+  };
+}
+
+/** Double-spend proof spender data. */
+interface Spender {
+  txversion: number,
+  sequence: number,
+  locktime: number,
+  hashprevoutputs: string,
+  hashsequence: string,
+  hashoutputs: string,
+  pushdata: {
+    asm: string,
+    hex: string
+  }
+}
+
+/** Verbosity 3: Double-spend proof with full spender details. */
+export interface GetDsProofVerbosity3 extends GetDsProofVerbosity2 {
+  response: {
+    dspid: string;
+    txid: string | null;
+    outpoint: {
+      txid: string;
+      vout: number;
+    };
+    spenders: Spender[];
+    descendants?: string[];
+    path?: string[];  // Optional for recursive = true
+  };
+}
+
+export interface GetDsProofListBase {
+  method: 'getdsprooflist';
+  params: [
+    verbosity?: number | boolean,
+    include_orphans?: boolean
+  ];
+}
+
+/** Verbosity 0: List of double-spend proof IDs. */
+export interface GetDsProofListVerbosity0 extends GetDsProofListBase {
+  params: [
+    verbosity?: 0 | false,
+    include_orphans?: boolean
+  ];
+  response: string[]
+}
+
+/** Verbosity 1: List of double-spend proofs as hex with txid. */
+export interface GetDsProofListVerbosity1 extends GetDsProofListBase {
+  params: [
+    verbosity?: 1,
+    include_orphans?: boolean
+  ];
+  response: {
+    hex: string;
+    txid: string | null;
+  }[]
+}
+
+/** Verbosity 2: List of double-spend proofs with parsed outpoints. */
+export interface GetDsProofListVerbosity2 extends GetDsProofListBase {
+  params: [
+    verbosity?: 2 | true,
+    include_orphans?: boolean
+  ];
+  response: {
+    dspid: string;
+    txid: string | null;
+    outpoint: {
+      txid: string;
+      vout: number;
+    };
+  }[]
+}
+
+/** Verbosity 3: List of double-spend proofs with full spender details. */
+export interface GetDsProofListVerbosity3 extends GetDsProofListBase {
+  response: {
+    dspid: string;
+    txid: string | null;
+    outpoint: {
+      txid: string;
+      vout: number;
+    };
+    spenders: Spender[]
+  }[]
+}
+
+/** Returns double-spend proof score for a transaction. */
+export interface GetDsProofScore {
+  method: 'getdsproofscore';
+  params: [
+    txid: string
+  ];
+  response: number;
+}
+
+/** Returns the hash of the last finalized block. */
+export interface GetFinalizedBlockHash {
+  method: 'getfinalizedblockhash';
+  params: [];
+  response: string;
+}
+
+interface GetMempoolAncestorsBase {
+  method: 'getmempoolancestors';
+  params: [
+    txid: string,
+    verbose?: boolean | number
+  ];
+}
+
+/** Verbosity 0: Returns ancestor txids as array. */
+export interface GetMempoolAncestorsVerbosity0 extends GetMempoolAncestorsBase {
+  params: [
+    txid: string,
+    verbose?: false | 0
+  ];
+  response: string[];
+}
+
+/** Verbosity 1: Returns ancestor txids with detailed mempool info. */
+export interface GetMempoolAncestorsVerbosity1 extends GetMempoolAncestorsBase {
+  params: [
+    txid: string,
+    verbose?: true | 1
+  ];
+  response: {
+    [transactionid: string]: {
+      size: number;
+      time: number;
+      fees: {
+        base: number;
+        modified: number;
+      };
+      depends: string[];
+      spentby: string[];
+    };
+  };
+}
+
+interface GetMempoolDescendantsBase {
+  method: 'getmempooldescendants';
+  params: [
+    txid: string,
+    verbose?: boolean | number
+  ];
+}
+
+/** Verbosity 0: Returns descendant txids as array. */
+export interface GetMempoolDescendantsVerbosity0 extends GetMempoolDescendantsBase {
+  params: [
+    txid: string,
+    verbose?: false | 0
+  ];
+  response: string[];
+}
+
+/** Verbosity 1: Returns descendant txids with detailed mempool info. */
+export interface GetMempoolDescendantsVerbosity1 extends GetMempoolDescendantsBase {
+  params: [
+    txid: string,
+    verbose?: true | 1
+  ];
+  response: {
+    [transactionid: string]: {
+      size: number;
+      time: number;
+      fees: {
+        base: number;
+        modified: number;
+      };
+      depends: string[];
+      spentby: string[];
+    };
+  };
+}
+
+/** Returns mempool entry for a specific transaction. */
+export interface GetMempoolEntry {
+  method: 'getmempoolentry';
+  params: [
+    txid: string
+  ];
+  response: {
+    size: number;
+    time: number;
+    fees: {
+      base: number;
+      modified: number;
+    };
+    depends: string[];
+    spentby: string[];
+  };
+}
+
+/** Returns mempool statistics and configuration. */
+export interface GetMempoolInfo {
+  method: 'getmempoolinfo';
+  params: [];
+  response: {
+    loaded: boolean;
+    size: number;
+    bytes: number;
+    usage: number;
+    maxmempool: number;
+    mempoolminfee: number;
+    minrelaytxfee: number;
+    permitbaremultisig: boolean;
+    maxdatacarriersize: number;
+  }
+}
+
+interface GetRawMempoolBase {
+  method: 'getrawmempool';
+  params: [
+    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
+  ];
+  response: {
+    [transactionid: string]: {
+      size: number;
+      time: number;
+      fees: {
+        base: number;
+        modified: number;
+      };
+      depends: string[];
+      spentby: string[];
+    };
+  };
+}
+
+/** Returns details about an unspent transaction output. */
+export interface GetTxOut {
+  method: 'gettxout';
+  params: [
+    txid: string,
+    vout: number,
+    include_mempool?: boolean
+  ];
+  response: {
+    bestblock: string;
+    confirmations: number
+    value: number;
+    scriptPubKey: {
+      asm: string;
+      hex: string;
+      type: string;
+      addresses: string[];
+    }
+    tokenData?: TokenData;
+    coinbase: boolean;
+  }
+}
+
+/** Returns a merkle proof that transaction(s) are in a block. */
+export interface GetTxOutProof {
+  method: 'gettxoutproof';
+  params: [
+    txids: string[],
+    blockhash?: string
+  ];
+  response: string;
+}
+
+/** Returns UTXO set statistics. */
+export interface GetTxOutSetInfo {
+  method: 'gettxoutsetinfo';
+  params: [
+    hash_type?: 'hash_serialized_3' | 'ecmh' | 'muhash',
+    hash_or_height?: string | number,
+    use_index?: boolean
+  ];
+  response: {
+    height: number;
+    bestblock: string;
+    transactions: number;
+    txouts: number;
+    bogosize: number;
+    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: [
+    blockhash: string
+  ];
+  response: null;
+}
+
+/** Marks a block as parked (temporarily invalid). */
+export interface ParkBlock {
+  method: 'parkblock';
+  params: [
+    blockhash: string
+  ];
+  response: null;
+}
+
+/** Treats a block as if it were received before others with same work. */
+export interface PreciousBlock {
+  method: 'preciousblock';
+  params: [
+    blockhash: string
+  ];
+  response: null;
+}
+
+/** Prunes blockchain up to specified height. Returns height of last pruned block. */
+export interface PruneBlockchain {
+  method: 'pruneblockchain';
+  params: [
+    height: number
+  ];
+  response: number;
+}
+
+/** Removes invalidity status from a block and its descendants. */
+export interface ReconsiderBlock {
+  method: 'reconsiderblock';
+  params: [
+    blockhash: string
+  ];
+  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: [
+    action: 'start' | 'abort' | 'status',
+    scanobjects?: Array<string | {
+      desc: string;
+      range?: number;
+    }>
+  ];
+  response: {
+    unspents: Array<{
+      txid: string;
+      vout: number;
+      scriptPubKey: string;
+      amount: number;
+      height: number;
+      tokenData?: TokenData;
+    }>;
+    total_amount: number;
+    token_total_amount?: {
+      [category: string]: string;
+    };
+  } | boolean;
+}
+
+/** Removes parked status from a block and its descendants. */
+export interface UnparkBlock {
+  method: 'unparkblock';
+  params: [
+    blockhash: string
+  ];
+  response: null;
+}
+
+/** Verifies blockchain database. */
+export interface VerifyChain {
+  method: 'verifychain';
+  params: [
+    checklevel?: number,
+    nblocks?: number
+  ];
+  response: boolean;
+}
+
+/** Verifies a merkle proof and returns the txids it commits to. */
+export interface VerifyTxOutProof {
+  method: 'verifytxoutproof';
+  params: [
+    proof: string
+  ];
+  response: string[];
 }