@sip-protocol/sdk 0.6.26 → 0.7.1

package/src/chains/solana/types.ts

@@ -0,0 +1,169 @@
+/**
+ * Solana Same-Chain Privacy Types
+ *
+ * Type definitions for Solana stealth address transfers and scanning.
+ */
+
+import type { PublicKey, Connection, Transaction, VersionedTransaction } from '@solana/web3.js'
+import type { StealthMetaAddress, StealthAddress, HexString } from '@sip-protocol/types'
+import type { SolanaCluster } from './constants'
+
+/**
+ * Parameters for sending a private SPL token transfer
+ */
+export interface SolanaPrivateTransferParams {
+  /** Solana RPC connection */
+  connection: Connection
+  /** Sender's public key */
+  sender: PublicKey
+  /** Sender's token account (ATA) */
+  senderTokenAccount: PublicKey
+  /** Recipient's stealth meta-address (sip:solana:...) */
+  recipientMetaAddress: StealthMetaAddress
+  /** SPL token mint address */
+  mint: PublicKey
+  /** Amount to transfer (in token's smallest unit) */
+  amount: bigint
+  /** Function to sign the transaction */
+  signTransaction: <T extends Transaction | VersionedTransaction>(tx: T) => Promise<T>
+}
+
+/**
+ * Result of a private SPL token transfer
+ */
+export interface SolanaPrivateTransferResult {
+  /** Transaction signature */
+  txSignature: string
+  /** Stealth address (base58 Solana address) */
+  stealthAddress: string
+  /** Ephemeral public key (base58) for recipient scanning */
+  ephemeralPublicKey: string
+  /** View tag for efficient scanning */
+  viewTag: string
+  /** Explorer URL for the transaction */
+  explorerUrl: string
+  /** Cluster the transaction was sent on */
+  cluster: SolanaCluster
+}
+
+/**
+ * Parameters for scanning for incoming stealth payments
+ */
+export interface SolanaScanParams {
+  /** Solana RPC connection */
+  connection: Connection
+  /** Recipient's viewing private key (hex) */
+  viewingPrivateKey: HexString
+  /** Recipient's spending public key (hex) */
+  spendingPublicKey: HexString
+  /** Optional: Start scanning from this slot */
+  fromSlot?: number
+  /** Optional: Stop scanning at this slot */
+  toSlot?: number
+  /** Optional: Limit number of results */
+  limit?: number
+}
+
+/**
+ * Result of scanning for incoming payments
+ */
+export interface SolanaScanResult {
+  /** Stealth address that received the payment (base58) */
+  stealthAddress: string
+  /** Ephemeral public key from the sender (base58) */
+  ephemeralPublicKey: string
+  /** Amount received (in token's smallest unit) */
+  amount: bigint
+  /** Token mint address */
+  mint: string
+  /** Token symbol (if known) */
+  tokenSymbol?: string
+  /** Transaction signature */
+  txSignature: string
+  /** Block slot */
+  slot: number
+  /** Block timestamp */
+  timestamp: number
+}
+
+/**
+ * Parameters for claiming a stealth payment
+ */
+export interface SolanaClaimParams {
+  /** Solana RPC connection */
+  connection: Connection
+  /** Stealth address to claim from (base58) */
+  stealthAddress: string
+  /** Ephemeral public key from the payment (base58) */
+  ephemeralPublicKey: string
+  /** Recipient's viewing private key (hex) */
+  viewingPrivateKey: HexString
+  /** Recipient's spending private key (hex) */
+  spendingPrivateKey: HexString
+  /** Destination address to send claimed funds (base58) */
+  destinationAddress: string
+  /** SPL token mint address */
+  mint: PublicKey
+}
+
+/**
+ * Result of claiming a stealth payment
+ */
+export interface SolanaClaimResult {
+  /** Transaction signature */
+  txSignature: string
+  /** Destination address that received the funds (base58) */
+  destinationAddress: string
+  /** Amount claimed (in token's smallest unit) */
+  amount: bigint
+  /** Explorer URL for the transaction */
+  explorerUrl: string
+}
+
+/**
+ * Announcement data stored in transaction memo
+ */
+export interface SolanaAnnouncement {
+  /** Ephemeral public key (base58) */
+  ephemeralPublicKey: string
+  /** View tag for efficient scanning (hex, 1 byte) */
+  viewTag: string
+  /** Full stealth address (for verification) */
+  stealthAddress?: string
+}
+
+/**
+ * Parse announcement from memo string
+ * Format: SIP:1:<ephemeral_pubkey_base58>:<view_tag_hex>
+ */
+export function parseAnnouncement(memo: string): SolanaAnnouncement | null {
+  if (!memo.startsWith('SIP:1:')) {
+    return null
+  }
+
+  const parts = memo.slice(6).split(':')
+  if (parts.length < 2) {
+    return null
+  }
+
+  return {
+    ephemeralPublicKey: parts[0],
+    viewTag: parts[1],
+    stealthAddress: parts[2],
+  }
+}
+
+/**
+ * Create announcement memo string
+ */
+export function createAnnouncementMemo(
+  ephemeralPublicKey: string,
+  viewTag: string,
+  stealthAddress?: string
+): string {
+  const parts = ['SIP:1', ephemeralPublicKey, viewTag]
+  if (stealthAddress) {
+    parts.push(stealthAddress)
+  }
+  return parts.join(':')
+}

