@bsv/wallet-toolbox 1.7.14 → 1.7.16

package/mobile/node_modules/@bsv/sdk/src/wallet/WalletClient.ts

@@ -0,0 +1,504 @@
+import {
+  AcquireCertificateArgs,
+  AcquireCertificateResult,
+  Base64String,
+  BasketStringUnder300Bytes,
+  BooleanDefaultFalse,
+  Byte,
+  CertificateFieldNameUnder50Bytes,
+  CreateActionArgs,
+  CreateActionResult,
+  DescriptionString5to50Bytes,
+  DiscoverCertificatesResult,
+  HexString,
+  InternalizeActionArgs,
+  ISOTimestampString,
+  KeyIDStringUnder800Bytes,
+  ListActionsArgs,
+  ListActionsResult,
+  ListCertificatesResult,
+  ListOutputsArgs,
+  ListOutputsResult,
+  OriginatorDomainNameStringUnder250Bytes,
+  OutpointString,
+  PositiveInteger,
+  PositiveIntegerDefault10Max10000,
+  PositiveIntegerOrZero,
+  ProtocolString5To400Bytes,
+  ProveCertificateArgs,
+  ProveCertificateResult,
+  PubKeyHex,
+  SecurityLevel,
+  SignActionArgs,
+  SignActionResult,
+  VersionString7To30Bytes,
+  WalletInterface,
+  AuthenticatedResult
+} from './Wallet.interfaces.js'
+import WindowCWISubstrate from './substrates/window.CWI.js'
+import XDMSubstrate from './substrates/XDM.js'
+import WalletWireTransceiver from './substrates/WalletWireTransceiver.js'
+import HTTPWalletWire from './substrates/HTTPWalletWire.js'
+import HTTPWalletJSON from './substrates/HTTPWalletJSON.js'
+import ReactNativeWebView from './substrates/ReactNativeWebView.js'
+import {
+  validateAbortActionArgs,
+  validateAcquireDirectCertificateArgs,
+  validateAcquireIssuanceCertificateArgs,
+  validateCreateActionArgs,
+  validateDiscoverByAttributesArgs,
+  validateDiscoverByIdentityKeyArgs,
+  validateInternalizeActionArgs,
+  validateListActionsArgs,
+  validateListCertificatesArgs,
+  validateListOutputsArgs,
+  validateProveCertificateArgs,
+  validateRelinquishCertificateArgs,
+  validateRelinquishOutputArgs,
+  validateSignActionArgs
+} from './validationHelpers.js'
+import { WERR_INVALID_PARAMETER } from './WERR_INVALID_PARAMETER.js'
+
+const MAX_XDM_RESPONSE_WAIT = 200
+
+/**
+ * The SDK is how applications communicate with wallets over a communications substrate.
+ */
+export default class WalletClient implements WalletInterface {
+  public substrate: 'auto' | WalletInterface
+  originator?: OriginatorDomainNameStringUnder250Bytes
+  constructor (
+    substrate:
+    | 'auto'
+    | 'Cicada'
+    | 'XDM'
+    | 'window.CWI'
+    | 'json-api'
+    | 'react-native'
+    | 'secure-json-api'
+    | WalletInterface = 'auto',
+    originator?: OriginatorDomainNameStringUnder250Bytes
+  ) {
+    if (substrate === 'Cicada') {
+      substrate = new WalletWireTransceiver(new HTTPWalletWire(originator))
+    }
+    if (substrate === 'window.CWI') substrate = new WindowCWISubstrate()
+    if (substrate === 'XDM') substrate = new XDMSubstrate()
+    if (substrate === 'json-api') substrate = new HTTPWalletJSON(originator)
+    if (substrate === 'react-native') substrate = new ReactNativeWebView(originator)
+    if (substrate === 'secure-json-api') substrate = new HTTPWalletJSON(originator, 'https://localhost:2121')
+    this.substrate = substrate
+    this.originator = originator
+  }
+
+  async connectToSubstrate (): Promise<void> {
+    if (typeof this.substrate === 'object') {
+      return // substrate is already connected
+    }
+
+    const attemptSubstrate = async (factory: () => WalletInterface, timeout?: number): Promise<{ success: boolean, sub?: WalletInterface }> => {
+      try {
+        const sub = factory()
+        let result
+        if (typeof timeout === 'number') {
+          result = await Promise.race([
+            sub.getVersion({}),
+            new Promise<never>((_resolve, reject) =>
+              setTimeout(() => reject(new Error('Timed out.')), timeout)
+            )
+          ])
+        } else {
+          result = await sub.getVersion({})
+        }
+        if (typeof result !== 'object' || typeof result.version !== 'string') {
+          return { success: false }
+        }
+        return { success: true, sub }
+      } catch {
+        return { success: false }
+      }
+    }
+
+    // Try fast substrates first
+    const fastAttempts = [
+      attemptSubstrate(() => new WindowCWISubstrate()),
+      attemptSubstrate(() => new HTTPWalletJSON(this.originator, 'https://localhost:2121')),
+      attemptSubstrate(() => new HTTPWalletJSON(this.originator)),
+      attemptSubstrate(() => new ReactNativeWebView(this.originator)),
+      attemptSubstrate(() => new WalletWireTransceiver(new HTTPWalletWire(this.originator)))
+    ]
+
+    const fastResults = await Promise.allSettled(fastAttempts)
+    const fastSuccessful = fastResults
+      .filter((r): r is PromiseFulfilledResult<{ success: boolean, sub?: WalletInterface }> => r.status === 'fulfilled' && r.value.success && r.value.sub !== undefined)
+      .map(r => r.value.sub as WalletInterface)
+
+    if (fastSuccessful.length > 0) {
+      this.substrate = fastSuccessful[0]
+      return
+    }
+
+    // Fall back to slower XDM substrate
+    const xdmResult = await attemptSubstrate(() => new XDMSubstrate(), MAX_XDM_RESPONSE_WAIT)
+    if (xdmResult.success && xdmResult.sub !== undefined) {
+      this.substrate = xdmResult.sub
+    } else {
+      throw new Error(
+        'No wallet available over any communication substrate. Install a BSV wallet today!'
+      )
+    }
+  }
+
+  async createAction (args: CreateActionArgs): Promise<CreateActionResult> {
+    validateCreateActionArgs(args)
+    await this.connectToSubstrate()
+    return await (this.substrate as WalletInterface).createAction(
+      args,
+      this.originator
+    )
+  }
+
+  async signAction (args: SignActionArgs): Promise<SignActionResult> {
+    validateSignActionArgs(args)
+    await this.connectToSubstrate()
+    return await (this.substrate as WalletInterface).signAction(
+      args,
+      this.originator
+    )
+  }
+
+  async abortAction (args: {
+    reference: Base64String
+  }): Promise<{ aborted: true }> {
+    validateAbortActionArgs(args)
+    await this.connectToSubstrate()
+    return await (this.substrate as WalletInterface).abortAction(
+      args,
+      this.originator
+    )
+  }
+
+  async listActions (args: ListActionsArgs): Promise<ListActionsResult> {
+    validateListActionsArgs(args)
+    await this.connectToSubstrate()
+    return await (this.substrate as WalletInterface).listActions(
+      args,
+      this.originator
+    )
+  }
+
+  async internalizeAction (
+    args: InternalizeActionArgs
+  ): Promise<{ accepted: true }> {
+    validateInternalizeActionArgs(args)
+    await this.connectToSubstrate()
+    return await (this.substrate as WalletInterface).internalizeAction(
+      args,
+      this.originator
+    )
+  }
+
+  async listOutputs (args: ListOutputsArgs): Promise<ListOutputsResult> {
+    validateListOutputsArgs(args)
+    await this.connectToSubstrate()
+    return await (this.substrate as WalletInterface).listOutputs(
+      args,
+      this.originator
+    )
+  }
+
+  async relinquishOutput (args: {
+    basket: BasketStringUnder300Bytes
+    output: OutpointString
+  }): Promise<{ relinquished: true }> {
+    validateRelinquishOutputArgs(args)
+    await this.connectToSubstrate()
+    return await (this.substrate as WalletInterface).relinquishOutput(
+      args,
+      this.originator
+    )
+  }
+
+  async getPublicKey (args: {
+    identityKey?: true
+    protocolID?: [SecurityLevel, ProtocolString5To400Bytes]
+    keyID?: KeyIDStringUnder800Bytes
+    privileged?: BooleanDefaultFalse
+    privilegedReason?: DescriptionString5to50Bytes
+    counterparty?: PubKeyHex | 'self' | 'anyone'
+    forSelf?: BooleanDefaultFalse
+  }): Promise<{ publicKey: PubKeyHex }> {
+    await this.connectToSubstrate()
+    return await (this.substrate as WalletInterface).getPublicKey(
+      args,
+      this.originator
+    )
+  }
+
+  async revealCounterpartyKeyLinkage (args: {
+    counterparty: PubKeyHex
+    verifier: PubKeyHex
+    privilegedReason?: DescriptionString5to50Bytes
+    privileged?: BooleanDefaultFalse
+  }): Promise<{
+      prover: PubKeyHex
+      verifier: PubKeyHex
+      counterparty: PubKeyHex
+      revelationTime: ISOTimestampString
+      encryptedLinkage: Byte[]
+      encryptedLinkageProof: Byte[]
+    }> {
+    await this.connectToSubstrate()
+    return await (
+      this.substrate as WalletInterface
+    ).revealCounterpartyKeyLinkage(args, this.originator)
+  }
+
+  async revealSpecificKeyLinkage (args: {
+    counterparty: PubKeyHex
+    verifier: PubKeyHex
+    protocolID: [SecurityLevel, ProtocolString5To400Bytes]
+    keyID: KeyIDStringUnder800Bytes
+    privilegedReason?: DescriptionString5to50Bytes
+    privileged?: BooleanDefaultFalse
+  }): Promise<{
+      prover: PubKeyHex
+      verifier: PubKeyHex
+      counterparty: PubKeyHex
+      protocolID: [SecurityLevel, ProtocolString5To400Bytes]
+      keyID: KeyIDStringUnder800Bytes
+      encryptedLinkage: Byte[]
+      encryptedLinkageProof: Byte[]
+      proofType: Byte
+    }> {
+    await this.connectToSubstrate()
+    return await (this.substrate as WalletInterface).revealSpecificKeyLinkage(
+      args,
+      this.originator
+    )
+  }
+
+  async encrypt (args: {
+    plaintext: Byte[]
+    protocolID: [SecurityLevel, ProtocolString5To400Bytes]
+    keyID: KeyIDStringUnder800Bytes
+    privilegedReason?: DescriptionString5to50Bytes
+    counterparty?: PubKeyHex | 'self' | 'anyone'
+    privileged?: BooleanDefaultFalse
+  }): Promise<{ ciphertext: Byte[] }> {
+    await this.connectToSubstrate()
+    return await (this.substrate as WalletInterface).encrypt(
+      args,
+      this.originator
+    )
+  }
+
+  async decrypt (args: {
+    ciphertext: Byte[]
+    protocolID: [SecurityLevel, ProtocolString5To400Bytes]
+    keyID: KeyIDStringUnder800Bytes
+    privilegedReason?: DescriptionString5to50Bytes
+    counterparty?: PubKeyHex | 'self' | 'anyone'
+    privileged?: BooleanDefaultFalse
+  }): Promise<{ plaintext: Byte[] }> {
+    await this.connectToSubstrate()
+    return await (this.substrate as WalletInterface).decrypt(
+      args,
+      this.originator
+    )
+  }
+
+  async createHmac (args: {
+    data: Byte[]
+    protocolID: [SecurityLevel, ProtocolString5To400Bytes]
+    keyID: KeyIDStringUnder800Bytes
+    privilegedReason?: DescriptionString5to50Bytes
+    counterparty?: PubKeyHex | 'self' | 'anyone'
+    privileged?: BooleanDefaultFalse
+  }): Promise<{ hmac: Byte[] }> {
+    await this.connectToSubstrate()
+    return await (this.substrate as WalletInterface).createHmac(
+      args,
+      this.originator
+    )
+  }
+
+  async verifyHmac (args: {
+    data: Byte[]
+    hmac: Byte[]
+    protocolID: [SecurityLevel, ProtocolString5To400Bytes]
+    keyID: KeyIDStringUnder800Bytes
+    privilegedReason?: DescriptionString5to50Bytes
+    counterparty?: PubKeyHex | 'self' | 'anyone'
+    privileged?: BooleanDefaultFalse
+  }): Promise<{ valid: true }> {
+    await this.connectToSubstrate()
+    return await (this.substrate as WalletInterface).verifyHmac(
+      args,
+      this.originator
+    )
+  }
+
+  async createSignature (args: {
+    data?: Byte[]
+    hashToDirectlySign?: Byte[]
+    protocolID: [SecurityLevel, ProtocolString5To400Bytes]
+    keyID: KeyIDStringUnder800Bytes
+    privilegedReason?: DescriptionString5to50Bytes
+    counterparty?: PubKeyHex | 'self' | 'anyone'
+    privileged?: BooleanDefaultFalse
+  }): Promise<{ signature: Byte[] }> {
+    await this.connectToSubstrate()
+    return await (this.substrate as WalletInterface).createSignature(
+      args,
+      this.originator
+    )
+  }
+
+  async verifySignature (args: {
+    data?: Byte[]
+    hashToDirectlyVerify?: Byte[]
+    signature: Byte[]
+    protocolID: [SecurityLevel, ProtocolString5To400Bytes]
+    keyID: KeyIDStringUnder800Bytes
+    privilegedReason?: DescriptionString5to50Bytes
+    counterparty?: PubKeyHex | 'self' | 'anyone'
+    forSelf?: BooleanDefaultFalse
+    privileged?: BooleanDefaultFalse
+  }): Promise<{ valid: true }> {
+    await this.connectToSubstrate()
+    return await (this.substrate as WalletInterface).verifySignature(
+      args,
+      this.originator
+    )
+  }
+
+  async acquireCertificate (
+    args: AcquireCertificateArgs
+  ): Promise<AcquireCertificateResult> {
+    if (args.acquisitionProtocol === 'direct') { validateAcquireDirectCertificateArgs(args) } else if (args.acquisitionProtocol === 'issuance') { validateAcquireIssuanceCertificateArgs(args) } else { throw new WERR_INVALID_PARAMETER('acquisitionProtocol', `valid. ${String(args.acquisitionProtocol)} is unrecognized.`) }
+    await this.connectToSubstrate()
+    return await (this.substrate as WalletInterface).acquireCertificate(
+      args,
+      this.originator
+    )
+  }
+
+  async listCertificates (args: {
+    certifiers: PubKeyHex[]
+    types: Base64String[]
+    limit?: PositiveIntegerDefault10Max10000
+    offset?: PositiveIntegerOrZero
+    privileged?: BooleanDefaultFalse
+    privilegedReason?: DescriptionString5to50Bytes
+  }): Promise<ListCertificatesResult> {
+    validateListCertificatesArgs(args)
+    await this.connectToSubstrate()
+    return await (this.substrate as WalletInterface).listCertificates(
+      args,
+      this.originator
+    )
+  }
+
+  async proveCertificate (
+    args: ProveCertificateArgs
+  ): Promise<ProveCertificateResult> {
+    validateProveCertificateArgs(args)
+    await this.connectToSubstrate()
+    return await (this.substrate as WalletInterface).proveCertificate(
+      args,
+      this.originator
+    )
+  }
+
+  async relinquishCertificate (args: {
+    type: Base64String
+    serialNumber: Base64String
+    certifier: PubKeyHex
+  }): Promise<{ relinquished: true }> {
+    validateRelinquishCertificateArgs(args)
+    await this.connectToSubstrate()
+    return await (this.substrate as WalletInterface).relinquishCertificate(
+      args,
+      this.originator
+    )
+  }
+
+  async discoverByIdentityKey (args: {
+    identityKey: PubKeyHex
+    limit?: PositiveIntegerDefault10Max10000
+    offset?: PositiveIntegerOrZero
+  }): Promise<DiscoverCertificatesResult> {
+    validateDiscoverByIdentityKeyArgs(args)
+    await this.connectToSubstrate()
+    return await (this.substrate as WalletInterface).discoverByIdentityKey(
+      args,
+      this.originator
+    )
+  }
+
+  async discoverByAttributes (args: {
+    attributes: Record<CertificateFieldNameUnder50Bytes, string>
+    limit?: PositiveIntegerDefault10Max10000
+    offset?: PositiveIntegerOrZero
+  }): Promise<DiscoverCertificatesResult> {
+    validateDiscoverByAttributesArgs(args)
+    await this.connectToSubstrate()
+    return await (this.substrate as WalletInterface).discoverByAttributes(
+      args,
+      this.originator
+    )
+  }
+
+  async isAuthenticated (args: object = {}): Promise<AuthenticatedResult> {
+    await this.connectToSubstrate()
+    return await (this.substrate as WalletInterface).isAuthenticated(
+      args,
+      this.originator
+    )
+  }
+
+  async waitForAuthentication (args: object = {}): Promise<{ authenticated: true }> {
+    await this.connectToSubstrate()
+    return await (this.substrate as WalletInterface).waitForAuthentication(
+      args,
+      this.originator
+    )
+  }
+
+  async getHeight (args: object = {}): Promise<{ height: PositiveInteger }> {
+    await this.connectToSubstrate()
+    return await (this.substrate as WalletInterface).getHeight(
+      args,
+      this.originator
+    )
+  }
+
+  async getHeaderForHeight (args: {
+    height: PositiveInteger
+  }): Promise<{ header: HexString }> {
+    await this.connectToSubstrate()
+    return await (this.substrate as WalletInterface).getHeaderForHeight(
+      args,
+      this.originator
+    )
+  }
+
+  async getNetwork (args: object = {}): Promise<{ network: 'mainnet' | 'testnet' }> {
+    await this.connectToSubstrate()
+    return await (this.substrate as WalletInterface).getNetwork(
+      args,
+      this.originator
+    )
+  }
+
+  async getVersion (
+    args: object = {}
+  ): Promise<{ version: VersionString7To30Bytes }> {
+    await this.connectToSubstrate()
+    return await (this.substrate as WalletInterface).getVersion(
+      args,
+      this.originator
+    )
+  }
+}

