methods-spec.md

Method Reference

Methods are sorted alphabetically. Each method documents its parameters, return values, and possible errors.

btck_block_copy

Copies a block.

Parameters:

• block (reference, required): Block reference

Result: Reference - Contains the copied block (e.g., {"ref": "$block_copy"})

Error: null (cannot return error)

---

btck_block_count_transactions

Returns the number of transactions in a block.

Parameters:

• block (reference, required): Block reference

Result: Integer - The transaction count

Error: null (cannot return error)

---

btck_block_create

Creates a block object from raw block data.

Parameters:

• raw_block (string, required): Hex-encoded raw block data

Result: Reference - Contains the created block (e.g., {"ref": "$block"})

Error: {} when operation fails

---

btck_block_destroy

Destroys a block.

Parameters:

• block (reference, required): Block reference to destroy

Result: null (void operation)

Error: null (cannot return error)

---

btck_block_get_hash

Gets the hash of a block.

Parameters:

• block (reference, required): Block reference

Result: Reference - Contains the returned block hash (e.g., {"ref": "$block_hash"})

Error: null (cannot return error)

---

btck_block_get_header

Gets the block header from a block.

Parameters:

• block (reference, required): Block reference

Result: Reference - Contains the returned block header (e.g., {"ref": "$header"}). The returned block header reference depends on the lifetime of the parent block and does not require an explicit destroy call.

Error: null (cannot return error)

---

btck_block_get_transaction_at

Retrieves the transaction at the given index from a block.

Parameters:

• block (reference, required): Block reference
• transaction_index (integer, required): Zero-based transaction index

Result: Reference - Contains the returned transaction (e.g., {"ref": "$transaction"}). The returned transaction reference depends on the lifetime of the parent block and does not require an explicit destroy call.

Error: null (cannot return error)

---

btck_block_hash_copy

Copies a block hash.

Parameters:

• block_hash (reference, required): Block hash reference

Result: Reference - Contains the copied block hash (e.g., {"ref": "$block_hash_copy"})

Error: null (cannot return error)

---

btck_block_hash_create

Creates a block hash object from raw 32-byte block hash data.

Parameters:

• block_hash (string, required): Hex-encoded raw 32-byte block hash data

Result: Reference - Contains the created block hash (e.g., {"ref": "$block_hash"})

Error: null (cannot return error)

---

btck_block_hash_destroy

Destroys a block hash.

Parameters:

• block_hash (reference, required): Block hash reference to destroy

Result: null (void operation)

Error: null (cannot return error)

---

btck_block_hash_equals

Checks if two block hashes are equal.

Parameters:

• hash1 (reference, required): First block hash reference
• hash2 (reference, required): Second block hash reference

Result: Boolean - true if the hashes are equal

Error: null (cannot return error)

---

btck_block_hash_to_bytes

Returns the raw 32-byte block hash as a hex string.

Parameters:

• block_hash (reference, required): Block hash reference

Result: String - Hex-encoded raw 32-byte block hash data

Error: null (cannot return error)

---

btck_block_header_copy

Copies a block header.

Parameters:

• header (reference, required): Block header reference

Result: Reference - Contains the copied block header (e.g., {"ref": "$header_copy"})

Error: null (cannot return error)

---

btck_block_header_create

Creates a block header object from raw serialized header data.

Parameters:

• raw_block_header (string, required): Hex-encoded raw block header data. At least 80 bytes are required; if additional bytes are provided, only the first 80 bytes are used to create the header.

Result: Reference - Contains the created block header (e.g., {"ref": "$header"})

Error: {} if fewer than 80 bytes are provided for the serialized block header

---

btck_block_header_destroy

Destroys a block header.

Parameters:

• header (reference, required): Block header reference to destroy

Result: null (void operation)

Error: null (cannot return error)

---

btck_block_header_get_bits

Gets the nBits difficulty target of a block header.

Parameters:

• header (reference, required): Block header reference

Result: Integer - The nBits value

Error: null (cannot return error)

---

btck_block_header_get_hash

Gets the hash of a block header.

Parameters:

• header (reference, required): Block header reference

Result: Reference - Contains the returned block hash (e.g., {"ref": "$block_hash"})

Error: null (cannot return error)

---

btck_block_header_get_nonce

Gets the nonce of a block header.

Parameters:

• header (reference, required): Block header reference

Result: Integer - The nonce value

Error: null (cannot return error)

---

btck_block_header_get_prev_hash

Gets the previous block hash from a block header.

Parameters:

• header (reference, required): Block header reference

Result: Reference - Contains the returned previous block hash (e.g., {"ref": "$prev_hash"}). The returned block hash reference depends on the lifetime of the parent block header and does not require an explicit destroy call.

