@sip-protocol/sdk 0.11.0 → 0.12.0

package/dist/index.mjs

@@ -448,7 +448,7 @@ import {
   verifyOracleSignature,
   verifyOwnership,
   walletRegistry
-} from "./chunk-L4RKPNIJ.mjs";
+} from "./chunk-4EHEBTKP.mjs";
 import {
   DEFAULT_NETWORK_CONFIG,
   DEFAULT_PROXY_TIMEOUT,
@@ -462,6 +462,7 @@ import {
   TOR_PORTS,
   addBlindings,
   addCommitments,
+  buildGaslessCashout,
   checkEd25519StealthAddress,
   checkEd25519StealthAddressV1,
   checkProxyAvailability,
@@ -470,6 +471,7 @@ import {
   claimStealthPayment,
   commit,
   commitZero,
+  computeRelayerFee,
   createAnnouncementMemo,
   createHeliusEnhanced,
   createNetworkPrivacyClient,
@@ -483,6 +485,7 @@ import {
   deriveSecp256k1StealthPrivateKeyV1,
   deriveStealthPrivateKey,
   deriveStealthPrivateKeyV1,
+  deriveStealthSigner,
   detectTorPort,
   ed25519PublicKeyToNearAddress,
   ed25519PublicKeyToSolanaAddress,
@@ -526,7 +529,9 @@ import {
   secureWipe,
   secureWipeAll,
   sendPrivateSPLTransfer,
+  signEd25519WithScalar,
   solanaAddressToEd25519PublicKey,
+  submitGaslessCashout,
   subtractBlindings,
   subtractCommitments,
   validateAsset,
@@ -540,7 +545,7 @@ import {
   verifyWebhookSignature,
   withSecureBuffer,
   withSecureBufferSync
-} from "./chunk-7IUKXWDN.mjs";
+} from "./chunk-MKTCJPFH.mjs";
 import {
   Halo2Provider,
   KimchiProvider,
@@ -574,6 +579,8 @@ import {
   ETH_RPC_ENDPOINTS,
   MEMO_PROGRAM_ID,
   SIP_MEMO_PREFIX,
+  SIP_MEMO_PREFIX_ANY,
+  SIP_MEMO_PREFIX_V2,
   SOLANA_EXPLORER_URLS,
   SOLANA_RPC_ENDPOINTS,
   SOLANA_RPC_ENDPOINTS2,
@@ -585,7 +592,7 @@ import {
   getSolanaTokenDecimals,
   getTokenMint
 } from "./chunk-KXETSSKP.mjs";
-import "./chunk-XGB3TDIC.mjs";
+import "./chunk-S3F4CPQ5.mjs";
 export {
   ATTESTATION_VERSION,
   AptosStealthService,
@@ -741,6 +748,8 @@ export {
   SIPError,
   SIPNativeBackend,
   SIP_MEMO_PREFIX,
+  SIP_MEMO_PREFIX_ANY,
+  SIP_MEMO_PREFIX_V2,
   SIP_VERSION,
   SOLANA_EXPLORER_URLS,
   SOLANA_RPC_ENDPOINTS2 as SOLANA_RPC_ENDPOINTS,
@@ -800,6 +809,7 @@ export {
   bpsToPercent,
   bytesToHex as browserBytesToHex,
   hexToBytes as browserHexToBytes,
+  buildGaslessCashout,
   cacheKeyGenerator,
   calculateFeeForSwap,
   calculatePrivacyScore,
@@ -821,6 +831,7 @@ export {
   computeAttestationHash,
   computeNEARViewingKeyHash,
   computeNEARViewingKeyHashFromPrivate,
+  computeRelayerFee,
   computeTweakedKey,
   configureLogger,
   convertFromSIP,
@@ -924,6 +935,7 @@ export {
   deriveSecp256k1StealthPrivateKeyV1,
   deriveStealthPrivateKey,
   deriveStealthPrivateKeyV1,
+  deriveStealthSigner,
   deriveSuiStealthPrivateKey,
   deriveTraditionalNullifier,
   deriveViewingKey,
@@ -1115,11 +1127,13 @@ export {
   serializePayment,
   setLogLevel,
   signAttestationMessage,
+  signEd25519WithScalar,
   silenceLogger,
   solanaAddressToEd25519PublicKey,
   optimizations_exports as solanaOptimizations,
   solanaPublicKeyToHex,
   stealthKeyToCosmosAddress,
+  submitGaslessCashout,
   subtractBlindings,
   subtractBlindingsNEAR,
   subtractCommitments,

package/dist/proofs/halo2.mjs

@@ -3,7 +3,7 @@ import {
   createHalo2Provider,
   createOrchardProvider
 } from "../chunk-5D7A3L3W.mjs";
-import "../chunk-XGB3TDIC.mjs";
+import "../chunk-S3F4CPQ5.mjs";
 export {
   Halo2Provider,
   createHalo2Provider,

package/dist/proofs/kimchi.mjs

@@ -4,7 +4,7 @@ import {
   createMinaMainnetProvider,
   createZkAppProvider
 } from "../chunk-5D7A3L3W.mjs";
-import "../chunk-XGB3TDIC.mjs";
+import "../chunk-S3F4CPQ5.mjs";
 export {
   KimchiProvider,
   createKimchiProvider,

package/dist/proofs/noir.mjs

@@ -13,7 +13,7 @@ import {
 import {
   ProofError
 } from "../chunk-Z3K7W5S3.mjs";
-import "../chunk-XGB3TDIC.mjs";
+import "../chunk-S3F4CPQ5.mjs";
 
 // src/proofs/noir.ts
 import { Noir } from "@noir-lang/noir_js";

package/dist/{solana-7QOA3HBZ.mjs → solana-VKZI66MK.mjs}

@@ -32,10 +32,12 @@ import {
   batchGetTokenBalances,
   batchResolveTokenMetadata,
   batchScanForRecipients,
+  buildGaslessCashout,
   calculatePriorityFee,
   claimStealthPayment,
   commitSPLToken,
   commitSolana,
+  computeRelayerFee,
   computeViewingKeyHash,
   computeViewingKeyHashFromPrivate,
   createAddress,
@@ -56,6 +58,7 @@ import {
   decryptWithViewing,
   deriveChildViewingKey,
   deriveSolanaStealthKeys,
+  deriveStealthSigner,
   deriveViewingKeyFromSpending,
   disposeEphemeralKeypairs,
   encryptForViewing,
@@ -102,7 +105,9 @@ import {
   sendPrivateSPLTransfer,
   sendSOLTransfer,
   shieldedTransfer,
+  signEd25519WithScalar,
   solToLamports,
+  submitGaslessCashout,
   subtractBlindingsSolana,
   subtractCommitmentsSolana,
   toAddress,
@@ -122,7 +127,7 @@ import {
   verifySPLTokenCommitment,
   verifyWebhookSignature,
   wipeEphemeralPrivateKey
-} from "./chunk-7IUKXWDN.mjs";
+} from "./chunk-MKTCJPFH.mjs";
 import "./chunk-Z3K7W5S3.mjs";
 import {
   ATA_RENT_LAMPORTS,
@@ -139,7 +144,7 @@ import {
   getSolanaTokenDecimals,
   getTokenMint
 } from "./chunk-KXETSSKP.mjs";
-import "./chunk-XGB3TDIC.mjs";
+import "./chunk-S3F4CPQ5.mjs";
 export {
   ATA_RENT_LAMPORTS,
   CONFIG_PDA,
@@ -184,10 +189,12 @@ export {
   batchGetTokenBalances,
   batchResolveTokenMetadata,
   batchScanForRecipients,
+  buildGaslessCashout,
   calculatePriorityFee,
   claimStealthPayment,
   commitSPLToken,
   commitSolana,
+  computeRelayerFee,
   computeViewingKeyHash,
   computeViewingKeyHashFromPrivate,
   createAddress,
@@ -208,6 +215,7 @@ export {
   decryptWithViewing,
   deriveChildViewingKey,
   deriveSolanaStealthKeys,
+  deriveStealthSigner,
   deriveViewingKeyFromSpending,
   disposeEphemeralKeypairs,
   encryptForViewing,
@@ -257,7 +265,9 @@ export {
   sendPrivateSPLTransfer,
   sendSOLTransfer,
   shieldedTransfer,
+  signEd25519WithScalar,
   solToLamports,
+  submitGaslessCashout,
   subtractBlindingsSolana,
   subtractCommitmentsSolana,
   toAddress,

package/dist/{validity_proof-3POXLPNY.mjs → validity_proof-2GVV6GA6.mjs}

@@ -8,7 +8,7 @@ import {
   noir_version,
   validity_proof_default
 } from "./chunk-I534WKN7.mjs";
-import "./chunk-XGB3TDIC.mjs";
+import "./chunk-S3F4CPQ5.mjs";
 export {
   abi,
   bytecode,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sip-protocol/sdk",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Core SDK for Shielded Intents Protocol - Privacy layer for cross-chain transactions",
   "author": "SIP Protocol <hello@sip-protocol.org>",
   "homepage": "https://sip-protocol.org",
@@ -56,12 +56,12 @@
     "@jup-ag/api": "^6.0.48",
     "@langchain/core": "^0.3.30",
     "@langchain/openai": "^0.4.2",
-    "@magicblock-labs/ephemeral-rollups-sdk": "^0.14.4",
+    "@magicblock-labs/ephemeral-rollups-sdk": "^0.15.0",
     "@noble/ciphers": "^2.2.0",
     "@noble/curves": "^1.3.0",
     "@noble/hashes": "^1.3.3",
     "@noir-lang/noir_js": "1.0.0-beta.18",
-    "@noir-lang/types": "1.0.0-beta.18",
+    "@noir-lang/types": "1.0.0-beta.22",
     "@radr/shadowwire": "^1.1.15",
     "@scure/base": "^2.2.0",
     "@scure/bip32": "^2.2.0",
@@ -74,19 +74,20 @@
     "@solana/spl-token": "^0.4.14",
     "@solana/web3.js": "^1.98.4",
     "@triton-one/yellowstone-grpc": "^4.0.2",
+    "bs58": "^6.0.0",
     "langchain": "^1.4.4",
     "pino": "^10.3.1",
     "zod": "^4.4.3"
   },
   "devDependencies": {
     "@grpc/grpc-js": "^1.14.4",
-    "@types/node": "^25.9.1",
+    "@types/node": "^25.9.2",
     "@vitest/coverage-v8": "^4.1.0",
     "fast-check": "^4.8.0",
     "https-proxy-agent": "^7.0.0",
     "socks-proxy-agent": "^8.0.0",
     "tsup": "^8.0.0",
-    "typescript": "^5.3.0",
+    "typescript": "^6.0.3",
     "vitest": "^4.1.0"
   },
   "keywords": [

package/src/chains/solana/gasless-cashout.ts

@@ -0,0 +1,331 @@
+/**
+ * Gasless cash-out for stealth recipients.
+ *
+ * A stealth address that received SPL tokens typically holds ZERO SOL, so it cannot
+ * pay a transaction fee to move those tokens out. Here a relayer is the fee-payer; the
+ * stealth address signs only the token transfers (via its raw ed25519 scalar — see
+ * deriveStealthSigner). The relayer recovers its SOL cost as an SPL fee deducted from
+ * the tokens being moved (fee-from-claim). Direct submission is the primary path; a
+ * Jito bundle is an optional mainnet hardening layer (see submitGaslessCashout).
+ */
+
+import {
+  Connection,
+  PublicKey,
+  Transaction,
+  Keypair,
+} from '@solana/web3.js'
+import {
+  getAssociatedTokenAddress,
+  createTransferInstruction,
+  createAssociatedTokenAccountIdempotentInstruction,
+  getAccount,
+} from '@solana/spl-token'
+import type { HexString } from '@sip-protocol/types'
+import { deriveStealthSigner } from './stealth-signer'
+import { computeRelayerFee, type RelayerFeeConfig } from './relayer-fee'
+import { getExplorerUrl, type SolanaCluster } from './constants'
+import type { JitoRelayer } from '../../solana/jito-relayer'
+
+/** Parameters for building a gasless cash-out transaction. */
+export interface GaslessCashoutParams {
+  /** Solana RPC connection */
+  connection: Connection
+  /** Stealth address holding the tokens (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
+  /** Final destination address (base58) */
+  destinationAddress: string
+  /** SPL token mint */
+  mint: PublicKey
+  /** Relayer public key — the transaction fee-payer (must hold SOL) */
+  relayerPublicKey: PublicKey
+  /** Relayer's token account that receives the fee (ATA for `mint`) */
+  relayerFeeAccount: PublicKey
+  /** Fee model */
+  feeConfig: RelayerFeeConfig
+  /** Announcement scheme version: '2' canonical (default) | '1' legacy */
+  version?: '1' | '2'
+}
+
+/** A stealth-signed gasless cash-out transaction, awaiting the relayer's fee-payer signature. */
+export interface GaslessCashoutBuild {
+  /** Transaction signed by the stealth address; feePayer = relayer (relayer must still sign) */
+  transaction: Transaction
+  /** Stealth address (base58) */
+  stealthAddress: string
+  /** Final destination (base58) */
+  destinationAddress: string
+  /** Gross amount in the stealth token account (base units) */
+  grossAmount: bigint
+  /** Relayer fee deducted (base units) */
+  relayerFee: bigint
+  /** Net amount forwarded to the destination (base units) */
+  netAmount: bigint
+  /** Blockhash the transaction is bound to */
+  blockhash: string
+  /** Last valid block height for confirmation */
+  lastValidBlockHeight: number
+}
+
+/**
+ * Build a gasless cash-out transaction.
+ *
+ * Derives the stealth signer from the recipient's keys, computes the fee-from-claim,
+ * assembles a two- (or three-) instruction transaction with the relayer as fee-payer,
+ * and pre-signs with the stealth scalar. The relayer must add its own signature before
+ * broadcasting.
+ *
+ * @throws If the relayer fee >= the gross claim amount (nothing left for the recipient)
+ */
+export async function buildGaslessCashout(
+  params: GaslessCashoutParams
+): Promise<GaslessCashoutBuild> {
+  const {
+    connection,
+    stealthAddress,
+    ephemeralPublicKey,
+    viewingPrivateKey,
+    spendingPrivateKey,
+    destinationAddress,
+    mint,
+    relayerPublicKey,
+    relayerFeeAccount,
+    feeConfig,
+    version = '2',
+  } = params
+
+  const stealthSigner = deriveStealthSigner({
+    stealthAddress,
+    ephemeralPublicKey,
+    viewingPrivateKey,
+    spendingPrivateKey,
+    version,
+  })
+  const stealthPubkey = stealthSigner.publicKey
+
+  const stealthATA = await getAssociatedTokenAddress(mint, stealthPubkey, true)
+  const destinationPubkey = new PublicKey(destinationAddress)
+  const destinationATA = await getAssociatedTokenAddress(mint, destinationPubkey)
+
+  if (destinationATA.equals(stealthATA)) {
+    throw new Error(
+      'destinationAddress resolves to the stealth token account; choose a different destination'
+    )
+  }
+
+  // Validate the relayer fee account is a token account for `mint` — otherwise the fee
+  // transfer would fail (mint mismatch) or the fee would be unrecoverable.
+  let feeAccount
+  try {
+    feeAccount = await getAccount(connection, relayerFeeAccount)
+  } catch {
+    throw new Error('relayerFeeAccount does not exist or is not a token account')
+  }
+  if (!feeAccount.mint.equals(mint)) {
+    throw new Error('relayerFeeAccount is not an associated token account for the given mint')
+  }
+
+  // Gross balance held by the stealth ATA
+  let balanceResp
+  try {
+    balanceResp = await connection.getTokenAccountBalance(stealthATA)
+  } catch {
+    throw new Error(
+      `Stealth token account ${stealthATA.toBase58()} for mint ${mint.toBase58()} does not exist or holds no balance; nothing to cash out`
+    )
+  }
+  const grossAmount = BigInt(balanceResp.value.amount)
+
+  const relayerFee = computeRelayerFee(grossAmount, feeConfig)
+  if (relayerFee >= grossAmount) {
+    throw new Error(
+      `Relayer fee (${relayerFee}) equals or exceeds the claim amount (${grossAmount}); nothing left to forward`
+    )
+  }
+  const netAmount = grossAmount - relayerFee
+
+  const transaction = new Transaction()
+
+  // Idempotently create the destination ATA — relayer pays rent. Idempotent means a
+  // no-op if it already exists, so no separate existence read is needed (one fewer RPC,
+  // and no TOCTOU gap between the read and broadcast). The flat-floor fee is intended to
+  // cover this rent, but it is denominated in token base units (no price oracle in v1),
+  // so SOL-rent recovery is approximate, not guaranteed.
+  transaction.add(
+    createAssociatedTokenAccountIdempotentInstruction(
+      relayerPublicKey, // payer (relayer pays rent)
+      destinationATA,
+      destinationPubkey,
+      mint
+    )
+  )
+
+  // Fee: stealth -> relayer fee account
+  transaction.add(
+    createTransferInstruction(stealthATA, relayerFeeAccount, stealthPubkey, relayerFee)
+  )
+  // Net: stealth -> destination
+  transaction.add(
+    createTransferInstruction(stealthATA, destinationATA, stealthPubkey, netAmount)
+  )
+
+  const { blockhash, lastValidBlockHeight } = await connection.getLatestBlockhash()
+  transaction.recentBlockhash = blockhash
+  transaction.lastValidBlockHeight = lastValidBlockHeight
+  transaction.feePayer = relayerPublicKey
+
+  // Stealth signs the token transfers via its scalar; relayer (fee-payer) signs at submit time.
+  // Must be done AFTER feePayer + recentBlockhash + all instructions are set.
+  stealthSigner.signTransaction(transaction)
+
+  return {
+    transaction,
+    stealthAddress,
+    destinationAddress,
+    grossAmount,
+    relayerFee,
+    netAmount,
+    blockhash,
+    lastValidBlockHeight,
+  }
+}
+
+/** Detect the Solana cluster from an RPC endpoint URL. */
+function detectCluster(endpoint: string): SolanaCluster {
+  if (endpoint.includes('devnet')) {
+    return 'devnet'
+  }
+  if (endpoint.includes('testnet')) {
+    return 'testnet'
+  }
+  if (endpoint.includes('localhost') || endpoint.includes('127.0.0.1')) {
+    return 'localnet'
+  }
+  return 'mainnet-beta'
+}
+
+/** Parameters for submitting a built gasless cash-out. */
+export interface SubmitGaslessCashoutParams {
+  /** Solana RPC connection */
+  connection: Connection
+  /** Output of buildGaslessCashout (stealth already signed) */
+  build: GaslessCashoutBuild
+  /** Relayer keypair — must equal build.transaction.feePayer */
+  relayerKeypair: Keypair
+  /** Optional Jito relayer for the bundle path (mainnet hardening). Default: direct submit. */
+  jitoRelayer?: JitoRelayer
+  /** Tip in lamports for the Jito path (ignored on the direct path) */
+  tipLamports?: number
+}
+
+/** Result of a gasless cash-out. */
+export interface GaslessCashoutResult {
+  /** Transaction signature (base58) */
+  txSignature: string
+  /** Destination that received the net amount (base58) */
+  destinationAddress: string
+  /** Net amount forwarded (base units) */
+  amount: bigint
+  /** Relayer fee charged (base units) */
+  relayerFee: bigint
+  /** Explorer URL */
+  explorerUrl: string
+  /** Whether the Jito bundle path was used */
+  viaJito: boolean
+}
+
+/**
+ * Sign as the relayer (fee-payer) and submit a gasless cash-out.
+ *
+ * Direct submission is the primary path (works on devnet + mainnet). Supplying a
+ * `jitoRelayer` routes through a Jito bundle instead (optional mainnet hardening;
+ * Jito has no devnet block engine).
+ *
+ * @throws If `relayerKeypair` is not the transaction's fee-payer
+ */
+export async function submitGaslessCashout(
+  params: SubmitGaslessCashoutParams
+): Promise<GaslessCashoutResult> {
+  const { connection, build, relayerKeypair, jitoRelayer, tipLamports } = params
+  const { transaction, netAmount, relayerFee, destinationAddress } = build
+
+  if (!transaction.feePayer || !transaction.feePayer.equals(relayerKeypair.publicKey)) {
+    throw new Error('relayerKeypair does not match the transaction fee-payer')
+  }
+
+  // Relayer adds its fee-payer signature alongside the stealth signature. Guard against
+  // re-signing when the same build is retried after a transient send failure — a second
+  // partialSign is wasteful and could surprise callers inspecting the signature set.
+  const relayerAlreadySigned = transaction.signatures.some(
+    (s) => s.publicKey.equals(relayerKeypair.publicKey) && s.signature !== null
+  )
+  if (!relayerAlreadySigned) {
+    transaction.partialSign(relayerKeypair)
+  }
+
+  const cluster = detectCluster(connection.rpcEndpoint)
+
+  // Optional Jito path (mainnet only — Jito has no devnet block engine).
+  if (jitoRelayer) {
+    const relayed = await jitoRelayer.relayTransaction({
+      transaction,
+      tipLamports,
+      tipPayer: relayerKeypair,
+      waitForConfirmation: true,
+    })
+    // Only a confirmed bundle means the funds actually moved. A 'submitted'/'failed'
+    // status is NOT success — surfacing it as one would silently lose the cash-out.
+    if (relayed.status !== 'confirmed') {
+      throw new Error(
+        `Gasless cash-out via Jito did not confirm (status: ${relayed.status})` +
+        (relayed.error ? `: ${relayed.error}` : '')
+      )
+    }
+    if (!relayed.signature) {
+      throw new Error('Gasless cash-out via Jito returned an empty transaction signature')
+    }
+    return {
+      txSignature: relayed.signature,
+      destinationAddress,
+      amount: netAmount,
+      relayerFee,
+      explorerUrl: getExplorerUrl(relayed.signature, cluster),
+      // Report the TRUE path: the relayer may have fallen back to direct submission.
+      viaJito: relayed.relayed,
+    }
+  }
+
+  // Direct path (primary): relayer is fee-payer; sendRawTransaction returns a base58 sig.
+  const txSignature = await connection.sendRawTransaction(transaction.serialize(), {
+    skipPreflight: false,
+    preflightCommitment: 'confirmed',
+  })
+  const confirmation = await connection.confirmTransaction(
+    {
+      signature: txSignature,
+      blockhash: build.blockhash,
+      lastValidBlockHeight: build.lastValidBlockHeight,
+    },
+    'confirmed'
+  )
+  if (confirmation.value.err) {
+    throw new Error(
+      `Gasless cash-out landed but failed on-chain: ${JSON.stringify(confirmation.value.err)}`
+    )
+  }
+
+  return {
+    txSignature,
+    destinationAddress,
+    amount: netAmount,
+    relayerFee,
+    explorerUrl: getExplorerUrl(txSignature, cluster),
+    viaJito: false,
+  }
+}

package/src/chains/solana/index.ts

@@ -359,3 +359,19 @@ export {
   type VerifyProofResult,
   type Groth16Proof,
 } from './sunspot-verifier'
+
+// Gasless Cash-Out (relayer fee-payer for stealth recipients)
+export {
+  buildGaslessCashout,
+  submitGaslessCashout,
+} from './gasless-cashout'
+export type {
+  GaslessCashoutParams,
+  GaslessCashoutBuild,
+  SubmitGaslessCashoutParams,
+  GaslessCashoutResult,
+} from './gasless-cashout'
+export { computeRelayerFee } from './relayer-fee'
+export type { RelayerFeeConfig } from './relayer-fee'
+export { signEd25519WithScalar, deriveStealthSigner } from './stealth-signer'
+export type { StealthSigner, DeriveStealthSignerParams } from './stealth-signer'

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

@@ -520,6 +520,7 @@ export class SolanaPrivacyAdapter {
       spendingPrivateKey: params.spendingPrivateKey,
       destinationAddress: params.destinationAddress,
       mint: new PublicKey(params.payment.mint),
+      version: params.payment.version,
     })
   }
 

package/src/chains/solana/providers/webhook.ts

@@ -666,6 +666,7 @@ async function processRawTransaction(
       const payment: SolanaScanResult = {
         stealthAddress: announcement.stealthAddress || '',
         ephemeralPublicKey: announcement.ephemeralPublicKey,
+        version: announcement.version as '1' | '2',
         amount: transferInfo?.amount ?? 0n,
         mint: transferInfo?.mint ?? '',
         tokenSymbol: transferInfo?.mint ? getTokenSymbol(transferInfo.mint) : undefined,

package/src/chains/solana/relayer-fee.ts

@@ -0,0 +1,39 @@
+/**
+ * Relayer fee model for gasless cash-out.
+ *
+ * The relayer fronts the SOL transaction fee on behalf of a stealth recipient
+ * and recovers its cost from the SPL tokens being cashed out (fee-from-claim).
+ * The fee is `max(flatFloor, amount * bps / 10_000)`: the floor guarantees the
+ * fixed SOL gas cost is covered even on tiny claims; bps scales on large ones.
+ * No price oracle in v1 — the floor is set in the token's base units.
+ */
+
+/** Relayer fee configuration (per token mint). */
+export interface RelayerFeeConfig {
+  /** Flat floor fee in the token's base units. Guarantees gas coverage on small claims. */
+  flatFloor: bigint
+  /** Basis points of the claim amount (1 bps = 0.01%). e.g. 10 = 0.1%. */
+  bps: number
+}
+
+/**
+ * Compute the relayer fee for a claim.
+ *
+ * @param amount - Gross amount available in the stealth token account (base units)
+ * @param config - Fee model
+ * @returns Fee in the token's base units (always >= flatFloor)
+ * @throws If `bps` is negative or non-integer, or if `amount` is negative, or if flatFloor is negative
+ */
+export function computeRelayerFee(amount: bigint, config: RelayerFeeConfig): bigint {
+  if (!Number.isInteger(config.bps) || config.bps < 0) {
+    throw new Error('bps must be a non-negative integer')
+  }
+  if (amount < 0n) {
+    throw new Error('amount must be a non-negative bigint')
+  }
+  if (typeof config.flatFloor !== 'bigint' || config.flatFloor < 0n) {
+    throw new Error('flatFloor must be a non-negative bigint')
+  }
+  const bpsFee = (amount * BigInt(config.bps)) / 10_000n
+  return bpsFee > config.flatFloor ? bpsFee : config.flatFloor
+}