@sip-protocol/sdk 0.2.10 → 0.3.1

package/src/proofs/worker.ts

@@ -181,6 +181,211 @@ export function createWorkerBlobURL(): string {
       }
     }
 
+    // Generate validity proof
+    async function generateValidityProof(id, params) {
+      if (!isReady) {
+        sendError(id, new Error('Worker not initialized'));
+        return;
+      }
+
+      try {
+        sendProgress(id, 'witness', 20, 'Preparing validity witness...');
+
+        // Import noble crypto for hashing
+        const { sha256 } = await import('@noble/hashes/sha256');
+
+        // Convert inputs to field elements
+        const intentHashField = hexToField(params.intentHash);
+        const senderAddressField = hexToField(params.senderAddress);
+        const senderBlindingField = bytesToField(params.senderBlinding);
+        const senderSecretField = bytesToField(params.senderSecret);
+        const nonceField = bytesToField(params.nonce);
+
+        // Compute sender commitment
+        const addressBytes = hexToBytes(senderAddressField);
+        const blindingBytes = hexToBytes(senderBlindingField.padStart(64, '0'));
+        const commitmentPreimage = new Uint8Array([...addressBytes, ...blindingBytes]);
+        const commitmentHash = sha256(commitmentPreimage);
+        const commitmentX = bytesToHex(commitmentHash.slice(0, 16)).padStart(64, '0');
+        const commitmentY = bytesToHex(commitmentHash.slice(16, 32)).padStart(64, '0');
+
+        // Compute nullifier
+        const secretBytes = hexToBytes(senderSecretField.padStart(64, '0'));
+        const intentBytes = hexToBytes(intentHashField);
+        const nonceBytes = hexToBytes(nonceField.padStart(64, '0'));
+        const nullifierPreimage = new Uint8Array([...secretBytes, ...intentBytes, ...nonceBytes]);
+        const nullifierHash = sha256(nullifierPreimage);
+        const nullifier = bytesToHex(nullifierHash);
+
+        const signature = Array.from(params.authorizationSignature);
+        const messageHash = fieldToBytes32(intentHashField);
+
+        // Get public key coordinates
+        let pubKeyX, pubKeyY;
+        if (params.senderPublicKey) {
+          pubKeyX = Array.from(params.senderPublicKey.x);
+          pubKeyY = Array.from(params.senderPublicKey.y);
+        } else {
+          // Derive from secret
+          const { secp256k1 } = await import('@noble/curves/secp256k1');
+          const uncompressedPubKey = secp256k1.getPublicKey(params.senderSecret, false);
+          pubKeyX = Array.from(uncompressedPubKey.slice(1, 33));
+          pubKeyY = Array.from(uncompressedPubKey.slice(33, 65));
+        }
+
+        const witnessInputs = {
+          intent_hash: intentHashField,
+          sender_commitment_x: commitmentX,
+          sender_commitment_y: commitmentY,
+          nullifier: nullifier,
+          timestamp: params.timestamp.toString(),
+          expiry: params.expiry.toString(),
+          sender_address: senderAddressField,
+          sender_blinding: senderBlindingField,
+          sender_secret: senderSecretField,
+          pub_key_x: pubKeyX,
+          pub_key_y: pubKeyY,
+          signature: signature,
+          message_hash: messageHash,
+          nonce: nonceField,
+        };
+
+        sendProgress(id, 'witness', 40, 'Executing validity circuit...');
+        const { witness } = await validityNoir.execute(witnessInputs);
+
+        sendProgress(id, 'proving', 60, 'Generating validity proof...');
+        const proofData = await validityBackend.generateProof(witness);
+
+        sendProgress(id, 'complete', 100, 'Validity proof generated');
+
+        const publicInputs = [
+          '0x' + intentHashField,
+          '0x' + commitmentX,
+          '0x' + commitmentY,
+          '0x' + nullifier,
+          '0x' + params.timestamp.toString(16).padStart(16, '0'),
+          '0x' + params.expiry.toString(16).padStart(16, '0'),
+        ];
+
+        const proof = {
+          type: 'validity',
+          proof: '0x' + bytesToHex(proofData.proof),
+          publicInputs,
+        };
+
+        sendSuccess(id, { proof, publicInputs });
+      } catch (error) {
+        sendError(id, error);
+      }
+    }
+
+    // Generate fulfillment proof
+    async function generateFulfillmentProof(id, params) {
+      if (!isReady) {
+        sendError(id, new Error('Worker not initialized'));
+        return;
+      }
+
+      try {
+        sendProgress(id, 'witness', 20, 'Preparing fulfillment witness...');
+
+        // Import noble crypto for hashing
+        const { sha256 } = await import('@noble/hashes/sha256');
+
+        const intentHashField = hexToField(params.intentHash);
+        const recipientStealthField = hexToField(params.recipientStealth);
+
+        // Compute output commitment
+        const amountBytes = bigintToBytes(params.outputAmount, 8);
+        const blindingBytes = params.outputBlinding.slice(0, 32);
+        const outputPreimage = new Uint8Array([...amountBytes, ...blindingBytes]);
+        const outputHash = sha256(outputPreimage);
+        const commitmentX = bytesToHex(outputHash.slice(0, 16)).padStart(64, '0');
+        const commitmentY = bytesToHex(outputHash.slice(16, 32)).padStart(64, '0');
+
+        const solverSecretField = bytesToField(params.solverSecret);
+
+        // Compute solver ID
+        const solverSecretBytes = hexToBytes(solverSecretField.padStart(64, '0'));
+        const solverIdHash = sha256(solverSecretBytes);
+        const solverId = bytesToHex(solverIdHash);
+
+        const outputBlindingField = bytesToField(params.outputBlinding);
+
+        const attestation = params.oracleAttestation;
+        const attestationRecipientField = hexToField(attestation.recipient);
+        const attestationTxHashField = hexToField(attestation.txHash);
+        const oracleSignature = Array.from(attestation.signature);
+
+        // Compute oracle message hash
+        const recipientBytes = hexToBytes(attestationRecipientField);
+        const attestationAmountBytes = bigintToBytes(attestation.amount, 8);
+        const txHashBytes = hexToBytes(attestationTxHashField);
+        const blockBytes = bigintToBytes(attestation.blockNumber, 8);
+        const oraclePreimage = new Uint8Array([
+          ...recipientBytes,
+          ...attestationAmountBytes,
+          ...txHashBytes,
+          ...blockBytes,
+        ]);
+        const oracleMessageHash = Array.from(sha256(oraclePreimage));
+
+        const oraclePubKeyX = config.oraclePublicKey?.x ?? new Array(32).fill(0);
+        const oraclePubKeyY = config.oraclePublicKey?.y ?? new Array(32).fill(0);
+
+        const witnessInputs = {
+          intent_hash: intentHashField,
+          output_commitment_x: commitmentX,
+          output_commitment_y: commitmentY,
+          recipient_stealth: recipientStealthField,
+          min_output_amount: params.minOutputAmount.toString(),
+          solver_id: solverId,
+          fulfillment_time: params.fulfillmentTime.toString(),
+          expiry: params.expiry.toString(),
+          output_amount: params.outputAmount.toString(),
+          output_blinding: outputBlindingField,
+          solver_secret: solverSecretField,
+          attestation_recipient: attestationRecipientField,
+          attestation_amount: attestation.amount.toString(),
+          attestation_tx_hash: attestationTxHashField,
+          attestation_block: attestation.blockNumber.toString(),
+          oracle_signature: oracleSignature,
+          oracle_message_hash: oracleMessageHash,
+          oracle_pub_key_x: oraclePubKeyX,
+          oracle_pub_key_y: oraclePubKeyY,
+        };
+
+        sendProgress(id, 'witness', 40, 'Executing fulfillment circuit...');
+        const { witness } = await fulfillmentNoir.execute(witnessInputs);
+
+        sendProgress(id, 'proving', 60, 'Generating fulfillment proof...');
+        const proofData = await fulfillmentBackend.generateProof(witness);
+
+        sendProgress(id, 'complete', 100, 'Fulfillment proof generated');
+
+        const publicInputs = [
+          '0x' + intentHashField,
+          '0x' + commitmentX,
+          '0x' + commitmentY,
+          '0x' + recipientStealthField,
+          '0x' + params.minOutputAmount.toString(16).padStart(16, '0'),
+          '0x' + solverId,
+          '0x' + params.fulfillmentTime.toString(16).padStart(16, '0'),
+          '0x' + params.expiry.toString(16).padStart(16, '0'),
+        ];
+
+        const proof = {
+          type: 'fulfillment',
+          proof: '0x' + bytesToHex(proofData.proof),
+          publicInputs,
+        };
+
+        sendSuccess(id, { proof, publicInputs });
+      } catch (error) {
+        sendError(id, error);
+      }
+    }
+
     // Helper functions
     function bytesToField(bytes) {
       let result = 0n;
@@ -208,6 +413,39 @@ export function createWorkerBlobURL(): string {
       return Array.from(bytes).map(b => b.toString(16).padStart(2, '0')).join('');
     }
 
+    function hexToBytes(hex) {
+      const h = hex.startsWith('0x') ? hex.slice(2) : hex;
+      const bytes = new Uint8Array(h.length / 2);
+      for (let i = 0; i < h.length; i += 2) {
+        bytes[i / 2] = parseInt(h.slice(i, i + 2), 16);
+      }
+      return bytes;
+    }
+
+    function hexToField(hex) {
+      const h = hex.startsWith('0x') ? hex.slice(2) : hex;
+      return h.padStart(64, '0');
+    }
+
+    function fieldToBytes32(field) {
+      const hex = field.padStart(64, '0');
+      const bytes = [];
+      for (let i = 0; i < 32; i++) {
+        bytes.push(parseInt(hex.slice(i * 2, i * 2 + 2), 16));
+      }
+      return bytes;
+    }
+
+    function bigintToBytes(value, length) {
+      const bytes = new Uint8Array(length);
+      let v = value;
+      for (let i = length - 1; i >= 0; i--) {
+        bytes[i] = Number(v & 0xffn);
+        v = v >> 8n;
+      }
+      return bytes;
+    }
+
     // Message handler
     self.onmessage = async function(event) {
       const { id, type, params, config: initConfig } = event.data;
@@ -220,12 +458,10 @@ export function createWorkerBlobURL(): string {
           await generateFundingProof(id, params);
           break;
         case 'generateValidityProof':
-          // TODO: Implement
-          sendError(id, new Error('Validity proof not yet implemented in worker'));
+          await generateValidityProof(id, params);
           break;
         case 'generateFulfillmentProof':
-          // TODO: Implement
-          sendError(id, new Error('Fulfillment proof not yet implemented in worker'));
+          await generateFulfillmentProof(id, params);
           break;
         case 'destroy':
           // Cleanup

package/src/settlement/README.md

@@ -0,0 +1,439 @@
+# Settlement Backend Interface
+
+This directory contains the settlement abstraction layer for SIP Protocol, enabling pluggable settlement backends for cross-chain swaps.
+
+## Overview
+
+The `SettlementBackend` interface provides a unified API for executing cross-chain swaps through different settlement providers (NEAR Intents, Zcash, THORChain, direct on-chain execution, etc.).
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  SIP SDK (Application Layer)                            │
+│  • createIntent()                                       │
+│  • getQuotes()                                          │
+│  • execute()                                            │
+└────────────────────┬────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────┐
+│  Settlement Backend Interface (Abstraction Layer)       │
+│  • getQuote()                                           │
+│  • executeSwap()                                        │
+│  • getStatus()                                          │
+└────────────────────┬────────────────────────────────────┘
+                     │
+         ┌───────────┼───────────┬───────────────┐
+         ▼           ▼           ▼               ▼
+┌─────────────┐ ┌─────────┐ ┌──────────┐ ┌──────────────┐
+│ NEAR        │ │ Zcash   │ │THORChain │ │ Direct Chain │
+│ Intents     │ │ Backend │ │ Backend  │ │ Backend      │
+└─────────────┘ └─────────┘ └──────────┘ └──────────────┘
+```
+
+## Core Types
+
+### SettlementBackend
+
+The main interface that all backends must implement:
+
+```typescript
+interface SettlementBackend {
+  readonly name: SettlementBackendName
+  readonly capabilities: BackendCapabilities
+
+  getQuote(params: QuoteParams): Promise<Quote>
+  executeSwap(params: SwapParams): Promise<SwapResult>
+  getStatus(swapId: string): Promise<SwapStatusResponse>
+
+  // Optional methods
+  cancel?(swapId: string): Promise<void>
+  waitForCompletion?(swapId: string, options?): Promise<SwapStatusResponse>
+  getDryQuote?(params: QuoteParams): Promise<Quote>
+  notifyDeposit?(swapId: string, txHash: string, metadata?): Promise<void>
+}
+```
+
+### QuoteParams
+
+Parameters for requesting a swap quote:
+
+```typescript
+interface QuoteParams {
+  fromChain: ChainId
+  toChain: ChainId
+  fromToken: string
+  toToken: string
+  amount: bigint
+  privacyLevel: PrivacyLevel
+  recipientMetaAddress?: StealthMetaAddress | string
+  senderAddress?: string
+  slippageTolerance?: number
+  deadline?: number
+}
+```
+
+### Quote
+
+Quote response with pricing and execution details:
+
+```typescript
+interface Quote {
+  quoteId: string
+  amountIn: string
+  amountOut: string
+  minAmountOut: string
+  fees: {
+    networkFee: string
+    protocolFee: string
+    totalFeeUSD?: string
+  }
+  depositAddress: string
+  recipientAddress: string
+  expiresAt: number
+  // ... optional fields
+}
+```
+
+### SwapStatus
+
+Enum tracking swap lifecycle:
+
+```typescript
+enum SwapStatus {
+  PENDING_DEPOSIT = 'pending_deposit',
+  DEPOSIT_CONFIRMED = 'deposit_confirmed',
+  IN_PROGRESS = 'in_progress',
+  SUCCESS = 'success',
+  FAILED = 'failed',
+  CANCELLED = 'cancelled',
+  REFUNDING = 'refunding',
+  REFUNDED = 'refunded',
+}
+```
+
+## Implementing a Backend
+
+### 1. Basic Implementation
+
+```typescript
+import type {
+  SettlementBackend,
+  QuoteParams,
+  Quote,
+  SwapParams,
+  SwapResult,
+  SwapStatusResponse,
+  BackendCapabilities,
+} from '@sip-protocol/sdk'
+
+export class MySettlementBackend implements SettlementBackend {
+  readonly name = 'my-backend'
+  readonly capabilities: BackendCapabilities = {
+    supportedSourceChains: ['ethereum', 'solana'],
+    supportedDestinationChains: ['near', 'polygon'],
+    supportedPrivacyLevels: [PrivacyLevel.TRANSPARENT, PrivacyLevel.SHIELDED],
+    supportsCancellation: false,
+    supportsRefunds: true,
+    averageExecutionTime: 120, // seconds
+  }
+
+  constructor(private config: MyBackendConfig) {}
+
+  async getQuote(params: QuoteParams): Promise<Quote> {
+    // 1. Validate parameters
+    this.validateQuoteParams(params)
+
+    // 2. Call backend API for quote
+    const backendQuote = await this.fetchQuote(params)
+
+    // 3. Convert to standard Quote format
+    return {
+      quoteId: backendQuote.id,
+      amountIn: params.amount.toString(),
+      amountOut: backendQuote.outputAmount,
+      minAmountOut: this.calculateMinOutput(
+        backendQuote.outputAmount,
+        params.slippageTolerance
+      ),
+      fees: {
+        networkFee: backendQuote.networkFee,
+        protocolFee: backendQuote.protocolFee,
+      },
+      depositAddress: backendQuote.depositAddress,
+      recipientAddress: backendQuote.recipient,
+      expiresAt: Date.now() + 300000, // 5 minutes
+    }
+  }
+
+  async executeSwap(params: SwapParams): Promise<SwapResult> {
+    // 1. Retrieve quote
+    const quote = await this.getQuoteById(params.quoteId)
+
+    // 2. Execute swap (may involve signing, approvals, etc.)
+    const execution = await this.executeBackendSwap(params)
+
+    // 3. Return result
+    return {
+      swapId: execution.id,
+      status: SwapStatus.PENDING_DEPOSIT,
+      quoteId: params.quoteId,
+      depositAddress: execution.depositAddress,
+    }
+  }
+
+  async getStatus(swapId: string): Promise<SwapStatusResponse> {
+    // Query backend for current status
+    const backendStatus = await this.fetchStatus(swapId)
+
+    return {
+      swapId,
+      status: this.mapStatus(backendStatus.status),
+      quoteId: backendStatus.quoteId,
+      depositAddress: backendStatus.depositAddress,
+      amountIn: backendStatus.amountIn,
+      amountOut: backendStatus.amountOut,
+      depositTxHash: backendStatus.depositTx,
+      settlementTxHash: backendStatus.settlementTx,
+      updatedAt: backendStatus.lastUpdated,
+    }
+  }
+
+  // Helper methods
+  private validateQuoteParams(params: QuoteParams): void {
+    if (!this.capabilities.supportedSourceChains.includes(params.fromChain)) {
+      throw new ValidationError(`Chain ${params.fromChain} not supported`)
+    }
+    // ... more validation
+  }
+
+  private mapStatus(backendStatus: string): SwapStatus {
+    // Map backend-specific status to SwapStatus enum
+    const statusMap = {
+      'waiting': SwapStatus.PENDING_DEPOSIT,
+      'processing': SwapStatus.IN_PROGRESS,
+      'completed': SwapStatus.SUCCESS,
+      'failed': SwapStatus.FAILED,
+    }
+    return statusMap[backendStatus] ?? SwapStatus.FAILED
+  }
+}
+```
+
+### 2. Optional Methods
+
+Implement optional methods for enhanced functionality:
+
+```typescript
+export class MySettlementBackend implements SettlementBackend {
+  // ... required methods ...
+
+  async cancel(swapId: string): Promise<void> {
+    if (!this.capabilities.supportsCancellation) {
+      throw new ProofError('Cancellation not supported')
+    }
+
+    const status = await this.getStatus(swapId)
+    if (status.status !== SwapStatus.PENDING_DEPOSIT) {
+      throw new ValidationError('Can only cancel pending swaps')
+    }
+
+    await this.backendCancelSwap(swapId)
+  }
+
+  async waitForCompletion(
+    swapId: string,
+    options?: { interval?: number; timeout?: number; onStatusChange?: (status: SwapStatusResponse) => void }
+  ): Promise<SwapStatusResponse> {
+    const interval = options?.interval ?? 5000
+    const timeout = options?.timeout ?? 600000
+    const startTime = Date.now()
+
+    while (Date.now() - startTime < timeout) {
+      const status = await this.getStatus(swapId)
+      options?.onStatusChange?.(status)
+
+      if (
+        status.status === SwapStatus.SUCCESS ||
+        status.status === SwapStatus.FAILED ||
+        status.status === SwapStatus.REFUNDED
+      ) {
+        return status
+      }
+
+      await new Promise(resolve => setTimeout(resolve, interval))
+    }
+
+    throw new NetworkError('Swap timeout')
+  }
+
+  async getDryQuote(params: QuoteParams): Promise<Quote> {
+    // Return quote without creating deposit address
+    return this.getQuote({ ...params, dry: true })
+  }
+
+  async notifyDeposit(
+    swapId: string,
+    txHash: string,
+    metadata?: Record<string, unknown>
+  ): Promise<void> {
+    await this.backendNotifyDeposit(swapId, txHash, metadata)
+  }
+}
+```
+
+### 3. Factory Function
+
+Provide a factory function for easy instantiation:
+
+```typescript
+export function createMyBackend(config: MyBackendConfig): SettlementBackend {
+  return new MySettlementBackend(config)
+}
+```
+
+### 4. Registry Entry
+
+Create a registry entry for discoverability:
+
+```typescript
+export const myBackendRegistry: SettlementBackendRegistry = {
+  name: 'my-backend',
+  factory: createMyBackend,
+  displayName: 'My Settlement Backend',
+  description: 'Fast and reliable cross-chain swaps',
+  homepage: 'https://mybackend.com',
+  docs: 'https://docs.mybackend.com',
+}
+```
+
+## Privacy Support
+
+Backends should handle privacy levels appropriately:
+
+### Transparent Mode
+
+No privacy features required. Use sender's address directly.
+
+```typescript
+if (params.privacyLevel === PrivacyLevel.TRANSPARENT) {
+  // Use senderAddress as both sender and recipient
+  recipientAddress = params.senderAddress
+}
+```
+
+### Shielded Mode
+
+Generate stealth address for recipient:
+
+```typescript
+if (params.privacyLevel === PrivacyLevel.SHIELDED) {
+  // Generate stealth address from recipientMetaAddress
+  const { stealthAddress, ephemeralPublicKey } = generateStealthAddress(
+    params.recipientMetaAddress
+  )
+
+  recipientAddress = stealthAddress
+  // Store ephemeralPublicKey in metadata for recipient recovery
+}
+```
+
+### Compliant Mode
+
+Same as shielded, but include viewing key hash for auditors:
+
+```typescript
+if (params.privacyLevel === PrivacyLevel.COMPLIANT) {
+  // Generate stealth address + viewing key hash
+  const { stealthAddress, viewingKeyHash } = generateCompliantAddress(
+    params.recipientMetaAddress,
+    params.viewingKey
+  )
+
+  recipientAddress = stealthAddress
+  // Include viewingKeyHash in metadata for auditors
+}
+```
+
+## Error Handling
+
+Use standard SIP errors:
+
+```typescript
+import { ValidationError, NetworkError, ProofError } from '@sip-protocol/sdk'
+
+// Invalid parameters
+throw new ValidationError('Invalid amount', 'amount', { min: 0, received: -1 })
+
+// API/network issues
+throw new NetworkError('Backend API unavailable', { status: 503 })
+
+// Unsupported features
+throw new ProofError('Feature not supported by this backend')
+```
+
+## Testing
+
+Write comprehensive tests for your backend:
+
+```typescript
+import { describe, it, expect } from 'vitest'
+import { PrivacyLevel } from '@sip-protocol/types'
+import { MySettlementBackend } from './my-backend'
+
+describe('MySettlementBackend', () => {
+  it('should implement SettlementBackend interface', () => {
+    const backend = new MySettlementBackend(config)
+
+    expect(backend.name).toBe('my-backend')
+    expect(backend.capabilities).toBeDefined()
+    expect(typeof backend.getQuote).toBe('function')
+    expect(typeof backend.executeSwap).toBe('function')
+    expect(typeof backend.getStatus).toBe('function')
+  })
+
+  it('should get quote for valid params', async () => {
+    const backend = new MySettlementBackend(config)
+
+    const quote = await backend.getQuote({
+      fromChain: 'ethereum',
+      toChain: 'near',
+      fromToken: 'USDC',
+      toToken: 'NEAR',
+      amount: 1000000n,
+      privacyLevel: PrivacyLevel.TRANSPARENT,
+    })
+
+    expect(quote.quoteId).toBeDefined()
+    expect(quote.depositAddress).toBeDefined()
+    expect(BigInt(quote.amountOut)).toBeGreaterThan(0n)
+  })
+
+  // ... more tests
+})
+```
+
+## Examples
+
+See existing implementations:
+
+- `packages/sdk/src/adapters/near-intents.ts` - NEAR Intents adapter (reference implementation)
+- `packages/sdk/src/zcash/swap-service.ts` - Zcash swap service (privacy-focused)
+
+## Roadmap
+
+Planned backends for M11-M12 milestones:
+
+- [x] NEAR Intents (M1-M8)
+- [ ] Zcash Settlement Backend (M9)
+- [ ] THORChain Backend (M10)
+- [ ] Direct Chain Backend (M11)
+- [ ] Mina Protocol Backend (M12)
+
+## Resources
+
+- [SIP Protocol Documentation](https://docs.sip-protocol.org)
+- [NEAR Intents API](https://1click.chaindefuser.com)
+- [THORChain Docs](https://docs.thorchain.org)
+- [Zcash Shielded Transactions](https://z.cash/technology/zksnarks/)