package/src/executors/index.ts

@@ -0,0 +1,18 @@
+/**
+ * Executors Module
+ *
+ * Transaction execution strategies for different scenarios.
+ *
+ * @packageDocumentation
+ */
+
+export {
+  SolanaSameChainExecutor,
+  createSameChainExecutor,
+  isSameChainSupported,
+  getSupportedSameChainChains,
+  type SameChainExecutor,
+  type SameChainTransferParams,
+  type SameChainTransferResult,
+  type SolanaSameChainConfig,
+} from './same-chain'

package/src/executors/same-chain.ts

@@ -0,0 +1,154 @@
+/**
+ * Same-Chain Privacy Executor
+ *
+ * Executes privacy-preserving transfers on the same chain,
+ * bypassing cross-chain settlement for direct transfers.
+ */
+
+import type { Connection, PublicKey, Transaction, VersionedTransaction } from '@solana/web3.js'
+import type { StealthMetaAddress, ChainId, HexString } from '@sip-protocol/types'
+import {
+  sendPrivateSPLTransfer,
+  estimatePrivateTransferFee,
+  type SolanaPrivateTransferResult,
+} from '../chains/solana'
+
+/**
+ * Parameters for same-chain private transfer
+ */
+export interface SameChainTransferParams {
+  /** Recipient's stealth meta-address */
+  recipientMetaAddress: StealthMetaAddress
+  /** Amount to transfer (in token's smallest unit) */
+  amount: bigint
+  /** Token identifier (symbol or mint address) */
+  token: string
+}
+
+/**
+ * Result of same-chain private transfer
+ */
+export interface SameChainTransferResult {
+  /** Transaction signature/hash */
+  txHash: string
+  /** Stealth address that received the funds */
+  stealthAddress: string
+  /** Ephemeral public key for recipient scanning */
+  ephemeralPublicKey: string
+  /** Explorer URL */
+  explorerUrl: string
+  /** Chain the transfer was executed on */
+  chain: ChainId
+}
+
+/**
+ * Same-chain executor interface
+ */
+export interface SameChainExecutor {
+  /** Chain this executor handles */
+  readonly chain: ChainId
+
+  /**
+   * Execute a same-chain private transfer
+   */
+  execute(params: SameChainTransferParams): Promise<SameChainTransferResult>
+
+  /**
+   * Estimate transaction fee
+   */
+  estimateFee(params: SameChainTransferParams): Promise<bigint>
+}
+
+/**
+ * Solana-specific executor configuration
+ */
+export interface SolanaSameChainConfig {
+  /** Solana RPC connection */
+  connection: Connection
+  /** Sender's public key */
+  sender: PublicKey
+  /** Sender's token account getter */
+  getTokenAccount: (mint: PublicKey) => Promise<PublicKey>
+  /** Transaction signer */
+  signTransaction: <T extends Transaction | VersionedTransaction>(tx: T) => Promise<T>
+  /** Token mint resolver (symbol -> PublicKey) */
+  getTokenMint: (symbol: string) => PublicKey
+}
+
+/**
+ * Solana Same-Chain Executor
+ *
+ * Executes privacy-preserving SPL token transfers on Solana.
+ */
+export class SolanaSameChainExecutor implements SameChainExecutor {
+  readonly chain = 'solana' as const
+  private config: SolanaSameChainConfig
+
+  constructor(config: SolanaSameChainConfig) {
+    this.config = config
+  }
+
+  async execute(params: SameChainTransferParams): Promise<SameChainTransferResult> {
+    const { recipientMetaAddress, amount, token } = params
+    const { connection, sender, getTokenAccount, signTransaction, getTokenMint } = this.config
+
+    // Resolve token mint
+    const mint = getTokenMint(token)
+
+    // Get sender's token account
+    const senderTokenAccount = await getTokenAccount(mint)
+
+    // Execute private transfer
+    const result = await sendPrivateSPLTransfer({
+      connection,
+      sender,
+      senderTokenAccount,
+      recipientMetaAddress,
+      mint,
+      amount,
+      signTransaction,
+    })
+
+    return {
+      txHash: result.txSignature,
+      stealthAddress: result.stealthAddress,
+      ephemeralPublicKey: result.ephemeralPublicKey,
+      explorerUrl: result.explorerUrl,
+      chain: 'solana',
+    }
+  }
+
+  async estimateFee(params: SameChainTransferParams): Promise<bigint> {
+    // For now, assume ATA might need creation
+    return estimatePrivateTransferFee(this.config.connection, true)
+  }
+}
+
+/**
+ * Factory function to create a same-chain executor for a given chain
+ */
+export function createSameChainExecutor(
+  chain: ChainId,
+  config: SolanaSameChainConfig
+): SameChainExecutor {
+  switch (chain) {
+    case 'solana':
+      return new SolanaSameChainExecutor(config)
+    default:
+      throw new Error(`Same-chain executor not available for chain: ${chain}`)
+  }
+}
+
+/**
+ * Check if same-chain privacy is supported for a chain
+ */
+export function isSameChainSupported(chain: ChainId): boolean {
+  return chain === 'solana'
+}
+
+/**
+ * Get supported same-chain privacy chains
+ */
+export function getSupportedSameChainChains(): ChainId[] {
+  return ['solana']
+}

