Namespace NArk.Core.Services
Classes
- ArkadeCashClaimResult
The outcome of claiming an ArkadeCash note: what moved, and what did not.
- ArkadeCashService
Claims ArkadeCash bearer instruments.
- ArkadeCashUnclaimedVtxo
One VTXO at an ArkadeCash address that the claim reported instead of sweeping.
- BatchManagementService
Service for managing Ark intents with automatic submission, event monitoring, and batch participation. Uses a single persistent gRPC event stream with dynamic topic updates via UpdateStreamTopics.
- BoardingUtxoPollService
Periodically polls the Bitcoin blockchain for boarding UTXOs. Delegates to BoardingUtxoSyncService which exits early when no boarding contracts are registered.
- BoardingUtxoSyncService
Synchronizes boarding UTXOs from the Bitcoin blockchain via an IBitcoinBlockchain. Queries on-chain UTXOs for boarding contract addresses and upserts them into VTXO storage.
- ContractReconciliationService
Keeps every SingleKey wallet's advertised "Default" contract aligned with the CURRENT arkd signer, and flags any wallet whose Arkade sweep destination was orphaned by a signer rotation.
A SingleKey wallet's Default contract is derived from
ArkServerInfo.SignerKey. When arkd rotates its signer, the old-signer Default becomes stale: the new-signer Default must be derived (and advertised), and the stale one superseded so only one row is the advertised default.Triggers:
- WalletSaved (wallet created/updated) → reconcile that one wallet.
- ServerInfoChanged (signer rotated) → reconcile ALL SingleKey wallets.
- Startup pass on StartAsync(CancellationToken) → reconcile ALL SingleKey wallets (covers wallets rotated while offline).
Destination safety: on the same triggers, for ANY wallet (SingleKey or HD) that has a sweep destination, if the destination's ArkAddress server key is now a deprecated signer the destination is flagged pending re-confirmation (a Metadata marker via DestinationSafety) and DestinationDisabled is raised once (on the set transition); a destination that is no longer stale clears the flag. WalletSaved therefore also enqueues HD wallets that carry a destination, so a re-save clears the flag.
Supersede semantics: funds safety does NOT depend on the deactivation — the sweeper gathers coins by VTXO script regardless of Active state — so deactivating stale
Source="Default"rows is purely about which row is the advertised default.Lifecycle mirrors SweeperService: event handlers only enqueue (non-blocking), a background worker drains the channel, subscribe in StartAsync(CancellationToken), unsubscribe + cancel in DisposeAsync().
- DelegationMonitorService
Hosted service that monitors VTXO changes and automatically delegates new VTXOs at delegate contracts to the configured delegator service.
- DelegationService
Orchestrates VTXO delegation to an external delegator service (e.g. Fulmine). The client creates a partially signed intent and forfeit transactions, then sends them to the delegator which registers the intent and participates in batches on the owner's behalf before VTXOs expire.
- DestinationSafety
Detects when a wallet's sweep destination has been orphaned by an Arkade signer rotation.
- ExitWatchtowerBackgroundService
Background service that periodically runs the exit watchtower check. Register as IHostedService for autonomous monitoring.
- ExitWatchtowerService
Monitors the blockchain for partial tree broadcasts and auto-starts unilateral exits when detected. If someone starts unrolling the tree but doesn't finish, previous owners may claim funds after their CSV timeout. The watchtower detects this and continues the exit automatically.
- OnchainSweepService
Detects expired boarding/unrolled UTXOs and sweeps them via the unilateral exit path to a fresh boarding address. This is a safety net for UTXOs whose CSV timeout has expired before they were consumed in a batch.
- PaymentTrackingService
Hosted service that subscribes to protocol events (VTXOs and intents) and automatically updates payment and payment request statuses. Registered via NArk.Storage.EfCore.Hosting.StorageServiceCollectionExtensions.AddArkPaymentTracking.
- PendingArkTransactionRecoveryService
Reconciles Arkade transactions that the server has registered as pending — i.e. the SDK called SubmitTx(string, string[], CancellationToken) (server locked the inputs as in-flight) but the matching FinalizeTx(string, string[], CancellationToken) never followed because the process crashed, the user closed the app, or the network dropped.
- PendingTxRecoveryFailureEventArgs
Raised by PendingArkTransactionRecoveryService when finalizing a single pending Arkade transaction fails. Subscribers can use this to surface a non-blocking banner in the wallet UI, ship telemetry, or schedule a manual retry — the recovery service itself moves on to the next pending tx in the same batch regardless, so failures here never block start-up.
- UnauthorizedPendingArkTransactionException
Thrown by PendingArkTransactionRecoveryService when a pending Arkade transaction reported by the server fails local authorization, i.e. it is not a transaction this wallet ever submitted.
- UnilateralExitService
Orchestrates unilateral exit for VTXOs. Broadcasts the chain of virtual txs from commitment to leaf, waits for CSV timelock, then claims funds on-chain.
- VirtualTxService
Fetches, stores, and prunes virtual transaction data for VTXOs. Virtual txs form the tree of pre-signed transactions from commitment tx to VTXO leaf. This data is required for unilateral exit (broadcasting the chain to claim funds on-chain).
- VtxoChainAutoFetchService
Background service that fetches and stores the virtual-tx chain for every new VTXO observed via VtxosChanged.
VTXOs arrive from multiple sources — batch settlement, change from a spend, incoming payment from another wallet, swap claim, sweep, etc. — and any of them can later need to be exited unilaterally. By subscribing to the storage-level event we capture them all uniformly, regardless of how they arrived.
Storage is opt-in — register via
services.AddVirtualTxAutoFetch(). With the auto-fetch off, callers can still drive VirtualTxService manually (e.g. only when starting an exit) if they prefer to defer the indexer round-trips.
- VtxoChainProofProvider
Supports all classes in the .NET class hierarchy and provides low-level services to derived classes. This is the ultimate base class of all .NET classes; it is the root of the type hierarchy.
Interfaces
- ICoinService
Resolves VTXOs into spendable ArkCoin instances by matching them with their contract metadata and wallet signing information.
- IOnchainService
Service for moving funds from Ark back to the Bitcoin base layer via collaborative exits.
- ISpendingService
Service for creating and submitting Ark off-chain spend transactions.
- IVtxoChainProofProvider
Builds the BIP-322-style ownership proof that authenticates GetVtxoChainAsync(OutPoint, string?, string?, CancellationToken) against the Arkade indexer. Given a VTXO the wallet owns, it resolves the backing contract, coin and signer and produces the
{"type":"get-data"}intent proof arkd expects.
Enums
- ArkadeCashUnclaimedReason
Why a VTXO at an ArkadeCash address could not be swept by ClaimAsync(ArkadeCash, ArkAddress, CancellationToken).