@bsv/wallet-toolbox 1.1.5 → 1.1.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bsv/wallet-toolbox",
-  "version": "1.1.5",
+  "version": "1.1.6",
   "description": "BRC100 conforming wallet, wallet storage and wallet signer components",
   "main": "./out/src/index.js",
   "types": "./out/src/index.d.ts",
@@ -57,7 +57,7 @@
     "standard": "^17.1.0",
     "ts-jest": "^29.0.5",
     "ts-node": "^10.9.1",
-    "ts2md": "^0.2.5",
+    "ts2md": "^0.2.6",
     "typescript": "^5.2.2"
   }
 }

package/src/Setup.ts

@@ -33,7 +33,7 @@ export abstract class Setup extends SetupClient {
    *
    * @publicbody
    */
-  static async createKnexWallet(
+  static async createWalletKnex(
     args: SetupWalletKnexArgs
   ): Promise<SetupWalletKnex> {
     const wo = await Setup.createWallet(args)
@@ -91,10 +91,10 @@ export abstract class Setup extends SetupClient {
   /**
    * @publicbody
    */
-  static async createMySQLWallet(
+  static async createWalletMySQL(
     args: SetupWalletMySQLArgs
   ): Promise<SetupWalletKnex> {
-    return await this.createKnexWallet({
+    return await this.createWalletKnex({
       ...args,
       knex: Setup.createMySQLKnex(args.env.mySQLConnection, args.databaseName)
     })
@@ -103,10 +103,10 @@ export abstract class Setup extends SetupClient {
   /**
    * @publicbody
    */
-  static async createSQLiteWallet(
+  static async createWalletSQLite(
     args: SetupWalletSQLiteArgs
   ): Promise<SetupWalletKnex> {
-    return await this.createKnexWallet({
+    return await this.createWalletKnex({
       ...args,
       knex: Setup.createSQLiteKnex(args.filePath)
     })

package/src/SetupClient.ts

@@ -132,12 +132,11 @@ export abstract class SetupClient {
    * @publicbody
    */
   static async createWallet(args: SetupWalletArgs): Promise<SetupWallet> {
-    args.chain ||= args.env.chain
+    const chain = args.env.chain
     args.rootKeyHex ||= args.env.devKeys[args.env.identityKey]
     const rootKey = PrivateKey.fromHex(args.rootKeyHex)
     const identityKey = rootKey.toPublicKey().toString()
     const keyDeriver = new KeyDeriver(rootKey)
-    const chain = args.chain
     const storage = new WalletStorageManager(
       identityKey,
       args.active,
@@ -146,7 +145,7 @@ export abstract class SetupClient {
     if (storage.stores.length > 0) await storage.makeAvailable()
     const serviceOptions = Services.createDefaultOptions(chain)
     serviceOptions.taalApiKey = args.env.taalApiKey
-    const services = new Services(args.chain)
+    const services = new Services(chain)
     const monopts = Monitor.createDefaultWalletMonitorOptions(
       chain,
       storage,
@@ -183,7 +182,7 @@ export abstract class SetupClient {
   /**
    * @publicBody
    */
-  static async createWalletWithStorageClient(
+  static async createWalletClient(
     args: SetupWalletClientArgs
   ): Promise<SetupWalletClient> {
     const wo = await SetupClient.createWallet(args)
@@ -333,54 +332,147 @@ export type KeyPairAddress = {
 }
 
 /**
+ * `SetupEnv` provides a starting point for managing secrets that
+ * must not appear in source code.
  *
+ * The `makeEnv` and `getEnv` functions of the `Setup` and `SetupClient` classes
+ * provide an easy way to create and import these secrets and related properties.
  */
 export interface SetupEnv {
+  /**
+   * The chan being accessed: 'main' for mainnet, 'test' for 'testnet'.
+   */
   chain: sdk.Chain
+  /**
+   * The user's primary identity key (public key).
+   */
   identityKey: string
+  /**
+   * A secondary identity key (public key), used to test exchanges with other users.
+   */
   identityKey2: string
+  /**
+   * A vaild TAAL API key for use by `Services`
+   */
   taalApiKey: string
+  /**
+   * A map of public keys (identity keys, hex strings) to private keys (hex strings).
+   */
   devKeys: Record<string, string>
+  /**
+   * A MySQL connection string including user and password properties.
+   * Must be valid to make use of MySQL `Setup` class support.
+   */
   mySQLConnection: string
 }
 
 /**
- * Arguments used to construct a `Wallet`
+ * Arguments used by `createWallet` to construct a `SetupWallet`.
+ *
+ * Extension `SetupWalletClientArgs` used by `createWalletClient` to construct a `SetupWalletClient`.
+ *
+ * Extension `SetupWalletKnexArgs` used by `createWalletKnex` to construct a `SetupWalletKnex`.
  *
- * @param env Configuration "secrets" typically obtained by `Setup.makeEnv` and `Setup.getEnv` functions.
- * @param chain Optional. Which chain this wallet is on: 'main' or 'test'.
- * Defaults to `env.chain`.
- * @param rootKeyHex Optional. The non-privileged private key used to initialize the `KeyDeriver` and determine the `identityKey`.
- * Defaults to `env.devKeys[env.identityKey]
- * @param privKeyHex Optional. The privileged private key used to initialize the `PrivilegedKeyManager`.
- * Defaults to undefined.
- * @param active. Optional. Active wallet storage. Can be added later.
- * @param backups. Optional. One or more storage providers managed as backup destinations. Can be added later.
+ * Extension `SetupWalletMySQLArgs` used by `createWalletMySQL` to construct a `SetupWalletKnex`.
+ *
+ * Extension `SetupWalletSQLiteArgs` used by `createWalletSQLite` to construct a `SetupWalletKnex`.
  */
 export interface SetupWalletArgs {
+  /**
+   * Configuration "secrets" typically obtained by `Setup.makeEnv` and `Setup.getEnv` functions.
+   */
   env: SetupEnv
-  chain?: sdk.Chain
+  /**
+   * Optional. The non-privileged private key used to initialize the `KeyDeriver` and determine the `identityKey`.
+   * Defaults to `env.devKeys[env.identityKey]
+   */
   rootKeyHex?: string
+  /**
+   * Optional. The privileged private key used to initialize the `PrivilegedKeyManager`.
+   * Defaults to undefined.
+   */
   privKeyHex?: string
+  /**
+   * Optional. Active wallet storage. Can be added later.
+   */
   active?: sdk.WalletStorageProvider
+  /**
+   * Optional. One or more storage providers managed as backup destinations. Can be added later.
+   */
   backups?: sdk.WalletStorageProvider[]
 }
 
+/**
+ * When creating a BRC-100 compatible `Wallet`, many components come into play.
+ *
+ * All of the `createWallet` functions in the `Setup` and `SetupClient` classes return
+ * an object with direct access to each component to facilitate experimentation, testing
+ * and customization.
+ */
 export interface SetupWallet {
+  /**
+   * The rootKey of the `KeyDeriver`. The private key from which other keys are derived.
+   */
   rootKey: PrivateKey
+  /**
+   * The pubilc key associated with the `rootKey` which also serves as the wallet's identity.
+   */
   identityKey: string
+  /**
+   * The `KeyDeriver` component used by the wallet for key derivation and cryptographic functions.
+   */
   keyDeriver: KeyDeriver
+  /**
+   * The chain ('main' or 'test') which the wallet accesses.
+   */
   chain: sdk.Chain
+  /**
+   * The `WalletStorageManager` that manages all the configured storage providers (active and backups)
+   * accessed by the wallet.
+   */
   storage: WalletStorageManager
+  /**
+   * The network `Services` component which provides the wallet with access to external services hosted
+   * on the public network.
+   */
   services: Services
+  /**
+   * The background task `Monitor` component available to the wallet to offload tasks
+   * that speed up wallet operations and maintain data integrity.
+   */
   monitor: Monitor
+  /**
+   * The actual BRC-100 `Wallet` to which all the other properties and components contribute.
+   *
+   * Note that internally, the wallet is itself linked to all these properties and components.
+   * They are included in this interface to facilitate access after wallet construction for
+   * experimentation, testing and customization. Any changes made to the configuration of these
+   * components after construction may disrupt the normal operation of the wallet.
+   */
   wallet: Wallet
 }
 
+/**
+ * Extension `SetupWalletClientArgs` of `SetupWalletArgs` is used by `createWalletClient`
+ * to construct a `SetupWalletClient`.
+ */
 export interface SetupWalletClientArgs extends SetupWalletArgs {
+  /**
+   * The endpoint URL of a service hosting the `StorageServer` JSON-RPC service to
+   * which a `StorageClient` instance should connect to function as
+   * the active storage provider of the newly created wallet.
+   */
   endpointUrl?: string
 }
 
+/**
+ * Extension `SetupWalletClient` of `SetupWallet` is returned by `createWalletClient`
+ */
 export interface SetupWalletClient extends SetupWallet {
+  /**
+   * The endpoint URL of the service hosting the `StorageServer` JSON-RPC service to
+   * which a `StorageClient` instance is connected to function as
+   * the active storage provider of the wallet.
+   */
   endpointUrl: string
 }

package/src/Wallet.ts

@@ -119,6 +119,11 @@ export class Wallet implements WalletInterface, ProtoWallet {
 
   pendingSignActions: Record<string, PendingSignAction>
 
+  /**
+   * For repeatability testing, set to an array of random numbers from [0..1).
+   */
+  randomVals?: number[] = undefined
+
   constructor(
     argsOrSigner: WalletArgs | WalletSigner,
     services?: sdk.WalletServices,
@@ -632,6 +637,10 @@ export class Wallet implements WalletInterface, ProtoWallet {
       args,
       sdk.validateCreateActionArgs
     )
+    if (this.randomVals && this.randomVals.length > 1) {
+      vargs.randomVals = [...this.randomVals]
+    }
+
     const r = await createAction(this, auth, vargs)
 
     if (r.signableTransaction) {

package/src/sdk/WalletError.ts

@@ -56,7 +56,6 @@ export class WalletError extends Error implements WalletErrorObject {
   /**
    * Recovers all public fields from WalletError derived error classes and relevant Error derived errors.
    *
-   * Critical client data fields are preserved across HTTP DojoExpress / DojoExpressClient encoding.
    */
   static fromUnknown(err: unknown): WalletError {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any

package/src/sdk/validationHelpers.ts

@@ -403,6 +403,7 @@ export interface ValidCreateActionArgs extends ValidProcessActionArgs {
   options: ValidCreateActionOptions
   // true if transaction creation completion will require a `signAction` call.
   isSignAction: boolean
+  randomVals?: number[]
 }
 
 export interface ValidSignActionArgs extends ValidProcessActionArgs {
@@ -428,7 +429,8 @@ export function validateCreateActionArgs(
     isDelayed: false,
     isNoSend: false,
     isNewTx: false,
-    isSignAction: false
+    isSignAction: false,
+    randomVals: undefined
   }
   vargs.isSendWith = vargs.options.sendWith.length > 0
   vargs.isNewTx = vargs.inputs.length > 0 || vargs.outputs.length > 0

package/src/storage/StorageProvider.ts

@@ -217,7 +217,7 @@ export abstract class StorageProvider
 
   /**
    * Given an array of transaction txids with current ProvenTxReq ready-to-share status,
-   * lookup their DojoProvenTxReqApi req records.
+   * lookup their ProvenTxReqApi req records.
    * For the txids with reqs and status still ready to send construct a single merged beef.
    *
    * @param txids
@@ -408,9 +408,6 @@ export abstract class StorageProvider
    *
    * For 'status' of 'failed', attempts to make outputs previously allocated as inputs to this transaction usable again.
    *
-   * @throws ERR_DOJO_COMPLETED_TX if current status is 'completed' and new status is not 'completed.
-   * @throws ERR_DOJO_PROVEN_TX if transaction has proof or provenTxId and new status is not 'completed'.
-   *
    * @param status
    * @param transactionId
    * @param userId

package/src/storage/methods/createAction.ts

@@ -7,7 +7,9 @@ import {
   PrivateKey,
   PubKeyHex,
   PublicKey,
-  Script
+  Random,
+  Script,
+  Utils
 } from '@bsv/sdk'
 import {
   asArray,
@@ -711,7 +713,7 @@ async function validateRequiredInputs(
 }
 
 async function validateNoSendChange(
-  dojo: StorageProvider,
+  storage: StorageProvider,
   userId: number,
   vargs: sdk.ValidCreateActionArgs,
   changeBasket: table.OutputBasket
@@ -725,7 +727,7 @@ async function validateNoSendChange(
   if (noSendChange && noSendChange.length > 0) {
     for (const op of noSendChange) {
       const output = verifyOneOrNone(
-        await dojo.findOutputs({
+        await storage.findOutputs({
           partial: { userId, txid: op.txid, vout: op.vout }
         })
       )
@@ -754,7 +756,7 @@ async function validateNoSendChange(
 }
 
 async function fundNewTransactionSdk(
-  dojo: StorageProvider,
+  storage: StorageProvider,
   userId: number,
   vargs: sdk.ValidCreateActionArgs,
   ctx: CreateTransactionSdkContext
@@ -781,7 +783,8 @@ async function fundNewTransactionSdk(
     changeLockingScriptLength: 25,
     changeUnlockingScriptLength: 107,
     targetNetCount:
-      ctx.changeBasket.numberOfDesiredUTXOs - ctx.availableChangeCount
+      ctx.changeBasket.numberOfDesiredUTXOs - ctx.availableChangeCount,
+    randomVals: vargs.randomVals
   }
 
   const noSendChange = [...ctx.noSendChangeIn]
@@ -796,7 +799,7 @@ async function fundNewTransactionSdk(
       const o = noSendChange.pop()!
       outputs[o.outputId!] = o
       // allocate the output in storage, noSendChange is by definition spendable false and part of noSpend transaction batch.
-      await dojo.updateOutput(o.outputId!, {
+      await storage.updateOutput(o.outputId!, {
         spendable: false,
         spentBy: ctx.transactionId
       })
@@ -810,7 +813,7 @@ async function fundNewTransactionSdk(
     }
 
     const basketId = ctx.changeBasket.basketId!
-    const o = await dojo.allocateChangeInput(
+    const o = await storage.allocateChangeInput(
       userId,
       basketId,
       targetSatoshis,
@@ -833,7 +836,7 @@ async function fundNewTransactionSdk(
       noSendChange.push(nsco)
       return
     }
-    await dojo.updateOutput(outputId, {
+    await storage.updateOutput(outputId, {
       spendable: true,
       spentBy: undefined
     })
@@ -845,8 +848,41 @@ async function fundNewTransactionSdk(
     releaseChangeInput
   )
 
+  const nextRandomVal = (): number => {
+    let val = 0
+    if (!vargs.randomVals || vargs.randomVals.length === 0) {
+      val = Math.random()
+    } else {
+      val = vargs.randomVals.shift() || 0
+      vargs.randomVals.push(val)
+    }
+    return val
+  }
+
+  /**
+   * @returns a random integer betweenn min and max, inclussive.
+   */
+  const rand = (min: number, max: number): number => {
+    if (max < min)
+      throw new sdk.WERR_INVALID_PARAMETER(
+        'max',
+        `less than min (${min}). max is (${max})`
+      )
+    return Math.floor(nextRandomVal() * (max - min + 1) + min)
+  }
+
+  const randomDerivation = (count: number): string => {
+    let val: number[] = []
+    if (!vargs.randomVals || vargs.randomVals.length === 0) {
+      val = Random(count)
+    } else {
+      for (let i = 0; i < count; i++) val.push(rand(0, 255))
+    }
+    return Utils.toBase64(val)
+  }
+
   // Generate a derivation prefix for the payment
-  const derivationPrefix = randomBytesBase64(16)
+  const derivationPrefix = randomDerivation(16)
 
   const r: {
     allocatedChange: table.Output[]
@@ -870,7 +906,7 @@ async function fundNewTransactionSdk(
           change: true,
           type: 'P2PKH',
           derivationPrefix,
-          derivationSuffix: randomBytesBase64(16),
+          derivationSuffix: randomDerivation(16),
           providedBy: 'storage',
           purpose: 'change',
           customInstructions: undefined,
@@ -910,7 +946,7 @@ function trimInputBeef(
 }
 
 async function mergeAllocatedChangeBeefs(
-  dojo: StorageProvider,
+  storage: StorageProvider,
   userId: number,
   vargs: sdk.ValidCreateActionArgs,
   allocatedChange: table.Output[],
@@ -931,7 +967,7 @@ async function mergeAllocatedChangeBeefs(
       !beef.findTxid(o.txid!) &&
       !vargs.options.knownTxids.find(txid => txid === o.txid)
     ) {
-      await dojo.getBeefForTransaction(o.txid!, options)
+      await storage.getBeefForTransaction(o.txid!, options)
     }
   }
   return trimInputBeef(beef, vargs)

package/src/storage/methods/generateChange.ts

@@ -331,7 +331,7 @@ export async function generateChangeSdk(
     return r
   } catch (eu: unknown) {
     const e = sdk.WalletError.fromUnknown(eu)
-    if (e.code === 'ERR_DOJO_NOT_SUFFICIENT_FUNDS') throw eu
+    if (e.code === 'WERR_INSUFFICIENT_FUNDS') throw eu
 
     // Capture the params in cloud run log which has a 100k text length limit per line.
     // logGenerateChangeSdkParams(params, eu)

package/src/storage/schema/tables/ProvenTxReq.ts

@@ -21,12 +21,12 @@ export interface ProvenTxReq extends ProvenTxReqDynamics {
   batch?: string
   /**
    * JSON string of processing history.
-   * Parses to `DojoProvenTxReqHistoryApi`.
+   * Parses to `ProvenTxReqHistoryApi`.
    */
   history: string
   /**
    * JSON string of data to drive notifications when this request completes.
-   * Parses to `DojoProvenTxReqNotifyApi`.
+   * Parses to `ProvenTxReqNotifyApi`.
    */
   notify: string
   rawTx: number[]
@@ -54,12 +54,12 @@ export interface ProvenTxReqDynamics extends sdk.EntityTimeStamp {
   batch?: string
   /**
    * JSON string of processing history.
-   * Parses to `DojoProvenTxReqHistoryApi`.
+   * Parses to `ProvenTxReqHistoryApi`.
    */
   history: string
   /**
    * JSON string of data to drive notifications when this request completes.
-   * Parses to `DojoProvenTxReqNotifyApi`.
+   * Parses to `ProvenTxReqNotifyApi`.
    */
   notify: string
 }

package/test/examples/README.man.test.ts

@@ -11,7 +11,7 @@ describe('examples README tests', () => {
   it('1 internalize wallet payment', async () => {
     const env = Setup.getEnv('test')
 
-    const { wallet } = await Setup.createSQLiteWallet({
+    const { wallet } = await Setup.createWalletSQLite({
       env,
       filePath: './myTestWallet.sqlite',
       databaseName: 'myTestWallet'