@bsv/wallet-toolbox 1.1.0

package/src/storage/sync/index.ts

@@ -0,0 +1 @@
+export * from './StorageMySQLDojoReader'

package/src/utility/README.md

@@ -0,0 +1,3 @@
+# Utility
+
+Useful stuff that's shared by more than one high level function but not important enough to merrit its own bucket ":-)"

package/src/utility/ScriptTemplateSABPPP.ts

@@ -0,0 +1,79 @@
+import { HexString, KeyDeriver, KeyDeriverApi, WalletProtocol } from '@bsv/sdk'
+import { asBsvSdkPrivateKey, verifyTruthy } from './index.client'
+import {
+  LockingScript,
+  P2PKH,
+  PrivateKey,
+  Script,
+  ScriptTemplate,
+  Transaction,
+  UnlockingScript
+} from '@bsv/sdk'
+
+export interface ScriptTemplateParamsSABPPP {
+  derivationPrefix?: string
+  derivationSuffix?: string
+  keyDeriver: KeyDeriverApi
+}
+
+export const brc29ProtocolID: WalletProtocol = [2, '3241645161d8']
+
+export class ScriptTemplateSABPPP implements ScriptTemplate {
+  p2pkh: P2PKH
+
+  constructor(public params: ScriptTemplateParamsSABPPP) {
+    this.p2pkh = new P2PKH()
+
+    verifyTruthy(params.derivationPrefix)
+    verifyTruthy(params.derivationSuffix)
+  }
+
+  getKeyID() {
+    return `${this.params.derivationPrefix} ${this.params.derivationSuffix}`
+  }
+
+  getKeyDeriver(privKey: PrivateKey | HexString): KeyDeriverApi {
+    if (typeof privKey === 'string') privKey = PrivateKey.fromHex(privKey)
+    if (
+      !this.params.keyDeriver ||
+      this.params.keyDeriver.rootKey.toHex() !== privKey.toHex()
+    )
+      return new KeyDeriver(privKey)
+    return this.params.keyDeriver
+  }
+
+  lock(lockerPrivKey: string, unlockerPubKey: string): LockingScript {
+    const address = this.getKeyDeriver(lockerPrivKey)
+      .derivePublicKey(brc29ProtocolID, this.getKeyID(), unlockerPubKey, false)
+      .toAddress()
+    const r = this.p2pkh.lock(address)
+    return r
+  }
+
+  unlock(
+    unlockerPrivKey: string,
+    lockerPubKey: string,
+    sourceSatoshis?: number,
+    lockingScript?: Script
+  ): {
+    sign: (tx: Transaction, inputIndex: number) => Promise<UnlockingScript>
+    estimateLength: (tx?: Transaction, inputIndex?: number) => Promise<number>
+  } {
+    const derivedPrivateKey = this.getKeyDeriver(unlockerPrivKey)
+      .derivePrivateKey(brc29ProtocolID, this.getKeyID(), lockerPubKey)
+      .toHex()
+    const r = this.p2pkh.unlock(
+      asBsvSdkPrivateKey(derivedPrivateKey),
+      'all',
+      false,
+      sourceSatoshis,
+      lockingScript
+    )
+    return r
+  }
+
+  /**
+   * P2PKH unlock estimateLength is a constant
+   */
+  unlockLength = 108
+}

package/src/utility/index.all.ts

@@ -0,0 +1,7 @@
+export * from './stampLog'
+export * from './ScriptTemplateSABPPP'
+export * from './parseTxScriptOffsets'
+export * from './tscProofToMerklePath'
+export * from './utilityHelpers'
+
+export * from './utilityHelpers.buffer'

package/src/utility/index.client.ts

@@ -0,0 +1,7 @@
+export * from './stampLog'
+export * from './ScriptTemplateSABPPP'
+export * from './parseTxScriptOffsets'
+export * from './tscProofToMerklePath'
+export * from './utilityHelpers'
+
+export * from './utilityHelpers.noBuffer'

package/src/utility/parseTxScriptOffsets.ts

