@sip-protocol/sdk 0.5.1 → 0.6.1

package/src/index.ts

@@ -93,8 +93,9 @@ export {
 
 export type { StealthCurve } from './stealth'
 
-// Move blockchain stealth addresses (Aptos)
+// Move blockchain stealth addresses (Aptos, Sui)
 export {
+  // Aptos
   AptosStealthService,
   generateAptosStealthAddress,
   deriveAptosStealthPrivateKey,
@@ -102,9 +103,17 @@ export {
   ed25519PublicKeyToAptosAddress,
   aptosAddressToAuthKey,
   isValidAptosAddress,
+  // Sui
+  SuiStealthService,
+  generateSuiStealthAddress,
+  deriveSuiStealthPrivateKey,
+  checkSuiStealthAddress,
+  ed25519PublicKeyToSuiAddress,
+  normalizeSuiAddress,
+  isValidSuiAddress,
 } from './move'
 
-export type { AptosStealthResult } from './move'
+export type { AptosStealthResult, SuiStealthResult } from './move'
 
 // Cosmos blockchain stealth addresses
 export {
@@ -297,6 +306,12 @@ export type {
   CreatePaymentParams,
   PaymentReceipt,
   TrackedPayment,
+  // NFT types
+  PrivateNFTOwnership,
+  OwnershipProof,
+  CreatePrivateOwnershipParams,
+  ProveOwnershipParams,
+  OwnershipVerification,
 } from '@sip-protocol/types'
 
 // Payment status enum
@@ -566,6 +581,39 @@ export {
   type TimeLockParams,
 } from './compliance'
 
+// Sealed-Bid Auctions
+export {
+  SealedBidAuction,
+  createSealedBidAuction,
+} from './auction'
+
+export type {
+  SealedBid,
+  BidReceipt,
+  CreateBidParams,
+  VerifyBidParams,
+} from './auction'
+
+// Governance (Private Voting)
+export {
+  PrivateVoting,
+  createPrivateVoting,
+} from './governance'
+
+export type {
+  EncryptedVote,
+  RevealedVote,
+  CastVoteParams,
+} from './governance'
+
+// NFT Module
+export {
+  PrivateNFT,
+  createPrivateOwnership,
+  proveOwnership,
+  verifyOwnership,
+} from './nft'
+
 // Wallet Adapters
 export {
   BaseWalletAdapter,

package/src/intent.ts

@@ -18,6 +18,7 @@ import {
   type HexString,
   type Hash,
   type PrivacyLevel,
+  type ChainId,
 } from '@sip-protocol/types'
 import { generateStealthAddress, decodeStealthMetaAddress } from './stealth'
 import {
@@ -41,24 +42,148 @@ 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
+
+  /**
+   * Signature proving ownership of the sender's address
+   *
+   * Required for production proof generation. This signature proves
+   * the sender controls the address that holds the input funds.
+   *
+   * Should be a 64-byte ECDSA signature over the address.
+   */
+  ownershipSignature?: Uint8Array
+
+  /**
+   * Sender's secret key for nullifier derivation
+   *
+   * Required for production proof generation. Used to derive:
+   * - Public key for ECDSA verification in proofs
+   * - Nullifier to prevent double-spending
+   *
+   * Should be a 32-byte secret. Keep this secure!
+   */
+  senderSecret?: Uint8Array
+
+  /**
+   * Signature authorizing this specific intent
+   *
+   * Required for production proof generation. This signature proves
+   * the sender authorized this intent (signs the intent hash).
+   *
+   * Should be a 64-byte ECDSA signature over the intent hash.
+   */
+  authorizationSignature?: Uint8Array
+
+  /**
+   * Allow placeholder signatures for development/testing
+   *
+   * When true, allows proof generation with empty placeholder signatures.
+   * **WARNING**: Never use this in production! Proofs with placeholders
+   * are not cryptographically valid.
+   *
+   * @default false
+   */
+  allowPlaceholders?: boolean
 }
 
 /**
- * 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> = {}
   private senderAddress?: string
   private proofProvider?: ProofProvider
+  private ownershipSignature?: Uint8Array
+  private senderSecret?: Uint8Array
+  private authorizationSignature?: Uint8Array
+  private allowPlaceholders?: boolean
 
   /**
    * Set the input for the intent
@@ -92,7 +217,7 @@ export class IntentBuilder {
 
     this.params.input = {
       asset: {
-        chain: chain as any,
+        chain: chain as ChainId,
         symbol: token,
         address: null,
         decimals: 18, // Default, should be looked up
@@ -136,7 +261,7 @@ export class IntentBuilder {
 
     this.params.output = {
       asset: {
-        chain: chain as any,
+        chain: chain as ChainId,
         symbol: token,
         address: null,
         decimals: 18,
@@ -238,6 +363,55 @@ export class IntentBuilder {
     return this
   }
 
+  /**
+   * Set the signatures and secret for proof generation
+   *
+   * Required for production proof generation. Provides the cryptographic
+   * materials needed to generate valid ZK proofs.
+   *
+   * @param signatures - Object containing ownership signature, sender secret, and authorization signature
+   * @returns this for chaining
+   *
+   * @example
+   * ```typescript
+   * const intent = await builder
+   *   .input('near', 'NEAR', 100n)
+   *   .output('zcash', 'ZEC', 95n)
+   *   .privacy(PrivacyLevel.SHIELDED)
+   *   .withProvider(noirProvider)
+   *   .withSignatures({
+   *     ownershipSignature: await wallet.signMessage(address),
+   *     senderSecret: wallet.privateKey,
+   *     authorizationSignature: await wallet.signMessage(intentHash),
+   *   })
+   *   .build()
+   * ```
+   */
+  withSignatures(signatures: {
+    ownershipSignature: Uint8Array
+    senderSecret: Uint8Array
+    authorizationSignature: Uint8Array
+  }): this {
+    this.ownershipSignature = signatures.ownershipSignature
+    this.senderSecret = signatures.senderSecret
+    this.authorizationSignature = signatures.authorizationSignature
+    return this
+  }
+
+  /**
+   * Allow placeholder signatures for development/testing
+   *
+   * **WARNING**: Never use this in production! Proofs with placeholders
+   * are not cryptographically valid.
+   *
+   * @param allow - Whether to allow placeholders (default: true)
+   * @returns this for chaining
+   */
+  withPlaceholders(allow: boolean = true): this {
+    this.allowPlaceholders = allow
+    return this
+  }
+
   /**
    * Build the shielded intent
    *
@@ -250,6 +424,10 @@ export class IntentBuilder {
     return createShieldedIntent(this.params as CreateIntentParams, {
       senderAddress: this.senderAddress,
       proofProvider: this.proofProvider,
+      ownershipSignature: this.ownershipSignature,
+      senderSecret: this.senderSecret,
+      authorizationSignature: this.authorizationSignature,
+      allowPlaceholders: this.allowPlaceholders,
     })
   }
 }
@@ -281,7 +459,14 @@ export async function createShieldedIntent(
   validateCreateIntentParams(params)
 
   const { input, output, privacy, recipientMetaAddress, viewingKey, ttl = 300 } = params
-  const { senderAddress, proofProvider } = options ?? {}
+  const {
+    senderAddress,
+    proofProvider,
+    ownershipSignature,
+    senderSecret,
+    authorizationSignature,
+    allowPlaceholders = false,
+  } = options ?? {}
 
   // Get privacy configuration
   // Compute viewing key hash the same way as generateViewingKey():
@@ -331,12 +516,42 @@ export async function createShieldedIntent(
   const requiresProofs = privacy !== PrivacyLevelEnum.TRANSPARENT
 
   if (requiresProofs && proofProvider && proofProvider.isReady) {
+    // Check if signatures are provided or placeholders are allowed
+    const hasSignatures = ownershipSignature && senderSecret && authorizationSignature
+    const usingPlaceholders = !hasSignatures
+
+    if (usingPlaceholders && !allowPlaceholders) {
+      throw new ValidationError(
+        'Proof generation requires signatures. Provide ownershipSignature, senderSecret, and authorizationSignature in options, or set allowPlaceholders: true for development/testing.',
+        'options',
+        {
+          missing: [
+            !ownershipSignature && 'ownershipSignature',
+            !senderSecret && 'senderSecret',
+            !authorizationSignature && 'authorizationSignature',
+          ].filter(Boolean),
+        }
+      )
+    }
+
+    if (usingPlaceholders) {
+      console.warn(
+        '[createShieldedIntent] WARNING: Using placeholder signatures for proof generation. ' +
+        'These proofs are NOT cryptographically valid. Do NOT use in production!'
+      )
+    }
+
     // Helper to convert HexString to Uint8Array
     const hexToUint8 = (hex: HexString): Uint8Array => {
       const cleanHex = hex.startsWith('0x') ? hex.slice(2) : hex
       return hexToBytes(cleanHex)
     }
 
+    // Use provided signatures or placeholders (if allowed)
+    const effectiveOwnershipSig = ownershipSignature ?? new Uint8Array(64)
+    const effectiveSenderSecret = senderSecret ?? new Uint8Array(32)
+    const effectiveAuthSig = authorizationSignature ?? new Uint8Array(64)
+
     // Generate funding proof
     const fundingResult = await proofProvider.generateFundingProof({
       balance: input.amount,
@@ -344,7 +559,7 @@ export async function createShieldedIntent(
       blindingFactor: hexToUint8(inputCommitment.blindingFactor as HexString),
       assetId: input.asset.symbol,
       userAddress: senderAddress ?? '0x0',
-      ownershipSignature: new Uint8Array(64), // Placeholder - would come from wallet
+      ownershipSignature: effectiveOwnershipSig,
     })
     fundingProof = fundingResult.proof
 
@@ -353,8 +568,8 @@ export async function createShieldedIntent(
       intentHash: hash(intentId) as HexString,
       senderAddress: senderAddress ?? '0x0',
       senderBlinding: hexToUint8(senderCommitment.blindingFactor as HexString),
-      senderSecret: new Uint8Array(32), // Placeholder - would come from wallet
-      authorizationSignature: new Uint8Array(64), // Placeholder - would come from wallet
+      senderSecret: effectiveSenderSecret,
+      authorizationSignature: effectiveAuthSig,
       nonce: new Uint8Array(32), // Could use randomBytes here
       timestamp: now,
       expiry: now + ttl,
@@ -381,8 +596,8 @@ export async function createShieldedIntent(
     // - TRANSPARENT mode (not required)
     // - No proof provider given
     // - Provider not ready
-    fundingProof: fundingProof as any,
-    validityProof: validityProof as any,
+    fundingProof,
+    validityProof,
 
     viewingKeyHash: privacyConfig.viewingKey?.hash,
   }

package/src/nft/index.ts

@@ -0,0 +1,27 @@
+/**
+ * NFT Module for SIP Protocol
+ *
+ * Private NFT ownership using stealth addresses and zero-knowledge proofs.
+ *
+ * @module nft
+ */
+
+export {
+  PrivateNFT,
+  createPrivateOwnership,
+  proveOwnership,
+  verifyOwnership,
+} from './private-nft'
+
+// Re-export types for convenience
+export type {
+  PrivateNFTOwnership,
+  OwnershipProof,
+  OwnershipVerification,
+  CreatePrivateOwnershipParams,
+  ProveOwnershipParams,
+  TransferPrivatelyParams,
+  TransferResult,
+  NFTTransfer,
+  OwnedNFT,
+} from '@sip-protocol/types'