@bsv/sdk 1.10.4 → 2.0.0

package/src/remittance/RemittanceModule.ts

@@ -0,0 +1,92 @@
+import { PubKeyHex } from '../wallet/index.js'
+import { Invoice, ModuleContext, RemittanceOptionId, ThreadId, Termination, Settlement } from './types.js'
+
+/**
+ * A remittance module implements a specific settlement system.
+ *
+ * The RemittanceManager core uses module ids as the only “capability mechanism”:
+ * if an invoice contains an option with module id X, a payer can only satisfy it
+ * if they are configured with module X.
+ */
+export interface RemittanceModule<
+  TOptionTerms = unknown,
+  TSettlementArtifact = unknown,
+  TReceiptData = unknown
+> {
+  /** Unique id used as the invoice.options key and as settlement.moduleId. */
+  id: RemittanceOptionId
+  /** Human-readable name for UIs. */
+  name: string
+
+  /**
+   * Whether this module allows unsolicited settlements (i.e. settlement without an invoice).
+   *
+   * If true, the payer can build a settlement without an invoice being provided by the payee.
+   * In this case, the option terms provided to `buildSettlement` may be used in lieu of an invoice.
+   *
+   * If false, an invoice must always be provided to `buildSettlement`.
+   */
+  allowUnsolicitedSettlements: boolean
+
+  /**
+   * Creates module-defined option terms that will be embedded into the invoice.
+   *
+   * In UTXO-ish offers, these option terms may include a partially-signed transaction template.
+   *
+   * Optional because some modules may not require any option data, or may only support unsolicited settlements.
+   *
+   * However, a module MAY still create option terms/invoices even if it can sometimes support unsolicited settlements.
+   */
+  createOption?: (args: { threadId: ThreadId, invoice: Invoice }, ctx: ModuleContext) => Promise<TOptionTerms>
+
+  /**
+   * Builds the settlement artifact for a chosen option.
+   *
+   * For UTXO settlement systems, this is usually a transaction (or partially-signed tx) to be broadcast.
+   *
+   * For unsolicited settlements, an invoice may not always be provided and the option terms may be used in lieu of an invoice to settle against.
+   *
+   * For example, the option terms may include a tx template with outputs to fulfill the settlement.
+   *
+   * When `allowUnsolicitedSettlements` is false, an invoice will always be provided.
+   *
+   * Termination can be returned to abort the protocol with a reason.
+   */
+  buildSettlement: (
+    args: { threadId: ThreadId, invoice?: Invoice, option: TOptionTerms, note?: string },
+    ctx: ModuleContext
+  ) => Promise<{ action: 'settle', artifact: TSettlementArtifact } | { action: 'terminate', termination: Termination }>
+
+  /**
+   * Accepts a settlement artifact on the payee side.
+   *
+   * The module should validate and internalize/store whatever it needs.
+   * The manager will wrap the returned value as receipt.receiptData.
+   *
+   * If the settlement is invalid, the module should return either a termination or receiptData (possibly with a refund or indicating the failure), depending how the module chooses to handle it.
+   */
+  acceptSettlement: (
+    args: { threadId: ThreadId, invoice?: Invoice, settlement: TSettlementArtifact, sender: PubKeyHex },
+    ctx: ModuleContext
+  ) => Promise<{ action: 'accept', receiptData?: TReceiptData } | { action: 'terminate', termination: Termination }>
+
+  /**
+   * Processes a receipt on the payer side.
+   *
+   * This is where a module can automatically internalize a refund, mark a local order fulfilled, receive goods and services, etc.
+   */
+  processReceipt?: (
+    args: { threadId: ThreadId, invoice?: Invoice, receiptData: TReceiptData, sender: PubKeyHex },
+    ctx: ModuleContext
+  ) => Promise<void>
+
+  /**
+   * Processes a termination on either side.
+   *
+   * This is where a module can clean up any internal state, reverse provisional actions, take refunds, etc.
+   */
+  processTermination?: (
+    args: { threadId: ThreadId, invoice?: Invoice, settlement?: Settlement, termination: Termination, sender: PubKeyHex },
+    ctx: ModuleContext
+  ) => Promise<void>
+}

