Merge pull request #4 from bsv-blockchain/feat/direct-payment

feat: add BRC-29 direct payment internalization to WalletCore

Author: MatiasJF

CLAUDE.md

@@ -110,7 +110,15 @@ const wallet = await createWallet({ network: 'main' })
 |--------|--------|---------|-------------|
 | `pay(options)` | `PaymentOptions` | `Promise<TransactionResult>` | Payment via MessageBox P2P (PeerPayClient) |
 | `send(options)` | `SendOptions` | `Promise<SendResult>` | Multi-output: P2PKH + OP_RETURN + PushDrop in one tx |
-| `fundServerWallet(request, basket?)` | `PaymentRequest, string?` | `Promise<TransactionResult>` | Fund a ServerWallet using BRC-29 derivation |
+| `fundServerWallet(request, basket?)` | `PaymentRequest, string?` | `Promise<TransactionResult>` | Fund a ServerWallet using BRC-29 derivation (legacy) |
+
+### Direct Payments — BRC-29 Wallet Payment Internalization (WalletCore)
+
+| Method | Params | Returns | Description |
+|--------|--------|---------|-------------|
+| `createPaymentRequest(options)` | `{ satoshis, memo? }` | `PaymentRequest` | Generate BRC-29 derivation data for someone to pay you |
+| `sendDirectPayment(request)` | `PaymentRequest` | `Promise<DirectPaymentResult>` | Create BRC-29 derived P2PKH tx + return remittance data |
+| `receiveDirectPayment(payment)` | `IncomingPayment` | `Promise<void>` | Internalize into wallet balance via `wallet payment` (NOT into a basket) |
 
 ### Tokens (tokens module)
 
