@sip-protocol/sdk 0.6.0 → 0.6.2

package/dist/noir-DKfEzWy9.d.ts

@@ -0,0 +1,482 @@
+import { ZKProof, HexString, Commitment } from '@sip-protocol/types';
+
+/**
+ * Proof Provider Interface
+ *
+ * Defines a pluggable interface for ZK proof generation and verification.
+ * This allows different backends (Noir, mock for testing) to be swapped.
+ *
+ * @see docs/specs/ZK-ARCHITECTURE.md for framework decision (Noir)
+ */
+
+/**
+ * Supported proof framework types
+ */
+type ProofFramework = 'noir' | 'mock';
+/**
+ * Parameters for generating a Funding Proof
+ *
+ * Proves: balance >= minimumRequired without revealing balance
+ *
+ * @see docs/specs/FUNDING-PROOF.md
+ */
+interface FundingProofParams {
+    /** User's actual balance (private) */
+    balance: bigint;
+    /** Minimum amount required for the intent (public) */
+    minimumRequired: bigint;
+    /** Blinding factor for the commitment (private) */
+    blindingFactor: Uint8Array;
+    /** Asset identifier (public) */
+    assetId: string;
+    /** User's address for ownership proof (private) */
+    userAddress: string;
+    /** Signature proving ownership of the address (private) */
+    ownershipSignature: Uint8Array;
+}
+/**
+ * Public key coordinates for secp256k1 (X and Y as byte arrays)
+ */
+interface PublicKeyXY {
+    /** X coordinate as 32-byte array */
+    x: Uint8Array;
+    /** Y coordinate as 32-byte array */
+    y: Uint8Array;
+}
+/**
+ * Parameters for generating a Validity Proof
+ *
+ * Proves: intent is authorized by sender without revealing sender
+ *
+ * @see docs/specs/VALIDITY-PROOF.md
+ */
+interface ValidityProofParams {
+    /** Hash of the intent (public) */
+    intentHash: HexString;
+    /** Sender's address (private) */
+    senderAddress: string;
+    /** Blinding factor for sender commitment (private) */
+    senderBlinding: Uint8Array;
+    /** Sender's secret key (private) - used to derive public key if senderPublicKey not provided */
+    senderSecret: Uint8Array;
+    /** Signature authorizing the intent (private) */
+    authorizationSignature: Uint8Array;
+    /** Nonce for nullifier generation (private) */
+    nonce: Uint8Array;
+    /** Intent timestamp (public) */
+    timestamp: number;
+    /** Intent expiry (public) */
+    expiry: number;
+    /** Optional: Sender's public key. If not provided, derived from senderSecret */
+    senderPublicKey?: PublicKeyXY;
+}
+/**
+ * Parameters for generating a Fulfillment Proof
+ *
+ * Proves: solver delivered output >= minimum to correct recipient
+ *
+ * @see docs/specs/FULFILLMENT-PROOF.md
+ */
+interface FulfillmentProofParams {
+    /** Hash of the original intent (public) */
+    intentHash: HexString;
+    /** Actual output amount delivered (private) */
+    outputAmount: bigint;
+    /** Blinding factor for output commitment (private) */
+    outputBlinding: Uint8Array;
+    /** Minimum required output from intent (public) */
+    minOutputAmount: bigint;
+    /** Recipient's stealth address (public) */
+    recipientStealth: HexString;
+    /** Solver's identifier (public) */
+    solverId: string;
+    /** Solver's secret for authorization (private) */
+    solverSecret: Uint8Array;
+    /** Oracle attestation of delivery (private) */
+    oracleAttestation: OracleAttestation;
+    /** Time of fulfillment (public) */
+    fulfillmentTime: number;
+    /** Intent expiry (public) */
+    expiry: number;
+}
+/**
+ * Oracle attestation for cross-chain verification
+ */
+interface OracleAttestation {
+    /** Recipient who received funds */
+    recipient: HexString;
+    /** Amount received */
+    amount: bigint;
+    /** Transaction hash on destination chain */
+    txHash: HexString;
+    /** Block number containing the transaction */
+    blockNumber: bigint;
+    /** Oracle signature (threshold signature for multi-oracle) */
+    signature: Uint8Array;
+}
+/**
+ * Result of proof generation
+ */
+interface ProofResult {
+    /** The generated proof */
+    proof: ZKProof;
+    /** Public inputs used in the proof */
+    publicInputs: HexString[];
+    /** Commitment (if generated as part of proof) */
+    commitment?: Commitment;
+}
+/**
+ * Proof Provider Interface
+ *
+ * Implementations of this interface provide ZK proof generation and verification.
+ * The SDK uses this interface to remain agnostic to the underlying ZK framework.
+ *
+ * @example
+ * ```typescript
+ * // Use mock provider for testing
+ * const mockProvider = new MockProofProvider()
+ *
+ * // Use Noir provider for production
+ * const noirProvider = new NoirProofProvider()
+ *
+ * // Configure SIP client with provider
+ * const sip = new SIP({
+ *   network: 'testnet',
+ *   proofProvider: noirProvider,
+ * })
+ * ```
+ */
+interface ProofProvider {
+    /**
+     * The ZK framework this provider uses
+     */
+    readonly framework: ProofFramework;
+    /**
+     * Whether the provider is ready to generate proofs
+     * (e.g., circuits compiled, keys loaded)
+     */
+    readonly isReady: boolean;
+    /**
+     * Initialize the provider (compile circuits, load keys, etc.)
+     *
+     * @throws Error if initialization fails
+     */
+    initialize(): Promise<void>;
+    /**
+     * Generate a Funding Proof
+     *
+     * Proves that the user has sufficient balance without revealing the exact amount.
+     *
+     * @param params - Funding proof parameters
+     * @returns The generated proof with public inputs
+     * @throws ProofGenerationError if proof generation fails
+     *
+     * @see docs/specs/FUNDING-PROOF.md (~22,000 constraints)
+     */
+    generateFundingProof(params: FundingProofParams): Promise<ProofResult>;
+    /**
+     * Generate a Validity Proof
+     *
+     * Proves that the intent is authorized without revealing the sender.
+     *
+     * @param params - Validity proof parameters
+     * @returns The generated proof with public inputs
+     * @throws ProofGenerationError if proof generation fails
+     *
+     * @see docs/specs/VALIDITY-PROOF.md (~72,000 constraints)
+     */
+    generateValidityProof(params: ValidityProofParams): Promise<ProofResult>;
+    /**
+     * Generate a Fulfillment Proof
+     *
+     * Proves that the solver correctly delivered the output.
+     *
+     * @param params - Fulfillment proof parameters
+     * @returns The generated proof with public inputs
+     * @throws ProofGenerationError if proof generation fails
+     *
+     * @see docs/specs/FULFILLMENT-PROOF.md (~22,000 constraints)
+     */
+    generateFulfillmentProof(params: FulfillmentProofParams): Promise<ProofResult>;
+    /**
+     * Verify a proof
+     *
+     * @param proof - The proof to verify
+     * @returns true if the proof is valid, false otherwise
+     */
+    verifyProof(proof: ZKProof): Promise<boolean>;
+}
+/**
+ * Error thrown when proof generation fails
+ */
+declare class ProofGenerationError extends Error {
+    readonly proofType: 'funding' | 'validity' | 'fulfillment';
+    readonly cause?: Error;
+    constructor(proofType: 'funding' | 'validity' | 'fulfillment', message: string, cause?: Error);
+}
+
+/**
+ * Noir Proof Provider
+ *
+ * Production-ready ZK proof provider using Noir (Aztec) circuits.
+ *
+ * This provider generates cryptographically sound proofs using:
+ * - Funding Proof: ~2,000 constraints (docs/specs/FUNDING-PROOF.md)
+ * - Validity Proof: ~72,000 constraints (docs/specs/VALIDITY-PROOF.md)
+ * - Fulfillment Proof: ~22,000 constraints (docs/specs/FULFILLMENT-PROOF.md)
+ *
+ * @see docs/specs/ZK-ARCHITECTURE.md for framework decision
+ */
+
+/**
+ * Public key coordinates for secp256k1
+ */
+interface PublicKeyCoordinates {
+    /** X coordinate as 32-byte array */
+    x: number[];
+    /** Y coordinate as 32-byte array */
+    y: number[];
+}
+/**
+ * Noir Proof Provider Configuration
+ */
+interface NoirProviderConfig {
+    /**
+     * Path to compiled circuit artifacts
+     * If not provided, uses bundled artifacts
+     */
+    artifactsPath?: string;
+    /**
+     * Backend to use for proof generation
+     * @default 'barretenberg' (UltraHonk)
+     */
+    backend?: 'barretenberg';
+    /**
+     * Enable verbose logging for debugging
+     * @default false
+     */
+    verbose?: boolean;
+    /**
+     * Oracle public key for verifying attestations in fulfillment proofs
+     * 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;
+}
+/**
+ * Noir Proof Provider
+ *
+ * Production ZK proof provider using Noir circuits.
+ *
+ * @example
+ * ```typescript
+ * const provider = new NoirProofProvider()
+ *
+ * await provider.initialize()
+ *
+ * const result = await provider.generateFundingProof({
+ *   balance: 100n,
+ *   minimumRequired: 50n,
+ *   blindingFactor: new Uint8Array(32),
+ *   assetId: '0xABCD',
+ *   userAddress: '0x1234...',
+ *   ownershipSignature: new Uint8Array(64),
+ * })
+ * ```
+ */
+declare class NoirProofProvider implements ProofProvider {
+    readonly framework: ProofFramework;
+    private _isReady;
+    private config;
+    private fundingNoir;
+    private fundingBackend;
+    private validityNoir;
+    private validityBackend;
+    private fulfillmentNoir;
+    private fulfillmentBackend;
+    constructor(config?: NoirProviderConfig);
+    get isReady(): boolean;
+    /**
+     * Derive secp256k1 public key coordinates from a private key
+     *
+     * Utility method that can be used to generate public key coordinates
+     * for use in ValidityProofParams.senderPublicKey or NoirProviderConfig.oraclePublicKey
+     *
+     * @param privateKey - 32-byte private key
+     * @returns X and Y coordinates as 32-byte arrays
+     *
+     * @example
+     * ```typescript
+     * const privateKey = new Uint8Array(32).fill(1) // Your secret key
+     * const publicKey = NoirProofProvider.derivePublicKey(privateKey)
+     *
+     * // Use for oracle configuration
+     * const provider = new NoirProofProvider({
+     *   oraclePublicKey: publicKey
+     * })
+     *
+     * // Or use for validity proof params
+     * const validityParams = {
+     *   // ... other params
+     *   senderPublicKey: {
+     *     x: new Uint8Array(publicKey.x),
+     *     y: new Uint8Array(publicKey.y)
+     *   }
+     * }
+     * ```
+     */
+    static derivePublicKey(privateKey: Uint8Array): PublicKeyCoordinates;
+    /**
+     * Initialize the Noir provider
+     *
+     * Loads circuit artifacts and initializes the proving backend.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Generate a Funding Proof using Noir circuits
+     *
+     * Proves: balance >= minimumRequired without revealing balance
+     *
+     * @see docs/specs/FUNDING-PROOF.md
+     */
+    generateFundingProof(params: FundingProofParams): Promise<ProofResult>;
+    /**
+     * Generate a Validity Proof using Noir circuits
+     *
+     * Proves: Intent is authorized by sender without revealing identity
+     *
+     * @see docs/specs/VALIDITY-PROOF.md
+     */
+    generateValidityProof(params: ValidityProofParams): Promise<ProofResult>;
+    /**
+     * Generate a Fulfillment Proof using Noir circuits
+     *
+     * Proves: Solver correctly executed the intent and delivered the required
+     * output to the recipient, without revealing execution path or liquidity sources.
+     *
+     * @see docs/specs/FULFILLMENT-PROOF.md
+     */
+    generateFulfillmentProof(params: FulfillmentProofParams): Promise<ProofResult>;
+    /**
+     * Verify a Noir proof
+     */
+    verifyProof(proof: ZKProof): Promise<boolean>;
+    /**
+     * Destroy the provider and free resources
+     */
+    destroy(): Promise<void>;
+    private ensureReady;
+    /**
+     * Compute the commitment hash that the circuit expects
+     *
+     * The circuit computes:
+     * 1. commitment = pedersen_commitment([balance, blinding])
+     * 2. commitment_hash = pedersen_hash([commitment.x, commitment.y, asset_id])
+     *
+     * We need to compute this outside to pass as a public input.
+     *
+     * **IMPORTANT**: This SDK uses SHA256 as a deterministic stand-in for Pedersen hash.
+     * Both the SDK and circuit MUST use the same hash function. The bundled circuit
+     * artifacts are configured to use SHA256 for compatibility. If you use custom
+     * circuits with actual Pedersen hashing, you must update this implementation.
+     *
+     * @see docs/specs/HASH-COMPATIBILITY.md for hash function requirements
+     */
+    private computeCommitmentHash;
+    /**
+     * Convert asset ID to field element
+     */
+    private assetIdToField;
+    /**
+     * Convert bytes to field element string
+     */
+    private bytesToField;
+    /**
+     * Convert bigint to bytes
+     */
+    private bigintToBytes;
+    /**
+     * Convert hex string to bytes
+     */
+    private hexToBytes;
+    /**
+     * Convert hex string to field element string
+     */
+    private hexToField;
+    /**
+     * Convert field string to 32-byte array
+     */
+    private fieldToBytes32;
+    /**
+     * Compute sender commitment for validity proof
+     *
+     * Uses SHA256 for SDK-side computation. The bundled circuit artifacts
+     * are compiled to use SHA256 for compatibility with this SDK.
+     *
+     * @see computeCommitmentHash for hash function compatibility notes
+     */
+    private computeSenderCommitment;
+    /**
+     * Compute nullifier for validity proof
+     *
+     * Uses SHA256 for SDK-side computation. The bundled circuit artifacts
+     * are compiled to use SHA256 for compatibility with this SDK.
+     *
+     * @see computeCommitmentHash for hash function compatibility notes
+     */
+    private computeNullifier;
+    /**
+     * Compute output commitment for fulfillment proof
+     *
+     * Uses SHA256 for SDK-side computation. The bundled circuit artifacts
+     * are compiled to use SHA256 for compatibility with this SDK.
+     *
+     * @see computeCommitmentHash for hash function compatibility notes
+     */
+    private computeOutputCommitment;
+    /**
+     * Compute solver ID from solver secret
+     *
+     * Uses SHA256 for SDK-side computation. The bundled circuit artifacts
+     * are compiled to use SHA256 for compatibility with this SDK.
+     *
+     * @see computeCommitmentHash for hash function compatibility notes
+     */
+    private computeSolverId;
+    /**
+     * Compute oracle message hash for fulfillment proof
+     *
+     * Hash of attestation data that oracle signs
+     */
+    private computeOracleMessageHash;
+    /**
+     * Derive secp256k1 public key coordinates from a private key
+     *
+     * @param privateKey - 32-byte private key as Uint8Array
+     * @returns X and Y coordinates as 32-byte arrays
+     */
+    private getPublicKeyCoordinates;
+    /**
+     * Derive public key coordinates from a field string (private key)
+     *
+     * @param privateKeyField - Private key as hex field string
+     * @returns X and Y coordinates as 32-byte arrays
+     */
+    private getPublicKeyFromField;
+}
+
+export { type FundingProofParams as F, type NoirProviderConfig as N, type OracleAttestation as O, type ProofResult as P, type ValidityProofParams as V, type FulfillmentProofParams as a, ProofGenerationError as b, type ProofProvider as c, type ProofFramework as d, type PublicKeyCoordinates as e, NoirProofProvider as f };

package/dist/proofs/noir.d.mts

@@ -1,2 +1,2 @@
 import '@sip-protocol/types';
-export { f as NoirProofProvider, N as NoirProviderConfig, e as PublicKeyCoordinates } from '../noir-BTyLXLlZ.mjs';
+export { f as NoirProofProvider, N as NoirProviderConfig, e as PublicKeyCoordinates } from '../noir-DKfEzWy9.mjs';

package/dist/proofs/noir.d.ts

@@ -1,2 +1,2 @@
 import '@sip-protocol/types';
-export { f as NoirProofProvider, N as NoirProviderConfig, e as PublicKeyCoordinates } from '../noir-BTyLXLlZ.js';
+export { f as NoirProofProvider, N as NoirProviderConfig, e as PublicKeyCoordinates } from '../noir-DKfEzWy9.js';

package/dist/proofs/noir.js

@@ -1000,6 +1000,7 @@ var NoirProofProvider = class {
     this.config = {
       backend: "barretenberg",
       verbose: false,
+      strictMode: false,
       ...config
     };
   }
@@ -1348,11 +1349,19 @@ var NoirProofProvider = class {
         attestation.txHash,
         attestation.blockNumber
       );
+      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."
+          );
+        }
+        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."
+        );
+      }
       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.");
