@sip-protocol/sdk 0.9.0 → 0.11.0

package/src/adapters/gelato-relay.ts

@@ -0,0 +1,386 @@
+/**
+ * Gelato Relay Adapter for SIP Protocol
+ *
+ * Enables gasless claim and withdrawal from stealth addresses via Gelato Relay.
+ * Recipients can claim funds without holding ETH for gas — critical for stealth
+ * addresses which are freshly generated and have zero balance.
+ *
+ * ## Two Modes
+ *
+ * - **sponsoredCall**: SIP pays gas from Gas Tank (requires API key)
+ * - **callWithSyncFee**: Fee deducted from withdrawal amount (requires SIPRelayer)
+ *
+ * ```
+ * ┌──────────────────────────────────────────────────────────┐
+ * │  GELATO RELAY + SIP PRIVACY FLOW                         │
+ * │                                                          │
+ * │  Sponsored Mode:                                         │
+ * │  1. Recipient calls sponsoredClaim() with proof          │
+ * │  2. Gelato relays tx to SIPPrivacy.withdrawDeposit()     │
+ * │  3. SIP Gas Tank pays the gas fee                        │
+ * │  4. Funds arrive at recipient stealth address             │
+ * │                                                          │
+ * │  SyncFee Mode:                                           │
+ * │  1. Recipient calls syncFeeClaim() with proof + maxFee   │
+ * │  2. Gelato relays tx to SIPRelayer contract              │
+ * │  3. SIPRelayer calls SIPPrivacy.withdrawDeposit()        │
+ * │  4. SIPRelayer deducts gas fee from withdrawn amount     │
+ * │  5. Remainder arrives at recipient stealth address        │
+ * │                                                          │
+ * │  Result: Zero-gas claims from stealth addresses          │
+ * └──────────────────────────────────────────────────────────┘
+ * ```
+ *
+ * ## ABI Encoding
+ *
+ * Uses manual ABI encoding with @noble/hashes keccak256 for function selectors.
+ * No ethers.js or viem dependency required.
+ *
+ * @see https://docs.gelato.network/web3-services/relay
+ */
+
+import { keccak_256 } from '@noble/hashes/sha3'
+import { bytesToHex } from '@noble/hashes/utils'
+
+// ═══════════════════════════════════════════
+// Types
+// ═══════════════════════════════════════════
+
+export interface GelatoRelayConfig {
+  /** Gelato Gas Tank API key (required for sponsoredCall) */
+  apiKey?: string
+  /** Target chain ID (e.g. 11155111 for Sepolia) */
+  chainId: number
+  /** SIPPrivacy contract address */
+  sipPrivacyAddress: string
+  /** SIPRelayer contract address (required for callWithSyncFee) */
+  sipRelayerAddress?: string
+}
+
+export interface RelayClaimParams {
+  /** Deposit transfer ID */
+  transferId: bigint
+  /** Nullifier hash (bytes32 hex) */
+  nullifier: string
+  /** ZK proof (bytes hex) */
+  proof: string
+  /** Recipient address (20-byte hex) */
+  recipient: string
+}
+
+export interface SyncFeeClaimParams extends RelayClaimParams {
+  /** Token to pay Gelato fee in */
+  feeToken: string
+  /** Maximum fee willing to pay */
+  maxFee: bigint
+  /** ERC20 token address (omit or zero address for ETH) */
+  token?: string
+}
+
+export interface RelayResult {
+  /** Gelato task ID for tracking */
+  taskId: string
+  /** Which relay mode was used */
+  mode: 'sponsored' | 'syncFee'
+}
+
+export type TaskStatus =
+  | 'CheckPending'
+  | 'ExecPending'
+  | 'ExecSuccess'
+  | 'ExecReverted'
+  | 'Cancelled'
+
+export interface TaskStatusResult {
+  /** Gelato task ID */
+  taskId: string
+  /** Current task state */
+  taskState: TaskStatus
+  /** Transaction hash (available after execution) */
+  transactionHash?: string
+  /** Block number (available after execution) */
+  blockNumber?: number
+}
+
+// ═══════════════════════════════════════════
+// Constants
+// ═══════════════════════════════════════════
+
+const GELATO_RELAY_URL = 'https://relay.gelato.digital'
+const ZERO_ADDRESS = '0x0000000000000000000000000000000000000000'
+
+// ═══════════════════════════════════════════
+// ABI Encoding Helpers (no ethers/viem)
+// ═══════════════════════════════════════════
+
+/**
+ * Compute 4-byte function selector from Solidity signature.
+ * selector = keccak256(signature)[0:4]
+ */
+export function functionSelector(signature: string): string {
+  const hash = keccak_256(new TextEncoder().encode(signature))
+  return '0x' + bytesToHex(hash).slice(0, 8)
+}
+
+/** Left-pad a bigint to 32 bytes (64 hex chars) */
+function padUint256(value: bigint): string {
+  if (value < 0n) throw new Error(`uint256 cannot be negative: ${value}`)
+  if (value >= 2n ** 256n) throw new Error(`uint256 overflow: ${value}`)
+  return value.toString(16).padStart(64, '0')
+}
+
+/** Left-pad an address to 32 bytes (64 hex chars) */
+function padAddress(addr: string): string {
+  const clean = addr.startsWith('0x') ? addr.slice(2) : addr
+  if (clean.length !== 40) {
+    throw new Error(`Invalid address length: expected 40 hex chars, got ${clean.length}`)
+  }
+  return clean.toLowerCase().padStart(64, '0')
+}
+
+/** Right-pad a bytes32 value to 32 bytes (64 hex chars) */
+function padBytes32(value: string): string {
+  const clean = value.startsWith('0x') ? value.slice(2) : value
+  if (clean.length > 64) {
+    throw new Error(`bytes32 value too long: ${clean.length} hex chars (max 64)`)
+  }
+  return clean.padEnd(64, '0')
+}
+
+/**
+ * ABI-encode a dynamic `bytes` value.
+ * Returns: length (32 bytes) + data (padded to 32-byte boundary)
+ */
+function encodeBytes(value: string): string {
+  const clean = value.startsWith('0x') ? value.slice(2) : value
+  if (clean.length % 2 !== 0) {
+    throw new Error(`bytes value must have even hex length, got ${clean.length}`)
+  }
+  const length = clean.length / 2
+  const paddedData = clean.length % 64 === 0
+    ? clean
+    : clean + '0'.repeat(64 - (clean.length % 64))
+  return padUint256(BigInt(length)) + paddedData
+}
+
+// ═══════════════════════════════════════════
+// GelatoRelayAdapter
+// ═══════════════════════════════════════════
+
+export class GelatoRelayAdapter {
+  private config: GelatoRelayConfig
+
+  constructor(config: GelatoRelayConfig) {
+    if (!config.sipPrivacyAddress) {
+      throw new Error('sipPrivacyAddress is required')
+    }
+    if (!config.chainId) {
+      throw new Error('chainId is required')
+    }
+    this.config = config
+  }
+
+  /**
+   * Gasless withdrawal via sponsoredCall (SIP pays gas from Gas Tank).
+   * Calls SIPPrivacy.withdrawDeposit() directly.
+   */
+  async sponsoredClaim(params: RelayClaimParams): Promise<RelayResult> {
+    if (!this.config.apiKey) {
+      throw new Error('API key required for sponsoredCall')
+    }
+
+    const data = this.encodeWithdrawDeposit(params)
+
+    const response = await fetch(`${GELATO_RELAY_URL}/relays/v2/sponsored-call`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        chainId: this.config.chainId,
+        target: this.config.sipPrivacyAddress,
+        data,
+        sponsorApiKey: this.config.apiKey,
+      }),
+    })
+
+    if (!response.ok) {
+      const text = await response.text().catch(() => response.statusText)
+      throw new Error(`Gelato relay error: ${response.status} ${text}`)
+    }
+
+    const result = await response.json()
+    return { taskId: result.taskId, mode: 'sponsored' }
+  }
+
+  /**
+   * Gasless withdrawal via callWithSyncFee (fee deducted from withdrawn amount).
+   * Routes through SIPRelayer contract which handles fee deduction.
+   *
+   * - ETH withdrawals: calls relayedWithdrawETH()
+   * - ERC20 withdrawals: calls relayedWithdrawToken() (when params.token is set)
+   */
+  async syncFeeClaim(params: SyncFeeClaimParams): Promise<RelayResult> {
+    if (!this.config.sipRelayerAddress) {
+      throw new Error('SIPRelayer address required for callWithSyncFee')
+    }
+
+    const isToken = params.token && params.token !== ZERO_ADDRESS
+    const data = isToken
+      ? this.encodeRelayedWithdrawToken(params)
+      : this.encodeRelayedWithdrawETH(params)
+
+    const response = await fetch(`${GELATO_RELAY_URL}/relays/v2/call-with-sync-fee`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        chainId: this.config.chainId,
+        target: this.config.sipRelayerAddress,
+        data,
+        feeToken: params.feeToken,
+        isRelayContext: true,
+      }),
+    })
+
+    if (!response.ok) {
+      const text = await response.text().catch(() => response.statusText)
+      throw new Error(`Gelato relay error: ${response.status} ${text}`)
+    }
+
+    const result = await response.json()
+    return { taskId: result.taskId, mode: 'syncFee' }
+  }
+
+  /**
+   * Check relay task status.
+   * Poll this after submitting a relay request to track execution.
+   */
+  async getTaskStatus(taskId: string): Promise<TaskStatusResult> {
+    if (!taskId) {
+      throw new Error('taskId is required')
+    }
+    if (!/^[a-zA-Z0-9_-]+$/.test(taskId)) {
+      throw new Error(`Invalid taskId format: ${taskId}`)
+    }
+
+    const response = await fetch(`${GELATO_RELAY_URL}/tasks/status/${taskId}`)
+
+    if (!response.ok) {
+      throw new Error(`Gelato status error: ${response.status}`)
+    }
+
+    const result = await response.json()
+    return {
+      taskId: result.task.taskId,
+      taskState: result.task.taskState,
+      transactionHash: result.task.transactionHash,
+      blockNumber: result.task.blockNumber,
+    }
+  }
+
+  // ═══════════════════════════════════════════
+  // ABI Encoding (no ethers/viem dependency)
+  // ═══════════════════════════════════════════
+
+  /**
+   * Encode withdrawDeposit(uint256,bytes32,bytes,address)
+   *
+   * ABI layout:
+   *   [selector 4B]
+   *   [0x00] transferId        — uint256
+   *   [0x20] nullifier         — bytes32
+   *   [0x40] proof offset      — uint256 (points to 0x80)
+   *   [0x60] recipient         — address
+   *   [0x80] proof length      — uint256
+   *   [0xa0] proof data        — bytes (padded)
+   */
+  private encodeWithdrawDeposit(params: RelayClaimParams): string {
+    const selector = functionSelector('withdrawDeposit(uint256,bytes32,bytes,address)')
+    const proofOffset = padUint256(128n) // 4 slots * 32 = 128
+
+    return selector
+      + padUint256(params.transferId)
+      + padBytes32(params.nullifier)
+      + proofOffset
+      + padAddress(params.recipient)
+      + encodeBytes(params.proof)
+  }
+
+  /**
+   * Encode relayedWithdrawETH(uint256,bytes32,bytes,address,uint256)
+   *
+   * ABI layout:
+   *   [selector 4B]
+   *   [0x00] transferId        — uint256
+   *   [0x20] nullifier         — bytes32
+   *   [0x40] proof offset      — uint256 (points to 0xa0)
+   *   [0x60] recipient         — address
+   *   [0x80] maxFee            — uint256
+   *   [0xa0] proof length      — uint256
+   *   [0xc0] proof data        — bytes (padded)
+   */
+  private encodeRelayedWithdrawETH(params: SyncFeeClaimParams): string {
+    const selector = functionSelector('relayedWithdrawETH(uint256,bytes32,bytes,address,uint256)')
+    const proofOffset = padUint256(160n) // 5 slots * 32 = 160
+
+    return selector
+      + padUint256(params.transferId)
+      + padBytes32(params.nullifier)
+      + proofOffset
+      + padAddress(params.recipient)
+      + padUint256(params.maxFee)
+      + encodeBytes(params.proof)
+  }
+
+  /**
+   * Encode relayedWithdrawToken(uint256,bytes32,bytes,address,address,uint256)
+   *
+   * ABI layout:
+   *   [selector 4B]
+   *   [0x00] transferId        — uint256
+   *   [0x20] nullifier         — bytes32
+   *   [0x40] proof offset      — uint256 (points to 0xc0)
+   *   [0x60] recipient         — address
+   *   [0x80] token             — address
+   *   [0xa0] maxFee            — uint256
+   *   [0xc0] proof length      — uint256
+   *   [0xe0] proof data        — bytes (padded)
+   */
+  private encodeRelayedWithdrawToken(params: SyncFeeClaimParams): string {
+    const selector = functionSelector('relayedWithdrawToken(uint256,bytes32,bytes,address,address,uint256)')
+    const proofOffset = padUint256(192n) // 6 slots * 32 = 192
+
+    return selector
+      + padUint256(params.transferId)
+      + padBytes32(params.nullifier)
+      + proofOffset
+      + padAddress(params.recipient)
+      + padAddress(params.token!)
+      + padUint256(params.maxFee)
+      + encodeBytes(params.proof)
+  }
+}
+
+/**
+ * Factory function for creating a GelatoRelayAdapter.
+ *
+ * @example
+ * ```typescript
+ * // Sponsored mode (SIP pays gas)
+ * const relay = createGelatoRelayAdapter({
+ *   apiKey: 'gelato-api-key',
+ *   chainId: 11155111,
+ *   sipPrivacyAddress: '0x1FED...',
+ * })
+ * const result = await relay.sponsoredClaim({ transferId, nullifier, proof, recipient })
+ *
+ * // SyncFee mode (fee from withdrawal)
+ * const relay = createGelatoRelayAdapter({
+ *   chainId: 11155111,
+ *   sipPrivacyAddress: '0x1FED...',
+ *   sipRelayerAddress: '0xABC...',
+ * })
+ * const result = await relay.syncFeeClaim({ transferId, nullifier, proof, recipient, feeToken, maxFee })
+ * ```
+ */
+export function createGelatoRelayAdapter(config: GelatoRelayConfig): GelatoRelayAdapter {
+  return new GelatoRelayAdapter(config)
+}

