@bsv/wallet-toolbox 1.1.0

package/src/storage/methods/getBeefForTransaction.ts

@@ -0,0 +1,143 @@
+import { Beef } from '@bsv/sdk'
+import {
+  asBsvSdkTx,
+  entity,
+  sdk,
+  StorageProvider,
+  verifyTruthy
+} from '../../index.client'
+
+/**
+ * Creates a `Beef` to support the validity of a transaction identified by its `txid`.
+ *
+ * `storage` is used to retrieve proven transactions and their merkle paths,
+ * or proven_tx_req record with beef of external inputs (internal inputs meged by recursion).
+ * Otherwise external services are used.
+ *
+ * `options.maxRecursionDepth` can be set to prevent overly deep chained dependencies. Will throw ERR_EXTSVS_ENVELOPE_DEPTH if exceeded.
+ *
+ * If `trustSelf` is true, a partial `Beef` will be returned where transactions known by `storage` to
+ * be valid by verified proof are represented solely by 'txid'.
+ *
+ * If `knownTxids` is defined, any 'txid' required by the `Beef` that appears in the array is represented solely as a 'known' txid.
+ *
+ * @param storage the chain on which txid exists.
+ * @param txid the transaction hash for which an envelope is requested.
+ * @param options
+ */
+export async function getBeefForTransaction(
+  storage: StorageProvider,
+  txid: string,
+  options: sdk.StorageGetBeefOptions
+): Promise<Beef> {
+  const beef =
+    // deserialize mergeToBeef if it is an array
+    Array.isArray(options.mergeToBeef)
+      ? Beef.fromBinary(options.mergeToBeef)
+      : // otherwise if undefined create a new Beef
+        options.mergeToBeef || new Beef()
+
+  await mergeBeefForTransactionRecurse(beef, storage, txid, options, 0)
+
+  return beef
+}
+
+/**
+ * @returns rawTx if txid known to network, if merkle proof available then also proven result is valid.
+ */
+async function getProvenOrRawTxFromServices(
+  storage: StorageProvider,
+  txid: string,
+  options: sdk.StorageGetBeefOptions
+): Promise<sdk.ProvenOrRawTx> {
+  const services = storage.getServices()
+  const por = await entity.ProvenTx.fromTxid(txid, await storage.getServices())
+  if (por.proven && !options.ignoreStorage && !options.ignoreNewProven) {
+    por.proven.provenTxId = await storage.insertProvenTx(por.proven.toApi())
+  }
+  return { proven: por.proven?.toApi(), rawTx: por.rawTx }
+}
+
+async function mergeBeefForTransactionRecurse(
+  beef: Beef,
+  storage: StorageProvider,
+  txid: string,
+  options: sdk.StorageGetBeefOptions,
+  recursionDepth: number
+): Promise<Beef> {
+  const maxDepth = storage.maxRecursionDepth
+  if (maxDepth && maxDepth <= recursionDepth)
+    throw new sdk.WERR_INVALID_OPERATION(
+      `Maximum BEEF depth exceeded. Limit is ${storage.maxRecursionDepth}`
+    )
+
+  if (options.knownTxids && options.knownTxids.indexOf(txid) > -1) {
+    // This txid is one of the txids the caller claims to already know are valid...
+    beef.mergeTxidOnly(txid)
+    return beef
+  }
+
+  if (!options.ignoreStorage) {
+    // if we can use storage, ask storage if it has the txid
+    const knownBeef = await storage.getValidBeefForTxid(
+      txid,
+      beef,
+      options.trustSelf,
+      options.knownTxids
+    )
+    if (knownBeef) return knownBeef
+  }
+
+  if (options.ignoreServices)
+    throw new sdk.WERR_INVALID_PARAMETER(
+      `txid ${txid}`,
+      `valid transaction on chain ${storage.chain}`
+    )
+
+  // if storage doesn't know about txid, use services
+  // to find it and if it has a proof, remember it.
+  const r = await getProvenOrRawTxFromServices(storage, txid, options)
+
+  if (
+    r.proven &&
+    options.minProofLevel &&
+    options.minProofLevel > recursionDepth
+  ) {
+    // ignore proof at this recursion depth
+    r.proven = undefined
+  }
+
+  if (r.proven) {
+    // storage has proven this txid,
+    // merge both the raw transaction and its merkle path
+    beef.mergeRawTx(r.proven.rawTx)
+    beef.mergeBump(new entity.ProvenTx(r.proven).getMerklePath())
+    return beef
+  }
+
+  if (!r.rawTx)
+    throw new sdk.WERR_INVALID_PARAMETER(
+      `txid ${txid}`,
+      `valid transaction on chain ${storage.chain}`
+    )
+
+  // merge the raw transaction and recurse over its inputs.
+  beef.mergeRawTx(r.rawTx!)
+  // recurse inputs
+  const tx = asBsvSdkTx(r.rawTx!)
+  for (const input of tx.inputs) {
+    const inputTxid = verifyTruthy(input.sourceTXID)
+    if (!beef.findTxid(inputTxid)) {
+      // Only if the txid is not already in the list of beef transactions.
+      await mergeBeefForTransactionRecurse(
+        beef,
+        storage,
+        inputTxid,
+        options,
+        recursionDepth + 1
+      )
+    }
+  }
+
+  return beef
+}

