@sip-protocol/sdk 0.7.3 → 0.7.4

package/src/stealth/index.ts

@@ -0,0 +1,233 @@
+/**
+ * Stealth Address Module
+ *
+ * Implements EIP-5564 style stealth addresses for multiple curves.
+ *
+ * Flow:
+ * 1. Recipient generates stealth meta-address (spending key P, viewing key Q)
+ * 2. Sender generates ephemeral keypair (r, R = r*G)
+ * 3. Sender computes shared secret: S = r * P
+ * 4. Sender derives stealth address: A = Q + hash(S)*G
+ * 5. Recipient scans: for each R, compute S = p * R, check if A matches
+ *
+ * @module stealth
+ */
+
+import type {
+  StealthMetaAddress,
+  StealthAddress,
+  StealthAddressRecovery,
+  ChainId,
+  HexString,
+} from '@sip-protocol/types'
+import { ValidationError } from '../errors'
+import { isValidChainId } from '../validation'
+
+// Import curve-specific implementations
+import {
+  isEd25519Chain,
+  getCurveForChain,
+  generateEd25519StealthMetaAddress,
+  generateEd25519StealthAddress,
+  deriveEd25519StealthPrivateKey,
+  checkEd25519StealthAddress,
+} from './ed25519'
+
+import {
+  generateSecp256k1StealthMetaAddress,
+  generateSecp256k1StealthAddress,
+  deriveSecp256k1StealthPrivateKey,
+  checkSecp256k1StealthAddress,
+  publicKeyToEthAddress,
+  validateSecp256k1StealthMetaAddress,
+  validateSecp256k1StealthAddress,
+} from './secp256k1'
+
+import {
+  encodeStealthMetaAddress,
+  decodeStealthMetaAddress,
+  validateStealthMetaAddress,
+  parseStealthAddress,
+} from './meta-address'
+
+import {
+  ed25519PublicKeyToSolanaAddress,
+  solanaAddressToEd25519PublicKey,
+  isValidSolanaAddress,
+  ed25519PublicKeyToNearAddress,
+  nearAddressToEd25519PublicKey,
+  isValidNearImplicitAddress,
+  isValidNearAccountId,
+} from './address-derivation'
+
+// Re-export types
+export type { StealthCurve } from './ed25519'
+
+// Re-export utility functions for tests and advanced use cases
+export {
+  bytesToBigInt,
+  bigIntToBytes,
+  bytesToBigIntLE,
+  bigIntToBytesLE,
+  bytesToBase58,
+  base58ToBytes,
+  toChecksumAddress,
+  ED25519_ORDER,
+  ED25519_CHAINS,
+  getEd25519Scalar,
+} from './utils'
+
+// ─── Unified API ────────────────────────────────────────────────────────────
+
+/**
+ * Generate a new stealth meta-address keypair for receiving private payments
+ *
+ * Automatically dispatches to the correct curve implementation based on chain.
+ * - secp256k1 for: ethereum, polygon, arbitrum, optimism, base, bitcoin, zcash
+ * - ed25519 for: solana, near, aptos, sui
+ *
+ * @param chain - Target blockchain network
+ * @param label - Optional human-readable label
+ * @returns Stealth meta-address and private keys
+ * @throws {ValidationError} If chain is invalid
+ */
+export function generateStealthMetaAddress(
+  chain: ChainId,
+  label?: string,
+): {
+  metaAddress: StealthMetaAddress
+  spendingPrivateKey: HexString
+  viewingPrivateKey: HexString
+} {
+  if (!isValidChainId(chain)) {
+    throw new ValidationError(
+      `invalid chain '${chain}', must be one of: solana, ethereum, near, zcash, polygon, arbitrum, optimism, base, bitcoin, aptos, sui, cosmos, osmosis, injective, celestia, sei, dydx`,
+      'chain'
+    )
+  }
+
+  if (isEd25519Chain(chain)) {
+    return generateEd25519StealthMetaAddress(chain, label)
+  }
+
+  return generateSecp256k1StealthMetaAddress(chain, label)
+}
+
+/**
+ * Generate a one-time stealth address for sending funds to a recipient
+ *
+ * Automatically dispatches to the correct curve implementation based on chain.
+ *
+ * @param recipientMetaAddress - Recipient's public stealth meta-address
+ * @returns Stealth address data for publication
+ * @throws {ValidationError} If meta-address is invalid
+ */
+export function generateStealthAddress(
+  recipientMetaAddress: StealthMetaAddress,
+): {
+  stealthAddress: StealthAddress
+  sharedSecret: HexString
+} {
+  validateStealthMetaAddress(recipientMetaAddress)
+
+  if (isEd25519Chain(recipientMetaAddress.chain)) {
+    return generateEd25519StealthAddress(recipientMetaAddress)
+  }
+
+  return generateSecp256k1StealthAddress(recipientMetaAddress)
+}
+
+/**
+ * Derive the private key for a stealth address (for recipient to claim funds)
+ *
+ * Automatically dispatches to the correct curve implementation.
+ *
+ * @param stealthAddress - The stealth address to recover
+ * @param spendingPrivateKey - Recipient's spending private key
+ * @param viewingPrivateKey - Recipient's viewing private key
+ * @returns Recovery data including derived private key
+ * @throws {ValidationError} If any input is invalid
+ */
+export function deriveStealthPrivateKey(
+  stealthAddress: StealthAddress,
+  spendingPrivateKey: HexString,
+  viewingPrivateKey: HexString,
+): StealthAddressRecovery {
+  // Try to detect curve from address length
+  // ed25519: 32 bytes (64 hex chars), secp256k1: 33 bytes (66 hex chars)
+  const addressHex = stealthAddress.address.slice(2)
+
+  if (addressHex.length === 64) {
+    // 32 bytes = ed25519
+    return deriveEd25519StealthPrivateKey(stealthAddress, spendingPrivateKey, viewingPrivateKey)
+  }
+
+  // Default to secp256k1
+  return deriveSecp256k1StealthPrivateKey(stealthAddress, spendingPrivateKey, viewingPrivateKey)
+}
+
+/**
+ * Check if a stealth address was intended for this recipient
+ *
+ * Automatically dispatches to the correct curve implementation.
+ *
+ * @param stealthAddress - Stealth address to check
+ * @param spendingPrivateKey - Recipient's spending private key
+ * @param viewingPrivateKey - Recipient's viewing private key
+ * @returns true if this address belongs to the recipient
+ * @throws {ValidationError} If any input is invalid
+ */
+export function checkStealthAddress(
+  stealthAddress: StealthAddress,
+  spendingPrivateKey: HexString,
+  viewingPrivateKey: HexString,
+): boolean {
+  // Try to detect curve from address length
+  const addressHex = stealthAddress.address.slice(2)
+
+  if (addressHex.length === 64) {
+    // 32 bytes = ed25519
+    return checkEd25519StealthAddress(stealthAddress, spendingPrivateKey, viewingPrivateKey)
+  }
+
+  // Default to secp256k1
+  return checkSecp256k1StealthAddress(stealthAddress, spendingPrivateKey, viewingPrivateKey)
+}
+
+// ─── Re-exports ─────────────────────────────────────────────────────────────
+
+// Chain detection
+export { isEd25519Chain, getCurveForChain }
+
+// ed25519 (Solana, NEAR, Aptos, Sui)
+export {
+  generateEd25519StealthMetaAddress,
+  generateEd25519StealthAddress,
+  deriveEd25519StealthPrivateKey,
+  checkEd25519StealthAddress,
+}
+
+// secp256k1 (Ethereum, Polygon, etc.)
+export { publicKeyToEthAddress }
+
+// Meta-address encoding
+export {
+  encodeStealthMetaAddress,
+  decodeStealthMetaAddress,
+  parseStealthAddress,
+}
+
+// Solana address derivation
+export {
+  ed25519PublicKeyToSolanaAddress,
+  solanaAddressToEd25519PublicKey,
+  isValidSolanaAddress,
+}
+
+// NEAR address derivation
+export {
+  ed25519PublicKeyToNearAddress,
+  nearAddressToEd25519PublicKey,
+  isValidNearImplicitAddress,
+  isValidNearAccountId,
+}