@@ -193,12 +201,11 @@ const wallet = await ServerWallet.create({
 
 | Method | Params | Returns | Description |
 |--------|--------|---------|-------------|
-| `createPaymentRequest(options)` | `{ satoshis, memo? }` | `PaymentRequest` | Generate BRC-29 payment request for desktop client |
-| `receivePayment(payment)` | `IncomingPayment` | `Promise<void>` | Internalize payment from desktop using `wallet payment` protocol |
+| `receivePayment(payment)` | `IncomingPayment` | `Promise<void>` | **Deprecated.** Use `receiveDirectPayment()` (inherited from WalletCore). Kept for backward compat with `server_funding` label. |
 
 ### Shared Methods
 
-ServerWallet has all the same methods as BrowserWallet (pay, send, createToken, inscribeText, etc.) via the same module composition pattern.
+ServerWallet has all the same methods as BrowserWallet (pay, send, createToken, inscribeText, createPaymentRequest, sendDirectPayment, receiveDirectPayment, etc.) via the same module composition pattern.
 
 ---
 
@@ -714,32 +721,64 @@ const incoming = await wallet.listIncomingPayments()
 await wallet.acceptIncomingPayment(incoming[0], 'received-payments')
 ```
 
-### 7.8 Server Wallet: Create, Fund, Receive, Balance
+### 7.8 Direct Payments (BRC-29 Wallet Payment Internalization)
 
 ```typescript
-// Server side: create wallet
-const { ServerWallet } = await import('@bsv/simple/server')
-const server = await ServerWallet.create({ privateKey: 'hex', network: 'main' })
+// Direct payments work on BOTH browser and server wallets.
+// Funds go directly into the wallet's spendable balance (NOT into a basket).
+
+// --- Flow: Browser pays Server ---
 
 // Server: generate payment request
-const request = server.createPaymentRequest({ satoshis: 50000 })
+const request = serverWallet.createPaymentRequest({ satoshis: 2000 })
 
-// Client: fund server wallet
-const result = await wallet.fundServerWallet(request, 'server-funding')
+// Browser: create BRC-29 derived P2PKH transaction
+const payment = await browserWallet.sendDirectPayment(request)
 
-// Client: send tx to server
-await fetch('/api/server-wallet?action=receive', {
+// Browser: send tx + remittance to server (via API)
+await fetch('/api/receive-payment', {
   method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
   body: JSON.stringify({
-    tx: Array.from(result.tx),
-    senderIdentityKey: wallet.getIdentityKey(),
-    derivationPrefix: request.derivationPrefix,
-    derivationSuffix: request.derivationSuffix,
-    outputIndex: 0
+    tx: Array.from(payment.tx),
+    senderIdentityKey: payment.senderIdentityKey,
+    derivationPrefix: payment.derivationPrefix,
+    derivationSuffix: payment.derivationSuffix,
+    outputIndex: payment.outputIndex
   })
 })
 
-// Server: receive payment
+// Server: internalize
+await serverWallet.receiveDirectPayment({ tx, senderIdentityKey, derivationPrefix, derivationSuffix, outputIndex: 0 })
+
+// --- Flow: Server pays Browser ---
+
+// Browser: create payment request
+const request = browserWallet.createPaymentRequest({ satoshis: 100 })
+// ... send request to server via API ...
+
+// Server: create payment
+const payment = await serverWallet.sendDirectPayment(request)
+// ... return payment data to browser ...
+
+// Browser: internalize into wallet balance
+await browserWallet.receiveDirectPayment({
+  tx: paymentData.tx,
+  senderIdentityKey: paymentData.senderIdentityKey,
+  derivationPrefix: paymentData.derivationPrefix,
+  derivationSuffix: paymentData.derivationSuffix,
+  outputIndex: paymentData.outputIndex
+})
+```
+
+### 7.8b Server Wallet: Legacy Fund Flow
+
+```typescript
+// Legacy pattern — prefer sendDirectPayment/receiveDirectPayment instead
+const { ServerWallet } = await import('@bsv/simple/server')
+const server = await ServerWallet.create({ privateKey: 'hex', network: 'main' })
+const request = server.createPaymentRequest({ satoshis: 50000 })
+const result = await wallet.fundServerWallet(request, 'server-funding')
 await server.receivePayment({ tx, senderIdentityKey, derivationPrefix, derivationSuffix, outputIndex: 0 })
 ```
 
@@ -873,6 +912,7 @@ interface InscriptionResult extends TransactionResult { type: InscriptionType; d
 interface ServerWalletConfig { privateKey: string; network?: Network; storageUrl?: string }
 interface PaymentRequest { serverIdentityKey: string; derivationPrefix: string; derivationSuffix: string; satoshis: number; memo?: string }
 interface IncomingPayment { tx: number[] | Uint8Array; senderIdentityKey: string; derivationPrefix: string; derivationSuffix: string; outputIndex: number; description?: string }
+interface DirectPaymentResult extends TransactionResult { senderIdentityKey: string; derivationPrefix: string; derivationSuffix: string; outputIndex: number }
 ```
 
 ### DID Types

jest.config.js

@@ -0,0 +1,11 @@
+/** @type {import('jest').Config} */
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  roots: ['<rootDir>/src'],
+  testMatch: ['**/__tests__/**/*.test.ts'],
+  moduleFileExtensions: ['ts', 'js', 'json'],
+  transformIgnorePatterns: [
+    'node_modules/(?!(@bsv)/)'
+  ]
+}

src/core/WalletCore.ts

@@ -20,7 +20,9 @@ import {
   SendResult,
   SendOutputDetail,
   TransactionResult,
-  PaymentRequest
+  PaymentRequest,
+  IncomingPayment,
+  DirectPaymentResult
 } from './types'
 
 export abstract class WalletCore {
@@ -224,6 +226,120 @@ export abstract class WalletCore {
     }
   }
 
+  // ============================================================================
+  // Direct Payment (BRC-29 wallet payment internalization)
+  // ============================================================================
+
+  /**
+   * Generate a payment request containing BRC-29 derivation data.
+   * Share this with the sender so they can create a payment via `sendDirectPayment()`.
+   */
+  createPaymentRequest (options: { satoshis: number, memo?: string }): PaymentRequest {
+    const derivationPrefix = Utils.toBase64(Utils.toArray('payment', 'utf8'))
+    const derivationSuffix = Utils.toBase64(Random(8))
+    return {
+      serverIdentityKey: this.identityKey,
+      derivationPrefix,
+      derivationSuffix,
+      satoshis: options.satoshis,
+      memo: options.memo
+    }
+  }
+
+  /**
+   * Create a BRC-29 derived P2PKH transaction for the recipient described in the request.
+   * Returns the transaction plus remittance data the recipient needs to call `receiveDirectPayment()`.
+   */
+  async sendDirectPayment (request: PaymentRequest): Promise<DirectPaymentResult> {
+    try {
+      const client = this.getClient()
+      const protocolID: [SecurityLevel, string] = [2 as SecurityLevel, '3241645161d8']
+      const keyID = `${request.derivationPrefix} ${request.derivationSuffix}`
+
+      const { publicKey: derivedKey } = await client.getPublicKey({
+        protocolID,
+        keyID,
+        counterparty: request.serverIdentityKey,
+        forSelf: false
+      })
+
+      const lockingScript = new P2PKH()
+        .lock(PublicKey.fromString(derivedKey).toAddress())
+        .toHex()
+
+      const outputs: any[] = [{
+        lockingScript,
+        satoshis: request.satoshis,
+        outputDescription: `Direct payment: ${request.satoshis} sats`,
+        customInstructions: JSON.stringify({
+          derivationPrefix: request.derivationPrefix,
+          derivationSuffix: request.derivationSuffix,
+          payee: request.serverIdentityKey
+        })
+      }]
+
+      if (request.memo != null && request.memo !== '') {
+        const memoScript = new Script()
+          .writeOpCode(OP.OP_FALSE)
+          .writeOpCode(OP.OP_RETURN)
+          .writeBin(Array.from(Utils.toArray(request.memo, 'utf8')))
+        outputs.push({
+          lockingScript: memoScript.toHex(),
+          satoshis: 0,
+          outputDescription: 'Payment memo'
+        })
+      }
+
+      const result = await client.createAction({
+        description: request.memo ?? `Direct payment (${request.satoshis} sats)`,
+        outputs,
+        options: { randomizeOutputs: false, acceptDelayedBroadcast: false }
+      })
+
+      return {
+        txid: result.txid ?? '',
+        tx: result.tx,
+        senderIdentityKey: this.identityKey,
+        derivationPrefix: request.derivationPrefix,
+        derivationSuffix: request.derivationSuffix,
+        outputIndex: 0
+      }
+    } catch (error) {
+      throw new Error(`Direct payment failed: ${(error as Error).message}`)
+    }
+  }
+
+  /**
+   * Internalize a received payment directly into the wallet's spendable balance
+   * using the `wallet payment` protocol. This does NOT put the output into a basket —
+   * it becomes a regular spendable UTXO managed by the wallet.
+   */
+  async receiveDirectPayment (payment: IncomingPayment): Promise<void> {
+    try {
+      const client = this.getClient()
+      const tx = payment.tx instanceof Uint8Array
+        ? Array.from(payment.tx)
+        : payment.tx
+
+      await (client as any).internalizeAction({
+        tx,
+        outputs: [{
+          outputIndex: payment.outputIndex,
+          protocol: 'wallet payment',
+          paymentRemittance: {
+            senderIdentityKey: payment.senderIdentityKey,
+            derivationPrefix: payment.derivationPrefix,
+            derivationSuffix: payment.derivationSuffix
+          }
+        }],
+        description: payment.description ?? `Payment from ${payment.senderIdentityKey.substring(0, 20)}...`,
+        labels: ['direct_payment']
+      })
+    } catch (error) {
+      throw new Error(`Failed to receive direct payment: ${(error as Error).message}`)
+    }
+  }
+
   // ============================================================================
   // Fund Server Wallet
   // ============================================================================