Error: null (cannot return error)

---

btck_block_header_get_timestamp

Gets the timestamp of a block header.

Parameters:

• header (reference, required): Block header reference

Result: Integer - The block timestamp as a Unix timestamp

Error: null (cannot return error)

---

btck_block_header_get_version

Gets the version field of a block header.

Parameters:

• header (reference, required): Block header reference

Result: Integer - The block version

Error: null (cannot return error)

---

btck_block_header_to_bytes

Returns the consensus-serialized block header as a hex string.

Parameters:

• header (reference, required): Block header reference

Result: String - Hex-encoded consensus serialization of the block header

Error: {} when operation fails

---

btck_block_to_bytes

Returns the consensus-serialized block as a hex string.

Parameters:

• block (reference, required): Block reference

Result: String - Hex-encoded consensus serialization of the block

Error: {} when operation fails

---

btck_block_tree_entry_get_block_hash

Gets the block hash from a block tree entry.

Parameters:

• block_tree_entry (reference, required): Block tree entry reference

Result: Reference - Contains the returned block hash (e.g., {"ref": "$block_hash"}). The returned block hash reference is a view that depends on the lifetime of the parent block tree entry and does not require an explicit destroy call.

Error: null (cannot return error)

---

btck_chain_contains

Checks whether a block tree entry is part of the active chain.

Parameters:

• chain (reference, required): Chain reference
• block_tree_entry (reference, required): Block tree entry reference to check

Result: Boolean - true if block is in the active chain, false otherwise

Error: null (cannot return error)

---

btck_chain_get_by_height

Retrieves a block tree entry at a specific height in the chain.

Parameters:

• chain (reference, required): Chain reference
• block_height (integer, required): Height to query

Result: Reference - Contains the returned block tree entry (e.g., {"ref": "$block_tree_entry"}). The returned block tree entry reference depends on the lifetime of the parent chain reference and does not require an explicit destroy call.

Error: {} if the requested height is out of bounds

---

btck_chain_get_height

Gets the current height of the active chain.

Parameters:

• chain (reference, required): Chain reference

Result: Integer - The chain height (0 = genesis)

Error: null (cannot return error)

---

btck_chainstate_manager_create

Creates a chainstate manager from a context.

Parameters:

• context (reference, required): Context reference

Result: Reference - Contains the created chainstate manager (e.g., {"ref": "$chainstate_manager"})

Error: {} when operation fails

---

btck_chainstate_manager_destroy

Destroys a chainstate manager and frees associated resources.

Parameters:

• chainstate_manager (reference, required): Chainstate manager reference to destroy

Result: null (void operation)

Error: null (cannot return error)

---

btck_chainstate_manager_get_active_chain

Retrieves the currently active chain from the chainstate manager.

Parameters:

• chainstate_manager (reference, required): Chainstate manager reference

Result: Reference - Contains the returned active chain (e.g., {"ref": "$chain"}). The returned chain reference depends on the lifetime of the parent chainstate manager and does not require an explicit destroy call.

Error: null (cannot return error)

---

btck_chainstate_manager_process_block

Processes a block through validation checks, disk storage, and UTXO set validation; successful processing does not indicate block validity.

Parameters:

• chainstate_manager (reference, required): Chainstate manager reference
• block (reference, required): Block reference

Result: Object containing:

• new_block (boolean): true if this block was not processed before, false otherwise

Error: {} when operation fails

---

btck_context_create

Creates a context with specified chain parameters.

Parameters:

• chain_parameters (object, required)
  • chain_type (string, required): Chain type. Allowed values:
    • btck_ChainType_MAINNET
    • btck_ChainType_TESTNET
    • btck_ChainType_TESTNET_4
    • btck_ChainType_SIGNET
    • btck_ChainType_REGTEST

Result: Reference - Contains the created context (e.g., {"ref": "$context"})

Error: {} when operation fails

---

btck_context_destroy

Destroys a context and frees associated resources.

Parameters:

• context (reference, required): Context reference to destroy

Result: null (void operation)

Error: null (cannot return error)

---

btck_precomputed_transaction_data_create

Creates precomputed transaction data for script verification. Precomputed data is reusable when verifying multiple inputs of the same transaction.

Parameters:

• tx_to (reference, required): Transaction reference
• spent_outputs (array of references, optional): Array of TransactionOutput references. Required when btck_ScriptVerificationFlags_TAPROOT is set

Result: Reference - Contains the created precomputed transaction data (e.g., {"ref": "$precomputed_txdata"})

Error: {} when operation fails

---

btck_precomputed_transaction_data_destroy

Destroys precomputed transaction data and frees associated resources.

Parameters:

