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 commands
libspiffy.coordinator.tell(CreateWalletCommand(walletId: 'my-wallet', name: 'My Wallet'));

// Subscribe to events
libspiffy.coordinatorEvents?.listen((event) {
  if (event is WalletCreatedEvent) { ... }
  if (event is PaymentReadyEvent) { ... }
});

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
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 stored Block headers were stored: how many, and the heights they span.
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: Broadcast to Arc failed (transaction queued for retry via duraq)
CancelDeferredPaymentCommand: Cancel an outstanding deferred payment and release its inputs. Answered with DeferredPaymentCancelledEvent.
ChannelClosedEvent: Channel closed
ChannelFundingRetriedEvent: another retry.
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.
ChannelP2PMessageToSendEvent: Outgoing P2P message that the app must transmit to the peer
ChannelP2PReceived: Incoming P2P message for a payment channel.
ChannelPayCommand: Make a payment over an open channel
ChannelPaymentEvent: Payment made or received on a channel
ChannelRefundClaimedEvent: The outcome of a RetryChannelFundingCommand (bead libspiffy-1n3).
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.
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
CoordinatorEvent: Base class for all coordinator events emitted on the event stream.
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.
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: Error from the coordinator
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).
GetBalanceQuery: Query wallet balance
GetDeferredPaymentsQuery: List or search the wallet's deferred payments. Answered with DeferredPaymentsResponse (or an ErrorEvent with source getDeferredPayments).
GetTransactionDetailQuery: Query specific transaction detail
GetTransactionsQuery: Query wallet transactions
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).
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
RefreshWalletCommand: Refresh wallet data
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.
ValidateBEEFCommand: Validate incoming BEEF data (structural + SPV validation)
WalletCoordinatorActor: The canonical public interface for third-party apps using LibSpiffy.
WalletCreatedEvent: Wallet successfully created
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.

coordinator library

Classes

Enums

libspiffy package

coordinator library