@sip-protocol/sdk 0.1.8 → 0.2.0

package/src/oracle/types.ts

@@ -0,0 +1,257 @@
+/**
+ * Oracle Attestation Types
+ *
+ * Type definitions for the oracle attestation protocol.
+ *
+ * @see docs/specs/ORACLE-ATTESTATION.md
+ */
+
+import type { HexString, ChainId } from '@sip-protocol/types'
+
+// ─── Oracle Identity ──────────────────────────────────────────────────────────
+
+/**
+ * Oracle identifier (SHA256 hash of public key)
+ */
+export type OracleId = HexString
+
+/**
+ * Oracle status in the registry
+ */
+export type OracleStatus = 'active' | 'suspended' | 'removed'
+
+/**
+ * Oracle information stored in registry
+ */
+export interface OracleInfo {
+  /** Unique oracle identifier (hash of public key) */
+  id: OracleId
+
+  /** Oracle's Ed25519 public key (32 bytes) */
+  publicKey: HexString
+
+  /** Human-readable name */
+  name: string
+
+  /** Supported destination chains */
+  supportedChains: ChainId[]
+
+  /** Oracle endpoint URL */
+  endpoint: string
+
+  /** Registration timestamp (Unix seconds) */
+  registeredAt: number
+
+  /** Current status */
+  status: OracleStatus
+
+  /** Reputation score (0-100) */
+  reputation: number
+
+  /** Staked amount in smallest unit */
+  stake: bigint
+}
+
+// ─── Attestation Message ──────────────────────────────────────────────────────
+
+/**
+ * The canonical message format that oracles sign
+ *
+ * This structure is serialized deterministically for signing.
+ * Total serialized size: 197 bytes
+ */
+export interface OracleAttestationMessage {
+  /** Protocol version (current: 1) */
+  version: number
+
+  /** Destination chain numeric ID */
+  chainId: number
+
+  /** Hash of original intent (32 bytes) */
+  intentHash: HexString
+
+  /** Recipient address, normalized to 32 bytes */
+  recipient: HexString
+
+  /** Amount delivered in smallest unit */
+  amount: bigint
+
+  /** Asset identifier hash (32 bytes) */
+  assetId: HexString
+
+  /** Transaction hash on destination chain (32 bytes) */
+  txHash: HexString
+
+  /** Block number containing transaction */
+  blockNumber: bigint
+
+  /** Block hash for finality verification (32 bytes) */
+  blockHash: HexString
+
+  /** Unix timestamp of attestation creation */
+  timestamp: number
+}
+
+// ─── Signatures ───────────────────────────────────────────────────────────────
+
+/**
+ * A single oracle's signature on an attestation
+ */
+export interface OracleSignature {
+  /** Oracle that produced this signature */
+  oracleId: OracleId
+
+  /** Ed25519 signature (64 bytes) */
+  signature: HexString
+}
+
+/**
+ * Complete attestation with message and signatures
+ */
+export interface SignedOracleAttestation {
+  /** The attested message */
+  message: OracleAttestationMessage
+
+  /** Signatures from k-of-n oracles */
+  signatures: OracleSignature[]
+}
+
+// ─── Registry ─────────────────────────────────────────────────────────────────
+
+/**
+ * Oracle registry containing all registered oracles
+ */
+export interface OracleRegistry {
+  /** Registered oracles indexed by ID */
+  oracles: Map<OracleId, OracleInfo>
+
+  /** Required signature threshold (k in k-of-n) */
+  threshold: number
+
+  /** Total number of oracles (n in k-of-n) */
+  totalOracles: number
+
+  /** Registry version for upgrades */
+  version: number
+
+  /** Last update timestamp */
+  lastUpdated: number
+}
+
+/**
+ * Oracle registry configuration
+ */
+export interface OracleRegistryConfig {
+  /** Minimum required signatures (default: 3) */
+  threshold?: number
+
+  /** Oracle endpoint timeout in ms (default: 30000) */
+  timeout?: number
+
+  /** Custom registry data (for testing) */
+  customOracles?: OracleInfo[]
+}
+
+// ─── Attestation Request ──────────────────────────────────────────────────────
+
+/**
+ * Request for oracle attestation
+ */
+export interface AttestationRequest {
+  /** Intent hash to attest */
+  intentHash: HexString
+
+  /** Destination chain */
+  destinationChain: ChainId
+
+  /** Expected recipient address */
+  expectedRecipient: HexString
+
+  /** Expected asset identifier */
+  expectedAsset: HexString
+
+  /** Minimum amount expected */
+  minAmount: bigint
+
+  /** Deadline for fulfillment (Unix timestamp) */
+  deadline: number
+}
+
+/**
+ * Result of attestation request
+ */
+export interface AttestationResult {
+  /** Whether attestation was successful */
+  success: boolean
+
+  /** The signed attestation (if successful) */
+  attestation?: SignedOracleAttestation
+
+  /** Error message (if failed) */
+  error?: string
+
+  /** Number of oracles that responded */
+  oracleResponses: number
+
+  /** Number of valid signatures collected */
+  validSignatures: number
+}
+
+// ─── Verification ─────────────────────────────────────────────────────────────
+
+/**
+ * Result of attestation verification
+ */
+export interface VerificationResult {
+  /** Whether verification passed */
+  valid: boolean
+
+  /** Number of valid signatures found */
+  validSignatures: number
+
+  /** Required threshold */
+  threshold: number
+
+  /** List of oracle IDs with valid signatures */
+  validOracles: OracleId[]
+
+  /** Error details (if invalid) */
+  errors?: string[]
+}
+
+// ─── Constants ────────────────────────────────────────────────────────────────
+
+/**
+ * Domain separator for attestation signing
+ */
+export const ORACLE_DOMAIN = 'SIP-ORACLE-ATTESTATION-V1'
+
+/**
+ * Current attestation protocol version
+ */
+export const ATTESTATION_VERSION = 1
+
+/**
+ * Default signature threshold
+ */
+export const DEFAULT_THRESHOLD = 3
+
+/**
+ * Default total oracles
+ */
+export const DEFAULT_TOTAL_ORACLES = 5
+
+/**
+ * Chain numeric IDs for attestation message
+ */
+export const CHAIN_NUMERIC_IDS: Record<ChainId, number> = {
+  ethereum: 1,
+  polygon: 137,
+  arbitrum: 42161,
+  optimism: 10,
+  base: 8453,
+  bitcoin: 0, // Non-standard, SIP-specific (Bitcoin mainnet)
+  solana: 501, // Non-standard, SIP-specific
+  near: 502, // Non-standard, SIP-specific
+  zcash: 503, // Non-standard, SIP-specific
+}

