@bsv/wallet-toolbox 1.1.0

package/src/storage/schema/entities/EntityBase.ts

@@ -0,0 +1,214 @@
+import { sdk, StorageProvider } from '../../../index.client'
+
+export type EntityStorage = StorageProvider
+
+export abstract class EntityBase<T> {
+  api: T
+
+  constructor(api: T) {
+    this.api = api
+  }
+
+  /**
+   * Standard property for entity database Id
+   */
+  abstract get id(): number
+
+  /**
+   * Name of derived entity class
+   */
+  abstract get entityName(): string
+
+  /**
+   * Schema table name of entity
+   */
+  abstract get entityTable(): string
+
+  /**
+   * On construction, an entity may decode properties of the `api` object,
+   * such as JSON stringified objects.
+   *
+   * The `updateApi` method must re-encode the current state of those decoded properties
+   * into the `api` object.
+   *
+   * Used by the `toApi` method to return an updated `api` object.
+   */
+  abstract updateApi(): void
+
+  /**
+   * Tests for equality or 'merge' / 'convergent' equality if syncMap is provided.
+   *
+   * 'convergent' equality must satisfy (A sync B) equals (B sync A)
+   *
+   * @param ei
+   * @param syncMap
+   */
+  abstract equals(ei: T, syncMap?: SyncMap): boolean
+
+  /**
+   * Perform a 'merge' / 'convergent' equality migration of state
+   * to this new local entity which was constructed
+   * as a copy of the external object.
+   *
+   * @param userId local userId
+   * @param syncMap
+   */
+  abstract mergeNew(
+    storage: EntityStorage,
+    userId: number,
+    syncMap: SyncMap,
+    trx?: sdk.TrxToken
+  ): Promise<void>
+
+  /**
+   * Perform a 'merge' / 'convergent' equality migration of state
+   * from external `ei` to this existing local entity.
+   *
+   * @param ei
+   * @param syncMap
+   * @returns true iff entity state changed and was updated to storage
+   */
+  abstract mergeExisting(
+    storage: EntityStorage,
+    since: Date | undefined,
+    ei: T,
+    syncMap: SyncMap,
+    trx?: sdk.TrxToken
+  ): Promise<boolean>
+
+  /**
+   * An entity may decode properties of the underlying Api object on construction.
+   *
+   * The `toApi` method forces an `updateApi` before returning the underlying,
+   * now updated, Api object.
+   *
+   * @returns The underlying Api object with any entity decoded properties updated.
+   */
+  toApi(): T {
+    this.updateApi()
+    return this.api
+  }
+}
+
+export interface EntitySyncMap {
+  entityName: string
+
+  /**
+   * Maps foreign ids to local ids
+   * Some entities don't have idMaps (CertificateField, TxLabelMap and OutputTagMap)
+   */
+  idMap: Record<number, number>
+
+  /**
+   * the maximum updated_at value seen for this entity over chunks received
+   * during this udpate cycle.
+   */
+  maxUpdated_at?: Date
+
+  /**
+   * The cummulative count of items of this entity type received over all the `SyncChunk`s
+   * since the `since` was last updated.
+   *
+   * This is the `offset` value to use for the next SyncChunk request.
+   */
+  count: number
+}
+
+export interface SyncMap {
+  provenTx: EntitySyncMap
+  outputBasket: EntitySyncMap
+  transaction: EntitySyncMap
+  provenTxReq: EntitySyncMap
+  txLabel: EntitySyncMap
+  txLabelMap: EntitySyncMap
+  output: EntitySyncMap
+  outputTag: EntitySyncMap
+  outputTagMap: EntitySyncMap
+  certificate: EntitySyncMap
+  certificateField: EntitySyncMap
+  commission: EntitySyncMap
+}
+
+export function createSyncMap(): SyncMap {
+  const r: SyncMap = {
+    provenTx: {
+      entityName: 'provenTx',
+      idMap: {},
+      maxUpdated_at: undefined,
+      count: 0
+    },
+    outputBasket: {
+      entityName: 'outputBasket',
+      idMap: {},
+      maxUpdated_at: undefined,
+      count: 0
+    },
+    transaction: {
+      entityName: 'transaction',
+      idMap: {},
+      maxUpdated_at: undefined,
+      count: 0
+    },
+    provenTxReq: {
+      entityName: 'provenTxReq',
+      idMap: {},
+      maxUpdated_at: undefined,
+      count: 0
+    },
+    txLabel: {
+      entityName: 'txLabel',
+      idMap: {},
+      maxUpdated_at: undefined,
+      count: 0
+    },
+    txLabelMap: {
+      entityName: 'txLabelMap',
+      idMap: {},
+      maxUpdated_at: undefined,
+      count: 0
+    },
+    output: {
+      entityName: 'output',
+      idMap: {},
+      maxUpdated_at: undefined,
+      count: 0
+    },
+    outputTag: {
+      entityName: 'outputTag',
+      idMap: {},
+      maxUpdated_at: undefined,
+      count: 0
+    },
+    outputTagMap: {
+      entityName: 'outputTagMap',
+      idMap: {},
+      maxUpdated_at: undefined,
+      count: 0
+    },
+    certificate: {
+      entityName: 'certificate',
+      idMap: {},
+      maxUpdated_at: undefined,
+      count: 0
+    },
+    certificateField: {
+      entityName: 'certificateField',
+      idMap: {},
+      maxUpdated_at: undefined,
+      count: 0
+    },
+    commission: {
+      entityName: 'commission',
+      idMap: {},
+      maxUpdated_at: undefined,
+      count: 0
+    }
+  }
+  return r
+}
+
+export interface SyncError {
+  code: string
+  description: string
+  stack?: string
+}