package/src/storage/methods/getSyncChunk.ts

@@ -0,0 +1,330 @@
+import { sdk, table, verifyTruthy } from '../../index.client'
+import { StorageReader } from '../StorageReader'
+
+/**
+ * Gets the next sync chunk of updated data from un-remoted storage (could be using a remote DB connection).
+ * @param storage
+ * @param args
+ * @returns
+ */
+export async function getSyncChunk(
+  storage: StorageReader,
+  args: sdk.RequestSyncChunkArgs
+): Promise<sdk.SyncChunk> {
+  const r: sdk.SyncChunk = {
+    fromStorageIdentityKey: '',
+    toStorageIdentityKey: '',
+    userIdentityKey: args.identityKey
+  }
+
+  let itemCount = args.maxItems
+  let roughSize = args.maxRoughSize
+  let i = 0
+  let done = false
+
+  const user = verifyTruthy(
+    await storage.findUserByIdentityKey(args.identityKey)
+  )
+  if (!args.since || user.updated_at > args.since) r.user = user
+
+  const chunkers: ChunkerArgs[] = [
+    {
+      name: 'provenTx',
+      maxDivider: 100,
+      preAdd: () => {
+        r.provenTxs = []
+      },
+      addItem: (i: table.ProvenTx) => {
+        r.provenTxs!.push(i)
+      },
+      findItems: async (
+        storage: StorageReader,
+        args: sdk.FindForUserSincePagedArgs
+      ) => {
+        return await storage.getProvenTxsForUser(args)
+      }
+    },
+    {
+      name: 'outputBasket',
+      maxDivider: 1,
+      preAdd: () => {
+        r.outputBaskets = []
+      },
+      addItem: (i: table.OutputBasket) => {
+        r.outputBaskets!.push(i)
+      },
+      findItems: async (
+        storage: StorageReader,
+        args: sdk.FindForUserSincePagedArgs
+      ) => {
+        return await storage.findOutputBaskets({
+          partial: { userId: args.userId },
+          since: args.since,
+          paged: args.paged
+        })
+      }
+    },
+    {
+      name: 'outputTag',
+      maxDivider: 1,
+      preAdd: () => {
+        r.outputTags = []
+      },
+      addItem: (i: table.OutputTag) => {
+        r.outputTags!.push(i)
+      },
+      findItems: async (
+        storage: StorageReader,
+        args: sdk.FindForUserSincePagedArgs
+      ) => {
+        return await storage.findOutputTags({
+          partial: { userId: args.userId },
+          since: args.since,
+          paged: args.paged
+        })
+      }
+    },
+    {
+      name: 'txLabel',
+      maxDivider: 1,
+      preAdd: () => {
+        r.txLabels = []
+      },
+      addItem: (i: table.TxLabel) => {
+        r.txLabels!.push(i)
+      },
+      findItems: async (
+        storage: StorageReader,
+        args: sdk.FindForUserSincePagedArgs
+      ) => {
+        return await storage.findTxLabels({
+          partial: { userId: args.userId },
+          since: args.since,
+          paged: args.paged
+        })
+      }
+    },
+    {
+      name: 'transaction',
+      maxDivider: 25,
+      preAdd: () => {
+        r.transactions = []
+      },
+      addItem: (i: table.Transaction) => {
+        r.transactions!.push(i)
+      },
+      findItems: async (
+        storage: StorageReader,
+        args: sdk.FindForUserSincePagedArgs
+      ) => {
+        return await storage.findTransactions({
+          partial: { userId: args.userId },
+          since: args.since,
+          paged: args.paged
+        })
+      }
+    },
+    {
+      name: 'output',
+      maxDivider: 25,
+      preAdd: () => {
+        r.outputs = []
+      },
+      addItem: (i: table.Output) => {
+        r.outputs!.push(i)
+      },
+      findItems: async (
+        storage: StorageReader,
+        args: sdk.FindForUserSincePagedArgs
+      ) => {
+        return await storage.findOutputs({
+          partial: { userId: args.userId },
+          since: args.since,
+          paged: args.paged
+        })
+      }
+    },
+    {
+      name: 'txLabelMap',
+      maxDivider: 1,
+      preAdd: () => {
+        r.txLabelMaps = []
+      },
+      addItem: (i: table.TxLabelMap) => {
+        r.txLabelMaps!.push(i)
+      },
+      findItems: async (
+        storage: StorageReader,
+        args: sdk.FindForUserSincePagedArgs
+      ) => {
+        return await storage.getTxLabelMapsForUser(args)
+      }
+    },
+    {
+      name: 'outputTagMap',
+      maxDivider: 1,
+      preAdd: () => {
+        r.outputTagMaps = []
+      },
+      addItem: (i: table.OutputTagMap) => {
+        r.outputTagMaps!.push(i)
+      },
+      findItems: async (
+        storage: StorageReader,
+        args: sdk.FindForUserSincePagedArgs
+      ) => {
+        return await storage.getOutputTagMapsForUser(args)
+      }
+    },
+    {
+      name: 'certificate',
+      maxDivider: 25,
+      preAdd: () => {
+        r.certificates = []
+      },
+      addItem: (i: table.Certificate) => {
+        r.certificates!.push(i)
+      },
+      findItems: async (
+        storage: StorageReader,
+        args: sdk.FindForUserSincePagedArgs
+      ) => {
+        return await storage.findCertificates({
+          partial: { userId: args.userId },
+          since: args.since,
+          paged: args.paged
+        })
+      }
+    },
+    {
+      name: 'certificateField',
+      maxDivider: 25,
+      preAdd: () => {
+        r.certificateFields = []
+      },
+      addItem: (i: table.CertificateField) => {
+        r.certificateFields!.push(i)
+      },
+      findItems: async (
+        storage: StorageReader,
+        args: sdk.FindForUserSincePagedArgs
+      ) => {
+        return await storage.findCertificateFields({
+          partial: { userId: args.userId },
+          since: args.since,
+          paged: args.paged
+        })
+      }
+    },
+    {
+      name: 'commission',
+      maxDivider: 25,
+      preAdd: () => {
+        r.commissions = []
+      },
+      addItem: (i: table.Commission) => {
+        r.commissions!.push(i)
+      },
+      findItems: async (
+        storage: StorageReader,
+        args: sdk.FindForUserSincePagedArgs
+      ) => {
+        return await storage.findCommissions({
+          partial: { userId: args.userId },
+          since: args.since,
+          paged: args.paged
+        })
+      }
+    },
+    {
+      name: 'provenTxReq',
+      maxDivider: 100,
+      preAdd: () => {
+        r.provenTxReqs = []
+      },
+      addItem: (i: table.ProvenTxReq) => {
+        r.provenTxReqs!.push(i)
+      },
+      findItems: async (
+        storage: StorageReader,
+        args: sdk.FindForUserSincePagedArgs
+      ) => {
+        return await storage.getProvenTxReqsForUser(args)
+      }
+    }
+  ]
+
+  const addItems = async (a: ChunkerArgs) => {
+    if (i >= args.offsets.length) {
+      done = true
+      return
+    }
+    let { offset, name: oname } = args.offsets[i++]
+    if (a.name !== oname)
+      throw new sdk.WERR_INVALID_PARAMETER(
+        'offsets',
+        `in dependency order. '${a.name}' expected, found ${oname}.`
+      )
+    let preAddCalled = false
+    for (; !done; ) {
+      const limit = Math.min(
+        itemCount,
+        Math.max(10, args.maxItems / a.maxDivider)
+      )
+      if (limit <= 0) break
+      const items = await a.findItems(storage, {
+        userId: user.userId,
+        since: args.since,
+        paged: { limit, offset }
+      })
+      checkEntityValues(items)
+      if (!preAddCalled) {
+        a.preAdd()
+        preAddCalled = true
+      }
+      if (items.length === 0) break
+      for (const item of items) {
+        offset++
+        a.addItem(item)
+        itemCount--
+        roughSize -= JSON.stringify(item).length
+        if (itemCount <= 0 || roughSize < 0) {
+          done = true
+          break
+        }
+      }
+    }
+  }
+
+  for (; !done; ) {
+    for (const c of chunkers) {
+      await addItems(c)
+    }
+  }
+
+  return r
+}
+
+type ChunkerArgs = {
+  name: string
+  maxDivider: number
+  preAdd: () => void
+  addItem: (i: any) => void
+  findItems: (
+    storage: StorageReader,
+    args: sdk.FindForUserSincePagedArgs
+  ) => Promise<any[]>
+}
+
+function checkIsDate(v: any) {
+  if (!(v instanceof Date)) throw new sdk.WERR_INVALID_OPERATION('bad date')
+}
+
+function checkEntityValues(es: object[]) {
+  for (const e of es) {
+    checkIsDate(e['created_at'])
+    checkIsDate(e['updated_at'])
+    for (const key of Object.keys(e))
+      if (e[key] === null) throw new sdk.WERR_INVALID_OPERATION()
+  }
+}