@bsv/wallet-toolbox 1.1.0

package/src/sdk/StorageSyncReaderWriter.ts

@@ -0,0 +1,263 @@
+import { sdk, table } from '../index.client'
+
+/**
+ * This is the minimal interface required for a WalletStorageProvider to import and export data to another provider.
+ */
+export interface StorageSyncReaderWriter extends sdk.StorageSyncReader {
+  getProvenOrRawTx(txid: string, trx?: sdk.TrxToken): Promise<sdk.ProvenOrRawTx>
+
+  purgeData(
+    params: sdk.PurgeParams,
+    trx?: sdk.TrxToken
+  ): Promise<sdk.PurgeResults>
+
+  transaction<T>(
+    scope: (trx: sdk.TrxToken) => Promise<T>,
+    trx?: sdk.TrxToken
+  ): Promise<T>
+
+  findOutputTagMaps(
+    args: sdk.FindOutputTagMapsArgs
+  ): Promise<table.OutputTagMap[]>
+  findProvenTxReqs(args: sdk.FindProvenTxReqsArgs): Promise<table.ProvenTxReq[]>
+  findProvenTxs(args: sdk.FindProvenTxsArgs): Promise<table.ProvenTx[]>
+  findTxLabelMaps(args: sdk.FindTxLabelMapsArgs): Promise<table.TxLabelMap[]>
+
+  countOutputTagMaps(args: sdk.FindOutputTagMapsArgs): Promise<number>
+  countProvenTxReqs(args: sdk.FindProvenTxReqsArgs): Promise<number>
+  countProvenTxs(args: sdk.FindProvenTxsArgs): Promise<number>
+  countTxLabelMaps(args: sdk.FindTxLabelMapsArgs): Promise<number>
+
+  insertProvenTx(tx: table.ProvenTx, trx?: sdk.TrxToken): Promise<number>
+  insertProvenTxReq(tx: table.ProvenTxReq, trx?: sdk.TrxToken): Promise<number>
+  insertUser(user: table.User, trx?: sdk.TrxToken): Promise<number>
+  insertCertificate(
+    certificate: table.Certificate,
+    trx?: sdk.TrxToken
+  ): Promise<number>
+  insertCertificateField(
+    certificateField: table.CertificateField,
+    trx?: sdk.TrxToken
+  ): Promise<void>
+  insertOutputBasket(
+    basket: table.OutputBasket,
+    trx?: sdk.TrxToken
+  ): Promise<number>
+  insertTransaction(tx: table.Transaction, trx?: sdk.TrxToken): Promise<number>
+  insertCommission(
+    commission: table.Commission,
+    trx?: sdk.TrxToken
+  ): Promise<number>
+  insertOutput(output: table.Output, trx?: sdk.TrxToken): Promise<number>
+  insertOutputTag(tag: table.OutputTag, trx?: sdk.TrxToken): Promise<number>
+  insertOutputTagMap(
+    tagMap: table.OutputTagMap,
+    trx?: sdk.TrxToken
+  ): Promise<void>
+  insertTxLabel(label: table.TxLabel, trx?: sdk.TrxToken): Promise<number>
+  insertTxLabelMap(
+    labelMap: table.TxLabelMap,
+    trx?: sdk.TrxToken
+  ): Promise<void>
+  insertSyncState(
+    syncState: table.SyncState,
+    trx?: sdk.TrxToken
+  ): Promise<number>
+
+  updateCertificateField(
+    certificateId: number,
+    fieldName: string,
+    update: Partial<table.CertificateField>,
+    trx?: sdk.TrxToken
+  ): Promise<number>
+  updateCertificate(
+    id: number,
+    update: Partial<table.Certificate>,
+    trx?: sdk.TrxToken
+  ): Promise<number>
+  updateCommission(
+    id: number,
+    update: Partial<table.Commission>,
+    trx?: sdk.TrxToken
+  ): Promise<number>
+  updateOutputBasket(
+    id: number,
+    update: Partial<table.OutputBasket>,
+    trx?: sdk.TrxToken
+  ): Promise<number>
+  updateOutput(
+    id: number,
+    update: Partial<table.Output>,
+    trx?: sdk.TrxToken
+  ): Promise<number>
+  updateOutputTagMap(
+    outputId: number,
+    tagId: number,
+    update: Partial<table.OutputTagMap>,
+    trx?: sdk.TrxToken
+  ): Promise<number>
+  updateOutputTag(
+    id: number,
+    update: Partial<table.OutputTag>,
+    trx?: sdk.TrxToken
+  ): Promise<number>
+  updateProvenTxReq(
+    id: number | number[],
+    update: Partial<table.ProvenTxReq>,
+    trx?: sdk.TrxToken
+  ): Promise<number>
+  updateProvenTxReqDynamics(
+    id: number,
+    update: Partial<table.ProvenTxReqDynamics>,
+    trx?: sdk.TrxToken
+  ): Promise<number>
+  updateProvenTxReqWithNewProvenTx(
+    args: sdk.UpdateProvenTxReqWithNewProvenTxArgs
+  ): Promise<sdk.UpdateProvenTxReqWithNewProvenTxResult>
+  updateProvenTx(
+    id: number,
+    update: Partial<table.ProvenTx>,
+    trx?: sdk.TrxToken
+  ): Promise<number>
+  updateSyncState(
+    id: number,
+    update: Partial<table.SyncState>,
+    trx?: sdk.TrxToken
+  ): Promise<number>
+  updateTransaction(
+    id: number | number[],
+    update: Partial<table.Transaction>,
+    trx?: sdk.TrxToken
+  ): Promise<number>
+  updateTransactionStatus(
+    status: sdk.TransactionStatus,
+    transactionId?: number,
+    userId?: number,
+    reference?: string,
+    trx?: sdk.TrxToken
+  ): Promise<void>
+  updateTransactionsStatus(
+    transactionIds: number[],
+    status: sdk.TransactionStatus
+  ): Promise<void>
+  updateTxLabelMap(
+    transactionId: number,
+    txLabelId: number,
+    update: Partial<table.TxLabelMap>,
+    trx?: sdk.TrxToken
+  ): Promise<number>
+  updateTxLabel(
+    id: number,
+    update: Partial<table.TxLabel>,
+    trx?: sdk.TrxToken
+  ): Promise<number>
+  updateUser(
+    id: number,
+    update: Partial<table.User>,
+    trx?: sdk.TrxToken
+  ): Promise<number>
+
+  findCertificateById(
+    id: number,
+    trx?: sdk.TrxToken
+  ): Promise<table.Certificate | undefined>
+  findCommissionById(
+    id: number,
+    trx?: sdk.TrxToken
+  ): Promise<table.Commission | undefined>
+  findOutputById(
+    id: number,
+    trx?: sdk.TrxToken,
+    noScript?: boolean
+  ): Promise<table.Output | undefined>
+  findOutputBasketById(
+    id: number,
+    trx?: sdk.TrxToken
+  ): Promise<table.OutputBasket | undefined>
+  findProvenTxById(
+    id: number,
+    trx?: sdk.TrxToken | undefined
+  ): Promise<table.ProvenTx | undefined>
+  findProvenTxReqById(
+    id: number,
+    trx?: sdk.TrxToken | undefined
+  ): Promise<table.ProvenTxReq | undefined>
+  findSyncStateById(
+    id: number,
+    trx?: sdk.TrxToken
+  ): Promise<table.SyncState | undefined>
+  findTransactionById(
+    id: number,
+    trx?: sdk.TrxToken,
+    noRawTx?: boolean
+  ): Promise<table.Transaction | undefined>
+  findTxLabelById(
+    id: number,
+    trx?: sdk.TrxToken
+  ): Promise<table.TxLabel | undefined>
+  findOutputTagById(
+    id: number,
+    trx?: sdk.TrxToken
+  ): Promise<table.OutputTag | undefined>
+  findUserById(id: number, trx?: sdk.TrxToken): Promise<table.User | undefined>
+
+  findOrInsertUser(
+    identityKey: string,
+    trx?: sdk.TrxToken
+  ): Promise<{ user: table.User; isNew: boolean }>
+
+  findOrInsertTransaction(
+    newTx: table.Transaction,
+    trx?: sdk.TrxToken
+  ): Promise<{ tx: table.Transaction; isNew: boolean }>
+  findOrInsertOutputBasket(
+    userId: number,
+    name: string,
+    trx?: sdk.TrxToken
+  ): Promise<table.OutputBasket>
+  findOrInsertTxLabel(
+    userId: number,
+    label: string,
+    trx?: sdk.TrxToken
+  ): Promise<table.TxLabel>
+  findOrInsertTxLabelMap(
+    transactionId: number,
+    txLabelId: number,
+    trx?: sdk.TrxToken
+  ): Promise<table.TxLabelMap>
+  findOrInsertOutputTag(
+    userId: number,
+    tag: string,
+    trx?: sdk.TrxToken
+  ): Promise<table.OutputTag>
+  findOrInsertOutputTagMap(
+    outputId: number,
+    outputTagId: number,
+    trx?: sdk.TrxToken
+  ): Promise<table.OutputTagMap>
+  findOrInsertSyncStateAuth(
+    auth: sdk.AuthId,
+    storageIdentityKey: string,
+    storageName: string
+  ): Promise<{ syncState: table.SyncState; isNew: boolean }>
+  findOrInsertProvenTxReq(
+    newReq: table.ProvenTxReq,
+    trx?: sdk.TrxToken
+  ): Promise<{ req: table.ProvenTxReq; isNew: boolean }>
+  findOrInsertProvenTx(
+    newProven: table.ProvenTx,
+    trx?: sdk.TrxToken
+  ): Promise<{ proven: table.ProvenTx; isNew: boolean }>
+  findUsers(args: sdk.FindUsersArgs): Promise<table.User[]>
+
+  tagOutput(
+    partial: Partial<table.Output>,
+    tag: string,
+    trx?: sdk.TrxToken
+  ): Promise<void>
+
+  processSyncChunk(
+    args: sdk.RequestSyncChunkArgs,
+    chunk: sdk.SyncChunk
+  ): Promise<sdk.ProcessSyncChunkResult>
+}

