@bopen-io/wallet-toolbox 1.7.18

package/src/signer/methods/completeSignedTransaction.ts

@@ -0,0 +1,117 @@
+import { Beef, SignActionResult, SignActionSpend, Spend, Transaction } from '@bsv/sdk'
+import { PendingSignAction, Wallet } from '../../Wallet'
+import { WERR_INVALID_PARAMETER } from '../../sdk/WERR_errors'
+import { asBsvSdkScript } from '../../utility/utilityHelpers'
+import { ScriptTemplateBRC29 } from '../../utility/ScriptTemplateBRC29'
+import { WalletError } from '../../sdk/WalletError'
+
+export async function completeSignedTransaction(
+  prior: PendingSignAction,
+  spends: Record<number, SignActionSpend>,
+  wallet: Wallet
+): Promise<Transaction> {
+  /////////////////////
+  // Insert the user provided unlocking scripts from "spends" arg
+  /////////////////////
+  for (const [key, spend] of Object.entries(spends)) {
+    const vin = Number(key)
+    const createInput = prior.args.inputs[vin]
+    const input = prior.tx.inputs[vin]
+    if (!createInput || !input || createInput.unlockingScript || !Number.isInteger(createInput.unlockingScriptLength))
+      throw new WERR_INVALID_PARAMETER(
+        'args',
+        `spend does not correspond to prior input with valid unlockingScriptLength.`
+      )
+    if (spend.unlockingScript.length / 2 > createInput.unlockingScriptLength!)
+      throw new WERR_INVALID_PARAMETER(
+        'args',
+        `spend unlockingScript length ${spend.unlockingScript.length} exceeds expected length ${createInput.unlockingScriptLength}`
+      )
+    input.unlockingScript = asBsvSdkScript(spend.unlockingScript)
+    if (spend.sequenceNumber !== undefined) input.sequence = spend.sequenceNumber
+  }
+
+  const results = {
+    sdk: <SignActionResult>{}
+  }
+
+  /////////////////////
+  // Insert SABPPP unlock templates for wallet signed inputs
+  /////////////////////
+  for (const pdi of prior.pdi) {
+    const sabppp = new ScriptTemplateBRC29({
+      derivationPrefix: pdi.derivationPrefix,
+      derivationSuffix: pdi.derivationSuffix,
+      keyDeriver: wallet.keyDeriver
+    })
+    const keys = wallet.getClientChangeKeyPair()
+    const lockerPrivKey = keys.privateKey
+    const unlockerPubKey = pdi.unlockerPubKey || keys.publicKey
+    const sourceSatoshis = pdi.sourceSatoshis
+    const lockingScript = asBsvSdkScript(pdi.lockingScript)
+    const unlockTemplate = sabppp.unlock(lockerPrivKey, unlockerPubKey, sourceSatoshis, lockingScript)
+    const input = prior.tx.inputs[pdi.vin]
+    input.unlockingScriptTemplate = unlockTemplate
+  }
+
+  /////////////////////
+  // Sign wallet signed inputs making transaction fully valid.
+  /////////////////////
+  await prior.tx.sign()
+
+  return prior.tx
+}
+
+/**
+ * @param txid The TXID of a transaction in the beef for which all unlocking scripts must be valid.
+ * @param beef Must contain transactions for txid and all its inputs.
+ * @throws WERR_INVALID_PARAMETER if any unlocking script is invalid, if sourceTXID is invalid, if beef doesn't contain required transactions.
+ */
+export function verifyUnlockScripts(txid: string, beef: Beef): void {
+  const tx = beef.findTxid(txid)?.tx
+  if (!tx) throw new WERR_INVALID_PARAMETER(`txid`, `contained in beef, txid ${txid}`)
+
+  for (let i = 0; i < tx.inputs.length; i++) {
+    const input = tx.inputs[i]
+    if (!input.sourceTXID) throw new WERR_INVALID_PARAMETER(`inputs[${i}].sourceTXID`, `valid`)
+    if (!input.unlockingScript) throw new WERR_INVALID_PARAMETER(`inputs[${i}].unlockingScript`, `valid`)
+    input.sourceTransaction = beef.findTxid(input.sourceTXID)?.tx
+    if (!input.sourceTransaction) {
+      // The beef doesn't contain all the source transactions only if advanced features
+      // such as knownTxids are used.
+      // Skip unlock script checks.
+      return
+      // throw new WERR_INVALID_PARAMETER(`inputs[${i}].sourceTXID`, `contained in beef`)
+    }
+  }
+
+  for (let i = 0; i < tx.inputs.length; i++) {
+    const input = tx.inputs[i]
+    const sourceOutput = input.sourceTransaction!.outputs[input.sourceOutputIndex]
+
+    const otherInputs = tx.inputs.filter((_, idx) => idx !== i)
+
+    const spend = new Spend({
+      sourceTXID: input.sourceTXID!,
+      sourceOutputIndex: input.sourceOutputIndex,
+      lockingScript: sourceOutput.lockingScript,
+      sourceSatoshis: sourceOutput.satoshis ?? 0,
+      transactionVersion: tx.version,
+      otherInputs,
+      unlockingScript: input.unlockingScript!,
+      inputSequence: input.sequence ?? 0,
+      inputIndex: i,
+      outputs: tx.outputs,
+      lockTime: tx.lockTime
+    })
+
+    try {
+      const spendValid = spend.validate()
+
+      if (!spendValid) throw new WERR_INVALID_PARAMETER(`inputs[${i}].unlockScript`, `valid`)
+    } catch (eu: unknown) {
+      const e = WalletError.fromUnknown(eu)
+      throw new WERR_INVALID_PARAMETER(`inputs[${i}].unlockScript`, `valid. ${e.message}`)
+    }
+  }
+}

