@sip-protocol/sdk 0.5.1 → 0.6.1

package/src/compliance/derivation.ts

@@ -122,10 +122,20 @@ export interface DeriveMultipleParams {
  */
 export class AuditorKeyDerivation {
   /**
-   * SIP Protocol coin type (BIP-44 registered)
+   * SIP Protocol coin type for BIP-44 derivation
    *
-   * Note: This is a placeholder. In production, register with SLIP-44:
-   * https://github.com/satoshilabs/slips/blob/master/slip-0044.md
+   * This uses 1234 as SIP Protocol's internal coin type identifier.
+   *
+   * **Registration Status**: Not registered with SLIP-44
+   *
+   * **Why this is acceptable**:
+   * - SIP viewing keys are protocol-specific, not wallet-portable
+   * - Keys derived here are for auditor access, not user funds
+   * - SLIP-44 registration is for coin types that need hardware wallet support
+   *
+   * **Future consideration**: If hardware wallet integration for SIP auditor keys
+   * is desired, submit a PR to https://github.com/satoshilabs/slips to register
+   * an official coin type. Current value (1234) is in the unregistered range.
    */
   static readonly COIN_TYPE = 1234
 

package/src/compliance/reports.ts

@@ -24,6 +24,7 @@ import type {
   FINCENExport,
   FINCENTransaction,
   CSVExport,
+  Jurisdiction,
 } from './types'
 import { generatePdfReport } from './pdf'
 
@@ -533,7 +534,7 @@ export class ComplianceReporter {
   private exportToFATF(
     reportId: string,
     transactions: DecryptedTransaction[],
-    jurisdiction: string,
+    jurisdiction: Jurisdiction,
     currency: string
   ): FATFExport {
     const fatfTransactions: FATFTransaction[] = transactions.map((tx) => ({
@@ -548,7 +549,7 @@ export class ComplianceReporter {
     return {
       reportId,
       generatedAt: new Date().toISOString(),
-      jurisdiction: jurisdiction as any,
+      jurisdiction,
       transactions: fatfTransactions,
     }
   }
@@ -612,7 +613,7 @@ export class ComplianceReporter {
   private exportToCSV(
     reportId: string,
     transactions: DecryptedTransaction[],
-    jurisdiction: string,
+    jurisdiction: Jurisdiction,
     currency: string
   ): CSVExport {
     const headers = [
@@ -636,7 +637,7 @@ export class ComplianceReporter {
     return {
       reportId,
       generatedAt: new Date().toISOString(),
-      jurisdiction: jurisdiction as any,
+      jurisdiction,
       headers,
       rows,
     }

package/src/cosmos/ibc-stealth.ts

@@ -34,7 +34,7 @@ import {
   type CosmosStealthResult,
   CHAIN_PREFIXES,
 } from './stealth'
-import type { HexString, StealthMetaAddress } from '@sip-protocol/types'
+import type { HexString, StealthMetaAddress, ChainId } from '@sip-protocol/types'
 import { ValidationError } from '../errors'
 
 /**
@@ -679,7 +679,7 @@ export class CosmosIBCStealthService {
 
     const [, chain, spendingKey, viewingKey] = parts
     return {
-      chain: chain as any,
+      chain: chain as ChainId,
       spendingKey: spendingKey as HexString,
       viewingKey: viewingKey as HexString,
     }

package/src/cosmos/stealth.ts

@@ -32,6 +32,7 @@ import type {
   StealthAddress,
   StealthAddressRecovery,
   HexString,
+  ChainId,
 } from '@sip-protocol/types'
 import { ValidationError } from '../errors'
 
@@ -118,12 +119,11 @@ export class CosmosStealthService {
     const result = generateStealthMetaAddress('ethereum', label)
 
     // Override chain with actual Cosmos chain ID
-    // Note: This is a workaround since the core types don't include Cosmos chains yet
     return {
       ...result,
       metaAddress: {
         ...result.metaAddress,
-        chain: chain as any, // Will be updated in types package
+        chain: chain as ChainId,
       },
     }
   }

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/governance/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Governance module for SIP Protocol
+ *
+ * Provides private voting functionality for DAO governance
+ */
+
+export {
+  PrivateVoting,
+  createPrivateVoting,
+} from './private-vote'
+
+export type {
+  EncryptedVote,
+  RevealedVote,
+  CastVoteParams,
+  EncryptedTally,
+  TallyResult,
+  DecryptionShare,
+} from './private-vote'