@sip-protocol/sdk 0.7.2 → 0.7.4

package/src/config/endpoints.ts

@@ -0,0 +1,100 @@
+/**
+ * Centralized RPC endpoint configuration
+ *
+ * All localhost URLs are configurable via environment variables.
+ * This allows Docker, Kubernetes, and CI environments to override defaults.
+ *
+ * @module config/endpoints
+ */
+
+/**
+ * Get environment variable or return default
+ * Works in both Node.js and browser environments
+ */
+function getEnvVar(name: string, defaultValue: string): string {
+  if (typeof process !== 'undefined' && process.env) {
+    return process.env[name] || defaultValue
+  }
+  return defaultValue
+}
+
+/**
+ * Solana RPC endpoints
+ */
+export const SOLANA_RPC_ENDPOINTS = {
+  localnet: getEnvVar('SOLANA_LOCALNET_RPC', 'http://localhost:8899'),
+  devnet: getEnvVar('SOLANA_DEVNET_RPC', 'https://api.devnet.solana.com'),
+  testnet: getEnvVar('SOLANA_TESTNET_RPC', 'https://api.testnet.solana.com'),
+  mainnet: getEnvVar('SOLANA_MAINNET_RPC', 'https://api.mainnet-beta.solana.com'),
+} as const
+
+/**
+ * Solana explorer endpoints
+ */
+export const SOLANA_EXPLORER_ENDPOINTS = {
+  localnet: getEnvVar('SOLANA_LOCALNET_EXPLORER', 'http://localhost:3000'),
+  devnet: getEnvVar('SOLANA_DEVNET_EXPLORER', 'https://explorer.solana.com'),
+  testnet: getEnvVar('SOLANA_TESTNET_EXPLORER', 'https://explorer.solana.com'),
+  mainnet: getEnvVar('SOLANA_MAINNET_EXPLORER', 'https://explorer.solana.com'),
+} as const
+
+/**
+ * Ethereum RPC endpoints
+ */
+export const ETH_RPC_ENDPOINTS = {
+  localnet: getEnvVar('ETH_LOCALNET_RPC', 'http://localhost:8545'),
+  goerli: getEnvVar('ETH_GOERLI_RPC', 'https://rpc.ankr.com/eth_goerli'),
+  sepolia: getEnvVar('ETH_SEPOLIA_RPC', 'https://rpc.ankr.com/eth_sepolia'),
+  mainnet: getEnvVar('ETH_MAINNET_RPC', 'https://rpc.ankr.com/eth'),
+} as const
+
+/**
+ * Sui RPC endpoints
+ */
+export const SUI_RPC_ENDPOINTS = {
+  localnet: getEnvVar('SUI_LOCALNET_RPC', 'http://localhost:9000'),
+  devnet: getEnvVar('SUI_DEVNET_RPC', 'https://fullnode.devnet.sui.io:443'),
+  testnet: getEnvVar('SUI_TESTNET_RPC', 'https://fullnode.testnet.sui.io:443'),
+  mainnet: getEnvVar('SUI_MAINNET_RPC', 'https://fullnode.mainnet.sui.io:443'),
+} as const
+
+/**
+ * Zcash RPC configuration
+ */
+export interface ZcashRpcConfig {
+  host: string
+  port: number
+}
+
+export const ZCASH_RPC_CONFIG: ZcashRpcConfig = {
+  host: getEnvVar('ZCASH_RPC_HOST', '127.0.0.1'),
+  port: parseInt(getEnvVar('ZCASH_RPC_PORT', '8232'), 10),
+}
+
+/**
+ * Get all configurable endpoint environment variables
+ * Useful for documentation and validation
+ */
+export function getEndpointEnvVars(): Record<string, { envVar: string; default: string }> {
+  return {
+    // Solana
+    'solana.localnet': { envVar: 'SOLANA_LOCALNET_RPC', default: 'http://localhost:8899' },
+    'solana.devnet': { envVar: 'SOLANA_DEVNET_RPC', default: 'https://api.devnet.solana.com' },
+    'solana.testnet': { envVar: 'SOLANA_TESTNET_RPC', default: 'https://api.testnet.solana.com' },
+    'solana.mainnet': { envVar: 'SOLANA_MAINNET_RPC', default: 'https://api.mainnet-beta.solana.com' },
+    'solana.localnet.explorer': { envVar: 'SOLANA_LOCALNET_EXPLORER', default: 'http://localhost:3000' },
+    // Ethereum
+    'ethereum.localnet': { envVar: 'ETH_LOCALNET_RPC', default: 'http://localhost:8545' },
+    'ethereum.goerli': { envVar: 'ETH_GOERLI_RPC', default: 'https://rpc.ankr.com/eth_goerli' },
+    'ethereum.sepolia': { envVar: 'ETH_SEPOLIA_RPC', default: 'https://rpc.ankr.com/eth_sepolia' },
+    'ethereum.mainnet': { envVar: 'ETH_MAINNET_RPC', default: 'https://rpc.ankr.com/eth' },
+    // Sui
+    'sui.localnet': { envVar: 'SUI_LOCALNET_RPC', default: 'http://localhost:9000' },
+    'sui.devnet': { envVar: 'SUI_DEVNET_RPC', default: 'https://fullnode.devnet.sui.io:443' },
+    'sui.testnet': { envVar: 'SUI_TESTNET_RPC', default: 'https://fullnode.testnet.sui.io:443' },
+    'sui.mainnet': { envVar: 'SUI_MAINNET_RPC', default: 'https://fullnode.mainnet.sui.io:443' },
+    // Zcash
+    'zcash.host': { envVar: 'ZCASH_RPC_HOST', default: '127.0.0.1' },
+    'zcash.port': { envVar: 'ZCASH_RPC_PORT', default: '8232' },
+  }
+}