package/src/signer/methods/createAction.ts

@@ -0,0 +1,172 @@
+import {
+  AtomicBEEF,
+  Beef,
+  CreateActionResult,
+  OutpointString,
+  SendWithResult,
+  SignableTransaction,
+  TXIDHexString,
+  Script,
+  Transaction,
+  Validation
+} from '@bsv/sdk'
+import { buildSignableTransaction } from './buildSignableTransaction'
+import {
+  AuthId,
+  ReviewActionResult,
+  StorageProcessActionArgs,
+  StorageProcessActionResults
+} from '../../sdk/WalletStorage.interfaces'
+import { completeSignedTransaction, verifyUnlockScripts } from './completeSignedTransaction'
+import { PendingSignAction, Wallet } from '../../Wallet'
+import { WERR_INTERNAL } from '../../sdk/WERR_errors'
+
+export interface CreateActionResultX extends CreateActionResult {
+  txid?: TXIDHexString
+  tx?: AtomicBEEF
+  noSendChange?: OutpointString[]
+  sendWithResults?: SendWithResult[]
+  signableTransaction?: SignableTransaction
+  notDelayedResults?: ReviewActionResult[]
+}
+
+export async function createAction(
+  wallet: Wallet,
+  auth: AuthId,
+  vargs: Validation.ValidCreateActionArgs
+): Promise<CreateActionResultX> {
+  const r: CreateActionResultX = {}
+  const logger = vargs.logger
+
+  let prior: PendingSignAction | undefined = undefined
+
+  if (vargs.isNewTx || vargs.isTestWerrReviewActions) {
+    prior = await createNewTx(wallet, vargs)
+    logger?.log('created new transaction')
+
+    if (vargs.isSignAction) {
+      const r = makeSignableTransactionResult(prior, wallet, vargs)
+      logger?.log('created signable transaction result')
+      return r
+    }
+
+    prior.tx = await completeSignedTransaction(prior, {}, wallet)
+    logger?.log('completed signed transaction')
+
+    r.txid = prior.tx.id('hex')
+    const beef = new Beef()
+    if (prior.dcr.inputBeef) beef.mergeBeef(prior.dcr.inputBeef)
+    beef.mergeTransaction(prior.tx)
+    logger?.log('merged beef')
+
+    verifyUnlockScripts(r.txid, beef)
+    logger?.log('verified unlock scripts')
+
+    r.noSendChange = prior.dcr.noSendChangeOutputVouts?.map(vout => `${r.txid}.${vout}`)
+    if (!vargs.options.returnTXIDOnly) r.tx = beef.toBinaryAtomic(r.txid)
+  }
+
+  const { sendWithResults, notDelayedResults } = await processAction(prior, wallet, auth, vargs)
+  logger?.log('processed transaction')
+
+  r.sendWithResults = sendWithResults
+  r.notDelayedResults = notDelayedResults
+
+  return r
+}
+
+async function createNewTx(wallet: Wallet, vargs: Validation.ValidCreateActionArgs): Promise<PendingSignAction> {
+  const logger = vargs.logger
+  const storageArgs = removeUnlockScripts(vargs)
+  const dcr = await wallet.storage.createAction(storageArgs)
+
+  const reference = dcr.reference
+
+  const { tx, amount, pdi } = buildSignableTransaction(dcr, vargs, wallet)
+  logger?.log('built signable transaction')
+
+  const prior: PendingSignAction = { reference, dcr, args: vargs, amount, tx, pdi }
+
+  return prior
+}
+
+function makeSignableTransactionResult(
+  prior: PendingSignAction,
+  wallet: Wallet,
+  args: Validation.ValidCreateActionArgs
+): CreateActionResult {
+  if (!prior.dcr.inputBeef) throw new WERR_INTERNAL('prior.dcr.inputBeef must be valid')
+
+  const txid = prior.tx.id('hex')
+
+  const r: CreateActionResult = {
+    noSendChange: args.isNoSend ? prior.dcr.noSendChangeOutputVouts?.map(vout => `${txid}.${vout}`) : undefined,
+    signableTransaction: {
+      reference: prior.dcr.reference,
+      tx: makeSignableTransactionBeef(prior.tx, prior.dcr.inputBeef)
+    }
+  }
+
+  wallet.pendingSignActions[r.signableTransaction!.reference] = prior
+
+  return r
+}
+
+function makeSignableTransactionBeef(tx: Transaction, inputBEEF: number[]): number[] {
+  // This is a special case beef for transaction signing.
+  // We only need the transaction being signed, and for each input, the raw source transaction.
+  const beef = new Beef()
+  for (const input of tx.inputs) {
+    if (!input.sourceTransaction)
+      throw new WERR_INTERNAL('Every signableTransaction input must have a sourceTransaction')
+    beef.mergeRawTx(input.sourceTransaction!.toBinary())
+  }
+  beef.mergeRawTx(tx.toBinary())
+  return beef.toBinaryAtomic(tx.id('hex'))
+}
+
+function removeUnlockScripts(args: Validation.ValidCreateActionArgs) {
+  let storageArgs = args
+  if (!storageArgs.inputs.every(i => i.unlockingScript === undefined)) {
+    // Never send unlocking scripts to storage, all it needs is the script length.
+    storageArgs = { ...args, inputs: [] }
+    for (const i of args.inputs) {
+      const di: Validation.ValidCreateActionInput = {
+        ...i,
+        unlockingScriptLength: i.unlockingScript !== undefined ? i.unlockingScript.length : i.unlockingScriptLength
+      }
+      delete di.unlockingScript
+      storageArgs.inputs.push(di)
+    }
+  }
+  return storageArgs
+}
+
+export async function processAction(
+  prior: PendingSignAction | undefined,
+  wallet: Wallet,
+  auth: AuthId,
+  vargs: Validation.ValidProcessActionArgs
+): Promise<StorageProcessActionResults> {
+  const args: StorageProcessActionArgs = {
+    isNewTx: vargs.isNewTx,
+    isSendWith: vargs.isSendWith,
+    isNoSend: vargs.isNoSend,
+    isDelayed: vargs.isDelayed,
+    reference: prior ? prior.reference : undefined,
+    txid: prior ? prior.tx.id('hex') : undefined,
+    rawTx: prior ? prior.tx.toBinary() : undefined,
+    sendWith: vargs.isSendWith ? vargs.options.sendWith : [],
+    logger: vargs.logger
+  }
+  const r: StorageProcessActionResults = await wallet.storage.processAction(args)
+
+  return r
+}
+
+function makeDummyTransactionForOutputSatoshis(vout: number, satoshis: number): Transaction {
+  const tx = new Transaction()
+  for (let i = 0; i < vout; i++) tx.addOutput({ lockingScript: new Script(), satoshis: 0 })
+  tx.addOutput({ lockingScript: new Script(), satoshis })
+  return tx
+}