package/src/stealth/meta-address.ts

@@ -0,0 +1,221 @@
+/**
+ * Stealth Meta-Address Encoding/Decoding
+ *
+ * Functions for encoding and decoding stealth meta-addresses.
+ */
+
+import type { StealthMetaAddress, StealthAddress, ChainId, HexString } from '@sip-protocol/types'
+import { ValidationError } from '../errors'
+import {
+  isValidChainId,
+  isValidCompressedPublicKey,
+  isValidEd25519PublicKey,
+} from '../validation'
+import { isEd25519Chain } from './ed25519'
+
+// ─── Meta-Address Encoding ──────────────────────────────────────────────────
+
+/**
+ * Encode a stealth meta-address as a string
+ * Format: sip:{chain}:{spendingKey}:{viewingKey}
+ */
+export function encodeStealthMetaAddress(metaAddress: StealthMetaAddress): string {
+  return `sip:${metaAddress.chain}:${metaAddress.spendingKey}:${metaAddress.viewingKey}`
+}
+
+/**
+ * Decode a stealth meta-address from a string
+ *
+ * @param encoded - Encoded stealth meta-address (format: sip:<chain>:<spendingKey>:<viewingKey>)
+ * @returns Decoded StealthMetaAddress
+ * @throws {ValidationError} If format is invalid or keys are malformed
+ */
+export function decodeStealthMetaAddress(encoded: string): StealthMetaAddress {
+  if (typeof encoded !== 'string') {
+    throw new ValidationError('must be a string', 'encoded')
+  }
+
+  const parts = encoded.split(':')
+  if (parts.length < 4 || parts[0] !== 'sip') {
+    throw new ValidationError(
+      'invalid format, expected: sip:<chain>:<spendingKey>:<viewingKey>',
+      'encoded'
+    )
+  }
+
+  const [, chain, spendingKey, viewingKey] = parts
+
+  // Validate chain
+  if (!isValidChainId(chain)) {
+    throw new ValidationError(
+      `invalid chain '${chain}'`,
+      'encoded.chain'
+    )
+  }
+
+  // Validate keys based on chain's curve type
+  const chainId = chain as ChainId
+  if (isEd25519Chain(chainId)) {
+    // Ed25519 chains (Solana, NEAR) use 32-byte public keys
+    if (!isValidEd25519PublicKey(spendingKey)) {
+      throw new ValidationError(
+        'spendingKey must be a valid 32-byte ed25519 public key',
+        'encoded.spendingKey'
+      )
+    }
+
+    if (!isValidEd25519PublicKey(viewingKey)) {
+      throw new ValidationError(
+        'viewingKey must be a valid 32-byte ed25519 public key',
+        'encoded.viewingKey'
+      )
+    }
+  } else {
+    // secp256k1 chains (Ethereum, etc.) use 33-byte compressed public keys
+    if (!isValidCompressedPublicKey(spendingKey)) {
+      throw new ValidationError(
+        'spendingKey must be a valid compressed secp256k1 public key',
+        'encoded.spendingKey'
+      )
+    }
+
+    if (!isValidCompressedPublicKey(viewingKey)) {
+      throw new ValidationError(
+        'viewingKey must be a valid compressed secp256k1 public key',
+        'encoded.viewingKey'
+      )
+    }
+  }
+
+  return {
+    chain: chain as ChainId,
+    spendingKey: spendingKey as HexString,
+    viewingKey: viewingKey as HexString,
+  }
+}
+
+// ─── Multi-Curve Meta-Address Validation ────────────────────────────────────
+
+/**
+ * Validate a StealthMetaAddress object
+ * Supports both secp256k1 (EVM chains) and ed25519 (Solana, NEAR, etc.) key formats
+ */
+export function validateStealthMetaAddress(
+  metaAddress: StealthMetaAddress,
+  field: string = 'recipientMetaAddress'
+): void {
+  if (!metaAddress || typeof metaAddress !== 'object') {
+    throw new ValidationError('must be an object', field)
+  }
+
+  // Validate chain
+  if (!isValidChainId(metaAddress.chain)) {
+    throw new ValidationError(
+      `invalid chain '${metaAddress.chain}'`,
+      `${field}.chain`
+    )
+  }
+
+  // Determine key type based on chain (ed25519 vs secp256k1)
+  const isEd25519 = isEd25519Chain(metaAddress.chain)
+
+  if (isEd25519) {
+    // Ed25519 chains (Solana, NEAR, Aptos, Sui) use 32-byte public keys
+    if (!isValidEd25519PublicKey(metaAddress.spendingKey)) {
+      throw new ValidationError(
+        'spendingKey must be a valid ed25519 public key (32 bytes)',
+        `${field}.spendingKey`
+      )
+    }
+    if (!isValidEd25519PublicKey(metaAddress.viewingKey)) {
+      throw new ValidationError(
+        'viewingKey must be a valid ed25519 public key (32 bytes)',
+        `${field}.viewingKey`
+      )
+    }
+  } else {
+    // Secp256k1 chains (Ethereum, etc.) use 33-byte compressed public keys
+    if (!isValidCompressedPublicKey(metaAddress.spendingKey)) {
+      throw new ValidationError(
+        'spendingKey must be a valid compressed secp256k1 public key (33 bytes, starting with 02 or 03)',
+        `${field}.spendingKey`
+      )
+    }
+    if (!isValidCompressedPublicKey(metaAddress.viewingKey)) {
+      throw new ValidationError(
+        'viewingKey must be a valid compressed secp256k1 public key (33 bytes, starting with 02 or 03)',
+        `${field}.viewingKey`
+      )
+    }
+  }
+}
+
+// ─── Stealth Address Parsing ────────────────────────────────────────────────
+
+/**
+ * Parse a stealth address string into its components
+ *
+ * Format: `<stealthAddress>:<ephemeralPublicKey>:<viewTag>`
+ */
+export function parseStealthAddress(input: string): StealthAddress {
+  if (!input || typeof input !== 'string') {
+    throw new ValidationError(
+      'stealth address input must be a non-empty string',
+      'input'
+    )
+  }
+
+  const parts = input.split(':')
+  if (parts.length !== 3) {
+    throw new ValidationError(
+      'invalid stealth address format. Expected: <address>:<ephemeralPublicKey>:<viewTag>',
+      'input'
+    )
+  }
+
+  const [address, ephemeralPublicKey, viewTagHex] = parts
+
+  // Validate address (basic check - hex or base58)
+  if (!address || address.length < 20) {
+    throw new ValidationError(
+      'invalid stealth address: too short',
+      'address'
+    )
+  }
+
+  // Validate ephemeral public key (hex or base58)
+  if (!ephemeralPublicKey || ephemeralPublicKey.length < 20) {
+    throw new ValidationError(
+      'invalid ephemeral public key: too short',
+      'ephemeralPublicKey'
+    )
+  }
+
+  // Validate view tag (1-2 hex chars, 0-255)
+  if (!viewTagHex || viewTagHex.length > 2 || !/^[0-9a-fA-F]+$/.test(viewTagHex)) {
+    throw new ValidationError(
+      'invalid view tag: must be 1-2 hex characters (0-255)',
+      'viewTag'
+    )
+  }
+
+  const viewTag = parseInt(viewTagHex, 16)
+  if (viewTag < 0 || viewTag > 255) {
+    throw new ValidationError(
+      'view tag must be in range 0-255',
+      'viewTag'
+    )
+  }
+
+  // Normalize address to hex format if needed
+  const normalizedAddress = address.startsWith('0x') ? address : `0x${address}`
+  const normalizedEphemeral = ephemeralPublicKey.startsWith('0x')
+    ? ephemeralPublicKey
+    : `0x${ephemeralPublicKey}`
+
+  return {
+    address: normalizedAddress as HexString,
+    ephemeralPublicKey: normalizedEphemeral as HexString,
+    viewTag,
+  }
+}