package/src/storage/schema/entities/MergeEntity.ts

@@ -0,0 +1,79 @@
+import { entity } from '../../index.client'
+import { maxDate, sdk, verifyId } from '../../../index.client'
+import { EntityBase } from './EntityBase'
+
+/**
+ * @param API one of the storage table interfaces.
+ * @param DE the corresponding entity class
+ */
+export class MergeEntity<
+  API extends sdk.EntityTimeStamp,
+  DE extends EntityBase<API>
+> {
+  idMap: Record<number, number>
+
+  constructor(
+    public stateArray: API[] | undefined,
+    public find: (
+      storage: entity.EntityStorage,
+      userId: number,
+      ei: API,
+      syncMap: entity.SyncMap,
+      trx?: sdk.TrxToken
+    ) => Promise<{ found: boolean; eo: DE; eiId: number }>,
+    /** id map for primary id of API and DE object. */
+    public esm: entity.EntitySyncMap
+  ) {
+    this.idMap = esm.idMap
+  }
+
+  updateSyncMap(map: Record<number, number>, inId: number, outId: number) {
+    const i = verifyId(inId)
+    const o = verifyId(outId)
+    if (map[i] === undefined) {
+      map[i] = o
+    } else if (map[i] !== o)
+      throw new sdk.WERR_INTERNAL(
+        `updateSyncMap map[${inId}] can't override ${map[i]} with ${o}`
+      )
+  }
+
+  /**
+   * @param since date of current sync chunk
+   */
+  async merge(
+    since: Date | undefined,
+    storage: entity.EntityStorage,
+    userId: number,
+    syncMap: entity.SyncMap,
+    trx?: sdk.TrxToken
+  ): Promise<{ inserts: number; updates: number }> {
+    let inserts = 0,
+      updates = 0
+    if (!this.stateArray) return { inserts, updates }
+    for (const ei of this.stateArray) {
+      this.esm.maxUpdated_at = maxDate(this.esm.maxUpdated_at, ei.updated_at)
+      /**
+       * TODO:
+       * Switch to using syncMap. If the ei id is in the map its an existing merge, else its a new merge.
+       */
+      const { found, eo, eiId } = await this.find(
+        storage,
+        userId,
+        ei,
+        syncMap,
+        trx
+      )
+      if (found) {
+        if (await eo.mergeExisting(storage, since, ei, syncMap, trx)) {
+          updates++
+        }
+      } else {
+        await eo.mergeNew(storage, userId, syncMap, trx)
+        inserts++
+      }
+      if (eiId > -1) this.updateSyncMap(this.idMap, eiId, eo.id)
+    }
+    return { inserts, updates }
+  }
+}

package/src/storage/schema/entities/Output.ts

