@bopen-io/wallet-toolbox 1.7.18

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

@@ -0,0 +1,210 @@
+import { TrxToken } from '../../../sdk/WalletStorage.interfaces'
+import { StorageProvider } from '../../StorageProvider'
+
+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?: TrxToken): Promise<void>
+
+  /**
+   * Perform a 'merge' / 'convergent' equality migration of state
+   * from external `ei` to this existing local EntityUser
+   *
+   * @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?: 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/EntityCertificate.ts

@@ -0,0 +1,188 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+import { TrxToken } from '../../../sdk/WalletStorage.interfaces'
+import { verifyId, verifyOneOrNone } from '../../../utility/utilityHelpers'
+import { TableCertificate } from '../tables/TableCertificate'
+import { EntityBase, EntityStorage, SyncMap } from './EntityBase'
+
+export class EntityCertificate extends EntityBase<TableCertificate> {
+  constructor(api?: TableCertificate) {
+    const now = new Date()
+    super(
+      api || {
+        certificateId: 0,
+        created_at: now,
+        updated_at: now,
+        userId: 0,
+        type: '',
+        subject: '',
+        verifier: undefined,
+        serialNumber: '',
+        certifier: '',
+        revocationOutpoint: '',
+        signature: '',
+        isDeleted: false
+      }
+    )
+  }
+
+  override updateApi(): void {
+    /* nothing needed yet... */
+  }
+
+  get certificateId() {
+    return this.api.certificateId
+  }
+  set certificateId(v: number) {
+    this.api.certificateId = 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 type() {
+    return this.api.type
+  }
+  set type(v: string) {
+    this.api.type = v
+  }
+  get subject() {
+    return this.api.subject
+  }
+  set subject(v: string) {
+    this.api.subject = v
+  }
+  get verifier() {
+    return this.api.verifier
+  }
+  set verifier(v: string | undefined) {
+    this.api.verifier = v
+  }
+  get serialNumber() {
+    return this.api.serialNumber
+  }
+  set serialNumber(v: string) {
+    this.api.serialNumber = v
+  }
+  get certifier() {
+    return this.api.certifier
+  }
+  set certifier(v: string) {
+    this.api.certifier = v
+  }
+  get revocationOutpoint() {
+    return this.api.revocationOutpoint
+  }
+  set revocationOutpoint(v: string) {
+    this.api.revocationOutpoint = v
+  }
+  get signature() {
+    return this.api.signature
+  }
+  set signature(v: string) {
+    this.api.signature = v
+  }
+  get isDeleted() {
+    return this.api.isDeleted
+  }
+  set isDeleted(v: boolean) {
+    this.api.isDeleted = v
+  }
+
+  //get fields() { return this.api.fields }
+  //set fields(v: Record<string, string> | undefined) { this.api.fields = v }
+
+  override get id(): number {
+    return this.api.certificateId
+  }
+  override set id(v: number) {
+    this.api.certificateId = v
+  }
+  override get entityName(): string {
+    return 'certificate'
+  }
+  override get entityTable(): string {
+    return 'certificates'
+  }
+
+  override equals(ei: TableCertificate, syncMap?: SyncMap): boolean {
+    if (
+      this.type !== ei.type ||
+      this.subject !== ei.subject ||
+      this.serialNumber !== ei.serialNumber ||
+      this.revocationOutpoint !== ei.revocationOutpoint ||
+      this.signature !== ei.signature ||
+      this.verifier !== ei.verifier ||
+      this.isDeleted !== ei.isDeleted
+    )
+      return false
+
+    return true
+  }
+
+  static async mergeFind(
+    storage: EntityStorage,
+    userId: number,
+    ei: TableCertificate,
+    syncMap: SyncMap,
+    trx?: TrxToken
+  ): Promise<{ found: boolean; eo: EntityCertificate; eiId: number }> {
+    const ef = verifyOneOrNone(
+      await storage.findCertificates({
+        partial: {
+          serialNumber: ei.serialNumber,
+          certifier: ei.certifier,
+          userId
+        },
+        trx
+      })
+    )
+    return {
+      found: !!ef,
+      eo: new EntityCertificate(ef || { ...ei }),
+      eiId: verifyId(ei.certificateId)
+    }
+  }
+
+  override async mergeNew(storage: EntityStorage, userId: number, syncMap: SyncMap, trx?: TrxToken): Promise<void> {
+    this.userId = userId
+    this.certificateId = 0
+    this.certificateId = await storage.insertCertificate(this.toApi(), trx)
+  }
+
+  override async mergeExisting(
+    storage: EntityStorage,
+    since: Date | undefined,
+    ei: TableCertificate,
+    syncMap: SyncMap,
+    trx?: TrxToken
+  ): Promise<boolean> {
+    let wasMerged = false
+    if (ei.updated_at > this.updated_at) {
+      this.type = ei.type
+      this.subject = ei.subject
+      this.serialNumber = ei.serialNumber
+      this.revocationOutpoint = ei.revocationOutpoint
+      this.signature = ei.signature
+      this.verifier = ei.verifier
+      this.isDeleted = ei.isDeleted
+      this.updated_at = new Date(Math.max(ei.updated_at.getTime(), this.updated_at.getTime()))
+      await storage.updateCertificate(this.id, this.toApi(), trx)
+      wasMerged = true
+    }
+    return wasMerged
+  }
+}

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