package/src/sdk/WERR_errors.ts

@@ -0,0 +1,152 @@
+import { WalletNetwork } from '@bsv/sdk'
+import { WalletError } from './WalletError'
+
+/**
+ * Not implemented.
+ */
+export class WERR_NOT_IMPLEMENTED extends WalletError {
+  constructor(message?: string) {
+    super('WERR_NOT_IMPLEMENTED', message ?? 'Not implemented.')
+  }
+}
+
+/**
+ * An internal error has occurred.
+ *
+ * This is an example of an error with an optional custom `message`.
+ */
+export class WERR_INTERNAL extends WalletError {
+  constructor(message?: string) {
+    super('WERR_INTERNAL', message ?? 'An internal error has occurred.')
+  }
+}
+
+/**
+ * The ${parameter} parameter is invalid.
+ *
+ * This is an example of an error object with a custom property `parameter` and templated `message`.
+ */
+export class WERR_INVALID_OPERATION extends WalletError {
+  constructor(message?: string) {
+    super(
+      'WERR_INVALID_OPERATION',
+      message ?? `An invalid operation was requested.`
+    )
+  }
+}
+
+/**
+ * The ${parameter} parameter is invalid.
+ *
+ * This is an example of an error object with a custom property `parameter` and templated `message`.
+ */
+export class WERR_INVALID_PARAMETER extends WalletError {
+  constructor(
+    public parameter: string,
+    mustBe?: string
+  ) {
+    super(
+      'WERR_INVALID_PARAMETER',
+      `The ${parameter} parameter must be ${mustBe ?? 'valid.'}`
+    )
+  }
+}
+
+/**
+ * The required ${parameter} parameter is missing.
+ *
+ * This is an example of an error object with a custom property `parameter`
+ */
+export class WERR_MISSING_PARAMETER extends WalletError {
+  constructor(public parameter: string) {
+    super(
+      'WERR_MISSING_PARAMETER',
+      `The required ${parameter} parameter is missing.`
+    )
+  }
+}
+
+/**
+ * The request is invalid.
+ */
+export class WERR_BAD_REQUEST extends WalletError {
+  constructor(message?: string) {
+    super('WERR_BAD_REQUEST', message ?? 'The request is invalid.')
+  }
+}
+
+/**
+ * Configured network chain is invalid or does not match across services.
+ */
+export class WERR_NETWORK_CHAIN extends WalletError {
+  constructor(message?: string) {
+    super(
+      'WERR_NETWORK_CHAIN',
+      message ??
+        'Configured network chain is invalid or does not match across services.'
+    )
+  }
+}
+
+/**
+ * Access is denied due to an authorization error.
+ */
+export class WERR_UNAUTHORIZED extends WalletError {
+  constructor(message?: string) {
+    super(
+      'WERR_UNAUTHORIZED',
+      message ?? 'Access is denied due to an authorization error.'
+    )
+  }
+}
+
+/**
+ * WalletStorageManager is not accessing user's active storage.
+ */
+export class WERR_NOT_ACTIVE extends WalletError {
+  constructor(message?: string) {
+    super(
+      'WERR_NOT_ACTIVE',
+      message ?? `WalletStorageManager is not accessing user's active storage.`
+    )
+  }
+}
+
+/**
+ * Insufficient funds in the available inputs to cover the cost of the required outputs
+ * and the transaction fee (${moreSatoshisNeeded} more satoshis are needed,
+ * for a total of ${totalSatoshisNeeded}), plus whatever would be required in order
+ * to pay the fee to unlock and spend the outputs used to provide the additional satoshis.
+ */
+export class WERR_INSUFFICIENT_FUNDS extends WalletError {
+  /**
+   * @param totalSatoshisNeeded Total satoshis required to fund transactions after net of required inputs and outputs.
+   * @param moreSatoshisNeeded Shortfall on total satoshis required to fund transactions after net of required inputs and outputs.
+   */
+  constructor(
+    public totalSatoshisNeeded: number,
+    public moreSatoshisNeeded: number
+  ) {
+    super(
+      'WERR_INSUFFICIENT_FUNDS',
+      `Insufficient funds in the available inputs to cover the cost of the required outputs and the transaction fee (${moreSatoshisNeeded} more satoshis are needed, for a total of ${totalSatoshisNeeded}), plus whatever would be required in order to pay the fee to unlock and spend the outputs used to provide the additional satoshis.`
+    )
+  }
+}
+
+export class WERR_INVALID_PUBLIC_KEY extends WalletError {
+  /**
+   * @param key The invalid public key that caused the error.
+   * @param environment Optional environment flag to control whether the key is included in the message.
+   */
+  constructor(
+    public key: string,
+    network: WalletNetwork = 'mainnet'
+  ) {
+    const message =
+      network === 'mainnet'
+        ? `The provided public key "${key}" is invalid or malformed.`
+        : `The provided public key is invalid or malformed.`
+    super('WERR_INVALID_PUBLIC_KEY', message)
+  }
+}

