@bopen-io/wallet-toolbox 2.6.2-brc153.5 → 2.15.0-bopen.1

package/docs/setup.md

@@ -59,10 +59,11 @@ export interface SetupClientWalletArgs {
     backups?: WalletStorageProvider[];
     taalApiKey?: string;
     scriptVerifier?: SpendVerifierInterface;
+    managedChangePolicy?: ManagedChangePolicyOptions;
 }
 ```
 
-See also: [Chain](./client.md#type-chain), [WalletStorageProvider](./client.md#interface-walletstorageprovider)
+See also: [Chain](./client.md#type-chain), [ManagedChangePolicyOptions](./storage.md#type-managedchangepolicyoptions), [WalletStorageProvider](./client.md#interface-walletstorageprovider)
 
 ###### Property active
 
@@ -82,6 +83,15 @@ backups?: WalletStorageProvider[]
 ```
 See also: [WalletStorageProvider](./client.md#interface-walletstorageprovider)
 
+###### Property managedChangePolicy
+
+Optional operator tuning for local wallet-managed liquidity shaping.
+
+```ts
+managedChangePolicy?: ManagedChangePolicyOptions
+```
+See also: [ManagedChangePolicyOptions](./storage.md#type-managedchangepolicyoptions)
+
 ###### Property privilegedKeyGetter
 
 Optional. The privileged private key getter used to initialize the `PrivilegedKeyManager`.
@@ -91,21 +101,21 @@ Defaults to undefined.
 privilegedKeyGetter?: () => Promise<PrivateKey>
 ```
 
-###### Property scriptVerifier
+###### Property rootKeyHex
 
-Optional high-performance verifier for internal wallet and locally hosted
-storage validation. This does not alter the BRC-100 interface.
+The non-privileged private key used to initialize the `KeyDeriver` and determine the `identityKey`.
 
 ```ts
-scriptVerifier?: SpendVerifierInterface
+rootKeyHex: string
 ```
 
-###### Property rootKeyHex
+###### Property scriptVerifier
 
-The non-privileged private key used to initialize the `KeyDeriver` and determine the `identityKey`.
+Optional high-performance verifier for internal wallet and locally hosted
+storage validation. This does not alter the BRC-100 interface.
 
 ```ts
-rootKeyHex: string
+scriptVerifier?: SpendVerifierInterface
 ```
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
@@ -343,10 +353,12 @@ export interface SetupWalletArgs {
     active?: WalletStorageProvider;
     backups?: WalletStorageProvider[];
     scriptVerifier?: SpendVerifierInterface;
+    managedChangePolicy?: ManagedChangePolicyOptions;
+    preparedBeef?: PreparedBeefOptions;
 }
 ```
 
-See also: [SetupEnv](./setup.md#interface-setupenv), [WalletStorageProvider](./client.md#interface-walletstorageprovider)
+See also: [ManagedChangePolicyOptions](./storage.md#type-managedchangepolicyoptions), [PreparedBeefOptions](./storage.md#interface-preparedbeefoptions), [SetupEnv](./setup.md#interface-setupenv), [WalletStorageProvider](./client.md#interface-walletstorageprovider)
 
 ###### Property active
 
@@ -375,22 +387,31 @@ env: SetupEnv
 ```
 See also: [SetupEnv](./setup.md#interface-setupenv)
 
-###### Property privilegedKeyGetter
+###### Property managedChangePolicy
 
-Optional. The privileged private key getter used to initialize the `PrivilegedKeyManager`.
-Defaults to undefined.
+Optional operator tuning for wallet-managed liquidity shaping.
 
 ```ts
-privilegedKeyGetter?: () => Promise<PrivateKey>
+managedChangePolicy?: ManagedChangePolicyOptions
 ```
+See also: [ManagedChangePolicyOptions](./storage.md#type-managedchangepolicyoptions)
 
-###### Property scriptVerifier
+###### Property preparedBeef
 
-Optional high-performance verifier for internal wallet and locally hosted
-storage validation. This does not alter the BRC-100 interface.
+Optional prepared-BEEF (COOK) rollout controls for Knex storage.
 
 ```ts
-scriptVerifier?: SpendVerifierInterface
+preparedBeef?: PreparedBeefOptions
+```
+See also: [PreparedBeefOptions](./storage.md#interface-preparedbeefoptions)
+
+###### Property privilegedKeyGetter
+
+Optional. The privileged private key getter used to initialize the `PrivilegedKeyManager`.
+Defaults to undefined.
+
+```ts
+privilegedKeyGetter?: () => Promise<PrivateKey>
 ```
 
 ###### Property rootKeyHex
@@ -402,6 +423,15 @@ Defaults to `env.devKeys[env.identityKey]
 rootKeyHex?: string
 ```
 
+###### Property scriptVerifier
+
+Optional high-performance verifier for internal wallet and locally hosted
+storage validation. This does not alter the BRC-100 interface.
+
+```ts
+scriptVerifier?: SpendVerifierInterface
+```
+
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
 
 ---
@@ -483,10 +513,20 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 ```ts
 export interface SetupWalletIdbArgs extends SetupClientWalletArgs {
     databaseName: string;
+    managedChangePolicy?: ManagedChangePolicyOptions;
 }
 ```
 
-See also: [SetupClientWalletArgs](./setup.md#interface-setupclientwalletargs)
+See also: [ManagedChangePolicyOptions](./storage.md#type-managedchangepolicyoptions), [SetupClientWalletArgs](./setup.md#interface-setupclientwalletargs)
+
+###### Property managedChangePolicy
+
+Optional operator tuning for wallet-managed liquidity shaping.
+
+```ts
+managedChangePolicy?: ManagedChangePolicyOptions
+```
+See also: [ManagedChangePolicyOptions](./storage.md#type-managedchangepolicyoptions)
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
 
@@ -519,11 +559,22 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 export interface SetupWalletKnexArgs extends SetupWalletArgs {
     knex: Knex<any, any[]>;
     databaseName: string;
+    actionBatchMaxReservedOutputs?: number;
 }
 ```
 
 See also: [SetupWalletArgs](./setup.md#interface-setupwalletargs)
 
+###### Property actionBatchMaxReservedOutputs
+
+Maximum persisted outputs one action-batch workspace may reserve.
+Defaults to 256. Set to -1 only when the storage operator deliberately
+accepts unbounded reservations.
+
+```ts
+actionBatchMaxReservedOutputs?: number
+```
+
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
 
 ---
@@ -600,7 +651,6 @@ DEV_KEYS = '{
     "${mainIdentityKey2}": "${mainPrivKey2.toString()}"
 }'
 `;
-        console.log(log);
         return log;
     }
     static getEnv(chain: Chain): SetupEnv {
@@ -636,16 +686,15 @@ DEV_KEYS = '{
         const services = new Services(serviceOptions);
         const monopts = Monitor.createDefaultWalletMonitorOptions(chain, storage, services, undefined, "default");
         const monitor = new Monitor(monopts);
-        const privilegedKeyManager = args.privilegedKeyGetter
-            ? new PrivilegedKeyManager(args.privilegedKeyGetter)
-            : undefined;
+        const privilegedKeyManager = args.privilegedKeyGetter != null ? new PrivilegedKeyManager(args.privilegedKeyGetter) : undefined;
         const wallet = new Wallet({
             chain,
             keyDeriver,
             storage,
             services,
             monitor,
-            privilegedKeyManager
+            privilegedKeyManager,
+            scriptVerifier: args.scriptVerifier
         });
         const r: SetupWallet = {
             rootKey,
@@ -664,6 +713,7 @@ DEV_KEYS = '{
         rootKeyHex: string;
         storageUrl?: string;
         privilegedKeyGetter?: () => Promise<PrivateKey>;
+        scriptVerifier?: SpendVerifierInterface;
     }): Promise<Wallet> 
     static async createWalletClient(args: SetupWalletClientArgs): Promise<SetupWalletClient> {
         const wo = await Setup.createWallet(args);
@@ -696,13 +746,13 @@ DEV_KEYS = '{
         const unlock = p2pkh.unlock(priv, "all", false, satoshis, lock);
         return unlock;
     }
-    static createP2PKHOutputs(outputs: {
+    static createP2PKHOutputs(outputs: Array<{
         address: string;
         satoshis: number;
         outputDescription?: string;
         basket?: string;
         tags?: string[];
-    }[]): CreateActionOutput[] {
+    }>): CreateActionOutput[] {
         const os: CreateActionOutput[] = [];
         const count = outputs.length;
         for (let i = 0; i < count; i++) {
@@ -717,19 +767,19 @@ DEV_KEYS = '{
         }
         return os;
     }
-    static async createP2PKHOutputsAction(wallet: WalletInterface, outputs: {
+    static async createP2PKHOutputsAction(wallet: WalletInterface, outputs: Array<{
         address: string;
         satoshis: number;
         outputDescription?: string;
         basket?: string;
         tags?: string[];
-    }[], options?: CreateActionOptions): Promise<{
+    }>, options?: CreateActionOptions): Promise<{
         cr: CreateActionResult;
         outpoints: string[] | undefined;
     }> {
         const os = Setup.createP2PKHOutputs(outputs);
         const createArgs: CreateActionArgs = {
-            description: `createP2PKHOutputs`,
+            description: "createP2PKHOutputs",
             outputs: os,
             options: {
                 ...options,
@@ -743,19 +793,19 @@ DEV_KEYS = '{
         }
         return { cr, outpoints };
     }
-    static async fundWalletFromP2PKHOutpoints(wallet: WalletInterface, outpoints: string[], p2pkhKey: KeyPairAddress, inputBEEF?: BEEF): Promise<{
+    static async fundWalletFromP2PKHOutpoints(wallet: WalletInterface, outpoints: string[], p2pkhKey: KeyPairAddress, inputBEEF?: BEEF): Promise<Array<{
         outpoint: string;
         txid?: string;
         success: boolean;
         error?: string;
-    }[]> {
-        return _fundWalletFromP2PKHOutpoints(wallet, outpoints, p2pkhKey, Setup.getUnlockP2PKH.bind(Setup), inputBEEF);
+    }>> {
+        return await _fundWalletFromP2PKHOutpoints(wallet, outpoints, p2pkhKey, Setup.getUnlockP2PKH.bind(Setup), inputBEEF);
     }
     static async createWalletKnex(args: SetupWalletKnexArgs): Promise<SetupWalletKnex> {
         const wo = await Setup.createWallet(args);
         const activeStorage = await Setup.createStorageKnex(args);
         await wo.storage.addWalletStorageProvider(activeStorage);
-        const { user, isNew } = await activeStorage.findOrInsertUser(wo.identityKey);
+        const { user } = await activeStorage.findOrInsertUser(wo.identityKey);
         const userId = user.userId;
         const r: SetupWalletKnex = {
             ...wo,
@@ -788,6 +838,20 @@ DEV_KEYS = '{
         const knex = makeKnex(config);
         return knex;
     }
+    static createPostgresKnex(connection: string, database?: string): Knex {
+        const c: Knex.PgConnectionConfig = JSON.parse(connection);
+        if (database) {
+            c.database = database;
+        }
+        const config: Knex.Config = {
+            client: "pg",
+            connection: c,
+            pool: { min: 0, max: 7, idleTimeoutMillis: 15000 }
+        };
+        const knex = makeKnex(config);
+        usePostgresInt8Numbers(knex);
+        return knex;
+    }
     static async createWalletMySQL(args: SetupWalletMySQLArgs): Promise<SetupWalletKnex> {
         return await this.createWalletKnex({
             ...args,
@@ -803,7 +867,38 @@ DEV_KEYS = '{
 }
 ```
 
-See also: [Chain](./client.md#type-chain), [KeyPairAddress](./setup.md#interface-keypairaddress), [Monitor](./monitor.md#class-monitor), [PrivilegedKeyManager](./client.md#class-privilegedkeymanager), [ScriptTemplateUnlock](./client.md#interface-scripttemplateunlock), [Services](./services.md#class-services), [SetupEnv](./setup.md#interface-setupenv), [SetupWallet](./setup.md#interface-setupwallet), [SetupWalletArgs](./setup.md#interface-setupwalletargs), [SetupWalletClient](./setup.md#interface-setupwalletclient), [SetupWalletClientArgs](./setup.md#interface-setupwalletclientargs), [SetupWalletKnex](./setup.md#interface-setupwalletknex), [SetupWalletKnexArgs](./setup.md#interface-setupwalletknexargs), [SetupWalletMySQLArgs](./setup.md#interface-setupwalletmysqlargs), [SetupWalletSQLiteArgs](./setup.md#interface-setupwalletsqliteargs), [StorageClient](./storage.md#class-storageclient), [StorageKnex](./storage.md#class-storageknex), [WERR_INVALID_OPERATION](./client.md#class-werr_invalid_operation), [Wallet](./client.md#class-wallet), [WalletStorageManager](./storage.md#class-walletstoragemanager), [createAction](./storage.md#function-createaction), [fundWalletFromP2PKHOutpoints](./client.md#function-fundwalletfromp2pkhoutpoints), [verifyTruthy](./client.md#function-verifytruthy)
+See also: [Chain](./client.md#type-chain), [KeyPairAddress](./setup.md#interface-keypairaddress), [Monitor](./monitor.md#class-monitor), [PrivilegedKeyManager](./client.md#class-privilegedkeymanager), [ScriptTemplateUnlock](./client.md#interface-scripttemplateunlock), [Services](./services.md#class-services), [SetupEnv](./setup.md#interface-setupenv), [SetupWallet](./setup.md#interface-setupwallet), [SetupWalletArgs](./setup.md#interface-setupwalletargs), [SetupWalletClient](./setup.md#interface-setupwalletclient), [SetupWalletClientArgs](./setup.md#interface-setupwalletclientargs), [SetupWalletKnex](./setup.md#interface-setupwalletknex), [SetupWalletKnexArgs](./setup.md#interface-setupwalletknexargs), [SetupWalletMySQLArgs](./setup.md#interface-setupwalletmysqlargs), [SetupWalletSQLiteArgs](./setup.md#interface-setupwalletsqliteargs), [StorageClient](./storage.md#class-storageclient), [StorageKnex](./storage.md#class-storageknex), [WERR_INVALID_OPERATION](./client.md#class-werr_invalid_operation), [Wallet](./client.md#class-wallet), [WalletStorageManager](./storage.md#class-walletstoragemanager), [createAction](./storage.md#function-createaction), [fundWalletFromP2PKHOutpoints](./client.md#function-fundwalletfromp2pkhoutpoints), [usePostgresInt8Numbers](./storage.md#function-usepostgresint8numbers), [verifyTruthy](./client.md#function-verifytruthy)
+
+###### Method createPostgresKnex
+
+Creates a knex for a Postgres `StorageKnex`. int8 values (bigint columns,
+counts) are returned as numbers, as with mysql2 and better-sqlite3, using a
+per-connection parser; see `usePostgresInt8Numbers`.
+
+```ts
+static createPostgresKnex(connection: string, database?: string): Knex {
+    const c: Knex.PgConnectionConfig = JSON.parse(connection);
+    if (database) {
+        c.database = database;
+    }
+    const config: Knex.Config = {
+        client: "pg",
+        connection: c,
+        pool: { min: 0, max: 7, idleTimeoutMillis: 15000 }
+    };
+    const knex = makeKnex(config);
+    usePostgresInt8Numbers(knex);
+    return knex;
+}
+```
+See also: [usePostgresInt8Numbers](./storage.md#function-usepostgresint8numbers)
+
+Argument Details
+
++ **connection**
+  + JSON node-postgres connection config
++ **database**
+  + optional database name overriding `connection.database`
 
 ###### Method createStorageKnex
 
@@ -838,16 +933,15 @@ static async createWallet(args: SetupWalletArgs): Promise<SetupWallet> {
     const services = new Services(serviceOptions);
     const monopts = Monitor.createDefaultWalletMonitorOptions(chain, storage, services, undefined, "default");
     const monitor = new Monitor(monopts);
-    const privilegedKeyManager = args.privilegedKeyGetter
-        ? new PrivilegedKeyManager(args.privilegedKeyGetter)
-        : undefined;
+    const privilegedKeyManager = args.privilegedKeyGetter != null ? new PrivilegedKeyManager(args.privilegedKeyGetter) : undefined;
     const wallet = new Wallet({
         chain,
         keyDeriver,
         storage,
         services,
         monitor,
-        privilegedKeyManager
+        privilegedKeyManager,
+        scriptVerifier: args.scriptVerifier
     });
     const r: SetupWallet = {
         rootKey,
@@ -874,6 +968,7 @@ static async createWalletClientNoEnv(args: {
     rootKeyHex: string;
     storageUrl?: string;
     privilegedKeyGetter?: () => Promise<PrivateKey>;
+    scriptVerifier?: SpendVerifierInterface;
 }): Promise<Wallet> 
 ```
 See also: [Chain](./client.md#type-chain), [Wallet](./client.md#class-wallet)
@@ -898,7 +993,7 @@ static async createWalletKnex(args: SetupWalletKnexArgs): Promise<SetupWalletKne
     const wo = await Setup.createWallet(args);
     const activeStorage = await Setup.createStorageKnex(args);
     await wo.storage.addWalletStorageProvider(activeStorage);
-    const { user, isNew } = await activeStorage.findOrInsertUser(wo.identityKey);
+    const { user } = await activeStorage.findOrInsertUser(wo.identityKey);
     const userId = user.userId;
     const r: SetupWalletKnex = {
         ...wo,
@@ -925,6 +1020,8 @@ For MySQL, a schema corresponding to databaseName must exist with full access pe
 
 Reads a .env file of the format created by `makeEnv`.
 
+Returns the generated text without writing credentials to stdout; the
+caller must explicitly choose a protected destination.
 Returns values for designated `chain`.
 
 Access private keys through the `devKeys` object: `devKeys[identityKey]`
@@ -996,7 +1093,6 @@ DEV_KEYS = '{
     "${mainIdentityKey2}": "${mainPrivKey2.toString()}"
 }'
 `;
-    console.log(log);
     return log;
 }
 ```
@@ -1038,16 +1134,15 @@ export abstract class SetupClient {
         const services = new Services(serviceOptions);
         const monopts = Monitor.createDefaultWalletMonitorOptions(chain, storage, services, undefined, "default");
         const monitor = new Monitor(monopts);
-        const privilegedKeyManager = args.privilegedKeyGetter
-            ? new PrivilegedKeyManager(args.privilegedKeyGetter)
-            : undefined;
+        const privilegedKeyManager = args.privilegedKeyGetter != null ? new PrivilegedKeyManager(args.privilegedKeyGetter) : undefined;
         const wallet = new Wallet({
             chain,
             keyDeriver,
             storage,
             services,
             monitor,
-            privilegedKeyManager
+            privilegedKeyManager,
+            scriptVerifier: args.scriptVerifier
         });
         const r: SetupWallet = {
             rootKey,
@@ -1066,6 +1161,7 @@ export abstract class SetupClient {
         rootKeyHex: string;
         storageUrl?: string;
         privilegedKeyGetter?: () => Promise<PrivateKey>;
+        scriptVerifier?: SpendVerifierInterface;
     }): Promise<Wallet> 
     static async createWalletClient(args: SetupClientWalletClientArgs): Promise<SetupWalletClient> {
         const wo = await SetupClient.createWallet(args);
@@ -1098,13 +1194,13 @@ export abstract class SetupClient {
         const unlock = p2pkh.unlock(priv, "all", false, satoshis, lock);
         return unlock;
     }
-    static createP2PKHOutputs(outputs: {
+    static createP2PKHOutputs(outputs: Array<{
         address: string;
         satoshis: number;
         outputDescription?: string;
         basket?: string;
         tags?: string[];
-    }[]): CreateActionOutput[] {
+    }>): CreateActionOutput[] {
         const os: CreateActionOutput[] = [];
         const count = outputs.length;
         for (let i = 0; i < count; i++) {
@@ -1119,19 +1215,19 @@ export abstract class SetupClient {
         }
         return os;
     }
-    static async createP2PKHOutputsAction(wallet: WalletInterface, outputs: {
+    static async createP2PKHOutputsAction(wallet: WalletInterface, outputs: Array<{
         address: string;
         satoshis: number;
         outputDescription?: string;
         basket?: string;
         tags?: string[];
-    }[], options?: CreateActionOptions): Promise<{
+    }>, options?: CreateActionOptions): Promise<{
         cr: CreateActionResult;
         outpoints: string[] | undefined;
     }> {
         const os = SetupClient.createP2PKHOutputs(outputs);
         const createArgs: CreateActionArgs = {
-            description: `createP2PKHOutputs`,
+            description: "createP2PKHOutputs",
             outputs: os,
             options: {
                 ...options,
@@ -1145,19 +1241,19 @@ export abstract class SetupClient {
         }
         return { cr, outpoints };
     }
-    static async fundWalletFromP2PKHOutpoints(wallet: WalletInterface, outpoints: string[], p2pkhKey: KeyPairAddress, inputBEEF?: BEEF): Promise<{
+    static async fundWalletFromP2PKHOutpoints(wallet: WalletInterface, outpoints: string[], p2pkhKey: KeyPairAddress, inputBEEF?: BEEF): Promise<Array<{
         outpoint: string;
         txid?: string;
         success: boolean;
         error?: string;
-    }[]> {
-        return _fundWalletFromP2PKHOutpoints(wallet, outpoints, p2pkhKey, SetupClient.getUnlockP2PKH.bind(SetupClient), inputBEEF);
+    }>> {
+        return await _fundWalletFromP2PKHOutpoints(wallet, outpoints, p2pkhKey, SetupClient.getUnlockP2PKH.bind(SetupClient), inputBEEF);
     }
     static async createWalletIdb(args: SetupWalletIdbArgs): Promise<SetupWalletIdb> {
         const wo = await SetupClient.createWallet(args);
         const activeStorage = await SetupClient.createStorageIdb(args);
         await wo.storage.addWalletStorageProvider(activeStorage);
-        const { user, isNew } = await activeStorage.findOrInsertUser(wo.identityKey);
+        const { user } = await activeStorage.findOrInsertUser(wo.identityKey);
         const userId = user.userId;
         const r: SetupWalletIdb = {
             ...wo,
@@ -1204,16 +1300,15 @@ static async createWallet(args: SetupClientWalletArgs): Promise<SetupWallet> {
     const services = new Services(serviceOptions);
     const monopts = Monitor.createDefaultWalletMonitorOptions(chain, storage, services, undefined, "default");
     const monitor = new Monitor(monopts);
-    const privilegedKeyManager = args.privilegedKeyGetter
-        ? new PrivilegedKeyManager(args.privilegedKeyGetter)
-        : undefined;
+    const privilegedKeyManager = args.privilegedKeyGetter != null ? new PrivilegedKeyManager(args.privilegedKeyGetter) : undefined;
     const wallet = new Wallet({
         chain,
         keyDeriver,
         storage,
         services,
         monitor,
-        privilegedKeyManager
+        privilegedKeyManager,
+        scriptVerifier: args.scriptVerifier
     });
     const r: SetupWallet = {
         rootKey,
@@ -1240,6 +1335,7 @@ static async createWalletClientNoEnv(args: {
     rootKeyHex: string;
     storageUrl?: string;
     privilegedKeyGetter?: () => Promise<PrivateKey>;
+    scriptVerifier?: SpendVerifierInterface;
 }): Promise<Wallet> 
 ```
 See also: [Chain](./client.md#type-chain), [Wallet](./client.md#class-wallet)
@@ -1264,7 +1360,7 @@ static async createWalletIdb(args: SetupWalletIdbArgs): Promise<SetupWalletIdb>
     const wo = await SetupClient.createWallet(args);
     const activeStorage = await SetupClient.createStorageIdb(args);
     await wo.storage.addWalletStorageProvider(activeStorage);
-    const { user, isNew } = await activeStorage.findOrInsertUser(wo.identityKey);
+    const { user } = await activeStorage.findOrInsertUser(wo.identityKey);
     const userId = user.userId;
     const r: SetupWalletIdb = {
         ...wo,