@bsv/wallet-toolbox 2.3.3 → 2.4.1

package/CHANGELOG.md

@@ -6,6 +6,17 @@ attention to changes that materially alter behavior or extend functionality.
 
 ## wallet-toolbox (unreleased)
 
+- Release prep for `2.4.1`: define one managed-change policy across Knex and IndexedDB allocation,
+  counting, default balance reporting, `balanceAndUtxos`, and `noSendChange`.
+  Only complete BRC-29 signer metadata is eligible; custom rows remain visible
+  through raw default-basket listing for recovery. `internalizeAction` now
+  rejects basket insertion into `default`, prevents managed change from being
+  reclassified, promotes verified legacy BRC-29 rows through `wallet payment`,
+  and permits incompatible custom rows to be swept to non-default baskets
+  without changing wallet balance.
+
+- Release prep for `2.4.0`: security fix for `GHSA-36f9-7rg5-cpf8`. `buildSignableTransaction` now verifies that storage-returned outputs match the caller's requested `args.outputs` before signing (rejects substituted/altered/reclassified/missing outputs), and rejects any unrequested output that isn't client-derived change or a single commission output bounded by `MAX_STORAGE_COMMISSION_SATOSHIS`. `WalletPermissionsManager.createAction` independently verifies requested outputs are present in the signable transaction before authorizing, as defense-in-depth. Protects against a malicious or compromised `StorageClient` operator substituting or injecting outputs that would be signed and broadcast without the caller's knowledge.
+
 - Release prep for `2.3.3`: add Arcade-first wallet service wiring, go-chaintracks
   live client/SSE support, resilient ARC/Arcade status handling, monitor
   rebroadcast safeguards, and callback-token redaction for Arcade SSE logs.

package/README.md