package/src/oracle/verification.ts

@@ -0,0 +1,257 @@
+/**
+ * Oracle Attestation Verification
+ *
+ * Verification of oracle signatures on attestation messages.
+ *
+ * @see docs/specs/ORACLE-ATTESTATION.md Section 4
+ */
+
+import { ed25519 } from '@noble/curves/ed25519'
+import { sha256 } from '@noble/hashes/sha256'
+import { bytesToHex, hexToBytes } from '@noble/hashes/utils'
+import type { HexString } from '@sip-protocol/types'
+import type {
+  OracleId,
+  OracleInfo,
+  OracleRegistry,
+  OracleRegistryConfig,
+  OracleSignature,
+  SignedOracleAttestation,
+  VerificationResult,
+} from './types'
+import { DEFAULT_THRESHOLD, DEFAULT_TOTAL_ORACLES } from './types'
+import { computeAttestationHash } from './serialization'
+
+/**
+ * Derive oracle ID from public key
+ *
+ * OracleId = SHA256(publicKey)
+ */
+export function deriveOracleId(publicKey: HexString | Uint8Array): OracleId {
+  const keyBytes = typeof publicKey === 'string'
+    ? hexToBytes(publicKey.startsWith('0x') ? publicKey.slice(2) : publicKey)
+    : publicKey
+
+  const hash = sha256(keyBytes)
+  return `0x${bytesToHex(hash)}` as OracleId
+}
+
+/**
+ * Verify a signed oracle attestation
+ *
+ * Checks:
+ * 1. Sufficient signatures (>= threshold)
+ * 2. All signatures are from registered, active oracles
+ * 3. All signatures are valid Ed25519 signatures
+ * 4. No duplicate oracles
+ */
+export function verifyAttestation(
+  attestation: SignedOracleAttestation,
+  registry: OracleRegistry
+): VerificationResult {
+  const { message, signatures } = attestation
+  const errors: string[] = []
+  const validOracles: OracleId[] = []
+
+  // Check we have enough signatures
+  if (signatures.length < registry.threshold) {
+    errors.push(
+      `Insufficient signatures: ${signatures.length} < ${registry.threshold} required`
+    )
+  }
+
+  // Compute message hash for verification
+  const messageHash = computeAttestationHash(message)
+
+  // Track seen oracles to prevent duplicates
+  const seenOracles = new Set<OracleId>()
+  let validCount = 0
+
+  for (const sig of signatures) {
+    // Check for duplicate oracles
+    if (seenOracles.has(sig.oracleId)) {
+      errors.push(`Duplicate signature from oracle: ${sig.oracleId}`)
+      continue
+    }
+    seenOracles.add(sig.oracleId)
+
+    // Get oracle from registry
+    const oracle = registry.oracles.get(sig.oracleId)
+    if (!oracle) {
+      errors.push(`Unknown oracle: ${sig.oracleId}`)
+      continue
+    }
+
+    if (oracle.status !== 'active') {
+      errors.push(`Oracle not active: ${sig.oracleId} (status: ${oracle.status})`)
+      continue
+    }
+
+    // Verify Ed25519 signature
+    try {
+      const publicKeyBytes = hexToBytes(
+        oracle.publicKey.startsWith('0x')
+          ? oracle.publicKey.slice(2)
+          : oracle.publicKey
+      )
+      const signatureBytes = hexToBytes(
+        sig.signature.startsWith('0x')
+          ? sig.signature.slice(2)
+          : sig.signature
+      )
+
+      const isValid = ed25519.verify(signatureBytes, messageHash, publicKeyBytes)
+
+      if (isValid) {
+        validCount++
+        validOracles.push(sig.oracleId)
+      } else {
+        errors.push(`Invalid signature from oracle: ${sig.oracleId}`)
+      }
+    } catch (e) {
+      errors.push(`Signature verification error for ${sig.oracleId}: ${e}`)
+    }
+  }
+
+  const valid = validCount >= registry.threshold && errors.length === 0
+
+  return {
+    valid,
+    validSignatures: validCount,
+    threshold: registry.threshold,
+    validOracles,
+    errors: errors.length > 0 ? errors : undefined,
+  }
+}
+
+/**
+ * Verify a single oracle signature
+ */
+export function verifyOracleSignature(
+  signature: OracleSignature,
+  messageHash: Uint8Array,
+  oracle: OracleInfo
+): boolean {
+  try {
+    const publicKeyBytes = hexToBytes(
+      oracle.publicKey.startsWith('0x')
+        ? oracle.publicKey.slice(2)
+        : oracle.publicKey
+    )
+    const signatureBytes = hexToBytes(
+      signature.signature.startsWith('0x')
+        ? signature.signature.slice(2)
+        : signature.signature
+    )
+
+    return ed25519.verify(signatureBytes, messageHash, publicKeyBytes)
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Sign an attestation message (for oracle implementations)
+ */
+export function signAttestationMessage(
+  messageHash: Uint8Array,
+  privateKey: Uint8Array
+): OracleSignature {
+  const signature = ed25519.sign(messageHash, privateKey)
+  const publicKey = ed25519.getPublicKey(privateKey)
+  const oracleId = deriveOracleId(publicKey)
+
+  return {
+    oracleId,
+    signature: `0x${bytesToHex(signature)}` as HexString,
+  }
+}
+
+// ─── Registry Management ──────────────────────────────────────────────────────
+
+/**
+ * Create a new oracle registry
+ */
+export function createOracleRegistry(
+  config: OracleRegistryConfig = {}
+): OracleRegistry {
+  const registry: OracleRegistry = {
+    oracles: new Map(),
+    threshold: config.threshold ?? DEFAULT_THRESHOLD,
+    totalOracles: 0,
+    version: 1,
+    lastUpdated: Date.now(),
+  }
+
+  // Add custom oracles if provided
+  if (config.customOracles) {
+    for (const oracle of config.customOracles) {
+      registry.oracles.set(oracle.id, oracle)
+    }
+    registry.totalOracles = config.customOracles.length
+  }
+
+  return registry
+}
+
+/**
+ * Add an oracle to the registry
+ */
+export function addOracle(
+  registry: OracleRegistry,
+  oracle: OracleInfo
+): void {
+  registry.oracles.set(oracle.id, oracle)
+  registry.totalOracles = registry.oracles.size
+  registry.lastUpdated = Date.now()
+}
+
+/**
+ * Remove an oracle from the registry
+ */
+export function removeOracle(
+  registry: OracleRegistry,
+  oracleId: OracleId
+): boolean {
+  const removed = registry.oracles.delete(oracleId)
+  if (removed) {
+    registry.totalOracles = registry.oracles.size
+    registry.lastUpdated = Date.now()
+  }
+  return removed
+}
+
+/**
+ * Update oracle status
+ */
+export function updateOracleStatus(
+  registry: OracleRegistry,
+  oracleId: OracleId,
+  status: OracleInfo['status']
+): boolean {
+  const oracle = registry.oracles.get(oracleId)
+  if (!oracle) {
+    return false
+  }
+
+  oracle.status = status
+  registry.lastUpdated = Date.now()
+  return true
+}
+
+/**
+ * Get all active oracles
+ */
+export function getActiveOracles(registry: OracleRegistry): OracleInfo[] {
+  return Array.from(registry.oracles.values()).filter(
+    (oracle) => oracle.status === 'active'
+  )
+}
+
+/**
+ * Check if registry has enough active oracles for threshold
+ */
+export function hasEnoughOracles(registry: OracleRegistry): boolean {
+  const activeCount = getActiveOracles(registry).length
+  return activeCount >= registry.threshold
+}

package/src/proofs/browser-utils.ts

@@ -0,0 +1,141 @@
+/**
+ * Browser-compatible utilities for proof generation
+ *
+ * These utilities replace Node.js-specific functions (like Buffer)
+ * with browser-compatible alternatives using Web APIs.
+ *
+ * @module proofs/browser-utils
+ */
+
+/**
+ * Convert hex string to Uint8Array (browser-compatible)
+ */
+export function hexToBytes(hex: string): Uint8Array {
+  const h = hex.startsWith('0x') ? hex.slice(2) : hex
+  if (h.length === 0) return new Uint8Array(0)
+  if (h.length % 2 !== 0) {
+    throw new Error('Hex string must have even length')
+  }
+  const bytes = new Uint8Array(h.length / 2)
+  for (let i = 0; i < bytes.length; i++) {
+    bytes[i] = parseInt(h.slice(i * 2, i * 2 + 2), 16)
+  }
+  return bytes
+}
+
+/**
+ * Convert Uint8Array to hex string (browser-compatible)
+ */
+export function bytesToHex(bytes: Uint8Array): string {
+  return Array.from(bytes)
+    .map((b) => b.toString(16).padStart(2, '0'))
+    .join('')
+}
+
+/**
+ * Check if running in browser environment
+ */
+export function isBrowser(): boolean {
+  return typeof window !== 'undefined' && typeof window.document !== 'undefined'
+}
+
+/**
+ * Check if Web Workers are available
+ */
+export function supportsWebWorkers(): boolean {
+  return typeof Worker !== 'undefined'
+}
+
+/**
+ * Check if SharedArrayBuffer is available (required for some WASM operations)
+ */
+export function supportsSharedArrayBuffer(): boolean {
+  try {
+    return typeof SharedArrayBuffer !== 'undefined'
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Get browser info for diagnostics
+ */
+export function getBrowserInfo(): {
+  isBrowser: boolean
+  supportsWorkers: boolean
+  supportsSharedArrayBuffer: boolean
+  userAgent: string | null
+} {
+  return {
+    isBrowser: isBrowser(),
+    supportsWorkers: supportsWebWorkers(),
+    supportsSharedArrayBuffer: supportsSharedArrayBuffer(),
+    userAgent: typeof navigator !== 'undefined' ? navigator.userAgent : null,
+  }
+}
+
+/**
+ * Load script dynamically (for WASM loading)
+ */
+export function loadScript(src: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (!isBrowser()) {
+      reject(new Error('loadScript can only be used in browser'))
+      return
+    }
+    const script = document.createElement('script')
+    script.src = src
+    script.onload = () => resolve()
+    script.onerror = () => reject(new Error(`Failed to load script: ${src}`))
+    document.head.appendChild(script)
+  })
+}
+
+/**
+ * Estimate available memory (approximate, browser-specific)
+ */
+export async function estimateAvailableMemory(): Promise<number | null> {
+  if (!isBrowser()) return null
+
+  // Use Performance API if available (Chrome)
+  // @ts-expect-error - Performance.measureUserAgentSpecificMemory is Chrome-specific
+  if (typeof performance !== 'undefined' && performance.measureUserAgentSpecificMemory) {
+    try {
+      // @ts-expect-error - Chrome-specific API
+      const result = await performance.measureUserAgentSpecificMemory()
+      return result.bytes
+    } catch {
+      // API not available or permission denied
+    }
+  }
+
+  // Use navigator.deviceMemory if available (Chrome, Opera)
+  // @ts-expect-error - deviceMemory is non-standard
+  if (typeof navigator !== 'undefined' && navigator.deviceMemory) {
+    // Returns approximate device memory in GB
+    // @ts-expect-error - deviceMemory is non-standard
+    return navigator.deviceMemory * 1024 * 1024 * 1024
+  }
+
+  return null
+}
+
+/**
+ * Create a blob URL for worker code (inline worker support)
+ */
+export function createWorkerBlobUrl(code: string): string {
+  if (!isBrowser()) {
+    throw new Error('createWorkerBlobUrl can only be used in browser')
+  }
+  const blob = new Blob([code], { type: 'application/javascript' })
+  return URL.createObjectURL(blob)
+}
+
+/**
+ * Revoke a blob URL to free memory
+ */
+export function revokeWorkerBlobUrl(url: string): void {
+  if (isBrowser() && url.startsWith('blob:')) {
+    URL.revokeObjectURL(url)
+  }
+}