package/mobile/node_modules/@bsv/sdk/src/wallet/WalletError.ts

@@ -0,0 +1,81 @@
+export class WalletError extends Error {
+  code: number
+  isError: boolean = true
+
+  constructor (message: string, code = 1, stack?: string) {
+    super(message)
+    this.code = code
+    this.name = this.constructor.name
+
+    if (stack !== undefined && stack !== null && stack !== '') {
+      this.stack = stack
+    } else {
+      Error.captureStackTrace(this, this.constructor)
+    }
+  }
+
+  /**
+   * Safely serializes a WalletError (including special cases), Error or unknown error to JSON.
+   *
+   * Safely means avoiding deep, large, circular issues.
+   *
+   * Example deserialization can be found in HTTPWalletJSON.ts of bsv ts-sdk.
+   *
+   * @param error
+   * @returns stringified JSON representation of the error such that it can be deserialized to a WalletError.
+   */
+  static unknownToJson (error: any): string {
+    let e: any | undefined
+    if (error.isError === true && String(error.name).startsWith('WERR_')) {
+      e = {
+        name: error.name,
+        message: error.message,
+        isError: true
+      }
+      if (e.name === 'WERR_REVIEW_ACTIONS') {
+        e.reviewActionResults = error.reviewActionResults
+        e.sendWithResults = error.sendWithResults
+        e.txid = error.txid
+        e.tx = error.tx
+        e.noSendChange = error.noSendChange
+        e.code = 5
+      } else if (e.name === 'WERR_INVALID_PARAMETER') {
+        e.parameter = error.parameter
+        e.code = 6
+      } else if (e.name === 'WERR_INSUFFICIENT_FUNDS') {
+        e.totalSatoshisNeeded = error.totalSatoshisNeeded
+        e.moreSatoshisNeeded = error.moreSatoshisNeeded
+        e.code = 7
+      }
+    } else if (error instanceof Error) {
+      e = {
+        name: error.constructor.name,
+        message: error.message,
+        isError: true
+      }
+    } else {
+      e = {
+        name: 'WERR_UNKNOWN',
+        message: String(error),
+        isError: true
+      }
+    }
+    const json = JSON.stringify(e)
+    return json
+  }
+}
+
+// NOTE: Enum values must not exceed the UInt8 range (0–255)
+export enum walletErrors {
+  unknownError = 1,
+  unsupportedAction = 2,
+  invalidHmac = 3,
+  invalidSignature = 4,
+  reviewActions = 5,
+  invalidParameter = 6,
+  insufficientFunds = 7,
+}
+
+export type WalletErrorCode = keyof typeof walletErrors
+
+export default WalletError