package/src/signer/methods/internalizeAction.ts

@@ -0,0 +1,106 @@
+import { Beef, InternalizeActionArgs, InternalizeOutput, P2PKH, WalletProtocol, Validation } from '@bsv/sdk'
+import { Wallet } from '../../Wallet'
+import { AuthId, StorageInternalizeActionResult } from '../../sdk/WalletStorage.interfaces'
+import { WERR_INTERNAL, WERR_INVALID_PARAMETER } from '../../sdk/WERR_errors'
+
+/**
+ * Internalize Action allows a wallet to take ownership of outputs in a pre-existing transaction.
+ * The transaction may, or may not already be known to both the storage and user.
+ *
+ * Two types of outputs are handled: "wallet payments" and "basket insertions".
+ *
+ * A "basket insertion" output is considered a custom output and has no effect on the wallet's "balance".
+ *
+ * A "wallet payment" adds an outputs value to the wallet's change "balance". These outputs are assigned to the "default" basket.
+ *
+ * Processing starts with simple validation and then checks for a pre-existing transaction.
+ * If the transaction is already known to the user, then the outputs are reviewed against the existing outputs treatment,
+ * and merge rules are added to the arguments passed to the storage layer.
+ * The existing transaction must be in the 'unproven' or 'completed' status. Any other status is an error.
+ *
+ * When the transaction already exists, the description is updated. The isOutgoing sense is not changed.
+ *
+ * "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".
+ *
+ * "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 `amount`, and the wallet balance.
+ *
+ */
+export async function internalizeAction(
+  wallet: Wallet,
+  auth: AuthId,
+  args: InternalizeActionArgs
+): Promise<StorageInternalizeActionResult> {
+  const vargs = Validation.validateInternalizeActionArgs(args)
+
+  const { ab, tx, txid } = await validateAtomicBeef()
+  const brc29ProtocolID: WalletProtocol = [2, '3241645161d8']
+
+  for (const o of vargs.outputs) {
+    if (o.outputIndex < 0 || o.outputIndex >= tx.outputs.length)
+      throw new WERR_INVALID_PARAMETER('outputIndex', `a valid output index in range 0 to ${tx.outputs.length - 1}`)
+    switch (o.protocol) {
+      case 'basket insertion':
+        setupBasketInsertionForOutput(o, vargs)
+        break
+      case 'wallet payment':
+        setupWalletPaymentForOutput(o, vargs)
+        break
+      default:
+        throw new WERR_INTERNAL(`unexpected protocol ${o.protocol}`)
+    }
+  }
+
+  const r: StorageInternalizeActionResult = await wallet.storage.internalizeAction(args)
+
+  return r
+
+  function setupWalletPaymentForOutput(o: InternalizeOutput, dargs: Validation.ValidInternalizeActionArgs) {
+    const p = o.paymentRemittance
+    const output = tx.outputs[o.outputIndex]
+    if (!p) throw new WERR_INVALID_PARAMETER('paymentRemittance', `valid for protocol ${o.protocol}`)
+
+    const keyID = `${p.derivationPrefix} ${p.derivationSuffix}`
+
+    const privKey = wallet.keyDeriver!.derivePrivateKey(brc29ProtocolID, keyID, p.senderIdentityKey)
+    const expectedLockScript = new P2PKH().lock(privKey.toAddress())
+    if (output.lockingScript.toHex() !== expectedLockScript.toHex())
+      throw new WERR_INVALID_PARAMETER('paymentRemittance', `locked by script conforming to BRC-29`)
+  }
+
+  function setupBasketInsertionForOutput(o: InternalizeOutput, dargs: Validation.ValidInternalizeActionArgs) {
+    /*
+    No additional validations...
+    */
+  }
+
+  /**
+   * Verifies that the `tx` argument passed to internalizeAction is a valid AtomicBEEF,
+   * and the proofs are valid according to the wallet's configured chainTracker.
+   * THIS DOES NOT GUARANTEE:
+   * 1. That the transaction has been broadcast. (Is known to the network).
+   * 2. That the proofs are for the same block as recorded in the wallet's configured storage in the event of a reorg.
+   */
+  async function validateAtomicBeef() {
+    const ab = Beef.fromBinary(vargs.tx)
+
+    // TODO: Add support for known txids...which would speed up processing by avoiding a network call,
+    // unless a local chaintracker is used.
+
+    const txValid = await ab.verify(await wallet.getServices().getChainTracker(), false)
+    if (!txValid || !ab.atomicTxid) {
+      console.log(`internalizeAction beef is invalid: ${ab.toLogString()}`)
+      throw new WERR_INVALID_PARAMETER('tx', 'valid AtomicBEEF')
+    }
+    const txid = ab.atomicTxid
+    const btx = ab.findTxid(txid)
+    if (!btx) throw new WERR_INVALID_PARAMETER('tx', `valid AtomicBEEF with newest txid of ${txid}`)
+    const tx = btx.tx!
+
+    return { ab, tx, txid }
+  }
+}

