@secondlayer/stacks 2.8.1 → 2.9.0

package/dist/src/bitcoin/index.d.cts

@@ -0,0 +1,743 @@
+type IntCV = {
+	readonly type: "int"
+	readonly value: bigint
+};
+type UIntCV = {
+	readonly type: "uint"
+	readonly value: bigint
+};
+type BooleanCV = TrueCV | FalseCV;
+type TrueCV = {
+	readonly type: "true"
+};
+type FalseCV = {
+	readonly type: "false"
+};
+type BufferCV = {
+	readonly type: "buffer"
+	readonly value: string
+};
+type NoneCV = {
+	readonly type: "none"
+};
+type SomeCV = {
+	readonly type: "some"
+	readonly value: ClarityValue
+};
+type ResponseOkCV = {
+	readonly type: "ok"
+	readonly value: ClarityValue
+};
+type ResponseErrorCV = {
+	readonly type: "err"
+	readonly value: ClarityValue
+};
+type StandardPrincipalCV = {
+	readonly type: "address"
+	readonly value: string
+};
+type ContractPrincipalCV = {
+	readonly type: "contract"
+	readonly value: string
+};
+type ListCV = {
+	type: "list"
+	value: ClarityValue[]
+};
+type TupleData = {
+	[key: string]: ClarityValue
+};
+type TupleCV = {
+	type: "tuple"
+	value: TupleData
+};
+type StringAsciiCV = {
+	readonly type: "ascii"
+	readonly value: string
+};
+type StringUtf8CV = {
+	readonly type: "utf8"
+	readonly value: string
+};
+type ClarityValue = IntCV | UIntCV | BooleanCV | BufferCV | NoneCV | SomeCV | ResponseOkCV | ResponseErrorCV | StandardPrincipalCV | ContractPrincipalCV | ListCV | TupleCV | StringAsciiCV | StringUtf8CV;
+/**
+* Bitcoin double-SHA256: `sha256(sha256(bytes))`. This is the hash Bitcoin uses
+* for txids, block headers, and merkle nodes — NOT the same as the Stacks
+* `txidFromBytes` (which uses sha512_256), so it lives here, not in `utils/hash`.
+*/
+declare function doubleSha256(bytes: Uint8Array): Uint8Array;
+/**
+* Reverse a byte array. Bitcoin hashes are computed and stored in *internal*
+* (little-endian) order but *displayed* big-endian, so the two differ by a
+* reversal. The SIP-044 built-ins consume internal order; only reverse for
+* display / when matching an explorer value.
+*/
+declare function reverseBytes(bytes: Uint8Array): Uint8Array;
+/**
+* A little-endian, varint-aware byte reader for Bitcoin serialization. The
+* shared `utils/BytesReader` is big-endian only; Bitcoin tx fields are
+* little-endian with compact-size (varint) length prefixes.
+*/
+declare class BtcReader {
+	private readonly data;
+	private readonly view;
+	offset: number;
+	constructor(data: Uint8Array);
+	get length(): number;
+	readUInt8(): number;
+	/** Read the next byte without advancing. */
+	peekUInt8(): number;
+	readUInt32LE(): number;
+	readUInt64LE(): bigint;
+	readBytes(n: number): Uint8Array;
+	/** Read a Bitcoin compact-size unsigned integer (varint). */
+	readVarInt(): number;
+}
+interface BitcoinTxInput {
+	/** Previous output txid, in serialized (internal) byte order. */
+	prevTxid: Uint8Array;
+	vout: number;
+	scriptSig: Uint8Array;
+	sequence: number;
+}
+interface BitcoinTxOutput {
+	/** Output value in satoshis. */
+	value: bigint;
+	scriptPubKey: Uint8Array;
+}
+interface ParsedBitcoinTx {
+	version: number;
+	hasWitness: boolean;
+	inputs: BitcoinTxInput[];
+	outputs: BitcoinTxOutput[];
+	locktime: number;
+	/**
+	* The legacy txid as the raw double-SHA256 in *internal* byte order — ready
+	* to pass as the leaf to `verify-merkle-proof`. Witness data is excluded
+	* (the txid is computed over the legacy serialization), so this is stable for
+	* both legacy and SegWit txs. Use `reverseBytes` for the displayed form.
+	*/
+	txidInternal: Uint8Array;
+}
+/** Parse a serialized Bitcoin tx (legacy or SegWit) into its fields + txid. */
+declare function parseBitcoinTx(rawTx: Uint8Array): ParsedBitcoinTx;
+/**
+* Return the legacy (witness-stripped) serialization of a tx. For a legacy tx
+* this is the input unchanged; for a SegWit tx the marker, flag, and witness
+* stack are removed. This is the byte string the txid is hashed over.
+*/
+declare function stripWitness(rawTx: Uint8Array): Uint8Array;
+/**
+* Compute a tx's id from its raw serialization. Internal byte order by default
+* (the merkle leaf / built-in input); pass `{ display: true }` for the
+* explorer-style big-endian form.
+*/
+declare function bitcoinTxid(rawTx: Uint8Array, { display }?: {
+	display?: boolean
+}): Uint8Array;
+interface BlockHeader {
+	version: number;
+	/** Previous block hash, internal byte order. */
+	prevBlock: Uint8Array;
+	/** Merkle root, internal byte order — pairs with `verify-merkle-proof`. */
+	merkleRoot: Uint8Array;
+	timestamp: number;
+	bits: number;
+	nonce: number;
+}
+/** Parse an 80-byte Bitcoin block header into its fields (hashes internal order). */
+declare function parseBlockHeader(header: Uint8Array): BlockHeader;
+/**
+* Hash an 80-byte block header (double-SHA256). Internal byte order by default;
+* `{ display: true }` for the explorer-style block hash.
+*/
+declare function blockHash(header: Uint8Array, { display }?: {
+	display?: boolean
+}): Uint8Array;
+/**
+* A Bitcoin merkle inclusion proof, shaped for the SIP-044 `verify-merkle-proof`
+* built-in: `(leaf-hash, root-hash, tx-index, tx-count, sibling-hashes)`.
+*
+* - `siblings` are the sibling node hashes from the leaf up to (excluding) the
+*   root, in *internal* byte order — never reversed.
+* - `txCount` (not tree-depth) pins the canonical tree shape; the built-in
+*   rejects any proof whose length differs from `ceil(log2(tx-count))`.
+*/
+interface MerkleProof {
+	siblings: Uint8Array[];
+	txIndex: number;
+	txCount: number;
+}
+/**
+* Compute the merkle root over txids in *internal* byte order. The result is
+* also internal order — it matches the `merkle-root` field read straight out of
+* an 80-byte block header, so it can be cross-checked against the header before
+* a proof is trusted.
+*/
+declare function merkleRoot2(txidsInternal: Uint8Array[]): Uint8Array;
+/**
+* Build the merkle inclusion proof for the tx at `txIndex`. Sibling count is
+* exactly `ceil(log2(txCount))`, as the SIP-044 built-in requires.
+*/
+declare function buildMerkleProof(txidsInternal: Uint8Array[], txIndex: number): MerkleProof;
+/**
+* Recompute the merkle root from a leaf + its proof — the same fold the on-chain
+* `verify-merkle-proof` performs. Use it off-chain to self-check a constructed
+* proof against the header's merkle root before submitting a contract call.
+*/
+declare function rootFromProof(leafInternal: Uint8Array, proof: MerkleProof): Uint8Array;
+/**
+* A self-contained Bitcoin SPV proof: everything the SIP-044 built-ins need to
+* prove a tx (and one of its outputs) is committed in a confirmed block. Hashes
+* are internal byte order throughout.
+*/
+interface SpvProof {
+	rawTx: Uint8Array;
+	/** The tx's txid, internal order — the merkle leaf. */
+	txidInternal: Uint8Array;
+	/** Output index of interest, if the proof targets a specific output. */
+	vout?: number;
+	merkle: MerkleProof;
+	/** The 80-byte block header that commits the tx. */
+	header: Uint8Array;
+	/** Bitcoin block height. */
+	height: number;
+}
+/** The block context a `ProofSource` resolves for a confirmed tx. */
+interface BlockForTx {
+	/** 80-byte block header. */
+	header: Uint8Array;
+	height: number;
+	/** All of the block's txids, internal order, in block order. */
+	txidsInternal: Uint8Array[];
+	/** Index of the target tx within the block. */
+	txIndex: number;
+}
+/**
+* Where proof inputs come from. The default is the integrator's own Bitcoin node
+* (`bitcoinRpcSource`) — trustless; a hosted Esplora-compatible endpoint
+* (`esploraSource`) is the fallback. `buildTxProof` independently re-checks
+* whatever a source returns, so a wrong or hostile source fails loudly rather
+* than producing a bad proof.
+*/
+interface ProofSource {
+	/** Raw (serialized) tx bytes for a txid (display-order hex). */
+	getRawTx(txid: string): Promise<Uint8Array>;
+	/** The confirming block's header, height, and txid set for a txid. */
+	getBlockForTx(txid: string): Promise<BlockForTx>;
+}
+/**
+* Assemble an `SpvProof` for a txid from a `ProofSource`, validating every claim
+* the source makes:
+*  - the returned raw tx actually hashes to the requested txid,
+*  - the claimed `txIndex` points at that txid in the block, and
+*  - the resulting merkle proof folds back to the block header's merkle root.
+* Any mismatch throws — the proof is never returned half-trusted.
+*/
+declare function buildTxProof(source: ProofSource, params: {
+	txid: string
+	vout?: number
+}): Promise<SpvProof>;
+/**
+* Compose sources into an ordered fallback chain: each call tries them in turn
+* and returns the first success, throwing the last error if all fail. Put the
+* trustless integrator node first and a hosted endpoint last.
+*/
+declare function fallbackProofSource(sources: ProofSource[]): ProofSource;
+interface BitcoinRpcConfig {
+	/** Bitcoin Core JSON-RPC endpoint URL. */
+	url: string;
+	/** Basic auth — `{ username, password }` or a pre-encoded base64 string. */
+	auth?: {
+		username: string
+		password: string
+	} | string;
+	/** Override the fetch implementation (testing / custom agents). */
+	fetch?: typeof fetch;
+}
+/**
+* A `ProofSource` backed by the integrator's own Bitcoin Core node over
+* JSON-RPC. This is the trustless default. The node must run with `-txindex`
+* (or the tx must be in the mempool's block view) so `getrawtransaction` can
+* resolve the confirming block.
+*/
+declare function bitcoinRpcSource(config: BitcoinRpcConfig): ProofSource;
+interface EsploraConfig {
+	/** Esplora REST base URL, e.g. `https://blockstream.info/api` or a self-hosted instance. */
+	url: string;
+	/** Override the fetch implementation. */
+	fetch?: typeof fetch;
+}
+/**
+* A `ProofSource` backed by an Esplora REST API (self-hosted, or a hosted
+* provider as a fallback). Provider-agnostic: any Esplora-compatible endpoint
+* works. Use as the hosted fallback behind `bitcoinRpcSource`.
+*/
+declare function esploraSource(config: EsploraConfig): ProofSource;
+/**
+* Encode the argument vector for the SIP-044 native built-in
+* `(verify-merkle-proof leaf-hash root-hash tx-index tx-count sibling-hashes)`.
+*
+* Returns the five args in order: `[leaf, root, tx-index, tx-count, siblings]`.
+* All hashes are passed in *internal* (raw) byte order — the built-in does NOT
+* reverse, and neither does this. The leaf is the tx's `txidInternal`; the root
+* is the block header's merkle root in internal order.
+*
+* Throws on shapes the built-in would reject, so a caller fails locally with a
+* clear message instead of an opaque on-chain `false`.
+*/
+declare function encodeMerkleProofArgs(params: {
+	leaf: Uint8Array
+	root: Uint8Array
+	proof: MerkleProof
+}): [BufferCV, BufferCV, UIntCV, UIntCV, ListCV];
+interface DecodedTxOutput {
+	/** scriptPubKey bytes. */
+	script: Uint8Array;
+	/** Output value in satoshis. */
+	amount: bigint;
+	/** The tx's txid in internal byte order — ready as a merkle leaf. */
+	txid: Uint8Array;
+}
+/**
+* Decode the tuple returned by `get-bitcoin-tx-output?`:
+* `(tuple (script (buff 1024)) (amount uint) (txid (buff 32)))`.
+*
+* Accepts either the bare tuple or a `(response ok ...)` wrapping it, so it
+* works whether or not the caller has already unwrapped the response.
+*/
+declare function decodeTxOutput(cv: ClarityValue): DecodedTxOutput;
+type OutputScriptType = "p2pkh" | "p2sh" | "p2wpkh" | "p2wsh" | "p2tr" | "op_return" | "unknown";
+interface ParsedOutputScript {
+	type: OutputScriptType;
+	/**
+	* The hash / witness program for the recognized output types: the 20-byte
+	* pubkey-hash (p2pkh), 20-byte script-hash (p2sh), or the 20/32-byte witness
+	* program (p2wpkh/p2wsh/p2tr). Undefined for op_return / unknown.
+	*
+	* Address formatting is intentionally left to the caller — base58/bech32 HRPs
+	* and version bytes are network-dependent, so it belongs where the network is
+	* known (see `verifyBitcoinPayment`), not in this pure decoder.
+	*/
+	hash?: Uint8Array;
+	/** OP_RETURN payload (the pushed data after the OP_RETURN opcode). */
+	data?: Uint8Array;
+}
+/**
+* Classify a Bitcoin output scriptPubKey by its standard template and surface
+* the embedded hash / witness program. Recognizes P2PKH, P2SH, P2WPKH, P2WSH,
+* P2TR, and OP_RETURN; anything else is `unknown`.
+*/
+declare function parseOutputScript(script: Uint8Array): ParsedOutputScript;
+type BitcoinNetwork = "mainnet" | "testnet";
+interface SpvAdapterRef {
+	/** Deployer principal. */
+	address: string;
+	/** Contract name. */
+	name: string;
+}
+/**
+* Reference `spv-adapter` deployments (the read-only wrapper around the SIP-044
+* built-ins). Populated by plan 013 once Clarity 6 / Epoch 4.0 activates and the
+* contract is deployed. Until then this is empty and callers must pass an
+* explicit `contract` to `bitcoinVerifier`.
+*/
+declare const SPV_ADAPTER_CONTRACTS: Partial<Record<BitcoinNetwork, SpvAdapterRef>>;
+/**
+* ABI for the reference `spv-adapter` contract — a thin, read-only wrapper that
+* exposes the SIP-044 Bitcoin built-ins (callable only from within a Clarity
+* contract) over read-only RPC. Plan 013 deploys a contract matching this shape;
+* `bitcoinVerifier` binds to it (or to an integrator's own contract with the
+* same surface).
+*
+* Hashes are internal (raw) byte order — the same as the built-ins. Do NOT
+* reverse before calling.
+*/
+declare const SPV_ADAPTER_ABI: {
+	readonly functions: readonly [{
+		readonly name: "get-tx-output"
+		readonly access: "read-only"
+		readonly args: readonly [{
+			readonly name: "tx"
+			readonly type: {
+				readonly buff: {
+					readonly length: 4096
+				}
+			}
+		}, {
+			readonly name: "vout"
+			readonly type: "uint128"
+		}]
+		readonly outputs: {
+			readonly response: {
+				readonly ok: {
+					readonly tuple: readonly [{
+						readonly name: "script"
+						readonly type: {
+							readonly buff: {
+								readonly length: 1024
+							}
+						}
+					}, {
+						readonly name: "amount"
+						readonly type: "uint128"
+					}, {
+						readonly name: "txid"
+						readonly type: {
+							readonly buff: {
+								readonly length: 32
+							}
+						}
+					}]
+				}
+				readonly error: "uint128"
+			}
+		}
+	}, {
+		readonly name: "verify-merkle"
+		readonly access: "read-only"
+		readonly args: readonly [{
+			readonly name: "leaf"
+			readonly type: {
+				readonly buff: {
+					readonly length: 32
+				}
+			}
+		}, {
+			readonly name: "root"
+			readonly type: {
+				readonly buff: {
+					readonly length: 32
+				}
+			}
+		}, {
+			readonly name: "tx-index"
+			readonly type: "uint128"
+		}, {
+			readonly name: "tx-count"
+			readonly type: "uint128"
+		}, {
+			readonly name: "siblings"
+			readonly type: {
+				readonly list: {
+					readonly type: {
+						readonly buff: {
+							readonly length: 32
+						}
+					}
+					readonly length: 24
+				}
+			}
+		}]
+		readonly outputs: "bool"
+	}, {
+		readonly name: "was-tx-mined"
+		readonly access: "read-only"
+		readonly args: readonly [{
+			readonly name: "header"
+			readonly type: {
+				readonly buff: {
+					readonly length: 80
+				}
+			}
+		}, {
+			readonly name: "height"
+			readonly type: "uint128"
+		}, {
+			readonly name: "leaf"
+			readonly type: {
+				readonly buff: {
+					readonly length: 32
+				}
+			}
+		}, {
+			readonly name: "tx-index"
+			readonly type: "uint128"
+		}, {
+			readonly name: "tx-count"
+			readonly type: "uint128"
+		}, {
+			readonly name: "siblings"
+			readonly type: {
+				readonly list: {
+					readonly type: {
+						readonly buff: {
+							readonly length: 32
+						}
+					}
+					readonly length: 24
+				}
+			}
+		}]
+		readonly outputs: {
+			readonly response: {
+				readonly ok: "bool"
+				readonly error: "uint128"
+			}
+		}
+	}]
+};
+/** Account derived from a local private key (mnemonic or raw key). */
+type LocalAccount = {
+	type: "local"
+	address: string
+	/** Compressed public key (hex) */
+	publicKey: string
+	/** Raw ECDSA sign over a hash */
+	sign(hash: Uint8Array): Uint8Array
+	/** Sign a structured message (SIP-018) */
+	signMessage(message: string | Uint8Array): string
+};
+/** Account with a user-provided signing function (sync or async). */
+type CustomAccount = {
+	type: "custom"
+	address: string
+	publicKey: string
+	sign(hash: Uint8Array): Promise<Uint8Array> | Uint8Array
+};
+/** Browser wallet provider interface (e.g. Leather, Xverse). */
+type StacksProvider = {
+	request(method: string, params?: any): Promise<any>
+};
+/** Account backed by a browser wallet {@link StacksProvider}. */
+type ProviderAccount = {
+	type: "provider"
+	address: string
+	publicKey: string
+	provider: StacksProvider
+};
+/** Allocates mempool-safe sequential nonces across rapid broadcasts from one account. */
+type NonceManager = {
+	consume(params: {
+		client: Client
+		address: string
+	}): Promise<bigint>
+	reset(params: {
+		client: Client
+		address: string
+	}): void | Promise<void>
+	/** Next nonce that {@link NonceManager.consume} would return without consuming it, or `undefined` if untracked. */
+	peek(params: {
+		client: Client
+		address: string
+	}): Promise<bigint | undefined>
+};
+/** Full chain descriptor used by clients and transports for network-aware operations. */
+type StacksChain = {
+	/** Chain ID (e.g. 0x00000001 for mainnet) */
+	id: number
+	/** Human-readable name */
+	name: string
+	/** Network type */
+	network: "mainnet" | "testnet"
+	/** Transaction version byte for serialization */
+	transactionVersion: number
+	/** Peer network ID for P2P broadcasting */
+	peerNetworkId: number
+	/** Address version bytes */
+	addressVersion: {
+		singleSig: number
+		multiSig: number
+	}
+	/** Magic bytes for network identification */
+	magicBytes: string
+	/** Boot address (system contracts deployer) */
+	bootAddress: string
+	/** Native currency info */
+	nativeCurrency: {
+		name: string
+		symbol: string
+		decimals: number
+	}
+	/** Default RPC URLs */
+	rpcUrls: {
+		default: {
+			http: string[]
+			ws?: string[]
+		}
+	}
+	/** Block explorer URLs */
+	blockExplorers?: {
+		default: {
+			name: string
+			url: string
+		}
+	}
+};
+/** Function that sends an HTTP request to a Stacks node API path. */
+type RequestFn = (path: string, options?: RequestOptions) => Promise<any>;
+/** Options for a transport-level HTTP request. */
+type RequestOptions = {
+	method?: "GET" | "POST" | "PUT" | "DELETE"
+	body?: unknown
+	headers?: Record<string, string>
+};
+/** Shared configuration for all transport types. */
+type TransportConfig = {
+	url?: string
+	timeout?: number
+	retryCount?: number
+	retryDelay?: number
+	fetchOptions?: RequestInit
+	apiKey?: string
+};
+/** A resolved transport instance with a bound request function. */
+type Transport = {
+	type: string
+	request: RequestFn
+	config: TransportConfig
+	destroy?: () => void
+};
+/** Union of all supported account types (local key, custom signer, or browser provider). */
+type Account = LocalAccount | CustomAccount | ProviderAccount;
+/**
+* Core client instance that holds chain context, transport, and extensible actions.
+* Created via {@link createClient}, {@link createPublicClient}, or {@link createWalletClient}.
+*/
+type Client<TExtended extends Record<string, unknown> = Record<string, unknown>> = {
+	chain?: StacksChain
+	account?: Account
+	transport: Transport
+	request: RequestFn
+	/** Optional nonce manager for mempool-safe sequential nonces across rapid broadcasts. */
+	nonceManager?: NonceManager
+	extend: <const TNew extends Record<string, unknown>>(fn: (client: Client<TExtended>) => TNew) => Client<TExtended & TNew> & TNew
+} & TExtended;
+/**
+* SIP-044 (the native Bitcoin SPV built-ins) activates as part of the **Stacks
+* Epoch 4.0 hard fork**. The exact activation Bitcoin block height is only
+* selected after the SIP vote passes, so there is no constant to hardcode — a
+* caller passes it once it is known.
+*/
+interface Clarity6Gate {
+	/**
+	* Bitcoin burn block height at which Clarity 6 / Epoch 4.0 activates. Pass it
+	* once the vote selects it; until then `isClarity6Active` cannot answer and
+	* throws.
+	*/
+	activationBurnHeight?: number;
+}
+/** Read the node's current Bitcoin burn block height from `/v2/info`. */
+declare function getBurnBlockHeight(client: Client): Promise<number>;
+/**
+* Whether Clarity 6 (the native SPV built-ins) is active on the node behind
+* `client`. Compares the node's current burn height to the SIP-044 / Epoch 4.0
+* activation height, which must be supplied (it is unknown until the vote — see
+* `Clarity6Gate`). `bitcoinVerifier` uses this to refuse calls before activation
+* rather than failing with an opaque contract error.
+*/
+declare function isClarity6Active(client: Client, gate?: Clarity6Gate): Promise<boolean>;
+interface BitcoinVerifierConfig {
+	/** Adapter contract principal, `"address.name"` (the reference `spv-adapter` or an integrator's own). */
+	contract: string;
+	/** Optional read-only call sender; defaults to the contract address. */
+	sender?: string;
+}
+interface BitcoinVerifier {
+	/**
+	* Verify a merkle inclusion proof against a supplied root via the adapter's
+	* `verify-merkle` (the native `verify-merkle-proof`). This proves membership
+	* under `root`; authenticating that `root` belongs to a canonical Bitcoin
+	* block is a separate step (header → height), composed in `verifyBitcoinPayment`.
+	*/
+	verifyMerkleProof(input: {
+		leaf: Uint8Array
+		root: Uint8Array
+		proof: MerkleProof
+	}): Promise<boolean>;
+	/** Verify an `SpvProof`'s merkle inclusion against its own header root (membership only — not chain-authenticated). */
+	verifySpvProof(proof: SpvProof): Promise<boolean>;
+	/**
+	* Full header-authenticated SPV check via the adapter's `was-tx-mined`: the
+	* contract authenticates the proof's header against the chain
+	* (`get-burn-block-info? header-hash`), extracts its root, and proves
+	* inclusion — atomically. Returns `false` if the header isn't canonical at
+	* its height or the tx isn't included. This is the real "is it on Bitcoin" check.
+	*/
+	wasTxMined(proof: SpvProof): Promise<boolean>;
+	/**
+	* Decode one output of a serialized Bitcoin tx via the adapter's
+	* `get-tx-output` (the native `get-bitcoin-tx-output?`).
+	*/
+	getTxOutput(rawTx: Uint8Array, vout: number): Promise<DecodedTxOutput>;
+}
+/**
+* Bind a `BitcoinVerifier` to a deployed adapter contract. There is a single,
+* native target — no caps and no legacy `clarity-bitcoin` path. The built-ins do
+* not exist until Clarity 6 / Epoch 4.0 activates, so read-only calls only
+* succeed on a node at that epoch (a local Clarity-6 devnet, or mainnet after
+* activation); guard with `isClarity6Active` when in doubt.
+*/
+declare function bitcoinVerifier(client: Client, config: BitcoinVerifierConfig): BitcoinVerifier;
+/**
+* Render a parsed output script as a Bitcoin address for the given network.
+* Returns `undefined` for scripts without a standard address (OP_RETURN, P2PK,
+* unknown). Address encoding is network-dependent, which is why this is separate
+* from the pure `parseOutputScript` decoder.
+*/
+declare function formatBitcoinAddress(parsed: ParsedOutputScript, network?: BitcoinNetwork): string | undefined;
+interface BitcoinPaymentOutput {
+	vout: number;
+	/** scriptPubKey bytes. */
+	script: Uint8Array;
+	/** Value in satoshis. */
+	amount: bigint;
+	type: OutputScriptType;
+	/** Address for the configured network, if the script has a standard one. */
+	address?: string;
+}
+interface VerifyBitcoinPaymentResult {
+	/** `mined` AND every supplied `expect` constraint holds. */
+	verified: boolean;
+	/**
+	* On-chain proof that the tx is committed in a Bitcoin block. With
+	* `authenticateHeader` (default), this is the adapter's `was-tx-mined` —
+	* header authenticated against the chain AND merkle inclusion. With it off,
+	* it is merkle inclusion against the proof's own (unauthenticated) header.
+	*/
+	mined: boolean;
+	/** The decoded output at `vout`. */
+	output: BitcoinPaymentOutput;
+	/** The proof used (built or supplied). */
+	proof: SpvProof;
+}
+type VerifyBitcoinPaymentParams = ({
+	proof: SpvProof
+} | {
+	txid: string
+	source: ProofSource
+}) & {
+	/** Adapter contract principal, `"address.name"`. */
+	contract: string
+	/** Output index to decode and assert against. */
+	vout: number
+	/** Network for address formatting. Defaults to mainnet. */
+	network?: BitcoinNetwork
+	/** Optional expectations; each supplied field must match for `verified`. */
+	expect?: {
+		address?: string
+		amount?: bigint
+	}
+	/**
+	* Confirm the proof's header is the canonical block at its height via
+	* `get-header-merkle-root` (default true). Turn off only when the caller has
+	* already authenticated the header.
+	*/
+	authenticateHeader?: boolean
+	sender?: string
+};
+/**
+* Verify that a Bitcoin payment is committed on-chain and (optionally) matches
+* an expected recipient/amount. Composes the whole SPV flow:
+*  1. build the proof from a `ProofSource` (or accept a prepared `SpvProof`),
+*  2. prove the tx is mined — `was-tx-mined` (header authenticated against the
+*     chain + merkle inclusion) by default, or membership-only when
+*     `authenticateHeader` is off,
+*  3. decode the target output and assert any `expect` constraints.
+*
+* The output is decoded off-chain from the proof's raw tx, which is sound: the
+* raw tx is pinned to the proven txid (`buildTxProof` checks it hashes to the
+* leaf), so its bytes are committed.
+*/
+declare function verifyBitcoinPayment(client: Client, params: VerifyBitcoinPaymentParams): Promise<VerifyBitcoinPaymentResult>;
+export { verifyBitcoinPayment, stripWitness, rootFromProof, reverseBytes, parseOutputScript, parseBlockHeader, parseBitcoinTx, merkleRoot2 as merkleRoot, isClarity6Active, getBurnBlockHeight, formatBitcoinAddress, fallbackProofSource, esploraSource, encodeMerkleProofArgs, doubleSha256, decodeTxOutput, buildTxProof, buildMerkleProof, blockHash, bitcoinVerifier, bitcoinTxid, bitcoinRpcSource, VerifyBitcoinPaymentResult, VerifyBitcoinPaymentParams, SpvProof, SpvAdapterRef, SPV_ADAPTER_CONTRACTS, SPV_ADAPTER_ABI, ProofSource, ParsedOutputScript, ParsedBitcoinTx, OutputScriptType, MerkleProof, EsploraConfig, DecodedTxOutput, Clarity6Gate, BtcReader, BlockHeader, BlockForTx, BitcoinVerifierConfig, BitcoinVerifier, BitcoinTxOutput, BitcoinTxInput, BitcoinRpcConfig, BitcoinPaymentOutput, BitcoinNetwork };