@@ -0,0 +1,29 @@
+import { Utils as SdkUtils } from '@bsv/sdk'
+
+export interface TxScriptOffsets {
+  inputs: { vin: number; offset: number; length: number }[]
+  outputs: { vout: number; offset: number; length: number }[]
+}
+
+export function parseTxScriptOffsets(rawTx: number[]): TxScriptOffsets {
+  const br = new SdkUtils.Reader(rawTx)
+  const inputs: { vin: number; offset: number; length: number }[] = []
+  const outputs: { vout: number; offset: number; length: number }[] = []
+
+  br.pos += 4 // version
+  const inputsLength = br.readVarIntNum()
+  for (let i = 0; i < inputsLength; i++) {
+    br.pos += 36 // txid and vout
+    const scriptLength = br.readVarIntNum()
+    inputs.push({ vin: i, offset: br.pos, length: scriptLength })
+    br.pos += scriptLength + 4 // script and sequence
+  }
+  const outputsLength = br.readVarIntNum()
+  for (let i = 0; i < outputsLength; i++) {
+    br.pos += 8 // satoshis
+    const scriptLength = br.readVarIntNum()
+    outputs.push({ vout: i, offset: br.pos, length: scriptLength })
+    br.pos += scriptLength
+  }
+  return { inputs, outputs }
+}

package/src/utility/stampLog.ts

@@ -0,0 +1,73 @@
+/**
+ * If a log is being kept, add a time stamped line.
+ * @param log  Optional time stamped log to extend, or an object with a log property to update
+ * @param lineToAdd Content to add to line.
+ * @returns undefined or log extended by time stamped `lineToAdd` and new line.
+ */
+export function stampLog(
+  log: string | undefined | { log?: string },
+  lineToAdd: string
+): string | undefined {
+  const add = `${new Date().toISOString()} ${lineToAdd}\n`
+  if (typeof log === 'object' && typeof log.log === 'string')
+    return (log.log = log.log + add)
+  if (typeof log === 'string') return log + add
+  return undefined
+}
+
+/**
+ * Replaces individual timestamps with delta msecs.
+ * Looks for two network crossings and adjusts clock for clock skew if found.
+ * Assumes log built by repeated calls to `stampLog`
+ * @param log Each logged event starts with ISO time stamp, space, rest of line, terminated by `\n`.
+ * @returns reformated multi-line event log
+ */
+export function stampLogFormat(log?: string): string {
+  if (typeof log !== 'string') return ''
+  const logLines = log.split('\n')
+  const data: {
+    when: number
+    rest: string
+    delta: number
+    newClock: boolean
+  }[] = []
+  let last = 0
+  const newClocks: number[] = []
+  for (const line of logLines) {
+    const spaceAt = line.indexOf(' ')
+    if (spaceAt > -1) {
+      const when = new Date(line.substring(0, spaceAt)).getTime()
+      const rest = line.substring(spaceAt + 1)
+      const delta = when - (last || when)
+      const newClock = rest.indexOf('**NETWORK**') > -1
+      if (newClock) newClocks.push(data.length)
+      data.push({ when, rest, delta, newClock })
+      last = when
+    }
+  }
+  const total = data[data.length - 1].when - data[0].when
+  if (newClocks.length % 2 === 0) {
+    // Adjust for paired network crossing times and clock skew between clocks.
+    let network = total
+    let lastNewClock = 0
+    for (const newClock of newClocks) {
+      network -= data[newClock - 1].when - data[lastNewClock].when
+      lastNewClock = newClock
+    }
+    network -= data[data.length - 1].when - data[lastNewClock].when
+    let networks = newClocks.length
+    for (const newClock of newClocks) {
+      const n = networks > 1 ? Math.floor(network / networks) : network
+      data[newClock].delta = n
+      network -= n
+      networks--
+    }
+  }
+  let log2 = `${new Date(data[0].when).toISOString()} Total = ${total} msecs\n`
+  for (const d of data) {
+    let df = d.delta.toString()
+    df = `${' '.repeat(8 - df.length)}${df}`
+    log2 += `${df} ${d.rest}\n`
+  }
+  return log2
+}

package/src/utility/tscProofToMerklePath.ts

@@ -0,0 +1,51 @@
+import { MerklePath } from '@bsv/sdk'
+
+export interface TscMerkleProofApi {
+  height: number
+  index: number
+  nodes: string[]
+}
+
+export function convertProofToMerklePath(
+  txid: string,
+  proof: TscMerkleProofApi
+): MerklePath {
+  const blockHeight = proof.height
+  const treeHeight = proof.nodes.length
+  type Leaf = {
+    offset: number
+    hash?: string
+    txid?: boolean
+    duplicate?: boolean
+  }
+  const path: Leaf[][] = Array(treeHeight)
+    .fill(0)
+    .map(() => [])
+  let index = proof.index
+  for (let level = 0; level < treeHeight; level++) {
+    const node = proof.nodes[level]
+    const isOdd = index % 2 === 1
+    const offset = isOdd ? index - 1 : index + 1
+    const leaf: Leaf = { offset }
+    if (node === '*' || (level === 0 && node === txid)) {
+      leaf.duplicate = true
+    } else {
+      leaf.hash = node
+    }
+    path[level].push(leaf)
+    if (level === 0) {
+      const txidLeaf: Leaf = {
+        offset: proof.index,
+        hash: txid,
+        txid: true
+      }
+      if (isOdd) {
+        path[0].push(txidLeaf)
+      } else {
+        path[0].unshift(txidLeaf)
+      }
+    }
+    index = index >> 1
+  }
+  return new MerklePath(blockHeight, path)
+}

