@bsv/wallet-toolbox 2.4.0 → 2.4.2

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

@@ -4732,7 +4732,7 @@ export default class SdkWhatsOnChain implements ChainTracker {
     readonly apiKey: string;
     protected readonly URL: string;
     protected readonly httpClient: HttpClient;
-    constructor(network: "main" | "test" | "stn" | "ttn" = "main", config: WhatsOnChainConfig = {}) 
+    constructor(network: "main" | "test" | "stn" | "ttn" | "tstn" = "main", config: WhatsOnChainConfig = {}) 
     async isValidRootForHeight(root: string, height: number): Promise<boolean> 
     async currentHeight(): Promise<number> 
     protected getHttpHeaders(): Record<string, string> 
@@ -4744,7 +4744,7 @@ export default class SdkWhatsOnChain implements ChainTracker {
 Constructs an instance of the WhatsOnChain ChainTracker.
 
 ```ts
-constructor(network: "main" | "test" | "stn" | "ttn" = "main", config: WhatsOnChainConfig = {}) 
+constructor(network: "main" | "test" | "stn" | "ttn" | "tstn" = "main", config: WhatsOnChainConfig = {}) 
 ```
 
 Argument Details
@@ -5135,30 +5135,31 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 
 | | | |
 | --- | --- | --- |
-| [WocHeadersBulkListener](#function-wocheadersbulklistener) | [deserializeBaseBlockHeaders](#function-deserializebaseblockheaders) | [readUInt32BE](#function-readuint32be) |
-| [WocHeadersBulkListener_test](#function-wocheadersbulklistener_test) | [deserializeBlockHeader](#function-deserializeblockheader) | [readUInt32LE](#function-readuint32le) |
-| [WocHeadersLiveListener](#function-wocheaderslivelistener) | [deserializeBlockHeaders](#function-deserializeblockheaders) | [selectBulkHeaderFiles](#function-selectbulkheaderfiles) |
-| [WocHeadersLiveListener_test](#function-wocheaderslivelistener_test) | [genesisBuffer](#function-genesisbuffer) | [serializeBaseBlockHeader](#function-serializebaseblockheader) |
-| [addWork](#function-addwork) | [genesisHeader](#function-genesisheader) | [serializeBaseBlockHeaders](#function-serializebaseblockheaders) |
-| [arcDefaultUrl](#function-arcdefaulturl) | [getBeefForTxid](#function-getbeeffortxid) | [sha256HashOfBinaryFile](#function-sha256hashofbinaryfile) |
-| [arcGorillaPoolUrl](#function-arcgorillapoolurl) | [getExchangeRatesIo](#function-getexchangeratesio) | [subWork](#function-subwork) |
-| [arcadeDefaultUrl](#function-arcadedefaulturl) | [getWhatsOnChainBlockHeaderByHash](#function-getwhatsonchainblockheaderbyhash) | [swapByteOrder](#function-swapbyteorder) |
-| [blockHash](#function-blockhash) | [handlePostRawTxErrorResponse](#function-handlepostrawtxerrorresponse) | [toBinaryBaseBlockHeader](#function-tobinarybaseblockheader) |
-| [buildChaintracksOptionsWithIngestors](#function-buildchaintracksoptionswithingestors) | [handleScriptHashHistoryCatch](#function-handlescripthashhistorycatch) | [updateChaintracksFiatExchangeRates](#function-updatechaintracksfiatexchangerates) |
-| [classifyMerklePathResponse](#function-classifymerklepathresponse) | [handleScriptHashHistoryResponse](#function-handlescripthashhistoryresponse) | [updateExchangeratesapi](#function-updateexchangeratesapi) |
-| [convertBitsToTarget](#function-convertbitstotarget) | [handleUtxoConnReset](#function-handleutxoconnreset) | [validBulkHeaderFilesByFileHash](#function-validbulkheaderfilesbyfilehash) |
-| [convertBitsToWork](#function-convertbitstowork) | [isArcAcceptedTxStatus](#function-isarcacceptedtxstatus) | [validateAgainstDirtyHashes](#function-validateagainstdirtyhashes) |
-| [convertBufferToUint32](#function-convertbuffertouint32) | [isArcDoubleSpendTxStatus](#function-isarcdoublespendtxstatus) | [validateBufferOfHeaders](#function-validatebufferofheaders) |
-| [convertUint32ToBuffer](#function-convertuint32tobuffer) | [isArcInvalidTxStatus](#function-isarcinvalidtxstatus) | [validateBulkFileData](#function-validatebulkfiledata) |
-| [convertWocToBlockHeaderHex](#function-convertwoctoblockheaderhex) | [isArcServiceErrorStatus](#function-isarcserviceerrorstatus) | [validateGenesisHeader](#function-validategenesisheader) |
-| [createDefaultIdbChaintracksOptions](#function-createdefaultidbchaintracksoptions) | [isBaseBlockHeader](#function-isbaseblockheader) | [validateHeaderDifficulty](#function-validateheaderdifficulty) |
-| [createDefaultKnexChaintracksOptions](#function-createdefaultknexchaintracksoptions) | [isBlockHeader](#function-isblockheader) | [validateHeaderFormat](#function-validateheaderformat) |
-| [createDefaultNoDbChaintracksOptions](#function-createdefaultnodbchaintracksoptions) | [isKnownValidBulkHeaderFile](#function-isknownvalidbulkheaderfile) | [validateScriptHash](#function-validatescripthash) |
-| [createDefaultWalletServicesOptions](#function-createdefaultwalletservicesoptions) | [isLive](#function-islive) | [wocGetHeadersHeaderToBlockHeader](#function-wocgetheadersheadertoblockheader) |
-| [createIdbChaintracks](#function-createidbchaintracks) | [isLiveBlockHeader](#function-isliveblockheader) | [workBNtoBuffer](#function-workbntobuffer) |
-| [createKnexChaintracks](#function-createknexchaintracks) | [isMoreWork](#function-ismorework) | [writeUInt32BE](#function-writeuint32be) |
-| [createNoDbChaintracks](#function-createnodbchaintracks) | [makeMerklePathNote](#function-makemerklepathnote) | [writeUInt32LE](#function-writeuint32le) |
-| [deserializeBaseBlockHeader](#function-deserializebaseblockheader) | [populateUtxoDetails](#function-populateutxodetails) |  |
+| [WocHeadersBulkListener](#function-wocheadersbulklistener) | [deserializeBlockHeader](#function-deserializeblockheader) | [selectBulkHeaderFiles](#function-selectbulkheaderfiles) |
+| [WocHeadersBulkListener_test](#function-wocheadersbulklistener_test) | [deserializeBlockHeaders](#function-deserializeblockheaders) | [serializeBaseBlockHeader](#function-serializebaseblockheader) |
+| [WocHeadersLiveListener](#function-wocheaderslivelistener) | [genesisBuffer](#function-genesisbuffer) | [serializeBaseBlockHeaders](#function-serializebaseblockheaders) |
+| [WocHeadersLiveListener_test](#function-wocheaderslivelistener_test) | [genesisHeader](#function-genesisheader) | [sha256HashOfBinaryFile](#function-sha256hashofbinaryfile) |
+| [addWork](#function-addwork) | [getBeefForTxid](#function-getbeeffortxid) | [subWork](#function-subwork) |
+| [arcDefaultUrl](#function-arcdefaulturl) | [getExchangeRatesIo](#function-getexchangeratesio) | [swapByteOrder](#function-swapbyteorder) |
+| [arcGorillaPoolUrl](#function-arcgorillapoolurl) | [getWhatsOnChainBlockHeaderByHash](#function-getwhatsonchainblockheaderbyhash) | [toBinaryBaseBlockHeader](#function-tobinarybaseblockheader) |
+| [arcadeDefaultUrl](#function-arcadedefaulturl) | [handlePostRawTxErrorResponse](#function-handlepostrawtxerrorresponse) | [tstnArcadeUrl](#function-tstnarcadeurl) |
+| [blockHash](#function-blockhash) | [handleScriptHashHistoryCatch](#function-handlescripthashhistorycatch) | [tstnChaintracksUrl](#function-tstnchaintracksurl) |
+| [buildChaintracksOptionsWithIngestors](#function-buildchaintracksoptionswithingestors) | [handleScriptHashHistoryResponse](#function-handlescripthashhistoryresponse) | [updateChaintracksFiatExchangeRates](#function-updatechaintracksfiatexchangerates) |
+| [classifyMerklePathResponse](#function-classifymerklepathresponse) | [handleUtxoConnReset](#function-handleutxoconnreset) | [updateExchangeratesapi](#function-updateexchangeratesapi) |
+| [convertBitsToTarget](#function-convertbitstotarget) | [isArcAcceptedTxStatus](#function-isarcacceptedtxstatus) | [validBulkHeaderFilesByFileHash](#function-validbulkheaderfilesbyfilehash) |
+| [convertBitsToWork](#function-convertbitstowork) | [isArcDoubleSpendTxStatus](#function-isarcdoublespendtxstatus) | [validateAgainstDirtyHashes](#function-validateagainstdirtyhashes) |
+| [convertBufferToUint32](#function-convertbuffertouint32) | [isArcInvalidTxStatus](#function-isarcinvalidtxstatus) | [validateBufferOfHeaders](#function-validatebufferofheaders) |
+| [convertUint32ToBuffer](#function-convertuint32tobuffer) | [isArcServiceErrorStatus](#function-isarcserviceerrorstatus) | [validateBulkFileData](#function-validatebulkfiledata) |
+| [convertWocToBlockHeaderHex](#function-convertwoctoblockheaderhex) | [isBaseBlockHeader](#function-isbaseblockheader) | [validateGenesisHeader](#function-validategenesisheader) |
+| [createDefaultIdbChaintracksOptions](#function-createdefaultidbchaintracksoptions) | [isBlockHeader](#function-isblockheader) | [validateHeaderDifficulty](#function-validateheaderdifficulty) |
+| [createDefaultKnexChaintracksOptions](#function-createdefaultknexchaintracksoptions) | [isKnownValidBulkHeaderFile](#function-isknownvalidbulkheaderfile) | [validateHeaderFormat](#function-validateheaderformat) |
+| [createDefaultNoDbChaintracksOptions](#function-createdefaultnodbchaintracksoptions) | [isLive](#function-islive) | [validateScriptHash](#function-validatescripthash) |
+| [createDefaultWalletServicesOptions](#function-createdefaultwalletservicesoptions) | [isLiveBlockHeader](#function-isliveblockheader) | [wocGetHeadersHeaderToBlockHeader](#function-wocgetheadersheadertoblockheader) |
+| [createIdbChaintracks](#function-createidbchaintracks) | [isMoreWork](#function-ismorework) | [workBNtoBuffer](#function-workbntobuffer) |
+| [createKnexChaintracks](#function-createknexchaintracks) | [makeMerklePathNote](#function-makemerklepathnote) | [writeUInt32BE](#function-writeuint32be) |
+| [createNoDbChaintracks](#function-createnodbchaintracks) | [populateUtxoDetails](#function-populateutxodetails) | [writeUInt32LE](#function-writeuint32le) |
+| [deserializeBaseBlockHeader](#function-deserializebaseblockheader) | [readUInt32BE](#function-readuint32be) |  |
+| [deserializeBaseBlockHeaders](#function-deserializebaseblockheaders) | [readUInt32LE](#function-readuint32le) |  |
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
 
@@ -5663,6 +5664,7 @@ export function genesisHeader(chain: Chain): BlockHeader {
             };
         case "test":
         case "ttn":
+        case "tstn":
             return {
                 version: 1,
                 previousHash: "0000000000000000000000000000000000000000000000000000000000000000",
@@ -6131,6 +6133,29 @@ Returns
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
 
+---
+##### Function: tstnArcadeUrl
+
+Arcade broadcaster / ARC endpoint for tstn, or `undefined` when `TSTN_ARCADE_URL` is unset.
+
+```ts
+export function tstnArcadeUrl(): string | undefined 
+```
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
+
+---
+##### Function: tstnChaintracksUrl
+
+ChainTracks service URL for tstn. Falls back to `${TSTN_ARCADE_URL}/chaintracks/v1` when
+`TSTN_CHAINTRACKS_URL` is unset (mirrors the ttn layout). Throws when neither is configured.
+
+```ts
+export function tstnChaintracksUrl(): string 
+```
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
+
 ---
 ##### Function: updateChaintracksFiatExchangeRates
 
@@ -6467,6 +6492,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) |
@@ -6475,6 +6501,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