package/src/adapters/index.ts

@@ -11,6 +11,9 @@
  * ### Solana DEX
  * - **JupiterAdapter** — Jupiter aggregator for private Solana swaps
  *
+ * ### EVM Relay
+ * - **GelatoRelayAdapter** — Gasless claims from stealth addresses via Gelato Relay
+ *
  * @example
  * ```typescript
  * import { JupiterAdapter, NEARIntentsAdapter } from '@sip-protocol/sdk'
@@ -58,3 +61,28 @@ export type {
   JupiterSwapResult,
   JupiterPrivateSwapResult,
 } from './jupiter'
+
+// 1inch Aggregator (EVM)
+export { OneInchAdapter } from './oneinch'
+
+export type {
+  OneInchQuote,
+  OneInchSwapData,
+  OneInchSwapParams,
+} from './oneinch'
+
+// Gelato Relay (EVM gasless)
+export {
+  GelatoRelayAdapter,
+  createGelatoRelayAdapter,
+  functionSelector,
+} from './gelato-relay'
+
+export type {
+  GelatoRelayConfig,
+  RelayClaimParams,
+  SyncFeeClaimParams,
+  RelayResult,
+  TaskStatus,
+  TaskStatusResult,
+} from './gelato-relay'

package/src/adapters/oneinch.ts

@@ -0,0 +1,126 @@
+/**
+ * 1inch Aggregator Adapter for SIP Protocol
+ *
+ * Generates swap calldata for privacy-preserving EVM swaps via 1inch aggregator.
+ * SIP adds stealth addresses as the swap recipient, breaking the on-chain identity link.
+ *
+ * ## Privacy Model
+ *
+ * 1inch swaps are routed through 200+ DEX pools for best price. SIP enhances privacy by:
+ * - Setting `destReceiver` to a stealth address (recipient unlinkable)
+ * - SIPSwapRouter validates calldata on-chain before forwarding to 1inch
+ *
+ * ```
+ * ┌──────────────────────────────────────────────────────────────┐
+ * │  1INCH + SIP PRIVACY FLOW                                    │
+ * │                                                              │
+ * │  1. SDK: Generate stealth address for output                 │
+ * │  2. SDK: Call 1inch API (destReceiver = stealth)             │
+ * │  3. SDK: Submit calldata to SIPSwapRouter                    │
+ * │  4. Contract: Validate calldata, deduct fee, forward         │
+ * │  5. 1inch Router → DEX pools → stealth address               │
+ * │                                                              │
+ * │  Result: Best-price swap, recipient unlinkable               │
+ * └──────────────────────────────────────────────────────────────┘
+ * ```
+ *
+ * @see https://portal.1inch.dev
+ */
+
+export interface OneInchQuote {
+  toAmount: string
+  estimatedGas: string
+  protocols: Array<{ name: string; part: number }>
+}
+
+export interface OneInchSwapData {
+  tx: {
+    to: string
+    data: string
+    value: string
+    gas: number
+  }
+  toAmount: string
+}
+
+export interface OneInchSwapParams {
+  src: string
+  dst: string
+  amount: string
+  from: string
+  destReceiver: string
+  slippage: number
+  disableEstimate?: boolean
+}
+
+const CHAIN_IDS: Record<string, number> = {
+  ethereum: 1,
+  arbitrum: 42161,
+  optimism: 10,
+  base: 8453,
+  polygon: 137,
+}
+
+const ONEINCH_ROUTER = '0x111111125421cA6dc452d289314280a0f8842A65'
+const API_BASE = 'https://api.1inch.dev/swap/v6.0'
+
+export class OneInchAdapter {
+  private apiKey: string
+  private chainId: number
+
+  constructor(apiKey: string, chain: string | number) {
+    this.apiKey = apiKey
+    this.chainId = typeof chain === 'number' ? chain : CHAIN_IDS[chain]
+    if (!this.chainId) throw new Error(`Unsupported chain: ${chain}`)
+  }
+
+  get routerAddress(): string {
+    return ONEINCH_ROUTER
+  }
+
+  async getQuote(params: {
+    src: string
+    dst: string
+    amount: string
+  }): Promise<OneInchQuote> {
+    const url = new URL(`${API_BASE}/${this.chainId}/quote`)
+    url.searchParams.set('src', params.src)
+    url.searchParams.set('dst', params.dst)
+    url.searchParams.set('amount', params.amount)
+
+    const response = await fetch(url.toString(), {
+      headers: { Authorization: `Bearer ${this.apiKey}` },
+    })
+
+    if (!response.ok) {
+      throw new Error(`1inch API error: ${response.status} ${response.statusText}`)
+    }
+
+    return response.json()
+  }
+
+  async getSwapCalldata(params: OneInchSwapParams): Promise<OneInchSwapData> {
+    const url = new URL(`${API_BASE}/${this.chainId}/swap`)
+    url.searchParams.set('src', params.src)
+    url.searchParams.set('dst', params.dst)
+    url.searchParams.set('amount', params.amount)
+    url.searchParams.set('from', params.from)
+    url.searchParams.set('destReceiver', params.destReceiver)
+    url.searchParams.set('slippage', params.slippage.toString())
+    url.searchParams.set('disableEstimate', (params.disableEstimate ?? true).toString())
+
+    const response = await fetch(url.toString(), {
+      headers: { Authorization: `Bearer ${this.apiKey}` },
+    })
+
+    if (!response.ok) {
+      throw new Error(`1inch API error: ${response.status} ${response.statusText}`)
+    }
+
+    return response.json()
+  }
+
+  static supportedChains(): string[] {
+    return Object.keys(CHAIN_IDS)
+  }
+}

package/src/chains/ethereum/index.ts

@@ -67,6 +67,7 @@ export type {
   EthereumPrivacyAdapterState,
   EthereumScanRecipient,
   EthereumDetectedPaymentResult,
+  EthereumViewOnlyDetectionResult,
 } from './types'
 
 // ─── Stealth Addresses ────────────────────────────────────────────────────────
@@ -85,6 +86,7 @@ export {
   deriveEthereumStealthPrivateKey,
   checkEthereumStealthAddress,
   checkEthereumStealthByEthAddress,
+  checkEthereumStealthByEthAddressViewOnly,
   stealthPublicKeyToEthAddress,
   extractPublicKeys,
   createMetaAddressFromPublicKeys,

package/src/chains/ethereum/privacy-adapter.ts

@@ -18,6 +18,7 @@ import {
   deriveEthereumStealthPrivateKey,
   checkEthereumStealthAddress,
   checkEthereumStealthByEthAddress,
+  checkEthereumStealthByEthAddressViewOnly,
   stealthPublicKeyToEthAddress,
   type EthereumStealthMetaAddress,
   type EthereumStealthAddress,
@@ -59,6 +60,7 @@ import type {
   EthereumPrivacyAdapterState,
   EthereumScanRecipient,
   EthereumDetectedPaymentResult,
+  EthereumViewOnlyDetectionResult,
   EthereumViewingKeyExport,
   EthereumViewingKeyPair,
   EthereumPedersenCommitment,
@@ -363,20 +365,23 @@ export class EthereumPrivacyAdapter {
   /**
    * Check if a stealth address belongs to a recipient
    *
+   * Canonical EIP-5564 view-only check: requires only the recipient's viewing
+   * private key plus their spending PUBLIC key (no spending private key needed).
+   *
    * @param stealthAddress - Stealth address object
-   * @param spendingPrivateKey - Spending private key (hex)
    * @param viewingPrivateKey - Viewing private key (hex)
+   * @param spendingPublicKey - Spending public key (hex, meta-address spendingKey)
    * @returns True if the address belongs to the recipient
    */
   checkStealthAddress(
     stealthAddress: StealthAddress,
-    spendingPrivateKey: HexString,
-    viewingPrivateKey: HexString
+    viewingPrivateKey: HexString,
+    spendingPublicKey: HexString
   ): boolean {
     return checkEthereumStealthAddress(
       stealthAddress,
-      spendingPrivateKey,
-      viewingPrivateKey
+      viewingPrivateKey,
+      spendingPublicKey
     )
   }
 
@@ -586,6 +591,11 @@ export class EthereumPrivacyAdapter {
 
       // Check each recipient
       for (const recipient of this.scanRecipients.values()) {
+        // The full scan derives the claimable key, which needs the spending private key.
+        // View-only recipients (no spending private key) are handled by scanAnnouncementsViewOnly.
+        if (!recipient.spendingPrivateKey) {
+          continue
+        }
         // Use ETH address comparison since announcements store 20-byte addresses
         // Returns the stealth private key if match found, null otherwise
         const stealthPrivateKey = checkEthereumStealthByEthAddress(
@@ -617,6 +627,55 @@ export class EthereumPrivacyAdapter {
     return results
   }
 
+  /**
+   * Scan announcements for incoming payments — VIEW-ONLY.
+   *
+   * Detects payments using each registered recipient's viewing private key + spending
+   * public key only (never the spending private key), so a compliance auditor or a
+   * delegated watcher can find incoming payments without spend authority. Results carry
+   * no derived private key — claim by deriving it separately at claim time (with both
+   * private keys).
+   *
+   * @param announcements - Announcements to scan
+   * @returns Detected payments (without private keys)
+   */
+  scanAnnouncementsViewOnly(
+    announcements: EthereumAnnouncement[]
+  ): EthereumViewOnlyDetectionResult[] {
+    const results: EthereumViewOnlyDetectionResult[] = []
+
+    for (const announcement of announcements) {
+      const stealthAddress = announcementToStealthAddress(announcement)
+
+      for (const recipient of this.scanRecipients.values()) {
+        const isMatch = checkEthereumStealthByEthAddressViewOnly(
+          announcement.stealthAddress,
+          announcement.ephemeralPublicKey,
+          announcement.viewTag,
+          recipient.spendingPublicKey,
+          recipient.viewingPrivateKey,
+        )
+
+        if (isMatch) {
+          results.push({
+            payment: {
+              stealthAddress,
+              stealthEthAddress: announcement.stealthAddress,
+              txHash: announcement.txHash!,
+              blockNumber: announcement.blockNumber!,
+              logIndex: announcement.logIndex,
+              timestamp: announcement.timestamp,
+            },
+            recipient,
+          })
+          break // Found owner, no need to check other recipients
+        }
+      }
+    }
+
+    return results
+  }
+
   /**
    * Get topics for filtering announcement logs
    *