@bsv/overlay 0.1.0-alpha.1

package/src/storage/Storage.ts

@@ -0,0 +1,72 @@
+import type { Output } from '../Output.js'
+
+/**
+ * Representa a transaction that has been applied to a topic.
+ */
+interface AppliedTransaction {
+  /** TXID of the applied transaction */
+  txid: string
+  /** Output index of the applied transaction */
+  topic: string
+}
+
+/**
+ * Defines the Storage Engine interface used internally by the Overlay Services Engine.
+ */
+export default interface Storage {
+  /**
+     * Adds a new output to storage
+     * @param utxo — The output to add
+     */
+  insertOutput: (utxo: Output) => Promise<void>
+
+  /**
+     * Finds an output from storage
+     * @param txid — TXID of hte output to find
+     * @param outputIndex — Output index for the output to find
+     * @param topic — The topic in which the output is stored
+     * @param spent — Whether the output must be spent to be returned
+     */
+  findOutput: (txid: string, outputIndex: number, topic?: string, spent?: boolean) => Promise<Output | null>
+
+  /**
+     * Deletes an output from storage
+     * @param txid — The TXID of the output to delete
+     * @param outputIndex — The index of the output to delete
+     * @param topic — The topic where the output should be deleted
+     */
+  deleteOutput: (txid: string, outputIndex: number, topic: string) => Promise<void>
+
+  /**
+    * Updates a UTXO as spent
+    * @param txid — TXID of the output to update
+    * @param outputIndex — Index of the output to update
+    * @param topic — Topic in which the output should be updated
+    */
+  markUTXOAsSpent: (txid: string, outputIndex: number, topic: string) => Promise<void>
+
+  /**
+    * Updates which outputs are consumed by this output
+    * @param txid — TXID of the output to update
+    * @param outputIndex — Index of the output to update
+    * @param topic — Topic in which the output should be updated
+    * @param consumedBy — The new set of outputs consumed by this output
+    */
+  updateConsumedBy: (txid: string, outputIndex: number, topic: string, consumedBy: Array<{
+    txid: string
+    outputIndex: number
+  }>) => Promise<void>
+
+  /**
+     * Inserts record of the applied transaction
+     * @param tx — The transaction to insert
+     */
+  insertAppliedTransaction: (tx: AppliedTransaction) => Promise<void>
+
+  /**
+     * Checks if a duplicate transaction exists
+     * @param tx — Transaction to check
+     * @returns Whether the transaction is already applied
+     */
+  doesAppliedTransactionExist: (tx: AppliedTransaction) => Promise<boolean>
+}

package/src/storage/knex/KnexStorage.ts

@@ -0,0 +1,90 @@
+import Storage from '../Storage.js'
+import { Knex } from 'knex'
+import type { Output } from '../../Output.js'
+
+export default class KnexStorage implements Storage {
+    knex: Knex
+
+    constructor(knex: Knex) {
+        this.knex = knex
+    }
+
+    async findOutput(txid: string, outputIndex: number, topic?: string, spent?: boolean): Promise<Output | null> {
+        const search: {
+            txid: string,
+            outputIndex: number,
+            topic?: string,
+            spent?: boolean
+        } = {
+            txid,
+            outputIndex
+        }
+        if (topic !== undefined) search.topic = topic
+        if (spent !== undefined) search.spent = spent
+        const [output] = await this.knex('outputs').where(search).select(
+            'txid', 'outputIndex', 'outputScript', 'topic', 'satoshis', 'beef', 'outputsConsumed', 'spent', 'consumedBy'
+        )
+        if (!output) {
+            return null
+        }
+        return {
+            ...output,
+            outputScript: [...output.outputScript],
+            beef: [...output.beef],
+            spent: Boolean(output.spent),
+            outputsConsumed: JSON.parse(output.outputsConsumed),
+            consumedBy: JSON.parse(output.consumedBy)
+        }
+    }
+
+    async deleteOutput(txid: string, outputIndex: number, topic: string): Promise<void> {
+        await this.knex('outputs').where({
+            txid, outputIndex, topic
+        }).del()
+    }
+
+    async insertOutput(output: Output) {
+        await this.knex('outputs').insert({
+            txid: output.txid,
+            outputIndex: Number(output.outputIndex),
+            outputScript: Buffer.from(output.outputScript),
+            topic: output.topic,
+            satoshis: Number(output.satoshis),
+            beef: [...output.beef],
+            outputsConsumed: JSON.stringify(output.outputsConsumed),
+            consumedBy: JSON.stringify(output.consumedBy),
+            spent: output.spent
+        })
+    }
+
+    async markUTXOAsSpent(txid: string, outputIndex: number, topic?: string): Promise<void> {
+        await this.knex('outputs').where({
+            txid,
+            outputIndex,
+            topic
+        }).update('spent', true)
+    }
+
+    async updateConsumedBy(txid: string, outputIndex: number, topic: string, consumedBy: { txid: string, outputIndex: number }[]) {
+        await this.knex('outputs').where({
+            txid,
+            outputIndex,
+            topic
+        }).update('consumedBy', consumedBy)
+    }
+
+    async insertAppliedTransaction(tx: { txid: string, topic: string }) {
+        await this.knex('applied_transactions').insert({
+            txid: tx.txid,
+            topic: tx.topic
+        })
+    }
+
+    async doesAppliedTransactionExist(tx: { txid: string, topic: string }): Promise<boolean> {
+        const appliedTransactions = await this.knex('applied_transactions').where({
+            txid: tx.txid,
+            topic: tx.topic
+        }).select('txid', 'topic')
+        return appliedTransactions.length > 0
+    }
+}

package/src/storage/knex/all-migrations.ts

@@ -0,0 +1,14 @@
+import { Knex } from 'knex'
+import { up as oneUp, down as oneDown } from './migrations/2024-05-18-001-initial.js'
+
+/**
+ * An array of all migrations, in order.
+ */
+const allMigrations: {
+    up: (knex: Knex) => Promise<void>
+    down: (knex: Knex) => Promise<void>
+}[] = [
+        { up: oneUp, down: oneDown }
+    ]
+
+export default allMigrations

package/src/storage/knex/migrations/2024-05-18-001-initial.ts

@@ -0,0 +1,30 @@
+import type { Knex } from 'knex'
+
+export async function up(knex: Knex): Promise<void> {
+  await knex.schema.createTable('outputs', table => {
+    table.increments()
+    table.string('txid', 64)
+    table.integer('outputIndex', 10)
+    table.binary('outputScript')
+    table.string('topic')
+    table.integer('satoshis', 15)
+    table.binary('beef')
+    // Represents the outputs that were provided as inputs
+    // to the transaction that created this output.
+    // This indicates the correct history of this output.
+    table.text('outputsConsumed', 'longtext').defaultTo('[]')
+    // Tracks any outputs the current output is used as an input in it's creation
+    table.text('consumedBy', 'longtext').defaultTo('[]')
+    table.boolean('spent').defaultTo(false)
+  })
+  await knex.schema.createTable('applied_transactions', table => {
+    table.increments()
+    table.string('txid', 64)
+    table.string('topic')
+  })
+}
+
+export async function down(knex: Knex): Promise<void> {
+  await knex.schema.dropTable('applied_transactions')
+  await knex.schema.dropTable('outputs')
+}