package/src/utility/utilityHelpers.buffer.ts

@@ -0,0 +1,43 @@
+/**
+ * Coerce a value to Buffer if currently encoded as a string or
+ * @param val Buffer or string or number[]. If string, encoding param applies. If number[], Buffer.from constructor is used.
+ * @param encoding defaults to 'hex'. Only applies to val of type string
+ * @returns input val if it is a Buffer or new Buffer from string val
+ * @publicbody
+ */
+export function asBuffer(
+  val: Buffer | string | number[],
+  encoding?: BufferEncoding
+): Buffer {
+  let b: Buffer
+  if (Buffer.isBuffer(val)) b = val
+  else if (typeof val === 'string') b = Buffer.from(val, encoding ?? 'hex')
+  else b = Buffer.from(val)
+  return b
+}
+
+/**
+ * Coerce a value to an encoded string if currently a Buffer or number[]
+ * @param val Buffer or string or number[]. If string, encoding param applies. If number[], Buffer.from constructor is used.
+ * @param encoding defaults to 'hex'
+ * @returns input val if it is a string; or if number[], first converted to Buffer then as Buffer; if Buffer encoded using `encoding`
+ * @publicbody
+ */
+export function asString(
+  val: Buffer | string | number[],
+  encoding?: BufferEncoding
+): string {
+  if (Array.isArray(val)) val = Buffer.from(val)
+  return Buffer.isBuffer(val) ? val.toString(encoding ?? 'hex') : val
+}
+
+export function asArray(
+  val: Buffer | string | number[],
+  encoding?: BufferEncoding
+): number[] {
+  let a: number[]
+  if (Array.isArray(val)) a = val
+  else if (Buffer.isBuffer(val)) a = Array.from(val)
+  else a = Array.from(Buffer.from(val, encoding || 'hex'))
+  return a
+}

package/src/utility/utilityHelpers.noBuffer.ts

@@ -0,0 +1,18 @@
+import { Utils } from '@bsv/sdk'
+
+/**
+ * Coerce a value to a hex encoded string if currently a hex encoded string or number[]
+ * @param val string or number[]. If string, encoding must be hex. If number[], each value must be 0..255.
+ * @returns input val if it is a string; or if number[], converts byte values to hex
+ * @publicbody
+ */
+export function asString(val: string | number[]): string {
+  if (typeof val === 'string') return val
+  return Utils.toHex(val)
+}
+
+export function asArray(val: string | number[]): number[] {
+  if (Array.isArray(val)) return val
+  let a: number[] = Utils.toArray(val, 'hex')
+  return a
+}

package/src/utility/utilityHelpers.ts