package/src/index.ts

@@ -46,7 +46,13 @@ export type { SerializedError } from './errors'
 
 // Main client
 export { SIP, createSIP, createProductionSIP } from './sip'
-export type { SIPConfig, WalletAdapter, ProductionQuote } from './sip'
+export type {
+  SIPConfig,
+  WalletAdapter,
+  ProductionQuote,
+  SameChainExecuteParams,
+  SameChainExecuteResult,
+} from './sip'
 
 // Intent creation
 export {
@@ -740,3 +746,54 @@ export type {
   HardwareErrorCodeType,
   MockHardwareConfig,
 } from './wallet'
+
+// Solana Same-Chain Privacy
+export {
+  // Transfer
+  sendPrivateSPLTransfer,
+  estimatePrivateTransferFee,
+  hasTokenAccount,
+  // Scan and Claim
+  scanForPayments,
+  claimStealthPayment,
+  getStealthBalance,
+  // Constants
+  SOLANA_TOKEN_MINTS,
+  SOLANA_TOKEN_DECIMALS,
+  SOLANA_RPC_ENDPOINTS,
+  SOLANA_EXPLORER_URLS,
+  MEMO_PROGRAM_ID,
+  SIP_MEMO_PREFIX,
+  getExplorerUrl as getSolanaExplorerUrl,
+  getTokenMint,
+  getTokenDecimals,
+  // Types helpers
+  parseAnnouncement,
+  createAnnouncementMemo,
+} from './chains/solana'
+
+export type {
+  SolanaPrivateTransferParams,
+  SolanaPrivateTransferResult,
+  SolanaScanParams,
+  SolanaScanResult,
+  SolanaClaimParams,
+  SolanaClaimResult,
+  SolanaAnnouncement,
+  SolanaCluster as SolanaSameChainCluster,
+} from './chains/solana'
+
+// Same-Chain Executors
+export {
+  SolanaSameChainExecutor,
+  createSameChainExecutor,
+  isSameChainSupported,
+  getSupportedSameChainChains,
+} from './executors'
+
+export type {
+  SameChainExecutor,
+  SameChainTransferParams,
+  SameChainTransferResult,
+  SolanaSameChainConfig,
+} from './executors'

package/src/intent.ts

@@ -554,6 +554,16 @@ export async function createShieldedIntent(
       return hexToBytes(cleanHex)
     }
 
+    // SECURITY: Prevent placeholder mode in production environments
+    // Placeholder signatures are NOT cryptographically valid and must never be used in production
+    if (allowPlaceholders && typeof process !== 'undefined' && process.env?.NODE_ENV === 'production') {
+      throw new ValidationError(
+        'allowPlaceholders cannot be used in production environment. ' +
+        'Provide valid senderSecret and signatures for production use.',
+        'options.allowPlaceholders'
+      )
+    }
+
     // Use provided signatures or generate them from senderSecret
     // IMPORTANT: senderSecret must be random even for placeholders, as secp256k1
     // rejects all-zero private keys. randomBytes generates cryptographically secure random values.

package/src/sip.ts

@@ -969,6 +969,133 @@ export class SIP {
       fulfilledAt: Math.floor(Date.now() / 1000),
     }
   }
