@sip-protocol/sdk 0.5.0 → 0.6.0

package/dist/index.mjs

@@ -238,7 +238,7 @@ import {
   walletRegistry,
   withSecureBuffer,
   withSecureBufferSync
-} from "./chunk-DMHBKRWV.mjs";
+} from "./chunk-KBS3OMSZ.mjs";
 import {
   CryptoError,
   EncryptionNotImplementedError,
@@ -255,6 +255,7 @@ import {
   isSIPError,
   wrapError
 } from "./chunk-HGU6HZRC.mjs";
+import "./chunk-UJCSKKID.mjs";
 export {
   ATTESTATION_VERSION,
   AptosStealthService,

package/dist/proofs/noir.mjs

@@ -7,6 +7,7 @@ import {
   ProofError,
   ProofGenerationError
 } from "../chunk-HGU6HZRC.mjs";
+import "../chunk-UJCSKKID.mjs";
 
 // src/proofs/noir.ts
 import { Noir } from "@noir-lang/noir_js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sip-protocol/sdk",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Core SDK for Shielded Intents Protocol - Privacy layer for cross-chain transactions",
   "author": "SIP Protocol <hello@sip-protocol.org>",
   "homepage": "https://sip-protocol.org",
@@ -36,17 +36,6 @@
     "dist",
     "src"
   ],
-  "scripts": {
-    "build": "tsup src/index.ts src/browser.ts src/proofs/noir.ts --format cjs,esm --dts",
-    "dev": "tsup src/index.ts src/browser.ts src/proofs/noir.ts --format cjs,esm --dts --watch",
-    "lint": "eslint --ext .ts src/",
-    "typecheck": "tsc --noEmit",
-    "clean": "rm -rf dist",
-    "test": "vitest",
-    "test:coverage": "vitest run --coverage",
-    "bench": "vitest bench --config vitest.bench.config.ts",
-    "bench:json": "vitest bench --config vitest.bench.config.ts --outputJson benchmarks/results.json"
-  },
   "dependencies": {
     "@aztec/bb.js": "^0.63.1",
     "@noble/ciphers": "^2.0.1",
@@ -55,7 +44,7 @@
     "@noir-lang/noir_js": "^1.0.0-beta.16",
     "@noir-lang/types": "1.0.0-beta.16",
     "@scure/base": "^2.0.0",
-    "@sip-protocol/types": "^0.1.1"
+    "@sip-protocol/types": "^0.2.0"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "1.6.1",
@@ -72,5 +61,16 @@
     "stealth-addresses",
     "zcash"
   ],
-  "license": "MIT"
-}
+  "license": "MIT",
+  "scripts": {
+    "build": "tsup src/index.ts src/browser.ts src/proofs/noir.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts src/browser.ts src/proofs/noir.ts --format cjs,esm --dts --watch",
+    "lint": "eslint --ext .ts src/",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "test": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "bench": "vitest bench --config vitest.bench.config.ts",
+    "bench:json": "vitest bench --config vitest.bench.config.ts --outputJson benchmarks/results.json"
+  }
+}

package/src/crypto.ts

@@ -1,13 +1,20 @@
 /**
  * Cryptographic utilities for SIP Protocol
  *
- * For ZK proofs, use ProofProvider:
- * @see ./proofs/interface.ts for the proof provider interface
- * @see ./proofs/mock.ts for testing
- * @see ./proofs/noir.ts for production (Noir circuits)
+ * This module provides low-level cryptographic primitives including:
+ * - Hash functions (SHA-256)
+ * - Random number generation
+ * - Pedersen commitments (legacy wrappers)
  *
- * For Pedersen commitments, use the dedicated commitment module:
- * @see ./commitment.ts for secure Pedersen commitment implementation
+ * **Important:**
+ * - For ZK proofs, use {@link ProofProvider} interface (see ./proofs/)
+ * - For Pedersen commitments in new code, use ./commitment.ts directly
+ * - This module maintains legacy functions for backward compatibility
+ *
+ * @module crypto
+ * @see {@link ProofProvider} for zero-knowledge proof generation
+ * @see ./commitment.ts for modern Pedersen commitment API
+ * @see ./stealth.ts for stealth address cryptography
  */
 
 import { sha256 } from '@noble/hashes/sha256'
