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.
- 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
- 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: falsefor 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_openpayload 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
- 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
- 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
- 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).
- FundingRecordedInWalletEvent
- The client wallet recorded the funding transaction (libspiffy-fsy).
- 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.
- LegacyWatchAddress
-
A watch address the read model recorded before watch addresses were
journaled (an address row with purpose
watch). - 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.
- RecordFundingBroadcastFailedCommand
- Client records that broadcasting its funding transaction failed; emits FundingBroadcastFailedEvent and leaves the channel unopened.
- RecordFundingInWalletCommand
- Client records that its wallet holds the funding transaction of the broadcast in progress; emits FundingRecordedInWalletEvent (libspiffy-fsy).
- 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)
- 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. - RecordTransactionNetworkStatusCommand
- Records a network status observed for txid (ARC or the data source).
- 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_openpayload 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: falsecarries the channel aggregate's rejection (e.g. the channel is not pending). - 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
- 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).
- 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)
- 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.
- 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