@@ -0,0 +1,323 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+import { MerklePath } from '@bsv/sdk'
+import {
+  arraysEqual,
+  entity,
+  optionalArraysEqual,
+  sdk,
+  table,
+  verifyId,
+  verifyOneOrNone
+} from '../../../index.client'
+import { EntityBase } from '.'
+
+export class Output extends EntityBase<table.Output> {
+  constructor(api?: table.Output) {
+    const now = new Date()
+    super(
+      api || {
+        outputId: 0,
+        created_at: now,
+        updated_at: now,
+        userId: 0,
+        transactionId: 0,
+        spendable: false,
+        change: false,
+        satoshis: 0,
+        outputDescription: '',
+        vout: 0,
+        type: '',
+        providedBy: 'you',
+        purpose: '',
+
+        txid: undefined,
+        basketId: undefined,
+        spentBy: undefined,
+        derivationPrefix: undefined,
+        derivationSuffix: undefined,
+        senderIdentityKey: undefined,
+        customInstructions: undefined,
+        spendingDescription: undefined,
+        scriptLength: undefined,
+        scriptOffset: undefined,
+        lockingScript: undefined
+      }
+    )
+  }
+
+  override updateApi(): void {
+    /* nothing needed yet... */
+  }
+
+  get outputId() {
+    return this.api.outputId
+  }
+  set outputId(v: number) {
+    this.api.outputId = v
+  }
+  get created_at() {
+    return this.api.created_at
+  }
+  set created_at(v: Date) {
+    this.api.created_at = v
+  }
+  get updated_at() {
+    return this.api.updated_at
+  }
+  set updated_at(v: Date) {
+    this.api.updated_at = v
+  }
+  get userId() {
+    return this.api.userId
+  }
+  set userId(v: number) {
+    this.api.userId = v
+  }
+  get transactionId() {
+    return this.api.transactionId
+  }
+  set transactionId(v: number) {
+    this.api.transactionId = v
+  }
+  get basketId() {
+    return this.api.basketId
+  }
+  set basketId(v: number | undefined) {
+    this.api.basketId = v
+  }
+  get spentBy() {
+    return this.api.spentBy
+  }
+  set spentBy(v: number | undefined) {
+    this.api.spentBy = v
+  }
+  get vout() {
+    return this.api.vout
+  }
+  set vout(v: number) {
+    this.api.vout = v
+  }
+  get satoshis() {
+    return this.api.satoshis
+  }
+  set satoshis(v: number) {
+    this.api.satoshis = v
+  }
+  get outputDescription() {
+    return this.api.outputDescription
+  }
+  set outputDescription(v: string) {
+    this.api.outputDescription = v
+  }
+  get spendable() {
+    return this.api.spendable
+  }
+  set spendable(v: boolean) {
+    this.api.spendable = v
+  }
+  get change() {
+    return this.api.change
+  }
+  set change(v: boolean) {
+    this.api.change = v
+  }
+
+  get txid() {
+    return this.api.txid
+  }
+  set txid(v: string | undefined) {
+    this.api.txid = v
+  }
+  get type() {
+    return this.api.type
+  }
+  set type(v: string) {
+    this.api.type = v
+  }
+  get providedBy() {
+    return this.api.providedBy
+  }
+  set providedBy(v: sdk.StorageProvidedBy) {
+    this.api.providedBy = v
+  }
+  get purpose() {
+    return this.api.purpose
+  }
+  set purpose(v: string) {
+    this.api.purpose = v
+  }
+  get spendingDescription() {
+    return this.api.spendingDescription
+  }
+  set spendingDescription(v: string | undefined) {
+    this.api.spendingDescription = v
+  }
+  get derivationPrefix() {
+    return this.api.derivationPrefix
+  }
+  set derivationPrefix(v: string | undefined) {
+    this.api.derivationPrefix = v
+  }
+  get derivationSuffix() {
+    return this.api.derivationSuffix
+  }
+  set derivationSuffix(v: string | undefined) {
+    this.api.derivationSuffix = v
+  }
+  get senderIdentityKey() {
+    return this.api.senderIdentityKey
+  }
+  set senderIdentityKey(v: string | undefined) {
+    this.api.senderIdentityKey = v
+  }
+  get customInstructions() {
+    return this.api.customInstructions
+  }
+  set customInstructions(v: string | undefined) {
+    this.api.customInstructions = v
+  }
+  get lockingScript() {
+    return this.api.lockingScript
+  }
+  set lockingScript(v: number[] | undefined) {
+    this.api.lockingScript = v
+  }
+  get scriptLength() {
+    return this.api.scriptLength
+  }
+  set scriptLength(v: number | undefined) {
+    this.api.scriptLength = v
+  }
+  get scriptOffset() {
+    return this.api.scriptOffset
+  }
+  set scriptOffset(v: number | undefined) {
+    this.api.scriptOffset = v
+  }
+
+  override get id(): number {
+    return this.api.outputId
+  }
+  override set id(v: number) {
+    this.api.outputId = v
+  }
+  override get entityName(): string {
+    return 'Output'
+  }
+  override get entityTable(): string {
+    return 'outputs'
+  }
+
+  override equals(
+    ei: table.Output,
+    syncMap?: entity.SyncMap | undefined
+  ): boolean {
+    if (
+      this.transactionId !==
+        (syncMap
+          ? syncMap.transaction.idMap[ei.transactionId]
+          : ei.transactionId) ||
+      this.basketId !==
+        (syncMap && ei.basketId
+          ? syncMap.outputBasket.idMap[ei.basketId]
+          : ei.basketId) ||
+      this.spentBy !==
+        (syncMap && ei.spentBy
+          ? syncMap.transaction.idMap[ei.spentBy]
+          : ei.spentBy) ||
+      this.vout !== ei.vout ||
+      this.satoshis !== ei.satoshis ||
+      this.spendable !== ei.spendable ||
+      this.change !== ei.change ||
+      this.txid !== ei.txid ||
+      this.type !== ei.type ||
+      this.providedBy !== ei.providedBy ||
+      this.purpose !== ei.purpose ||
+      this.outputDescription !== ei.outputDescription ||
+      this.spendingDescription !== ei.spendingDescription ||
+      this.derivationPrefix !== ei.derivationPrefix ||
+      this.derivationSuffix !== ei.derivationSuffix ||
+      this.senderIdentityKey !== ei.senderIdentityKey ||
+      this.customInstructions !== ei.customInstructions ||
+      !optionalArraysEqual(this.lockingScript, ei.lockingScript) ||
+      this.scriptLength !== ei.scriptLength ||
+      this.scriptOffset !== ei.scriptOffset
+    )
+      return false
+
+    return true
+  }
+
+  static async mergeFind(
+    storage: entity.EntityStorage,
+    userId: number,
+    ei: table.Output,
+    syncMap: entity.SyncMap,
+    trx?: sdk.TrxToken
+  ): Promise<{ found: boolean; eo: entity.Output; eiId: number }> {
+    const transactionId = syncMap.transaction.idMap[ei.transactionId]
+    const basketId = ei.basketId
+      ? syncMap.outputBasket.idMap[ei.basketId]
+      : null
+    const ef = verifyOneOrNone(
+      await storage.findOutputs({
+        partial: { userId, transactionId, vout: ei.vout },
+        trx
+      })
+    )
+    return {
+      found: !!ef,
+      eo: new entity.Output(ef || { ...ei }),
+      eiId: verifyId(ei.outputId)
+    }
+  }
+
+  override async mergeNew(
+    storage: entity.EntityStorage,
+    userId: number,
+    syncMap: entity.SyncMap,
+    trx?: sdk.TrxToken
+  ): Promise<void> {
+    this.userId = userId
+    this.basketId = this.basketId
+      ? syncMap.outputBasket.idMap[this.basketId]
+      : undefined
+    this.transactionId = syncMap.transaction.idMap[this.transactionId]
+    this.spentBy = this.spentBy
+      ? syncMap.transaction.idMap[this.spentBy]
+      : undefined
+    this.outputId = 0
+    this.outputId = await storage.insertOutput(this.toApi(), trx)
+  }
+
+  override async mergeExisting(
+    storage: entity.EntityStorage,
+    since: Date | undefined,
+    ei: table.Output,
+    syncMap: entity.SyncMap,
+    trx?: sdk.TrxToken
+  ): Promise<boolean> {
+    let wasMerged = false
+    if (ei.updated_at > this.updated_at) {
+      this.spentBy = ei.spentBy
+        ? syncMap.transaction.idMap[ei.spentBy]
+        : undefined
+      this.spendable = ei.spendable
+      this.change = ei.change
+      this.type = ei.type
+      this.providedBy = ei.providedBy
+      this.purpose = ei.purpose
+      this.outputDescription = ei.outputDescription
+      this.spendingDescription = ei.spendingDescription
+      this.senderIdentityKey = ei.senderIdentityKey
+      this.customInstructions = ei.customInstructions
+      this.scriptLength = ei.scriptLength
+      this.scriptOffset = ei.scriptOffset
+      this.lockingScript = ei.lockingScript
+      this.updated_at = new Date()
+      await storage.updateOutput(this.id, this.toApi(), trx)
+      wasMerged = true
+    }
+    return wasMerged
+  }
+}