coordinator library

LibSpiffy Coordinator API - The canonical public interface for third-party apps.

Import this library to interact with LibSpiffy through the unified coordinator:

import 'package:libspiffy/coordinator.dart';

// Send a request and get its own reply; a failure throws CoordinatorFailure
final wallet = await libspiffy.coordinator
    .ask(CreateWalletCommand(walletId: 'my-wallet', name: 'My Wallet', mnemonic: mnemonic));

// Follow what happens without a request
libspiffy.coordinator.on<BalanceUpdatedEvent>(walletId: 'my-wallet').listen(render);

example/coordinator_example.dart runs this offline.

This provides clean command/event names without collisions with internal domain types. For access to internal actors and domain types, use package:libspiffy/libspiffy.dart.

Classes

AcceptChannelCommand: Accept an incoming channel request
AddressGeneratedEvent: Result of GenerateAddressCommand: the wallet's fresh address, where it sits on the wallet's keys (chain, derivationIndex) and, when asked for, its publicKeyHex.
AncestorProofRequestedEvent: What became of a RequestAncestorProofCommand (bead libspiffy-a2v3).
AncestorProofRequestReceivedEvent: A proof_request a peer sent us, and what we did about it (bead libspiffy-a2v3).
AncestorProofResponseEvent: What became of a proof_response a counterparty sent back (bead libspiffy-a2v3).
AnchorPublicKeyEvent: Answer to IssueAnchorKeyCommand: the wallet's anchor public key for the context (compressed, hex), or why there is none (an xpub or WIF wallet has no anchor key; an empty context is refused).
AnchorSignedEvent: Answer to SignWithAnchorKeyCommand: the DER signature (hex) of SHA-256 of the message by the anchor key publicKey, or why there is none. The signature is deterministic (RFC 6979) with a low S.
BalanceResponse: Balance query response, computed from the read model.
BalanceUpdatedEvent: The wallet's balance changed: the read model applied an event that moved money, and these are the numbers it now holds (bead libspiffy-7ye4).
BEEFSettledEvent: Result of settling a BEEF via ARC.
BEEFValidationResultEvent: The answer to a ValidateBEEFCommand: a counterparty's payment, checked, recorded and submitted.
BlockHeadersStoredEvent: Block headers were stored: how many, and the heights they span.
Brc100KeyOperationCommand: Runs the BRC-100 key operation request with a BRC-42 child of the wallet's anchor key for anchorContext, the anchor acting as BRC-100's root key: an anchor issued for a BRC-100 identity signs (BRC-3), encrypts (BRC-2), and derives keys as that identity. Answered with Brc100KeyOperationEvent.
Brc100KeyOperationEvent: Answer to Brc100KeyOperationCommand: the operation's result, or why there is none.
BroadcastDeferredPaymentCommand: Broadcast a deferred payment yourself, e.g. when the recipient is slow to do it. Its unconfirmed ancestors (from the BEEF rebuilt from storage) are submitted first. Idempotent: a transaction the network already has is reported as such. Answered with DeferredPaymentBroadcastEvent.
BroadcastFailureEvent: A broadcast to ARC failed that no request is waiting on (a durable retry, or a broadcast another actor started).
CancelDeferredPaymentCommand: Cancel an outstanding deferred payment and release its inputs. Answered with DeferredPaymentCancelledEvent.
ChannelAcceptedEvent: Answer to AcceptChannelCommand: the acceptance is journaled and channel_accept handed to the app's transport for the client. The channel opens when the client funds it (ChannelOpenedEvent).
ChannelClosedEvent: Channel closed
ChannelExpiredEvent: Answer to ExpireChannelCommand: the expiry is journaled, or why not.
ChannelFundingRetriedEvent: The outcome of a RetryChannelFundingCommand (bead libspiffy-1n3).
ChannelOpenedEvent: Channel opened successfully
ChannelOpenResentEvent: The outcome of a ResendChannelOpenCommand (bead libspiffy-1n3).
ChannelP2PAdapter: Transport-agnostic adapter that translates between P2P protocol messages (as raw maps) and LibSpiffy's PaymentChannelManagerActor messages.
ChannelPayCommand: Make a payment over an open channel
ChannelPaymentEvent: Payment made or received on a channel
ChannelPaymentPendingEvent: A payment the client signed and sent, not yet acknowledged by the server (bead overnode_v2-0o5.3.2). The ChannelPayCommand is answered by its ChannelPaymentEvent once the server acknowledges it, or by an ErrorEvent when it does not within ChannelTiming.confirmWithin; it is still resent then, and a later acknowledgement brings a ChannelPaymentEvent that answers no request.
ChannelRefundClaimedEvent: The outcome of a ClaimChannelRefundCommand (bead libspiffy-cqc, the V-99 follow-up).
ChannelRejectedEvent: Answer to RejectChannelCommand: channel_reject is handed to the app's transport for the client, when the request is one this side holds.
ChannelRequestReceivedEvent: Incoming channel request from a peer (app should show UI for approval)
CheckDeferredPaymentStatusCommand: Ask the network about a deferred payment now instead of waiting for the periodic ARC scan. Answered with DeferredPaymentStatusEvent.
CheckForeignSpendsCommand: Asks whether outputs the wallet holds were spent by someone else: by default every plugin output (a token) the wallet has not spent. For each one the configured data source answers who spent it. A spender that is mined and proven against the local headers (ForeignSpend.proven) is received by the wallet as any mined transaction of its is: the output it spends is marked spent, its outputs that pay the wallet's addresses are received as available in the block its proof names, and it joins the wallet's transaction history (ForeignSpend.recorded). Its raw transaction and its BEEF come back too. Anything less is a lead, reported and not acted on.
ClaimChannelRefundCommand: Claim the refund of an expired channel (non-cooperative close).
ClientChannelInfo: Tracks state for a channel we initiated (client role).
CloseChannelCommand: Close a payment channel
CompleteDeferredPaymentCommand: Completes an outstanding deferred payment that the wallet signed only in part, with rawHex: the same transaction carrying the counterparty's signatures on the inputs the wallet does not hold.
CoordinatorEvent: Base class for all coordinator events emitted on the event stream.
CoordinatorReply: The event that answers a CoordinatorRequest: each request names its reply type, and the coordinator answers it with exactly one, on success and on failure, carrying the request's requestId.
CoordinatorRequest<R extends CoordinatorReply>: A command or query the coordinator answers with one R.
CreateInvoiceCommand: Create a payment invoice
CreateWalletCommand: Create a new wallet
DeferredNetworkStatus: Network status strings recorded for deferred payments.
DeferredPayment: Read model of a deferred payment. Never deleted (only a wallet deletion removes it): resolved payments stay listable with their state.
DeferredPaymentBroadcastEvent: Result of BroadcastDeferredPaymentCommand.
DeferredPaymentCancelledEvent: Result of CancelDeferredPaymentCommand.
DeferredPaymentCompletedEvent: Result of CompleteDeferredPaymentCommand: on success the completed transaction completedTxid is recorded and holds the half's inputs.
DeferredPaymentDetail: One deferred payment in a DeferredPaymentsResponse, with what is needed to act on it.
DeferredPaymentInput: One input a deferred payment holds.
DeferredPaymentPage: One page of deferred payments.
DeferredPaymentPurpose: The purpose a deferred payment carries, for the values the wallet itself sets and reads back.
DeferredPaymentQuery: Filter and page of ReadModelStorage.listDeferredPayments.
DeferredPaymentReclaimedEvent: Result of ReclaimDeferredPaymentCommand.
DeferredPaymentsResponse: Answer to GetDeferredPaymentsQuery.
DeferredPaymentStatusEvent: Result of CheckDeferredPaymentStatusCommand.
DeleteWalletCommand: Delete a wallet permanently (event-sourced)
DeriveType42DestinationCommand: Derives a type-42 destination for paying the holder of anchor key anchorPublicKey while it is offline (beads libspiffy-zxkd, libspiffy-fdal; spv-understanding.md, "Payment modes"). Answered with Type42DestinationEvent: the address to pay, and the hand-off (A, its anchorContext when given, the payer key B and the invoice number) the payee takes the payment in with.
ErrorEvent: Something failed that has no reply of its own to report it in.
ExpireChannelCommand: Record that a payment channel has expired (lockTime elapsed).
ExportTransactionQuery: Export a transaction of the wallet with its merkle proof, as a BEEF that another wallet imports with ImportTransactionCommand (bead libspiffy-m8qu).
ForeignSpend: One wallet output another transaction spends: found by CheckOutputSpendersMessage, and recorded in the wallet by CheckForeignSpendsCommand when the spender is proven.
ForeignSpendsCheckedEvent: Result of CheckForeignSpendsCommand.
GenerateAddressCommand: Asks wallet walletId for a fresh address of its own: a key no payment has named yet, derived on its receive chain (purpose 'receive', the default) or its change chain ('change'), with an optional label. With includePublicKey the answer carries the key's public key, which a counterparty needs to name the wallet's coin by key (a swap's funding, a P2PK output) or to build a multisig with it. Answered with AddressGeneratedEvent once the read model holds the address, so a payment to it validates at once (SPV attributes outputs by the read model's address rows).
GetBalanceQuery: Query wallet balance
GetDeferredPaymentsQuery: List or search the wallet's deferred payments. Answered with DeferredPaymentsResponse (or an ErrorEvent with source getDeferredPayments).
GetHeaderSyncStatusQuery: Asks where header sync stands; answered with HeaderSyncStatusResponse.
GetTransactionDetailQuery: Query specific transaction detail
GetTransactionsQuery: Query wallet transactions
HeaderSyncStatus: Where header sync stands: the chain's height, the height its peers reported, and whether it has caught up with them.
HeaderSyncStatusEvent: Header sync caught up with its peers, or fell behind them: emitted when HeaderSyncStatus.synced changes. Each batch of headers stored on the way is a BlockHeadersStoredEvent.
HeaderSyncStatusResponse: Answer to GetHeaderSyncStatusQuery.
ImportCompleteEvent: Wallet import completed
ImportProgressEvent: Wallet import progress update
ImportTransactionCommand: Import a transaction the wallet already knows to be mined: recovering a wallet, or bringing in its own history.
ImportTransactionConfirmedEvent: Transaction confirmed by aggregate during import
ImportUTXOConfirmedEvent: UTXO confirmed by aggregate during import
ImportWalletCommand: Import a wallet from extended private key or WIF.
InvoiceCreatedEvent: Invoice created successfully
InvoicePaidEvent: Invoice paid
IssueAnchorKeyCommand: Issues the wallet's anchor key for anchorContext (beads libspiffy-zxkd, libspiffy-fdal): the key a payer derives type-42 destinations from to pay this wallet while it is offline (spv-understanding.md, "Payment modes"). The app publishes it, bound to the identity it is for. Answered with AnchorPublicKeyEvent.
OpenChannelCommand: Open a payment channel with a peer
P2PMessageReceived: An inbound peer-to-peer message the app received on its own transport and hands to the library (bead libspiffy-a2v3).
P2PMessageToSendEvent: An outgoing peer-to-peer message the app must transmit to toPeerId on its own transport (bead libspiffy-a2v3).
P2PSendFailed: The app could not hand a P2PMessageToSendEvent to toPeerId (bead overnode_v2-0o5.3.2): its transport failed to reach the peer. The payment-channel protocol sends it again sooner than it would otherwise; the rest of the library has nothing to retry.
PayInvoiceCommand: Pay an invoice (builds BEEF, does NOT broadcast)
PaymentReadyEvent: BEEF payment constructed and ready for transmission to counterparty
PeerInfo: Tracks which peers are involved in a channel.
PendingRequest: A pending incoming channel request awaiting accept/reject.
ProofP2PAdapter: Asks a counterparty for a fresh merkle proof, and answers when one asks us (bead libspiffy-a2v3).
ProvisionFundingCommand: Provision earmark-aware funding UTXOs for a token lifecycle.
ProvisioningCompleteEvent: Funding provisioning completed (earmarked UTXOs created).
ReclaimDeferredPaymentCommand: Reclaim an outstanding deferred payment: spend the inputs it holds back into this wallet and broadcast that transaction. Answered with DeferredPaymentReclaimedEvent.
RecordOutgoingCommand: Record an outgoing transaction in the wallet
RegisterWatchAddressCommand: Register an address to watch for activity
RejectChannelCommand: Reject an incoming channel request
ReleaseUTXOsCommand: Release reserved UTXOs
RequestAncestorProofCommand: Ask the counterparty who handed us txid for a fresh merkle proof for its ancestry (bead libspiffy-a2v3).
ResendChannelOpenCommand: Send channel_open again for a channel that is already open on this side, when the counterparty never received it (bead libspiffy-1n3).
RetryChannelFundingCommand: Broadcast the funding transaction of a channel whose funding broadcast failed, so the open can finish (bead libspiffy-1n3).
ServerChannelInfo: Tracks state for a channel we accepted (server role).
SettleBEEFCommand: Settle a BEEF by broadcasting all unsettled transactions (hasMerkle=false) to ARC in dependency order.
ShutdownCommand: Gracefully shutdown the coordinator
SignWithAnchorKeyCommand: Signs SHA-256(message) with the wallet's anchor key for anchorContext (beads libspiffy-zxkd, libspiffy-fdal), to bind that anchor to an identity — a NodeCast registration, say. The message is hashed by the wallet, so the anchor key never signs a digest the caller chose; the message should name its purpose (domain separation). Answered with AnchorSignedEvent.
SplitTransactionOutcome: One Benford split transaction and how it ended (SplitTransactionStatus).
SplitUTXOsCommand: Split UTXOs using Benford's Law distribution for privacy
SPVValidationResultEvent: SPV validation result for a received transaction
StoreHeadersCommand: Store block headers for SPV validation.
TimestampCommand: Create a timestamp archive (OP_RETURN data on-chain)
TimestampCompleteEvent: Timestamp archive completed
TransactionConfirmationRevertedEvent: The chain no longer supports a confirmation this wallet announced.
TransactionConfirmedEvent: A merkle proof put the transaction in the block at blockHeight, whose header we hold on our active chain: confirmed, and there is nothing more to it (bead libspiffy-jc3h).
TransactionDetailResponse: Transaction detail query response
TransactionExportedEvent: Answer to ExportTransactionQuery: the transaction with its proof and what proves its ancestry, as BEEF bytes, or why there is none.
TransactionImportedEvent: Transaction imported into wallet
TransactionRecordedEvent: An outgoing transaction a RecordOutgoingCommand asked the wallet to record is recorded: journaled by the wallet aggregate and applied to the read model, so the transaction queries can already see it (bead libspiffy-5ml6). The same promise WalletCreatedEvent and TransactionImportedEvent make, for the same reason — an app told "recorded" queries next.
TransactionsResponse: Transactions query response
Type42DestinationEvent: Answer to DeriveType42DestinationCommand: the destination, or why there is none. Type42Destination.address is what the payer pays; Type42Destination.derivation is the hand-off.
UnfinishedChannel: One channel that started opening and never finished (bead libspiffy-29jd).
UnfinishedChannelsFoundEvent: Channels of walletId that started opening and never reached open, reported once at startup (bead libspiffy-29jd).
UTXOSplitCompleteEvent: Benford UTXO split completed.
UTXOSplitStartedEvent: A Benford UTXO split has started: the wallet's spendable outputs have been chosen and the first split transaction is about to be built.
UTXOsReleasedEvent: Answer to ReleaseUTXOsCommand: the UTXOs the reservation held are available again. releasedUtxoKeys is empty when the reservation held none (already released, or expired).
ValidateBEEFCommand: Validate incoming BEEF data (structural + SPV validation)
WalletCoordinator: The coordinator, as an application talks to it: send a command and wait for its own answer (ask), send one and leave the answer on the event stream (tell), or follow the events of one kind (on).
WalletCoordinatorActor: The canonical public interface for third-party apps using LibSpiffy.
WalletCreatedEvent: Answer to CreateWalletCommand: the wallet is created and the read model holds it, or why not.
WalletDeletedEvent: Answer to DeleteWalletCommand: the wallet's deletion is journaled.
WalletStatusEvent: Wallet status update
WatchAddressRegisteredEvent: Watch address registered

Enums

DeferredPaymentNetworkSource: Where a network check or a broadcast of a deferred payment goes.
DeferredPaymentState: Lifecycle of a deferred payment.
SplitTransactionStatus: How one Benford split transaction ended (bead libspiffy-wdch). A split is recorded as a deferred payment before it is broadcast (bead libspiffy-ypp), so every status but notRecorded names a transaction the wallet lists (GetDeferredPaymentsQuery) until the network settles it.

Exceptions / Errors

CoordinatorFailure: Why WalletCoordinator.ask has no reply to return.

coordinator library

Classes

Enums

Exceptions / Errors

libspiffy package

coordinator library