package/src/sdk/WalletError.ts

@@ -0,0 +1,136 @@
+import {
+  ErrorCodeString10To40Bytes,
+  ErrorDescriptionString20To200Bytes,
+  WalletErrorObject
+} from '@bsv/sdk'
+
+/**
+ * Derived class constructors should use the derived class name as the value for `name`,
+ * and an internationalizable constant string for `message`.
+ *
+ * If a derived class intends to wrap another WalletError, the public property should
+ * be named `walletError` and will be recovered by `fromUnknown`.
+ *
+ * Optionaly, the derived class `message` can include template parameters passed in
+ * to the constructor. See WERR_MISSING_PARAMETER for an example.
+ *
+ * To avoid derived class name colisions, packages should include a package specific
+ * identifier after the 'WERR_' prefix. e.g. 'WERR_FOO_' as the prefix for Foo package error
+ * classes.
+ */
+export class WalletError extends Error implements WalletErrorObject {
+  // Facilitates detection of Error objects from non-error return values.
+  isError: true = true
+
+  constructor(
+    name: string,
+    message: string,
+    stack?: string,
+    public details?: Record<string, string>
+  ) {
+    super(message)
+    this.name = name
+    if (stack) this.stack = stack
+  }
+
+  /**
+   * Error class compatible accessor for  `code`.
+   */
+  get code(): ErrorCodeString10To40Bytes {
+    return this.name
+  }
+  set code(v: ErrorCodeString10To40Bytes) {
+    this.name = v
+  }
+
+  /**
+   * Error class compatible accessor for `description`.
+   */
+  get description(): ErrorDescriptionString20To200Bytes {
+    return this.message
+  }
+  set description(v: ErrorDescriptionString20To200Bytes) {
+    this.message = v
+  }
+
+  /**
+   * 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
+    let name = 'WERR_UNKNOWN'
+    let message = ''
+    let stack: string | undefined
+    const details: Record<string, string> = {}
+    if (err !== null && typeof err === 'object') {
+      if (err['name'] === 'Error' || err['name'] === 'FetchError')
+        name = err['code'] || err['status'] || 'WERR_UNKNOWN'
+      else name = err['name'] || err['code'] || err['status'] || 'WERR_UNKNOWN'
+      if (typeof name !== 'string') name = 'WERR_UNKNOWN'
+
+      message = err['message'] || err['description'] || ''
+      if (typeof message !== 'string') message = 'WERR_UNKNOWN'
+
+      if (typeof err['stack'] === 'string') stack = err['stack']
+
+      if (typeof err['sql'] === 'string') details.sql = err['sql']
+      if (typeof err['sqlMessage'] === 'string')
+        details.sqlMessage = err['sqlMessage']
+    }
+    const e = new WalletError(
+      name,
+      message,
+      stack,
+      Object.keys(details).length > 0 ? details : undefined
+    )
+    if (err !== null && typeof err === 'object') {
+      for (const [key, value] of Object.entries(err)) {
+        if (
+          key !== 'walletError' &&
+          typeof value !== 'string' &&
+          typeof value !== 'number' &&
+          !Array.isArray(value)
+        )
+          continue
+        switch (key) {
+          case 'walletError':
+            e[key] = WalletError.fromUnknown(value)
+            break
+          case 'status':
+            break
+          case 'name':
+            break
+          case 'code':
+            break
+          case 'message':
+            break
+          case 'description':
+            break
+          case 'stack':
+            break
+          case 'sql':
+            break
+          case 'sqlMessage':
+            break
+          default:
+            e[key] = value
+            break
+        }
+      }
+    }
+    return e
+  }
+
+  /**
+   * @returns standard HTTP error status object with status property set to 'error'.
+   */
+  asStatus(): { status: string; code: string; description: string } {
+    return {
+      status: 'error',
+      code: this.name,
+      description: this.message
+    }
+  }
+}