Interface IBitcoinBlockchain

Namespace

NArk.Abstractions.Blockchain

Assembly

NArk.Abstractions.dll

Unified Bitcoin-blockchain backend: chain-time, address-indexed UTXO lookup, transaction broadcast, tx-status, and fee estimation. Realistically every concrete backend (NBXplorer, Esplora, Bitcoin Core RPC) is going to expose some flavour of all of these, so the SDK takes them as one interface rather than imposing the wiring tax of three split-by-responsibility abstractions.

Not every backend supports every method — Bitcoin Core RPC, for example, has no native address-indexed UTXO API. Implementations should throw NotSupportedException with a clear message for genuinely unsupported operations. See per-impl docs for what each backend covers.

public interface IBitcoinBlockchain

Methods

BroadcastAsync(Transaction, CancellationToken)

Broadcast a single transaction. Returns true when the broadcast was accepted (in mempool); false otherwise. Implementations should not throw on policy / consensus rejection — the rejection is observable and recoverable, but it isn't an exceptional condition for callers.

Task<bool> BroadcastAsync(Transaction tx, CancellationToken cancellationToken = default)

Parameters

tx Transaction

cancellationToken CancellationToken

Returns

Task<bool>

BroadcastPackageAsync(Transaction, Transaction, CancellationToken)

Broadcast a 1p1c package (parent + CPFP child) via Bitcoin Core's submitpackage. Used by the unilateral-exit broadcaster to wrap each virtual tx with a fee-bearing child so it gets past TRUC policy.

Task<bool> BroadcastPackageAsync(Transaction parent, Transaction child, CancellationToken cancellationToken = default)

Parameters

parent Transaction

child Transaction

cancellationToken CancellationToken

Returns

Task<bool>

EstimateFeeRateAsync(int, CancellationToken)

Estimate fee rate (sat/vB) for inclusion within confirmTarget blocks. Used by CPFP child construction and the claim-tx builder.

Task<FeeRate> EstimateFeeRateAsync(int confirmTarget = 6, CancellationToken cancellationToken = default)

Parameters

confirmTarget int

cancellationToken CancellationToken

Returns

Task<FeeRate>

GetChainTime(CancellationToken)

Current chain time + block height. Used by the SDK for batch-expiry math, CSV-maturity checks, sweep eligibility, and similar timing decisions across spending, swaps, and unilateral exit.

Timestamp must be the tip's median time past (BIP 113), not the tip block's own nTime — that's the clock consensus uses for time-based locks, so anything comparing a timelock against it (BIP-68 relative time locks, CLTV) would otherwise be off by up to a couple of hours.

Task<TimeHeight> GetChainTime(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Returns

Task<TimeHeight>

GetMedianTimePastAsync(uint, CancellationToken)

Median time past (BIP 113) of the block at blockHeight. Returns null when the backend has no block at that height.

Needed to evaluate BIP-68 time-based relative locks: a time-locked input matures once the spending block's MTP is at least the MTP of the block that confirmed the input plus the lock period. Block heights are meaningless for that comparison, so the unilateral exit path calls this whenever the operator advertises a time-based unilateral-exit delay (arkd's production default is 24 h).

Task<DateTimeOffset?> GetMedianTimePastAsync(uint blockHeight, CancellationToken cancellationToken = default)

Parameters

blockHeight uint

cancellationToken CancellationToken

Returns

Task<DateTimeOffset?>

Exceptions

NotSupportedException

Backend cannot resolve a historical block's median time past. Time-based relative locks cannot be evaluated against such a backend; use NBXplorer, Esplora, or Bitcoin Core RPC.

GetRawTransactionAsync(uint256, CancellationToken)

Fetch a confirmed or mempool transaction in full, by txid. Returns null when the backend does not know the transaction.

Needed to carry a boarding or commitment transaction as a PSBT prevout field: the Arkade emulator requires the transaction behind every input of a submitted intent proof, and those two have no off-chain source, so arkd's indexer cannot serve them.

Task<Transaction?> GetRawTransactionAsync(uint256 txid, CancellationToken cancellationToken = default)

Parameters

txid uint256

The transaction id to fetch.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<Transaction>

Exceptions

NotSupportedException

The backend cannot serve raw transactions. This is the default, so a third-party implementation keeps compiling; the in-box Esplora, NBXplorer and Bitcoin Core RPC backends all override it.

GetTxStatusAsync(uint256, CancellationToken)

Query whether a transaction has confirmed, is sitting in the mempool, or is unknown to the backend. The exit broadcaster + watchtower poll this to advance sessions from Broadcasting → AwaitingCsvDelay.

Task<TxStatus> GetTxStatusAsync(uint256 txid, CancellationToken cancellationToken = default)

Parameters

txid uint256

cancellationToken CancellationToken

Returns

Task<TxStatus>

GetUtxosAsync(string, CancellationToken)

Lists confirmed + mempool UTXOs at a single on-chain address. Used to discover funds at boarding addresses (the on-chain entry point to a VTXO) and to drive HD-wallet recovery.

Task<IReadOnlyList<BoardingUtxo>> GetUtxosAsync(string address, CancellationToken cancellationToken = default)

Parameters

address string

cancellationToken CancellationToken

Returns

Task<IReadOnlyList<BoardingUtxo>>

Exceptions

NotSupportedException

Backend has no address-indexed UTXO API (e.g. plain Bitcoin Core RPC without an external indexer). Use NBXplorer or Esplora when this capability is required.