@@ -0,0 +1,283 @@
+import { HexString, PubKeyHex, WalletInterface, WalletNetwork } from '@bsv/sdk'
+import {
+  Beef,
+  Hash,
+  PrivateKey,
+  PublicKey,
+  Random,
+  Script,
+  Transaction,
+  Utils
+} from '@bsv/sdk'
+import { sdk } from '../index.client'
+import { Chain } from '../sdk/types'
+import { CertOpsWallet } from '../sdk'
+
+export async function getIdentityKey(
+  wallet: CertOpsWallet
+): Promise<PubKeyHex> {
+  return (await wallet.getPublicKey({ identityKey: true })).publicKey
+}
+
+export function toWalletNetwork(chain: Chain): WalletNetwork {
+  return chain === 'main' ? 'mainnet' : 'testnet'
+}
+
+export function makeAtomicBeef(
+  tx: Transaction,
+  beef: number[] | Beef
+): number[] {
+  if (Array.isArray(beef)) beef = Beef.fromBinary(beef)
+  beef.mergeTransaction(tx)
+  return beef.toBinaryAtomic(tx.id('hex'))
+}
+
+/**
+ * Coerce a bsv transaction encoded as a hex string, serialized array, or Transaction to Transaction
+ * If tx is already a Transaction, just return it.
+ * @publicbody
+ */
+export function asBsvSdkTx(
+  tx: HexString | number[] | Transaction
+): Transaction {
+  if (Array.isArray(tx)) {
+    tx = Transaction.fromBinary(tx)
+  } else if (typeof tx === 'string') {
+    tx = Transaction.fromHex(tx)
+  }
+  return tx
+}
+
+/**
+ * Coerce a bsv script encoded as a hex string, serialized array, or Script to Script
+ * If script is already a Script, just return it.
+ * @publicbody
+ */
+export function asBsvSdkScript(script: HexString | number[] | Script): Script {
+  if (Array.isArray(script)) {
+    script = Script.fromBinary(script)
+  } else if (typeof script === 'string') {
+    script = Script.fromHex(script)
+  }
+  return script
+}
+
+/**
+ * @param privKey bitcoin private key in 32 byte hex string form
+ * @returns @bsv/sdk PrivateKey
+ */
+export function asBsvSdkPrivateKey(privKey: string): PrivateKey {
+  return PrivateKey.fromString(privKey, 'hex')
+}
+
+/**
+ * @param pubKey bitcoin public key in standard compressed key hex string form
+ * @returns @bsv/sdk PublicKey
+ */
+export function asBsvSdkPublickKey(pubKey: string): PublicKey {
+  return PublicKey.fromString(pubKey)
+}
+
+/**
+ * Helper function.
+ *
+ * Verifies that a possibly optional value has a value.
+ */
+export function verifyTruthy<T>(
+  v: T | null | undefined,
+  description?: string
+): T {
+  if (v == null)
+    throw new sdk.WERR_INTERNAL(description ?? 'A truthy value is required.')
+  return v
+}
+
+/**
+ * Helper function.
+ *
+ * Verifies that a hex string is trimmed and lower case.
+ */
+export function verifyHexString(v: string): string {
+  if (typeof v !== 'string')
+    throw new sdk.WERR_INTERNAL('A string is required.')
+  v = v.trim().toLowerCase()
+  return v
+}
+
+/**
+ * Helper function.
+ *
+ * Verifies that an optional or null hex string is undefined or a trimmed lowercase string.
+ */
+export function verifyOptionalHexString(v?: string | null): string | undefined {
+  if (!v) return undefined
+  return verifyHexString(v)
+}
+
+/**
+ * Helper function.
+ *
+ * Verifies that an optional or null number has a numeric value.
+ */
+export function verifyNumber(v: number | null | undefined): number {
+  if (typeof v !== 'number')
+    throw new sdk.WERR_INTERNAL('A number is required.')
+  return v
+}
+
+/**
+ * Helper function.
+ *
+ * Verifies that an optional or null number has a numeric value.
+ */
+export function verifyInteger(v: number | null | undefined): number {
+  if (typeof v !== 'number' || !Number.isInteger(v))
+    throw new sdk.WERR_INTERNAL('An integer is required.')
+  return v
+}
+
+/**
+ * Helper function.
+ *
+ * Verifies that a database record identifier is an integer greater than zero.
+ */
+export function verifyId(id: number | undefined | null): number {
+  id = verifyInteger(id)
+  if (id < 1)
+    throw new sdk.WERR_INTERNAL(`id must be valid integer greater than zero.`)
+  return id
+}
+
+/**
+ * Helper function.
+ *
+ * @throws WERR_BAD_REQUEST if results has length greater than one.
+ *
+ * @returns results[0] or undefined if length is zero.
+ */
+export function verifyOneOrNone<T>(results: T[]): T | undefined {
+  if (results.length > 1)
+    throw new sdk.WERR_BAD_REQUEST('Result must be unique.')
+  return results[0]
+}
+
+/**
+ * Helper function.
+ *
+ * @throws WERR_BAD_REQUEST if results has length other than one.
+ *
+ * @returns results[0].
+ */
+export function verifyOne<T>(results: T[], errorDescrition?: string): T {
+  if (results.length !== 1)
+    throw new sdk.WERR_BAD_REQUEST(
+      errorDescrition ?? 'Result must exist and be unique.'
+    )
+  return results[0]
+}
+
+/**
+ * Returns an await'able Promise that resolves in the given number of msecs.
+ * @publicbody
+ */
+export function wait(msecs: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, msecs))
+}
+
+/**
+ * @returns count cryptographically secure random bytes as array of bytes
+ */
+export function randomBytes(count: number): number[] {
+  return Random(count)
+}
+
+/**
+ * @returns count cryptographically secure random bytes as hex encoded string
+ */
+export function randomBytesHex(count: number): string {
+  return Utils.toHex(Random(count))
+}
+
+/**
+ * @returns count cryptographically secure random bytes as base64 encoded string
+ */
+export function randomBytesBase64(count: number): string {
+  return Utils.toBase64(Random(count))
+}
+
+export function validateSecondsSinceEpoch(time: number): Date {
+  const date = new Date(time * 1000)
+  if (
+    date.getTime() / 1000 !== time ||
+    time < 1600000000 ||
+    time > 100000000000
+  ) {
+    throw new sdk.WERR_INVALID_PARAMETER(
+      'time',
+      `valid "since epoch" unix time`
+    )
+  }
+  return date
+}
+
+/**
+ * Compares lengths and direct equality of values.
+ * @param arr1
+ * @param arr2
+ * @returns
+ */
+export function arraysEqual(arr1: Number[], arr2: Number[]) {
+  if (arr1.length !== arr2.length) return false
+  for (let i = 0; i < arr1.length; i++) {
+    if (arr1[i] !== arr2[i]) return false
+  }
+  return true
+}
+
+export function optionalArraysEqual(arr1?: Number[], arr2?: Number[]) {
+  if (!arr1 && !arr2) return true
+  if (!arr1 || !arr2) return false
+  return arraysEqual(arr1, arr2)
+}
+
+export function maxDate(d1?: Date, d2?: Date): Date | undefined {
+  if (d1 && d2) {
+    if (d1 > d2) return d1
+    return d2
+  }
+  if (d1) return d1
+  if (d2) return d2
+  return undefined
+}
+
+/**
+ * Calculate the SHA256 hash of an array of bytes
+ * @returns sha256 hash of buffer contents.
+ * @publicbody
+ */
+export function sha256Hash(data: number[]): number[] {
+  const first = new Hash.SHA256().update(data).digest()
+  return first
+}
+
+/**
+ * Calculate the SHA256 hash of the SHA256 hash of an array of bytes.
+ * @param data an array of bytes
+ * @returns double sha256 hash of data, byte 0 of hash first.
+ * @publicbody
+ */
+export function doubleSha256HashLE(data: number[]): number[] {
+  const first = new Hash.SHA256().update(data).digest()
+  const second = new Hash.SHA256().update(first).digest()
+  return second
+}
+
+/**
+ * Calculate the SHA256 hash of the SHA256 hash of an array of bytes.
+ * @param data is an array of bytes.
+ * @returns reversed (big-endian) double sha256 hash of data, byte 31 of hash first.
+ * @publicbody
+ */
+export function doubleSha256BE(data: number[]): number[] {
+  return doubleSha256HashLE(data).reverse()
+}

