@bsv/wallet-toolbox 2.3.3 → 2.4.1

package/docs/storage.md

@@ -462,6 +462,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[]>;
@@ -472,6 +473,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.
@@ -3669,7 +3678,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
@@ -4089,7 +4099,8 @@ See also: [TableOutput](./storage.md#interface-tableoutput)
 
 ###### Method countChangeInputs
 
-Counts the outputs for userId in basketId that are spendable: true
+Counts wallet-managed BRC-29 change outputs for userId in basketId that
+are currently eligible for automatic allocation
 AND whose transaction status is one of:
 - completed
 - unproven
@@ -4902,26 +4913,28 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 
 | | | |
 | --- | --- | --- |
-| [attemptToPostReqsToNetwork](#function-attempttopostreqstonetwork) | [matchesCertificatePartial](#function-matchescertificatepartial) | [transactionInputSize](#function-transactioninputsize) |
-| [classifyReqStatus](#function-classifyreqstatus) | [matchesCommissionPartial](#function-matchescommissionpartial) | [transactionOutputSize](#function-transactionoutputsize) |
-| [createAction](#function-createaction) | [matchesMonitorEventPartial](#function-matchesmonitoreventpartial) | [transactionSize](#function-transactionsize) |
-| [createStorageServiceChargeScript](#function-createstorageservicechargescript) | [matchesOutputBasketPartial](#function-matchesoutputbasketpartial) | [updateReqsFromAggregateResults](#function-updatereqsfromaggregateresults) |
-| [createSyncMap](#function-createsyncmap) | [matchesOutputPartial](#function-matchesoutputpartial) | [upgradeAllStoresV1](#function-upgradeallstoresv1) |
-| [dateMatches](#function-datematches) | [matchesOutputTagMapPartial](#function-matchesoutputtagmappartial) | [upgradeCertificateFields](#function-upgradecertificatefields) |
-| [decryptBRC39](#function-decryptbrc39) | [matchesOutputTagPartial](#function-matchesoutputtagpartial) | [upgradeCertificates](#function-upgradecertificates) |
-| [determineDBType](#function-determinedbtype) | [matchesProvenTxPartial](#function-matchesproventxpartial) | [upgradeCommissions](#function-upgradecommissions) |
-| [encryptBRC39](#function-encryptbrc39) | [matchesProvenTxReqPartial](#function-matchesproventxreqpartial) | [upgradeMonitorEvents](#function-upgrademonitorevents) |
-| [exportBRC38](#function-exportbrc38) | [matchesSyncStatePartial](#function-matchessyncstatepartial) | [upgradeOutputBaskets](#function-upgradeoutputbaskets) |
-| [exportBRC38Json](#function-exportbrc38json) | [matchesTransactionPartial](#function-matchestransactionpartial) | [upgradeOutputTags](#function-upgradeoutputtags) |
-| [exportBRC39](#function-exportbrc39) | [matchesTxLabelMapPartial](#function-matchestxlabelmappartial) | [upgradeOutputTagsMap](#function-upgradeoutputtagsmap) |
-| [generateChangeSdk](#function-generatechangesdk) | [matchesTxLabelPartial](#function-matchestxlabelpartial) | [upgradeOutputs](#function-upgradeoutputs) |
-| [generateChangeSdkMakeStorage](#function-generatechangesdkmakestorage) | [mergeInputBeefs](#function-mergeinputbeefs) | [upgradeProvenTxReqs](#function-upgradeproventxreqs) |
-| [getBeefForTransaction](#function-getbeeffortransaction) | [mergeInputsIntoBeef](#function-mergeinputsintobeef) | [upgradeProvenTxs](#function-upgradeproventxs) |
-| [getListOutputsSpecOp](#function-getlistoutputsspecop) | [notifyTransactionsOfProof](#function-notifytransactionsofproof) | [upgradeSyncStates](#function-upgradesyncstates) |
-| [getSyncChunk](#function-getsyncchunk) | [offsetPrivKey](#function-offsetprivkey) | [upgradeTransactions](#function-upgradetransactions) |
-| [importBRC38](#function-importbrc38) | [offsetPubKey](#function-offsetpubkey) | [upgradeTxLabels](#function-upgradetxlabels) |
-| [importBRC39](#function-importbrc39) | [parseBRC38Json](#function-parsebrc38json) | [upgradeTxLabelsMap](#function-upgradetxlabelsmap) |
-| [internalizeAction](#function-internalizeaction) | [partitionActionLabels](#function-partitionactionlabels) | [upgradeUsers](#function-upgradeusers) |
+| [attemptToPostReqsToNetwork](#function-attempttopostreqstonetwork) | [markUserInputsSpent](#function-markuserinputsspent) | [setDisableDoubleSpendCheckForTest](#function-setdisabledoublespendcheckfortest) |
+| [classifyReqStatus](#function-classifyreqstatus) | [matchesCertificateFieldPartial](#function-matchescertificatefieldpartial) | [shareReqsWithWorld](#function-sharereqswithworld) |
+| [createAction](#function-createaction) | [matchesCertificatePartial](#function-matchescertificatepartial) | [transactionInputSize](#function-transactioninputsize) |
+| [createStorageServiceChargeScript](#function-createstorageservicechargescript) | [matchesCommissionPartial](#function-matchescommissionpartial) | [transactionOutputSize](#function-transactionoutputsize) |
+| [createSyncMap](#function-createsyncmap) | [matchesMonitorEventPartial](#function-matchesmonitoreventpartial) | [transactionSize](#function-transactionsize) |
+| [dateMatches](#function-datematches) | [matchesOutputBasketPartial](#function-matchesoutputbasketpartial) | [updateReqsFromAggregateResults](#function-updatereqsfromaggregateresults) |
+| [decryptBRC39](#function-decryptbrc39) | [matchesOutputPartial](#function-matchesoutputpartial) | [upgradeAllStoresV1](#function-upgradeallstoresv1) |
+| [determineDBType](#function-determinedbtype) | [matchesOutputTagMapPartial](#function-matchesoutputtagmappartial) | [upgradeCertificateFields](#function-upgradecertificatefields) |
+| [encryptBRC39](#function-encryptbrc39) | [matchesOutputTagPartial](#function-matchesoutputtagpartial) | [upgradeCertificates](#function-upgradecertificates) |
+| [exportBRC38](#function-exportbrc38) | [matchesProvenTxPartial](#function-matchesproventxpartial) | [upgradeCommissions](#function-upgradecommissions) |
+| [exportBRC38Json](#function-exportbrc38json) | [matchesProvenTxReqPartial](#function-matchesproventxreqpartial) | [upgradeMonitorEvents](#function-upgrademonitorevents) |
+| [exportBRC39](#function-exportbrc39) | [matchesSyncStatePartial](#function-matchessyncstatepartial) | [upgradeOutputBaskets](#function-upgradeoutputbaskets) |
+| [generateChangeSdk](#function-generatechangesdk) | [matchesTransactionPartial](#function-matchestransactionpartial) | [upgradeOutputTags](#function-upgradeoutputtags) |
+| [generateChangeSdkMakeStorage](#function-generatechangesdkmakestorage) | [matchesTxLabelMapPartial](#function-matchestxlabelmappartial) | [upgradeOutputTagsMap](#function-upgradeoutputtagsmap) |
+| [getBeefForTransaction](#function-getbeeffortransaction) | [matchesTxLabelPartial](#function-matchestxlabelpartial) | [upgradeOutputs](#function-upgradeoutputs) |
+| [getListOutputsSpecOp](#function-getlistoutputsspecop) | [mergeInputBeefs](#function-mergeinputbeefs) | [upgradeProvenTxReqs](#function-upgradeproventxreqs) |
+| [getSyncChunk](#function-getsyncchunk) | [mergeInputsIntoBeef](#function-mergeinputsintobeef) | [upgradeProvenTxs](#function-upgradeproventxs) |
+| [importBRC38](#function-importbrc38) | [notifyTransactionsOfProof](#function-notifytransactionsofproof) | [upgradeSyncStates](#function-upgradesyncstates) |
+| [importBRC39](#function-importbrc39) | [offsetPrivKey](#function-offsetprivkey) | [upgradeTransactions](#function-upgradetransactions) |
+| [internalizeAction](#function-internalizeaction) | [offsetPubKey](#function-offsetpubkey) | [upgradeTxLabels](#function-upgradetxlabels) |
+| [isAutoSpendableChangeOutput](#function-isautospendablechangeoutput) | [parseBRC38Json](#function-parsebrc38json) | [upgradeTxLabelsMap](#function-upgradetxlabelsmap) |
+| [isManagedChangeOutput](#function-ismanagedchangeoutput) | [partitionActionLabels](#function-partitionactionlabels) | [upgradeUsers](#function-upgradeusers) |
 | [keyOffsetToHashedSecret](#function-keyoffsettohashedsecret) | [processAction](#function-processaction) | [validateDate](#function-validatedate) |
 | [listActions](#function-listactions) | [purgeData](#function-purgedata) | [validateEntities](#function-validateentities) |
 | [listActionsIdb](#function-listactionsidb) | [purgeDataIdb](#function-purgedataidb) | [validateEntity](#function-validateentity) |
@@ -4930,8 +4943,6 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 | [listOutputsIdb](#function-listoutputsidb) | [restoreInputsToSpendable](#function-restoreinputstospendable) | [validateStorageFeeModel](#function-validatestoragefeemodel) |
 | [lockScriptWithKeyOffsetFromPubKey](#function-lockscriptwithkeyoffsetfrompubkey) | [reviewStatus](#function-reviewstatus) | [validateSyncChunkEntities](#function-validatesyncchunkentities) |
 | [markStaleInputsAsSpent](#function-markstaleinputsasspent) | [reviewStatusIdb](#function-reviewstatusidb) | [varUintSize](#function-varuintsize) |
-| [markUserInputsSpent](#function-markuserinputsspent) | [setDisableDoubleSpendCheckForTest](#function-setdisabledoublespendcheckfortest) |  |
-| [matchesCertificateFieldPartial](#function-matchescertificatefieldpartial) | [shareReqsWithWorld](#function-sharereqswithworld) |  |
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
 
@@ -5225,12 +5236,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> 
@@ -5240,6 +5253,35 @@ See also: [AuthId](./client.md#interface-authid), [StorageInternalizeActionResul
 
 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: 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: keyOffsetToHashedSecret
 
@@ -6218,6 +6260,7 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 | |
 | --- |
 | [getLabelToSpecOp](#variable-getlabeltospecop) |
+| [managedChangeOutputFields](#variable-managedchangeoutputfields) |
 | [maxChangeOutputsPerTransaction](#variable-maxchangeoutputspertransaction) |
 | [maxPossibleSatoshis](#variable-maxpossiblesatoshis) |
 | [outputColumnsWithoutLockingScript](#variable-outputcolumnswithoutlockingscript) |
@@ -6292,6 +6335,20 @@ See also: [AuthId](./client.md#interface-authid), [ListActionsSpecOp](./storage.
 
 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
 
@@ -6369,4 +6426,4 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 
 ---
 
-<!--#endregion ts2md-api-merged-here-->
+<!--#endregion ts2md-api-merged-here-->

package/docs/wallet.md

@@ -783,6 +783,7 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 ```ts
 export interface ChaintracksChainTrackerOptions {
     maxRetries?: number;
+    retryDelayMs?: number;
 }
 ```
 
@@ -10988,6 +10989,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> 
 ```
@@ -11754,16 +11759,16 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 
 | | | |
 | --- | --- | --- |
-| [WalletErrorFromJson](#function-walleterrorfromjson) | [handlePostRawTxErrorResponse](#function-handlepostrawtxerrorresponse) | [serializeBaseBlockHeaders](#function-serializebaseblockheaders) |
-| [acquireDirectCertificate](#function-acquiredirectcertificate) | [handleScriptHashHistoryCatch](#function-handlescripthashhistorycatch) | [setDisableDoubleSpendCheckForTest](#function-setdisabledoublespendcheckfortest) |
-| [addWork](#function-addwork) | [handleScriptHashHistoryResponse](#function-handlescripthashhistoryresponse) | [sha256Hash](#function-sha256hash) |
-| [arcDefaultUrl](#function-arcdefaulturl) | [handleUtxoConnReset](#function-handleutxoconnreset) | [sha256HashOfBinaryFile](#function-sha256hashofbinaryfile) |
+| [WalletErrorFromJson](#function-walleterrorfromjson) | [handleScriptHashHistoryCatch](#function-handlescripthashhistorycatch) | [serializeBaseBlockHeaders](#function-serializebaseblockheaders) |
+| [acquireDirectCertificate](#function-acquiredirectcertificate) | [handleScriptHashHistoryResponse](#function-handlescripthashhistoryresponse) | [setDisableDoubleSpendCheckForTest](#function-setdisabledoublespendcheckfortest) |
+| [addWork](#function-addwork) | [handleUtxoConnReset](#function-handleutxoconnreset) | [sha256Hash](#function-sha256hash) |
+| [arcDefaultUrl](#function-arcdefaulturl) | [internalizeAction](#function-internalizeaction) | [sha256HashOfBinaryFile](#function-sha256hashofbinaryfile) |
 | [arcGorillaPoolUrl](#function-arcgorillapoolurl) | [internalizeAction](#function-internalizeaction) | [shareReqsWithWorld](#function-sharereqswithworld) |
-| [arcadeDefaultUrl](#function-arcadedefaulturl) | [internalizeAction](#function-internalizeaction) | [signAction](#function-signaction) |
-| [arraysEqual](#function-arraysequal) | [isArcAcceptedTxStatus](#function-isarcacceptedtxstatus) | [stampLog](#function-stamplog) |
-| [asArray](#function-asarray) | [isArcDoubleSpendTxStatus](#function-isarcdoublespendtxstatus) | [stampLogFormat](#function-stamplogformat) |
-| [asBsvSdkPrivateKey](#function-asbsvsdkprivatekey) | [isArcInvalidTxStatus](#function-isarcinvalidtxstatus) | [subWork](#function-subwork) |
-| [asBsvSdkPublickKey](#function-asbsvsdkpublickkey) | [isArcServiceErrorStatus](#function-isarcserviceerrorstatus) | [swapByteOrder](#function-swapbyteorder) |
+| [arcadeDefaultUrl](#function-arcadedefaulturl) | [isArcAcceptedTxStatus](#function-isarcacceptedtxstatus) | [signAction](#function-signaction) |
+| [arraysEqual](#function-arraysequal) | [isArcDoubleSpendTxStatus](#function-isarcdoublespendtxstatus) | [stampLog](#function-stamplog) |
+| [asArray](#function-asarray) | [isArcInvalidTxStatus](#function-isarcinvalidtxstatus) | [stampLogFormat](#function-stamplogformat) |
+| [asBsvSdkPrivateKey](#function-asbsvsdkprivatekey) | [isArcServiceErrorStatus](#function-isarcserviceerrorstatus) | [subWork](#function-subwork) |
+| [asBsvSdkPublickKey](#function-asbsvsdkpublickkey) | [isAutoSpendableChangeOutput](#function-isautospendablechangeoutput) | [swapByteOrder](#function-swapbyteorder) |
 | [asBsvSdkScript](#function-asbsvsdkscript) | [isBaseBlockHeader](#function-isbaseblockheader) | [throwDummyReviewActions](#function-throwdummyreviewactions) |
 | [asBsvSdkTx](#function-asbsvsdktx) | [isBlockHeader](#function-isblockheader) | [toBinaryBaseBlockHeader](#function-tobinarybaseblockheader) |
 | [asString](#function-asstring) | [isCreateActionSpecOp](#function-iscreateactionspecop) | [toLookupNetworkPreset](#function-tolookupnetworkpreset) |
@@ -11772,39 +11777,40 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 | [blockHash](#function-blockhash) | [isListOutputsSpecOp](#function-islistoutputsspecop) | [transactionOutputSize](#function-transactionoutputsize) |
 | [buildSignableTransaction](#function-buildsignabletransaction) | [isLive](#function-islive) | [transactionSize](#function-transactionsize) |
 | [classifyMerklePathResponse](#function-classifymerklepathresponse) | [isLiveBlockHeader](#function-isliveblockheader) | [updateChaintracksFiatExchangeRates](#function-updatechaintracksfiatexchangerates) |
-| [classifyReqStatus](#function-classifyreqstatus) | [isMoreWork](#function-ismorework) | [updateExchangeratesapi](#function-updateexchangeratesapi) |
-| [completeSignedTransaction](#function-completesignedtransaction) | [keyOffsetToHashedSecret](#function-keyoffsettohashedsecret) | [updateReqsFromAggregateResults](#function-updatereqsfromaggregateresults) |
-| [computeMerklePath](#function-computemerklepath) | [listCertificates](#function-listcertificates) | [validBulkHeaderFilesByFileHash](#function-validbulkheaderfilesbyfilehash) |
-| [computeMerkleRoot](#function-computemerkleroot) | [lockScriptWithKeyOffsetFromPubKey](#function-lockscriptwithkeyoffsetfrompubkey) | [validateAgainstDirtyHashes](#function-validateagainstdirtyhashes) |
-| [convertBitsToTarget](#function-convertbitstotarget) | [logCreateActionArgs](#function-logcreateactionargs) | [validateBufferOfHeaders](#function-validatebufferofheaders) |
-| [convertBitsToWork](#function-convertbitstowork) | [logWalletError](#function-logwalleterror) | [validateBulkFileData](#function-validatebulkfiledata) |
-| [convertBufferToUint32](#function-convertbuffertouint32) | [makeAtomicBeef](#function-makeatomicbeef) | [validateDate](#function-validatedate) |
-| [convertProofToMerklePath](#function-convertprooftomerklepath) | [makeChangeLock](#function-makechangelock) | [validateEntities](#function-validateentities) |
-| [convertUint32ToBuffer](#function-convertuint32tobuffer) | [makeMerklePathNote](#function-makemerklepathnote) | [validateEntity](#function-validateentity) |
-| [convertWocToBlockHeaderHex](#function-convertwoctoblockheaderhex) | [markStaleInputsAsSpent](#function-markstaleinputsasspent) | [validateGenerateChangeSdkParams](#function-validategeneratechangesdkparams) |
-| [createAction](#function-createaction) | [markUserInputsSpent](#function-markuserinputsspent) | [validateGenerateChangeSdkResult](#function-validategeneratechangesdkresult) |
-| [createAction](#function-createaction) | [maxDate](#function-maxdate) | [validateGenesisHeader](#function-validategenesisheader) |
-| [createCoinbaseTransaction](#function-createcoinbasetransaction) | [mergeInputBeefs](#function-mergeinputbeefs) | [validateHeaderDifficulty](#function-validateheaderdifficulty) |
-| [createDefaultWalletServicesOptions](#function-createdefaultwalletservicesoptions) | [mergeInputsIntoBeef](#function-mergeinputsintobeef) | [validateHeaderFormat](#function-validateheaderformat) |
-| [createStorageServiceChargeScript](#function-createstorageservicechargescript) | [notifyTransactionsOfProof](#function-notifytransactionsofproof) | [validateScriptHash](#function-validatescripthash) |
-| [createSyncMap](#function-createsyncmap) | [offsetPrivKey](#function-offsetprivkey) | [validateSecondsSinceEpoch](#function-validatesecondssinceepoch) |
-| [deserializeBaseBlockHeader](#function-deserializebaseblockheader) | [offsetPubKey](#function-offsetpubkey) | [validateStorageFeeModel](#function-validatestoragefeemodel) |
-| [deserializeBaseBlockHeaders](#function-deserializebaseblockheaders) | [optionalArraysEqual](#function-optionalarraysequal) | [validateSyncChunkEntities](#function-validatesyncchunkentities) |
-| [deserializeBlockHeader](#function-deserializeblockheader) | [parseResults$](#function-parseresults$) | [varUintSize](#function-varuintsize) |
-| [deserializeBlockHeaders](#function-deserializeblockheaders) | [parseTxScriptOffsets](#function-parsetxscriptoffsets) | [verifyHexString](#function-verifyhexstring) |
-| [doubleSha256BE](#function-doublesha256be) | [populateUtxoDetails](#function-populateutxodetails) | [verifyId](#function-verifyid) |
-| [doubleSha256LE](#function-doublesha256le) | [processAction](#function-processaction) | [verifyInteger](#function-verifyinteger) |
+| [classifyReqStatus](#function-classifyreqstatus) | [isManagedChangeOutput](#function-ismanagedchangeoutput) | [updateExchangeratesapi](#function-updateexchangeratesapi) |
+| [completeSignedTransaction](#function-completesignedtransaction) | [isMoreWork](#function-ismorework) | [updateReqsFromAggregateResults](#function-updatereqsfromaggregateresults) |
+| [computeMerklePath](#function-computemerklepath) | [keyOffsetToHashedSecret](#function-keyoffsettohashedsecret) | [validBulkHeaderFilesByFileHash](#function-validbulkheaderfilesbyfilehash) |
+| [computeMerkleRoot](#function-computemerkleroot) | [listCertificates](#function-listcertificates) | [validateAgainstDirtyHashes](#function-validateagainstdirtyhashes) |
+| [convertBitsToTarget](#function-convertbitstotarget) | [lockScriptWithKeyOffsetFromPubKey](#function-lockscriptwithkeyoffsetfrompubkey) | [validateBufferOfHeaders](#function-validatebufferofheaders) |
+| [convertBitsToWork](#function-convertbitstowork) | [logCreateActionArgs](#function-logcreateactionargs) | [validateBulkFileData](#function-validatebulkfiledata) |
+| [convertBufferToUint32](#function-convertbuffertouint32) | [logWalletError](#function-logwalleterror) | [validateDate](#function-validatedate) |
+| [convertProofToMerklePath](#function-convertprooftomerklepath) | [makeAtomicBeef](#function-makeatomicbeef) | [validateEntities](#function-validateentities) |
+| [convertUint32ToBuffer](#function-convertuint32tobuffer) | [makeChangeLock](#function-makechangelock) | [validateEntity](#function-validateentity) |
+| [convertWocToBlockHeaderHex](#function-convertwoctoblockheaderhex) | [makeMerklePathNote](#function-makemerklepathnote) | [validateGenerateChangeSdkParams](#function-validategeneratechangesdkparams) |
+| [createAction](#function-createaction) | [markStaleInputsAsSpent](#function-markstaleinputsasspent) | [validateGenerateChangeSdkResult](#function-validategeneratechangesdkresult) |
+| [createAction](#function-createaction) | [markUserInputsSpent](#function-markuserinputsspent) | [validateGenesisHeader](#function-validategenesisheader) |
+| [createCoinbaseTransaction](#function-createcoinbasetransaction) | [maxDate](#function-maxdate) | [validateHeaderDifficulty](#function-validateheaderdifficulty) |
+| [createDefaultWalletServicesOptions](#function-createdefaultwalletservicesoptions) | [mergeInputBeefs](#function-mergeinputbeefs) | [validateHeaderFormat](#function-validateheaderformat) |
+| [createStorageServiceChargeScript](#function-createstorageservicechargescript) | [mergeInputsIntoBeef](#function-mergeinputsintobeef) | [validateScriptHash](#function-validatescripthash) |
+| [createSyncMap](#function-createsyncmap) | [notifyTransactionsOfProof](#function-notifytransactionsofproof) | [validateSecondsSinceEpoch](#function-validatesecondssinceepoch) |
+| [deserializeBaseBlockHeader](#function-deserializebaseblockheader) | [offsetPrivKey](#function-offsetprivkey) | [validateStorageFeeModel](#function-validatestoragefeemodel) |
+| [deserializeBaseBlockHeaders](#function-deserializebaseblockheaders) | [offsetPubKey](#function-offsetpubkey) | [validateSyncChunkEntities](#function-validatesyncchunkentities) |
+| [deserializeBlockHeader](#function-deserializeblockheader) | [optionalArraysEqual](#function-optionalarraysequal) | [varUintSize](#function-varuintsize) |
+| [deserializeBlockHeaders](#function-deserializeblockheaders) | [parseResults$](#function-parseresults$) | [verifyHexString](#function-verifyhexstring) |
+| [doubleSha256BE](#function-doublesha256be) | [parseTxScriptOffsets](#function-parsetxscriptoffsets) | [verifyId](#function-verifyid) |
+| [doubleSha256LE](#function-doublesha256le) | [populateUtxoDetails](#function-populateutxodetails) | [verifyInteger](#function-verifyinteger) |
 | [generateChangeSdk](#function-generatechangesdk) | [processAction](#function-processaction) | [verifyNumber](#function-verifynumber) |
-| [generateChangeSdkMakeStorage](#function-generatechangesdkmakestorage) | [proveCertificate](#function-provecertificate) | [verifyOne](#function-verifyone) |
-| [genesisBuffer](#function-genesisbuffer) | [randomBytes](#function-randombytes) | [verifyOneOrNone](#function-verifyoneornone) |
-| [genesisHeader](#function-genesisheader) | [randomBytesBase64](#function-randombytesbase64) | [verifyOptionalHexString](#function-verifyoptionalhexstring) |
-| [getBeefForTransaction](#function-getbeeffortransaction) | [randomBytesHex](#function-randombyteshex) | [verifyTruthy](#function-verifytruthy) |
-| [getBeefForTxid](#function-getbeeffortxid) | [readUInt32BE](#function-readuint32be) | [verifyUnlockScripts](#function-verifyunlockscripts) |
-| [getExchangeRatesIo](#function-getexchangeratesio) | [readUInt32LE](#function-readuint32le) | [wait](#function-wait) |
-| [getIdentityKey](#function-getidentitykey) | [redeemServiceCharges](#function-redeemservicecharges) | [workBNtoBuffer](#function-workbntobuffer) |
-| [getProofs](#function-getproofs) | [restoreInputsToSpendable](#function-restoreinputstospendable) | [writeUInt32BE](#function-writeuint32be) |
-| [getSyncChunk](#function-getsyncchunk) | [selectBulkHeaderFiles](#function-selectbulkheaderfiles) | [writeUInt32LE](#function-writeuint32le) |
-| [getWhatsOnChainBlockHeaderByHash](#function-getwhatsonchainblockheaderbyhash) | [serializeBaseBlockHeader](#function-serializebaseblockheader) |  |
+| [generateChangeSdkMakeStorage](#function-generatechangesdkmakestorage) | [processAction](#function-processaction) | [verifyOne](#function-verifyone) |
+| [genesisBuffer](#function-genesisbuffer) | [proveCertificate](#function-provecertificate) | [verifyOneOrNone](#function-verifyoneornone) |
+| [genesisHeader](#function-genesisheader) | [randomBytes](#function-randombytes) | [verifyOptionalHexString](#function-verifyoptionalhexstring) |
+| [getBeefForTransaction](#function-getbeeffortransaction) | [randomBytesBase64](#function-randombytesbase64) | [verifyRequestedOutputsUnchanged](#function-verifyrequestedoutputsunchanged) |
+| [getBeefForTxid](#function-getbeeffortxid) | [randomBytesHex](#function-randombyteshex) | [verifyTruthy](#function-verifytruthy) |
+| [getExchangeRatesIo](#function-getexchangeratesio) | [readUInt32BE](#function-readuint32be) | [verifyUnlockScripts](#function-verifyunlockscripts) |
+| [getIdentityKey](#function-getidentitykey) | [readUInt32LE](#function-readuint32le) | [verifyUnrequestedOutputsAreChangeOrCommission](#function-verifyunrequestedoutputsarechangeorcommission) |
+| [getProofs](#function-getproofs) | [redeemServiceCharges](#function-redeemservicecharges) | [wait](#function-wait) |
+| [getSyncChunk](#function-getsyncchunk) | [restoreInputsToSpendable](#function-restoreinputstospendable) | [workBNtoBuffer](#function-workbntobuffer) |
+| [getWhatsOnChainBlockHeaderByHash](#function-getwhatsonchainblockheaderbyhash) | [selectBulkHeaderFiles](#function-selectbulkheaderfiles) | [writeUInt32BE](#function-writeuint32be) |
+| [handlePostRawTxErrorResponse](#function-handlepostrawtxerrorresponse) | [serializeBaseBlockHeader](#function-serializebaseblockheader) | [writeUInt32LE](#function-writeuint32le) |
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
 
@@ -12788,12 +12794,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> 
@@ -12836,12 +12844,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> 
@@ -12887,6 +12897,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
 
@@ -13048,6 +13071,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
 
@@ -14249,6 +14288,37 @@ export function verifyOptionalHexString(v?: string | null): string | undefined
 
 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
 
@@ -14282,6 +14352,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
 
@@ -14760,24 +14866,31 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 ---
 #### Variables
 
-| | |
-| --- | --- |
-| [DEFAULT_SETTINGS](#variable-default_settings) | [parseResults](#variable-parseresults) |
-| [ProvenTxReqNonTerminalStatus](#variable-proventxreqnonterminalstatus) | [queryOverlay](#variable-queryoverlay) |
-| [ProvenTxReqTerminalStatus](#variable-proventxreqterminalstatus) | [specOpFailedActions](#variable-specopfailedactions) |
-| [TESTNET_DEFAULT_SETTINGS](#variable-testnet_default_settings) | [specOpInvalidChange](#variable-specopinvalidchange) |
-| [aggregateActionResults](#variable-aggregateactionresults) | [specOpNoSendActions](#variable-specopnosendactions) |
-| [brc29ProtocolID](#variable-brc29protocolid) | [specOpSetWalletChangeParams](#variable-specopsetwalletchangeparams) |
-| [dirtyHashes](#variable-dirtyhashes) | [specOpThrowReviewActions](#variable-specopthrowreviewactions) |
-| [logger](#variable-logger) | [specOpWalletBalance](#variable-specopwalletbalance) |
-| [maxChangeOutputsPerTransaction](#variable-maxchangeoutputspertransaction) | [transactionColumnsWithoutRawTx](#variable-transactioncolumnswithoutrawtx) |
-| [maxPossibleSatoshis](#variable-maxpossiblesatoshis) | [transformVerifiableCertificatesWithTrust](#variable-transformverifiablecertificateswithtrust) |
-| [outputColumnsWithoutLockingScript](#variable-outputcolumnswithoutlockingscript) | [validBulkHeaderFiles](#variable-validbulkheaderfiles) |
+| | | |
+| --- | --- | --- |
+| [ARCADE_POST_BEEF_CONCURRENCY](#variable-arcade_post_beef_concurrency) | [logger](#variable-logger) | [specOpNoSendActions](#variable-specopnosendactions) |
+| [DEFAULT_SETTINGS](#variable-default_settings) | [managedChangeOutputFields](#variable-managedchangeoutputfields) | [specOpSetWalletChangeParams](#variable-specopsetwalletchangeparams) |
+| [MAX_STORAGE_COMMISSION_SATOSHIS](#variable-max_storage_commission_satoshis) | [maxChangeOutputsPerTransaction](#variable-maxchangeoutputspertransaction) | [specOpThrowReviewActions](#variable-specopthrowreviewactions) |
+| [ProvenTxReqNonTerminalStatus](#variable-proventxreqnonterminalstatus) | [maxPossibleSatoshis](#variable-maxpossiblesatoshis) | [specOpWalletBalance](#variable-specopwalletbalance) |
+| [ProvenTxReqTerminalStatus](#variable-proventxreqterminalstatus) | [outputColumnsWithoutLockingScript](#variable-outputcolumnswithoutlockingscript) | [specOpWalletManagedUtxos](#variable-specopwalletmanagedutxos) |
+| [TESTNET_DEFAULT_SETTINGS](#variable-testnet_default_settings) | [parseResults](#variable-parseresults) | [transactionColumnsWithoutRawTx](#variable-transactioncolumnswithoutrawtx) |
+| [aggregateActionResults](#variable-aggregateactionresults) | [queryOverlay](#variable-queryoverlay) | [transformVerifiableCertificatesWithTrust](#variable-transformverifiablecertificateswithtrust) |
+| [brc29ProtocolID](#variable-brc29protocolid) | [specOpFailedActions](#variable-specopfailedactions) | [validBulkHeaderFiles](#variable-validbulkheaderfiles) |
+| [dirtyHashes](#variable-dirtyhashes) | [specOpInvalidChange](#variable-specopinvalidchange) |  |
 
 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: DEFAULT_SETTINGS
 
 ```ts
@@ -14810,6 +14923,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: ProvenTxReqNonTerminalStatus
 
@@ -14947,6 +15069,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
 
@@ -15092,6 +15228,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/out/src/Wallet.d.ts

@@ -181,6 +181,10 @@ export declare class Wallet implements WalletInterface, ProtoWallet {
      * 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.
+     *
      * @param {string} basket - Optional. Defaults to 'default', the wallet change basket.
      * @returns {WalletBalance} total sum of output satoshis and utxo details (satoshis and outpoints)
      */