• precomputed_txdata (reference, required): Precomputed transaction data reference to destroy

Result: null (void operation)

Error: null (cannot return error)

---

btck_script_pubkey_copy

Copies a script pubkey.

Parameters:

• script_pubkey (reference, required): Script pubkey reference

Result: Reference - Contains the copied script pubkey (e.g., {"ref": "$script_pubkey_copy"})

Error: null (cannot return error)

---

btck_script_pubkey_create

Creates a script pubkey object from hex-encoded data.

Parameters:

• script_pubkey (string, required): Hex-encoded script pubkey data

Result: Reference - Contains the created script pubkey (e.g., {"ref": "$script_pubkey"})

Error: null (cannot return error)

---

btck_script_pubkey_destroy

Destroys a script pubkey and frees associated resources.

Parameters:

• script_pubkey (reference, required): Script pubkey reference to destroy

Result: null (void operation)

Error: null (cannot return error)

---

btck_script_pubkey_to_bytes

Serializes a script pubkey to raw bytes encoded as hex.

Parameters:

• script_pubkey (reference, required): Script pubkey reference

Result: String - Hex-encoded serialized script pubkey bytes

Error: {} when operation fails

---

btck_script_pubkey_verify

Verifies a script pubkey against spending conditions.

Parameters:

• script_pubkey (reference, required): ScriptPubkey reference
• amount (number, required): Amount of the script pubkey's associated output. May be zero if the witness flag is not set
• tx_to (reference, required): Transaction reference
• precomputed_txdata (reference, optional): PrecomputedTransactionData reference. Required when the taproot flag is set
• input_index (number, required): Index of the input in tx_to spending the script_pubkey
• flags (array of strings, required): Script verification flags controlling validation constraints. Allowed values:
  • btck_ScriptVerificationFlags_NONE
  • btck_ScriptVerificationFlags_P2SH
  • btck_ScriptVerificationFlags_DERSIG
  • btck_ScriptVerificationFlags_NULLDUMMY
  • btck_ScriptVerificationFlags_CHECKLOCKTIMEVERIFY
  • btck_ScriptVerificationFlags_CHECKSEQUENCEVERIFY
  • btck_ScriptVerificationFlags_WITNESS
  • btck_ScriptVerificationFlags_TAPROOT

Result: Boolean - true if script is valid, false if invalid

Error: On error, returns {"code": {"type": "btck_ScriptVerifyStatus", "member": ...}} where member can be one of:

• ERROR_INVALID_FLAGS_COMBINATION - Invalid or inconsistent verification flags were provided. This occurs when the supplied script_verify_flags combination violates internal consistency rules.
• ERROR_SPENT_OUTPUTS_REQUIRED - Spent outputs are required but were not provided (e.g., for Taproot verification).

---

btck_transaction_copy

Copies a transaction.

Parameters:

• transaction (reference, required): Transaction reference

Result: Reference - Contains the copied transaction (e.g., {"ref": "$transaction_copy"})

Error: null (cannot return error)

---

btck_transaction_count_inputs

Returns the number of inputs in a transaction.

Parameters:

• transaction (reference, required): Transaction reference

Result: Integer - The input count

Error: null (cannot return error)

---

btck_transaction_count_outputs

Returns the number of outputs in a transaction.

Parameters:

• transaction (reference, required): Transaction reference

Result: Integer - The output count

Error: null (cannot return error)

---

btck_transaction_create

Creates a transaction object from raw hex-encoded transaction data.

Parameters:

• raw_transaction (string, required): Hex-encoded raw transaction data

Result: Reference - Contains the created transaction (e.g., {"ref": "$transaction"})

Error: {} when operation fails

---

btck_transaction_destroy

Destroys a transaction.

Parameters:

• transaction (reference, required): Transaction reference to destroy

Result: null (void operation)

Error: null (cannot return error)

---

btck_transaction_get_input_at

Retrieves the input at the given index from a transaction.

Parameters:

• transaction (reference, required): Transaction reference
• input_index (integer, required): Zero-based input index

Result: Reference - Contains the returned transaction input (e.g., {"ref": "$transaction_input"}). The returned transaction input reference is a view that depends on the lifetime of the parent transaction and does not require an explicit destroy call.

Error: null (cannot return error)

---

btck_transaction_get_output_at

Retrieves the output at the given index from a transaction.

Parameters:

• transaction (reference, required): Transaction reference
• output_index (integer, required): Zero-based output index

Result: Reference - Contains the returned transaction output (e.g., {"ref": "$transaction_output"}). The returned transaction output reference is a view that depends on the lifetime of the parent transaction and does not require an explicit destroy call.

Error: null (cannot return error)

---

btck_transaction_get_txid

Gets the txid of a transaction.