@@ -70,7 +77,18 @@ export function verifyCommitment(
 }
 
 /**
- * Generate a random intent ID
+ * Generate a unique intent identifier
+ *
+ * Creates a cryptographically random intent ID with the `sip-` prefix.
+ * IDs are globally unique with negligible collision probability (128-bit randomness).
+ *
+ * @returns Intent ID string in format: `sip-<32 hex chars>`
+ *
+ * @example
+ * ```typescript
+ * const intentId = generateIntentId()
+ * console.log(intentId) // "sip-a1b2c3d4e5f67890a1b2c3d4e5f67890"
+ * ```
  */
 export function generateIntentId(): string {
   const bytes = randomBytes(16)
@@ -78,7 +96,36 @@ export function generateIntentId(): string {
 }
 
 /**
- * Hash data using SHA256
+ * Compute SHA-256 hash of data
+ *
+ * General-purpose cryptographic hash function used throughout SIP protocol
+ * for commitment derivation, data integrity, and key derivation.
+ *
+ * **Use cases:**
+ * - Hash transaction data for commitments
+ * - Derive deterministic IDs from inputs
+ * - Verify data integrity
+ *
+ * @param data - Input data as UTF-8 string or raw bytes
+ * @returns 32-byte hash as hex string with `0x` prefix
+ *
+ * @example Hash a string
+ * ```typescript
+ * const messageHash = hash('Hello, SIP Protocol!')
+ * console.log(messageHash) // "0xabc123..."
+ * ```
+ *
+ * @example Hash binary data
+ * ```typescript
+ * const dataBytes = new Uint8Array([1, 2, 3, 4])
+ * const dataHash = hash(dataBytes)
+ * ```
+ *
+ * @example Use in commitment scheme
+ * ```typescript
+ * const intentHash = hash(intent.intentId)
+ * const commitment = commit(amount, hexToBytes(intentHash))
+ * ```
  */
 export function hash(data: string | Uint8Array): Hash {
   const input = typeof data === 'string' ? new TextEncoder().encode(data) : data
@@ -86,7 +133,30 @@ export function hash(data: string | Uint8Array): Hash {
 }
 
 /**
- * Generate random bytes
+ * Generate cryptographically secure random bytes
+ *
+ * Uses the platform's secure random source (Web Crypto API in browsers,
+ * crypto.randomBytes in Node.js) to generate unpredictable random data.
+ *
+ * **Use cases:**
+ * - Generate private keys
+ * - Create nonces for encryption
+ * - Produce blinding factors for commitments
+ * - Generate ephemeral keypairs
+ *
+ * @param length - Number of random bytes to generate
+ * @returns Random bytes as hex string with `0x` prefix
+ *
+ * @example Generate a 32-byte private key
+ * ```typescript
+ * const privateKey = generateRandomBytes(32)
+ * console.log(privateKey) // "0xabc123...def" (64 hex chars)
+ * ```
+ *
+ * @example Generate a nonce
+ * ```typescript
+ * const nonce = generateRandomBytes(24) // For XChaCha20
+ * ```
  */
 export function generateRandomBytes(length: number): HexString {
   return `0x${bytesToHex(randomBytes(length))}` as HexString

package/src/intent.ts

@@ -41,19 +41,97 @@ import {
 
 /**
  * Options for creating a shielded intent
+ *
+ * Additional configuration passed to {@link createShieldedIntent} that
+ * affects proof generation and sender identification.
  */
 export interface CreateIntentOptions {
-  /** Sender address (for ownership proof) */
+  /**
+   * Wallet address of the sender
+   *
+   * Used for:
+   * - Generating ownership proofs (proving control of input funds)
+   * - Creating sender commitments
+   * - Enabling refunds if transaction fails
+   *
+   * Optional but recommended for production use.
+   */
   senderAddress?: string
+
   /**
-   * Proof provider for generating ZK proofs
-   * If provided and privacy level requires proofs, they will be generated automatically
+   * Proof provider for automatic ZK proof generation
+   *
+   * If provided and privacy level is SHIELDED or COMPLIANT, proofs will be
+   * generated automatically during intent creation. If not provided, proofs
+   * must be attached later using {@link attachProofs}.
+   *
+   * **Available providers:**
+   * - {@link MockProofProvider}: For testing
+   * - `NoirProofProvider`: For production (Node.js)
+   * - `BrowserNoirProvider`: For browsers
+   *
+   * @example
+   * ```typescript
+   * import { NoirProofProvider } from '@sip-protocol/sdk/proofs/noir'
+   *
+   * const provider = new NoirProofProvider()
+   * await provider.initialize()
+   *
+   * const intent = await createShieldedIntent(params, {
+   *   senderAddress: wallet.address,
+   *   proofProvider: provider,
+   * })
+   * ```
    */
   proofProvider?: ProofProvider
 }
 
 /**
- * Builder class for creating shielded intents
+ * Fluent builder for creating shielded intents
+ *
+ * Provides a chainable API for constructing intents step-by-step.
+ * More ergonomic than passing a large parameter object directly.
+ *
+ * **Builder Methods:**
+ * - {@link input}: Set input asset and amount
+ * - {@link output}: Set output asset and constraints
+ * - {@link privacy}: Set privacy level
+ * - {@link recipient}: Set recipient stealth meta-address
+ * - {@link slippage}: Set slippage tolerance
+ * - {@link ttl}: Set time-to-live
+ * - {@link withProvider}: Set proof provider
+ * - {@link build}: Create the intent
+ *
+ * @example Basic intent
+ * ```typescript
+ * const intent = await new IntentBuilder()
+ *   .input('solana', 'SOL', 10n * 10n**9n)
+ *   .output('ethereum', 'ETH', 0n)
+ *   .privacy(PrivacyLevel.SHIELDED)
+ *   .build()
+ * ```
+ *
+ * @example Full-featured intent with proofs
+ * ```typescript
+ * import { IntentBuilder, PrivacyLevel, MockProofProvider } from '@sip-protocol/sdk'
+ *
+ * const builder = new IntentBuilder()
+ * const intent = await builder
+ *   .input('near', 'NEAR', 100n * 10n**24n, wallet.address) // 100 NEAR
+ *   .output('zcash', 'ZEC', 95n * 10n**8n)                   // Min 95 ZEC
+ *   .privacy(PrivacyLevel.COMPLIANT)
+ *   .recipient('sip:zcash:0x02abc...123:0x03def...456')
+ *   .slippage(1) // 1%
+ *   .ttl(600)    // 10 minutes
+ *   .withProvider(new MockProofProvider())
+ *   .build()
+ *
+ * console.log('Intent created:', intent.intentId)
+ * console.log('Has proofs:', !!intent.fundingProof && !!intent.validityProof)
+ * ```
+ *
+ * @see {@link createShieldedIntent} for the underlying implementation
+ * @see {@link CreateIntentParams} for parameter types
  */
 export class IntentBuilder {
   private params: Partial<CreateIntentParams> = {}

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)