@sip-protocol/sdk 0.5.1 → 0.6.1

package/src/privacy.ts

@@ -48,7 +48,41 @@ export interface PrivacyConfig {
 }
 
 /**
- * Get privacy configuration for a privacy level
+ * Get privacy configuration for a given privacy level
+ *
+ * Returns a configuration object that determines which privacy features
+ * to enable for an intent. Used internally by the SDK to configure
+ * privacy behavior.
+ *
+ * **Privacy Levels:**
+ * - `'transparent'`: No privacy, fully public on-chain
+ * - `'shielded'`: Full privacy, hidden sender/amount/recipient
+ * - `'compliant'`: Privacy with viewing key for regulatory compliance
+ *
+ * @param level - Privacy level to configure
+ * @param viewingKey - Required for compliant mode, optional otherwise
+ * @returns Configuration object specifying privacy features
+ *
+ * @throws {ValidationError} If compliant mode specified without viewing key
+ *
+ * @example
+ * ```typescript
+ * // Transparent (no privacy)
+ * const config = getPrivacyConfig('transparent')
+ * // { level: 'transparent', useStealth: false, encryptData: false }
+ *
+ * // Shielded (full privacy)
+ * const config = getPrivacyConfig('shielded')
+ * // { level: 'shielded', useStealth: true, encryptData: true }
+ *
+ * // Compliant (privacy + audit)
+ * const viewingKey = generateViewingKey()
+ * const config = getPrivacyConfig('compliant', viewingKey)
+ * // { level: 'compliant', viewingKey, useStealth: true, encryptData: true }
+ * ```
+ *
+ * @see {@link PrivacyLevel} for available privacy levels
+ * @see {@link generateViewingKey} to create viewing keys
  */
 export function getPrivacyConfig(
   level: PrivacyLevel,
@@ -96,7 +130,59 @@ export function getPrivacyConfig(
 }
 
 /**
- * Generate a new viewing key
+ * Generate a new viewing key for compliant privacy mode
+ *
+ * Creates a cryptographically random viewing key that enables selective
+ * disclosure of transaction details to auditors or regulators while
+ * maintaining on-chain privacy.
+ *
+ * **Use Cases:**
+ * - Regulatory compliance (AML/KYC audits)
+ * - Internal accounting and reconciliation
+ * - Voluntary disclosure to trusted parties
+ * - Hierarchical key management (via derivation paths)
+ *
+ * **Security:**
+ * - Keep viewing keys secret - they decrypt all transaction details
+ * - Use hierarchical derivation for key management (BIP32-style paths)
+ * - Rotate keys periodically for forward secrecy
+ *
+ * @param path - Hierarchical derivation path (BIP32-style, e.g., "m/0", "m/44'/0'/0'")
+ * @returns Viewing key object with key, path, and hash
+ *
+ * @example Generate master viewing key
+ * ```typescript
+ * const masterKey = generateViewingKey('m/0')
+ * console.log(masterKey.key)  // "0xabc123..."
+ * console.log(masterKey.path) // "m/0"
+ * console.log(masterKey.hash) // "0xdef456..." (for identification)
+ * ```
+ *
+ * @example Generate organization-specific keys
+ * ```typescript
+ * const auditKey = generateViewingKey('m/0/audit')
+ * const accountingKey = generateViewingKey('m/0/accounting')
+ *
+ * // Share different keys with different departments
+ * shareWithAuditor(auditKey)
+ * shareWithAccounting(accountingKey)
+ * ```
+ *
+ * @example Use in compliant intent
+ * ```typescript
+ * const viewingKey = generateViewingKey()
+ *
+ * const intent = await sip.createIntent({
+ *   input: { asset: { chain: 'near', symbol: 'NEAR', address: null, decimals: 24 }, amount: 100n },
+ *   output: { asset: { chain: 'zcash', symbol: 'ZEC', address: null, decimals: 8 }, minAmount: 0n, maxSlippage: 0.01 },
+ *   privacy: PrivacyLevel.COMPLIANT,
+ *   viewingKey: viewingKey.key,
+ * })
+ * ```
+ *
+ * @see {@link deriveViewingKey} to derive child keys hierarchically
+ * @see {@link encryptForViewing} to encrypt data with viewing key
+ * @see {@link decryptWithViewing} to decrypt data with viewing key
  */
 export function generateViewingKey(path: string = 'm/0'): ViewingKey {
   const keyBytes = randomBytes(32)

package/src/proofs/browser-utils.ts

@@ -241,10 +241,8 @@ export function getMobileDeviceInfo(): MobileDeviceInfo {
     isTablet: isTablet(),
     supportsTouch: supportsTouch(),
     deviceMemoryGB:
-      // @ts-expect-error - deviceMemory is non-standard
       typeof navigator !== 'undefined' && navigator.deviceMemory
-        ? // @ts-expect-error - deviceMemory is non-standard
-          navigator.deviceMemory
+        ? navigator.deviceMemory
         : null,
     hardwareConcurrency:
       typeof navigator !== 'undefined' && navigator.hardwareConcurrency
@@ -487,10 +485,8 @@ 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 {
@@ -499,10 +495,8 @@ export async function estimateAvailableMemory(): Promise<number | null> {
   }
 
   // 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
   }
 

package/src/proofs/noir.ts

@@ -71,9 +71,25 @@ export interface NoirProviderConfig {
 
   /**
    * Oracle public key for verifying attestations in fulfillment proofs
-   * Required for production use. If not provided, proofs will use placeholder keys.
+   * Required for production use. If not provided and strictMode is true,
+   * fulfillment proof generation will throw an error.
    */
   oraclePublicKey?: PublicKeyCoordinates
+
+  /**
+   * Enable strict mode for production use
+   *
+   * When true:
+   * - Fulfillment proofs require configured oraclePublicKey
+   * - Missing configuration throws errors instead of warnings
+   *
+   * When false (default):
+   * - Placeholder keys are used when oraclePublicKey not configured
+   * - Warnings are logged for missing configuration
+   *
+   * @default false
+   */
+  strictMode?: boolean
 }
 
 /**
@@ -114,6 +130,7 @@ export class NoirProofProvider implements ProofProvider {
     this.config = {
       backend: 'barretenberg',
       verbose: false,
+      strictMode: false,
       ...config,
     }
   }
@@ -588,15 +605,25 @@ export class NoirProofProvider implements ProofProvider {
         attestation.blockNumber
       )
 
-      // Use configured oracle public key, or placeholder if not configured
-      // In production, the oracle public key should always be configured
+      // Validate oracle public key configuration
+      if (!this.config.oraclePublicKey) {
+        if (this.config.strictMode) {
+          throw new ProofGenerationError(
+            'fulfillment',
+            'Oracle public key is required in strict mode. Configure oraclePublicKey in NoirProviderConfig for production use.'
+          )
+        }
+        // Always warn when using placeholder keys, not just in verbose mode
+        console.warn(
+          '[NoirProofProvider] WARNING: No oracle public key configured. Using placeholder keys. ' +
+          'Proofs will NOT be valid for production. Set strictMode: true to enforce configuration.'
+        )
+      }
+
+      // Use configured oracle public key, or placeholder if not in strict mode
       const oraclePubKeyX = this.config.oraclePublicKey?.x ?? new Array(32).fill(0)
       const oraclePubKeyY = this.config.oraclePublicKey?.y ?? new Array(32).fill(0)
 
-      if (!this.config.oraclePublicKey && this.config.verbose) {
-        console.warn('[NoirProofProvider] Warning: No oracle public key configured. Using placeholder keys.')
-      }
-
       // Prepare witness inputs for the circuit
       const witnessInputs = {
         // Public inputs

package/src/settlement/backends/direct-chain.ts

@@ -39,6 +39,8 @@ import {
   ed25519PublicKeyToNearAddress,
   isEd25519Chain,
 } from '../../stealth'
+import { ed25519PublicKeyToAptosAddress } from '../../move/aptos'
+import { ed25519PublicKeyToSuiAddress } from '../../move/sui'
 import { ValidationError } from '../../errors'
 import { randomBytes, bytesToHex } from '@noble/hashes/utils'
 
@@ -161,6 +163,8 @@ export class DirectChainBackend implements SettlementBackend {
       'optimism',
       'base',
       'bitcoin',
+      'aptos',
+      'sui',
     ],
     supportedDestinationChains: [
       'ethereum',
@@ -172,6 +176,8 @@ export class DirectChainBackend implements SettlementBackend {
       'optimism',
       'base',
       'bitcoin',
+      'aptos',
+      'sui',
     ],
     supportedPrivacyLevels: [
       PrivacyLevel.TRANSPARENT,
@@ -280,7 +286,7 @@ export class DirectChainBackend implements SettlementBackend {
         : params.recipientMetaAddress
 
       if (isEd25519Chain(chain)) {
-        // Ed25519 chains (Solana, NEAR)
+        // Ed25519 chains (Solana, NEAR, Aptos, Sui)
         const { stealthAddress } = generateEd25519StealthAddress(metaAddr)
         stealthData = stealthAddress
 
@@ -288,11 +294,16 @@ export class DirectChainBackend implements SettlementBackend {
           recipientAddress = ed25519PublicKeyToSolanaAddress(stealthAddress.address)
         } else if (chain === 'near') {
           recipientAddress = ed25519PublicKeyToNearAddress(stealthAddress.address)
+        } else if (chain === 'aptos') {
+          recipientAddress = ed25519PublicKeyToAptosAddress(stealthAddress.address)
+        } else if (chain === 'sui') {
+          recipientAddress = ed25519PublicKeyToSuiAddress(stealthAddress.address)
         } else {
+          // This should not happen if ED25519_CHAINS is kept in sync
           throw new ValidationError(
-            `Ed25519 address derivation not implemented for ${chain}`,
+            `Ed25519 address derivation not implemented for ${chain}. Please add support in direct-chain.ts.`,
             'toChain',
-            { chain }
+            { chain, hint: 'Add address derivation function for this chain' }
           )
         }
       } else {

package/src/sip.ts

@@ -32,50 +32,145 @@ import { isValidChainId } from './validation'
 import { NEARIntentsAdapter, type NEARIntentsAdapterConfig, type SwapRequest } from './adapters'
 
 /**
- * SIP SDK configuration
+ * Configuration options for the SIP SDK client
+ *
+ * Controls network selection, privacy defaults, proof generation, and settlement backend.
+ *
+ * @example Basic configuration
+ * ```typescript
+ * const sip = new SIP({
+ *   network: 'testnet',
+ *   defaultPrivacy: PrivacyLevel.SHIELDED
+ * })
+ * ```
+ *
+ * @example Production configuration with NEAR Intents
+ * ```typescript
+ * const sip = new SIP({
+ *   network: 'mainnet',
+ *   mode: 'production',
+ *   proofProvider: new MockProofProvider(),
+ *   intentsAdapter: {
+ *     jwtToken: process.env.NEAR_INTENTS_JWT
+ *   }
+ * })
+ * ```
  */
 export interface SIPConfig {
-  /** Network: mainnet or testnet */
+  /**
+   * Network to operate on
+   *
+   * - `'mainnet'`: Production network with real assets
+   * - `'testnet'`: Test network for development
+   */
   network: 'mainnet' | 'testnet'
+
   /**
-   * Mode: 'demo' for mock data, 'production' for real NEAR Intents
+   * Operating mode for quote fetching and execution
+   *
+   * - `'demo'`: Returns mock quotes for testing (default)
+   * - `'production'`: Uses real NEAR Intents 1Click API
+   *
    * @default 'demo'
    */
   mode?: 'demo' | 'production'
-  /** Default privacy level */
+
+  /**
+   * Default privacy level for new intents
+   *
+   * Can be overridden per intent. See {@link PrivacyLevel} for options.
+   *
+   * @default PrivacyLevel.SHIELDED
+   */
   defaultPrivacy?: PrivacyLevel
-  /** RPC endpoints for chains */
-  rpcEndpoints?: Partial<Record<ChainId, string>>
+
   /**
-   * Proof provider for ZK proof generation
+   * Custom RPC endpoints for blockchain connections
    *
-   * If not provided, proof generation will not be available.
-   * Use MockProofProvider for testing, NoirProofProvider for production.
+   * Maps chain IDs to RPC URLs. Used for direct blockchain interactions
+   * when not using settlement adapters.
    *
    * @example
    * ```typescript
+   * {
+   *   rpcEndpoints: {
+   *     ethereum: 'https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY',
+   *     solana: 'https://api.mainnet-beta.solana.com'
+   *   }
+   * }
+   * ```
+   */
+  rpcEndpoints?: Partial<Record<ChainId, string>>
+
+  /**
+   * Proof provider for zero-knowledge proof generation
+   *
+   * Required for SHIELDED and COMPLIANT privacy modes. If not provided,
+   * intents will be created without proofs (must be attached later).
+   *
+   * **Available providers:**
+   * - {@link MockProofProvider}: For testing and development
+   * - `NoirProofProvider`: For production (import from '@sip-protocol/sdk/proofs/noir')
+   * - `BrowserNoirProvider`: For browser environments (import from '@sip-protocol/sdk/browser')
+   *
+   * @example Testing with mock proofs
+   * ```typescript
    * import { MockProofProvider } from '@sip-protocol/sdk'
    *
    * const sip = new SIP({
    *   network: 'testnet',
-   *   proofProvider: new MockProofProvider(),
+   *   proofProvider: new MockProofProvider()
+   * })
+   * ```
+   *
+   * @example Production with Noir proofs (Node.js)
+   * ```typescript
+   * import { NoirProofProvider } from '@sip-protocol/sdk/proofs/noir'
+   *
+   * const provider = new NoirProofProvider()
+   * await provider.initialize()
+   *
+   * const sip = new SIP({
+   *   network: 'mainnet',
+   *   proofProvider: provider
    * })
    * ```
    */
   proofProvider?: ProofProvider
+
   /**
-   * NEAR Intents adapter configuration
+   * NEAR Intents adapter for production mode
    *
-   * Required for production mode. Provides connection to 1Click API.
+   * Required when `mode: 'production'`. Provides connection to the 1Click API
+   * for real cross-chain swaps via NEAR Intents.
    *
-   * @example
+   * Can be either:
+   * - Configuration object ({@link NEARIntentsAdapterConfig})
+   * - Pre-configured adapter instance ({@link NEARIntentsAdapter})
+   *
+   * @example With JWT token
    * ```typescript
    * const sip = new SIP({
    *   network: 'mainnet',
    *   mode: 'production',
    *   intentsAdapter: {
-   *     jwtToken: process.env.NEAR_INTENTS_JWT,
-   *   },
+   *     jwtToken: process.env.NEAR_INTENTS_JWT
+   *   }
+   * })
+   * ```
+   *
+   * @example With pre-configured adapter
+   * ```typescript
+   * import { createNEARIntentsAdapter } from '@sip-protocol/sdk'
+   *
+   * const adapter = createNEARIntentsAdapter({
+   *   jwtToken: process.env.NEAR_INTENTS_JWT
+   * })
+   *
+   * const sip = new SIP({
+   *   network: 'mainnet',
+   *   mode: 'production',
+   *   intentsAdapter: adapter
    * })
    * ```
    */
@@ -83,33 +178,212 @@ export interface SIPConfig {
 }
 
 /**
- * Wallet adapter interface
+ * Wallet adapter interface for blockchain interactions
+ *
+ * Provides a unified interface for signing messages and transactions
+ * across different blockchain wallets (Ethereum, Solana, etc.).
+ *
+ * @example Implementing a wallet adapter
+ * ```typescript
+ * class MyWalletAdapter implements WalletAdapter {
+ *   chain = 'ethereum' as const
+ *   address = '0x...'
+ *
+ *   async signMessage(message: string): Promise<string> {
+ *     return await wallet.signMessage(message)
+ *   }
+ *
+ *   async signTransaction(tx: unknown): Promise<unknown> {
+ *     return await wallet.signTransaction(tx)
+ *   }
+ * }
+ * ```
  */
 export interface WalletAdapter {
-  /** Connected chain */
+  /**
+   * Blockchain network this wallet is connected to
+   *
+   * Must match one of the supported {@link ChainId} values.
+   */
   chain: ChainId
-  /** Wallet address */
+
+  /**
+   * Wallet address on the connected chain
+   *
+   * Format depends on the chain:
+   * - Ethereum: `0x...` (checksummed)
+   * - Solana: Base58-encoded public key
+   * - NEAR: Account ID or implicit address
+   */
   address: string
-  /** Sign a message */
+
+  /**
+   * Sign a message with the wallet's private key
+   *
+   * @param message - UTF-8 string to sign
+   * @returns Signature as hex string or base58 (chain-dependent)
+   *
+   * @example
+   * ```typescript
+   * const signature = await wallet.signMessage('Hello SIP!')
+   * ```
+   */
   signMessage(message: string): Promise<string>
-  /** Sign a transaction */
+
+  /**
+   * Sign a transaction without broadcasting
+   *
+   * @param tx - Chain-specific transaction object
+   * @returns Signed transaction ready for broadcast
+   *
+   * @example
+   * ```typescript
+   * const signedTx = await wallet.signTransaction(tx)
+   * ```
+   */
   signTransaction(tx: unknown): Promise<unknown>
-  /** Send a transaction (optional) */
+
+  /**
+   * Sign and broadcast a transaction (optional)
+   *
+   * If implemented, allows the wallet to handle both signing and sending.
+   * If not implemented, caller must broadcast the signed transaction separately.
+   *
+   * @param tx - Chain-specific transaction object
+   * @returns Transaction hash after broadcast
+   *
+   * @example
+   * ```typescript
+   * if (wallet.sendTransaction) {
+   *   const txHash = await wallet.sendTransaction(tx)
+   * }
+   * ```
+   */
   sendTransaction?(tx: unknown): Promise<string>
 }
 
 /**
- * Extended quote with deposit info for production mode
+ * Extended quote with production-specific metadata
+ *
+ * In production mode, quotes include deposit addresses and raw API responses
+ * from the NEAR 1Click API for advanced use cases.
  */
 export interface ProductionQuote extends Quote {
-  /** Deposit address for input tokens (production mode only) */
+  /**
+   * Deposit address for input tokens
+   *
+   * When using NEAR Intents in production mode, users deposit funds to this
+   * address to initiate the swap.
+   *
+   * Only present in production mode quotes.
+   */
   depositAddress?: string
-  /** Raw 1Click quote response (production mode only) */
+
+  /**
+   * Raw response from NEAR 1Click API
+   *
+   * Contains the complete quote data from the settlement backend.
+   * Useful for debugging or accessing provider-specific metadata.
+   *
+   * Only present in production mode quotes.
+   */
   rawQuote?: OneClickQuoteResponse
 }
 
 /**
- * Main SIP SDK class
+ * Main SIP SDK client for privacy-preserving cross-chain transactions
+ *
+ * The SIP class is the primary interface for interacting with the Shielded Intents Protocol.
+ * It provides methods for:
+ *
+ * - Creating shielded intents with privacy guarantees
+ * - Fetching quotes from solvers/market makers
+ * - Executing cross-chain swaps via settlement backends
+ * - Managing stealth addresses and viewing keys
+ * - Generating zero-knowledge proofs
+ *
+ * **Key Concepts:**
+ *
+ * - **Intent**: A declaration of desired output (e.g., "I want 95+ ZEC on Zcash")
+ * - **Privacy Levels**: transparent (public), shielded (private), compliant (private + auditable)
+ * - **Stealth Address**: One-time recipient address for unlinkable transactions
+ * - **Commitment**: Cryptographic hiding of amounts using Pedersen commitments
+ * - **Viewing Key**: Selective disclosure key for compliance/auditing
+ *
+ * @example Basic usage (demo mode)
+ * ```typescript
+ * import { SIP, PrivacyLevel } from '@sip-protocol/sdk'
+ *
+ * // Initialize client
+ * const sip = new SIP({ network: 'testnet' })
+ *
+ * // Create a shielded intent
+ * const intent = await sip.createIntent({
+ *   input: {
+ *     asset: { chain: 'solana', symbol: 'SOL', address: null, decimals: 9 },
+ *     amount: 10n * 10n**9n, // 10 SOL
+ *   },
+ *   output: {
+ *     asset: { chain: 'ethereum', symbol: 'ETH', address: null, decimals: 18 },
+ *     minAmount: 0n, // Accept any amount
+ *     maxSlippage: 0.01, // 1%
+ *   },
+ *   privacy: PrivacyLevel.SHIELDED,
+ * })
+ *
+ * // Get quotes from solvers
+ * const quotes = await sip.getQuotes(intent)
+ *
+ * // Execute with best quote
+ * const result = await sip.execute(intent, quotes[0])
+ * console.log('Swap completed:', result.txHash)
+ * ```
+ *
+ * @example Production mode with NEAR Intents
+ * ```typescript
+ * import { SIP, PrivacyLevel, MockProofProvider } from '@sip-protocol/sdk'
+ *
+ * // Initialize with production backend
+ * const sip = new SIP({
+ *   network: 'mainnet',
+ *   mode: 'production',
+ *   proofProvider: new MockProofProvider(), // Use NoirProofProvider in prod
+ *   intentsAdapter: {
+ *     jwtToken: process.env.NEAR_INTENTS_JWT,
+ *   },
+ * })
+ *
+ * // Connect wallet
+ * sip.connect(myWalletAdapter)
+ *
+ * // Generate stealth keys for receiving
+ * const stealthMetaAddress = sip.generateStealthKeys('ethereum', 'My Privacy Wallet')
+ *
+ * // Create intent with stealth recipient
+ * const intent = await sip.createIntent({
+ *   input: { asset: { chain: 'near', symbol: 'NEAR', address: null, decimals: 24 }, amount: 100n },
+ *   output: { asset: { chain: 'zcash', symbol: 'ZEC', address: null, decimals: 8 }, minAmount: 0n, maxSlippage: 0.01 },
+ *   privacy: PrivacyLevel.SHIELDED,
+ *   recipientMetaAddress: sip.getStealthAddress(),
+ * })
+ *
+ * // Get real quotes
+ * const quotes = await sip.getQuotes(intent)
+ *
+ * // Execute with deposit callback
+ * const result = await sip.execute(intent, quotes[0], {
+ *   onDepositRequired: async (depositAddr, amount) => {
+ *     console.log(`Deposit ${amount} to ${depositAddr}`)
+ *     const tx = await wallet.transfer(depositAddr, amount)
+ *     return tx.hash
+ *   },
+ *   onStatusUpdate: (status) => console.log('Status:', status),
+ * })
+ * ```
+ *
+ * @see {@link SIPConfig} for configuration options
+ * @see {@link createShieldedIntent} for intent creation
+ * @see {@link PrivacyLevel} for privacy modes
  */
 export class SIP {
   private config: SIPConfig & { mode: 'demo' | 'production' }
@@ -124,6 +398,31 @@ export class SIP {
   /** Cache of pending swaps by intent ID */
   private pendingSwaps: Map<string, { depositAddress: string; quote: OneClickQuoteResponse }> = new Map()
 
+  /**
+   * Create a new SIP SDK client
+   *
+   * @param config - Configuration options for the client
+   * @throws {ValidationError} If configuration is invalid
+   *
+   * @example Minimal configuration
+   * ```typescript
+   * const sip = new SIP({ network: 'testnet' })
+   * ```
+   *
+   * @example Full configuration
+   * ```typescript
+   * const sip = new SIP({
+   *   network: 'mainnet',
+   *   mode: 'production',
+   *   defaultPrivacy: PrivacyLevel.COMPLIANT,
+   *   proofProvider: await NoirProofProvider.create(),
+   *   intentsAdapter: { jwtToken: process.env.JWT },
+   *   rpcEndpoints: {
+   *     ethereum: 'https://eth-mainnet.g.alchemy.com/v2/KEY',
+   *   },
+   * })
+   * ```
+   */
   constructor(config: SIPConfig) {
     // Validate config
     if (!config || typeof config !== 'object') {