@bsv/wallet-toolbox 1.3.3 → 1.3.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bsv/wallet-toolbox",
-  "version": "1.3.3",
+  "version": "1.3.4",
   "description": "BRC100 conforming wallet, wallet storage and wallet signer components",
   "main": "./out/src/index.js",
   "types": "./out/src/index.d.ts",
@@ -34,6 +34,7 @@
     "@bsv/payment-express-middleware": "^1.0.6",
     "@bsv/sdk": "^1.4.20",
     "express": "^4.21.2",
+    "idb": "^8.0.2",
     "knex": "^3.1.0",
     "mysql2": "^3.12.0",
     "sqlite3": "^5.1.7"
@@ -46,6 +47,7 @@
     "@types/node": "^20.8.2",
     "chalk": "^4.1.2",
     "dotenv": "^16.4.7",
+    "fake-indexeddb": "^6.0.0",
     "fs-extra": "^11.2.0",
     "jest": "^29.7.0",
     "jest-diff": "^29.7.0",

package/src/Setup.ts

@@ -1,3 +1,4 @@
+import { KeyPairAddress, SetupWallet, SetupWalletClient } from './SetupWallet'
 import {
   BEEF,
   CreateActionArgs,
@@ -513,15 +514,6 @@ export interface SetupWalletKnex extends SetupWallet {
   wallet: Wallet
 }
 
-/**
- * A private key and associated public key and address.
- */
-export interface KeyPairAddress {
-  privateKey: PrivateKey
-  publicKey: PublicKey
-  address: string
-}
-
 /**
  * `SetupEnv` provides a starting point for managing secrets that
  * must not appear in source code.
@@ -561,56 +553,6 @@ export interface SetupEnv {
   mySQLConnection: string
 }
 
-/**
- * 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`.
@@ -623,15 +565,3 @@ export interface SetupWalletClientArgs extends SetupWalletArgs {
    */
   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/SetupClient.ts

@@ -0,0 +1,312 @@
+import {
+  BEEF,
+  CreateActionArgs,
+  CreateActionOptions,
+  CreateActionOutput,
+  CreateActionResult,
+  KeyDeriver,
+  LockingScript,
+  P2PKH,
+  PrivateKey,
+  PublicKey,
+  WalletInterface
+} from '@bsv/sdk'
+import { Monitor, randomBytesHex, sdk, Services, StorageClient, Wallet, WalletStorageManager } from './index.client'
+import { KeyPairAddress, SetupClientWalletArgs, SetupWallet, SetupWalletClient } from './SetupWallet'
+import { StorageIdb } from './storage/StorageIdb'
+
+/**
+ * The 'Setup` class provides static setup functions to construct BRC-100 compatible
+ * wallets in a variety of configurations.
+ *
+ * It serves as a starting point for experimentation and customization.
+ */
+export abstract class SetupClient {
+  /**
+   * Create a `Wallet`. Storage can optionally be provided or configured later.
+   *
+   * The following components are configured: KeyDeriver, WalletStorageManager, WalletService, WalletStorage.
+   * Optionally, PrivilegedKeyManager is also configured.
+   *
+   * @publicbody
+   */
+  static async createWallet(args: SetupClientWalletArgs): Promise<SetupWallet> {
+    const chain = args.chain
+    const rootKey = PrivateKey.fromHex(args.rootKeyHex)
+    const identityKey = rootKey.toPublicKey().toString()
+    const keyDeriver = new KeyDeriver(rootKey)
+    const storage = new WalletStorageManager(identityKey, args.active, args.backups)
+    if (storage.canMakeAvailable()) await storage.makeAvailable()
+    const serviceOptions = Services.createDefaultOptions(chain)
+    serviceOptions.taalApiKey = args.taalApiKey
+    const services = new Services(serviceOptions)
+    const monopts = Monitor.createDefaultWalletMonitorOptions(chain, storage, services)
+    const monitor = new Monitor(monopts)
+    monitor.addDefaultTasks()
+    const privilegedKeyManager = args.privilegedKeyGetter
+      ? new sdk.PrivilegedKeyManager(args.privilegedKeyGetter)
+      : undefined
+    const wallet = new Wallet({
+      chain,
+      keyDeriver,
+      storage,
+      services,
+      monitor,
+      privilegedKeyManager
+    })
+    const r: SetupWallet = {
+      rootKey,
+      identityKey,
+      keyDeriver,
+      chain,
+      storage,
+      services,
+      monitor,
+      wallet
+    }
+    return r
+  }
+
+  /**
+   * Setup a new `Wallet` without requiring a .env file.
+   *
+   * @param args.chain - 'main' or 'test'
+   * @param args.rootKeyHex  - Root private key for wallet's key deriver.
+   * @param args.storageUrl - Optional. `StorageClient` and `chain` compatible endpoint URL.
+   * @param args.privilegedKeyGetter - Optional. Method that will return the privileged `PrivateKey`, on demand.
+   */
+  static async createWalletClientNoEnv(args: {
+    chain: sdk.Chain
+    rootKeyHex: string
+    storageUrl?: string
+    privilegedKeyGetter?: () => Promise<PrivateKey>
+  }): Promise<Wallet> {
+    const chain = args.chain
+    const endpointUrl = args.storageUrl || `https://${args.chain !== 'main' ? 'staging-' : ''}storage.babbage.systems`
+    const rootKey = PrivateKey.fromHex(args.rootKeyHex)
+    const keyDeriver = new KeyDeriver(rootKey)
+    const storage = new WalletStorageManager(keyDeriver.identityKey)
+    const services = new Services(chain)
+    const privilegedKeyManager = args.privilegedKeyGetter
+      ? new sdk.PrivilegedKeyManager(args.privilegedKeyGetter)
+      : undefined
+    const wallet = new Wallet({
+      chain,
+      keyDeriver,
+      storage,
+      services,
+      privilegedKeyManager
+    })
+    const client = new StorageClient(wallet, endpointUrl)
+    await storage.addWalletStorageProvider(client)
+    await storage.makeAvailable()
+    return wallet
+  }
+
+  /**
+   * @publicbody
+   */
+  static async createWalletClient(args: SetupClientWalletClientArgs): Promise<SetupWalletClient> {
+    const wo = await SetupClient.createWallet(args)
+
+    const endpointUrl = args.endpointUrl || `https://${args.chain !== 'main' ? 'staging-' : ''}storage.babbage.systems`
+
+    const client = new StorageClient(wo.wallet, endpointUrl)
+    await wo.storage.addWalletStorageProvider(client)
+    await wo.storage.makeAvailable()
+    return {
+      ...wo,
+      endpointUrl
+    }
+  }
+
+  /**
+   * @publicbody
+   */
+  static getKeyPair(priv?: string | PrivateKey): KeyPairAddress {
+    if (priv === undefined) priv = PrivateKey.fromRandom()
+    else if (typeof priv === 'string') priv = new PrivateKey(priv, 'hex')
+
+    const pub = PublicKey.fromPrivateKey(priv)
+    const address = pub.toAddress()
+    return { privateKey: priv, publicKey: pub, address }
+  }
+
+  /**
+   * @publicbody
+   */
+  static getLockP2PKH(address: string): LockingScript {
+    const p2pkh = new P2PKH()
+    const lock = p2pkh.lock(address)
+    return lock
+  }
+
+  /**
+   * @publicbody
+   */
+  static getUnlockP2PKH(priv: PrivateKey, satoshis: number): sdk.ScriptTemplateUnlock {
+    const p2pkh = new P2PKH()
+    const lock = SetupClient.getLockP2PKH(SetupClient.getKeyPair(priv).address)
+    // Prepare to pay with SIGHASH_ALL and without ANYONE_CAN_PAY.
+    // In otherwords:
+    // - all outputs must remain in the current order, amount and locking scripts.
+    // - all inputs must remain from the current outpoints and sequence numbers.
+    // (unlock scripts are never signed)
+    const unlock = p2pkh.unlock(priv, 'all', false, satoshis, lock)
+    return unlock
+  }
+
+  /**
+   * @publicbody
+   */
+  static createP2PKHOutputs(
+    outputs: {
+      address: string
+      satoshis: number
+      outputDescription?: string
+      basket?: string
+      tags?: string[]
+    }[]
+  ): CreateActionOutput[] {
+    const os: CreateActionOutput[] = []
+    const count = outputs.length
+    for (let i = 0; i < count; i++) {
+      const o = outputs[i]
+      os.push({
+        basket: o.basket,
+        tags: o.tags,
+        satoshis: o.satoshis,
+        lockingScript: SetupClient.getLockP2PKH(o.address).toHex(),
+        outputDescription: o.outputDescription || `p2pkh ${i}`
+      })
+    }
+    return os
+  }
+
+  /**
+   * @publicbody
+   */
+  static async createP2PKHOutputsAction(
+    wallet: WalletInterface,
+    outputs: {
+      address: string
+      satoshis: number
+      outputDescription?: string
+      basket?: string
+      tags?: string[]
+    }[],
+    options?: CreateActionOptions
+  ): Promise<{
+    cr: CreateActionResult
+    outpoints: string[] | undefined
+  }> {
+    const os = SetupClient.createP2PKHOutputs(outputs)
+
+    const createArgs: CreateActionArgs = {
+      description: `createP2PKHOutputs`,
+      outputs: os,
+      options: {
+        ...options,
+        // Don't randomize so we can simplify outpoint creation
+        randomizeOutputs: false
+      }
+    }
+
+    const cr = await wallet.createAction(createArgs)
+
+    let outpoints: string[] | undefined
+
+    if (cr.txid) {
+      outpoints = os.map((o, i) => `${cr.txid}.${i}`)
+    }
+
+    return { cr, outpoints }
+  }
+
+  /**
+   * @publicbody
+   */
+  static async fundWalletFromP2PKHOutpoints(
+    wallet: WalletInterface,
+    outpoints: string[],
+    p2pkhKey: KeyPairAddress,
+    inputBEEF?: BEEF
+  ) {
+    // TODO
+  }
+
+  /**
+   * Adds `indexedDB` based storage to a `Wallet` configured by `SetupClient.createWalletOnly`
+   *
+   * @param args.databaseName Name for this storage. For MySQL, the schema name within the MySQL instance.
+   * @param args.chain Which chain this wallet is on: 'main' or 'test'. Defaults to 'test'.
+   * @param args.rootKeyHex
+   *
+   * @publicbody
+   */
+  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 userId = user.userId
+    const r: SetupWalletIdb = {
+      ...wo,
+      activeStorage,
+      userId
+    }
+    return r
+  }
+
+  /**
+   * @returns {StorageIdb} - `Knex` based storage provider for a wallet. May be used for either active storage or backup storage.
+   */
+  static async createStorageIdb(args: SetupWalletIdbArgs): Promise<StorageIdb> {
+    const storage = new StorageIdb({
+      chain: args.chain,
+      commissionSatoshis: 0,
+      commissionPubKeyHex: undefined,
+      feeModel: { model: 'sat/kb', value: 1 }
+    })
+    await storage.migrate(args.databaseName, randomBytesHex(33))
+    await storage.makeAvailable()
+    return storage
+  }
+}
+
+/**
+ *
+ */
+export interface SetupWalletIdbArgs extends SetupClientWalletArgs {
+  databaseName: string
+}
+
+/**
+ *
+ */
+export interface SetupWalletIdb extends SetupWallet {
+  activeStorage: StorageIdb
+  userId: number
+
+  rootKey: PrivateKey
+  identityKey: string
+  keyDeriver: KeyDeriver
+  chain: sdk.Chain
+  storage: WalletStorageManager
+  services: Services
+  monitor: Monitor
+  wallet: Wallet
+}
+
+/**
+ * Extension `SetupWalletClientArgs` of `SetupWalletArgs` is used by `createWalletClient`
+ * to construct a `SetupWalletClient`.
+ */
+export interface SetupClientWalletClientArgs extends SetupClientWalletArgs {
+  /**
+   * 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
+}

package/src/SetupWallet.ts

@@ -0,0 +1,105 @@
+import { PrivateKey, KeyDeriver, PublicKey } from '@bsv/sdk'
+import { WalletStorageManager, Monitor, sdk } from './index.client'
+import { Services } from './services'
+import { Wallet } from './Wallet'
+
+/**
+ * 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
+} /**
+ * A private key and associated public key and address.
+ */
+
+export interface KeyPairAddress {
+  privateKey: PrivateKey
+  publicKey: PublicKey
+  address: string
+}
+/**
+ * Arguments used by `createWallet` to construct a `SetupWallet`.
+ *
+ * Extension `SetupWalletClientArgs` used by `createWalletClient` to construct a `SetupWalletClient`.
+ *
+ * Extension `SetupWalletIdbArgs` used by `createWalletIdb` to construct a `SetupWalletIdb`.
+ */
+
+export interface SetupClientWalletArgs {
+  chain: sdk.Chain
+  /**
+   * The non-privileged private key used to initialize the `KeyDeriver` and determine the `identityKey`.
+   */
+  rootKeyHex: string
+  /**
+   * Optional. The privileged private key getter used to initialize the `PrivilegedKeyManager`.
+   * Defaults to undefined.
+   */
+  privilegedKeyGetter?: () => Promise<PrivateKey>
+  /**
+   * 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[]
+
+  taalApiKey?: 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/index.all.ts

@@ -2,6 +2,8 @@ export * as sdk from './sdk/index'
 export * from './utility/index.all'
 export * from './Wallet'
 export * from './Setup'
+export * from './SetupClient'
+export * from './SetupWallet'
 export * from './signer/WalletSigner'
 export * from './storage/index.all'
 export * from './services/Services'

package/src/index.client.ts

@@ -13,3 +13,4 @@ export * from './sdk/PrivilegedKeyManager'
 export * from './SimpleWalletManager'
 export * from './storage/index.client'
 export * from './Wallet'
+export * from './monitor/Monitor'

package/src/monitor/Monitor.ts

@@ -16,6 +16,7 @@ import { TaskNewHeader } from './tasks/TaskNewHeader'
 
 import { TaskSendWaiting } from './tasks/TaskSendWaiting'
 import { TaskCheckNoSends } from './tasks/TaskCheckNoSends'
+import { TaskUnFail } from './tasks/TaskUnFail'
 
 export type MonitorStorage = WalletStorageManager
 
@@ -114,6 +115,7 @@ export class Monitor {
     this._otherTasks.push(new TaskSendWaiting(this))
     this._otherTasks.push(new TaskCheckForProofs(this))
     this._otherTasks.push(new TaskCheckNoSends(this))
+    this._otherTasks.push(new TaskUnFail(this))
 
     this._otherTasks.push(new TaskFailAbandoned(this))
 
@@ -130,6 +132,7 @@ export class Monitor {
     this._tasks.push(new TaskCheckForProofs(this, 2 * this.oneHour)) // Every two hours if no block found
     this._tasks.push(new TaskCheckNoSends(this))
     this._tasks.push(new TaskFailAbandoned(this, 8 * this.oneMinute))
+    this._tasks.push(new TaskUnFail(this))
     // No purging until invalid transactions are really invalid...
     //this._tasks.push(new TaskPurge(this, this.defaultPurgeParams, 6 * this.oneHour))
     this._tasks.push(new TaskReviewStatus(this))
@@ -146,6 +149,7 @@ export class Monitor {
     this._tasks.push(new TaskCheckForProofs(this, 2 * this.oneHour)) // Every two hours if no block found
     this._tasks.push(new TaskCheckNoSends(this))
     this._tasks.push(new TaskFailAbandoned(this, 8 * this.oneMinute))
+    this._tasks.push(new TaskUnFail(this))
     // No purging until invalid transactions are really invalid...
     //this._tasks.push(new TaskPurge(this, this.defaultPurgeParams, 6 * this.oneHour))
     this._tasks.push(new TaskReviewStatus(this))

package/src/monitor/MonitorDaemon.ts

@@ -118,7 +118,6 @@ export class MonitorDaemon {
 
     if (a.monitor._tasks.length === 0) {
       a.monitor.addMultiUserTasks()
-      a.monitor.addTask(new TaskUnFail(a.monitor))
     }
   }
 

package/src/monitor/tasks/TaskUnFail.ts

@@ -1,9 +1,9 @@
 import { Transaction, Utils } from '@bsv/sdk'
 import { Monitor } from '../Monitor'
 import { WalletMonitorTask } from './WalletMonitorTask'
-import { StorageKnex } from '../../storage/StorageKnex'
 import { TableProvenTxReq } from '../../storage/schema/tables'
 import { EntityProvenTxReq } from '../../storage/schema/entities'
+import { StorageProvider } from '../../index.client'
 
 /**
  * Setting provenTxReq status to 'unfail' when 'invalid' will attempt to find a merklePath, and if successful:
@@ -103,7 +103,7 @@ export class TaskUnFail extends WalletMonitorTask {
     for (const id of txIds) {
       const bsvtx = Transaction.fromBinary(req.rawTx)
       await this.storage.runAsStorageProvider(async sp => {
-        const spk = sp as StorageKnex
+        const spk = sp as StorageProvider
         const tx = await sp.findTransactionById(id, undefined, true)
         if (!tx) {
           log += ' '.repeat(indent) + `transaction ${id} was not found\n`
@@ -134,8 +134,7 @@ export class TaskUnFail extends WalletMonitorTask {
           if (!o.lockingScript) {
             log += ' '.repeat(indent + 2) + `output ${o.outputId} does not have a valid locking script\n`
           } else {
-            const or = await services.getUtxoStatus(Utils.toHex(o.lockingScript!))
-            const isUtxo = or.isUtxo === true
+            const isUtxo = await services.isUtxo(o)
             if (isUtxo !== o.spendable) {
               log += ' '.repeat(indent + 2) + `output ${o.outputId} set to ${isUtxo ? 'spendable' : 'spent'}\n`
               await sp.updateOutput(o.outputId, { spendable: isUtxo })

package/src/sdk/WalletServices.interfaces.ts

@@ -2,8 +2,7 @@ import { ArcConfig, Beef, Transaction as BsvTransaction, ChainTracker, MerklePat
 import { ChaintracksServiceClient } from '../services/chaintracker'
 import { Chain, ReqHistoryNote } from './types'
 import { WalletError } from './WalletError'
-import { TableOutput } from '../storage/schema/tables/Output'
-
+import { TableOutput } from '../storage/schema/tables/TableOutput'
 /**
  * Defines standard interfaces to access functionality implemented by external transaction processing services.
  */

package/src/services/__tests/postBeef.test.ts

@@ -29,7 +29,7 @@ function createServices(chain: sdk.Chain): Services {
   }
   if (env.whatsonchainApiKey) options.whatsOnChainApiKey = env.whatsonchainApiKey
   if (env.bitailsApiKey) options.bitailsApiKey = env.bitailsApiKey
-  console.log(`
+  logger(`
 API Keys:
 TAAL ${options.taalApiKey!.slice(0, 20)}
 WHATSONCHAIN ${options.whatsOnChainApiKey!.slice(0, 20)}