package/src/signer/methods/proveCertificate.ts

@@ -0,0 +1,43 @@
+import { MasterCertificate, ProveCertificateResult, Validation } from '@bsv/sdk'
+import { Wallet } from '../../Wallet'
+import { WERR_INVALID_PARAMETER } from '../../sdk/WERR_errors'
+import { AuthId } from '../../sdk/WalletStorage.interfaces'
+
+export async function proveCertificate(
+  wallet: Wallet,
+  auth: AuthId,
+  vargs: Validation.ValidProveCertificateArgs
+): Promise<ProveCertificateResult> {
+  const lcargs: Validation.ValidListCertificatesArgs = {
+    partial: {
+      type: vargs.type,
+      serialNumber: vargs.serialNumber,
+      certifier: vargs.certifier,
+      subject: vargs.subject,
+      revocationOutpoint: vargs.revocationOutpoint,
+      signature: vargs.signature
+    },
+    certifiers: [],
+    types: [],
+    limit: 2,
+    offset: 0,
+    privileged: false
+  }
+
+  const lcr = await wallet.storage.listCertificates(lcargs)
+  if (lcr.certificates.length != 1) throw new WERR_INVALID_PARAMETER('args', `a unique certificate match`)
+  const storageCert = lcr.certificates[0]
+  const keyringForVerifier = await MasterCertificate.createKeyringForVerifier(
+    wallet,
+    storageCert.certifier,
+    vargs.verifier,
+    storageCert.fields,
+    vargs.fieldsToReveal,
+    storageCert.keyring!,
+    storageCert.serialNumber,
+    vargs.privileged,
+    vargs.privilegedReason
+  )
+
+  return { keyringForVerifier }
+}

