Table of Contents

Namespace NArk.Core.Recovery

Classes

BoardingUtxoDiscoveryProvider

Discovery provider that asks the on-chain side (NBXplorer / Esplora, abstracted by IBitcoinBlockchain) whether the ArkBoardingContract derived from a given HD index ever received a UTXO. Boarding contracts are one-shot funding entry points onto the Ark — a historical hit at any index is unambiguous evidence of usage.

HdWalletRecoveryService

Iteratively probes derivation indices of an HD wallet to recover contracts that were used before the wallet was imported into local storage. Each index is probed by every registered IContractDiscoveryProvider (arkd indexer, on-chain boarding, …) and the union of results determines whether the index counts as used.

IndexerVtxoDiscoveryProvider

Discovery provider that asks arkd's indexer whether any VTXO (spent or unspent) is recorded against the contracts derivable from a given HD index. A single VTXO at any state is sufficient evidence the index was used.

To recover funds locked under legacy script formats, this derives and probes more than the current default contract — mirroring the canonical arkade-os/ts-sdk restore. For each index it builds, for every signer in { current SignerKey } ∪ DeprecatedSigners (server-key rotation leaves old funds under a different script):

On mainnet the candidate set also pairs each signer with the historical 7-day unilateral-exit delay (605184s) alongside the arkd-advertised one — matching ts-sdk's MAINNET_UNILATERAL_EXIT_DELAY fallback. arkd only advertises the CURRENT delay; without this, wallets that minted VTXOs while mainnet still ran the original delay would silently fail discovery after the operator shortened it. We keep one hardcoded fallback rather than scanning an unbounded history because arkd does not record deprecated delays.

Every candidate whose script the indexer reports a VTXO for is returned so the orchestrator persists it.

SingleKeyVtxoRecoveryService

Recovery for SingleKey wallets. There is no derivation index to scan: the flat tr(pubkey) descriptor yields one candidate set. We probe every IContractDiscoveryProvider ONCE with that descriptor; the indexer provider internally probes { current signer ∪ deprecated signers } (IndexerVtxoDiscoveryProvider.BuildCandidates), so funds stranded under a rotated signer are discovered. Discovered contracts are persisted Active.

WalletRecoveryReport

Outcome of a unified RecoverAsync(string, RecoveryOptions?, CancellationToken) run.

WalletRecoveryService

Unified, wallet-type-agnostic recovery. Composes the existing building blocks — the HD index scanner (HdWalletRecoveryService), the pending-tx finalizer (PendingArkTransactionRecoveryService) and the VTXO sync (VtxoSynchronizationService) — behind one RecoverAsync(string, RecoveryOptions?, CancellationToken) call.

Interfaces

ISingleKeyDefaultEnsurer

Idempotently ensures a SingleKey wallet's CURRENT-signer "Default" contract exists (Active, Metadata["Source"] == "Default") and reports its script.

Extracted from SingleKeyVtxoRecoveryService so the reconciliation service can depend on (and substitute) a minimal seam rather than the concrete recovery service.

IWalletRecoveryService

Wallet-type-agnostic recovery entry point. Given a wallet id, rebuilds local state from on-chain / indexer sources: contracts (incl. legacy script variants under deprecated server signers), the HD derivation index, funds (VTXOs), and any in-flight Arkade transactions.

Dispatches by wallet type: HD wallets get a gap-limit index scan; SingleKey wallets — whose contract set is fixed by their one key — re-derive that contract. Both then finalize pending transactions and sync funds.