-      }
       const witnessInputs = {
         // Public inputs
         intent_hash: intentHashField,

package/dist/proofs/noir.mjs

@@ -28,6 +28,7 @@ var NoirProofProvider = class {
     this.config = {
       backend: "barretenberg",
       verbose: false,
+      strictMode: false,
       ...config
     };
   }
@@ -376,11 +377,19 @@ var NoirProofProvider = class {
         attestation.txHash,
         attestation.blockNumber
       );
+      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."
+          );
+        }
+        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."
+        );
+      }
       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.");
-      }
       const witnessInputs = {
         // Public inputs
         intent_hash: intentHashField,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sip-protocol/sdk",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "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,8 +36,21 @@
     "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",
+    "demo:auction": "tsx examples/auction-demo.ts"
+  },
   "dependencies": {
     "@aztec/bb.js": "^0.63.1",
+    "@ethereumjs/rlp": "^10.1.0",
     "@noble/ciphers": "^2.0.1",
     "@noble/curves": "^1.3.0",
     "@noble/hashes": "^1.3.3",
@@ -61,16 +74,5 @@
     "stealth-addresses",
     "zcash"
   ],
-  "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"
-  }
-}
+  "license": "MIT"
+}

package/src/adapters/near-intents.ts

@@ -39,6 +39,8 @@ import {
   getCurveForChain,
   type StealthCurve,
 } from '../stealth'