package/mobile/node_modules/@bsv/sdk/src/wallet/WalletLoggerInterface.ts

@@ -0,0 +1,85 @@
+/**
+ * A console-like interface for logging within wallet operations.
+ *
+ * Intended to reflect a subset of standard `Console` interface methods used by `Wallet`
+ */
+
+export interface WalletLoggerInterface {
+  /**
+   * Increases indentation of subsequent lines.
+   *
+   * If one or more `label`s are provided, those are printed first without the
+   * additional indentation.
+   */
+  group: (...label: any[]) => void
+  /**
+   * Decreases indentation of subsequent lines.
+   */
+  groupEnd: () => void
+  /**
+   * Log a message.
+   */
+  log: (message?: any, ...optionalParams: any[]) => void
+  /**
+   * Log an error message.
+   */
+  error: (message?: any, ...optionalParams: any[]) => void
+  /**
+   * Loggers may accumulate data instead of immediately handling it.
+   *
+   * Loggers that do not accumulate should not implement this method.
+   *
+   * @returns undefined if this was the origin and data has been logged, else a WalletLoggerJson object.
+   */
+  flush?: () => object | undefined
+
+  /**
+   * Merge log data from another logger.
+   *
+   * Typically used to merge log data from network request.
+   *
+   * @param log
+   * @returns
+   */
+  merge?: (log: WalletLoggerInterface) => void
+
+  /**
+   * Optional. Logging levels that may influence what is logged.
+   *
+   * 'error' Only requests resulting in an exception should be logged.
+   * 'warn' Also log requests that succeed but with an abnormal condition.
+   * 'info' Also log normal successful requests.
+   * 'debug' Add input parm and result details where possible.
+   * 'trace' Instead of adding debug details, focus on execution path and timing.
+   */
+  level?: 'error' | 'warn' | 'info' | 'debug' | 'trace'
+
+  /**
+   * Valid if an accumulating logger. Count of `group` calls without matching `groupEnd`.
+   */
+  indent?: number
+  /**
+   * True if this is an accumulating logger and the logger belongs to the object servicing the initial request.
+   */
+  isOrigin?: boolean
+  /**
+   * True if this is an accumulating logger and an error was logged.
+   */
+  isError?: boolean
+
+  /**
+   * Optional array of accumulated logged data and errors.
+   */
+  logs?: WalletLoggerLog[]
+}
+
+export interface WalletLoggerLog {
+  when: number
+  indent: number
+  log: string
+  isError?: boolean
+  isBegin?: boolean
+  isEnd?: boolean
+}
+
+export type MakeWalletLogger = (log?: string | WalletLoggerInterface) => WalletLoggerInterface