Parameters:

• transaction (reference, required): Transaction reference or transaction view reference

Result: Reference - Contains the returned txid (e.g., {"ref": "$txid"}). The returned txid reference is a view that depends on the lifetime of the parent transaction and does not require an explicit destroy call.

Error: null (cannot return error)

---

btck_transaction_input_copy

Copies a transaction input.

Parameters:

• transaction_input (reference, required): Transaction input reference

Result: Reference - Contains the copied transaction input (e.g., {"ref": "$transaction_input_copy"})

Error: null (cannot return error)

---

btck_transaction_input_destroy

Destroys a transaction input.

Parameters:

• transaction_input (reference, required): TransactionInput reference to destroy

Result: null (void operation)

Error: null (cannot return error)

---

btck_transaction_input_get_out_point

Gets the out point from a transaction input.

Parameters:

• transaction_input (reference, required): Transaction input reference

Result: Reference - Contains the returned transaction out point (e.g., {"ref": "$transaction_out_point"}). The returned transaction out point reference is a view that depends on the lifetime of the parent transaction input and does not require an explicit destroy call.

Error: null (cannot return error)

---

btck_transaction_out_point_copy

Copies a transaction out point.

Parameters:

• transaction_out_point (reference, required): Transaction out point reference

Result: Reference - Contains the copied transaction out point (e.g., {"ref": "$transaction_out_point_copy"})

Error: null (cannot return error)

---

btck_transaction_out_point_destroy

Destroys a transaction out point.

Parameters:

• transaction_out_point (reference, required): Transaction out point reference to destroy

Result: null (void operation)

Error: null (cannot return error)

---

btck_transaction_out_point_get_index

Gets the output index from a transaction out point.

Parameters:

• transaction_out_point (reference, required): Transaction out point reference

Result: Integer - The output index

Error: null (cannot return error)

---

btck_transaction_out_point_get_txid

Gets the txid from a transaction out point.

Parameters:

• transaction_out_point (reference, required): Transaction out point reference

Result: Reference - Contains the returned txid (e.g., {"ref": "$txid"}). The returned txid reference is a view that depends on the lifetime of the parent transaction out point and does not require an explicit destroy call.

Error: null (cannot return error)

---

btck_transaction_output_copy

Copies a transaction output.

Parameters:

• transaction_output (reference, required): Transaction output reference

Result: Reference - Contains the copied transaction output (e.g., {"ref": "$transaction_output_copy"})

Error: null (cannot return error)

---

btck_transaction_output_create

Creates a transaction output from a script pubkey reference and amount.

Parameters:

• script_pubkey (reference, required): ScriptPubkey reference
• amount (number, required): Amount in satoshis

Result: Reference - Contains the created transaction output (e.g., {"ref": "$transaction_output"})

Error: null (cannot return error)

---

btck_transaction_output_destroy

Destroys a transaction output.

Parameters:

• transaction_output (reference, required): Transaction output reference to destroy

Result: null (void operation)

Error: null (cannot return error)

---

btck_transaction_output_get_amount

Gets the amount in satoshis from a transaction output.

Parameters:

• transaction_output (reference, required): Transaction output reference

Result: Integer - The amount in satoshis

Error: null (cannot return error)

---

btck_transaction_output_get_script_pubkey

Gets the script pubkey of a transaction output.

Parameters:

• transaction_output (reference, required): Transaction output reference

Result: Reference - Contains the returned script pubkey (e.g., {"ref": "$script_pubkey"}). The returned script pubkey reference is a view that depends on the lifetime of the parent transaction output and does not require an explicit destroy call.

Error: null (cannot return error)

---

btck_transaction_to_bytes

Returns the consensus-serialized transaction as a hex string.

Parameters:

• transaction (reference, required): Transaction reference

Result: String - Hex-encoded consensus serialization of the transaction

Error: {} when operation fails

---

btck_txid_copy

Copies a txid.

Parameters:

• txid (reference, required): Txid reference

Result: Reference - Contains the copied txid (e.g., {"ref": "$txid_copy"})

Error: null (cannot return error)

---

btck_txid_destroy

Destroys a txid.

Parameters:

• txid (reference, required): Txid reference to destroy

Result: null (void operation)

Error: null (cannot return error)

---

btck_txid_equals

Checks if two txids are equal.

Parameters:

• txid1 (reference, required): First txid reference
• txid2 (reference, required): Second txid reference

Result: Boolean - true if the txids are equal

Error: null (cannot return error)

---

btck_txid_to_bytes

Returns the txid as raw bytes encoded as hex.

Parameters:

• txid (reference, required): Txid reference

Result: String - Hex-encoded raw 32-byte txid

Error: null (cannot return error)