package/src/signer/methods/signAction.ts

@@ -0,0 +1,54 @@
+import { AtomicBEEF, Beef, SendWithResult, SignActionArgs, SignActionResult, TXIDHexString, Validation } from '@bsv/sdk'
+import { processAction } from './createAction'
+import { AuthId, ReviewActionResult } from '../../sdk/WalletStorage.interfaces'
+import { completeSignedTransaction, verifyUnlockScripts } from './completeSignedTransaction'
+import { Wallet } from '../../Wallet'
+import { WERR_INTERNAL, WERR_NOT_IMPLEMENTED } from '../../sdk/WERR_errors'
+
+export interface SignActionResultX extends SignActionResult {
+  txid?: TXIDHexString
+  tx?: AtomicBEEF
+  sendWithResults?: SendWithResult[]
+  notDelayedResults?: ReviewActionResult[]
+}
+
+export async function signAction(wallet: Wallet, auth: AuthId, args: SignActionArgs): Promise<SignActionResultX> {
+  const prior = wallet.pendingSignActions[args.reference]
+  if (!prior)
+    throw new WERR_NOT_IMPLEMENTED('recovery of out-of-session signAction reference data is not yet implemented.')
+  if (!prior.dcr.inputBeef) throw new WERR_INTERNAL('prior.dcr.inputBeef must be valid')
+
+  const vargs = mergePriorOptions(prior.args, args)
+
+  prior.tx = await completeSignedTransaction(prior, vargs.spends, wallet)
+
+  const { sendWithResults, notDelayedResults } = await processAction(prior, wallet, auth, vargs)
+
+  const txid = prior.tx.id('hex')
+  const beef = Beef.fromBinary(prior.dcr.inputBeef)
+  beef.mergeTransaction(prior.tx)
+
+  verifyUnlockScripts(txid, beef)
+
+  const r: SignActionResultX = {
+    txid: prior.tx.id('hex'),
+    tx: vargs.options.returnTXIDOnly ? undefined : beef.toBinaryAtomic(txid),
+    sendWithResults,
+    notDelayedResults
+  }
+
+  return r
+}
+
+function mergePriorOptions(
+  caVargs: Validation.ValidCreateActionArgs,
+  saArgs: SignActionArgs
+): Validation.ValidSignActionArgs {
+  const saOptions = (saArgs.options ||= {})
+  if (saOptions.acceptDelayedBroadcast === undefined)
+    saOptions.acceptDelayedBroadcast = caVargs.options.acceptDelayedBroadcast
+  if (saOptions.returnTXIDOnly === undefined) saOptions.returnTXIDOnly = caVargs.options.returnTXIDOnly
+  if (saOptions.noSend === undefined) saOptions.noSend = caVargs.options.noSend
+  if (saOptions.sendWith === undefined) saOptions.sendWith = caVargs.options.sendWith
+  return Validation.validateSignActionArgs(saArgs)
+}

package/src/storage/README.md

@@ -0,0 +1,14 @@
+# WalletStorage
+
+Provides access to persistent storage in support of Wallet.interfaces.
+
+This includes:
+
+- Direct storage on a variety of databases.
+- Remoted storage to service providers for backup and mobile support.
+- Synchronization between multiple stores.
+- Import from legacy stores.
+- Support single user, multi-read/single write, full multi-user modes.
+
+
+