@bsv/wallet-toolbox 1.1.3 → 1.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bsv/wallet-toolbox",
-  "version": "1.1.3",
+  "version": "1.1.5",
   "description": "BRC100 conforming wallet, wallet storage and wallet signer components",
   "main": "./out/src/index.js",
   "types": "./out/src/index.d.ts",

package/src/Setup.ts

@@ -1,61 +1,42 @@
-import {
-  Beef,
-  CreateActionArgs,
-  CreateActionOutput,
-  CreateActionResult,
-  KeyDeriver,
-  P2PKH,
-  PrivateKey,
-  PublicKey,
-  SignActionArgs,
-  SignActionResult,
-  WalletInterface
-} from '@bsv/sdk'
+import { KeyDeriver, PrivateKey } from '@bsv/sdk'
 import {
   Monitor,
   sdk,
   Services,
   SetupClient,
-  StorageClient,
-  verifyTruthy,
   Wallet,
   WalletStorageManager
 } from './index.client'
-import { PrivilegedKeyManager } from './sdk'
 import { Knex, knex as makeKnex } from 'knex'
-import { SetupWalletOnly, StorageKnex } from './index.all'
+import { SetupWallet, SetupWalletArgs, StorageKnex } from './index.all'
 
 /**
- * This class provides static setup functions to construct BRC-100 compatible
+ * 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.
  *
+ * `SetupClient` references only browser compatible code including storage via `StorageClient`.
+ * `Setup` extends `SetupClient` adding database storage via `Knex` and `StorageKnex`.
+ *
  */
 export abstract class Setup extends SetupClient {
   /**
    * Adds `Knex` based storage to a `Wallet` configured by `Setup.createWalletOnly`
    *
-   * @param args
-   * @returns
+   * @param args.knex `Knex` object configured for either MySQL or SQLite database access.
+   * Schema will be created and migrated as needed.
+   * For MySQL, a schema corresponding to databaseName must exist with full access permissions.
+   * @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 createKnexWallet(args: {
-    /**
-     * `Knex` object configured for either MySQL or SQLite database access.
-     * Schema will be created and migrated as needed.
-     * For MySQL, a schema corresponding to databaseName must exist with full access permissions.
-     */
-    knex: Knex<any, any[]>
-    databaseName: string
-    chain?: sdk.Chain
-    rootKeyHex?: string
-    privKeyHex?: string
-  }): Promise<SetupWallet> {
-    const wo = await Setup.createWalletOnly({
-      chain: args.chain,
-      rootKeyHex: args.rootKeyHex,
-      privKeyHex: args.privKeyHex
-    })
+  static async createKnexWallet(
+    args: SetupWalletKnexArgs
+  ): Promise<SetupWalletKnex> {
+    const wo = await Setup.createWallet(args)
     const activeStorage = new StorageKnex({
       chain: wo.chain,
       knex: args.knex,
@@ -68,7 +49,7 @@ export abstract class Setup extends SetupClient {
     await wo.storage.addWalletStorageProvider(activeStorage)
     const { user, isNew } = await activeStorage.findOrInsertUser(wo.identityKey)
     const userId = user.userId
-    const r: SetupWallet = {
+    const r: SetupWalletKnex = {
       ...wo,
       activeStorage,
       userId
@@ -76,6 +57,9 @@ export abstract class Setup extends SetupClient {
     return r
   }
 
+  /**
+   * @publicbody
+   */
   static createSQLiteKnex(filename: string): Knex {
     const config: Knex.Config = {
       client: 'sqlite3',
@@ -86,6 +70,9 @@ export abstract class Setup extends SetupClient {
     return knex
   }
 
+  /**
+   * @publicbody
+   */
   static createMySQLKnex(connection: string, database?: string): Knex {
     const c: Knex.MySql2ConnectionConfig = JSON.parse(connection)
     if (database) {
@@ -101,26 +88,24 @@ export abstract class Setup extends SetupClient {
     return knex
   }
 
-  static async createMySQLWallet(args: {
-    databaseName: string
-    chain?: sdk.Chain
-    rootKeyHex?: string
-    privKeyHex?: string
-  }): Promise<SetupWallet> {
-    const env = Setup.getEnv(args.chain || 'test')
+  /**
+   * @publicbody
+   */
+  static async createMySQLWallet(
+    args: SetupWalletMySQLArgs
+  ): Promise<SetupWalletKnex> {
     return await this.createKnexWallet({
       ...args,
-      knex: Setup.createMySQLKnex(env.mySQLConnection, args.databaseName)
+      knex: Setup.createMySQLKnex(args.env.mySQLConnection, args.databaseName)
     })
   }
 
-  static async createSQLiteWallet(args: {
-    filePath: string
-    databaseName: string
-    chain?: sdk.Chain
-    rootKeyHex?: string
-    privKeyHex?: string
-  }): Promise<SetupWallet> {
+  /**
+   * @publicbody
+   */
+  static async createSQLiteWallet(
+    args: SetupWalletSQLiteArgs
+  ): Promise<SetupWalletKnex> {
     return await this.createKnexWallet({
       ...args,
       knex: Setup.createSQLiteKnex(args.filePath)
@@ -128,7 +113,33 @@ export abstract class Setup extends SetupClient {
   }
 }
 
-export interface SetupWallet extends SetupWalletOnly {
+/**
+ *
+ */
+export interface SetupWalletKnexArgs extends SetupWalletArgs {
+  knex: Knex<any, any[]>
+  databaseName: string
+}
+
+/**
+ *
+ */
+export interface SetupWalletMySQLArgs extends SetupWalletArgs {
+  databaseName: string
+}
+
+/**
+ *
+ */
+export interface SetupWalletSQLiteArgs extends SetupWalletArgs {
+  filePath: string
+  databaseName: string
+}
+
+/**
+ *
+ */
+export interface SetupWalletKnex extends SetupWallet {
   activeStorage: StorageKnex
   userId: number
 

package/src/SetupClient.ts

@@ -1,6 +1,8 @@
 import {
+  BEEF,
   Beef,
   CreateActionArgs,
+  CreateActionOptions,
   CreateActionOutput,
   CreateActionResult,
   KeyDeriver,
@@ -9,6 +11,8 @@ import {
   PublicKey,
   SignActionArgs,
   SignActionResult,
+  Transaction,
+  UnlockingScript,
   WalletInterface
 } from '@bsv/sdk'
 import {
@@ -20,17 +24,29 @@ import {
   Wallet,
   WalletStorageManager
 } from './index.client'
-import { PrivilegedKeyManager } from './sdk'
 
 /**
- * This class provides static setup functions to construct BRC-100 compatible
+ * The `SetupClient` 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.
  *
+ * `SetupClient` references only browser compatible code including storage via `StorageClient`.
+ * `Setup` extends `SetupClient` adding database storage via `Knex` and `StorageKnex`.
+ *
  */
 export abstract class SetupClient {
-  static makeEnv(chain: sdk.Chain): void {
+  /**
+   * Creates content for .env file with some private keys, identity keys, sample API keys, and sample MySQL connection string.
+   *
+   * Two new, random private keys are generated each time, with their associated public identity keys.
+   *
+   * Loading secrets from a .env file is intended only for experimentation and getting started.
+   * Private keys should never be included directly in your source code.
+   *
+   * @publicBody
+   */
+  static makeEnv(): string {
     const testPrivKey1 = PrivateKey.fromRandom()
     const testIdentityKey1 = testPrivKey1.toPublicKey().toString()
     const testPrivKey2 = PrivateKey.fromRandom()
@@ -57,18 +73,24 @@ export abstract class SetupClient {
     MYSQL_CONNECTION='{"port":3306,"host":"127.0.0.1","user":"root","password":"<your_password>","database":"<your_database>", "timezone": "Z"}'
     `
     console.log(log)
+
+    return log
   }
 
-  static getEnv(chain: sdk.Chain) {
+  /**
+   * Reads a .env file of the format created by `makeEnv`.
+   *
+   * Returns values for designated `chain`.
+   *
+   * Access private keys through the `devKeys` object: `devKeys[identityKey]`
+   *
+   * @param chain Which chain to use: 'test' or 'main'
+   * @returns {SetupEnv} with configuration environment secrets used by `Setup` functions.
+   *
+   * @publicBody
+   */
+  static getEnv(chain: sdk.Chain): SetupEnv {
     // Identity keys of the lead maintainer of this repo...
-    const mainTaalApiKey = verifyTruthy(
-      process.env.MAIN_TAAL_API_KEY || '',
-      `.env value for 'mainTaalApiKey' is required.`
-    )
-    const testTaalApiKey = verifyTruthy(
-      process.env.TEST_TAAL_API_KEY || '',
-      `.env value for 'testTaalApiKey' is required.`
-    )
     const identityKey =
       chain === 'main'
         ? process.env.MY_MAIN_IDENTITY
@@ -79,137 +101,39 @@ export abstract class SetupClient {
         : process.env.MY_TEST_IDENTITY2
     const DEV_KEYS = process.env.DEV_KEYS || '{}'
     const mySQLConnection = process.env.MYSQL_CONNECTION || '{}'
+    const taalApiKey = verifyTruthy(
+      chain === 'main'
+        ? process.env.MAIN_TAAL_API_KEY
+        : process.env.TEST_TAAL_API_KEY,
+      `.env value for '${chain.toUpperCase()}_TAAL_API_KEY' is required.`
+    )
+
+    if (!identityKey || !identityKey2)
+      throw new sdk.WERR_INVALID_OPERATION(
+        '.env is not a valid SetupEnv configuration.'
+      )
 
     return {
       chain,
       identityKey,
       identityKey2,
-      mainTaalApiKey,
-      testTaalApiKey,
+      taalApiKey,
       devKeys: JSON.parse(DEV_KEYS) as Record<string, string>,
       mySQLConnection
     }
   }
 
-  static async createNoSendP2PKHOutpoint(
-    basket: string,
-    address: string,
-    satoshis: number,
-    noSendChange: string[] | undefined,
-    wallet: WalletInterface
-  ): Promise<{
-    noSendChange: string[]
-    txid: string
-    cr: CreateActionResult
-    sr: SignActionResult
-  }> {
-    return await SetupClient.createNoSendP2PKHOutpoints(
-      1,
-      basket,
-      address,
-      satoshis,
-      noSendChange,
-      wallet
-    )
-  }
-
-  static async createNoSendP2PKHOutpoints(
-    count: number,
-    basket: string,
-    address: string,
-    satoshis: number,
-    noSendChange: string[] | undefined,
-    wallet: WalletInterface
-  ): Promise<{
-    noSendChange: string[]
-    txid: string
-    cr: CreateActionResult
-    sr: SignActionResult
-  }> {
-    const outputs: CreateActionOutput[] = []
-    for (let i = 0; i < count; i++) {
-      outputs.push({
-        basket,
-        satoshis,
-        lockingScript: SetupClient.getLockP2PKH(address).toHex(),
-        outputDescription: `p2pkh ${i}`
-      })
-    }
-
-    const createArgs: CreateActionArgs = {
-      description: `to ${address}`,
-      outputs,
-      options: {
-        noSendChange,
-        randomizeOutputs: false,
-        signAndProcess: false,
-        noSend: true
-      }
-    }
-
-    const cr = await wallet.createAction(createArgs)
-    noSendChange = cr.noSendChange
-
-    const st = cr.signableTransaction!
-    // const tx = Transaction.fromAtomicBEEF(st.tx) // Transaction doesn't support V2 Beef yet.
-    const beef = Beef.fromBinary(st.tx)
-    const btx = beef.txs.slice(-1)[0]
-    const tx = beef.findAtomicTransaction(btx.txid)
-
-    // sign and complete
-    const signArgs: SignActionArgs = {
-      reference: st.reference,
-      spends: {},
-      options: {
-        returnTXIDOnly: true,
-        noSend: true
-      }
-    }
-
-    const sr = await wallet.signAction(signArgs)
-
-    let txid = sr.txid!
-    // Update the noSendChange txid to final signed value.
-    noSendChange = noSendChange!.map(op => `${txid}.${op.split('.')[1]}`)
-    return { noSendChange, txid, cr, sr }
-  }
-
-  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 }
-  }
-
-  static getLockP2PKH(address: string) {
-    const p2pkh = new P2PKH()
-    const lock = p2pkh.lock(address)
-    return lock
-  }
-
-  static getUnlockP2PKH(priv: PrivateKey, satoshis: number) {
-    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
-  }
-
-  static async createWalletOnly(args: {
-    chain?: sdk.Chain
-    rootKeyHex?: string
-    active?: sdk.WalletStorageProvider
-    backups?: sdk.WalletStorageProvider[]
-    privKeyHex?: string
-  }): Promise<SetupWalletOnly> {
-    args.chain ||= 'test'
-    args.rootKeyHex ||= '1'.repeat(64)
+  /**
+   * 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: SetupWalletArgs): Promise<SetupWallet> {
+    args.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)
@@ -220,6 +144,8 @@ export abstract class SetupClient {
       args.backups
     )
     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 monopts = Monitor.createDefaultWalletMonitorOptions(
       chain,
@@ -228,10 +154,10 @@ export abstract class SetupClient {
     )
     const monitor = new Monitor(monopts)
     monitor.addDefaultTasks()
-    let privilegedKeyManager: PrivilegedKeyManager | undefined = undefined
+    let privilegedKeyManager: sdk.PrivilegedKeyManager | undefined = undefined
     if (args.privKeyHex) {
       const privKey = PrivateKey.fromString(args.privKeyHex)
-      privilegedKeyManager = new PrivilegedKeyManager(async () => privKey)
+      privilegedKeyManager = new sdk.PrivilegedKeyManager(async () => privKey)
     }
     const wallet = new Wallet({
       chain,
@@ -241,7 +167,7 @@ export abstract class SetupClient {
       monitor,
       privilegedKeyManager
     })
-    const r: SetupWalletOnly = {
+    const r: SetupWallet = {
       rootKey,
       identityKey,
       keyDeriver,
@@ -254,36 +180,193 @@ export abstract class SetupClient {
     return r
   }
 
-  static async createWalletWithStorageClient(args: {
-    rootKeyHex?: string
-    endpointUrl?: string
-    chain?: sdk.Chain
-  }): Promise<SetupWalletOnly> {
-    if (args.chain === 'main')
+  /**
+   * @publicBody
+   */
+  static async createWalletWithStorageClient(
+    args: SetupWalletClientArgs
+  ): Promise<SetupWalletClient> {
+    const wo = await SetupClient.createWallet(args)
+    if (wo.chain === 'main')
       throw new sdk.WERR_INVALID_PARAMETER(
         'chain',
         `'test' for now, 'main' is not yet supported.`
       )
 
-    const wo = await SetupClient.createWalletOnly({
-      chain: 'test',
-      rootKeyHex: args.rootKeyHex
-    })
-    args.endpointUrl ||= 'https://staging-dojo.babbage.systems'
-    const client = new StorageClient(wo.wallet, args.endpointUrl)
+    const endpointUrl =
+      args.endpointUrl || 'https://staging-dojo.babbage.systems'
+    const client = new StorageClient(wo.wallet, endpointUrl)
     await wo.storage.addWalletStorageProvider(client)
     await wo.storage.makeAvailable()
-    return wo
+    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) {
+    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
   }
 }
 
+/**
+ *
+ */
 export type KeyPairAddress = {
   privateKey: PrivateKey
   publicKey: PublicKey
   address: string
 }
 
-export interface SetupWalletOnly {
+/**
+ *
+ */
+export interface SetupEnv {
+  chain: sdk.Chain
+  identityKey: string
+  identityKey2: string
+  taalApiKey: string
+  devKeys: Record<string, string>
+  mySQLConnection: string
+}
+
+/**
+ * Arguments used to construct a `Wallet`
+ *
+ * @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.
+ */
+export interface SetupWalletArgs {
+  env: SetupEnv
+  chain?: sdk.Chain
+  rootKeyHex?: string
+  privKeyHex?: string
+  active?: sdk.WalletStorageProvider
+  backups?: sdk.WalletStorageProvider[]
+}
+
+export interface SetupWallet {
   rootKey: PrivateKey
   identityKey: string
   keyDeriver: KeyDeriver
@@ -293,3 +376,11 @@ export interface SetupWalletOnly {
   monitor: Monitor
   wallet: Wallet
 }
+
+export interface SetupWalletClientArgs extends SetupWalletArgs {
+  endpointUrl?: string
+}
+
+export interface SetupWalletClient extends SetupWallet {
+  endpointUrl: string
+}

package/src/Wallet.ts

@@ -101,6 +101,16 @@ export class Wallet implements WalletInterface, ProtoWallet {
 
   identityKey: string
 
+  /**
+   * The wallet creates a `BeefParty` when it is created.
+   * All the Beefs that pass through the wallet are merged into this beef.
+   * Thus what it contains at any time is the union of all transactions and proof data processed.
+   * The class `BeefParty` derives from `Beef`, adding the ability to track the source of merged data.
+   *
+   * This allows it to generate beefs to send to a particular “party” (storage or the user)
+   * that includes “txid only proofs” for transactions they already know about.
+   * Over time, this allows an active wallet to drastically reduce the amount of data transmitted.
+   */
   beef: BeefParty
   trustSelf?: TrustSelf
   userParty: string