package/test/Wallet/StorageClient/storageClient.man.test.ts

@@ -0,0 +1,55 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+import { StorageClient } from '../../../src/index.all'
+import { _tu, TestWalletOnly } from '../../utils/TestUtilsWalletStorage'
+
+/**
+ * WARNING: This test hangs the commit to master automated test run cycle if included in regular tests...
+ */
+
+describe('walletStorageClient test', () => {
+  jest.setTimeout(99999999)
+
+  const env = _tu.getEnv('test')
+  const testName = () => expect.getState().currentTestName || 'test'
+
+  const ctxs: TestWalletOnly[] = []
+
+  beforeAll(async () => {
+    //_tu.mockPostServicesAsSuccess(ctxs)
+  })
+
+  afterAll(async () => {
+    for (const ctx of ctxs) {
+      await ctx.storage.destroy()
+    }
+  })
+
+  test('1 backup to client', async () => {
+    const ctx = await _tu.createLegacyWalletSQLiteCopy('walletStorageClient1')
+    ctxs.push(ctx)
+    const { wallet, storage } = ctx
+
+    {
+      const client = new StorageClient(
+        wallet,
+        'https://staging-dojo.babbage.systems'
+      )
+      await storage.addWalletStorageProvider(client)
+      await storage.updateBackups()
+    }
+  })
+
+  test('2 create storage client wallet', async () => {
+    const ctx = await _tu.createTestWalletWithStorageClient({
+      rootKeyHex: '1'.repeat(64),
+      endpointUrl: 'https://staging-dojo.babbage.systems'
+    })
+    ctxs.push(ctx)
+    const { wallet, storage } = ctx
+
+    {
+      const auth = await storage.getAuth()
+      expect(auth.userId).toBeTruthy()
+    }
+  })
+})