package/src/crypto.ts

@@ -22,6 +22,7 @@ import { bytesToHex, randomBytes } from '@noble/hashes/utils'
 import type { Commitment, HexString, Hash } from '@sip-protocol/types'
 import { commit, verifyOpening } from './commitment'
 import { ValidationError, ErrorCode } from './errors'
+import { warnOnce, deprecationMessage } from './utils'
 
 /**
  * Create a Pedersen commitment to a value
@@ -37,10 +38,11 @@ export function createCommitment(
   value: bigint,
   blindingFactor?: Uint8Array,
 ): Commitment {
-  console.warn(
-    'createCommitment() is deprecated and will be removed in v0.2.0. ' +
-    'Use commit() from "./commitment" instead.'
-  )
+  warnOnce('createCommitment', deprecationMessage(
+    'createCommitment()',
+    'commit() from "./commitment"',
+    '2026-06-01'
+  ))
 
   const { commitment, blinding } = commit(value, blindingFactor)
 
@@ -59,10 +61,11 @@ export function verifyCommitment(
   commitment: Commitment,
   expectedValue: bigint,
 ): boolean {
-  console.warn(
-    'verifyCommitment() is deprecated and will be removed in v0.2.0. ' +
-    'Use verifyOpening() from "./commitment" instead.'
-  )
+  warnOnce('verifyCommitment', deprecationMessage(
+    'verifyCommitment()',
+    'verifyOpening() from "./commitment"',
+    '2026-06-01'
+  ))
 
   if (!commitment.blindingFactor) {
     throw new ValidationError(

package/src/errors.ts

@@ -31,6 +31,8 @@ export enum ErrorCode {
   INVALID_ADDRESS = 'SIP_2007',
   MISSING_REQUIRED = 'SIP_2008',
   OUT_OF_RANGE = 'SIP_2009',
+  TOKEN_NOT_FOUND = 'SIP_2010',
+  UNSUPPORTED_CHAIN = 'SIP_2011',
 
   // Cryptographic errors (3xxx)
   CRYPTO_FAILED = 'SIP_3000',
@@ -81,6 +83,25 @@ export enum ErrorCode {
   WALLET_CONNECTION_FAILED = 'SIP_7002',
   WALLET_SIGNING_FAILED = 'SIP_7003',
   WALLET_TRANSACTION_FAILED = 'SIP_7004',
+
+  // Security errors (8xxx)
+  SECURITY_ERROR = 'SIP_8000',
+  INVALID_SIGNATURE = 'SIP_8001',
+  INVALID_AUTH = 'SIP_8002',
+  UNAUTHORIZED = 'SIP_8003',
+  RATE_LIMIT_EXCEEDED = 'SIP_8004',
+
+  // Privacy backend errors (9xxx)
+  PRIVACY_BACKEND_ERROR = 'SIP_9000',
+  ARCIUM_ERROR = 'SIP_9001',
+  ARCIUM_INVALID_NETWORK = 'SIP_9002',
+  ARCIUM_COMPUTATION_FAILED = 'SIP_9003',
+  ARCIUM_COMPUTATION_TIMEOUT = 'SIP_9004',
+  ARCIUM_CLUSTER_UNAVAILABLE = 'SIP_9005',
+  ARCIUM_CIRCUIT_NOT_FOUND = 'SIP_9006',
+  INCO_ERROR = 'SIP_9010',
+  MAGICBLOCK_ERROR = 'SIP_9020',
+  SHADOWWIRE_ERROR = 'SIP_9030',
 }
 
 // ─── Serialized Error Type ───────────────────────────────────────────────────
@@ -423,6 +444,60 @@ export class NetworkError extends SIPError {
   }
 }
 
+// ─── Security Error ──────────────────────────────────────────────────────────
+
+/**
+ * Error thrown when security/authentication checks fail
+ *
+ * Used for signature verification, authorization, and rate limiting.
+ *
+ * @example
+ * ```typescript
+ * throw new SecurityError('Invalid webhook signature', 'INVALID_SIGNATURE')
+ *
+ * // With context
+ * throw new SecurityError('Rate limit exceeded', 'RATE_LIMIT_EXCEEDED', {
+ *   context: { limit: 100, window: '1m' }
+ * })
+ * ```
+ */
+export class SecurityError extends SIPError {
+  /** Security error type for programmatic handling */
+  readonly securityType: string
+
+  constructor(
+    message: string,
+    securityType: string = 'SECURITY_ERROR',
+    options?: {
+      cause?: Error
+      context?: Record<string, unknown>
+    }
+  ) {
+    // Map security type to error code
+    let code: ErrorCode
+    switch (securityType) {
+      case 'INVALID_SIGNATURE':
+        code = ErrorCode.INVALID_SIGNATURE
+        break
+      case 'INVALID_AUTH':
+        code = ErrorCode.INVALID_AUTH
+        break
+      case 'UNAUTHORIZED':
+        code = ErrorCode.UNAUTHORIZED
+        break
+      case 'RATE_LIMIT_EXCEEDED':
+        code = ErrorCode.RATE_LIMIT_EXCEEDED
+        break
+      default:
+        code = ErrorCode.SECURITY_ERROR
+    }
+
+    super(message, code, options)
+    this.name = 'SecurityError'
+    this.securityType = securityType
+  }
+}
+
 // ─── Error Utilities ─────────────────────────────────────────────────────────
 
 /**
@@ -432,6 +507,13 @@ export function isSIPError(error: unknown): error is SIPError {
   return error instanceof SIPError
 }
 
+/**
+ * Check if an error is a security error
+ */
+export function isSecurityError(error: unknown): error is SecurityError {
+  return error instanceof SecurityError
+}
+
 /**
  * Check if an error has a specific error code
  */