@sip-protocol/sdk 0.11.1 → 0.12.0

package/src/chains/solana/scan.ts

@@ -7,7 +7,6 @@
 import {
   PublicKey,
   Transaction,
-  Keypair,
 } from '@solana/web3.js'
 import {
   getAssociatedTokenAddress,
@@ -16,8 +15,6 @@ import {
 } from '@solana/spl-token'
 import {
   checkEd25519StealthAddress,
-  deriveEd25519StealthPrivateKey,
-  deriveEd25519StealthPrivateKeyV1,
   solanaAddressToEd25519PublicKey,
 } from '../../stealth'
 import type { StealthAddress, HexString } from '@sip-protocol/types'
@@ -38,8 +35,7 @@ import {
 } from './constants'
 import { getTokenSymbol, parseTokenTransferFromBalances } from './utils'
 import type { SolanaRPCProvider } from './providers/interface'
-import { hexToBytes } from '@noble/hashes/utils'
-import { ed25519 } from '@noble/curves/ed25519'
+import { deriveStealthSigner } from './stealth-signer'
 
 /**
  * Scan for incoming stealth payments
@@ -201,6 +197,7 @@ export async function scanForPayments(
               results.push({
                 stealthAddress: announcement.stealthAddress || '',
                 ephemeralPublicKey: announcement.ephemeralPublicKey,
+                version: announcement.version as '1' | '2',
                 amount,
                 mint: transferInfo.mint,
                 tokenSymbol,
@@ -276,54 +273,14 @@ export async function claimStealthPayment(
     )
   }
 
-  // Convert addresses to hex for SDK functions
-  const stealthAddressHex = solanaAddressToEd25519PublicKey(stealthAddress)
-  const ephemeralPubKeyHex = solanaAddressToEd25519PublicKey(ephemeralPublicKey)
-
-  // Construct stealth address object
-  const stealthAddressObj: StealthAddress = {
-    address: stealthAddressHex,
-    ephemeralPublicKey: ephemeralPubKeyHex,
-    viewTag: 0, // Not needed for derivation
-  }
-
-  // Derive stealth private key — route by announcement version:
-  // legacy SIP:1 (swapped scheme) vs canonical SIP:2 (EIP-5564).
-  const recovery = version === '1'
-    ? deriveEd25519StealthPrivateKeyV1(stealthAddressObj, spendingPrivateKey, viewingPrivateKey)
-    : deriveEd25519StealthPrivateKey(stealthAddressObj, spendingPrivateKey, viewingPrivateKey)
-
-  // Create Solana keypair from derived private key
-  // Note: ed25519 private keys in Solana are seeds, not raw scalars
-  // The SDK returns a scalar, so we need to handle this carefully
-  const stealthPrivKeyBytes = hexToBytes(recovery.privateKey.slice(2))
-
-  // Validate that the derived private key (scalar) produces the expected public key
-  // Note: SIP derives a scalar, not a seed. We use scalar multiplication to verify.
+  const stealthSigner = deriveStealthSigner({
+    stealthAddress,
+    ephemeralPublicKey,
+    viewingPrivateKey,
+    spendingPrivateKey,
+    version,
+  })
   const stealthPubkey = new PublicKey(stealthAddress)
-  const expectedPubKeyBytes = stealthPubkey.toBytes()
-
-  // Convert scalar bytes to bigint (little-endian for ed25519)
-  const scalarBigInt = bytesToBigIntLE(stealthPrivKeyBytes)
-  const ED25519_ORDER = 2n ** 252n + 27742317777372353535851937790883648493n
-  let validScalar = scalarBigInt % ED25519_ORDER
-  if (validScalar === 0n) validScalar = 1n
-
-  // Derive public key via scalar multiplication
-  const derivedPubKeyBytes = ed25519.ExtendedPoint.BASE.multiply(validScalar).toRawBytes()
-
-  if (!derivedPubKeyBytes.every((b, i) => b === expectedPubKeyBytes[i])) {
-    throw new Error(
-      'Stealth key derivation failed: derived private key does not produce expected public key. ' +
-      'This may indicate incorrect spending/viewing keys or corrupted announcement data.'
-    )
-  }
-
-  // Solana keypairs expect 64 bytes (32 byte seed + 32 byte public key)
-  // We construct this from the derived scalar (now validated)
-  const stealthKeypair = Keypair.fromSecretKey(
-    new Uint8Array([...stealthPrivKeyBytes, ...expectedPubKeyBytes])
-  )
 
   // Get token accounts
   const stealthATA = await getAssociatedTokenAddress(
@@ -360,8 +317,8 @@ export async function claimStealthPayment(
   transaction.lastValidBlockHeight = lastValidBlockHeight
   transaction.feePayer = stealthPubkey // Stealth address pays fee
 
-  // Sign with stealth keypair
-  transaction.sign(stealthKeypair)
+  // Sign with stealth scalar signer (Keypair cannot sign a raw-scalar stealth address)
+  stealthSigner.signTransaction(transaction)
 
   // Send transaction
   const txSignature = await connection.sendRawTransaction(
@@ -462,19 +419,3 @@ function detectCluster(endpoint: string): SolanaCluster {
   return 'mainnet-beta'
 }
 
-/**
- * Convert bytes to bigint in little-endian format
- *
- * Used for ed25519 scalar conversion where bytes are in little-endian order.
- *
- * @param bytes - Byte array to convert
- * @returns BigInt representation of the bytes
- * @internal
- */
-function bytesToBigIntLE(bytes: Uint8Array): bigint {
-  let result = 0n
-  for (let i = bytes.length - 1; i >= 0; i--) {
-    result = (result << 8n) | BigInt(bytes[i])
-  }
-  return result
-}

package/src/chains/solana/stealth-scanner.ts

@@ -115,6 +115,13 @@ export interface DetectedPayment {
    */
   ephemeralPublicKey: string
 
+  /**
+   * Announcement scheme version ('1' legacy | '2' canonical).
+   * Pass to the claim path so it routes to the matching derivation.
+   * Optional for back-compat with payments detected before version threading.
+   */
+  version?: '1' | '2'
+
   /**
    * View tag for efficient scanning
    */
@@ -548,6 +555,7 @@ export class StealthScanner {
           return {
             stealthAddress: announcement.stealthAddress || '',
             ephemeralPublicKey: announcement.ephemeralPublicKey,
+            version: announcement.version as '1' | '2',
             viewTag: viewTagNumber,
             amount,
             mint: transferInfo.mint,

package/src/chains/solana/stealth-signer.ts

@@ -0,0 +1,145 @@
+/**
+ * Stealth address signing for Solana.
+ *
+ * SIP's ed25519 stealth derivation yields a RAW SCALAR (s = s_spend + H(S) mod L),
+ * not a standard ed25519 seed. Solana's `Keypair` (tweetnacl) signs by treating the
+ * first 32 bytes as a seed (SHA-512 + clamp), so it cannot sign for a stealth address
+ * whose private key is a raw scalar. This module signs directly with the scalar using
+ * RFC 8032 Ed25519 — producing signatures any standard verifier and the Solana runtime
+ * accept — and attaches them to a transaction via `Transaction.addSignature`.
+ */
+
+import { PublicKey, Transaction } from '@solana/web3.js'
+import { ed25519 } from '@noble/curves/ed25519'
+import { sha512 } from '@noble/hashes/sha512'
+import { hexToBytes } from '@noble/hashes/utils'
+import type { StealthAddress, HexString } from '@sip-protocol/types'
+import {
+  deriveEd25519StealthPrivateKey,
+  deriveEd25519StealthPrivateKeyV1,
+  solanaAddressToEd25519PublicKey,
+} from '../../stealth'
+import { bytesToBigIntLE, bigIntToBytesLE, ED25519_ORDER } from '../../stealth/utils'
+
+/** Reduce a bigint into [0, L). */
+function modL(value: bigint): bigint {
+  const reduced = value % ED25519_ORDER
+  return reduced >= 0n ? reduced : reduced + ED25519_ORDER
+}
+
+/**
+ * Produce an RFC 8032 Ed25519 signature from a raw little-endian scalar.
+ *
+ * Unlike `Keypair`/tweetnacl signing (which expects a 32-byte seed and re-derives the
+ * scalar via SHA-512 + clamp), this signs directly with the provided scalar `a` whose
+ * public key is `A = a·G`. The per-signature nonce is derived deterministically from a
+ * hash of the scalar and the message (RFC 8032 structure): unique per message, never
+ * reused across distinct messages.
+ *
+ * @param message - Exact bytes to sign (e.g. a compiled transaction message)
+ * @param scalar - 32-byte little-endian ed25519 scalar (the stealth private key)
+ * @returns 64-byte signature (R ‖ S)
+ * @throws If the scalar reduces to zero
+ */
+export function signEd25519WithScalar(message: Uint8Array, scalar: Uint8Array): Uint8Array {
+  const a = modL(bytesToBigIntLE(scalar))
+  if (a === 0n) {
+    throw new Error('Invalid stealth scalar: reduces to zero')
+  }
+  const A = ed25519.ExtendedPoint.BASE.multiply(a).toRawBytes()
+
+  const prefix = sha512(scalar).slice(32, 64)
+  const r = modL(bytesToBigIntLE(sha512(new Uint8Array([...prefix, ...message]))))
+  if (r === 0n) {
+    throw new Error('Invalid nonce: reduces to zero')
+  }
+  const R = ed25519.ExtendedPoint.BASE.multiply(r).toRawBytes()
+
+  const k = modL(bytesToBigIntLE(sha512(new Uint8Array([...R, ...A, ...message]))))
+  const S = modL(r + k * a)
+
+  return new Uint8Array([...R, ...bigIntToBytesLE(S, 32)])
+}
+
+/** Parameters needed to derive a stealth address's signer. */
+export interface DeriveStealthSignerParams {
+  /** Stealth address (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
+  /** Announcement scheme version: '2' canonical (default) | '1' legacy */
+  version?: '1' | '2'
+}
+
+/** Signs transactions/messages as a stealth address using its raw ed25519 scalar. */
+export interface StealthSigner {
+  /** The stealth address this signer controls */
+  readonly publicKey: PublicKey
+  /** Sign arbitrary bytes, returning a 64-byte ed25519 signature */
+  signMessage(message: Uint8Array): Uint8Array
+  /** Attach this stealth address's signature to a transaction. Call LAST — after feePayer, recentBlockhash, and all instructions are finalized (the signature covers the serialized message at call time). */
+  signTransaction(transaction: Transaction): void
+}
+
+/**
+ * Re-derive the signer that controls a stealth address.
+ *
+ * Routes derivation by announcement version (canonical SIP:2 vs legacy SIP:1) and
+ * validates the derived scalar reproduces the on-chain stealth public key before
+ * returning a signer. The signer signs with the raw scalar (see
+ * {@link signEd25519WithScalar}); it does NOT construct a `Keypair`, which cannot sign
+ * for a scalar-derived stealth address.
+ *
+ * @throws If the derived scalar does not produce the expected stealth public key
+ */
+export function deriveStealthSigner(params: DeriveStealthSignerParams): StealthSigner {
+  const {
+    stealthAddress,
+    ephemeralPublicKey,
+    viewingPrivateKey,
+    spendingPrivateKey,
+    version = '2',
+  } = params
+
+  const stealthAddressHex = solanaAddressToEd25519PublicKey(stealthAddress)
+  const ephemeralPubKeyHex = solanaAddressToEd25519PublicKey(ephemeralPublicKey)
+
+  const stealthAddressObj: StealthAddress = {
+    address: stealthAddressHex,
+    ephemeralPublicKey: ephemeralPubKeyHex,
+    viewTag: 0,
+  }
+
+  const recovery = version === '1'
+    ? deriveEd25519StealthPrivateKeyV1(stealthAddressObj, spendingPrivateKey, viewingPrivateKey)
+    : deriveEd25519StealthPrivateKey(stealthAddressObj, spendingPrivateKey, viewingPrivateKey)
+
+  const scalar = hexToBytes(recovery.privateKey.slice(2))
+
+  const publicKey = new PublicKey(stealthAddress)
+  const expectedPubKeyBytes = publicKey.toBytes()
+  const derivedPubKeyBytes = ed25519.ExtendedPoint.BASE.multiply(modL(bytesToBigIntLE(scalar))).toRawBytes()
+
+  if (!derivedPubKeyBytes.every((b, i) => b === expectedPubKeyBytes[i])) {
+    throw new Error(
+      'Stealth key derivation failed: derived scalar does not produce expected public key. ' +
+      'This may indicate incorrect spending/viewing keys or corrupted announcement data.'
+    )
+  }
+
+  return {
+    publicKey,
+    signMessage(message: Uint8Array): Uint8Array {
+      return signEd25519WithScalar(message, scalar)
+    },
+    signTransaction(transaction: Transaction): void {
+      const message = transaction.serializeMessage()
+      const signature = signEd25519WithScalar(message, scalar)
+      transaction.addSignature(publicKey, Buffer.from(signature))
+    },
+  }
+}

package/src/chains/solana/types.ts

@@ -99,6 +99,8 @@ export interface SolanaScanResult {
   stealthAddress: string
   /** Ephemeral public key from the sender (base58) */
   ephemeralPublicKey: string
+  /** Announcement scheme version ('1' legacy | '2' canonical) — pass to claim */
+  version: '1' | '2'
   /** Amount received (in token's smallest unit) */
   amount: bigint
   /** Token mint address */

package/src/index.ts

@@ -1036,6 +1036,12 @@ export {
   // Helius Enhanced Transactions (Human-readable TX data)
   HeliusEnhanced,
   createHeliusEnhanced,
+  // Gasless Cash-Out (relayer fee-payer for stealth recipients)
+  buildGaslessCashout,
+  submitGaslessCashout,
+  computeRelayerFee,
+  signEd25519WithScalar,
+  deriveStealthSigner,
 } from './chains/solana'
 
 // Solana Noir Verification (Aztec/Noir bounty)
@@ -1132,6 +1138,14 @@ export type {
   SIPTransactionMetadata,
   SIPEnhancedTransaction,
   TransactionSummary,
+  // Gasless Cash-Out types (relayer fee-payer for stealth recipients)
+  GaslessCashoutParams,
+  GaslessCashoutBuild,
+  SubmitGaslessCashoutParams,
+  GaslessCashoutResult,
+  RelayerFeeConfig,
+  StealthSigner,
+  DeriveStealthSignerParams,
 } from './chains/solana'
 
 // NEAR Same-Chain Privacy (M17-NEAR)

package/src/proofs/parallel/concurrency.ts

@@ -47,7 +47,7 @@ function getCpuCores(): number {
   }
   // Node.js
   try {
-    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
     const os = require('os')
     return os.cpus().length
   } catch {
@@ -73,7 +73,7 @@ function getMemoryInfo(): { total: number; available: number } {
   }
   // Node.js
   try {
-    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
     const os = require('os')
     return {
       total: os.totalmem(),

package/src/solana/jito-relayer.ts

@@ -44,10 +44,10 @@ import {
   VersionedTransaction,
   Transaction,
   SystemProgram,
-  type Keypair,
+  Keypair,
   type TransactionInstruction,
 } from '@solana/web3.js'
-import { bytesToHex } from '@noble/hashes/utils'
+import bs58 from 'bs58'
 
 // ─── Constants ────────────────────────────────────────────────────────────────
 
@@ -156,6 +156,8 @@ export interface RelayedTransactionRequest {
   transaction: Transaction | VersionedTransaction
   /** Tip amount in lamports (paid by relayer, recovered from user) */
   tipLamports?: number
+  /** Keypair that pays the Jito tip. Required for the Jito-bundle path to land. */
+  tipPayer?: Keypair
   /** Whether to wait for confirmation */
   waitForConfirmation?: boolean
 }
@@ -233,10 +235,11 @@ export class JitoRelayerError extends Error {
  *   blockEngineUrl: 'https://ny.mainnet.block-engine.jito.wtf/api/v1',
  * })
  *
- * // Submit a signed transaction via relayer
+ * // Submit a signed transaction via the relayer (tipPayer is required for the bundle to land)
  * const result = await relayer.relayTransaction({
  *   transaction: signedTx,
  *   tipLamports: 10_000, // 0.00001 SOL tip
+ *   tipPayer: relayerKeypair,
  * })
  *
  * console.log('Transaction relayed:', result.signature)
@@ -262,6 +265,13 @@ export class JitoRelayer {
     this.submissionTimeout = config.submissionTimeout ?? JITO_DEFAULTS.submissionTimeout
   }
 
+  // ─── Static Helpers ─────────────────────────────────────────────────────────
+
+  /** Encode a 64-byte ed25519 signature as a base58 string (Solana canonical form). */
+  static encodeSignature(sig: Uint8Array): string {
+    return bs58.encode(sig)
+  }
+
   // ─── Public Methods ─────────────────────────────────────────────────────────
 
   /**
@@ -331,10 +341,10 @@ export class JitoRelayer {
     // Extract signatures
     const signatures = bundleTransactions.map(tx => {
       if (tx instanceof VersionedTransaction) {
-        return bytesToHex(tx.signatures[0])
-      } else {
-        return tx.signature?.toString() ?? ''
+        return JitoRelayer.encodeSignature(tx.signatures[0])
       }
+      const sig = tx.signature
+      return sig ? JitoRelayer.encodeSignature(sig) : ''
     })
 
     // Wait for confirmation if requested
@@ -373,6 +383,27 @@ export class JitoRelayer {
     this.log('Relaying transaction')
 
     try {
+      // Jito bundles require a tip to land. If a tipPayer is supplied, use the
+      // bundle path (which prepends a tip tx); otherwise fall through to the
+      // existing single-tx submission.
+      if (request.tipPayer) {
+        const bundle = await this.submitBundle({
+          transactions: [request.transaction],
+          tipLamports: request.tipLamports,
+          tipPayer: request.tipPayer,
+          waitForConfirmation: request.waitForConfirmation,
+        })
+        return {
+          signature: bundle.signatures[bundle.signatures.length - 1] ?? '',
+          bundleId: bundle.bundleId,
+          status: bundle.status === 'landed' ? 'confirmed'
+            : bundle.status === 'submitted' ? 'submitted' : 'failed',
+          slot: bundle.slot,
+          error: bundle.error,
+          relayed: true,
+        }
+      }
+
       // For single transaction relay, we need to handle it differently
       // The transaction should already be signed by the user
       // We add it to a bundle with a tip transaction
@@ -385,9 +416,10 @@ export class JitoRelayer {
       // Get signature
       let signature: string
       if (request.transaction instanceof VersionedTransaction) {
-        signature = bytesToHex(request.transaction.signatures[0])
+        signature = JitoRelayer.encodeSignature(request.transaction.signatures[0])
       } else {
-        signature = request.transaction.signature?.toString() ?? ''
+        const sig = request.transaction.signature
+        signature = sig ? JitoRelayer.encodeSignature(sig) : ''
       }
 
       // Wait for confirmation if requested

package/src/wallet/solana/privacy-adapter.ts

@@ -23,6 +23,20 @@ import {
   checkEd25519StealthAddress,
   ed25519PublicKeyToSolanaAddress,
 } from '../../stealth'
+// Imported from the source module (not the barrel) to avoid a circular-import
+// cycle that leaves the barrel re-export undefined at call time — matching the
+// pattern in chains/solana/stealth-signer.ts and chains/ethereum/stealth.ts.
+// Using the canonical primitives here (rather than local copies) guarantees the
+// stealth address this adapter reconstructs is byte-for-byte consistent with the
+// key deriveEd25519StealthPrivateKey returns — they must share the SAME
+// bytesToBigInt (big-endian) and curve order.
+import {
+  getEd25519Scalar,
+  bytesToBigInt,
+  bytesToHex,
+  hexToBytes,
+  ED25519_ORDER,
+} from '../../stealth/utils'
 
 // ─── Types ──────────────────────────────────────────────────────────────────
 
@@ -87,7 +101,12 @@ export interface ScannedPayment {
  * Result of claiming a stealth payment
  */
 export interface ClaimResult {
-  /** Derived private key for spending */
+  /**
+   * Derived spending key — a RAW ed25519 scalar (hex), NOT a 32-byte Keypair seed.
+   * Do NOT pass to `new Keypair(...)` / `Keypair.fromSecretKey(...)` — it produces
+   * INVALID signatures. Sign with `signEd25519WithScalar` (or `deriveStealthSigner`)
+   * from `@sip-protocol/sdk` instead.
+   */
   privateKey: HexString
   /** Public key (stealth address) */
   publicKey: HexString
@@ -134,7 +153,8 @@ export interface ClaimResult {
  * const payments = wallet.scanPayments([announcement1, announcement2])
  * for (const payment of payments.filter(p => p.isOwned)) {
  *   const claim = wallet.deriveClaimKey(payment.ephemeralPublicKey, payment.viewTag)
- *   // Use claim.privateKey to sign transactions
+ *   // claim.privateKey is a RAW scalar — sign via signEd25519WithScalar, NOT a Keypair:
+ *   const sig = signEd25519WithScalar(message, hexToBytes(claim.privateKey.slice(2)))
  * }
  * ```
  */
@@ -358,10 +378,13 @@ export class PrivacySolanaWalletAdapter extends SolanaWalletAdapter {
     // Compute stealth address from ephemeral key
     const ephemeralPubBytes = hexToBytes(ephemeralPublicKey.slice(2))
 
-    // Compute shared secret: S = viewing_scalar * R (canonical EIP-5564)
-    const viewingScalar = getEd25519ScalarFromPrivate(
-      hexToBytes(this.stealthKeys.viewingPrivateKey.slice(2))
-    )
+    // Compute shared secret: S = viewing_scalar * R (canonical EIP-5564).
+    // Must use the canonical ed25519 scalar (SHA-512 + little-endian +
+    // reduction mod L) so the address this reconstructs matches the key
+    // deriveEd25519StealthPrivateKey returns below.
+    const viewingScalar =
+      getEd25519Scalar(hexToBytes(this.stealthKeys.viewingPrivateKey.slice(2))) %
+      ED25519_ORDER
 
     const ephemeralPoint = ed25519.ExtendedPoint.fromHex(ephemeralPubBytes)
     const sharedSecretPoint = ephemeralPoint.multiply(viewingScalar)
@@ -478,66 +501,6 @@ export class PrivacySolanaWalletAdapter extends SolanaWalletAdapter {
   }
 }
 
-// ─── Utilities ──────────────────────────────────────────────────────────────
-
-/** ed25519 curve order */
-const ED25519_ORDER = BigInt('0x1000000000000000000000000000000014def9dea2f79cd65812631a5cf5d3ed')
-
-/**
- * Convert bytes to BigInt (little-endian)
- */
-function bytesToBigInt(bytes: Uint8Array): bigint {
-  let result = 0n
-  for (let i = bytes.length - 1; i >= 0; i--) {
-    result = (result << 8n) | BigInt(bytes[i])
-  }
-  return result
-}
-
-/**
- * Convert hex string to bytes
- */
-function hexToBytes(hex: string): Uint8Array {
-  const bytes = new Uint8Array(hex.length / 2)
-  for (let i = 0; i < hex.length; i += 2) {
-    bytes[i / 2] = parseInt(hex.substring(i, i + 2), 16)
-  }
-  return bytes
-}
-
-/**
- * Convert bytes to hex string
- */
-function bytesToHex(bytes: Uint8Array): string {
-  return Array.from(bytes)
-    .map(b => b.toString(16).padStart(2, '0'))
-    .join('')
-}
-
-/**
- * Get ed25519 scalar from private key seed
- *
- * ed25519 derives the actual scalar by hashing the seed and taking
- * the lower 32 bytes with specific bit manipulations.
- */
-function getEd25519ScalarFromPrivate(seed: Uint8Array): bigint {
-  // Hash the seed to get 64 bytes
-  const h = sha256(seed)
-
-  // Take lower 32 bytes and apply ed25519 clamping
-  const scalar = new Uint8Array(32)
-  for (let i = 0; i < 32; i++) {
-    scalar[i] = h[i]
-  }
-
-  // Clamp: clear low 3 bits, clear high bit, set second-high bit
-  scalar[0] &= 248
-  scalar[31] &= 127
-  scalar[31] |= 64
-
-  return bytesToBigInt(scalar)
-}
-
 // ─── Factory ────────────────────────────────────────────────────────────────
 
 /**