internals library

LibSpiffy Internals - Domain event-sourcing types for advanced use.

Most applications should use package:libspiffy/coordinator.dart instead. This library exposes the aggregate commands, domain events, and actor-level messages used internally by the coordinator. Import this only if you are building custom actors, extending aggregates, or writing integration tests that need direct access to the event-sourcing layer.

Classes

AcceptChannelCommand
Server accepts a channel request
AcceptChannelMessage
Request to accept a channel as server
AcknowledgePaymentCommand
Server acknowledges payment with pre-computed server signature
AcknowledgePaymentMessage
Request to acknowledge a payment as server
AddressDiscoveredEvent
Event fired when an address is discovered during import
AddressGeneratedEvent
Event fired when a new address is generated
AddressLabelUpdatedEvent
Event fired when an address label is updated
AddWatchAddressCommand
Adds a watch address to the wallet (bead libspiffy-p4kv): an address the wallet holds no key for whose payments it attributes to itself.
AllUTXOsSplitCompletedEvent
Event fired when all UTXOs have been processed.
AnchorKeyIssuedEvent
The wallet issued its anchor key for a context (bead libspiffy-fdal): anchorPublicKey is the key at m/3'/0'/k1'/k2' for anchorContext (hex). Journaled once per context, so a hand-off that names only the anchor is matched to the context that derives its key. Nothing here is a private key.
ApplyDeferredSpendCommand
The network has the transaction txid: the wallet's UTXOs it spends are spent, and its outputs the wallet holds pending become available.
BeefAncestor
A transaction a received BEEF carried as an ancestor of the paid transaction, with its BUMP when it is proven (bead libspiffy-zsh).
BitcoinWalletAggregate
Bitcoin wallet aggregate root implementing event sourcing
Brc100KeyOperationCommand
Runs the BRC-100 key operation request with a BRC-42 child of the wallet's anchor key for anchorContext: the anchor is the root key of BRC-100's key derivation, so an anchor issued as a BRC-100 identity signs, encrypts and derives as that identity. Journals nothing.
BroadcastTransactionCommand
Command to broadcast a transaction
BuildFundingTransactionCommand
Command to build and sign a payment channel funding transaction.
BuildRefundTransactionMessage
Request to build refund transaction (client side, after server accepts)
CancelDeferredSpendCommand
Cancels the outstanding deferred payment txid and releases its inputs.
CancelInvoiceCommand
Command to cancel an invoice
ChannelAcceptedEvent
Server has accepted a channel request
ChannelAcceptedResponse
Response to channel acceptance
ChannelClosedEvent
Channel has been closed (settlement TX broadcast)
ChannelClosedResponse
Response to channel close
ChannelClosingEvent
Channel close has been initiated
ChannelCommand
Base class for all channel commands
ChannelCommandCheck
Asks a channel aggregate whether it would take command, without taking it: the command runs through the aggregate's own handler and nothing is journaled (bead libspiffy-1a5k).
ChannelCommandCheckResponse
The aggregate's answer to ChannelCommandCheck: error is why it refuses the command, and null when it would take it.
ChannelCommandResult
What PaymentChannelAggregate answers a command with (bead libspiffy-kl4i).
ChannelDetailsQueryMessage
Asks the channel manager for a channel's full journaled state (the aggregate is recovered from its journal when not loaded); answered with FullChannelStateResponse, success: false for an unknown channel. The P2P adapter rebuilds its channel records from it after a restart (libspiffy-fsy, libspiffy-36f).
ChannelEvent
Base class for all channel events.
ChannelExpiredEvent
Channel has expired (lockTime elapsed).
ChannelExpiredResponse
Response to channel expiry recording
ChannelFundingRetriedResponse
The outcome of a RetryChannelFundingMessage.
ChannelInitiatedResponse
Response to channel initiation
ChannelOpenedEvent
Channel is now open (funding TX broadcast)
ChannelOpenedResponse
Response to channel opening
ChannelOpenResentResponse
The channel_open payload of an open channel, rebuilt from its journaled state (bead libspiffy-1n3), or why there is none to send.
ChannelRefundClaimedResponse
Response to a refund claim.
ChannelRejectedEvent
Server has rejected a channel request
ChannelRequestedEvent
Channel has been requested by a client
ChannelState
State for a payment channel aggregate
ChannelStateQuery
Direct query to aggregate for full state (for building transactions)
ChannelStateResponse
Response with channel state
CheckInvoiceStatusCommand
Command to check invoice status.
ClaimRefundCommand
Claim refund after channel expiry (non-cooperative close)
ClaimRefundMessage
Claim the refund of an expired channel: broadcast it, journal the claim and record it in the wallet (bead libspiffy-cqc (b)).
CleanupExpiredReservationsCommand
Command to clean up expired UTXO reservations
CloseChannelCommand
Initiate channel close (cooperative)
CloseChannelMessage
Request to close a channel
CompleteDeferredSpendCommand
Completes the outstanding deferred payment txid, a transaction the wallet signed only in part: rawHex is the same transaction with the counterparty's signatures on the inputs the wallet does not hold. A sale in one transaction is the case: the buyer signs its coin, the seller its token, and the first to sign records a half that can never be broadcast.
ConfirmTransactionCommand
Command to confirm a pending transaction (transition from pending to confirmed)
CreateInvoiceCommand
Command to create a new invoice
CreateWalletCommand
Command to create a new wallet
DeferredSpendCompletedEvent
The half-signed deferred payment txid was completed by its counterparty as completedTxid (CompleteDeferredSpendCommand). The completed transaction's own recording, journaled just before this event, took over the hold on completedUtxoKeys; txid is resolved as DeferredPaymentState.completed and its own pending outputs are voided.
DeferredSpendReclaimedEvent
A deferred payment is being reclaimed: the wallet recorded its own transaction (reclaimTxid) spending that payment's held inputs back to itself, and the hold on those inputs moved to it (bead libspiffy-87a).
DeferredTransactionCancelledEvent
The user cancelled an outstanding deferred payment the network did not know (or the wallet cancelled a payment it never handed over): its held inputs return to the status they had before they were reserved. This does not revoke a signed transaction the recipient holds.
DeferredTransactionFailedEvent
ARC reported a deferred payment definitively failed (REJECTED; journals written before bead libspiffy-ey2 also hold this event for DOUBLE_SPEND_ATTEMPTED and replay it as written): its held inputs return to the status they had before they were reserved.
DeleteWalletCommand
Command to permanently delete a wallet
DeriveType42DestinationCommand
Derives a type-42 destination for paying the holder of anchor key anchorPublicKey (beads libspiffy-zxkd, libspiffy-fdal): the wallet's next payer key B (m/3'/1'/n', never used twice) and invoiceNumber give C = A + HMAC-SHA256(ECDH(b, A), invoiceNumber)·G.
ExpireChannelCommand
Record that a channel has expired (lockTime elapsed).
ExpireChannelMessage
Request to record that a channel has expired (lockTime elapsed).
ExpireInvoiceCommand
Command to expire an invoice
FinalizeCloseCommand
Finalize channel close after settlement TX is broadcast
FullChannelStateResponse
Full channel state response from aggregate (for building transactions)
FundingBroadcastFailedEvent
Broadcasting the client's funding transaction failed (libspiffy-9f7).
FundingBroadcastStartedEvent
The client is about to broadcast its funding transaction (libspiffy-9f7).
FundingFailedEvent
The client's sent funding can never be mined (bead libspiffy-4kfq): the wallet failed it, because a coin it spends is already spent by a confirmed transaction or ARC rejected it. The server never opens the channel on it, so the client stops sending channel_open; the channel never opened and nothing is locked in it.
FundingRecordedInWalletEvent
The client wallet recorded the funding transaction (libspiffy-fsy).
FundingSentEvent
ARC took the client's funding broadcast (bead libspiffy-jark).
GenerateAddressCommand
Command to generate a new address
ImportWalletFromXprivCommand
Command to import a wallet from xpriv with transaction history.
InitiateChannelMessage
Request to initiate a new payment channel as client
InvoiceAggregate
Invoice aggregate root implementing event sourcing
InvoiceCancelledEvent
Event fired when an invoice is cancelled
InvoiceCommand
Base class for all invoice commands
InvoiceCreatedEvent
Event fired when an invoice is created
InvoiceEvent
Base class for all invoice-related domain events
InvoiceExpiredEvent
Event fired when an invoice expires
InvoicePaidEvent
Event fired when an invoice is paid
InvoiceStatusChangedEvent
Event fired when invoice status changes.
IssueAnchorKeyCommand
Issues the wallet's anchor key for anchorContext (bead libspiffy-fdal): the key payers derive type-42 destinations from, one per context (m/3'/0'/k1'/k2'), so identities sharing the wallet publish unrelated anchors. The context is opaque bytes, such as an identity key followed by a rotation epoch; an empty one is refused. Journals the anchor the first time it is issued for a context (AnchorKeyIssuedEvent), so a hand-off that names only the anchor is matched to its context; answers from that record after.
LegacyWatchAddress
A watch address the read model recorded before watch addresses were journaled (an address row with purpose watch).
LookupType42AddressesCommand
Asks which type-42 addresses the wallet knows the transaction rawTransaction (hex) pays: ones it derived as a payer, and ones payers derived from its anchor key. Journals nothing.
MarkInvoicePaidCommand
Command to mark an invoice as paid
MarkUTXOAvailableCommand
Command to mark UTXO as available for spending
OpenChannelCommand
Mark channel as open after funding transaction is broadcast.
OpenChannelMessage
Message to finalize channel opening after funding TX is broadcast
PaymentAcknowledgedEvent
Payment has been acknowledged (server side - verified and countersigned)
PaymentAcknowledgedResponse
Response to payment acknowledgment
PaymentChannelAggregate
Payment Channel Aggregate Root
PaymentChannelManagerActor
Payment Channel Manager - Orchestrates all channel operations
PaymentCountersignedEvent
The client held the server's countersignature of the latest payment (bead libspiffy-z2px).
PaymentRecordedEvent
Payment has been recorded (client side - built and signed)
PaymentRecordedResponse
Response to payment recording
PreloadWalletCommand
Command to preload a wallet aggregate at startup
ProvideRefundSignatureCommand
Client records the server's signature on its refund transaction.
QueryChannelStateMessage
Query current state of a channel
ReceiveUTXOCommand
Command to record a received UTXO.
ReclaimDeferredSpendCommand
Reclaims the outstanding deferred payment txid: records rawHex, the wallet's own signed transaction spending that payment's held inputs back to itself, and moves the hold on those inputs to it (bead libspiffy-87a).
ReconcileDeferredSpendsCommand
Journals the holds of outgoing transactions recorded with a deferred spend before holds were journaled (journals written before bead libspiffy-7p2).
ReconcileWatchAddressesCommand
Journals the watch addresses the read model recorded before watch addresses were journaled (bead libspiffy-p4kv), so that the wallet knows them and a read model rebuilt from the journal keeps them.
RecordDelegatedAddressesCommand
Records addresses a service issued on the wallet's delegated chain (m/2/{index}, AddressChain.delegated) while the wallet was offline, so that a payment to them can be imported and spent (bead libspiffy-m8qu; spv-understanding.md, "Payment modes").
RecordFundingBroadcastFailedCommand
Client records that broadcasting its funding transaction failed; emits FundingBroadcastFailedEvent and leaves the channel unopened.
RecordFundingFailedCommand
Client records that its sent funding can never be mined: the wallet failed it (a coin it spends is already spent by a confirmed transaction, or ARC rejected it). Emits FundingFailedEvent; nothing more is sent for the channel (bead libspiffy-4kfq).
RecordFundingFailedMessage
The wallet failed the client's sent funding fundingTxId of channelId: it can never be mined (bead libspiffy-4kfq). The manager journals it (RecordFundingFailedCommand); nothing is answered.
RecordFundingInWalletCommand
Client records that its wallet holds the funding transaction of the broadcast in progress; emits FundingRecordedInWalletEvent (libspiffy-fsy).
RecordFundingSentCommand
Client records that ARC took its funding broadcast; emits FundingSentEvent (bead libspiffy-jark).
RecordImportedTransactionCommand
Command to record an imported transaction (from blockchain scan)
RecordOutgoingTransactionCommand
Command to record an outgoing transaction (payment created by this wallet) Records transaction in PENDING state until payment is confirmed by recipient
RecordPaymentCommand
Client records a payment with pre-built and pre-signed payment TX
RecordPaymentMessage
Request to record a payment as client
RecordRefundBuiltCommand
Client journals the refund transaction it built, with its own signature and the signed funding transaction the refund spends (libspiffy-b83).
RecordRefundSignatureMessage
Request to record server's refund signature (client side, received via P2P)
RecordReturnLegInWalletCommand
This side's wallet holds the transaction that ended the channel and paid it back — a cooperative settlement, or a refund after expiry (bead libspiffy-lfrv).
RecordServerAcceptanceCommand
Client records that the server accepted the channel
RecordServerAcceptanceMessage
Client records that server accepted the channel (stores server pubkey/address)
RecordServerOpenedMessage
The server says it opened the channel on fundingTxId:fundingOutputIndex (channel_opened, bead libspiffy-jark): the client journals its open. Answered with ServerOpenRecordedResponse.
RecordSettlementMessage
The settlement a channel's server broadcast, handed to the client in channel_closed (bead libspiffy-u6q6): the client checks it is its latest payment, fully signed, records its return leg and closes the channel. Answered with ChannelClosedResponse.
RecordTransactionAncestorsCommand
Keeps the ancestors of txid, a transaction this wallet recorded, that the BEEF it was settled with carried (SettleBEEFCommand, bead libspiffy-yiba): the parents of inputs the wallet does not own, a counterparty's transactions it spends, back to proven ones with their BUMPs. Without them no outgoing BEEF can spend txid's outputs before txid is mined and proven.
RecordTransactionNetworkStatusCommand
Records a network status observed for txid (ARC or the data source).
RecordType42AddressesCommand
Records addresses payers derived from the wallet's anchor key with type-42 (BRC-42) while the wallet was offline, so that a payment to them can be taken in and spent (bead libspiffy-zxkd; spv-understanding.md, "Payment modes").
RefundBuiltEvent
Refund transaction has been built (client side).
RefundClaimedEvent
Refund has been claimed after channel expiry
RefundCountersignedEvent
Server has signed the refund transaction.
RefundSignatureRecordedResponse
Response to recording refund signature
RefundTransactionBuiltResponse
Response with built refund transaction
RefundTransactionSignedResponse
Response with refund signature
RegisterDiscoveredAddressCommand
Command to register a discovered address (from wallet import)
RejectChannelCommand
Server rejects a channel request
ReleasedDeferredInput
A UTXO a deferred payment's failure or cancellation released, and the status it returned to.
ReleaseUTXOCommand
Command to release a UTXO reservation
ReleaseUTXOsCommand
Command to release UTXO reservations
RenewUTXOReservationCommand
Command to renew/extend a UTXO reservation
RequestChannelCommand
Client requests to open a channel with a server
RequestRefundSignatureCommand
Server journals its signature on the client's refund transaction.
ResendChannelOpenMessage
Ask for the channel_open payload of a channel that is already open, so the adapter can send it to the server again (bead libspiffy-1n3).
ReserveUTXOCommand
Command to reserve a UTXO for a transaction
ReserveUTXOsCommand
Command to reserve UTXOs for a transaction
RetryChannelFundingMessage
Re-broadcast the funding transaction of a channel whose funding broadcast failed (bead libspiffy-1n3).
ReturnLegRecordedInWalletEvent
This side's wallet holds the transaction that ended the channel and paid it back (bead libspiffy-lfrv).
RevertTransactionConfirmationCommand
Command to take back the confirmation of txid (audit 3b0).
ServerAcceptanceRecordedEvent
Client has recorded server's acceptance (server pubkey/address)
ServerAcceptanceRecordedResponse
Response to RecordServerAcceptanceMessage: success: false carries the channel aggregate's rejection (e.g. the channel is not pending).
ServerOpenRecordedResponse
Whether the client journaled its open on the server's word.
SignInputCommand
Command to sign one input of a transaction with the wallet key at an explicit derivation path, against a caller-supplied subscript and amount.
SignMultisigTransactionCommand
Command to sign a multisig transaction input Used for payment channels where we need to sign one input of a 2-of-2 multisig
SignRefundTransactionMessage
Request to sign refund transaction (server side)
SignTransactionCommand
Command to sign a transaction
SignWithAnchorKeyCommand
Signs SHA-256(message) with the wallet's anchor key for anchorContext, for binding that anchor to an identity (a registration such as NodeCast's). Journals nothing.
SpendUTXOCommand
Command to spend a UTXO
SplitUTXOsToBenfordCommand
Command to split wallet UTXOs into Benford distribution for privacy
StartFundingBroadcastCommand
Client asks to broadcast its funding transaction (libspiffy-9f7).
TransactionAncestorsRecordedEvent
The ancestors of txid, a transaction this wallet recorded, that the BEEF it was settled with carried (see RecordTransactionAncestorsCommand in wallet_commands.dart). Stored as a received BEEF's are (TransactionImportedEvent.ancestors): raw transactions in the txid-keyed ancestor store, BUMPs as merkle proofs.
TransactionBroadcastEvent
Event fired when a transaction is broadcast
TransactionConfirmationRevertedEvent
Event fired when a transaction's confirmation is taken back (audit 3b0): its block left the active chain, or its proof does not match the block header at the proof's height.
TransactionConfirmedEvent
Event fired when a pending transaction is confirmed
TransactionImportedEvent
Event fired when a transaction is imported
TransactionNetworkStatusCheckedEvent
A network status observed for a deferred payment (ARC or the configured data source). The periodic status scan journals a status only when it differs from the last one; an explicit check or broadcast always does.
TransactionRecordedEvent
Event fired when an outgoing transaction is recorded (in pending state)
TransactionSignedEvent
Event fired when a transaction is created Event fired when a transaction is signed
TransactionSpendDeferredEvent
A recorded outgoing transaction's spend is deferred: the wallet holds its inputs until the network settles it (bead libspiffy-7p2).
TransactionStatusUpdatedEvent
Event fired when a transaction's status is updated (e.g., from ARC status transitions)
TransactionVoidedEvent
A transaction handed to this wallet can never be mined: spentInput, an input of it, is already spent by spentBy, which a merkle proof confirms. Its row is failed and its pending outputs are voided (see VoidUnsettledTransactionCommand).
Type42AddressRecordedEvent
A payer's type-42 address was recorded (bead libspiffy-zxkd): address is the anchor key's type-42 child for derivation, which the wallet derived itself from its anchor private key. The wallet signs for it with that child key, derived again for each signature; the key itself is never journaled.
Type42DestinationDerivedEvent
The wallet derived a type-42 destination as a payer (bead libspiffy-zxkd): it used payer key Type42Destination.payerKeyIndex, which it never uses again, and destination is the hand-off the recipient takes the payment in with. Nothing here is a private key.
UpdateAddressLabelCommand
Command to update an address label
UpdateTransactionStatusCommand
Command to update a transaction's status (e.g., from ARC status transitions)
UpdateUTXOConfirmationsCommand
Command to record a confirmation count a caller reports for a UTXO.
UpdateWalletConfigurationCommand
Command to update wallet configuration
UTXOConfirmationUpdatedEvent
Event fired when a confirmation count reported for a UTXO is recorded.
UTXOMarkedAvailableEvent
Event fired when UTXO becomes available for spending
UTXOReceivedEvent
Event fired when a UTXO is received
UTXOReleasedEvent
Event fired when a UTXO reservation is released
UTXOReservationExpiredEvent
Event fired when UTXO reservation expires.
UTXOReservationPlacedEvent
Event fired when UTXOs are reserved for transaction creation.
UTXOReservationReleasedEvent
Event fired when UTXO reservation is released.
UTXOReservationRenewedEvent
Event fired when a UTXO reservation is renewed/extended
UTXOReservedEvent
Event fired when a UTXO is reserved for a transaction
UTXOSpentEvent
Event fired when a UTXO is spent
UTXOSplitCompletedEvent
Event fired when a single UTXO has been successfully split.
UTXOSplitInitiatedEvent
A split the wallet aggregate was asked for, in a journal written by an earlier release.
VoidUnsettledTransactionCommand
Records that txid, a transaction handed to this wallet that the network has not settled, can never be mined: an input of it is already spent by spentBy, a transaction a merkle proof confirms (checked against the local header chain by the caller).
WalletCommand
Base class for all wallet commands
WalletConfigurationUpdatedEvent
Event fired when wallet configuration is updated
WalletCreatedEvent
Event fired when a wallet is created
WalletDeletedEvent
Event fired when a wallet is permanently deleted
WalletImportCompletedEvent
The import finished.
WalletImportFailedEvent
The import failed or was cancelled (metadata['cancelled'] == true).
WalletImportNotification
Progress of a wallet import, broadcast in-process by the ImportActor.
WalletImportProgressEvent
Periodic progress of a running import.
WalletImportStartedEvent
An import job has created (or confirmed) the wallet and is starting.
WalletImportTransactionConfirmedEvent
The wallet aggregate acknowledged (or rejected) an imported transaction.
WalletImportUTXOConfirmedEvent
The wallet aggregate acknowledged (or rejected) an imported UTXO.
WatchAddressAddedEvent
A watch address was added to the wallet (bead libspiffy-p4kv).

Enums

ChannelRole
Role in a payment channel
ChannelStatus
Status of a payment channel