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
- AddLockKeyCommand
-
Gives the wallet a lock key (bead spiffyvault-mnz.5): a private key
outside its HD tree that HODLocker coins may be locked to, such as the
RelayX paymail key at
m/0'/236'/0'/0/0of a RelayX seed. The key is kept in secure storage, never in an event; a LockKeyAddedEvent journals its address, which is then one of the wallet's: a HODLocker output locked to it is the wallet's, and the wallet signs its unlock with the key. - 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: 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
- 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 asDeferredPaymentState.completedand 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 giveC = 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). - LockKeyAddedEvent
- The wallet took a lock key (bead spiffyvault-mnz.5): address is the P2PKH address of a private key outside its HD tree, kept in secure storage. The address is one of the wallet's from now on, signed for with that key.
- 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").
- RecordType42DestinationsCommand
- Records type-42 destinations the wallet derived as a payer and no longer holds (spiffyvault-56z follow-up): a wallet imported again by its phrase starts its payer keys at 0, and would use again the keys its earlier payments used. The app hands back the derivations its payment records kept.
- 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
- RejectedTransactionVoidedEvent
- ARC reported txid, a transaction handed to this wallet, REJECTED: its pending outputs are voided (see VoidRejectedTransactionCommand). A later SEEN_ON_NETWORK or proof of txid makes them available again.
- 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). - 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.
- SignMessageCommand
- Signs message as a Bitcoin Signed Message with the wallet key whose public key hashes to pubkeyHash (40 hex): proof, to whoever checks it against that key's address, that this wallet holds it. Journals nothing.
- 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.
- VoidRejectedTransactionCommand
- Records that ARC reported txid, a transaction handed to this wallet, REJECTED (bead spiffyvault-izz): its pending outputs become UTXOStatus.voided, so they stop counting as funds on the way. Its row is failed by UpdateTransactionStatusCommand, as before.
- 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