package/src/remittance/__tests/BasicBRC29.test.ts

@@ -0,0 +1,188 @@
+import type { ModuleContext } from '../types.js'
+import type { WalletInterface } from '../../wallet/Wallet.interfaces.js'
+import { Brc29RemittanceModule } from '../modules/BasicBRC29.js'
+
+const makeContext = (wallet: WalletInterface): ModuleContext => ({
+  wallet,
+  originator: 'example.com',
+  now: () => 123
+})
+
+describe('Brc29RemittanceModule', () => {
+  // Prevent console.log output during tests
+  const consoleErrorSpy = jest.spyOn(console, 'log').mockImplementation(() => { })
+
+  describe('unsolicited settlements (no invoice)', () => {
+    it('builds a settlement artifact for unsolicited payment', async () => {
+      const wallet = {
+        getPublicKey: jest.fn(async () => ({ publicKey: '02deadbeef' })),
+        createAction: jest.fn(async () => ({ tx: [1, 2, 3] }))
+      } as unknown as WalletInterface
+
+      const module = new Brc29RemittanceModule({
+        protocolID: [2, 'test-protocol'],
+        labels: ['label-1'],
+        description: 'Test payment',
+        outputDescription: 'Test output',
+        nonceProvider: {
+          createNonce: jest.fn()
+            .mockResolvedValueOnce('prefix')
+            .mockResolvedValueOnce('suffix')
+        },
+        lockingScriptProvider: {
+          pubKeyToP2PKHLockingScript: jest.fn(async () => '76a914deadbeef88ac')
+        }
+      })
+
+      const option = { amountSatoshis: 1000, payee: 'payee-key' }
+      const result = await module.buildSettlement({ threadId: 'thread-1', option, note: 'unsolicited payment' }, makeContext(wallet))
+      expect(result.action).toBe('settle')
+      if (result.action !== 'settle') return
+
+      expect(result.artifact.customInstructions).toEqual({ derivationPrefix: 'prefix', derivationSuffix: 'suffix' })
+      expect(result.artifact.amountSatoshis).toBe(1000)
+      expect(result.artifact.outputIndex).toBe(0)
+      expect(result.artifact.transaction).toEqual([1, 2, 3])
+
+      expect(wallet.getPublicKey).toHaveBeenCalledWith(
+        {
+          protocolID: [2, 'test-protocol'],
+          keyID: 'prefix suffix',
+          counterparty: option.payee
+        },
+        'example.com'
+      )
+
+      const createArgs = (wallet.createAction as jest.Mock).mock.calls[0][0]
+      const customInstructions = JSON.parse(createArgs.outputs[0].customInstructions as string)
+      expect(customInstructions).toEqual({
+        derivationPrefix: 'prefix',
+        derivationSuffix: 'suffix',
+        payee: option.payee,
+        threadId: 'thread-1',
+        note: 'unsolicited payment'
+      })
+      expect(createArgs.outputs[0].outputDescription).toBe('Test output')
+    })
+
+    it('terminates on invalid amounts for unsolicited settlements', async () => {
+      const wallet = {
+        getPublicKey: jest.fn(async () => ({ publicKey: '02deadbeef' })),
+        createAction: jest.fn(async () => ({ tx: [1, 2, 3] }))
+      } as unknown as WalletInterface
+
+      const module = new Brc29RemittanceModule()
+      const option = { amountSatoshis: 0, payee: 'payee-key' }
+      const result = await module.buildSettlement({ threadId: 'thread-1', option }, makeContext(wallet))
+      expect(result.action).toBe('terminate')
+    })
+
+    it('terminates on invalid option data for unsolicited settlements', async () => {
+      const wallet = {
+        getPublicKey: jest.fn(async () => ({ publicKey: '02deadbeef' })),
+        createAction: jest.fn(async () => ({ tx: [1, 2, 3] }))
+      } as unknown as WalletInterface
+
+      const module = new Brc29RemittanceModule()
+      const option = { amountSatoshis: -5, payee: 'payee-key', outputIndex: -1 }
+      const result = await module.buildSettlement({ threadId: 'thread-1', option }, makeContext(wallet))
+      expect(result.action).toBe('terminate')
+      if (result.action === 'terminate') {
+        expect(result.termination.code).toBe('brc29.invalid_option')
+      }
+    })
+  })
+
+  describe('settlement building edge cases', () => {
+    it('terminates when wallet fails to create transaction', async () => {
+      const wallet = {
+        getPublicKey: jest.fn(async () => ({ publicKey: '02deadbeef' })),
+        createAction: jest.fn(async () => ({}))
+      } as unknown as WalletInterface
+
+      const module = new Brc29RemittanceModule({
+        nonceProvider: {
+          createNonce: jest.fn()
+            .mockResolvedValueOnce('prefix')
+            .mockResolvedValueOnce('suffix')
+        },
+        lockingScriptProvider: {
+          pubKeyToP2PKHLockingScript: jest.fn(async () => '76a914deadbeef88ac')
+        }
+      })
+      const option = { amountSatoshis: 1000, payee: 'payee-key' }
+      const result = await module.buildSettlement({ threadId: 'thread-1', option }, makeContext(wallet))
+      expect(result.action).toBe('terminate')
+      if (result.action === 'terminate') {
+        expect(result.termination.code).toBe('brc29.missing_tx')
+      }
+    })
+  })
+
+  describe('settlement acceptance', () => {
+    it('accepts settlements by internalizing the payment', async () => {
+      const wallet = {
+        internalizeAction: jest.fn(async () => ({ ok: true }))
+      } as unknown as WalletInterface
+
+      const module = new Brc29RemittanceModule()
+      const settlement = {
+        customInstructions: { derivationPrefix: 'p', derivationSuffix: 's' },
+        transaction: [9, 9, 9],
+        amountSatoshis: 1000,
+        outputIndex: 1
+      }
+      const result = await module.acceptSettlement(
+        { threadId: 'thread-1', settlement, sender: 'payer-key' },
+        makeContext(wallet)
+      )
+      expect(result.action).toBe('accept')
+      if (result.action === 'accept') {
+        expect(result.receiptData?.internalizeResult).toEqual({ ok: true })
+      }
+
+      expect(wallet.internalizeAction).toHaveBeenCalledWith(
+        {
+          tx: settlement.transaction,
+          outputs: [
+            {
+              paymentRemittance: {
+                derivationPrefix: 'p',
+                derivationSuffix: 's',
+                senderIdentityKey: 'payer-key'
+              },
+              outputIndex: 1,
+              protocol: 'wallet payment'
+            }
+          ],
+          labels: ['brc29'],
+          description: 'BRC-29 payment received'
+        },
+        'example.com'
+      )
+    })
+
+    it('terminates when internalization fails', async () => {
+      const wallet = {
+        internalizeAction: jest.fn(async () => {
+          throw new Error('fail')
+        })
+      } as unknown as WalletInterface
+
+      const module = new Brc29RemittanceModule()
+      const settlement = {
+        customInstructions: { derivationPrefix: 'p', derivationSuffix: 's' },
+        transaction: [9, 9, 9],
+        amountSatoshis: 1000
+      }
+      const result = await module.acceptSettlement(
+        { threadId: 'thread-1', settlement, sender: 'payer-key' },
+        makeContext(wallet)
+      )
+      expect(result.action).toBe('terminate')
+      if (result.action === 'terminate') {
+        expect(result.termination.code).toBe('brc29.internalize_failed')
+      }
+    })
+  })
+})