+import { ed25519PublicKeyToAptosAddress } from '../move/aptos'
+import { ed25519PublicKeyToSuiAddress } from '../move/sui'
 import { ValidationError } from '../errors'
 import { isAddressValidForChain, getChainAddressType } from '../validation'
 
@@ -360,12 +362,16 @@ export class NEARIntentsAdapter {
           recipientAddress = ed25519PublicKeyToSolanaAddress(stealthAddress.address)
         } else if (outputChain === 'near') {
           recipientAddress = ed25519PublicKeyToNearAddress(stealthAddress.address)
+        } else if (outputChain === 'aptos') {
+          recipientAddress = ed25519PublicKeyToAptosAddress(stealthAddress.address)
+        } else if (outputChain === 'sui') {
+          recipientAddress = ed25519PublicKeyToSuiAddress(stealthAddress.address)
         } else {
-          // Future ed25519 chains
+          // This should not happen if ED25519_CHAINS is kept in sync
           throw new ValidationError(
-            `ed25519 address derivation not implemented for ${outputChain}`,
+            `ed25519 address derivation not implemented for ${outputChain}. Please add support in near-intents.ts.`,
             'outputAsset',
-            { outputChain }
+            { outputChain, hint: 'Add address derivation function for this chain' }
           )
         }
         nativeRecipientAddress = recipientAddress
