@bsv/wallet-toolbox 2.4.0 → 2.4.2

package/docs/storage.md

@@ -22,27 +22,28 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 
 | | | |
 | --- | --- | --- |
-| [AdminStatsResult](#interface-adminstatsresult) | [MonitorAdminContextConfig](#interface-monitoradmincontextconfig) | [TableCertificateX](#interface-tablecertificatex) |
-| [AggregatePostBeefTxResult](#interface-aggregatepostbeeftxresult) | [PostBeefResultForTxidApi](#interface-postbeefresultfortxidapi) | [TableCommission](#interface-tablecommission) |
-| [BRC38ImportOptions](#interface-brc38importoptions) | [PostReqsToNetworkDetails](#interface-postreqstonetworkdetails) | [TableMonitorEvent](#interface-tablemonitorevent) |
-| [BRC38ImportResult](#interface-brc38importresult) | [PostReqsToNetworkResult](#interface-postreqstonetworkresult) | [TableOutput](#interface-tableoutput) |
-| [BRC38Tables](#interface-brc38tables) | [ProvenTxFromTxidResult](#interface-proventxfromtxidresult) | [TableOutputBasket](#interface-tableoutputbasket) |
-| [BRC38WalletData](#interface-brc38walletdata) | [ProvenTxReqHistory](#interface-proventxreqhistory) | [TableOutputTag](#interface-tableoutputtag) |
-| [BRC39Options](#interface-brc39options) | [ProvenTxReqHistorySummaryApi](#interface-proventxreqhistorysummaryapi) | [TableOutputTagMap](#interface-tableoutputtagmap) |
-| [CommitNewTxResults](#interface-commitnewtxresults) | [ProvenTxReqNotify](#interface-proventxreqnotify) | [TableOutputX](#interface-tableoutputx) |
-| [EntitySyncMap](#interface-entitysyncmap) | [SpentInputTransition](#interface-spentinputtransition) | [TableProvenTx](#interface-tableproventx) |
-| [GenerateChangeSdkChangeInput](#interface-generatechangesdkchangeinput) | [StorageAdminStats](#interface-storageadminstats) | [TableProvenTxReq](#interface-tableproventxreq) |
-| [GenerateChangeSdkChangeOutput](#interface-generatechangesdkchangeoutput) | [StorageIdbOptions](#interface-storageidboptions) | [TableProvenTxReqDynamics](#interface-tableproventxreqdynamics) |
-| [GenerateChangeSdkInput](#interface-generatechangesdkinput) | [StorageIdbSchema](#interface-storageidbschema) | [TableSettings](#interface-tablesettings) |
-| [GenerateChangeSdkOutput](#interface-generatechangesdkoutput) | [StorageKnexOptions](#interface-storageknexoptions) | [TableSyncState](#interface-tablesyncstate) |
-| [GenerateChangeSdkParams](#interface-generatechangesdkparams) | [StorageMySQLDojoReaderOptions](#interface-storagemysqldojoreaderoptions) | [TableTransaction](#interface-tabletransaction) |
-| [GenerateChangeSdkResult](#interface-generatechangesdkresult) | [StorageProviderOptions](#interface-storageprovideroptions) | [TableTxLabel](#interface-tabletxlabel) |
-| [GenerateChangeSdkStorageChange](#interface-generatechangesdkstoragechange) | [StorageReaderOptions](#interface-storagereaderoptions) | [TableTxLabelMap](#interface-tabletxlabelmap) |
-| [GetReqsAndBeefDetail](#interface-getreqsandbeefdetail) | [StorageReaderWriterOptions](#interface-storagereaderwriteroptions) | [TableUser](#interface-tableuser) |
-| [GetReqsAndBeefResult](#interface-getreqsandbeefresult) | [SyncError](#interface-syncerror) | [ValidateGenerateChangeSdkParamsResult](#interface-validategeneratechangesdkparamsresult) |
+| [AdminStatsResult](#interface-adminstatsresult) | [MonitorAdminContextConfig](#interface-monitoradmincontextconfig) | [TableCertificateField](#interface-tablecertificatefield) |
+| [AggregatePostBeefTxResult](#interface-aggregatepostbeeftxresult) | [PostBeefResultForTxidApi](#interface-postbeefresultfortxidapi) | [TableCertificateX](#interface-tablecertificatex) |
+| [BRC38ImportOptions](#interface-brc38importoptions) | [PostReqsToNetworkDetails](#interface-postreqstonetworkdetails) | [TableCommission](#interface-tablecommission) |
+| [BRC38ImportResult](#interface-brc38importresult) | [PostReqsToNetworkResult](#interface-postreqstonetworkresult) | [TableMonitorEvent](#interface-tablemonitorevent) |
+| [BRC38Tables](#interface-brc38tables) | [ProvenTxFromTxidResult](#interface-proventxfromtxidresult) | [TableOutput](#interface-tableoutput) |
+| [BRC38WalletData](#interface-brc38walletdata) | [ProvenTxReqHistory](#interface-proventxreqhistory) | [TableOutputBasket](#interface-tableoutputbasket) |
+| [BRC39Options](#interface-brc39options) | [ProvenTxReqHistorySummaryApi](#interface-proventxreqhistorysummaryapi) | [TableOutputTag](#interface-tableoutputtag) |
+| [CommitNewTxResults](#interface-commitnewtxresults) | [ProvenTxReqNotify](#interface-proventxreqnotify) | [TableOutputTagMap](#interface-tableoutputtagmap) |
+| [EntitySyncMap](#interface-entitysyncmap) | [SpentInputTransition](#interface-spentinputtransition) | [TableOutputX](#interface-tableoutputx) |
+| [GenerateChangeSdkChangeInput](#interface-generatechangesdkchangeinput) | [StorageAdminStats](#interface-storageadminstats) | [TableProvenTx](#interface-tableproventx) |
+| [GenerateChangeSdkChangeOutput](#interface-generatechangesdkchangeoutput) | [StorageClientOptions](#interface-storageclientoptions) | [TableProvenTxReq](#interface-tableproventxreq) |
+| [GenerateChangeSdkInput](#interface-generatechangesdkinput) | [StorageIdbOptions](#interface-storageidboptions) | [TableProvenTxReqDynamics](#interface-tableproventxreqdynamics) |
+| [GenerateChangeSdkOutput](#interface-generatechangesdkoutput) | [StorageIdbSchema](#interface-storageidbschema) | [TableSettings](#interface-tablesettings) |
+| [GenerateChangeSdkParams](#interface-generatechangesdkparams) | [StorageKnexOptions](#interface-storageknexoptions) | [TableSyncState](#interface-tablesyncstate) |
+| [GenerateChangeSdkResult](#interface-generatechangesdkresult) | [StorageMySQLDojoReaderOptions](#interface-storagemysqldojoreaderoptions) | [TableTransaction](#interface-tabletransaction) |
+| [GenerateChangeSdkStorageChange](#interface-generatechangesdkstoragechange) | [StorageProviderOptions](#interface-storageprovideroptions) | [TableTxLabel](#interface-tabletxlabel) |
+| [GetReqsAndBeefDetail](#interface-getreqsandbeefdetail) | [StorageReaderOptions](#interface-storagereaderoptions) | [TableTxLabelMap](#interface-tabletxlabelmap) |
+| [GetReqsAndBeefResult](#interface-getreqsandbeefresult) | [StorageReaderWriterOptions](#interface-storagereaderwriteroptions) | [TableUser](#interface-tableuser) |
+| [KnexSessionManagerOptions](#interface-knexsessionmanageroptions) | [SyncError](#interface-syncerror) | [ValidateGenerateChangeSdkParamsResult](#interface-validategeneratechangesdkparamsresult) |
 | [ListActionsSpecOp](#interface-listactionsspecop) | [SyncMap](#interface-syncmap) | [VerifyAndRepairBeefResult](#interface-verifyandrepairbeefresult) |
-| [ListOutputsSpecOp](#interface-listoutputsspecop) | [TableCertificate](#interface-tablecertificate) | [WalletStorageServerOptions](#interface-walletstorageserveroptions) |
-| [MonitorAdminContext](#interface-monitoradmincontext) | [TableCertificateField](#interface-tablecertificatefield) | [XValidCreateActionOutput](#interface-xvalidcreateactionoutput) |
+| [ListOutputsSpecOp](#interface-listoutputsspecop) | [TableAuthSession](#interface-tableauthsession) | [WalletStorageServerOptions](#interface-walletstorageserveroptions) |
+| [MonitorAdminContext](#interface-monitoradmincontext) | [TableCertificate](#interface-tablecertificate) | [XValidCreateActionOutput](#interface-xvalidcreateactionoutput) |
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
 
@@ -425,6 +426,34 @@ See also: [GetReqsAndBeefDetail](./storage.md#interface-getreqsandbeefdetail)
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
 
+---
+##### Interface: KnexSessionManagerOptions
+
+```ts
+export interface KnexSessionManagerOptions {
+    ttlMs?: number;
+    now?: () => number;
+}
+```
+
+###### Property now
+
+Testable clock source. Defaults to `Date.now`.
+
+```ts
+now?: () => number
+```
+
+###### Property ttlMs
+
+Session lifetime since its most recent authenticated use. Default: 24 hours.
+
+```ts
+ttlMs?: number
+```
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
+
 ---
 ##### Interface: ListActionsSpecOp
 
@@ -462,6 +491,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 +502,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.
@@ -771,6 +809,27 @@ export interface StorageAdminStats {
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
 
+---
+##### Interface: StorageClientOptions
+
+```ts
+export interface StorageClientOptions {
+    binaryRequests?: boolean;
+}
+```
+
+###### Property binaryRequests
+
+Send compact tagged binary request values after the server advertises
+support. Leave disabled during rolling deployments where an endpoint may
+still route requests to legacy server instances.
+
+```ts
+binaryRequests?: boolean
+```
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
+
 ---
 ##### Interface: StorageIdbOptions
 
@@ -1080,6 +1139,30 @@ See also: [EntitySyncMap](./storage.md#interface-entitysyncmap)
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
 
+---
+##### Interface: TableAuthSession
+
+Durable representation of a BRC-103 peer session.
+
+The session nonce is the authoritative key. `lastUpdate` also acts as the
+optimistic-write version so a delayed request from one replica cannot
+overwrite newer authentication state written by another replica.
+
+```ts
+export interface TableAuthSession {
+    sessionNonce: string;
+    peerNonce?: string | null;
+    peerIdentityKey?: string | null;
+    isAuthenticated: boolean | number;
+    lastUpdate: number | string;
+    certificatesRequired?: boolean | number | null;
+    certificatesValidated?: boolean | number | null;
+    expiresAt: number | string;
+}
+```
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
+
 ---
 ##### Interface: TableCertificate
 
@@ -1710,11 +1793,30 @@ export interface WalletStorageServerOptions {
     calculateRequestPrice?: (req: Request) => number | Promise<number>;
     adminIdentityKeys?: string[];
     makeLogger?: MakeWalletLogger;
+    sessionManager?: AuthMiddlewareOptions["sessionManager"];
+    logRpcRequests?: boolean;
 }
 ```
 
 See also: [Wallet](./client.md#class-wallet)
 
+###### Property logRpcRequests
+
+Emit one JSON log record for each authenticated RPC. Default: true.
+
+```ts
+logRpcRequests?: boolean
+```
+
+###### Property sessionManager
+
+Shared BRC-103 session storage for multi-process or multi-replica servers.
+Defaults to the auth middleware's in-process SessionManager.
+
+```ts
+sessionManager?: AuthMiddlewareOptions["sessionManager"]
+```
+
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
 
 ---
@@ -1739,16 +1841,16 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 
 | | | |
 | --- | --- | --- |
-| [AdminServer](#class-adminserver) | [EntityProvenTxReq](#class-entityproventxreq) | [StorageIdb](#class-storageidb) |
-| [EntityBase](#class-entitybase) | [EntitySyncState](#class-entitysyncstate) | [StorageKnex](#class-storageknex) |
-| [EntityCertificate](#class-entitycertificate) | [EntityTransaction](#class-entitytransaction) | [StorageMySQLDojoReader](#class-storagemysqldojoreader) |
-| [EntityCertificateField](#class-entitycertificatefield) | [EntityTxLabel](#class-entitytxlabel) | [StorageProvider](#class-storageprovider) |
-| [EntityCommission](#class-entitycommission) | [EntityTxLabelMap](#class-entitytxlabelmap) | [StorageReader](#class-storagereader) |
-| [EntityOutput](#class-entityoutput) | [EntityUser](#class-entityuser) | [StorageReaderWriter](#class-storagereaderwriter) |
-| [EntityOutputBasket](#class-entityoutputbasket) | [KnexMigrations](#class-knexmigrations) | [StorageServer](#class-storageserver) |
-| [EntityOutputTag](#class-entityoutputtag) | [MergeEntity](#class-mergeentity) | [StorageSyncReader](#class-storagesyncreader) |
-| [EntityOutputTagMap](#class-entityoutputtagmap) | [StorageClient](#class-storageclient) | [WalletStorageManager](#class-walletstoragemanager) |
-| [EntityProvenTx](#class-entityproventx) | [StorageClientBase](#class-storageclientbase) |  |
+| [AdminServer](#class-adminserver) | [EntityProvenTxReq](#class-entityproventxreq) | [StorageClientBase](#class-storageclientbase) |
+| [EntityBase](#class-entitybase) | [EntitySyncState](#class-entitysyncstate) | [StorageIdb](#class-storageidb) |
+| [EntityCertificate](#class-entitycertificate) | [EntityTransaction](#class-entitytransaction) | [StorageKnex](#class-storageknex) |
+| [EntityCertificateField](#class-entitycertificatefield) | [EntityTxLabel](#class-entitytxlabel) | [StorageMySQLDojoReader](#class-storagemysqldojoreader) |
+| [EntityCommission](#class-entitycommission) | [EntityTxLabelMap](#class-entitytxlabelmap) | [StorageProvider](#class-storageprovider) |
+| [EntityOutput](#class-entityoutput) | [EntityUser](#class-entityuser) | [StorageReader](#class-storagereader) |
+| [EntityOutputBasket](#class-entityoutputbasket) | [KnexMigrations](#class-knexmigrations) | [StorageReaderWriter](#class-storagereaderwriter) |
+| [EntityOutputTag](#class-entityoutputtag) | [KnexSessionManager](#class-knexsessionmanager) | [StorageServer](#class-storageserver) |
+| [EntityOutputTagMap](#class-entityoutputtagmap) | [MergeEntity](#class-mergeentity) | [StorageSyncReader](#class-storagesyncreader) |
+| [EntityProvenTx](#class-entityproventx) | [StorageClient](#class-storageclient) | [WalletStorageManager](#class-walletstoragemanager) |
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
 
@@ -2794,6 +2896,40 @@ Argument Details
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
 
+---
+##### Class: KnexSessionManager
+
+Shared BRC-103 session storage for horizontally scaled StorageServer nodes.
+
+Every instance must use the same Knex database. The wallet-toolbox migration
+creates the required `auth_sessions` table. Writes are monotonic by
+`PeerSession.lastUpdate`, preventing a delayed request on one replica from
+replacing newer session state written by another replica.
+
+```ts
+export class KnexSessionManager implements AsyncSessionManager {
+    constructor(private readonly knex: Knex, options: KnexSessionManagerOptions = {}) 
+    async addSession(session: PeerSession): Promise<void> 
+    async updateSession(session: PeerSession): Promise<void> 
+    async getSession(identifier: string): Promise<PeerSession | undefined> 
+    async removeSession(session: PeerSession): Promise<void> 
+    async hasSession(identifier: string): Promise<boolean> 
+    async pruneExpiredSessions(): Promise<number> 
+}
+```
+
+See also: [KnexSessionManagerOptions](./storage.md#interface-knexsessionmanageroptions)
+
+###### Method pruneExpiredSessions
+
+Delete expired rows. Call from an operator-controlled maintenance task.
+
+```ts
+async pruneExpiredSessions(): Promise<number> 
+```
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
+
 ---
 ##### Class: MergeEntity
 
@@ -2850,12 +2986,12 @@ For details of the API implemented, follow the "See also" link for the `WalletSt
 
 ```ts
 export class StorageClient extends StorageClientBase {
-    constructor(wallet: WalletInterface, endpointUrl: string) 
+    constructor(wallet: WalletInterface, endpointUrl: string, options: StorageClientOptions = {}) 
     protected async rpcCall<T>(method: string, params: unknown[]): Promise<T> 
 }
 ```
 
-See also: [StorageClientBase](./storage.md#class-storageclientbase)
+See also: [StorageClientBase](./storage.md#class-storageclientbase), [StorageClientOptions](./storage.md#interface-storageclientoptions)
 
 ###### Method rpcCall
 
@@ -2888,8 +3024,10 @@ export abstract class StorageClientBase implements WalletStorageProvider {
     readonly endpointUrl: string;
     protected readonly authClient: AuthFetch;
     protected nextId = 1;
+    protected serverSupportsBinary = false;
+    protected readonly binaryRequests: boolean;
     public settings?: TableSettings;
-    constructor(wallet: WalletInterface, endpointUrl: string) 
+    constructor(wallet: WalletInterface, endpointUrl: string, options: StorageClientOptions = {}) 
     isStorageProvider(): boolean 
     protected abstract rpcCall<T>(method: string, params: unknown[]): Promise<T>;
     isAvailable(): boolean 
@@ -2931,7 +3069,7 @@ export abstract class StorageClientBase implements WalletStorageProvider {
 }
 ```
 
-See also: [AuthId](./client.md#interface-authid), [EntityTimeStamp](./client.md#interface-entitytimestamp), [FindCertificatesArgs](./client.md#interface-findcertificatesargs), [FindOutputBasketsArgs](./client.md#interface-findoutputbasketsargs), [FindOutputsArgs](./client.md#interface-findoutputsargs), [FindProvenTxReqsArgs](./client.md#interface-findproventxreqsargs), [ProcessSyncChunkResult](./client.md#interface-processsyncchunkresult), [RequestSyncChunkArgs](./client.md#interface-requestsyncchunkargs), [StorageCreateActionResult](./client.md#interface-storagecreateactionresult), [StorageInternalizeActionResult](./client.md#interface-storageinternalizeactionresult), [StorageProcessActionArgs](./client.md#interface-storageprocessactionargs), [StorageProcessActionResults](./client.md#interface-storageprocessactionresults), [SyncChunk](./client.md#interface-syncchunk), [TableCertificateX](./storage.md#interface-tablecertificatex), [TableOutput](./storage.md#interface-tableoutput), [TableOutputBasket](./storage.md#interface-tableoutputbasket), [TableProvenTxReq](./storage.md#interface-tableproventxreq), [TableSettings](./storage.md#interface-tablesettings), [TableSyncState](./storage.md#interface-tablesyncstate), [TableUser](./storage.md#interface-tableuser), [UpdateProvenTxReqWithNewProvenTxArgs](./client.md#interface-updateproventxreqwithnewproventxargs), [UpdateProvenTxReqWithNewProvenTxResult](./client.md#interface-updateproventxreqwithnewproventxresult), [WalletServices](./client.md#interface-walletservices), [WalletStorageProvider](./client.md#interface-walletstorageprovider), [createAction](./storage.md#function-createaction), [getSyncChunk](./storage.md#function-getsyncchunk), [internalizeAction](./storage.md#function-internalizeaction), [listActions](./storage.md#function-listactions), [listCertificates](./storage.md#function-listcertificates), [listOutputs](./storage.md#function-listoutputs), [processAction](./storage.md#function-processaction), [validateDate](./storage.md#function-validatedate), [validateEntities](./storage.md#function-validateentities), [validateEntity](./storage.md#function-validateentity)
+See also: [AuthId](./client.md#interface-authid), [EntityTimeStamp](./client.md#interface-entitytimestamp), [FindCertificatesArgs](./client.md#interface-findcertificatesargs), [FindOutputBasketsArgs](./client.md#interface-findoutputbasketsargs), [FindOutputsArgs](./client.md#interface-findoutputsargs), [FindProvenTxReqsArgs](./client.md#interface-findproventxreqsargs), [ProcessSyncChunkResult](./client.md#interface-processsyncchunkresult), [RequestSyncChunkArgs](./client.md#interface-requestsyncchunkargs), [StorageClientOptions](./storage.md#interface-storageclientoptions), [StorageCreateActionResult](./client.md#interface-storagecreateactionresult), [StorageInternalizeActionResult](./client.md#interface-storageinternalizeactionresult), [StorageProcessActionArgs](./client.md#interface-storageprocessactionargs), [StorageProcessActionResults](./client.md#interface-storageprocessactionresults), [SyncChunk](./client.md#interface-syncchunk), [TableCertificateX](./storage.md#interface-tablecertificatex), [TableOutput](./storage.md#interface-tableoutput), [TableOutputBasket](./storage.md#interface-tableoutputbasket), [TableProvenTxReq](./storage.md#interface-tableproventxreq), [TableSettings](./storage.md#interface-tablesettings), [TableSyncState](./storage.md#interface-tablesyncstate), [TableUser](./storage.md#interface-tableuser), [UpdateProvenTxReqWithNewProvenTxArgs](./client.md#interface-updateproventxreqwithnewproventxargs), [UpdateProvenTxReqWithNewProvenTxResult](./client.md#interface-updateproventxreqwithnewproventxresult), [WalletServices](./client.md#interface-walletservices), [WalletStorageProvider](./client.md#interface-walletstorageprovider), [createAction](./storage.md#function-createaction), [getSyncChunk](./storage.md#function-getsyncchunk), [internalizeAction](./storage.md#function-internalizeaction), [listActions](./storage.md#function-listactions), [listCertificates](./storage.md#function-listcertificates), [listOutputs](./storage.md#function-listoutputs), [processAction](./storage.md#function-processaction), [validateDate](./storage.md#function-validatedate), [validateEntities](./storage.md#function-validateentities), [validateEntity](./storage.md#function-validateentity)
 
 ###### Method abortAction
 
@@ -3669,7 +3807,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 +4228,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
@@ -4322,6 +4462,10 @@ export abstract class StorageProvider extends StorageReaderWriter implements Wal
     async relinquishOutput(auth: AuthId, args: RelinquishOutputArgs): Promise<number> 
     async processSyncChunk(args: RequestSyncChunkArgs, chunk: SyncChunk): Promise<ProcessSyncChunkResult> 
     async updateProvenTxReqWithNewProvenTx(args: UpdateProvenTxReqWithNewProvenTxArgs): Promise<UpdateProvenTxReqWithNewProvenTxResult> 
+    async reconcileCompletedProvenTxReqs(): Promise<{
+        log: string;
+    }> 
+    async unfailTransactionsForProof(req: EntityProvenTxReq, indent = 0, requestUpdate?: Pick<TableProvenTxReqDynamics, "status" | "attempts">): Promise<string> 
     async confirmSpendableOutputs(): Promise<{
         invalidSpendableOutputs: TableOutput[];
     }> 
@@ -4373,6 +4517,31 @@ async getValidBeefForKnownTxid(txid: string, mergeToBeef?: Beef, trustSelf?: Tru
 ```
 See also: [TrxToken](./client.md#interface-trxtoken)
 
+###### Method reconcileCompletedProvenTxReqs
+
+Reconcile completed proof requests whose transaction fan-out previously
+failed or whose durable notification state drifted.
+
+This is called by TaskReviewStatus so a completed request with
+`notified = false` is retried and can become eligible for normal purge.
+
+```ts
+async reconcileCompletedProvenTxReqs(): Promise<{
+    log: string;
+}> 
+```
+
+###### Method unfailTransactionsForProof
+
+Restore every failed local copy of a transaction before proof completion.
+Also heals the request's notification set from the authoritative txid
+lookup so TaskUnFail cannot omit a local copy after notification drift.
+
+```ts
+async unfailTransactionsForProof(req: EntityProvenTxReq, indent = 0, requestUpdate?: Pick<TableProvenTxReqDynamics, "status" | "attempts">): Promise<string> 
+```
+See also: [EntityProvenTxReq](./storage.md#class-entityproventxreq), [TableProvenTxReqDynamics](./storage.md#interface-tableproventxreqdynamics)
+
 ###### Method updateProvenTxReqWithNewProvenTx
 
 Handles storage changes when a valid MerklePath and mined block header are found for a ProvenTxReq txid.
@@ -4902,12 +5071,15 @@ 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) |
+| [attemptToPostReqsToNetwork](#function-attempttopostreqstonetwork) | [markStaleInputsAsSpent](#function-markstaleinputsasspent) | [shareReqsWithWorld](#function-sharereqswithworld) |
+| [binaryJsonReplacer](#function-binaryjsonreplacer) | [markUserInputsSpent](#function-markuserinputsspent) | [stringifyJsonRpc](#function-stringifyjsonrpc) |
+| [binaryJsonReviver](#function-binaryjsonreviver) | [matchesCertificateFieldPartial](#function-matchescertificatefieldpartial) | [tableAuthSessionToPeerSession](#function-tableauthsessiontopeersession) |
+| [classifyReqStatus](#function-classifyreqstatus) | [matchesCertificatePartial](#function-matchescertificatepartial) | [transactionInputSize](#function-transactioninputsize) |
+| [createAction](#function-createaction) | [matchesCommissionPartial](#function-matchescommissionpartial) | [transactionOutputSize](#function-transactionoutputsize) |
+| [createStorageServiceChargeScript](#function-createstorageservicechargescript) | [matchesMonitorEventPartial](#function-matchesmonitoreventpartial) | [transactionSize](#function-transactionsize) |
+| [createSyncMap](#function-createsyncmap) | [matchesOutputBasketPartial](#function-matchesoutputbasketpartial) | [updateReqsFromAggregateResults](#function-updatereqsfromaggregateresults) |
+| [dateMatches](#function-datematches) | [matchesOutputPartial](#function-matchesoutputpartial) | [upgradeAllStoresV1](#function-upgradeallstoresv1) |
+| [decodeBinaryJsonValue](#function-decodebinaryjsonvalue) | [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) |
@@ -4921,17 +5093,17 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 | [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) |
-| [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) |
-| [listCertificates](#function-listcertificates) | [redeemServiceCharges](#function-redeemservicecharges) | [validateGenerateChangeSdkParams](#function-validategeneratechangesdkparams) |
-| [listOutputs](#function-listoutputs) | [renderAdminPage](#function-renderadminpage) | [validateGenerateChangeSdkResult](#function-validategeneratechangesdkresult) |
-| [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) |  |
+| [internalizeAction](#function-internalizeaction) | [parseJsonRpc](#function-parsejsonrpc) | [upgradeUsers](#function-upgradeusers) |
+| [isAutoSpendableChangeOutput](#function-isautospendablechangeoutput) | [partitionActionLabels](#function-partitionactionlabels) | [validateDate](#function-validatedate) |
+| [isManagedChangeOutput](#function-ismanagedchangeoutput) | [processAction](#function-processaction) | [validateEntities](#function-validateentities) |
+| [keyOffsetToHashedSecret](#function-keyoffsettohashedsecret) | [purgeData](#function-purgedata) | [validateEntity](#function-validateentity) |
+| [legacyBinaryJsonReplacer](#function-legacybinaryjsonreplacer) | [purgeDataIdb](#function-purgedataidb) | [validateGenerateChangeSdkParams](#function-validategeneratechangesdkparams) |
+| [listActions](#function-listactions) | [redeemServiceCharges](#function-redeemservicecharges) | [validateGenerateChangeSdkResult](#function-validategeneratechangesdkresult) |
+| [listActionsIdb](#function-listactionsidb) | [renderAdminPage](#function-renderadminpage) | [validateStorageFeeModel](#function-validatestoragefeemodel) |
+| [listCertificates](#function-listcertificates) | [restoreInputsToSpendable](#function-restoreinputstospendable) | [validateSyncChunkEntities](#function-validatesyncchunkentities) |
+| [listOutputs](#function-listoutputs) | [reviewStatus](#function-reviewstatus) | [varUintSize](#function-varuintsize) |
+| [listOutputsIdb](#function-listoutputsidb) | [reviewStatusIdb](#function-reviewstatusidb) |  |
+| [lockScriptWithKeyOffsetFromPubKey](#function-lockscriptwithkeyoffsetfrompubkey) | [setDisableDoubleSpendCheckForTest](#function-setdisabledoublespendcheckfortest) |  |
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
 
@@ -4950,6 +5122,24 @@ See also: [EntityProvenTxReq](./storage.md#class-entityproventxreq), [PostReqsTo
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
 
+---
+##### Function: binaryJsonReplacer
+
+```ts
+export function binaryJsonReplacer(this: Record<string, unknown>, key: string, value: unknown): unknown 
+```
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
+
+---
+##### Function: binaryJsonReviver
+
+```ts
+export function binaryJsonReviver(_key: string, value: unknown): unknown 
+```
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
+
 ---
 ##### Function: classifyReqStatus
 
@@ -5007,6 +5197,15 @@ export function dateMatches(a: Date | undefined, b: Date | undefined): boolean
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
 
+---
+##### Function: decodeBinaryJsonValue
+
+```ts
+export function decodeBinaryJsonValue(value: unknown): unknown 
+```
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
+
 ---
 ##### Function: decryptBRC39
 
@@ -5225,12 +5424,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 +5441,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
 
@@ -5252,6 +5482,15 @@ export function keyOffsetToHashedSecret(pub: PublicKey, keyOffset?: string): {
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
 
+---
+##### Function: legacyBinaryJsonReplacer
+
+```ts
+export function legacyBinaryJsonReplacer(_key: string, value: unknown): unknown 
+```
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
+
 ---
 ##### Function: listActions
 
@@ -5574,14 +5813,15 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 Notify each transaction that a proof has been found.
 Mutates `req` history notes in place.
 
-The `addNote` and `flushNotes` callbacks avoid coupling this helper to a
-specific entity type.
+The `addNote` callback avoids coupling this helper to a specific entity type.
+Returns false if any transaction update failed so callers can retain the
+request for later status repair.
 
 ```ts
-export async function notifyTransactionsOfProof(ids: number[], provenTxId: number, addNote: (note: ReqHistoryNote) => void, flushNotes: () => Promise<void>, updateTransaction: (id: number, update: {
+export async function notifyTransactionsOfProof(ids: number[], provenTxId: number, addNote: (note: ReqHistoryNote) => void, updateTransaction: (id: number, update: {
     provenTxId: number;
     status: "completed";
-}) => Promise<unknown>): Promise<void> 
+}) => Promise<unknown>): Promise<boolean> 
 ```
 
 See also: [ReqHistoryNote](./client.md#interface-reqhistorynote)
@@ -5623,6 +5863,15 @@ See also: [BRC38WalletData](./storage.md#interface-brc38walletdata)
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
 
+---
+##### Function: parseJsonRpc
+
+```ts
+export function parseJsonRpc(text: string, binary: boolean = false): any 
+```
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
+
 ---
 ##### Function: partitionActionLabels
 
@@ -5770,6 +6019,26 @@ See also: [GetReqsAndBeefResult](./storage.md#interface-getreqsandbeefresult), [
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
 
+---
+##### Function: stringifyJsonRpc
+
+```ts
+export function stringifyJsonRpc(value: unknown, binary: boolean): string 
+```
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
+
+---
+##### Function: tableAuthSessionToPeerSession
+
+```ts
+export function tableAuthSessionToPeerSession(row: TableAuthSession): PeerSession 
+```
+
+See also: [TableAuthSession](./storage.md#interface-tableauthsession)
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
+
 ---
 ##### Function: transactionInputSize
 
@@ -6215,18 +6484,83 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 ---
 #### Variables
 
-| |
-| --- |
-| [getLabelToSpecOp](#variable-getlabeltospecop) |
-| [maxChangeOutputsPerTransaction](#variable-maxchangeoutputspertransaction) |
-| [maxPossibleSatoshis](#variable-maxpossiblesatoshis) |
-| [outputColumnsWithoutLockingScript](#variable-outputcolumnswithoutlockingscript) |
-| [transactionColumnsWithoutRawTx](#variable-transactioncolumnswithoutrawtx) |
+| | |
+| --- | --- |
+| [AUTH_SESSION_MIGRATION](#variable-auth_session_migration) | [getLabelToSpecOp](#variable-getlabeltospecop) |
+| [AUTH_SESSION_TABLE](#variable-auth_session_table) | [managedChangeOutputFields](#variable-managedchangeoutputfields) |
+| [BINARY_ENCODING](#variable-binary_encoding) | [maxChangeOutputsPerTransaction](#variable-maxchangeoutputspertransaction) |
+| [BINARY_ENCODING_HEADER](#variable-binary_encoding_header) | [maxPossibleSatoshis](#variable-maxpossiblesatoshis) |
+| [BINARY_REQUEST_ENCODING_HEADER](#variable-binary_request_encoding_header) | [outputColumnsWithoutLockingScript](#variable-outputcolumnswithoutlockingscript) |
+| [DEFAULT_AUTH_SESSION_TTL_MS](#variable-default_auth_session_ttl_ms) | [transactionColumnsWithoutRawTx](#variable-transactioncolumnswithoutrawtx) |
+| [MONITOR_CREATED_AT_INDEX_MIGRATION](#variable-monitor_created_at_index_migration) |  |
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
 
 ---
 
+##### Variable: AUTH_SESSION_MIGRATION
+
+```ts
+AUTH_SESSION_MIGRATION = "2026-07-14-001 add shared auth sessions"
+```
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
+
+---
+##### Variable: AUTH_SESSION_TABLE
+
+```ts
+AUTH_SESSION_TABLE = "auth_sessions"
+```
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
+
+---
+##### Variable: BINARY_ENCODING
+
+```ts
+BINARY_ENCODING = "base64"
+```
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
+
+---
+##### Variable: BINARY_ENCODING_HEADER
+
+```ts
+BINARY_ENCODING_HEADER = "X-BSV-Binary-Encoding"
+```
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
+
+---
+##### Variable: BINARY_REQUEST_ENCODING_HEADER
+
+```ts
+BINARY_REQUEST_ENCODING_HEADER = "X-BSV-Binary-Request-Encoding"
+```
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
+
+---
+##### Variable: DEFAULT_AUTH_SESSION_TTL_MS
+
+```ts
+DEFAULT_AUTH_SESSION_TTL_MS = 24 * 60 * 60 * 1000
+```
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
+
+---
+##### Variable: MONITOR_CREATED_AT_INDEX_MIGRATION
+
+```ts
+MONITOR_CREATED_AT_INDEX_MIGRATION = "2026-07-14-002 add monitor created index"
+```
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
+
+---
 ##### Variable: getLabelToSpecOp
 
 ```ts
@@ -6292,6 +6626,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 +6717,4 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 
 ---
 
-<!--#endregion ts2md-api-merged-here-->
+<!--#endregion ts2md-api-merged-here-->