@@ -0,0 +1,136 @@
+import { TrxToken } from '../../../sdk/WalletStorage.interfaces'
+import { WERR_INVALID_OPERATION } from '../../../sdk/WERR_errors'
+import { verifyOneOrNone } from '../../../utility/utilityHelpers'
+import { TableCertificateField } from '../tables/TableCertificateField'
+import { EntityBase, EntityStorage, SyncMap } from './EntityBase'
+
+export class EntityCertificateField extends EntityBase<TableCertificateField> {
+  constructor(api?: TableCertificateField) {
+    const now = new Date()
+    super(
+      api || {
+        created_at: now,
+        updated_at: now,
+        userId: 0,
+        certificateId: 0,
+        fieldName: '',
+        fieldValue: '',
+        masterKey: ''
+      }
+    )
+  }
+
+  override updateApi(): void {
+    /* nothing needed yet... */
+  }
+
+  get userId() {
+    return this.api.userId
+  }
+  set userId(v: number) {
+    this.api.userId = v
+  }
+  get certificateId() {
+    return this.api.certificateId
+  }
+  set certificateId(v: number) {
+    this.api.certificateId = 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 fieldName() {
+    return this.api.fieldName
+  }
+  set fieldName(v: string) {
+    this.api.fieldName = v
+  }
+  get fieldValue() {
+    return this.api.fieldValue
+  }
+  set fieldValue(v: string) {
+    this.api.fieldValue = v
+  }
+  get masterKey() {
+    return this.api.masterKey
+  }
+  set masterKey(v: string) {
+    this.api.masterKey = v
+  }
+
+  override get id(): number {
+    throw new WERR_INVALID_OPERATION('entity has no "id" value')
+  }
+  override get entityName(): string {
+    return 'certificateField'
+  }
+  override get entityTable(): string {
+    return 'certificate_fields'
+  }
+
+  override equals(ei: TableCertificateField, syncMap?: SyncMap | undefined): boolean {
+    if (
+      this.certificateId !== (syncMap ? syncMap.certificate.idMap[ei.certificateId] : ei.certificateId) ||
+      this.fieldName !== ei.fieldName ||
+      this.fieldValue !== ei.fieldValue ||
+      this.masterKey !== ei.masterKey
+    )
+      return false
+
+    return true
+  }
+
+  static async mergeFind(
+    storage: EntityStorage,
+    userId: number,
+    ei: TableCertificateField,
+    syncMap: SyncMap,
+    trx?: TrxToken
+  ): Promise<{ found: boolean; eo: EntityCertificateField; eiId: number }> {
+    const certificateId = syncMap.certificate.idMap[ei.certificateId]
+    const ef = verifyOneOrNone(
+      await storage.findCertificateFields({
+        partial: { certificateId, userId, fieldName: ei.fieldName },
+        trx
+      })
+    )
+    return {
+      found: !!ef,
+      eo: new EntityCertificateField(ef || { ...ei }),
+      eiId: -1
+    }
+  }
+
+  override async mergeNew(storage: EntityStorage, userId: number, syncMap: SyncMap, trx?: TrxToken): Promise<void> {
+    this.certificateId = syncMap.certificate.idMap[this.certificateId]
+    this.userId = userId
+    await storage.insertCertificateField(this.toApi(), trx)
+  }
+
+  override async mergeExisting(
+    storage: EntityStorage,
+    since: Date | undefined,
+    ei: TableCertificateField,
+    syncMap: SyncMap,
+    trx?: TrxToken
+  ): Promise<boolean> {
+    let wasMerged = false
+    if (ei.updated_at > this.updated_at) {
+      this.fieldValue = ei.fieldValue
+      this.masterKey = ei.masterKey
+      this.updated_at = new Date(Math.max(ei.updated_at.getTime(), this.updated_at.getTime()))
+      await storage.updateCertificateField(this.certificateId, this.fieldName, this.toApi(), trx)
+      wasMerged = true
+    }
+    return wasMerged
+  }
+}

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

@@ -0,0 +1,148 @@
+import { TrxToken } from '../../../sdk/WalletStorage.interfaces'
+import { arraysEqual, verifyId, verifyOneOrNone } from '../../../utility/utilityHelpers'
+import { TableCommission } from '../tables/TableCommission'
+import { EntityBase, EntityStorage, SyncMap } from './EntityBase'
+
+export class EntityCommission extends EntityBase<TableCommission> {
+  constructor(api?: TableCommission) {
+    const now = new Date()
+    super(
+      api || {
+        commissionId: 0,
+        created_at: now,
+        updated_at: now,
+        transactionId: 0,
+        userId: 0,
+        isRedeemed: false,
+        keyOffset: '',
+        lockingScript: [],
+        satoshis: 0
+      }
+    )
+  }
+
+  override updateApi(): void {
+    /* nothing needed yet... */
+  }
+
+  get commissionId() {
+    return this.api.commissionId
+  }
+  set commissionId(v: number) {
+    this.api.commissionId = 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 transactionId() {
+    return this.api.transactionId
+  }
+  set transactionId(v: number) {
+    this.api.transactionId = v
+  }
+  get userId() {
+    return this.api.userId
+  }
+  set userId(v: number) {
+    this.api.userId = v
+  }
+  get isRedeemed() {
+    return this.api.isRedeemed
+  }
+  set isRedeemed(v: boolean) {
+    this.api.isRedeemed = v
+  }
+  get keyOffset() {
+    return this.api.keyOffset
+  }
+  set keyOffset(v: string) {
+    this.api.keyOffset = v
+  }
+  get lockingScript() {
+    return this.api.lockingScript
+  }
+  set lockingScript(v: number[]) {
+    this.api.lockingScript = v
+  }
+  get satoshis() {
+    return this.api.satoshis
+  }
+  set satoshis(v: number) {
+    this.api.satoshis = v
+  }
+
+  override get id(): number {
+    return this.api.commissionId
+  }
+  override set id(v: number) {
+    this.api.commissionId = v
+  }
+  override get entityName(): string {
+    return 'commission'
+  }
+  override get entityTable(): string {
+    return 'commissions'
+  }
+
+  override equals(ei: TableCommission, syncMap?: SyncMap | undefined): boolean {
+    if (
+      this.isRedeemed !== ei.isRedeemed ||
+      this.transactionId !== (syncMap ? syncMap.transaction.idMap[ei.transactionId] : ei.transactionId) ||
+      this.keyOffset !== ei.keyOffset ||
+      !arraysEqual(this.lockingScript, ei.lockingScript) ||
+      this.satoshis !== ei.satoshis
+    )
+      return false
+
+    return true
+  }
+
+  static async mergeFind(
+    storage: EntityStorage,
+    userId: number,
+    ei: TableCommission,
+    syncMap: SyncMap,
+    trx?: TrxToken
+  ): Promise<{ found: boolean; eo: EntityCommission; eiId: number }> {
+    const transactionId = syncMap.transaction.idMap[ei.transactionId]
+    const ef = verifyOneOrNone(await storage.findCommissions({ partial: { transactionId, userId }, trx }))
+    return {
+      found: !!ef,
+      eo: new EntityCommission(ef || { ...ei }),
+      eiId: verifyId(ei.commissionId)
+    }
+  }
+
+  override async mergeNew(storage: EntityStorage, userId: number, syncMap: SyncMap, trx?: TrxToken): Promise<void> {
+    if (this.transactionId) this.transactionId = syncMap.transaction.idMap[this.transactionId]
+    this.userId = userId
+    this.commissionId = 0
+    this.commissionId = await storage.insertCommission(this.toApi(), trx)
+  }
+
+  override async mergeExisting(
+    storage: EntityStorage,
+    since: Date | undefined,
+    ei: TableCommission,
+    syncMap: SyncMap,
+    trx?: TrxToken
+  ): Promise<boolean> {
+    let wasMerged = false
+    if (ei.updated_at > this.updated_at) {
+      this.isRedeemed = ei.isRedeemed
+      this.updated_at = new Date(Math.max(ei.updated_at.getTime(), this.updated_at.getTime()))
+      await storage.updateCommission(this.id, this.toApi(), trx)
+      wasMerged = true
+    }
+    return wasMerged
+  }
+}