@@ -75,6 +75,10 @@ const result = await wallet.createAction({
 
 [Full API documentation](https://bsv-blockchain.github.io/wallet-toolbox) is available on GitHub Pages.
 
+See [Managed change, sweeping, and recovery](./docs/managed-change-policy.md)
+for the default-basket invariant, automatic funding policy, and supported
+`internalizeAction` repair paths.
+
 The codebase has detailed JSDoc annotations throughout — these will surface inline in editors like VS Code.
 
 ## Development

package/docs/client.md

@@ -1341,6 +1341,7 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 ```ts
 export interface ChaintracksChainTrackerOptions {
     maxRetries?: number;
+    retryDelayMs?: number;
 }
 ```
 
@@ -3846,6 +3847,7 @@ export interface ListOutputsSpecOp {
     includeOutputScripts?: boolean;
     includeSpent?: boolean;
     totalOutputsIsSumOfSatoshis?: boolean;
+    managedChangeOnly?: boolean;
     resultFromTags?: (s: StorageProvider, auth: AuthId, vargs: Validation.ValidListOutputsArgs, specOpTags: string[]) => Promise<ListOutputsResult>;
     resultFromOutputs?: (s: StorageProvider, auth: AuthId, vargs: Validation.ValidListOutputsArgs, specOpTags: string[], outputs: TableOutput[]) => Promise<ListOutputsResult>;
     filterOutputs?: (s: StorageProvider, auth: AuthId, vargs: Validation.ValidListOutputsArgs, specOpTags: string[], outputs: TableOutput[]) => Promise<TableOutput[]>;
@@ -3856,6 +3858,14 @@ export interface ListOutputsSpecOp {
 
 See also: [AuthId](./client.md#interface-authid), [StorageProvider](./storage.md#class-storageprovider), [TableOutput](./storage.md#interface-tableoutput)
 
+###### Property managedChangeOnly
+
+Restrict the operation to wallet-managed, BRC-29-signable change.
+
+```ts
+managedChangeOnly?: boolean
+```
+
 ###### Property tagsParamsCount
 
 How many positional tags to intercept.
@@ -14020,7 +14030,8 @@ Proceeds in three stages:
 3. Find an output that comes as close to funding as possible (targetSatoshis).
 4. Return undefined if no output is found.
 
-Outputs must belong to userId and basketId and have spendable true.
+Outputs must belong to userId and basketId and satisfy the wallet-managed
+BRC-29 change policy.
 Their corresponding transaction must have status of 'completed', 'unproven', or 'sending' (if excludeSending is false).
 
 ```ts
@@ -15800,6 +15811,10 @@ sum of output satoshis
 Uses `listOutputs` to iterate over chunks of up to 1000 outputs to
 compute the sum of output satoshis.
 
+For `default`, only wallet-managed BRC-29 change is included. Raw
+administrative `listOutputs({ basket: 'default' })` remains available to
+discover legacy incompatible rows for recovery.
+
 ```ts
 async balanceAndUtxos(basket: string = "default"): Promise<WalletBalance> 
 ```
@@ -17175,15 +17190,15 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 
 | | | |
 | --- | --- | --- |
-| [WalletErrorFromJson](#function-walleterrorfromjson) | [importBRC38](#function-importbrc38) | [selectBulkHeaderFiles](#function-selectbulkheaderfiles) |
-| [WocHeadersBulkListener](#function-wocheadersbulklistener) | [importBRC39](#function-importbrc39) | [serializeBaseBlockHeader](#function-serializebaseblockheader) |
-| [WocHeadersBulkListener_test](#function-wocheadersbulklistener_test) | [importSingleOutpoint](#function-importsingleoutpoint) | [serializeBaseBlockHeaders](#function-serializebaseblockheaders) |
+| [WalletErrorFromJson](#function-walleterrorfromjson) | [importBRC39](#function-importbrc39) | [selectBulkHeaderFiles](#function-selectbulkheaderfiles) |
+| [WocHeadersBulkListener](#function-wocheadersbulklistener) | [importSingleOutpoint](#function-importsingleoutpoint) | [serializeBaseBlockHeader](#function-serializebaseblockheader) |
+| [WocHeadersBulkListener_test](#function-wocheadersbulklistener_test) | [internalizeAction](#function-internalizeaction) | [serializeBaseBlockHeaders](#function-serializebaseblockheaders) |
 | [WocHeadersLiveListener](#function-wocheaderslivelistener) | [internalizeAction](#function-internalizeaction) | [setDisableDoubleSpendCheckForTest](#function-setdisabledoublespendcheckfortest) |
-| [WocHeadersLiveListener_test](#function-wocheaderslivelistener_test) | [internalizeAction](#function-internalizeaction) | [sha256Hash](#function-sha256hash) |
-| [acquireDirectCertificate](#function-acquiredirectcertificate) | [isArcAcceptedTxStatus](#function-isarcacceptedtxstatus) | [sha256HashOfBinaryFile](#function-sha256hashofbinaryfile) |
-| [addWork](#function-addwork) | [isArcDoubleSpendTxStatus](#function-isarcdoublespendtxstatus) | [shareReqsWithWorld](#function-sharereqswithworld) |
-| [arcDefaultUrl](#function-arcdefaulturl) | [isArcInvalidTxStatus](#function-isarcinvalidtxstatus) | [signAction](#function-signaction) |
-| [arcGorillaPoolUrl](#function-arcgorillapoolurl) | [isArcServiceErrorStatus](#function-isarcserviceerrorstatus) | [signAndComplete](#function-signandcomplete) |
+| [WocHeadersLiveListener_test](#function-wocheaderslivelistener_test) | [isArcAcceptedTxStatus](#function-isarcacceptedtxstatus) | [sha256Hash](#function-sha256hash) |
+| [acquireDirectCertificate](#function-acquiredirectcertificate) | [isArcDoubleSpendTxStatus](#function-isarcdoublespendtxstatus) | [sha256HashOfBinaryFile](#function-sha256hashofbinaryfile) |
+| [addWork](#function-addwork) | [isArcInvalidTxStatus](#function-isarcinvalidtxstatus) | [shareReqsWithWorld](#function-sharereqswithworld) |
+| [arcDefaultUrl](#function-arcdefaulturl) | [isArcServiceErrorStatus](#function-isarcserviceerrorstatus) | [signAction](#function-signaction) |
+| [arcGorillaPoolUrl](#function-arcgorillapoolurl) | [isAutoSpendableChangeOutput](#function-isautospendablechangeoutput) | [signAndComplete](#function-signandcomplete) |
 | [arcadeDefaultUrl](#function-arcadedefaulturl) | [isBaseBlockHeader](#function-isbaseblockheader) | [stampLog](#function-stamplog) |
 | [arraysEqual](#function-arraysequal) | [isBlockHeader](#function-isblockheader) | [stampLogFormat](#function-stamplogformat) |
 | [asArray](#function-asarray) | [isCreateActionSpecOp](#function-iscreateactionspecop) | [subWork](#function-subwork) |
@@ -17192,62 +17207,63 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 | [asBsvSdkScript](#function-asbsvsdkscript) | [isListOutputsSpecOp](#function-islistoutputsspecop) | [toBinaryBaseBlockHeader](#function-tobinarybaseblockheader) |
 | [asBsvSdkTx](#function-asbsvsdktx) | [isLive](#function-islive) | [toLookupNetworkPreset](#function-tolookupnetworkpreset) |
 | [asString](#function-asstring) | [isLiveBlockHeader](#function-isliveblockheader) | [toWalletNetwork](#function-towalletnetwork) |
-| [asUint8Array](#function-asuint8array) | [isMoreWork](#function-ismorework) | [transactionInputSize](#function-transactioninputsize) |
-| [attemptToPostReqsToNetwork](#function-attempttopostreqstonetwork) | [keyOffsetToHashedSecret](#function-keyoffsettohashedsecret) | [transactionOutputSize](#function-transactionoutputsize) |
-| [blockHash](#function-blockhash) | [listActionsIdb](#function-listactionsidb) | [transactionSize](#function-transactionsize) |
-| [buildBeefForOutpoints](#function-buildbeefforoutpoints) | [listCertificates](#function-listcertificates) | [updateChaintracksFiatExchangeRates](#function-updatechaintracksfiatexchangerates) |
-| [buildChaintracksOptionsWithIngestors](#function-buildchaintracksoptionswithingestors) | [listOutputsIdb](#function-listoutputsidb) | [updateExchangeratesapi](#function-updateexchangeratesapi) |
-| [buildSignableTransaction](#function-buildsignabletransaction) | [lockScriptWithKeyOffsetFromPubKey](#function-lockscriptwithkeyoffsetfrompubkey) | [updateReqsFromAggregateResults](#function-updatereqsfromaggregateresults) |
-| [classifyMerklePathResponse](#function-classifymerklepathresponse) | [logCreateActionArgs](#function-logcreateactionargs) | [upgradeAllStoresV1](#function-upgradeallstoresv1) |
-| [classifyReqStatus](#function-classifyreqstatus) | [logWalletError](#function-logwalleterror) | [upgradeCertificateFields](#function-upgradecertificatefields) |
-| [completeSignedTransaction](#function-completesignedtransaction) | [makeAtomicBeef](#function-makeatomicbeef) | [upgradeCertificates](#function-upgradecertificates) |
-| [computeMerklePath](#function-computemerklepath) | [makeBrc114ActionTimeLabel](#function-makebrc114actiontimelabel) | [upgradeCommissions](#function-upgradecommissions) |
-| [computeMerkleRoot](#function-computemerkleroot) | [makeChangeLock](#function-makechangelock) | [upgradeMonitorEvents](#function-upgrademonitorevents) |
-| [convertBitsToTarget](#function-convertbitstotarget) | [makeMerklePathNote](#function-makemerklepathnote) | [upgradeOutputBaskets](#function-upgradeoutputbaskets) |
-| [convertBitsToWork](#function-convertbitstowork) | [markStaleInputsAsSpent](#function-markstaleinputsasspent) | [upgradeOutputTags](#function-upgradeoutputtags) |
-| [convertBufferToUint32](#function-convertbuffertouint32) | [markUserInputsSpent](#function-markuserinputsspent) | [upgradeOutputTagsMap](#function-upgradeoutputtagsmap) |
-| [convertProofToMerklePath](#function-convertprooftomerklepath) | [matchesCertificateFieldPartial](#function-matchescertificatefieldpartial) | [upgradeOutputs](#function-upgradeoutputs) |
-| [convertUint32ToBuffer](#function-convertuint32tobuffer) | [matchesCertificatePartial](#function-matchescertificatepartial) | [upgradeProvenTxReqs](#function-upgradeproventxreqs) |
-| [convertWocToBlockHeaderHex](#function-convertwoctoblockheaderhex) | [matchesCommissionPartial](#function-matchescommissionpartial) | [upgradeProvenTxs](#function-upgradeproventxs) |
-| [createAction](#function-createaction) | [matchesMonitorEventPartial](#function-matchesmonitoreventpartial) | [upgradeSyncStates](#function-upgradesyncstates) |
-| [createAction](#function-createaction) | [matchesOutputBasketPartial](#function-matchesoutputbasketpartial) | [upgradeTransactions](#function-upgradetransactions) |
-| [createCoinbaseTransaction](#function-createcoinbasetransaction) | [matchesOutputPartial](#function-matchesoutputpartial) | [upgradeTxLabels](#function-upgradetxlabels) |
-| [createDefaultIdbChaintracksOptions](#function-createdefaultidbchaintracksoptions) | [matchesOutputTagMapPartial](#function-matchesoutputtagmappartial) | [upgradeTxLabelsMap](#function-upgradetxlabelsmap) |
-| [createDefaultNoDbChaintracksOptions](#function-createdefaultnodbchaintracksoptions) | [matchesOutputTagPartial](#function-matchesoutputtagpartial) | [upgradeUsers](#function-upgradeusers) |
-| [createDefaultWalletServicesOptions](#function-createdefaultwalletservicesoptions) | [matchesProvenTxPartial](#function-matchesproventxpartial) | [validBulkHeaderFilesByFileHash](#function-validbulkheaderfilesbyfilehash) |
-| [createIdbChaintracks](#function-createidbchaintracks) | [matchesProvenTxReqPartial](#function-matchesproventxreqpartial) | [validateAgainstDirtyHashes](#function-validateagainstdirtyhashes) |
-| [createNoDbChaintracks](#function-createnodbchaintracks) | [matchesSyncStatePartial](#function-matchessyncstatepartial) | [validateBufferOfHeaders](#function-validatebufferofheaders) |
-| [createStorageServiceChargeScript](#function-createstorageservicechargescript) | [matchesTransactionPartial](#function-matchestransactionpartial) | [validateBulkFileData](#function-validatebulkfiledata) |
-| [createSyncMap](#function-createsyncmap) | [matchesTxLabelMapPartial](#function-matchestxlabelmappartial) | [validateDate](#function-validatedate) |
-| [dateMatches](#function-datematches) | [matchesTxLabelPartial](#function-matchestxlabelpartial) | [validateEntities](#function-validateentities) |
-| [decryptBRC39](#function-decryptbrc39) | [maxDate](#function-maxdate) | [validateEntity](#function-validateentity) |
-| [deserializeBaseBlockHeader](#function-deserializebaseblockheader) | [mergeInputBeefs](#function-mergeinputbeefs) | [validateGenerateChangeSdkParams](#function-validategeneratechangesdkparams) |
-| [deserializeBaseBlockHeaders](#function-deserializebaseblockheaders) | [mergeInputsIntoBeef](#function-mergeinputsintobeef) | [validateGenerateChangeSdkResult](#function-validategeneratechangesdkresult) |
-| [deserializeBlockHeader](#function-deserializeblockheader) | [notifyTransactionsOfProof](#function-notifytransactionsofproof) | [validateGenesisHeader](#function-validategenesisheader) |
-| [deserializeBlockHeaders](#function-deserializeblockheaders) | [offsetPrivKey](#function-offsetprivkey) | [validateHeaderDifficulty](#function-validateheaderdifficulty) |
-| [doubleSha256BE](#function-doublesha256be) | [offsetPubKey](#function-offsetpubkey) | [validateHeaderFormat](#function-validateheaderformat) |
-| [doubleSha256LE](#function-doublesha256le) | [optionalArraysEqual](#function-optionalarraysequal) | [validateScriptHash](#function-validatescripthash) |
-| [encryptBRC39](#function-encryptbrc39) | [parseBRC38Json](#function-parsebrc38json) | [validateSecondsSinceEpoch](#function-validatesecondssinceepoch) |
-| [exportBRC38](#function-exportbrc38) | [parseBrc114ActionTimeLabels](#function-parsebrc114actiontimelabels) | [validateStorageFeeModel](#function-validatestoragefeemodel) |
-| [exportBRC38Json](#function-exportbrc38json) | [parseOutpoint](#function-parseoutpoint) | [validateSyncChunkEntities](#function-validatesyncchunkentities) |
-| [exportBRC39](#function-exportbrc39) | [parseResults$](#function-parseresults$) | [varUintSize](#function-varuintsize) |
-| [fundWalletFromP2PKHOutpoints](#function-fundwalletfromp2pkhoutpoints) | [parseTxAndAssertId](#function-parsetxandassertid) | [verifyHexString](#function-verifyhexstring) |
-| [generateChangeSdk](#function-generatechangesdk) | [parseTxScriptOffsets](#function-parsetxscriptoffsets) | [verifyId](#function-verifyid) |
-| [generateChangeSdkMakeStorage](#function-generatechangesdkmakestorage) | [partitionActionLabels](#function-partitionactionlabels) | [verifyInteger](#function-verifyinteger) |
-| [genesisBuffer](#function-genesisbuffer) | [populateUtxoDetails](#function-populateutxodetails) | [verifyNumber](#function-verifynumber) |
-| [genesisHeader](#function-genesisheader) | [processAction](#function-processaction) | [verifyOne](#function-verifyone) |
+| [asUint8Array](#function-asuint8array) | [isManagedChangeOutput](#function-ismanagedchangeoutput) | [transactionInputSize](#function-transactioninputsize) |
+| [attemptToPostReqsToNetwork](#function-attempttopostreqstonetwork) | [isMoreWork](#function-ismorework) | [transactionOutputSize](#function-transactionoutputsize) |
+| [blockHash](#function-blockhash) | [keyOffsetToHashedSecret](#function-keyoffsettohashedsecret) | [transactionSize](#function-transactionsize) |
+| [buildBeefForOutpoints](#function-buildbeefforoutpoints) | [listActionsIdb](#function-listactionsidb) | [updateChaintracksFiatExchangeRates](#function-updatechaintracksfiatexchangerates) |
+| [buildChaintracksOptionsWithIngestors](#function-buildchaintracksoptionswithingestors) | [listCertificates](#function-listcertificates) | [updateExchangeratesapi](#function-updateexchangeratesapi) |
+| [buildSignableTransaction](#function-buildsignabletransaction) | [listOutputsIdb](#function-listoutputsidb) | [updateReqsFromAggregateResults](#function-updatereqsfromaggregateresults) |
+| [classifyMerklePathResponse](#function-classifymerklepathresponse) | [lockScriptWithKeyOffsetFromPubKey](#function-lockscriptwithkeyoffsetfrompubkey) | [upgradeAllStoresV1](#function-upgradeallstoresv1) |
+| [classifyReqStatus](#function-classifyreqstatus) | [logCreateActionArgs](#function-logcreateactionargs) | [upgradeCertificateFields](#function-upgradecertificatefields) |
+| [completeSignedTransaction](#function-completesignedtransaction) | [logWalletError](#function-logwalleterror) | [upgradeCertificates](#function-upgradecertificates) |
+| [computeMerklePath](#function-computemerklepath) | [makeAtomicBeef](#function-makeatomicbeef) | [upgradeCommissions](#function-upgradecommissions) |
+| [computeMerkleRoot](#function-computemerkleroot) | [makeBrc114ActionTimeLabel](#function-makebrc114actiontimelabel) | [upgradeMonitorEvents](#function-upgrademonitorevents) |
+| [convertBitsToTarget](#function-convertbitstotarget) | [makeChangeLock](#function-makechangelock) | [upgradeOutputBaskets](#function-upgradeoutputbaskets) |
+| [convertBitsToWork](#function-convertbitstowork) | [makeMerklePathNote](#function-makemerklepathnote) | [upgradeOutputTags](#function-upgradeoutputtags) |
+| [convertBufferToUint32](#function-convertbuffertouint32) | [markStaleInputsAsSpent](#function-markstaleinputsasspent) | [upgradeOutputTagsMap](#function-upgradeoutputtagsmap) |
+| [convertProofToMerklePath](#function-convertprooftomerklepath) | [markUserInputsSpent](#function-markuserinputsspent) | [upgradeOutputs](#function-upgradeoutputs) |
+| [convertUint32ToBuffer](#function-convertuint32tobuffer) | [matchesCertificateFieldPartial](#function-matchescertificatefieldpartial) | [upgradeProvenTxReqs](#function-upgradeproventxreqs) |
+| [convertWocToBlockHeaderHex](#function-convertwoctoblockheaderhex) | [matchesCertificatePartial](#function-matchescertificatepartial) | [upgradeProvenTxs](#function-upgradeproventxs) |
+| [createAction](#function-createaction) | [matchesCommissionPartial](#function-matchescommissionpartial) | [upgradeSyncStates](#function-upgradesyncstates) |
+| [createAction](#function-createaction) | [matchesMonitorEventPartial](#function-matchesmonitoreventpartial) | [upgradeTransactions](#function-upgradetransactions) |
+| [createCoinbaseTransaction](#function-createcoinbasetransaction) | [matchesOutputBasketPartial](#function-matchesoutputbasketpartial) | [upgradeTxLabels](#function-upgradetxlabels) |
+| [createDefaultIdbChaintracksOptions](#function-createdefaultidbchaintracksoptions) | [matchesOutputPartial](#function-matchesoutputpartial) | [upgradeTxLabelsMap](#function-upgradetxlabelsmap) |
+| [createDefaultNoDbChaintracksOptions](#function-createdefaultnodbchaintracksoptions) | [matchesOutputTagMapPartial](#function-matchesoutputtagmappartial) | [upgradeUsers](#function-upgradeusers) |
+| [createDefaultWalletServicesOptions](#function-createdefaultwalletservicesoptions) | [matchesOutputTagPartial](#function-matchesoutputtagpartial) | [validBulkHeaderFilesByFileHash](#function-validbulkheaderfilesbyfilehash) |
+| [createIdbChaintracks](#function-createidbchaintracks) | [matchesProvenTxPartial](#function-matchesproventxpartial) | [validateAgainstDirtyHashes](#function-validateagainstdirtyhashes) |
+| [createNoDbChaintracks](#function-createnodbchaintracks) | [matchesProvenTxReqPartial](#function-matchesproventxreqpartial) | [validateBufferOfHeaders](#function-validatebufferofheaders) |
+| [createStorageServiceChargeScript](#function-createstorageservicechargescript) | [matchesSyncStatePartial](#function-matchessyncstatepartial) | [validateBulkFileData](#function-validatebulkfiledata) |
+| [createSyncMap](#function-createsyncmap) | [matchesTransactionPartial](#function-matchestransactionpartial) | [validateDate](#function-validatedate) |
+| [dateMatches](#function-datematches) | [matchesTxLabelMapPartial](#function-matchestxlabelmappartial) | [validateEntities](#function-validateentities) |
+| [decryptBRC39](#function-decryptbrc39) | [matchesTxLabelPartial](#function-matchestxlabelpartial) | [validateEntity](#function-validateentity) |
+| [deserializeBaseBlockHeader](#function-deserializebaseblockheader) | [maxDate](#function-maxdate) | [validateGenerateChangeSdkParams](#function-validategeneratechangesdkparams) |
+| [deserializeBaseBlockHeaders](#function-deserializebaseblockheaders) | [mergeInputBeefs](#function-mergeinputbeefs) | [validateGenerateChangeSdkResult](#function-validategeneratechangesdkresult) |
+| [deserializeBlockHeader](#function-deserializeblockheader) | [mergeInputsIntoBeef](#function-mergeinputsintobeef) | [validateGenesisHeader](#function-validategenesisheader) |
+| [deserializeBlockHeaders](#function-deserializeblockheaders) | [notifyTransactionsOfProof](#function-notifytransactionsofproof) | [validateHeaderDifficulty](#function-validateheaderdifficulty) |
+| [doubleSha256BE](#function-doublesha256be) | [offsetPrivKey](#function-offsetprivkey) | [validateHeaderFormat](#function-validateheaderformat) |
+| [doubleSha256LE](#function-doublesha256le) | [offsetPubKey](#function-offsetpubkey) | [validateScriptHash](#function-validatescripthash) |
+| [encryptBRC39](#function-encryptbrc39) | [optionalArraysEqual](#function-optionalarraysequal) | [validateSecondsSinceEpoch](#function-validatesecondssinceepoch) |
+| [exportBRC38](#function-exportbrc38) | [parseBRC38Json](#function-parsebrc38json) | [validateStorageFeeModel](#function-validatestoragefeemodel) |
+| [exportBRC38Json](#function-exportbrc38json) | [parseBrc114ActionTimeLabels](#function-parsebrc114actiontimelabels) | [validateSyncChunkEntities](#function-validatesyncchunkentities) |
+| [exportBRC39](#function-exportbrc39) | [parseOutpoint](#function-parseoutpoint) | [varUintSize](#function-varuintsize) |
+| [fundWalletFromP2PKHOutpoints](#function-fundwalletfromp2pkhoutpoints) | [parseResults$](#function-parseresults$) | [verifyHexString](#function-verifyhexstring) |
+| [generateChangeSdk](#function-generatechangesdk) | [parseTxAndAssertId](#function-parsetxandassertid) | [verifyId](#function-verifyid) |
+| [generateChangeSdkMakeStorage](#function-generatechangesdkmakestorage) | [parseTxScriptOffsets](#function-parsetxscriptoffsets) | [verifyInteger](#function-verifyinteger) |
+| [genesisBuffer](#function-genesisbuffer) | [partitionActionLabels](#function-partitionactionlabels) | [verifyNumber](#function-verifynumber) |
+| [genesisHeader](#function-genesisheader) | [populateUtxoDetails](#function-populateutxodetails) | [verifyOne](#function-verifyone) |
 | [getBeefForTransaction](#function-getbeeffortransaction) | [processAction](#function-processaction) | [verifyOneOrNone](#function-verifyoneornone) |
-| [getBeefForTxid](#function-getbeeffortxid) | [proveCertificate](#function-provecertificate) | [verifyOptionalHexString](#function-verifyoptionalhexstring) |
-| [getExchangeRatesIo](#function-getexchangeratesio) | [purgeDataIdb](#function-purgedataidb) | [verifyP2PKHOwnership](#function-verifyp2pkhownership) |
-| [getIdentityKey](#function-getidentitykey) | [randomBytes](#function-randombytes) | [verifyTruthy](#function-verifytruthy) |
-| [getListOutputsSpecOp](#function-getlistoutputsspecop) | [randomBytesBase64](#function-randombytesbase64) | [verifyUnlockScripts](#function-verifyunlockscripts) |
-| [getProofs](#function-getproofs) | [randomBytesHex](#function-randombyteshex) | [wait](#function-wait) |
-| [getSyncChunk](#function-getsyncchunk) | [readUInt32BE](#function-readuint32be) | [wocGetHeadersHeaderToBlockHeader](#function-wocgetheadersheadertoblockheader) |
-| [getWhatsOnChainBlockHeaderByHash](#function-getwhatsonchainblockheaderbyhash) | [readUInt32LE](#function-readuint32le) | [workBNtoBuffer](#function-workbntobuffer) |
-| [handlePostRawTxErrorResponse](#function-handlepostrawtxerrorresponse) | [redeemServiceCharges](#function-redeemservicecharges) | [writeUInt32BE](#function-writeuint32be) |
-| [handleScriptHashHistoryCatch](#function-handlescripthashhistorycatch) | [resolveAutoSigned](#function-resolveautosigned) | [writeUInt32LE](#function-writeuint32le) |
-| [handleScriptHashHistoryResponse](#function-handlescripthashhistoryresponse) | [restoreInputsToSpendable](#function-restoreinputstospendable) |  |
-| [handleUtxoConnReset](#function-handleutxoconnreset) | [reviewStatusIdb](#function-reviewstatusidb) |  |
+| [getBeefForTxid](#function-getbeeffortxid) | [processAction](#function-processaction) | [verifyOptionalHexString](#function-verifyoptionalhexstring) |
+| [getExchangeRatesIo](#function-getexchangeratesio) | [proveCertificate](#function-provecertificate) | [verifyP2PKHOwnership](#function-verifyp2pkhownership) |
+| [getIdentityKey](#function-getidentitykey) | [purgeDataIdb](#function-purgedataidb) | [verifyRequestedOutputsUnchanged](#function-verifyrequestedoutputsunchanged) |
+| [getListOutputsSpecOp](#function-getlistoutputsspecop) | [randomBytes](#function-randombytes) | [verifyTruthy](#function-verifytruthy) |
+| [getProofs](#function-getproofs) | [randomBytesBase64](#function-randombytesbase64) | [verifyUnlockScripts](#function-verifyunlockscripts) |
+| [getSyncChunk](#function-getsyncchunk) | [randomBytesHex](#function-randombyteshex) | [verifyUnrequestedOutputsAreChangeOrCommission](#function-verifyunrequestedoutputsarechangeorcommission) |
+| [getWhatsOnChainBlockHeaderByHash](#function-getwhatsonchainblockheaderbyhash) | [readUInt32BE](#function-readuint32be) | [wait](#function-wait) |
+| [handlePostRawTxErrorResponse](#function-handlepostrawtxerrorresponse) | [readUInt32LE](#function-readuint32le) | [wocGetHeadersHeaderToBlockHeader](#function-wocgetheadersheadertoblockheader) |
+| [handleScriptHashHistoryCatch](#function-handlescripthashhistorycatch) | [redeemServiceCharges](#function-redeemservicecharges) | [workBNtoBuffer](#function-workbntobuffer) |
+| [handleScriptHashHistoryResponse](#function-handlescripthashhistoryresponse) | [resolveAutoSigned](#function-resolveautosigned) | [writeUInt32BE](#function-writeuint32be) |
+| [handleUtxoConnReset](#function-handleutxoconnreset) | [restoreInputsToSpendable](#function-restoreinputstospendable) | [writeUInt32LE](#function-writeuint32le) |
+| [importBRC38](#function-importbrc38) | [reviewStatusIdb](#function-reviewstatusidb) |  |
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
 
@@ -18551,12 +18567,14 @@ When the transaction already exists, the description is updated. The isOutgoing
 
 "basket insertion" Merge Rules:
 1. The "default" basket may not be specified as the insertion basket.
-2. A change output in the "default" basket may not be target of an insertion into a different basket.
-3. These baskets do not affect the wallet's balance and are typed "custom".
+2. Managed change may not be reclassified as a basket insertion.
+3. Basket insertions do not affect wallet balance and are typed "custom".
 
 "wallet payment" Merge Rules:
-1. Targetting an existing change "default" basket output results in a no-op. No error. No alterations made.
-2. Targetting a previously "custom" non-change output converts it into a change output. This alters the transaction's `amount`, and the wallet balance.
+1. Targeting an existing managed output is idempotent.
+2. Targeting a custom output converts it to managed BRC-29 change after
+   the locking script is verified. This is the only supported in-place
+   recovery path for a misclassified BRC-29 payment.
 
 ```ts
 export async function internalizeAction(wallet: Wallet, auth: AuthId, args: InternalizeActionArgs): Promise<StorageInternalizeActionResult> 
@@ -18599,12 +18617,14 @@ When the transaction already exists, the description is updated. The isOutgoing
 
 "basket insertion" Merge Rules:
 1. The "default" basket may not be specified as the insertion basket.
-2. A change output in the "default" basket may not be target of an insertion into a different basket.
-3. These baskets do not affect the wallet's balance and are typed "custom".
+2. Managed change may not be reclassified as a basket insertion.
+3. Basket insertions do not affect wallet balance and are typed "custom".
 
 "wallet payment" Merge Rules:
-1. Targetting an existing change "default" basket output results in a no-op. No error. No alterations made.
-2. Targetting a previously "custom" non-change output converts it into a change output. This alters the transaction's `satoshis`, and the wallet balance.
+1. Targeting an existing managed output is idempotent.
+2. Targeting an existing custom output converts it to managed BRC-29
+   change and increases wallet balance. This includes verified recovery of
+   a legacy custom row that was incorrectly placed in the default basket.
 
 ```ts
 export async function internalizeAction(storage: StorageProvider, auth: AuthId, args: InternalizeActionArgs): Promise<StorageInternalizeActionResult> 
@@ -18650,6 +18670,19 @@ export function isArcServiceErrorStatus(status: number | undefined, detail?: str
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
 
+---
+##### Function: isAutoSpendableChangeOutput
+
+True when managed change is currently eligible for automatic allocation.
+
+```ts
+export function isAutoSpendableChangeOutput(output: TableOutput | undefined): output is TableOutput 
+```
+
+See also: [TableOutput](./storage.md#interface-tableoutput)
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
+
 ---
 ##### Function: isBaseBlockHeader
 
@@ -18811,6 +18844,22 @@ See also: [AnyBlockHeader](./services.md#type-anyblockheader), [LiveBlockHeader]
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
 
+---
+##### Function: isManagedChangeOutput
+
+True when an output has all metadata required to use the wallet-managed
+BRC-29 signing path. `senderIdentityKey` is optional: wallet-created change
+uses the client's change public key when it is absent, while received
+BRC-29 payments record the sender's identity key.
+
+```ts
+export function isManagedChangeOutput(output: TableOutput | undefined): output is TableOutput 
+```
+
+See also: [TableOutput](./storage.md#interface-tableoutput)
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
+
 ---
 ##### Function: isMoreWork
 
@@ -20500,6 +20549,37 @@ export function verifyP2PKHOwnership(lockingScript: LockingScript, publicKey: Pu
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
 
+---
+##### Function: verifyRequestedOutputsUnchanged
+
+Verify that the outputs returned by storage for caller-specified outputs match
+exactly what the caller requested in `args.outputs`.
+
+The storage response (`StorageCreateActionResult.outputs`) is ordered, by
+contract, as: the caller's `args.outputs` in their original order, followed by
+the optional commission output, followed by storage-provided change outputs.
+Only the `vout` field is randomized when `randomizeOutputs` is set; the array
+order is stable. Therefore array index `i` (for `i < args.outputs.length`)
+corresponds to `args.outputs[i]`.
+
+Because the locking script that is ultimately signed is taken from the storage
+response, an untrusted storage provider must not be allowed to alter the
+recipient script (or amount) of a caller-specified output. Any mismatch is a
+hard error. (GHSA-36f9-7rg5-cpf8)
+
+```ts
+export function verifyRequestedOutputsUnchanged(storageOutputs: StorageCreateTransactionSdkOutput[], args: Validation.ValidCreateActionArgs): void 
+```
+
+See also: [StorageCreateTransactionSdkOutput](./client.md#interface-storagecreatetransactionsdkoutput)
+
+Throws
+
+WERR_INVALID_PARAMETER if storage omitted, reclassified, or modified
+any caller-specified output.
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
+
 ---
 ##### Function: verifyTruthy
 
@@ -20533,6 +20613,42 @@ WERR_INVALID_PARAMETER if any unlocking script is invalid, if sourceTXID is inva
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
 
+---
+##### Function: verifyUnrequestedOutputsAreChangeOrCommission
+
+Verify that every storage output beyond the caller's requested outputs is
+either a change output or the (single, bounded) commission output.
+
+The storage response is ordered `[caller outputs][commission?][change...]`;
+`verifyRequestedOutputsUnchanged` already validates the caller region (indices
+`< args.outputs.length`). This checks the remainder.
+
+Change outputs (`providedBy: 'storage', purpose: 'change'`) are safe at any
+amount: `buildSignableTransaction` ignores the storage-supplied script and
+re-derives it client-side (`makeChangeLock` / BRC-29 under the client's own
+change key), so a change output can only ever pay the client. A change output
+mislabeled by storage is therefore harmless.
+
+The commission output's script, by contrast, is taken verbatim from storage
+and cannot be verified client-side. A malicious storage could inject an extra
+output — or relabel one as commission — to redirect funds to an attacker while
+the caller/UI only sees the requested recipients. To bound that, at most one
+commission output is allowed and its amount must not exceed `maxCommission`.
+Any other unrecognized output is rejected outright.
+
+```ts
+export function verifyUnrequestedOutputsAreChangeOrCommission(storageOutputs: StorageCreateTransactionSdkOutput[], args: Validation.ValidCreateActionArgs, maxCommission: number = MAX_STORAGE_COMMISSION_SATOSHIS): void 
+```
+
+See also: [MAX_STORAGE_COMMISSION_SATOSHIS](./client.md#variable-max_storage_commission_satoshis), [StorageCreateTransactionSdkOutput](./client.md#interface-storagecreatetransactionsdkoutput)
+
+Throws
+
+WERR_INVALID_PARAMETER if storage returned an unrecognized output, more
+than one commission output, or a commission exceeding `maxCommission`.
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
+
 ---
 ##### Function: wait
 
@@ -21109,21 +21225,31 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 
 | | | |
 | --- | --- | --- |
+| [ARCADE_POST_BEEF_CONCURRENCY](#variable-arcade_post_beef_concurrency) | [TESTNET_DEFAULT_SETTINGS](#variable-testnet_default_settings) | [queryOverlay](#variable-queryoverlay) |
 | [ARGON2ID_DEFAULT_HASH_LENGTH](#variable-argon2id_default_hash_length) | [aggregateActionResults](#variable-aggregateactionresults) | [specOpFailedActions](#variable-specopfailedactions) |
 | [ARGON2ID_DEFAULT_ITERATIONS](#variable-argon2id_default_iterations) | [brc29ProtocolID](#variable-brc29protocolid) | [specOpInvalidChange](#variable-specopinvalidchange) |
 | [ARGON2ID_DEFAULT_MEMORY_KIB](#variable-argon2id_default_memory_kib) | [dirtyHashes](#variable-dirtyhashes) | [specOpNoSendActions](#variable-specopnosendactions) |
 | [ARGON2ID_DEFAULT_PARALLELISM](#variable-argon2id_default_parallelism) | [getLabelToSpecOp](#variable-getlabeltospecop) | [specOpSetWalletChangeParams](#variable-specopsetwalletchangeparams) |
 | [DEFAULT_PROFILE_ID](#variable-default_profile_id) | [logger](#variable-logger) | [specOpThrowReviewActions](#variable-specopthrowreviewactions) |
-| [DEFAULT_SETTINGS](#variable-default_settings) | [maxChangeOutputsPerTransaction](#variable-maxchangeoutputspertransaction) | [specOpWalletBalance](#variable-specopwalletbalance) |
+| [DEFAULT_SETTINGS](#variable-default_settings) | [managedChangeOutputFields](#variable-managedchangeoutputfields) | [specOpWalletBalance](#variable-specopwalletbalance) |
+| [MAX_STORAGE_COMMISSION_SATOSHIS](#variable-max_storage_commission_satoshis) | [maxChangeOutputsPerTransaction](#variable-maxchangeoutputspertransaction) | [specOpWalletManagedUtxos](#variable-specopwalletmanagedutxos) |
 | [PBKDF2_NUM_ROUNDS](#variable-pbkdf2_num_rounds) | [maxPossibleSatoshis](#variable-maxpossiblesatoshis) | [transactionColumnsWithoutRawTx](#variable-transactioncolumnswithoutrawtx) |
 | [ProvenTxReqNonTerminalStatus](#variable-proventxreqnonterminalstatus) | [outputColumnsWithoutLockingScript](#variable-outputcolumnswithoutlockingscript) | [transformVerifiableCertificatesWithTrust](#variable-transformverifiablecertificateswithtrust) |
 | [ProvenTxReqTerminalStatus](#variable-proventxreqterminalstatus) | [parseResults](#variable-parseresults) | [validBulkHeaderFiles](#variable-validbulkheaderfiles) |
-| [TESTNET_DEFAULT_SETTINGS](#variable-testnet_default_settings) | [queryOverlay](#variable-queryoverlay) |  |
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
 
 ---
 
+##### Variable: ARCADE_POST_BEEF_CONCURRENCY
+
+```ts
+ARCADE_POST_BEEF_CONCURRENCY = 4
+```
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
+
+---
 ##### Variable: ARGON2ID_DEFAULT_HASH_LENGTH
 
 ```ts
@@ -21201,6 +21327,15 @@ See also: [WalletSettings](./client.md#interface-walletsettings)
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
 
+---
+##### Variable: MAX_STORAGE_COMMISSION_SATOSHIS
+
+```ts
+MAX_STORAGE_COMMISSION_SATOSHIS = 500000
+```
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
+
 ---
 ##### Variable: PBKDF2_NUM_ROUNDS
 
@@ -21413,6 +21548,20 @@ logger = (message: string, ...optionalParams: any[]): void => {
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
 
+---
+##### Variable: managedChangeOutputFields
+
+```ts
+managedChangeOutputFields = {
+    type: "P2PKH",
+    change: true,
+    providedBy: "storage",
+    purpose: "change"
+} as const
+```
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
+
 ---
 ##### Variable: maxChangeOutputsPerTransaction
 
@@ -21558,6 +21707,15 @@ specOpWalletBalance = "893b7646de0e1c9f741bd6e9169b76a8847ae34adef7bef1e6a285371
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
 
+---
+##### Variable: specOpWalletManagedUtxos
+
+```ts
+specOpWalletManagedUtxos = "284570a6213a74ba861c38b1cf790e1e400d9cf9324454b76ea98860b6031c1a"
+```
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
+
 ---
 ##### Variable: transactionColumnsWithoutRawTx
 

package/docs/managed-change-policy.md

@@ -0,0 +1,79 @@
+# Managed change, sweeping, and recovery
+
+The default basket is the wallet's funding pool. An output being physically
+stored in that basket is not, by itself, proof that the wallet can spend it.
+Automatic funding and wallet balance therefore use the managed-change policy
+below instead of trusting basket membership or the locking script alone.
+
+## Output classes
+
+A **managed change output** has all of the following metadata:
+
+- `type: 'P2PKH'`
+- `change: true`
+- `providedBy: 'storage'`
+- `purpose: 'change'`
+- non-empty `derivationPrefix` and `derivationSuffix`
+
+Here, `type: 'P2PKH'` is an operational signer type, not merely a description
+of the script. It selects the BRC-29 unlocking path. A raw P2PKH output without
+matching derivation metadata is not managed change and must not be selected by
+the wallet automatically.
+
+A **custom output** belongs to an application-defined protocol. It is normally
+stored outside the default basket with `type: 'custom'`, `change: false`, and
+`providedBy: 'you'`. Custom outputs are discoverable and may be explicitly
+spent by application logic, but are not wallet balance and are never automatic
+fee inputs.
+
+## Enforcement
+
+The same managed-change predicate is applied to:
+
+- change-input counting and allocation in Knex/SQLite/MySQL and IndexedDB;
+- the default wallet balance and `balanceAndUtxos()` results; and
+- validation of `noSendChange` inputs.
+
+Raw administrative `listOutputs({ basket: 'default' })` remains unfiltered on
+purpose. This makes incompatible legacy rows visible for diagnosis and recovery
+without allowing them into balance or automatic funding.
+
+## `internalizeAction` rules
+
+| Request | New output | Existing custom output | Existing managed change |
+| --- | --- | --- | --- |
+| `wallet payment` | Store as managed change in `default` | Promote to managed change after BRC-29 script verification | Idempotent when already in `default` |
+| `basket insertion` to a non-default basket | Store as custom | Move/update as custom; no wallet-balance adjustment | Reject; managed change cannot be reclassified |
+| `basket insertion` to `default` | Reject | Reject | Reject |
+
+The wallet signer verifies that `paymentRemittance` derives the transaction
+output's locking script before storage can promote it. This is the supported
+way to repair a genuine BRC-29 payment that was previously classified as
+custom. Merely recognizing a P2PKH locking script is not enough.
+
+## Sweeping and recovery
+
+"Sweep" means moving an incompatible custom row out of the default basket with
+a `basket insertion` into a named, non-default recovery basket. This is a
+metadata repair: the output remains custom and wallet balance does not change.
+
+There are two valid recovery choices for a legacy custom row in `default`:
+
+1. If it is a genuine payment to this wallet under BRC-29, internalize it as a
+   `wallet payment` with the correct derivation prefix, derivation suffix, and
+   sender identity key. Successful verification promotes it to managed change
+   and adds its value to wallet balance.
+2. Otherwise, sweep it to a non-default basket. The application can then apply
+   its own unlocking and lifecycle rules explicitly.
+
+Do not repair rows by directly changing `type`, `change`, or derivation fields.
+That bypasses the BRC-29 ownership check and can make balance appear spendable
+when the wallet does not possess the required key path.
+
+## BRC-29 remittance module
+
+`Brc29RemittanceModule` always accepts settlements through the `wallet payment`
+protocol. The deprecated `internalizeProtocol: 'basket insertion'` setting is
+rejected because it supplied no insertion remittance and would classify a
+recipient payment as a custom application output instead of spendable wallet
+balance.

package/docs/services.md

@@ -999,6 +999,7 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 ```ts
 export interface ChaintracksChainTrackerOptions {
     maxRetries?: number;
+    retryDelayMs?: number;
 }
 ```
 
@@ -6466,6 +6467,7 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 
 | |
 | --- |
+| [ARCADE_POST_BEEF_CONCURRENCY](#variable-arcade_post_beef_concurrency) |
 | [ChaintracksFs](#variable-chaintracksfs) |
 | [dirtyHashes](#variable-dirtyhashes) |
 | [validBulkHeaderFiles](#variable-validbulkheaderfiles) |
@@ -6474,6 +6476,15 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 
 ---
 
+##### Variable: ARCADE_POST_BEEF_CONCURRENCY
+
+```ts
+ARCADE_POST_BEEF_CONCURRENCY = 4
+```
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
+
+---
 ##### Variable: ChaintracksFs
 
 ```ts