@@ -419,6 +425,10 @@ export class NEARIntentsAdapter {
               refundAddress = ed25519PublicKeyToSolanaAddress(refundStealth.stealthAddress.address)
             } else if (inputChain === 'near') {
               refundAddress = ed25519PublicKeyToNearAddress(refundStealth.stealthAddress.address)
+            } else if (inputChain === 'aptos') {
+              refundAddress = ed25519PublicKeyToAptosAddress(refundStealth.stealthAddress.address)
+            } else if (inputChain === 'sui') {
+              refundAddress = ed25519PublicKeyToSuiAddress(refundStealth.stealthAddress.address)
             }
           } else {
             // Cross-curve: output is secp256k1 but input is ed25519

package/src/auction/index.ts

@@ -0,0 +1,20 @@
+/**
+ * Sealed-Bid Auction Module
+ *
+ * Cryptographic primitives for privacy-preserving sealed-bid auctions.
+ *
+ * @module auction
+ */
+
+export {
+  SealedBidAuction,
+  createSealedBidAuction,
+  type SealedBid,
+  type BidReceipt,
+  type RevealedBid,
+  type CreateBidParams,
+  type VerifyBidParams,
+} from './sealed-bid'
+
+// Re-export winner verification types from @sip-protocol/types
+export type { WinnerResult, WinnerProof, WinnerVerification } from '@sip-protocol/types'