+
+  // ─── Same-Chain Privacy ───────────────────────────────────────────────────
+
+  /**
+   * Execute a same-chain private transfer
+   *
+   * Bypasses cross-chain settlement for direct on-chain privacy transfers.
+   * Currently supports Solana only.
+   *
+   * @param chain - Chain to execute on (must be 'solana')
+   * @param params - Transfer parameters
+   * @returns Transfer result with stealth address
+   *
+   * @example
+   * ```typescript
+   * const result = await sip.executeSameChain('solana', {
+   *   recipientMetaAddress: {
+   *     chain: 'solana',
+   *     spendingKey: '0x...',
+   *     viewingKey: '0x...',
+   *   },
+   *   amount: 5_000_000n,  // 5 USDC
+   *   token: 'USDC',
+   *   connection,
+   *   sender: wallet.publicKey,
+   *   signTransaction: wallet.signTransaction,
+   * })
+   *
+   * console.log('Sent to stealth:', result.stealthAddress)
+   * ```
+   */
+  async executeSameChain(
+    chain: ChainId,
+    params: SameChainExecuteParams
+  ): Promise<SameChainExecuteResult> {
+    // Validate chain support
+    if (chain !== 'solana') {
+      throw new ValidationError(
+        `Same-chain privacy only supported for 'solana', got '${chain}'`,
+        'chain'
+      )
+    }
+
+    // Import Solana execution dynamically to avoid bundling issues
+    const { sendPrivateSPLTransfer } = await import('./chains/solana')
+    const { PublicKey: SolanaPublicKey } = await import('@solana/web3.js')
+    const { getAssociatedTokenAddress } = await import('@solana/spl-token')
+    const { SOLANA_TOKEN_MINTS } = await import('./chains/solana/constants')
+
+    // Resolve token mint
+    let mint: InstanceType<typeof SolanaPublicKey>
+    if (params.token in SOLANA_TOKEN_MINTS) {
+      mint = new SolanaPublicKey(SOLANA_TOKEN_MINTS[params.token as keyof typeof SOLANA_TOKEN_MINTS])
+    } else {
+      // Assume it's a mint address
+      mint = new SolanaPublicKey(params.token)
+    }
+
+    // Get sender's token account
+    const senderTokenAccount = await getAssociatedTokenAddress(
+      mint,
+      params.sender
+    )
+
+    // Execute private transfer
+    const result = await sendPrivateSPLTransfer({
+      connection: params.connection,
+      sender: params.sender,
+      senderTokenAccount,
+      recipientMetaAddress: params.recipientMetaAddress,
+      mint,
+      amount: params.amount,
+      signTransaction: params.signTransaction,
+    })
+
+    return {
+      txHash: result.txSignature,
+      stealthAddress: result.stealthAddress,
+      ephemeralPublicKey: result.ephemeralPublicKey,
+      viewTag: result.viewTag,
+      explorerUrl: result.explorerUrl,
+      chain: 'solana',
+    }
+  }
+
+  /**
+   * Check if same-chain privacy is supported for a chain
+   */
+  isSameChainSupported(chain: ChainId): boolean {
+    return chain === 'solana'
+  }
+}
+
+/**
+ * Parameters for same-chain private transfer execution
+ */
+export interface SameChainExecuteParams {
+  /** Recipient's stealth meta-address */
+  recipientMetaAddress: StealthMetaAddress
+  /** Amount to transfer (in token's smallest unit) */
+  amount: bigint
+  /** Token symbol (e.g., 'USDC') or mint address */
+  token: string
+  /** Solana RPC connection */
+  connection: import('@solana/web3.js').Connection
+  /** Sender's public key */
+  sender: import('@solana/web3.js').PublicKey
+  /** Transaction signer */
+  signTransaction: <T extends import('@solana/web3.js').Transaction | import('@solana/web3.js').VersionedTransaction>(tx: T) => Promise<T>
+}
+
+/**
+ * Result of same-chain private transfer
+ */
+export interface SameChainExecuteResult {
+  /** Transaction hash */
+  txHash: string
+  /** Stealth address that received the funds */
+  stealthAddress: string
+  /** Ephemeral public key for recipient scanning */
+  ephemeralPublicKey: string
+  /** View tag for efficient scanning */
+  viewTag: string
+  /** Explorer URL */
+  explorerUrl: string
+  /** Chain the transfer was executed on */
+  chain: ChainId
 }
 
 /**

package/src/stealth.ts

@@ -113,7 +113,12 @@ export function generateStealthMetaAddress(
     )
   }
 
-  // Generate random private keys
+  // Dispatch to curve-specific implementation
+  if (isEd25519Chain(chain)) {
+    return generateEd25519StealthMetaAddress(chain, label)
+  }
+
+  // secp256k1 implementation for EVM chains
   const spendingPrivateKey = randomBytes(32)
   const viewingPrivateKey = randomBytes(32)
 
@@ -269,7 +274,12 @@ export function generateStealthAddress(
   // Validate input
   validateStealthMetaAddress(recipientMetaAddress)
 
-  // Generate ephemeral keypair
+  // Dispatch to curve-specific implementation based on chain
+  if (isEd25519Chain(recipientMetaAddress.chain)) {
+    return generateEd25519StealthAddress(recipientMetaAddress)
+  }
+
+  // secp256k1 implementation for EVM chains
   const ephemeralPrivateKey = randomBytes(32)
 
   try {