libspiffy 6.0.0
libspiffy: ^6.0.0 copied to clipboard
An actor-based Bitcoin SV SPV wallet library: event-sourced wallets, BEEF payments with merkle-proof validation, ARC broadcast, payment channels and pluggable token scripts.
6.0.0 #
Breaking: every default network is now mainnet, a wallet created or imported without a network follows the network the system was initialized with, and BroadcastCallbackConfig.bridgeTestnet() is removed. Up to 5.17.x, a network you did not name was testnet; now it is mainnet, where coins are real. A network you pass behaves exactly as before.
- Requires dartsv 3.1.4. Earlier dartsv refused valid mainnet addresses shorter than 34 characters (about 3 in 100), which mainnet makes common: paying, scanning or deriving such an address threw
AddressFormatException. - What changed. Each of these used testnet when no network was given and now uses mainnet:
LibSpiffyActorSystem.initialize(networkType:)andinitializeLibSpiffy(networkType:):'main'instead of'test'. That selects the mainnet genesis header, DNS seeds and address encoding, and, with noarcConfig, the mainnet Arcade (ArcServiceConfig.bsvaArcadeMainnet()).- The system's
importWalletFromXpriv,importWalletFromWifandresumeWalletImport:'main'. ImportWalletMessage,SPVActorandPaymentChannelManagerActorbuilt directly: mainnet.NetworkName.canonical(null)is'mainnet',NetworkName.toDartsv(null)isNetworkType.MAIN, andNetworkName.isMainnet(null)is true. SoWalletRowRules.defaultNetwork(the network a wallet row stored withReadModelStorage.storeWalletand nonetworkTypegets),WalletState.emptyandWalletReadModel.empty,NetworkParams.forNetwork(null), aBlockHeaderChainbuilt withoutparams, and a wallet aggregate given aCreateWalletCommandwith no network are all mainnet. A name that is given but not recognised still means testnet.- The
dartsv.NetworkTypeparameters ofDartSVCryptoService(the constructor andmnemonicToHDPrivateKey,generateAddress,generateRandomPrivateKey,privateKeyToWIF,privateKeyFromWIF,deriveAddress), the same methods onCryptoService,TransactionAnalyzer,ScriptTypeRegistryandPP1LockBuilder:NetworkType.MAIN.
- A wallet follows
initialize()unless its command names a network. Through the coordinator, aCreateWalletCommandwhosewalletMetadatahas no'network'entry, and anImportWalletCommandwith nonetworkType, create the wallet on the network passed toinitialize(networkType:). Up to 5.17.x such a wallet was always testnet, whatever the system's network, so a mainnet system created testnet wallets unless every command named mainnet. A network the command names still wins.ImportWalletCommand.networkTypeis nowString?(null: the system's network); code that read it as aStringhandles null. - How to stay on testnet. Pass
networkType: 'test'toinitialize()(orinitializeLibSpiffy()); wallets created and imported through the coordinator follow it. Pass the network yourself where you build lower-level parts directly:networkType: 'test'toImportWalletMessageandSPVActor, a'network'entry inwalletMetadatafor aCreateWalletCommandsent to the wallet aggregate orCreateWalletMessagesent to the wallet manager, andnetwork: dartsv.NetworkType.TEST(ornetworkType:on the constructors) for the crypto services. Wallets already stored keep the network they were created with; they need nothing. - An
ImportWalletCommandwith amnemoniccreates its wallet on the import's network. It created the wallet with no network, so the wallet took the default whatever the import asked for (testnet before this release, which made a mainnet mnemonic import a testnet wallet). BroadcastCallbackConfig.bridgeTestnet()is removed. libspiffy names no callback bridge: the bridge'scallbackUrl,bridgePeerIdandbridgeX25519PubHexare the app's configuration, given toBroadcastCallbackConfig(...). An app that used the preset builds the config from its own settings.- The callback token and the status envelope are documented in the library itself.
mintCallbackTokenandparseBroadcastStatusEnvelopesay what a bridge must decode and send: the token's CBOR body, signature domain, key derivation and cipher, and the envelope's JSON. The vectors intest/data/broadcast_token_vectors.jsonuse test keys only. - Every layer still resolves an unspecified network to the same one, now mainnet:
NetworkName, the storage backends, the wallet aggregate and the actor system's defaults. Inside a running system, that one is the system's network.
5.17.1 #
- The fill of the older headers completes against a CDN whose chunks start at height 1. headers.overnode.net serves heights 1 and up; the genesis block is not on it. Once every header down to height 1 was held, each step looked for a chunk holding height 0, found none and failed, so the fill was retried for ever and never reported complete (an app showed it at 99%). Now the last step stores the genesis block from the code, after checking that the header held at height 1 names it, and the fill reports complete. A CDN that does serve height 0 works as before.
5.17.0 #
A fresh install starts its header chain at a built-in checkpoint (spiffyvault-emk.1), parked receives wait for the header they need (spiffyvault-emk.2), restored coins wait for theirs (spiffyvault-emk.4), and the headers below the checkpoint are filled in from the CDN (spiffyvault-emk.3); an unknown deferred payment has its own error code (spiffyvault-1zp)
-
HeaderCheckpoint: the newest headers of a network, shipped with an app. A compact file (.svhc): the first header whole, then 48 bytes a header withprevBlockleft out and rebuilt on load, then the last header's hash. 200,000 mainnet headers are 9.6 MB.decodechecks every header's proof of work and the closing hash;loaddoes it on another isolate (about a second for 200,000 on a laptop). -
LibSpiffyActorSystem.initialize(headerCheckpoint: bytes): on an empty header store the chain is anchored at the window's lowest header, not genesis, and the rest of the window is stored in the background before the CDN and peers are asked for anything, so a new install catches up only from the window's newest header. A start stopped part way through carries on from the stored tip. An install that already holds headers keeps its anchor (BlockHeaderChain.chooseAnchor); one that synced from genesis but fell behind the window's top is brought up to it from the window. WithoutheaderCheckpointnothing changes. -
BlockHeaderChain.chooseAnchorandBlockHeaderChain.extendFromWindoware the two steps above, for a host that builds its own chain. -
tool/build_header_checkpoint.dartbuilds the window from a header CDN package (fetch_woc_headers_to_cdn.dart's output): it checks the whole chain from the in-code genesis block (manifest SHA-256s, linkage, proof of work) and writes the newest--windowheaders (default 200,000). -
Transaction status can be pushed instead of polled, through the broadcast-bridge.
LibSpiffyActorSystem.enableBroadcastCallbacks(config, signer)makes every submission carry the bridge'sX-CallbackUrland a freshX-CallbackToken(mintCallbackToken: a CBOR body signed by the user's Ricochet identity key through the app'sCallbackTokenSigner, encrypted to the bridge's X25519 key; byte for byte the bridge's own test vectors). The Broadcaster's MINED or REJECTED then reaches the user's Ricochet mailbox, and the app hands it toapplyBroadcastStatusEnvelope(payload), which applies each item exactly as a polled answer: MINED confirms nothing until its merkle path checks against our own header (a forged callback fails there), and a duplicate or stale item is a no-op. A token that cannot be made never holds a submission back, and polling goes on as the safety net. Off unless the app turns it on, which it does only once the mailbox exists and grants the bridge write access.BroadcastCallbackConfig.bridgeTestnet()is the testnet bridge while it is verified. -
ArcService.submitTransactionandsubmitBatchTransactionstakecallbackToken, sent asX-CallbackTokenwithX-CallbackUrl. A subclass that overrides them adds the parameter. -
A parked receive is replayed when we hold the header at every height its proofs need. It was replayed once the tip reached its
neededHeight, which assumed headers arrive only upwards from genesis. A chain that starts at a built-in checkpoint (spiffyvault-emk) has no headers below it until they are filled in, so a receive whose proof is older than the checkpoint would have been replayed on every block, asking the network for the missing header each time, and parked again. The replay now checks the stored header at each needed height first (the subject's proof's height, or every BUMP's when the subject has none), and reads the parked rows a page at a time so receives still waiting for an older header never hide newer ones behind them. -
BlockHeadersBackfilledMessage(fromHeight, toHeight): tells SPVActor that headers were stored below the tip. It checks the pendingHeader proofs and replays the parked receives that can now be judged; the tip, revived proofs and ARC's pending-output check are untouched. The backfill below sends it. -
The headers below the checkpoint are filled in from the header CDN, newest first, down to genesis (spiffyvault-emk.3). With
headerCheckpointandcdnBaseUrl, once the start-up sync is done a background fill fetches the CDN chunk right below the lowest header held, one chunk (about 50,000 headers, 4 MB) a step; some 125 MB in all on mainnet. The CDN is not trusted: the header we hold names the hash of the one below it, so each run must end on that hash and link all the way down, every header must carry its own proof of work, and height 0 must be the network's genesis block; a run that fails stores nothing. The tip is untouched. After each step SPVActor is sentBlockHeadersBackfilledMessage, so proofs and payments waiting for those headers settle (restored coins among them, emk.4). Where the fill stopped is read back from storage, so a restart carries on; once height 0 is held the next start is anchored at genesis. Peers are not used: they hand out headers upwards from a block we know, never down. -
initialize(mayBackfillHeaders:, onHeaderBackfillProgress:): before each step the fill asksmayBackfillHeaderswhether downloading is all right now (an app on a phone answers true only on Wi-Fi); while it says no, it asks again every 5 minutes. Null: always. A failed step is tried again after 1 minute, doubling up to 30.onHeaderBackfillProgress(lowestHeight, checkpointHeight)is called at the start and after each step;lowestHeight0 means complete. Shutdown ends the fill and any wait. -
BlockHeaderChain.lowestHeldHeight()andBlockHeaderChain.storeBelow(headers, startHeight),CdnHeaderSyncService.backfillNext()returning aCdnBackfillStep, andHeaderBackfillRunnerare those parts, for a host that runs its own. -
ReadModelStorage.getPendingReceivesUpToHeighttakesafter: (createdAt:, txid:)to continue a listing past a row. Implemented by the in-memory, Isar and Postgres storages; no schema change. -
A header-stored notification below the tip no longer rechecks proofs and replays receives only up to that height: both run up to the tip.
-
A restored coin is spendable only once its merkle proof checks against a header we hold (spiffyvault-emk.4). A wallet import or address scan made every coin it found available and its transaction confirmed whenever the data source sent a proof, even when no header was held at that height. With a chain that starts at a checkpoint, that would have been every coin older than the checkpoint. Such a coin is now pending, with no height, and its transaction is recorded with the BUMP but no height. The read model keeps the transaction pending and the proof pendingHeader (also when the header is held by the time the event is handled, since the wallet has not confirmed it), and SPVActor confirms the transaction and makes the coins available when the header arrives, as for any proof that came before its header. A coin whose proof did check is available at once, as before.
-
A pending coin that nothing reserves or holds can be marked spent by an unproven spend. Only an available coin, or a coin the wallet's own recorded payment spends, could be. A restore records a coin with an unchecked proof as pending, and the restored transaction that spent it must still mark it spent, or the coin would turn spendable once its header arrived. A coin a deferred payment holds is still refused.
-
SpiffyErrorCode.noSuchPayment: the wallet has no record of the deferred payment named (spiffyvault-1zp).DeferredPaymentStatusEvent,DeferredPaymentBroadcastEvent,DeferredPaymentCancelledEvent,DeferredPaymentCompletedEventandDeferredPaymentReclaimedEventnow carryerrorCode, set to it when the payment is unknown (for example, its wallet was deleted), so an app can stop following the payment without reading the Englisherror. Cancelling an unknown payment on the aggregate throws aSpiffyStateErrorwith this code, still aStateError. An app with an exhaustiveswitchonSpiffyErrorCodeadds a case.
5.16.0 #
Payments to an address show while still in the mempool, and a payment someone sent that the network never takes stops showing as on the way for ever
-
A named-address scan finds payments still in the mempool (spiffyvault-bld).
ImportWalletCommand(resume: true, addresses: [...])read mined history only, so a payment to an address showed some ten minutes after it was made, once a block held it. The scan now also reads each address's unspent outputs from the data source and, for every unmined transaction the wallet does not hold, builds its BEEF: the transaction and its ancestors back to mined ones with their merkle proofs (UnminedPaymentFinder). The coordinator checks each with the wallet's BEEF check before it reports the scan complete, so each is answered with its ownBEEFValidationResultEvent, as a payment handed to the wallet is, and comes in as on the way.ImportCompleteEvent.unminedPaymentscounts those taken;WalletImportCompletedEvent.unminedPaymentBeefscarries them from the import. Nothing the data source says is trusted: the BEEF check is SPV against the stored headers. A transaction whose lock time is still to come is left out (the network refuses it until then, and it can be replaced), and so is one the data source cannot deliver whole; the block brings it to a later scan. -
A payment handed to the wallet that ARC does not know is sent to ARC again (spiffyvault-95e). It stayed pending, its coins on the way, for ever: the payer may never have broadcast it, or ARC dropped it. The status scan now resubmits it, at most once per
ARCActor.unknownResendInterval(30 minutes), and acts on ARC's answer as on any submission's: on the network makes its coins available, REJECTED voids them (below), and a competing spend that is mined voids them as before. Only an incoming transaction that is not a deferred payment of the wallet, and only a final one, is resent. No time limit voids a payment nobody answers for: the resend is expected to settle every case, and a time limit is added only if one turns out not to. -
An invoice with several addresses and no outputs list is paid in full (spiffyvault-bnb, spiffyvault-2ct.7). The amount was split as
amount ~/ nper address and the remainder went to the fee, so a payee that asked for 1001 sats over two addresses was paid 1000 and refused it as short. The last address now takes the remainder, on the payer's side (PayInvoiceMessage) and on the payee's (CreateInvoiceCommand.effectiveOutputs, the invoice coordinator's outputs), through one helper,evenSplit. -
VoidRejectedTransactionCommand, journaled asRejectedTransactionVoidedEvent(wallet.transaction.rejected_voided): when ARC reports a transaction handed to the wallet REJECTED, its row already became failed, but its outputs stayed pending: never spendable, yet counted as funds on the way for ever (spiffyvault-izz). They are now voided, asVoidUnsettledTransactionCommanddoes for a payment whose input is spent elsewhere. Nothing is deleted. REJECTED can be stale: a later SEEN_ON_NETWORK or a merkle proof of the transaction makes its outputs available, as for any voided output. The ARC actor sends the command on every REJECTED; the wallet journals nothing for a transaction it built itself (a deferred payment fails through its network status, as before) or when nothing of it is pending.
5.15.1 #
A payment whose ancestors share a block, sent by a wallet built on the BSV SDK, is accepted
- A BUMP that leaves out the nodes its lower levels determine is walked to its root. The BSV SDK merges the proofs of two transactions mined in the same block into one BUMP and trims every node the walk can compute from the levels below (
MerklePath.trim()); a whole level can be empty.BUMP.siblingAtlooked a node up only where it was stored, so such a BUMP failed with "Missing sibling" and the payment was refused as "Ancestor transaction at index 0 failed merkle proof validation". Found when the demo shop's till (wallet-toolbox) swept two phone payments to a phone. A missing node is now computed from its two children, as the SDK does; the root it leads to is still checked against the block header, so a tampered hash below it is refused as before.
5.15.0 #
Both networks broadcast through the BSV Association's Arcade by default: ARC is deprecated on 30 November 2026
ArcServiceConfig.bsvaArcadeMainnet(): the mainnet Arcade athttps://arcade-v2-us-1.bsvblockchain.tech, no API key, the ARC API at its root as on testnet. It publishes the network's own rate (1 sat/kB today, where GorillaPool's ARC publishes 100), so an app that wants to pay more passesminimumFeeRate.LibSpiffyActorSystemwith noarcConfignow uses Arcade on both networks: mainnet was GorillaPool's ARC and testnet TAAL's, which answers 401 without an API key. An app that passes its own config is unchanged.- The TAAL and GorillaPool presets stay, marked in their docs as ending with ARC.
5.14.0 #
A wallet signs a message with the key of one of its addresses
SignMessageCommand(walletId, pubkeyHash, message), answered withMessageSignedEvent(publicKey, signature): the message signed as a Bitcoin Signed Message (compact, base64, as dartsv'sMessage.sign) by the wallet key whose public key hashes topubkeyHash. It proves the wallet holds that address's key, for a token held there, say (overnode_v2-l6bx.7). The wallet adds the message prefix and hashes the message, so no caller can have a key sign a digest of its choosing. A hash the wallet holds no key for is refused, and so are watch-only wallets and a WIF wallet whose one key is another. Journals nothing.
5.13.0 #
A payee can answer its payer as soon as ARC accepts a payment, and ARC's fee policy is read once, when the app starts
PaymentAcceptedEvent(walletId, invoiceId, txid, networkStatus, requestId): a received payment validated, the read model holds it, and ARC accepted its submission while still taking it to the network (Arcade'sRECEIVED). It comes before the payment'sBEEFValidationResultEvent, which still comes with the status the network got to, and the invoice is still marked paid only then. A payee answers its payer at the first and tells it the outcome at the second; with Arcade that was a 5–9 s wait before any answer (spiffyvault-voo). A payment whose first ARC answer is already final (seen, mined, refused) gets no such event.BroadcastTransactionMessage(acceptedTo:)is toldBroadcastAcceptedMessagewhen ARC's first answer is in flight; the sender is answered as before.- ARC's fee policy is read when ARCActor starts and kept for its life. Every payment asked ARC for its policy, about 0.9 s from a phone, and a policy changes rarely. A read that fails is not kept: the next fee quote asks ARC again, and a payment is still never built at a rate ARC did not publish. Tests that need their own policy now set it before the system starts.
5.12.1 #
A payment is signed with the wallet's HD root derived once, not once for each coin it spends.
- A transaction is signed with the wallet's HD root derived once. A mnemonic wallet's root is the mnemonic stretched by PBKDF2, about 1.1 s on a phone with four secure-storage reads, and
WalletTransactionSigner.signTransactionderived it again for every input it signed: a two-input payment spent 2.65 s signing on a Pixel.WalletKeys.withHdRoot(walletId, body)holds the root whilebodyruns and drops it when the last overlapping call returns, so it is still never kept between operations. Signing a transaction now derives it once (bead libspiffy-kbhf).
5.12.0 #
Coins locked to a key outside the wallet's account are found and can be unlocked, the fee of an unlock can be quoted, and a mainnet wallet's import no longer fails when testnet scripts were read first. Needs eventador 4.2.0, which stores events one byte for each byte; with 4.1.0 an event of about 2 MiB (a transaction with many outputs and its parents) was written outside the journal's index, and the wallet's next write failed.
Lock keys (bead spiffyvault-mnz.5). hodlocker.com locked a RelayX user's coins to the RelayX paymail key at m/0'/236'/0'/0/0, outside the account m/44'/236'/0' the wallet is imported from, so an import read those locks and dropped them.
AddLockKeyCommand(walletId, wif)→LockKeyAddedResponse,LockKeyAddedEvent: the wallet takes a private key outside its HD tree. The key goes to secure storage (WalletKeys.lockKeysKey), never into the journal; its address is one of the wallet's, so a HODLocker output locked to it is the wallet's coin. Idempotent; refused for a key of another network.LockKeyPath(address): theKeyPathof a lock key's address. The read model records the address withAddressMetadata.lockKeyPurpose, and the wallet signs for it with the stored key, as an unlock does.ImportWalletCommand.lockKeyWifs,ImportWalletMessage.lockKeyWifs,importWalletFromXpriv(lockKeyWifs:): keys handed to the wallet before the scan; an application derives them from the seed the account came from.
Unlock fees (bead spiffyvault-mnz.7). A HODLocker unlock holds the whole locking script in its preimage, about 1,300 bytes, so a coin of a few satoshis costs more to unlock than it holds and UnlockCoinsCommand refuses it.
HodlockerLock.unlockSize(lockingScriptLength): the signed size of an unlock; the unlock's fee is taken on it.QuoteUnlockFeeCommand(lockingScriptLength)→UnlockFeeQuotedEvent: ARC's policy rate on that size, for an application to tell a lock worth unlocking from one that is not. Nothing is built.
Fixed:
ScriptTypeRegistry: one registry for each network. It was one instance for the isolate, fixed to the first network asked for, so every later use for the other network threw (already initialized with NetworkType.TEST, cannot reinitialize with NetworkType.MAIN): a mainnet import read no parent transactions and then failed (bead spiffyvault-mnz.6).
5.11.1 #
An import no longer fails at a transaction with many inputs. A mainnet wallet's import stopped at a transaction with 162 inputs: its parents were fetched one by one (94 seconds), and the wait for the wallet read model to apply the transaction had started before them, so its 30 seconds were over before the transaction was sent.
- Import: the wait for a transaction to be applied starts when its first command is sent, after its parents are fetched. A transaction's parents are fetched six at a time and each once, from storage when it holds them.
WhatsOnChainDataSource: requests made at the same time keep torequestsPerSecondLimit. A request now takes its place in the last second's requests under the lock; before, requests that checked the limit together all went through.
5.11.0 #
Address discovery no longer counts a failed lookup as an unused address. An address whose history could not be read (after the data source's own retries) ended a chain's scan exactly as a real gap would, so an outage or a run of rate-limit errors during an import left every address past it unfound, with nothing to say so.
AddressDiscoveryService.discoverAddressesanddiscoverAddressRange: throw aDataSourceExceptionnaming the address (an error of another type is wrapped, with it asoriginalError). An import fails withSpiffyErrorCode.chainServiceUnreachableand can be resumed.
HODLocker coins — coins time-locked to a wallet key until a block height — are the wallet's, and a seed-phrase import finds them (bead spiffyvault-mnz.1). dartsv names the HODLocker script hodlocker, and the import, the SPV receive path and the recording of the wallet's own transactions had no case for it, so every such output was dropped. A locked coin is recorded as plugin-managed, so it is never selected for a payment and is in no balance but the new locked one.
HodlockerLock: reads a HODLocker script (parseHex,parse): the owner's key hash and the lock height. Every fixed byte of the contract is compared; dartsv'sScriptPattern.isHODLockerchecks only the lengths of its leading constants.metadatais what a wallet's lock is recorded with (pluginId: 'hodlocker',lockHeight,ownerAddress),isLockedCoinandlockedSatoshisread it back.- Import: a HODLocker output whose key is one of the wallet's is imported with its lock. The lock transaction is in the history of the address that funded it; the key it is locked to has no history of its own, so its owner is also looked for among the addresses the scan found unused, and such an address is registered with the wallet before the coin.
AddressDiscoveryResult.unusedAddresseslists them. - SPV receive and
RecordOutgoingTransactionCommand: a HODLocker output to a wallet key is the wallet's. ReceiveUTXOCommand: a HODLocker output is refused when its key is neither a wallet nor a watch address, and is recorded with its lock whatever metadata the sender gave.BalanceResponse.lockedBalance,BalanceUpdatedEvent.lockedBalance: the value of the wallet's HODLocker coins, mined or not; not part oftotalBalanceor any other number.
Coins can be locked and unlocked (bead spiffyvault-mnz.2).
LockCoinsCommand(walletId, amount, lockHeight)→CoinsLockedEvent: paysamountto a HODLocker output locked to a fresh receive address of the wallet untillockHeight, with change, through the ordinary payment path, and broadcasts it. Refused for a height the chain has reached or one of 500000000 or more. The reply names the transaction and the owner address.UnlockCoinsCommand(walletId, utxoKey)→CoinsUnlockedEvent: spends a locked coin back to a fresh address of the wallet, less the fee: nLockTime at the lock height, the input's sequence0xfffffffe, and<signature> <public key> <preimage>, checked against the locking script before it is recorded and broadcast. Refused, with nothing built, while the header chain is below the lock height, so no transaction the network cannot take yet is sent.HodlockerOutputSpec: an invoice or payment output locked to an address until a height.AggregateSigningClient.signInputWithKey:signInputwith the signing key's public key.HodlockerLockalso reads a lock height written as a small-number opcode (OP_1toOP_16), which dartsv's pattern does not; the import, SPV and outgoing paths ask it before dartsv's templates.
5.10.0 #
Errors and import progress carry codes, for an app to say them in its own language (bead spiffyvault-9ae.5). SpiffyVault read libspiffy's English messages to tell the user what went wrong ("Insufficient funds", "ARC's policy fee rate could not be read"), and guessed an import's step from its progress. The English stays, for logs.
SpiffyErrorCode: insufficientFunds, addressInvalid, addressMainnet, addressTestnet, feeRateUnavailable, coinsInUse, chainServiceUnreachable, notInitialized, timedOut, cancelled.SpiffyErrorCode.of(error)reads a code from an error: its own, or aDataSourceException,SocketException,HttpExceptionorTimeoutExceptionby its type.byNamereads a code back after it crossed an isolate.SpiffyStateError,SpiffyArgumentError: coded errors, thrown where aStateErrororArgumentErrorwas, soon StateErrorandon ArgumentErrorstill catch them. Insufficient funds (payments, channel funding, the UTXO ledger), an unreadable fee rate, an address of the other network or no address at all, and a system not initialized throw them.CoordinatorReply.errorCode: set byPaymentReadyEvent(fromBEEFPaymentResponse.errorCode),UTXOSplitCompleteEvent(fromSplitUTXOsResponse.errorCode) andImportCompleteEvent(fromWalletImportFailedEvent.errorCode); null for every other reply, and for a failure with no code.CoordinatorFailure.spiffyCodeis its reply's code, soSpiffyErrorCode.ofreads it from whataskthrows.ImportStep: opening, discovering, fetching, recording, finalizing, done.ImportProgressEvent.stepandWalletImportProgressEvent.stepsay what an import is doing;phaseis unchanged.
5.9.0 #
A reclaimed payment's own row is failed (bead spiffyvault-56z). The reclaim resolved the deferred payment as reclaimed, but nothing changed the payment's transaction row, so a payment the payee never broadcast showed as pending for ever, and the status scan kept asking about it.
- When the self-spend reaches the network: the reclaimed payment's row fails with its record, unless it is confirmed.
- The status scan: a pending or broadcast row whose deferred payment was reclaimed is failed, as one whose deferred payment failed already was. This repairs the rows that wallets already hold.
A wallet imported again can take back the payer keys its earlier payments used. A wallet imported by its phrase alone starts its payer keys at 0, so its next type-42 payments would use again the payer keys of payments made before, and a payee could link them.
RecordType42DestinationsCommand: the app hands back the type-42 derivations its payment records kept. The wallet looks for each derivation's payer key among its own (m/3'/1'/n', up to 100 past the highest found or used), derives the address itself, and journals aType42DestinationDerivedEventfor each destination it does not hold yet, which moves the payer-key count past it. A derivation whose payer key is not the wallet's own is skipped. Answered withType42DestinationsRecordedEvent: the addresses, how many were skipped, and the payer keys used now.
5.8.0 #
A payment the payee broadcast through another service is settled from a node's merkle proof (bead spiffyvault-ri8). The payer's wallet asked only its broadcaster, by txid, and a broadcaster knows only what was submitted to it. Such a payment stayed pending for ever and its change stayed on the way, and a reclaim of it was allowed after it was mined.
MerkleProofSource,TeranodeMerkleProofSource: where a proof is looked up.TeranodeMerkleProofSourceasks a Teranode asset service for/merkle_proof/{txid}/hex;gorillaPoolTestnetis a node that serves it.LibSpiffyActorSystem.initialize(merkleProofSource:)sets it; without one nothing changes.- The status scan: a pending or broadcast transaction that ARC does not know, or keeps in flight, for an hour is looked up at the source, then at most every ten minutes. A proof that matches the stored header at its height applies the deferred spend and confirms the transaction, as an ARC MINED report does. Any other answer changes nothing.
CheckDeferredPaymentStatusCommand: when ARC does not know the payment, the source is asked at once; a proof answersMINED, confirmed, with the sourcemerkleProofSource.- A failed row stays failed on an in-flight answer: only SEEN_ON_NETWORK or a proof brings it back. A reclaim that lost its race went back to broadcasting two seconds after it failed, and showed so for ever.
- A lost reclaim's row is failed: when the payment it reclaimed spends its coin, the self-spend's row fails with its record. A row left broadcasting while its deferred payment failed is failed by the next scan.
5.7.0 #
An app can scan one address of a wallet for coins (bead spiffyvault-017). SpiffyVault hands a fresh address to a payer outside it, such as an exchange, and nothing tells the wallet when that payer pays. The import could only rescan a whole wallet up to its gap limit, which is slow and misses an address past the gap.
ImportWalletCommand.addresses: withresume: true, only these addresses of the wallet are scanned, instead of discovering its addresses. Each must be an address the wallet holds, or the scan fails. A history lookup that fails fails the scan, so an outage does not read as an empty address. Transactions the wallet has recorded are skipped, so a scan can be repeated. The wallet's other addresses still count as its own for the outputs of a scanned transaction.LibSpiffyActorSystem.resumeWalletImporttakesaddressestoo.
5.6.0 #
An app can export a transaction that is not mined yet (bead spiffyvault-3fm). SpiffyVault's transaction screen copies a payment as BEEF before it is mined, for a payee or a person who checks it with SPV. ExportTransactionQuery refused such a transaction, so the app imported AncestorChainService from src/.
ExportTransactionQuery.requireProof: true by default, as before. With false, a transaction with no proof of its own is exported with its ancestry back to the ancestors whose proofs the wallet holds (BRC-62, parents first). A mined transaction exports as before.
5.5.0 #
The app no longer needs the wallet's internals for what it does every day (bead overnode_v2-rww). OverNode sent commands to the wallet aggregate and messages to the ARC actor itself, and imported helpers from src/: the coordinator had no command for them. Each now has a public one.
RecordType42AddressesCommand: records type-42 keys of the wallet's anchors as its own, so it signs with them and attributes outputs paying them. Answered withType42AddressesRecordedEventonce the read model holds every address. For keys the wallet uses for itself, such as the key a token it makes is locked to (a hand-off received with a payment still records its addresses throughImportTransactionCommand).RenameWalletCommand: answered withWalletRenamedEventonce the wallet row holds the new name.BroadcastTransactionCommand: broadcasts a fully signed transaction the app holds and the wallet has no command for (a channel's settlement), answered with ARC's answer asTransactionBroadcastEvent.CheckPendingTransactionsCommand: asks ARC again about transactions waiting for a proof, as a new header does.- Public helpers:
Bip32(derivation that keeps hardened paths hardened),AddressDiscoveryService, andAnchorKeys: the path and public key of a wallet's anchor for a context, the ruleWalletKeys.anchorPathfollows, for tools that work from a wallet's seed.
5.4.0 #
A type-42 destination carries its tweak t (bead overnode_v2-93y.1). A broker that sells access to a recording checks that the buyer paid the creator without holding either private key: it recomputes the destination as A + t·G from the creator's anchor key A and the tweak t. The wallet computed t to derive the destination and dropped it, so a buyer could not give it.
Type42Destination.tweak: t,HMAC-SHA256(ECDH(b, A), invoiceNumber), as 32 bytes of lower-case hex. It discloses the one destination and nothing else.DeriveType42DestinationCommandsets it, and it is journaled with the destination; one journaled before 5.4.0 reads with none.
5.3.3 #
A client whose server cannot be reached no longer sends to it every two seconds (bead overnode_v2-7pf). Two tabs were still closing when a phone started, and neither host could be found ("No addresses found for peer"): every send failed at once. Each failure brought the next resend forward to resendAfter, so the close went every two seconds for as long as the host stayed away. Some hosts never come back.
- A failed send brings forward one resend per wait. After that the resends back off as usual, up to
resendAtMost. - At the longest wait, with the last send failed, the resends stop. The messages are kept. The new
ChannelPeerAwayEvent(channel, peer) tells the app, which can watch for the peer. - The peer back, the kept messages go at once. The app says so with the new
ChannelPeerReachablemessage. Any message from the peer does the same. - A channel that ends past its lock time sends nothing more. Before, only a close or a reject stopped the resends, so an expired channel, or one whose refund was claimed, went on sending its close for ever.
5.3.2 #
A tab with nothing paid closes when both sides close at once (bead overnode_v2-7pf). The host ended a room and closed its side first. The client had paid nothing, so the host held no payment to settle with. A minute later the client closed with its payment of nothing (bead libspiffy-w4l2). The host refused it because its channel was no longer open. The client resent its close every two seconds for hours, and its 1000 sats stayed locked until the refund lock time.
- A server that is already closing takes the client's payment of nothing and settles with it, paying the client back. The aggregate and the channel manager allow it only for the closing payment of nothing (
closing, sequence 0). A channel that isclosingstill refuses every payment of money. - A refused payment no longer restarts the resend wait. The close carries the latest payment, and the server answered each resend with a
channel_errorrefusing it. Each refusal reset the wait toresendAfter, so the close went every two seconds instead of backing off toresendAtMost. A refusal now clears the payment once and leaves the wait as it was.
Events applied again at start are no longer acted on again (bead overnode_v2-7pf). A projection catches up from its checkpoint, which is saved every 100 events, so an app the OS stops replays up to 99 of them. A restore copies a backup's journal in for the projections to apply. Every channel event a projection applied went to ChannelP2PAdapter, which acted on it as if it were new. After a restore, one phone re-sent every channel message of the past (channel_request, channel_accept, refund_signed, channel_close, channel_closed, payments) to the peers concerned, and the app was told again of every channel opened and closed, and of every confirmation and paid invoice. Replay itself is unchanged: the read models are still built from it.
- libspiffy notes the journal head when it starts, before any actor can write, from the Isar or Postgres store (
PostgresEventStore.highestJournalId, new). An applied event at or before that head was replayed. Requires eventador 4.1.0 (ProjectionActor.appliedEventsWithSequence). - A replayed channel event sends nothing and tells the app nothing. It goes to the adapter on a stream of its own (
replayedChannelEvents, a new optional parameter ofChannelP2PAdapterandWalletCoordinatorActor).LibSpiffyActorSystem.channelEventscarries only events journaled since the start. - A replayed confirmation, reverted confirmation or paid invoice is not announced (
WalletCoordinatorActor's newisReplayed). What follows from the event is still done, in case the app stopped first: an invoice its payment pays, or a channel its failed funding can never open. Each step leaves alone what is already done. - After a restart a channel resumes from its journaled state. A client's close goes again until
channel_closedarrives. A funding sent has itschannel_opengo again untilchannel_opened. On a server, an open channel's settlement is armed. Only a run's live events used to arm these, so a restart lost them unless the projection happened to apply their event again.ChannelP2PAdapter.resumeAfterRestartreads the state and leaves alone a channel with nothing to send. The coordinator calls it at startup for each client channel the read model shows closing or funding. The adapter calls it for each channel a replayed event names, unless the replay shows that channel end, so a change the read model does not show yet is resumed too.
5.3.1 #
A coin proven spent by a transaction from elsewhere stays spent when the payment stuck on it fails (bead libspiffy-4kfq). A payment that stays unsettled past ARCActor.inFlightStuckAfter has its inputs checked. When one is spent by a confirmed transaction proven against the local headers, the payment fails (INPUT_SPENT), and the failure releases its inputs. The proven-spent coin was released too, and became available again. When the spender was not one of the wallet's own transactions (sent from another wallet with the same keys), SpentOutputRepair never found it. Every later payment could take the coin up again, sit at SENT_TO_NETWORK and fail: on one phone the same coin was spent five times, two of them channel fundings the server rightly refused to open.
- After failing the payment, the ARC actor spends the coin with
SpendUTXOCommand, by the proven spender and at the block height of its proof, asSpentOutputRepairdoes for a spender of the wallet's own. Only for the wallet's own deferred payments: a transaction handed to the wallet is voided, as before, and spends none of its coins. - A channel whose funding can never be mined stops sending
channel_open. A client resentchannel_openuntil the server answered, the channel closed or the settlement margin began, a day later; a funding the wallet failed never gets an answer. The server re-submitted the funding to ARC for each one, waiting about half a minute while its channel actor did nothing else, so with two such channels resending, another client'schannel_requestwaited past its open timeout. NewRecordFundingFailedCommand/FundingFailedEvent(channel.funding.failed): the client's channel state getsfundingFailed, its row becomesfailed, the adapter sends no morechannel_openand fails the app's open request (notstillSent), and the channel can no longer open. The coordinator records it when the wallet fails a deferred payment with purposechannel-funding, and at startup for a funding the wallet failed before (the channel journal is replayed to the adapter at every start, so the failure stops the resend each time too).ResendChannelOpenCommandrefuses such a channel.FullChannelStateResponse.fundingFailedis new.
5.3.0 #
A channel request's failure says whether what failed is still being sent (bead overnode_v2-0o5.3.4). A payment the server has not acknowledged within ChannelTiming.confirmWithin and an open the server refused are both answered with a CoordinatorFailure, and both are resent: the payment may still land, the open may still be taken. A refused payment, a rejected open or a payment a settlement left out are final. The app could tell them apart only by the failure's wording.
ErrorEvent.stillSent, andCoordinatorFailure.stillSentreading it: true when the client keeps resending what failed, so a later event that answers no request may report it landing (aChannelPaymentEvent, aChannelOpenedEvent). Set for an unacknowledged payment, for achannel_errorrefusing an open whosechannel_openis still resent, and for achannel_openedthe client failed to record while itschannel_openis still resent. False everywhere else, and when noErrorEventreported the failure.
5.2.0 #
A client's channel opens when its server has opened it (bead libspiffy-jark). The server opens a channel only once ARC reports the network holds its funding, SEEN_ON_NETWORK or MINED; the client opened as soon as ARC took the funding, which on testnet ARC can answer SENT_TO_NETWORK for minutes. The server refused, the client never heard, and it went on paying into a channel the server had never opened: its tab looked spent and the server's empty.
- The client opens on the server's
channel_opened. A new message: the server sends it for everychannel_openit opens on, a repeat included. The client journals the newFundingSentEventwhen ARC takes its funding (the channel staysrefundSigned, its rowfunding, withfundingSentin its state) and itsChannelOpenedEventonly whenchannel_openedarrives. No payment can be made before. channel_openis resent until the server answers. As a payment and a close are, waitingChannelTiming.resendAfter, then twice as long, up toresendAtMost. Each one has the server submit the funding and look at the network again, so a funding the network takes late still opens the channel. Resending stops when the settlement margin begins, with anErrorEvent: the server would settle the channel as it opened it, and the refund returns the funding at the lock time.- A refused open answers the app, and the open goes on. The server's
channel_erroranswersOpenChannelCommandwith aCoordinatorFailurecarrying its reason, andchannel_openis still resent; if the server opens later, aChannelOpenedEventthat answers no request says so. ResendChannelOpenCommandresends a funded channel'schannel_openwhile it waits for the server, and keeps resending it untilchannel_opened.RetryChannelFundingCommandrefuses a channel whose funding is already sent.- Breaking for mixed versions: a 5.2 client waits for a
channel_openeda 5.1 server never sends. A 5.1 client ignores it and opens on its own, as before.
5.1.0 #
A channel message the app's transport loses is sent again, and a payment is answered when the server has it (bead overnode_v2-0o5.3.2). On a phone's connection a payment_update or channel_close was lost as often as not when the connection changed, and the adapter handed each message to the transport once. A lost payment was reported sent. Every payment carries the channel's balances, so the server refused every later one, and at close the client refused the server's settlement because it was not its latest payment: the channel stayed closing until the refund lock time.
- A client resends what its server has not answered. The latest unacknowledged
payment_updateis resent until apayment_ackcovers it, and the client'schannel_closeuntilchannel_closedarrives. The first resend waitsChannelTiming.resendAfter(2 s), and each wait is twice the last, up toresendAtMost(30 s). The app can tell the coordinator a send failed with the newP2PSendFailed, which brings the next resend forward; without it the resend still comes. ChannelPayCommandis answered when the server acknowledges the payment, not whenpayment_updateis handed to the transport.ChannelPaymentPendingEventsays it is signed and on its way. A payment with no acknowledgement withinChannelTiming.confirmWithin(20 s) is answered with anErrorEvent. It is not withdrawn: the client signed it and the server may hold it, the acknowledgement being what was lost. It is still resent and goes with the close, and if its acknowledgement comes later, aChannelPaymentEventthat answers no request says so. A payment the server refuses is answered with the refusal and not resent; the server'schannel_errornow names the payment'ssequenceNumber.- The server takes any later payment, and acknowledges a repeat again. It required each payment to be exactly one sequence after its latest. Each payment carries the channel's balances, so one that follows a lost payment pays that one too; the aggregate already checked the balances follow from the server's own. A payment at or below its latest sequence is acknowledged again at its latest, with nothing journaled (
PaymentAcknowledgedResponse.repeat). - The client's close carries its latest payment, which the server takes before it settles, so a lost
payment_updateis still paid. A close of a channel the server already closed is answered with the settlement it closed with, handed over again (ChannelClosedResponse.alreadyClosedandsettlementTxHex). The client's channel state keeps its signature on its latest payment again (latestClientSignatureHex) so a close after a restart carries it too. - The client takes a settlement from an earlier payment. A server that never received the client's latest payment settles with the one before, which pays the client more. The client refused any settlement but its latest payment; it now takes one it signed that pays the server no more than its latest balance. The channel's
ChannelClosedEventrecords what the settlement pays (finalClientBalance,finalServerBalanceon the coordinator event), and payments the settlement left out are answered as failed. - A channel with nothing paid closes cooperatively (bead libspiffy-w4l2). Its server held no payment to settle with, so the client's funds waited for the refund lock time. A client closing a channel with no payment now first records a payment of nothing (
RecordPaymentCommand.closing, the only payment of nothing the aggregate takes) and sends it with the close; the server settles with it, paying the client back. - Funding change of a satoshi or more comes back to the wallet (bead libspiffy-kov9). Change at or below 546 sats, Bitcoin Core's dust limit, was left out of a channel's funding transaction and went to the miner. BSV has no dust limit, and the fee already paid for the change output.
5.0.0 #
Breaking changes are marked Breaking; each says what to change.
- A coordinator request is answered with its own reply, and
askwaits for it. Every app wrote its own "send, then find the matching reply oncoordinatorEvents" helper, and could not do it reliably: the commands'correlationIdwas derived from the wallet or invoice (two payments of one invoice shared it) or rebuilt fromDateTime.now()on every read, nothing in the library read it, andErrorEventnamed no request. Every command and query with an answer is now aCoordinatorRequest<R>, with arequestIdfixed when it is made (given, or generated), and declares its reply typeR, aCoordinatorReply. The coordinator answers each with exactly oneRcarrying that id, on success and on every failure path, and anErrorEventa request causes carries it too.LibSpiffyActorSystem.coordinatoris aWalletCoordinator:ask(request, {timeout})sends a request and completes with its reply, throwingCoordinatorFailure(carrying the failed reply or theErrorEvent) when it failed, or when the coordinator stopped first (closed), andTimeoutExceptionafter the request'sreplyTimeout; a timeout does not cancel the request.tellsends without waiting;on<E>({walletId})follows one kind of event. Replies are still published oncoordinatorEvents(bead libspiffy-xc78.1).- Breaking:
LibSpiffyActorSystem.coordinatoris aWalletCoordinator, not anActorRef:tellworks as before; code that typed itActorRefchanges the type. - Breaking:
queryIdisrequestIdon every query and response (GetBalanceQuery,GetTransactionsQuery,GetTransactionDetailQuery,ExportTransactionQuery,GetDeferredPaymentsQuery,GetHeaderSyncStatusQuery, and their answers); it is optional onGetHeaderSyncStatusQuerytoo. On repliesrequestIdis nullable: the same event type is emitted without a request for what nobody asked (a receive replayed when its header arrived, a peer's headers). - Breaking:
DeleteWalletCommandis answered withWalletDeletedEvent, andReleaseUTXOsCommandwithUTXOsReleasedEvent, once the read model shows it; a refusal of either, or ofRecordOutgoingCommand, is its reply'sfailure, no longer anErrorEvent. The wallet aggregate answers a deletion (WalletDeletedResponse) and a release (UTXOsReleasedResponse, naming the UTXOs released), and answers an outgoing recording once, withTransactionRecordedResponse, instead of first with aUTXOReceivedResponseper change output. - Breaking:
ImportWalletCommandwith a mnemonic imports the wallet's history: the wallet is created from the mnemonic and its import run as a resume, which derives its keys from the stored mnemonic. It created the wallet and imported nothing, answering withWalletCreatedEvent. Without a blockchain data source an import is refused with a failedImportCompleteEvent. - Breaking:
TimestampCommandis answered with ARC's answer to the broadcast; it reported success when the broadcast was handed to ARC, before ARC answered. - Breaking:
RefreshWalletCommandis removed: it refreshed nothing and announced that it had. The named constructorsPaymentReadyEvent.error()andProvisioningCompleteEvent.error(), which nothing called, are removed; theerrorfields stay. - A
StoreHeadersCommandwhose batch throws is answered, with nothing stored; it was not answered at all. - Every coordinator event takes its
eventTimestampwhen it is made; it was the time it was read.
- Breaking:
- Channel commands are answered through
asktoo.OpenChannelCommandis answered with the channel'sChannelOpenedEvent(5 minute default timeout: the counterparty and the funding broadcast are waited for),ChannelPayCommandwith itsChannelPaymentEvent,CloseChannelCommandwithChannelClosedEvent,ClaimChannelRefundCommand,RetryChannelFundingCommandandResendChannelOpenCommandwith the events they had; a step of an open or close that fails, and the counterparty'schannel_rejectorchannel_errorduring an open, is anErrorEventnaming the request. The adapter answers a channel's requests of one kind in the order they were made (bead libspiffy-xc78.2).- Breaking:
AcceptChannelCommandis answered with a newChannelAcceptedEvent,RejectChannelCommandwithChannelRejectedEvent, andExpireChannelCommandwithChannelExpiredEvent, which carries a failed expiry that was anErrorEvent. - The channel's request, its acceptance and a payment are asked of the channel manager: told with no sender, a refusal of any of them (an unknown wallet, a payment above the client's balance) reached nobody, and the app waited for a channel or payment that never came.
- A coordinator built without channel events answers a channel command with an
ErrorEvent; it dropped it. - A server's settlement timer closes its channel without registering a close request, so it cannot take the answer of a close the app asked for.
- Breaking:
- Breaking:
NodeRpcDataSourceis removed, as 4.7.0 announced. It read proofs withgettxoutproof, which only an SV Node serves; Teranode does not. UseWhatsOnChainDataSource, or aBlockchainDataSourceof your own. Thesvnodetest tag and its tests are gone with it (bead libspiffy-cquj). - Breaking: the deprecations kept for compatibility are removed.
CdnHeaderSyncConfig.concurrentDownloads(never read: chunks are validated in sequence); thewalletIdEqualTo/walletIdNotEqualTowhere clauses ofAddressEntityandstatusEqualTo/statusNotEqualToofBitcoinTransactionEntity(usewalletIdEqualToAnyPurposeandstatusEqualToAnyWalletId, the composite indexes' prefixes);LibSpiffyActorSystem.broadcastChannelEvent(channel events are broadcast once the projection applied them); the unusedsecureStorageparameters ofPaymentCoordinatorActorandBenfordCoordinatorActor, andWalletCoordinatorActor's unusedimportActor. Deprecated events and commands that old journals hold stay, for replay (bead libspiffy-zoql). - Breaking:
ChannelP2PReceivedandChannelP2PMessageToSendEventare removed. They were the channel-named copies ofP2PMessageReceivedandP2PMessageToSendEvent, and an app that listened only for the channel class missed the merkle-proof protocol's messages. Deliver what your transport receives asP2PMessageReceived, and send everyP2PMessageToSendEvent. - A payment waiting for its block header is answered, not failed.
BEEFValidationResultEvent.failureis null whileawaitingHeader, soaskreturns the reply; the verdict the header brings is a second event with the samerequestId(while the process runs). AnImportTransactionCommandwhose proof waits for a header is answered by that verdict too, within its timeout: the coordinator kept no record of the request once the first reply came, and the verdict named none. BroadcastFailureEvent.willRetryis ARC's answer, required, not always true: no retry is queued on a backend without the retry queue (PostgreSQL), or for a definitive refusal.ProvisionedTransactionis exported: a plugin implementingTransactionBuilderPlugin.provisionFundingnames its return type without importinglib/src.- The README, the developer guide and
lib/coordinator.dartteachask, with a request-to-reply table;example/coordinator_example.dartruns it offline. The guide said a wallet created without key material gets a generated mnemonic: libspiffy generates no keys, and the refusal now says what to provide. The localnet tests and their harness useaskfor every request they wait on;next<T>()remains for events nobody requested (bead libspiffy-xc78.3).
4.7.0 #
- A BEEF settled through the wallet keeps the ancestry it carries. A payment that spends an output the wallet does not own (a token purchase spending the seller's listing) was recorded without that output's parent: the app hands it to the plugin, and
TransactionRecordedEventcarries no ancestors. Every spend of the payment's change then failed inAncestorChainServicewith "Transaction <the counterparty's txid> not found in storage" until the payment was mined and its proof arrived.SettleBEEFCommandnow keeps what the BEEF carries for its subject, back to proven transactions with their BUMPs, when the subject is a transaction the wallet recorded:RecordTransactionAncestorsCommandjournalsTransactionAncestorsRecordedEvent, and the projection stores it as it stores a received BEEF's ancestors. The settlement returns once the read model holds them. Each transaction the settlement broadcasts goes with the BEEF, so ARC is sent the Extended Format of a transaction spending a counterparty's output; Arcade refuses one it cannot extend (460). An app settling such a payment hands the complete BEEF, the counterparty's transactions included. The BEEF ancestry walk moved from SPVActor toBeefAncestry(lib/src/spv/beef_ancestry.dart), which both use (bead libspiffy-yiba). - A channel's settlement and refund reach Arcade.
PaymentChannelManagerActorsubmitted the settlement (server) and the refund claim (client) without the funding transaction they spend. The funding output is no wallet UTXO, so the Extended Format fell back to raw; ARC looked the parent up itself, Arcade answered 460 and every channel close and refund failed. Both now go with a BEEF of the funding transaction and the spend (bead libspiffy-uqa4). - The app sets a minimum fee rate.
ArcServiceConfig.minimumFeeRate(and on every preset): the wallet pays ARC's published policy rate, or this floor when the policy is lower. GorillaPool's testnet ARC publishes 0 sat/kB, and nothing paying 0 is mined there. A floor is never a rate in place of a policy ARC could not be asked for.FeeRate.isAbovecompares two rates exactly (bead libspiffy-23j2). - The default P2P user agent passes Teranode. Teranode's wire-protocol service accepts a peer only if its user agent contains
BSVorBitcoin SV, and bans any other's IP for 24 hours;/LibSpiffy:1.0/did not pass, and one refused connection locked every client behind the same address out. The default isLibSpiffyActorSystem.defaultUserAgent,/LibSpiffy-BSV:1.0/(bead libspiffy-c04p). The P2P network line is a log record, not aprint. checkBumpAgainstHeadersis exported, withcheckBumpHexAgainstHeaders,ProofHeaderCheckandProofHeaderStatus: an app checks a merkle proof against its headers without importinglib/src(bead libspiffy-09oj).- A plugin's placeholder signing pass is not logged as a plugin failure. A plugin that checks the spend it built (a token's script) refuses the pass signed with placeholder signatures, by design; the next pass signs for real. Each refused pass was logged as a WARNING with a stack trace. The plugin guard now covers the whole build, so only a failure with nothing left to sign is the plugin's (bead libspiffy-kzwv).
NodeRpcDataSourceis deprecated and goes in 5.0.0. It reads proofs withgettxoutproof, which only an SV Node serves; Teranode does not, and the SV Node regtest stack it was tested against is retired (bead libspiffy-cquj).- The localnet tests run on Teranode.
test/integration/localnet_harness.darttargets../localnet-teranode(Teranode, Merkle Service, Arcade): coins from its faucet through Arcade, BEEFs from Arcade's merkle paths, the tip and a transaction's block from the DataHub, headers over the wire protocol on :18444. The SV Node + ARC stack in../localnetis retired; theNodeRpcDataSourcetests that need an SV Node's RPC are taggedsvnode(dart test -P svnode). Arcade refuses a later double spend outright (REJECTED) where ARC held it as DOUBLE_SPEND_ATTEMPTED, and a spend of an output spent in a block likewise (bead libspiffy-kynm).
4.6.1 #
- A payment channel's payment pays every share of a satoshi or more.
PaymentChannelBuilderleft a party's output out of a payment, and a refund failed, when its share was at or below 546 sats, Bitcoin Core's dust limit. BSV has no dust limit and ARC asks for none, so the share went to the miner: a 1000 sat room tab that paid the host 350 settled with one output, back to the client, and the host's 350 was lost.dustThresholdis replaced byPaymentChannelBuilder.minimumOutputSats(1); a share of nothing is still left out. The server no longer accepts a payment that leaves its own balance out:_checkPaymentTransactionrequires the server's output to carry its whole balance (bead libspiffy-b4kv).
4.6.0 #
- Arcade, the Teranode-era ARC, works as a broadcaster. Arcade serves ARC's API at its root (no
/v1) and accepts a submission with HTTP 202 andtxStatus: RECEIVED, whichArcService.submitTransactionthrew as a failure: every transaction Arcade accepted was reported failed and queued for retry. A 202 is an answer like a 200.ArcServiceConfig.bsvaArcadeTestnet()is the BSV Association's testnet Arcade. Arcade'sSEEN_MULTIPLE_NODESis on the network, asSEEN_ON_NETWORKis, and itsPENDING_RETRYis in flight (ArcTransactionStatus,DeferredNetworkStatus); both read asunknownbefore.test/integration/arcade_testnet_live_test.dart(dart test -P arcade) runsArcServiceagainst the live instance.submitBatchTransactionsdoes not work with Arcade, whose/txstakesapplication/octet-streamand answers with counts; nothing in libspiffy calls it (bead libspiffy-i5he). - A received payment is submitted in Extended Format. The payee submitted a counterparty's payment raw: its inputs spend the payer's outputs, which no wallet here stores, so the Extended Format fell back to raw. ARC looked the parents up itself; Arcade refuses a raw transaction with 460, "Not extended format", and the payment was queued for retries that met the same answer.
SPVValidationResult.beefHexcarries the BEEF a receive came in, and the payment's broadcast extends it from that, also when the receive waited for a header and was replayed (bead libspiffy-3qt8). - A submission answered in flight is answered with the status the network gets to. ARC waited for the network before answering a submission; Arcade answers every one RECEIVED at once and takes it to the network afterwards, so a payee's payment stayed "broadcasting" and its invoice unpaid until a status scan came round. ARCActor now hands an in-flight answer ([DeferredNetworkStatus.inFlight]) to a new
SubmissionWatcherActor, which asks ARC after each ofARCActor.inFlightFollowDelays(1, 2, 4, 8 and 15 s by default;LibSpiffyActorSystem.initialize(arcInFlightFollowDelays:)) and stops at the first status that is not in flight. The caller ofBroadcastTransactionMessage,BroadcastBEEFMessageorBroadcastDeferredPaymentMessageis answered with that status, and the wallet hears both answers. The follow runs outside ARCActor's mailbox: each wait is a timer message and each query's answer a message, so other submissions are not held behind it, andStopArcWorkMessageanswers any still followed with ARC's latest answer (bead libspiffy-2t5z).- The follows the callers did themselves are gone: the wallet coordinator's for deferred-payment broadcasts and reclaims (bead libspiffy-ggsg), and
PaymentChannelManagerActor's for funding and settlement (bead libspiffy-m715), each of which slept in its own mailbox.PaymentChannelManagerActor'sinFlightTimeoutandinFlightPollIntervalare removed, and itsbroadcastTimeoutdefaults to 60 s, since a broadcast's answer now includes the follow.
- The follows the callers did themselves are gone: the wallet coordinator's for deferred-payment broadcasts and reclaims (bead libspiffy-ggsg), and
4.5.3 #
- Each wallet's row of an orphaned transaction gets the temporary data-source check. The 4.5.2 stopgap waited 5 minutes between checks per transaction, not per wallet: a move between two wallets on one device has a row in each, and checking the payer's kept the payee's waiting, so the coin the payee received stayed pending while the payer's side confirmed (bead libspiffy-tfks). The wait is now per wallet and transaction. The check is still temporary (bead libspiffy-5it6).
4.5.2 #
- Temporary stopgap: a transaction ARC goes on calling orphaned is looked up in the data source. Transaction status comes from ARC; the data source (WhatsOnChain) is for wallet recovery, and this check is to be removed once ARC is fixed (bead libspiffy-5it6). A transaction ARC answered SEEN_IN_ORPHAN_MEMPOOL for good (here an ARC whose node could not have its parents: a regtest ARC configured for a testnet wallet) went through orphan remediation three times, after which only ARC was asked, so its outputs stayed pending and nothing could spend them (bead libspiffy-tfks). Once remediation has given up, the scan asks the configured data source every
ARCActor.orphanSourceCheckInterval(5 minutes): a transaction it knows applies as on the network, and its merkle proof confirms it only when it matches a local header. Orphan remediation's resubmissions go in Extended Format too.
4.5.1 #
- ARC is sent a transaction in Extended Format when its parents are at hand. A transaction went to ARC raw, and ARC looks up the parent of every input to check it. A coin from a block ARC never saw (one an imported wallet received long ago) could not be found, and ARC refused the spend with 460, "Not extended format: parent transaction not found": a move from an imported single-key wallet to another wallet never reached the network, and the coin it paid stayed pending (bead libspiffy-7gen). ARCActor now submits every transaction, and every unproven ancestor it submits first, in Extended Format (BRC-30), each input carrying the satoshis and locking script of the output it spends. They come from the transaction's BEEF or, without one, from the transactions any wallet stores; when one is missing the transaction goes raw, as before.
ExtendedFormat(lib/src/utils/extended_format.dart) encodes it. A BEEF broadcast (BroadcastBEEFMessage) now submits the BEEF's unproven ancestors first too, as the other broadcasts do. - A broadcast retry is sent as the first attempt was. The durable retry queue kept the raw transaction only, so a retry went without the ancestors and without the outputs its inputs spend, and was refused with 460 for as long as it was retried. The queue entry now keeps the BEEF; a retry submits its unproven ancestors and the extended form again. An entry queued before this has no BEEF and is extended from the stored parents.
4.5.0 #
- Spread inputs no longer fall back to the largest coin first.
PaymentPrivacy.spreadInputstried random coins smaller than the payment and, when six of them could not pay it, took the wallet's largest coin: in a wallet of many small coins and one large one, nearly every payment was still funded by the large one (bead libspiffy-5hnt). It now tries the largest of the smaller coins withinmaxInputs, then the smallest single coin that pays, so the change is as small as one coin allows, and only then the largest coins. - A Benford split takes the largest coins first.
SplitUTXOsToBenfordCommand(maxUtxosToSplit:)took the first coins in storage order, so a wallet's largest coin could stay whole while its small coins were split again and again. It now takes the largest. New, all optional:utxoKeyssplits only the coins named;partSatssplits each into pieces of about that size, from 2 totargetUtxoCountof them;minPartSatsmakes no piece smaller, so a coin makes fewer pieces, or none when it cannot make two (its outcome says so).SplitUTXOsCommandcarries the same three.SplitUTXOsResponse.splitCountcounts the pieces each split made.
4.4.0 #
- Opt-in payment privacy: change in parts, funding from smaller coins. A payment's change was one output and its inputs the largest coins, so next to a payment split into parts the large input and the large change output told an observer which output was the payer's (bead libspiffy-o7a4).
PayInvoiceCommand(privacy: PaymentPrivacy(...))asks for both remedies; without it a payment is built exactly as before.maxChangePartspays the change as up to that many outputs, each to a fresh change-chain address, with Benford-distributed amounts in random order;randomChangePartsdraws the count from 2 to the maximum per payment;minChangePartSats(1,000 by default) is the smallest part, and less change makes fewer parts, or one output. The selection's fee counts every change output it may pay, and the fee is worked out again for the parts it does pay.PaymentReadyEvent.changeAmountis the change of all parts.spreadInputsfunds the payment from coins smaller than it, coins of one parent transaction together and before single coins (spending already-linked coins together shows nothing new), up tomaxInputs(6 by default), since coins spent together show one owner. When they cannot pay within that, the largest coins do, as before.- Every random choice is drawn from a generator seeded with the invoice id: paying the same invoice again over the same coins signs the same transaction, as the repeat-payment rules need (libspiffy-4r0).
BenfordDistribution.distributetakes an optionalrandom, so a seeded generator gives the same amounts again.
4.3.1 #
- A channel funding goes to ARC with its unconfirmed ancestors. The channel built its funding BEEF and then broadcast the funding transaction alone, so a funding that spent a coin from a transaction ARC had not seen (fresh change, a split, a payment received peer to peer) was refused with 460, "Not extended format: parent transaction not found", and the channel never opened (bead libspiffy-b3z4).
BroadcastTransactionMessagetakes the transaction'sbeefHex, and ARCActor submits the BEEF's unproven ancestors, parents first, before the transaction, as it already did for a deferred payment; one ARC refuses is logged and passed over, since ARC may know it already. The client's funding broadcast and the server's re-submission of the funding it receives both pass their BEEF. A broadcast without one is unchanged.
4.3.0 #
- A payment's change goes to a fresh address.
PayInvoiceCommandwithout achangeAddresssent the change back to the address of the payment's first input, so every payment reused an address and linked the change to the coin it came from (bead libspiffy-zjyu). The payment coordinator now asks the wallet for the next address on its change chain (m/1/i) when the payment pays change; a payment with no change takes none, and a plugin-built transaction is unchanged. A caller'schangeAddressis still used as given. A single-key (WIF) wallet still has its one address. If the wallet gives no change address, the payment fails and says so rather than reuse one. - The change chain counts its own index. Receive and change addresses took their indices from one counter, so change addresses would leave gaps on the receive chain, and address discovery, which stops after 20 unused addresses on each chain, would read a run of payments as the end of it. A change address now takes one past the highest change index the wallet holds, and neither a generated nor a discovered change address moves the receive counter.
4.2.0 #
- P2P header sync writes a batch at a time. Every header a peer sent was written in its own storage transaction, about 2 ms a header: one node took 100 s for localnet's 45,000 headers, and three in one process reached only 36,000 after 6.5 minutes (bead libspiffy-mii4).
BlockHeaderChain.acceptHeadersvalidates a batch header by header and writes each run that extends the tip in one transaction; a header off the tip (a side branch, a reorganization) is decided after the run before it is written. A write that fails leaves the chain where the run began. A late duplicate of a full batch, all known and ending below the tip, no longer asks for the next batch again, which could have every later batch sent twice. The header cache evicts its lowest height without sorting every cached height per header (bead libspiffy-j1yc). - Where header sync stands, from the coordinator. The actor system is ready before its headers are, and nothing said when they had caught up (bead libspiffy-ndfr).
GetHeaderSyncStatusQuery(queryId:)is answered withHeaderSyncStatusResponse, andHeaderSyncStatusEventis emitted when the chain catches up with its peers or falls behind them. Both carry aHeaderSyncStatus:height,networkHeight(asLibSpiffyActorSystem.networkHeight),synced(the last peer answer held less than a full batch) andpeerCount.BlockHeadersStoredEvent, documented as every batch stored, was emitted only forStoreHeadersCommand; it now is for every batch from peers too, and carriessource.GetSPVStatusMessageanswersisSyncedassynced, not as "initialized", and header sync no longer tells SPVActor it is synced at startup. StoreHeadersCommandvalidates its headers. It wrote them straight to storage, behind the header chain, which neither checked them nor moved its tip. They now go through the header chain like a peer's; a header that does not connect, or fails a consensus check, is refused and named in theBlockHeadersStoredEvent'serror.WalletCoordinatorActor(headerSyncActor:)is no longer deprecated: the coordinator uses it.
4.1.0 #
- A reclaim that loses its race no longer strands the payment it reclaimed. A buyer signs a swap half (a deferred payment holding its coin); the seller completes the swap and the network takes it first; the buyer's
ReclaimDeferredPaymentCommandjournals its self-spend, which can never be mined. The self-spend failed as before (bead libspiffy-wfvi), but the half kept itsreclaimTxid, so completing, cancelling and reclaiming it again were all refused as "being reclaimed", and the buyer never recorded the swap the chain kept (bead libspiffy-bapp). Now a self-spend that fails, by a spend of its input or by ARC'sREJECTED, hands every input it still holds back to the payment it reclaimed, which is plain outstanding again.CompleteDeferredPaymentCommandaccepts a half whose inputs the completion itself already spent, and records the completion as seen when it has.SpendUTXOCommandrecords a spend whose spender is proven in a block (blockHeight, set only by a sender that verified the proof) even over a reservation or hold for another transaction: before, it was refused unless the wallet had recorded the spender itself, so a counterparty's mined completion, received with its proof, could not mark the coin spent. An unproven spend of an output reserved for another transaction is still refused (audit C1), since either spend may yet be mined. The same spend reported twice journals nothing; a spend by another transaction of an output already recorded as spent is refused as a double spend, proven or not. SPV receives pass the height when the BEEF carried the spender's proof, andSpentOutputRepairspends a reserved output when the spender's row has its block. - A fresh address from the public API. The coordinator's
GenerateAddressCommand(walletId, label:, purpose:, includePublicKey:, requestId:)answers withAddressGeneratedEvent(the address, its chain and derivation index, and its public key when asked for) once the read model holds the address, so a payment to it attributes at once. Before, an application had to import the aggregate's command frompackage:libspiffy/internals.dart(bead libspiffy-u5qe). - "Insufficient funds" names the amount and the shortfall, both when the wallet has no spendable coin and when it has too little (bead libspiffy-khb7).
- Nothing is printed to stdout. eventador 4.0.0 moves its
[PersistentActor]recovery lines,Command processing failed …and every otherprinttopackage:logging(loggers undereventador.), so a host speaking a protocol over stdio (an MCP server) need not divert them (bead libspiffy-oe77). - A sold listing's price is credited.
CheckForeignSpendsCommandmarked a wallet output spent by a proven foreign spender and recorded nothing else, so a Listed NFT bought by a stranger lost its token output and the price it paid to the listing's owner key, a key of the selling wallet, never appeared among the wallet's UTXOs or in its balance (bead libspiffy-zyfr). A proven spender is now 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 history.ForeignSpendsCheckedEventis announced once the read model shows it.ForeignSpendgainsspenderBeefHex,recordedandrecordError. ARCActor answersCheckOutputSpendersMessagewith the proven spender's BEEF and records nothing itself.
4.0.0 #
-
Breaking:
IsolateConfigis gone, with every parameter that took one. libspiffy never ran a storage operation in an isolate, and nothing read the setting. Removed: the class,LibSpiffyActorSystem.initialize(isolateConfig:),initializeLibSpiffy(isolateConfig:),StorageFactory.createReadModelStorage(isolateConfig:),StorageFactory.createStorages(isolateConfig:)andIsarWalletStorage(isar, config:). Delete the argument; nothing else changes. -
Breaking: two settings that were stored and never read are gone.
PaymentChannelAggregate(networkType:): the aggregate takes a channel's network from the server address it pays.HeaderSyncActor(startHeight:)andInitiateHeaderSyncMessage(startHeight:): header sync continues from the tip of the stored chain.LibSpiffyActorSystem.initialize(startHeight:)stays and is documented as what it is, the height this node reports to peers in its version handshake. -
WalletRowRulesis exported.ReadModelStorage.storeWalletstates its contract in terms ofWalletRowRules.canonicalNetworkandWalletRowRules.defaultNetwork; an application implementing the interface can now call them, and read a wallet row'snetworkwithNetworkName. -
A deferred payment can carry a deadline, at which the wallet reclaims it by itself.
PayInvoiceCommand(deadline:)(a UTC instant, bead libspiffy-8442) is journaled with the payment's hold (TransactionSpendDeferredEvent.deadline), stored (DeferredPayment.deadline; Isar property, Postgres migration v029) and listed (GetDeferredPaymentsQuery(dueBefore:),DeferredPaymentQuery.dueBefore). The coordinator sweeps every wallet's outstanding payments atLibSpiffyActorSystem.initialize(deadlineSweepInterval:)(a minute by default) and reclaims each one whose deadline has passed, asReclaimDeferredPaymentCommandwould; the answer is aDeferredPaymentReclaimedEventwith request iddeadline-<txid>. A payment seen, mined, completed, failed or cancelled before its deadline is left alone. The deadline bounds the option the payment gives its holder and does not end it: the reclaim ends it when the network has it. A node that withdrew its halves past an age sets a deadline instead. Found on the way:DeferredPaymentQuery.allStatesomittedcompleted, soincludeResolveddid not list completed halves; it does now. -
Change from a payment is spendable when the network takes it, not a status scan later. When ARC reported a payment on the network while the read model held its transaction row and not yet its outputs, the change stayed pending until the next status scan (30 s), and a
CheckDeferredPaymentStatusCommandsent meanwhile did not answer until then. Settling a payment and checking it at once took 30 s.ARCActorworked out which UTXOs to spend and make available from the read model, which shows a recording one event at a time. The wallet aggregate now decides it from its own state:ARCActorsends oneApplyDeferredSpendCommandwith the transaction, in place of aSpendUTXOCommandand aMarkUTXOAvailableCommandper UTXO. The same check now answers in under a second. Breaking:ARCActor(deferredSpendRecheckDelay:)is gone, with the recheck it timed. -
A deferred payment that the counterparty completes. A sale in one transaction is signed by two wallets: the first records a half (its own input signed, a placeholder for the other side's) as a deferred payment, which holds its input.
CompleteDeferredPaymentCommand(walletId, txid, rawHex)records the completed transaction in the half's place: the aggregate refuses unless it has the same version, lock time, inputs, sequences and outputs, and the wallet's own unlocking scripts unchanged. The completed transaction takes over the hold; the half becomesDeferredPaymentState.completed(new, appended), and its own pending outputs are voided. Journaled asDeferredSpendCompletedEvent(wallet.transaction.deferred_completed). Withdrawing a half isReclaimDeferredPaymentCommand, as for any deferred payment. -
Outputs the wallet holds, spent by someone else.
CheckForeignSpendsCommandasks the data source (SpentOutputLookup) who spent each plugin output the wallet holds, or the outputs named. A spender that is mined and whose merkle proof matches the local headers marks the output spent and is returned with its raw transaction (ForeignSpend); anything less is reported as a lead and changes nothing. A token taken back by its issuer, a listing bought, a pot seized: the wallet learns of it by asking about what it holds, never by scanning. ARCActor answersCheckOutputSpendersMessage. -
Plugin actions that need no funding coin. When a plugin's
requiredFundingUtxoCount(action)is 0, the payment coordinator selects and reserves no wallet coin. It does not refuse the payment when the wallet has no coins. It calls the plugin with an empty funding list; the plugin names the keys it signs with throughkeyFor. A token that pays its own fees (tstokenlib's Fuelled NFT) is moved this way. Before, the coordinator always selected a coin for the payment's amount and recorded it as spent, although the transaction never spent it. -
Plugin payments hold every wallet output they spend. A plugin's transaction can spend wallet outputs that the plugin found itself, such as a token the wallet holds, and the earmarks auto-provisioned for the payment. They are now held with the payment and spent when the network takes it, like the funding. A payment that spends an output already held by another payment, spent, or not yet on the network is refused with the reason.
-
A plugin can name the key that signs an input.
PluginTransactionRequest.keyFor(pubkeyHash)answers aPluginKey: a signer bound to the wallet key with that public key hash, and the key's public key. It fails when the wallet holds no such key. libspiffy finds the key for a plugin's input from the script the signature covers. A covenant that signs only the code after anOP_CODESEPARATOR, with its owner in a header before it, names nobody there, so its input was signed with the funding key. The payment and provisioning paths both offer the lookup. -
An output the wallet holds as unspent, although its own confirmed transaction spends it, is repaired. An imported wallet held two outputs as available that were spent in their parent's own block: the import recorded by height only, children before parents, and a child can mark only an output the wallet already holds. A deferred payment later spent one, and ARC kept it
SENT_TO_NETWORKfor ever. The import now records the oldest block first and, inside a block, parents before children.SpentOutputRepairruns once per wallet load and after an import: it reads only the wallet's own records, marks such an output spent, and fails an outstanding deferred payment that holds it (DeferredNetworkStatus.inputSpent,INPUT_SPENT, a definitive failure). A transaction handed to the wallet whose input a confirmed transaction spends is voided (VoidUnsettledTransactionCommand,TransactionVoidedEvent,wallet.transaction.voided): its row fails and its pending outputs are voided.ARCActorchecks the inputs of a transaction unsettled for longer thaninFlightStuckAfter(1 h) through the optionalSpentOutputLookup, and acts only on a spender whose merkle proof matches a local header. -
A payment carries the payer's memo.
PayInvoiceCommand(memo:)andValidateBEEFCommand(memo:)journal the note with the payment (TransactionRecordedEvent,TransactionImportedEvent,UTXOReceivedEvent) and keep it on the transaction row (BitcoinTransaction.memo). The first non-empty memo stays: a later record never blanks or replaces it, on the in-memory, Isar and Postgres backends. A receive parked until its header arrives keeps its memo (PendingReceive.memo, Postgres migration v028). -
A derived anchor key is kept for 5 minutes. Deriving one reads the mnemonic from secure storage and stretches it to the seed, 0.3 to 0.4 s on a phone, and a BRC-100 message-box check runs two key operations every 30 s. The derived anchor key is kept, never the mnemonic or the HD root; removing a wallet's key material forgets it.
-
Commands are taken before the header sync ends.
LibSpiffyActorSystem.readycompletes once the actors run, before the CDN sync and the P2P start thatinitialize()still waits for. Creating or importing a wallet needs no chain; on a first install the CDN sync runs for minutes, and wallet creation timed out behind it. -
networkHeightis what peers reported. spiffynode's tip tracker counted the catch-up headers libspiffy requested twice, so the tip ran ahead of the real one and the chain never looked synced (99%).LibSpiffyActorSystem.networkHeightis now the higher of the connected peers' handshake heights and the local chain, and 0 while no peer is connected. -
P2P peers are dialled again when none is left. spiffynode removes dead peers and adds none, so a laptop that slept stayed at zero peers until restart. Every 30 s (
LibSpiffyActorSystem.peerUpkeepInterval) with no peer left, the seeds are resolved and dialled again, and header sync resumes when one connects. -
The CDN header sync is retried, and reports how it ended. One stalled chunk download ended the CDN sync, and the rest of the chain came from peers, slowly. The actor system now runs up to three passes, each resuming from the chain's tip on a fresh HTTP client, before it leaves headers to peers.
initialize(onHeaderSyncResult:)is called with theCdnSyncResultof the startup sync: success, the error that ended it, or that no CDN was configured. -
A wallet manager's refusal reaches the application with its reason. The coordinator asked the wallet manager for a typed answer; a refusal (an unknown wallet, say) is a
FailureResponse, and was reported as an ask type mismatch. The failure event now carries the manager's reason. -
BRC-100 key operations, and BEEF V2 and Atomic BEEF.
Brc100Keysruns BRC-100's key methods on one root key: BRC-43 protocols, self and anyone counterparties, BRC-42 child keys, BRC-3 signatures, BRC-2 encryption and HMACs, pinned to the ts-stack conformance vectors.Brc100KeyOperationCommandruns them in the wallet with an anchor key as root; for payment spend keys it gives out public keys only.Brc95reads BEEF V1, V2 (BRC-96) and Atomic BEEF (BRC-95) into V1 and wraps V1 as Atomic, and refuses a BEEF that holds anything but the subject and its ancestors.DeriveType42DestinationCommand(payerAnchorContext:)pays with an anchor as the payer key, as a BRC-29 sender to a BRC-100 wallet must. -
Breaking: Isar is now
isar_community3.3.2. The originalisar3.1.0+1 is unmaintained, and its Android library is aligned to 4 KB pages, which Google Play rejects for apps targeting Android 15 or later.Isaris part of the public API (LibSpiffyActorSystem.initialize(isar:),LibSpiffySchemas), so hosts must switch too: depend onisar_community,isar_community_flutter_libsandisar_community_generator^3.3.2, changepackage:isar/isar.dartimports topackage:isar_community/isar.dart, and regenerate.g.dartfiles. Requireseventador4.0.0 andduraq_isar3.0.0. Schema ids are unchanged, and databases written by Isar 3.1 open without migration (checked in both directions). -
Hosts on macOS and iOS: the published
isar_community3.3.2 binary wastes disk space without bound. It is built on libmdbxv0.13.8-temp-upstream-fix, which on Apple platforms preallocates the whole new file size past the end of the database file every time the file grows, and never releases it: a 135 MiB header store holds 1.9 GiB on disk, a full testnet header store about 59 GiB. Every Isar database is affected, not only headers. libmdbx fixed it in v0.13.9;isar_communityhas not released the upgrade (isar-community/isar-community#85, #129). Until it does, override both packages with the 3.3.2 build on libmdbx v0.13.12, as libspiffy's ownpubspec.yamldoes forisar_community:dependency_overrides: isar_community: git: url: https://github.com/stephanfeb/isar-community.git ref: 3.3.2-libmdbx-0.13.12 path: packages/isar_community isar_community_flutter_libs: # Flutter apps only git: url: https://github.com/stephanfeb/isar-community.git ref: 3.3.2-libmdbx-0.13.12 path: packages/isar_community_flutter_libsThe fixed binary does not give back space a database already holds past its end. With the database closed, extending the file by one page and truncating it back to its length releases it.
test/storage/isar_disk_allocation_test.dartfails on the published binary. -
Mainnet runs on the network it was given, everywhere. The payment channel manager and the default crypto service were started without a network and so encoded mainnet settlement outputs as testnet; they now get the actor system's network.
WhatsOnChainDataSourceaccepts both spellings (main/mainnet,test/testnet).NetworkNameis exported so hosts can compare network names through one helper. -
A payment to an address of the other network is refused.
PaymentCoordinatorActortakes the network (LibSpiffyActorSystempasses its own) and refuses a P2PKH output, from an invoice's address list or a structured output, whose address belongs to the other network ("is a mainnet address; this wallet is on testnet"). Both networks share keys, so such a payment reached a key the payee owns but a wallet that never sees it, and the payer's coins stayed held for it. -
Mainnet ARC defaults to GorillaPool (
ArcServiceConfig.gorillaPoolMainnet, no API key).gorillaPoolTestnetis available too; testnet still defaults to TAAL. -
Shut LibSpiffy down before closing Isar. The new Isar core crashes the process if the database is closed, or the isolate ends, while writes started by wallet creation are still running.
LibSpiffyActorSystem.shutdown()waits for them; closing the actor system alone does not. -
A payment with no outputs is refused, not a division by zero.
PayInvoiceCommandwith neitheroutputsnoraddressessplit the amount over zero addresses and failed withIntegerDivisionByZeroException, which told an application nothing (found by SpiffyVault: a payee whose wallet had refused to create an invoice was relayed to the payer as an invoice with no addresses). It now fails with anArgumentErrorsaying the invoice has nothing to pay. -
Reading the chain tip no longer scans the whole header store.
IsarWalletStorage.getChainTipandgetBestHeightwalked the height index from the top with Isar's asyncfindFirst(), which in Isar 3 fetches every matching row and returns the first (onlyfindFirstSyncpasses a limit of 1). Every call therefore read and decoded the entire header store: over a second on a phone holding testnet's history, paid by every SPV check and by every application reading confirmations (found by SpiffyVault: a one-second stall opening a wallet, timed to the tip read). Both queries now carrylimit(1), and the read is a one-row index walk. Anyone reading the header store with a descending where clause should do the same. -
A wallet import fetches each transaction once and says so as it goes.
ImportActorfetched every transaction of every discovered address in turn, so a transaction touching several of the wallet's addresses (a payment with its change, a consolidation) was fetched — raw hex, proof and details, three requests — once per address and dropped as a duplicate only afterwards; and it reported progress once per address, so an address with hundreds of transactions left an application without a word for minutes (found by SpiffyVault: 819 history entries, a UI that sat at "Collecting transactions from address 1/…"). The per-address histories are now unioned first, each txid is fetched once, andWalletImportProgressEventis emitted per transaction:Fetching transactions: n/N(n fetched with proof, progress 0.40–0.55) and thenRecording transactions: n/N(n recorded through the wallet, 0.55–0.90), withtotalTransactionsthe number of distinct transactions. TheCollecting transactions from address i/NandProcessing transactionsmessages are gone. -
An imported transaction's inputs are linked to what they spend.
ImportActorfetched every parent transaction to compute the fee and the sending addresses, then dropped them:RecordImportedTransaction Command.ancestorswas empty for an import, so the wallet projection had no evidence for the inputs and left them unlinked (an application showed "Unknown" for the amount of every input of a received transaction). The fetched parents now travel as the import's ancestors (raw transaction, no BUMP), are filed in the ancestor store, and each input gets its transaction-address link with the spent output's address and amount. Transactions imported before this keep their unlinked inputs until re-imported. -
A wallet import can be resumed. An import ran in memory only; a host killed mid-way (a phone suspended and reclaimed) was left with a wallet that looked partly restored and no way to continue.
ImportWalletMessage (resume: true)/ImportWalletCommand(resume: true)/LibSpiffyActorSystem.resumeWalletImportimport an existing wallet again: the key is read from secure storage (ImportActor(secureStorage:)— the xpriv or WIF it was imported with, or the mnemonic and passphrase it was created with), discovery re-runs, addresses the read model holds and transactions it has recorded are skipped, the rest is imported. The same message resumes after a kill, retries after a network failure and rescans a wallet for history it gained elsewhere; sent while the import still runs it is ignored as a duplicate. A watch-only wallet is refused.WalletImportCompletedEvent/ImportCompleteEventgaintransactionsSkipped(already held) andtransactionsFailed(could not be fetched or proven; not zero means the import is incomplete and a resume tries exactly these again). -
A second import command for a running wallet no longer doubles its events. The coordinator subscribed to the wallet's import notifications again without cancelling the first subscription.
-
WhatsOnChainDataSourceabandons and retries a request that hangs. A request on a connection the network silently dropped (a suspended phone, a carrier NAT) hung until the operating system gave up, a minute or more, and cost the caller a transaction each time. Requests now time out (requestTimeout, default 30 s) and a timeout, a dropped or refused connection or a failed handshake is retried with the same backoff as a 429; a 404 or a malformed body is still an answer and is not retried.
3.0.1 #
P2P reaches the network from its DNS seeds again (found by cloak-cli, whose
first testnet and mainnet starts were refused with Could not connect to any of 1 peer(s) although the seeds' nodes were up).
- Every address of a seed is dialled. A seed was dialled as one
host:port, which reaches whichever address the resolver lists first; at the time two oftestnet-seed.bitcoinsv.io's four nodes accepted a connection and never answered. Peer entries, named or default, are now resolved to every address they hold (PeerAddresses), each dialled in parallel, and a start fails only if none answers. The error names each address, the seed it came from and why it failed, and each failure is logged; before, the reasons were collected and dropped. - The start goes on at the first peer that answers. It waited for every dial, so one dead address held each start for its connect timeout (19 s on testnet). The other dials finish in the background, joining as peers or logged as failures; a peer that connects after the system shut down is closed rather than left holding its socket.
- The seeds are the node's own.
NetworkParams.dnsSeedsholds them per network, replacing a private one-seed list: mainnetseed.bitcoinsv.io,seed.satoshisvision.network,seed.bitcoinseed.directory; testnettestnet-seed.bitcoinsv.io,testnet-seed.bitcoincloud.net,testnet-seed.bitcoinseed.directory, and GorillaPool'stestnet.gorillapool.ioandseed.gorillapool.io; regtest none. - Header sync asks the peer furthest ahead.
getheaderswent to the first connected peer. With every seed address dialled that can be a node stuck far behind (one mainnet seed's node reports height 413,551), which answers with nothing past its own height. Peers are now asked in order of the height their version handshake reported (inSyncOrder).
3.0.0 #
Three payment modes, made explicit (spv-understanding.md, "Payment modes"):
both parties online; a service taking payments for an offline payee on the
payee's delegated chain (m/2/i) and handing them over proven; and a
payer paying an offline payee directly with type-42 (BRC-42) keys from an
anchor the payee publishes, one anchor per identity. An xpub wallet's money
is now watch-only, as it always should have been, and a transaction that is
not the wallet's is refused rather than recorded.
Upgrading from 2.x #
- Change/receive flags are an
AddressChain, and signing paths aKeyPath. ReplaceisChange: truewithchain: AddressChain.change,SigningPath(i)withHdKeyPath(i), and thederivationIndices/isChangeFlagsofSignTransactionCommandwithkeyPaths. See Breaking below for every renamed member. AddressMetadata.chainis nullable: null for a type-42 address.- Stored data needs no conversion. Journals and snapshots written by 2.x
replay as they were. Isar adds the new address fields itself. PostgreSQL
deployments run migrations v025–v027 (
PostgresMigrations.migrate()); v027 refuses to roll back while a type-42 address row exists. - An xpub wallet no longer reports spendable money: its UTXOs are
watchOnlyBalance. An app that showed them as spendable was showing money it could not spend.
Added #
- Payments for an offline payee (bead libspiffy-m8qu; spv-understanding.md,
"Payment modes"). A service keeps a payee's xpub as a watch-only wallet and
answers invoice requests for them; the payee's wallet takes the payment
once it is mined.
- A third chain of the HD tree, delegated (
m/2/i): an xpub wallet issues every address on it, so the service and the payee's own wallet (receive chain,m/0/i) can never hand out the same address. ExportTransactionQuery/TransactionExportedEvent: a proven transaction of the wallet as a BEEF carrying its proof. Refused while the transaction has no proof verified on our header chain.ImportTransactionCommand.delegatedIndices: the payee's wallet derives those delegated addresses from its own key, records them (without moving its own address counter) and then imports the payment, which it can spend like any other.- Address discovery (wallet import) scans the delegated chain as well as the receive and change chains.
InvoiceCreatedEvent.issuedAddressesnames each address an invoice issued with its chain and derivation index (IssuedAddress), so the payment mode is visible where it is chosen;TransactionExportedEvent .delegatedIndicescarries the indices the payee imports with.
- A third chain of the HD tree, delegated (
Type42: BRC-42 (type-42) key derivation. A payer derives a per-invoice destination from the recipient's public key (deriveChildPublic), and the recipient the matching spend key (deriveChildPrivate). Pinned to the official BRC-42 test vectors and to the Go-verified values of NodeCast's Tier-0 harness. A tweak of 0 mod N is refused.- Payer-broadcast payments to an offline payee with type-42 (bead
libspiffy-zxkd; spv-understanding.md, "Payment modes"). No service and no
xpub: the payer derives the address from the payee's published anchor
key, broadcasts the payment itself and hands it over.
- Anchor keys, one per anchor context (bead libspiffy-fdal), for a
wallet that holds its keys:
m/3'/0'/k1'/k2', k1 and k2 fromSHA-256("libspiffy/type42-anchor" ‖ context). Identities sharing a wallet publish unrelated anchors; a context carrying an epoch lets an app rotate one. An empty context is refused.IssueAnchorKeyCommand/AnchorPublicKeyEvent(journaled once per context,AnchorKeyIssuedEvent), andSignWithAnchorKeyCommand/AnchorSignedEvent(ECDSA over SHA-256 of a message, RFC 6979, low S; byte for byte go-sdk's). DeriveType42DestinationCommand/Type42DestinationEvent: a destination for a recipient's anchor key (and the context it was published with, passed through), with a payer key atm/3'/1'/n'never used twice, and a BRC-29 invoice number unless one is given. Journaled (Type42DestinationDerivedEvent), so a restarted wallet does not reuse a payer key.ImportTransactionCommand.type42DerivationsandValidateBEEFCommand.type42Derivations: the hand-off {anchor, context, payer key, invoice number}. The payee's wallet finds the anchor's context (its issued anchors first, else the hand-off's, refused unless it gives the anchor), derives each destination from its own anchor key, journals the derivation (Type42AddressRecordedEvent; never a private key), takes the payment in and signs for it with the anchor key's type-42 child.TransactionExportedEvent.type42Derivations: the hand-off for each type-42 destination the exported transaction pays, on the payer's side and the payee's.KeyPath(HdKeyPath,Type42KeyPath),Type42DerivationandType42Destinationare exported;AddressMetadata.type42records a type-42 address row. Postgres migration v027 adds its columns.- A type-42 output cannot be found from the seed alone: a wallet restored by address discovery does not see it, and the payer's hand-off, given again, recovers it.
- Anchor keys, one per anchor context (bead libspiffy-fdal), for a
wallet that holds its keys:
- The validated header chain is exported:
BlockHeaderChain,BlockHeaderAnchor,HeaderAcceptResult,HeaderRejectReasonandNetworkParams, for a host that answers header questions from it.
Breaking #
AddressChainreplaces every change/receive flag.isChangebecomeschainonAddressMetadata,DiscoveredAddress,RegisterDiscoveredAddressCommand,AddressDiscoveredEventandSignMultisigTransactionCommand; theReadModelStorageaddress queries takeAddressChain? chain. Journals, snapshots and stored rows written before are read as they were: an event or snapshot without a chain reads itsisChange, and an Isar address row keepsisChangebeside the new nullablechain. Postgres migration v026 replacesaddresses.is_changewithchain.- A key's path is a
KeyPath: an HD path (HdKeyPath(index, chain:)) or a type-42 derivation (Type42KeyPath).SigningPathis gone for it;SignInputCommand.keyPathreplacesderivationIndexandisChange, andSignTransactionCommand.keyPathsreplacesderivationIndicesandisChangeFlags.AddressMetadata.chainis null for a type-42 address, which is on no chain. CryptoService:derivePrivateKey(hdKey, addressIndex, {chain})andderiveAddress(hdPublicKey, addressIndex, {chain, network})replacederivePrivateKey(hdKey, accountIndex, addressIndex, {coinType, isChange})(whoseaccountIndexwas, in fact, the chain) andgenerateReceivingAddress/generateChangeAddress.BuildFundingTransactionCommandlosesderivationIndexandisChange, which nothing read: channel funding signs each UTXO with its own path.AddressGeneratedResponsecarries the address'schain.
Changed #
- The guides moved from
docs/todoc/, pub's layout, beside the audit reports already there.spv-understanding.md, which the API documentation cites throughout, ships with the package.
Fixed #
-
An import was announced before the wallet's read model held it when another wallet of the same process already held the transaction (a payer and its payee, or a service and the payee it hands a payment to): the wait matched any wallet's row and event of the txid. Every read-model wait of the coordinator and the channel manager now names its wallet.
-
A transaction that is not the wallet's was recorded as if it were. One that pays none of the wallet's addresses (nor an invoice of it) and spends none of its outputs passed SPV:
ImportTransactionCommandput it in the wallet's history with nothing in it, andValidateBEEFCommandsubmitted it to ARC. Both now refuse it, saying so. -
An xpub (watch-only) wallet's money was reported as spendable. Such a wallet holds no private key, yet
WalletState.availableBalance,BalanceResponse.totalBalance,ReadModelStorage.getBalanceand the wallet row's balances counted its UTXOs, coin selection picked them, and signing then failed. Every UTXO of an xpub wallet is now watch-only funds on both layers: kept, reported aswatchOnlyBalance, never spent (bead libspiffy-bfs1). -
The Postgres wallet row recorded every wallet as
hd, and the in-memory row had nowalletTypeat all.getWallet(id)['walletType']is now the type the wallet was created with, on every backend.