@shroud-fi/payments 0.1.2 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shroud-fi/payments",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Sender-side stealth payment construction for ShroudFi. ETH + ERC-20 unlinkable payments on Base via EIP-5564 announcements.",
   "keywords": [
     "shroudfi",
@@ -27,13 +27,16 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "src",
+    "tsconfig.json",
+    "README.md"
   ],
   "dependencies": {
     "@noble/curves": "^1.6.0",
     "@noble/hashes": "^1.5.0",
-    "@shroud-fi/core": "0.1.2",
-    "@shroud-fi/transport": "0.1.3"
+    "@shroud-fi/core": "0.1.3",
+    "@shroud-fi/transport": "0.1.4"
   },
   "peerDependencies": {
     "viem": "^2.21.0"

package/src/amount-privacy.ts

@@ -0,0 +1,59 @@
+import type { Address } from 'viem';
+import { AmountPrivacyNotSupportedError } from './errors.js';
+
+export interface ShieldResult {
+  readonly txHash: string;
+  readonly noteId?: string;
+}
+
+export interface PrivateTransferResult {
+  readonly txHash: string;
+  readonly recipient: Address;
+}
+
+export interface UnshieldResult {
+  readonly txHash: string;
+}
+
+export interface AmountPrivacyProvider {
+  readonly name: string;
+  shield(token: Address, amount: bigint): Promise<ShieldResult>;
+  privateTransfer(to: Address, amount: bigint, token: Address): Promise<PrivateTransferResult>;
+  unshield(amount: bigint, token: Address): Promise<UnshieldResult>;
+  grantViewAccess(viewer: Address): Promise<void>;
+  estimateGas(token: Address, amount: bigint): Promise<bigint>;
+}
+
+export class NullAmountPrivacyProvider implements AmountPrivacyProvider {
+  readonly name = 'null';
+
+  async shield(_token?: Address, _amount?: bigint): Promise<ShieldResult> {
+    throw new AmountPrivacyNotSupportedError('shield');
+  }
+
+  async privateTransfer(
+    _to?: Address,
+    _amount?: bigint,
+    _token?: Address,
+  ): Promise<PrivateTransferResult> {
+    throw new AmountPrivacyNotSupportedError('privateTransfer');
+  }
+
+  async unshield(_amount?: bigint, _token?: Address): Promise<UnshieldResult> {
+    throw new AmountPrivacyNotSupportedError('unshield');
+  }
+
+  async grantViewAccess(_viewer?: Address): Promise<void> {
+    throw new AmountPrivacyNotSupportedError('grantViewAccess');
+  }
+
+  async estimateGas(_token?: Address, _amount?: bigint): Promise<bigint> {
+    throw new AmountPrivacyNotSupportedError('estimateGas');
+  }
+}
+
+export function assertSupported(provider: AmountPrivacyProvider): void {
+  if (provider.name === 'null') {
+    throw new AmountPrivacyNotSupportedError(provider.name);
+  }
+}

package/src/constants.ts

@@ -0,0 +1,12 @@
+import type { Address } from 'viem';
+
+export const DEFAULT_GAS_MULTIPLIER = 120n;
+
+export const ETH_SENTINEL = '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE' as const satisfies Address;
+
+export const ZERO_ADDRESS = '0x0000000000000000000000000000000000000000' as const satisfies Address;
+
+export const SCHEME_ID = 1n;
+
+export const ERC20_TRANSFER_GAS_ESTIMATE = 65_000n;
+export const ETH_TRANSFER_GAS_ESTIMATE = 21_000n;

package/src/errors.ts

@@ -0,0 +1,86 @@
+export class PaymentError extends Error {
+  override readonly name: string = 'PaymentError';
+  constructor(message: string) {
+    super(message);
+  }
+}
+
+export class SweepError extends Error {
+  override readonly name: string = 'SweepError';
+  constructor(message: string) {
+    super(message);
+  }
+}
+
+export class InvalidRecipientError extends PaymentError {
+  override readonly name: string = 'InvalidRecipientError';
+  constructor() {
+    super('Invalid recipient meta-address');
+  }
+}
+
+export class InsufficientBalanceError extends SweepError {
+  override readonly name: string = 'InsufficientBalanceError';
+  constructor() {
+    super('Insufficient balance to cover gas');
+  }
+}
+
+export class ZeroAmountError extends PaymentError {
+  override readonly name: string = 'ZeroAmountError';
+  constructor() {
+    super('Amount must be greater than zero');
+  }
+}
+
+export class AmountPrivacyNotSupportedError extends Error {
+  override readonly name: string = 'AmountPrivacyNotSupportedError';
+  constructor(method: string) {
+    super(`Amount privacy not supported: ${method}`);
+  }
+}
+
+export class MissingWalletClientError extends PaymentError {
+  override readonly name: string = 'MissingWalletClientError';
+  constructor() {
+    super('Transport has no walletClient configured');
+  }
+}
+
+export class StealthPaymentContractNotConfiguredError extends PaymentError {
+  override readonly name: string = 'StealthPaymentContractNotConfiguredError';
+  constructor() {
+    super('ShroudFiStealth contract address not configured');
+  }
+}
+
+/**
+ * Thrown when a sender tries to pay a wallet that has not yet registered a
+ * stealth meta-address in the canonical ERC-6538 registry. The recipient must
+ * onboard first (publish their (S, B) pubkeys) before stealth payments are
+ * possible.
+ *
+ * Privacy note: the offending wallet address is NOT placed in `.message`. It
+ * is exposed via the `wallet` property so callers can show a useful UI hint
+ * without leaking the address into logs that only capture `.message`.
+ */
+export class RecipientNotOnboardedError extends PaymentError {
+  override readonly name: string = 'RecipientNotOnboardedError';
+  readonly wallet: `0x${string}`;
+  constructor(wallet: `0x${string}`) {
+    super('Recipient wallet has not registered a stealth meta-address');
+    this.wallet = wallet;
+  }
+}
+
+/**
+ * Thrown when the bytes returned by `stealthMetaAddressOf` are not the
+ * expected 66 raw bytes (33 spending pubkey + 33 viewing pubkey) with valid
+ * compressed-point prefixes. Indicates registry corruption or off-spec usage.
+ */
+export class MalformedMetaAddressError extends PaymentError {
+  override readonly name: string = 'MalformedMetaAddressError';
+  constructor() {
+    super('Registry returned a malformed stealth meta-address');
+  }
+}

package/src/index.ts

@@ -0,0 +1,62 @@
+// Public surface — @shroud-fi/payments
+// Phase 1: stealth payment construction + sweep (self-funded).
+// Sweep timing (log-normal delay, destination rotation) lives in @shroud-fi/scanning (P3).
+// Relayer-funded sweep + EIP-2612 permit lives in the relayer service (P5).
+
+// Functions
+export {
+  sendETHPayment,
+  sendERC20Payment,
+  prepareStealthPayment,
+} from './payments.js';
+export {
+  sweepETH,
+  sweepERC20,
+} from './sweep.js';
+export {
+  sendToWallet,
+  lookupMetaAddress,
+} from './send-to-wallet.js';
+export {
+  NullAmountPrivacyProvider,
+  assertSupported,
+} from './amount-privacy.js';
+
+// Types
+export type {
+  SendOptions,
+  PaymentReceipt,
+  SweepReceipt,
+  PreparedStealthPayment,
+} from './types.js';
+export type { SendToWalletAsset } from './send-to-wallet.js';
+export type {
+  AmountPrivacyProvider,
+  ShieldResult,
+  PrivateTransferResult,
+  UnshieldResult,
+} from './amount-privacy.js';
+
+// Constants
+export {
+  DEFAULT_GAS_MULTIPLIER,
+  ETH_SENTINEL,
+  ZERO_ADDRESS,
+  SCHEME_ID,
+  ETH_TRANSFER_GAS_ESTIMATE,
+  ERC20_TRANSFER_GAS_ESTIMATE,
+} from './constants.js';
+
+// Errors
+export {
+  PaymentError,
+  SweepError,
+  InvalidRecipientError,
+  InsufficientBalanceError,
+  ZeroAmountError,
+  AmountPrivacyNotSupportedError,
+  MissingWalletClientError,
+  StealthPaymentContractNotConfiguredError,
+  RecipientNotOnboardedError,
+  MalformedMetaAddressError,
+} from './errors.js';

package/src/payments.ts

@@ -0,0 +1,319 @@
+/**
+ * ShroudFi Payments - Stealth Payment Construction
+ *
+ * Builds and submits stealth payments through the ShroudFiStealth contract.
+ * Uses generateStealthAddress from @shroud-fi/core for derivation.
+ *
+ * Privacy invariants enforced:
+ *   - No private key material in any error message
+ *   - No plaintext amounts in any error message
+ *   - No console.log/warn/error anywhere
+ *   - Non-custodial: only constructs transactions, never holds funds
+ */
+
+import type { Address, Hash, Hex, PublicClient, TransactionReceipt } from 'viem';
+import { decodeEventLog } from 'viem';
+import { generateStealthAddress } from '@shroud-fi/core';
+import type { StealthMetaAddress } from '@shroud-fi/core';
+import { ShroudFiStealthAbi } from '@shroud-fi/transport';
+import type { ShroudFiTransport } from '@shroud-fi/transport';
+import type {
+  PaymentReceipt,
+  PreparedStealthPayment,
+  SendOptions,
+} from './types.js';
+import {
+  MissingWalletClientError,
+  ZeroAmountError,
+  InvalidRecipientError,
+  PaymentError,
+} from './errors.js';
+import { DEFAULT_GAS_MULTIPLIER } from './constants.js';
+
+/**
+ * Encode the view tag (0-255) as a single byte (bytes1) for the contract call.
+ * Returns a `0x${string}` of exactly 4 chars (e.g. "0x07", "0xff").
+ */
+function viewTagToBytes1(viewTag: number): `0x${string}` {
+  return `0x${viewTag.toString(16).padStart(2, '0')}` as `0x${string}`;
+}
+
+/**
+ * Convert a Uint8Array ephemeral pubkey to a 0x-prefixed hex string.
+ */
+function ephemeralPubKeyToHex(bytes: Uint8Array): Hex {
+  let hex = '0x';
+  for (const b of bytes) {
+    hex += b.toString(16).padStart(2, '0');
+  }
+  return hex as Hex;
+}
+
+/**
+ * Prepare stealth payment material from a recipient meta-address.
+ * Pure helper - does not submit any transaction.
+ *
+ * @throws InvalidRecipientError if the meta-address is malformed or invalid.
+ */
+export function prepareStealthPayment(
+  metaAddress: StealthMetaAddress,
+): PreparedStealthPayment {
+  let result;
+  try {
+    result = generateStealthAddress(metaAddress);
+  } catch {
+    // Wrap all core errors as InvalidRecipientError - never leak key bytes.
+    throw new InvalidRecipientError();
+  }
+  return {
+    stealthAddress: result.stealthAddress,
+    ephemeralPubKey: ephemeralPubKeyToHex(result.ephemeralPubKey),
+    viewTag: result.viewTag,
+  };
+}
+
+/**
+ * Decode the StealthPayment event from a transaction receipt.
+ * Returns a PaymentReceipt with the on-chain stealth address + token + block.
+ *
+ * @throws PaymentError if the StealthPayment log cannot be found / decoded.
+ */
+async function parsePaymentReceipt(
+  txHash: Hash,
+  publicClient: PublicClient,
+  ephemeralPubKey: Hex,
+  viewTag: number,
+  expectedToken: Address,
+): Promise<PaymentReceipt> {
+  const receipt: TransactionReceipt =
+    await publicClient.getTransactionReceipt({ hash: txHash });
+
+  for (const log of receipt.logs) {
+    try {
+      const decoded = decodeEventLog({
+        abi: ShroudFiStealthAbi,
+        data: log.data,
+        topics: log.topics,
+        eventName: 'StealthPayment',
+      });
+      if (decoded.eventName === 'StealthPayment') {
+        const args = decoded.args as {
+          stealthAddress: Address;
+          token: Address;
+          amount: bigint;
+        };
+        // expectedToken is informational - we trust the event token.
+        void expectedToken;
+        void args.amount; // Never expose amount via this return - already in receipt.
+        return {
+          txHash,
+          stealthAddress: args.stealthAddress,
+          ephemeralPubKey,
+          viewTag,
+          blockNumber: receipt.blockNumber,
+          token: args.token,
+        };
+      }
+    } catch {
+      // Not a StealthPayment log - try next.
+      continue;
+    }
+  }
+  throw new PaymentError('StealthPayment event not found in receipt');
+}
+
+/**
+ * Send native ETH to a stealth address derived from `metaAddress`.
+ *
+ * Privacy notes:
+ *   - The contract emits a StealthPayment event with the stealth address.
+ *   - The amount is on-chain by necessity (no native ETH amount privacy).
+ *   - Caller pays gas - relayer abstraction is a separate concern.
+ *
+ * @throws MissingWalletClientError if transport has no walletClient configured.
+ * @throws ZeroAmountError if valueWei is 0n.
+ * @throws InvalidRecipientError if the meta-address is invalid.
+ */
+export async function sendETHPayment(
+  transport: ShroudFiTransport,
+  contractAddress: Address,
+  metaAddress: StealthMetaAddress,
+  valueWei: bigint,
+  options?: SendOptions,
+): Promise<PaymentReceipt> {
+  if (valueWei === 0n) {
+    throw new ZeroAmountError();
+  }
+  const wallet = transport.walletClient;
+  if (!wallet) {
+    throw new MissingWalletClientError();
+  }
+  const account = wallet.account;
+  if (!account) {
+    throw new MissingWalletClientError();
+  }
+
+  const prepared = prepareStealthPayment(metaAddress);
+  const viewTagByte = viewTagToBytes1(prepared.viewTag);
+
+  const gasMultiplier = options?.gasMultiplier ?? DEFAULT_GAS_MULTIPLIER;
+  let gas: bigint | undefined;
+  try {
+    const estimated = await transport.publicClient.estimateContractGas({
+      address: contractAddress,
+      abi: ShroudFiStealthAbi,
+      functionName: 'sendETH',
+      args: [prepared.stealthAddress, prepared.ephemeralPubKey, viewTagByte],
+      value: valueWei,
+      account: account.address,
+    });
+    // Ceil-division — match sweep.ts so multiplier never under-shoots gas
+    gas = (estimated * gasMultiplier + 99n) / 100n;
+  } catch {
+    // Gas estimation can fail in tests / on mocks - fall through without gas
+    // override; walletClient will estimate on send.
+    gas = undefined;
+  }
+
+  const writeArgs: Record<string, unknown> = {
+    address: contractAddress,
+    abi: ShroudFiStealthAbi,
+    functionName: 'sendETH',
+    args: [prepared.stealthAddress, prepared.ephemeralPubKey, viewTagByte],
+    value: valueWei,
+    account,
+    chain: transport.chain,
+  };
+  if (gas !== undefined) writeArgs['gas'] = gas;
+  if (options?.maxFeePerGas !== undefined) writeArgs['maxFeePerGas'] = options.maxFeePerGas;
+  if (options?.maxPriorityFeePerGas !== undefined)
+    writeArgs['maxPriorityFeePerGas'] = options.maxPriorityFeePerGas;
+  if (options?.nonce !== undefined) writeArgs['nonce'] = options.nonce;
+
+  let txHash: Hash;
+  try {
+    // viem's writeContract has a complex union signature - cast at the boundary.
+    txHash = (await (wallet.writeContract as (a: unknown) => Promise<Hash>)(
+      writeArgs,
+    )) as Hash;
+  } catch (err) {
+    // Re-wrap without leaking amount or key material.
+    if (err instanceof PaymentError) throw err;
+    throw new PaymentError('Failed to submit stealth ETH payment');
+  }
+
+  try {
+    await transport.publicClient.waitForTransactionReceipt({ hash: txHash });
+  } catch {
+    throw new PaymentError('Failed to confirm stealth ETH payment');
+  }
+
+  return parsePaymentReceipt(
+    txHash,
+    transport.publicClient,
+    prepared.ephemeralPubKey,
+    prepared.viewTag,
+    '0x0000000000000000000000000000000000000000' as Address,
+  );
+}
+
+/**
+ * Send an ERC-20 token to a stealth address derived from `metaAddress`.
+ *
+ * **Pre-approval required:** the caller MUST have already approved
+ * `contractAddress` to spend at least `amount` of `token` from the sender's
+ * account. v1 does not include an approve flow.
+ *
+ * @throws MissingWalletClientError if transport has no walletClient configured.
+ * @throws ZeroAmountError if amount is 0n.
+ * @throws InvalidRecipientError if the meta-address is invalid.
+ */
+export async function sendERC20Payment(
+  transport: ShroudFiTransport,
+  contractAddress: Address,
+  metaAddress: StealthMetaAddress,
+  token: Address,
+  amount: bigint,
+  options?: SendOptions,
+): Promise<PaymentReceipt> {
+  if (amount === 0n) {
+    throw new ZeroAmountError();
+  }
+  const wallet = transport.walletClient;
+  if (!wallet) {
+    throw new MissingWalletClientError();
+  }
+  const account = wallet.account;
+  if (!account) {
+    throw new MissingWalletClientError();
+  }
+
+  const prepared = prepareStealthPayment(metaAddress);
+  const viewTagByte = viewTagToBytes1(prepared.viewTag);
+
+  const gasMultiplier = options?.gasMultiplier ?? DEFAULT_GAS_MULTIPLIER;
+  let gas: bigint | undefined;
+  try {
+    const estimated = await transport.publicClient.estimateContractGas({
+      address: contractAddress,
+      abi: ShroudFiStealthAbi,
+      functionName: 'sendERC20',
+      args: [
+        prepared.stealthAddress,
+        token,
+        amount,
+        prepared.ephemeralPubKey,
+        viewTagByte,
+      ],
+      account: account.address,
+    });
+    // Ceil-division — match sweep.ts so multiplier never under-shoots gas
+    gas = (estimated * gasMultiplier + 99n) / 100n;
+  } catch {
+    gas = undefined;
+  }
+
+  const writeArgs: Record<string, unknown> = {
+    address: contractAddress,
+    abi: ShroudFiStealthAbi,
+    functionName: 'sendERC20',
+    args: [
+      prepared.stealthAddress,
+      token,
+      amount,
+      prepared.ephemeralPubKey,
+      viewTagByte,
+    ],
+    account,
+    chain: transport.chain,
+  };
+  if (gas !== undefined) writeArgs['gas'] = gas;
+  if (options?.maxFeePerGas !== undefined) writeArgs['maxFeePerGas'] = options.maxFeePerGas;
+  if (options?.maxPriorityFeePerGas !== undefined)
+    writeArgs['maxPriorityFeePerGas'] = options.maxPriorityFeePerGas;
+  if (options?.nonce !== undefined) writeArgs['nonce'] = options.nonce;
+
+  let txHash: Hash;
+  try {
+    txHash = (await (wallet.writeContract as (a: unknown) => Promise<Hash>)(
+      writeArgs,
+    )) as Hash;
+  } catch (err) {
+    if (err instanceof PaymentError) throw err;
+    throw new PaymentError('Failed to submit stealth ERC-20 payment');
+  }
+
+  try {
+    await transport.publicClient.waitForTransactionReceipt({ hash: txHash });
+  } catch {
+    throw new PaymentError('Failed to confirm stealth ERC-20 payment');
+  }
+
+  return parsePaymentReceipt(
+    txHash,
+    transport.publicClient,
+    prepared.ephemeralPubKey,
+    prepared.viewTag,
+    token,
+  );
+}

package/src/send-to-wallet.ts

@@ -0,0 +1,144 @@
+/**
+ * sendToWallet — ergonomic agent-facing helper.
+ *
+ * Pay an EVM wallet by its plain address. The helper:
+ *   1. Queries the canonical ERC-6538 Registry for the recipient's stealth
+ *      meta-address (scheme 1, secp256k1 + view tag).
+ *   2. Throws `RecipientNotOnboardedError` if the recipient has not registered.
+ *   3. Decodes the 66-byte payload into a `StealthMetaAddress`.
+ *   4. Resolves the chain's `ShroudFiStealth` contract.
+ *   5. Dispatches to `sendETHPayment` or `sendERC20Payment`.
+ *
+ * Senders never have to know about meta-address formats, contract addresses,
+ * or scheme IDs — they pass `0xRecipient`, an asset, and an amount.
+ *
+ * Privacy invariants (see CLAUDE.md):
+ *   - No console.* anywhere.
+ *   - No plaintext amount in any error message.
+ *   - The recipient wallet is NOT placed in `.message` strings; it lives on
+ *     `RecipientNotOnboardedError.wallet` so log scrapers picking up `.message`
+ *     do not capture it.
+ */
+
+import type { Address, Hex, PublicClient } from 'viem';
+import { hexToBytes, isAddress } from 'viem';
+import type { StealthMetaAddress } from '@shroud-fi/core';
+import {
+  ERC6538_REGISTRY,
+  ERC6538RegistryAbi,
+  getShroudFiStealth,
+} from '@shroud-fi/transport';
+import type { ShroudFiTransport } from '@shroud-fi/transport';
+import { sendETHPayment, sendERC20Payment } from './payments.js';
+import type { PaymentReceipt, SendOptions } from './types.js';
+import {
+  InvalidRecipientError,
+  MalformedMetaAddressError,
+  RecipientNotOnboardedError,
+} from './errors.js';
+import { SCHEME_ID, ZERO_ADDRESS } from './constants.js';
+
+// Numeric form for the `StealthMetaAddress.schemeId` field (which is `number`).
+// Keep in sync with payments' `SCHEME_ID` bigint (registry call arg).
+const STEALTH_SCHEME_ID_NUM = 1;
+
+/**
+ * Asset selector. `'ETH'` sends native ETH; `{ token: 0x... }` sends an
+ * ERC-20 (caller must have pre-approved `ShroudFiStealth` to spend the
+ * amount from the sender's account — same constraint as `sendERC20Payment`).
+ */
+export type SendToWalletAsset = 'ETH' | { readonly token: Address };
+
+const COMPRESSED_KEY_LENGTH = 33;
+const META_ADDRESS_PAYLOAD_LENGTH = COMPRESSED_KEY_LENGTH * 2;
+
+/**
+ * Look up a wallet's stealth meta-address in the canonical ERC-6538 registry.
+ * Public helper — useful for UIs that want to show "this wallet is onboarded"
+ * without dispatching a payment.
+ *
+ * @returns the decoded meta-address, or `null` if the wallet is not registered.
+ * @throws MalformedMetaAddressError if the registry bytes are not the expected
+ *   66-byte (33 + 33) compressed-key payload.
+ */
+export async function lookupMetaAddress(
+  transport: ShroudFiTransport,
+  recipientWallet: Address,
+): Promise<StealthMetaAddress | null> {
+  if (!isAddress(recipientWallet) || recipientWallet === ZERO_ADDRESS) {
+    throw new InvalidRecipientError();
+  }
+  const raw = (await (
+    transport.publicClient as PublicClient
+  ).readContract({
+    address: ERC6538_REGISTRY,
+    abi: ERC6538RegistryAbi,
+    functionName: 'stealthMetaAddressOf',
+    args: [recipientWallet, SCHEME_ID],
+  })) as Hex;
+
+  // Empty bytes → not registered. viem returns '0x' for empty.
+  if (raw === '0x' || raw.length <= 2) return null;
+
+  const bytes = hexToBytes(raw);
+  if (bytes.length !== META_ADDRESS_PAYLOAD_LENGTH) {
+    throw new MalformedMetaAddressError();
+  }
+  const spendingPubKey = bytes.slice(0, COMPRESSED_KEY_LENGTH);
+  const viewingPubKey = bytes.slice(COMPRESSED_KEY_LENGTH);
+  const sPrefix = spendingPubKey[0];
+  const vPrefix = viewingPubKey[0];
+  if (sPrefix !== 0x02 && sPrefix !== 0x03) {
+    throw new MalformedMetaAddressError();
+  }
+  if (vPrefix !== 0x02 && vPrefix !== 0x03) {
+    throw new MalformedMetaAddressError();
+  }
+  return {
+    spendingPubKey,
+    viewingPubKey,
+    schemeId: STEALTH_SCHEME_ID_NUM,
+  };
+}
+
+/**
+ * Send a payment to a plain EVM wallet address. The helper performs the
+ * Registry lookup → stealth derivation → on-chain dispatch in one call.
+ *
+ * @throws RecipientNotOnboardedError if the recipient has not registered.
+ * @throws MalformedMetaAddressError if the registry payload is corrupt.
+ * @throws InvalidRecipientError if `recipientWallet` is zero / not a valid address,
+ *   or if the meta-address fails curve validation downstream.
+ * @throws ZeroAmountError if `amount` is 0n.
+ * @throws MissingWalletClientError if transport has no walletClient configured.
+ * @throws UnknownChainError if the transport's chain has no ShroudFiStealth deployment.
+ */
+export async function sendToWallet(
+  transport: ShroudFiTransport,
+  recipientWallet: Address,
+  asset: SendToWalletAsset,
+  amount: bigint,
+  options?: SendOptions,
+): Promise<PaymentReceipt> {
+  if (!isAddress(recipientWallet) || recipientWallet === ZERO_ADDRESS) {
+    throw new InvalidRecipientError();
+  }
+  const meta = await lookupMetaAddress(transport, recipientWallet);
+  if (meta === null) {
+    throw new RecipientNotOnboardedError(recipientWallet);
+  }
+
+  const stealthContract = getShroudFiStealth(transport.chain.id);
+
+  if (asset === 'ETH') {
+    return sendETHPayment(transport, stealthContract, meta, amount, options);
+  }
+  return sendERC20Payment(
+    transport,
+    stealthContract,
+    meta,
+    asset.token,
+    amount,
+    options,
+  );
+}

package/src/sweep.ts

@@ -0,0 +1,313 @@
+import type { Address, Hex } from 'viem';
+import { encodeFunctionData } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+import { ERC20Abi } from '@shroud-fi/transport';
+import type { ShroudFiTransport } from '@shroud-fi/transport';
+import type { SweepReceipt, SendOptions } from './types.js';
+import { SweepError, InsufficientBalanceError } from './errors.js';
+import {
+  DEFAULT_GAS_MULTIPLIER,
+  ETH_SENTINEL,
+  ZERO_ADDRESS,
+  ETH_TRANSFER_GAS_ESTIMATE,
+  ERC20_TRANSFER_GAS_ESTIMATE,
+} from './constants.js';
+
+/**
+ * Fetch EIP-1559 fee suggestions with a safe fallback. viem's
+ * `estimateFeesPerGas` returns the recommended {maxFeePerGas, maxPriorityFeePerGas}
+ * given the current base fee; on chains where the method 404s we fall back to
+ * the legacy `getGasPrice` + a small priority tip so the tx remains valid.
+ *
+ * Crucially we DON'T set maxPriorityFeePerGas == maxFeePerGas — Geth-derived
+ * RPCs reject EIP-1559 transactions where the priority cap equals the total
+ * cap and the base fee is non-zero (effective tip becomes 0, but the producer
+ * still gates on `priority < maxFee - baseFee`). Splitting them keeps Base
+ * Sepolia + mainnet RPCs from returning TransactionRejectedRpcError (-32003).
+ */
+async function suggestEip1559Fees(
+  transport: ShroudFiTransport,
+  options: SendOptions | undefined,
+): Promise<{ maxFeePerGas: bigint; maxPriorityFeePerGas: bigint }> {
+  if (
+    options?.maxFeePerGas !== undefined &&
+    options.maxPriorityFeePerGas !== undefined
+  ) {
+    return {
+      maxFeePerGas: options.maxFeePerGas,
+      maxPriorityFeePerGas: options.maxPriorityFeePerGas,
+    };
+  }
+  try {
+    const fees = await transport.publicClient.estimateFeesPerGas();
+    return {
+      maxFeePerGas: options?.maxFeePerGas ?? fees.maxFeePerGas,
+      maxPriorityFeePerGas:
+        options?.maxPriorityFeePerGas ?? fees.maxPriorityFeePerGas,
+    };
+  } catch {
+    const legacy = await transport.publicClient.getGasPrice();
+    const priority = options?.maxPriorityFeePerGas ?? legacy / 10n;
+    const fee = options?.maxFeePerGas ?? legacy * 2n;
+    return { maxFeePerGas: fee, maxPriorityFeePerGas: priority };
+  }
+}
+
+/**
+ * L2 chains (Base, Optimism, etc.) deduct an L1 data-posting fee from the
+ * sender's balance on top of the L2 gas. The sweep formula `balance - L2gas`
+ * doesn't account for it and the RPC rejects the broadcast as underfunded.
+ *
+ * We reserve a small portion of the swept value to cover the L1 fee plus
+ * fluctuation headroom. Magnitude: keep min(balance * 2%, 0.0001 ETH).
+ */
+function l2DataFeeReserve(balance: bigint): bigint {
+  const percent = balance / 50n;          // 2 %
+  const cap = 100_000_000_000_000n;        // 0.0001 ETH
+  return percent < cap ? percent : cap;
+}
+
+/**
+ * Apply gas multiplier (basis-of-100 percent). Default 120n = 120% headroom.
+ * Performs ceil-division to avoid undershooting fees.
+ */
+function applyGasMultiplier(gas: bigint, multiplier: bigint): bigint {
+  // ceil((gas * multiplier) / 100)
+  return (gas * multiplier + 99n) / 100n;
+}
+
+/**
+ * Compute the required ETH gas reserve for a transaction.
+ *
+ * No amounts are logged or surfaced in errors — privacy invariant #5.
+ */
+async function resolveGasCost(
+  transport: ShroudFiTransport,
+  gasEstimate: bigint,
+  options: SendOptions | undefined,
+): Promise<bigint> {
+  const multiplier = options?.gasMultiplier ?? DEFAULT_GAS_MULTIPLIER;
+  const adjustedGas = applyGasMultiplier(gasEstimate, multiplier);
+
+  const feePerGas =
+    options?.maxFeePerGas ?? (await transport.publicClient.getGasPrice());
+
+  return adjustedGas * feePerGas;
+}
+
+/**
+ * Sweep the entire ETH balance from a stealth address to a destination.
+ *
+ * @param transport - ShroudFi transport (publicClient must reach the target chain)
+ * @param stealthPrivateKey - one-time stealth address private key. Treat as
+ *   sensitive: caller MUST NOT log, persist, or transmit this value. The SDK
+ *   does not retain it after the call returns.
+ * @param destination - final address that receives swept ETH
+ * @param options - optional fee/nonce overrides
+ *
+ * @remarks Phase 1: self-funded sweep. The stealth address pays its own gas in ETH,
+ * which creates a gas-funding correlation vector documented in research (Umbra deanonymization
+ * heuristic H2). This will be addressed in Phase 5 by a gasless relayer flow.
+ *
+ * @remarks Balance/nonce/gas-price are queried separately before signing. Callers running
+ * sweeps concurrently against the same stealth address should pass an explicit `nonce` in
+ * options to avoid races. Stack traces of thrown errors should NOT be logged by callers —
+ * they may contain RPC payload metadata.
+ */
+export async function sweepETH(
+  transport: ShroudFiTransport,
+  stealthPrivateKey: Hex,
+  destination: Address,
+  options?: SendOptions,
+): Promise<SweepReceipt> {
+  if (!destination || destination === ZERO_ADDRESS) {
+    throw new SweepError('Invalid destination');
+  }
+
+  const account = privateKeyToAccount(stealthPrivateKey);
+
+  const balance = await transport.publicClient.getBalance({
+    address: account.address,
+  });
+  if (balance === 0n) {
+    throw new InsufficientBalanceError();
+  }
+
+  const gasCost = await resolveGasCost(
+    transport,
+    ETH_TRANSFER_GAS_ESTIMATE,
+    options,
+  );
+
+  const l2Reserve = l2DataFeeReserve(balance);
+
+  if (balance <= gasCost + l2Reserve) {
+    throw new InsufficientBalanceError();
+  }
+
+  const valueToSend = balance - gasCost - l2Reserve;
+
+  const chain = transport.chain;
+  const nonce =
+    options?.nonce ??
+    (await transport.publicClient.getTransactionCount({
+      address: account.address,
+    }));
+
+  const { maxFeePerGas, maxPriorityFeePerGas } = await suggestEip1559Fees(
+    transport,
+    options,
+  );
+
+  const serializedTransaction = await account.signTransaction({
+    to: destination,
+    value: valueToSend,
+    gas: ETH_TRANSFER_GAS_ESTIMATE,
+    maxFeePerGas,
+    maxPriorityFeePerGas,
+    nonce,
+    chainId: chain.id,
+    type: 'eip1559',
+  });
+
+  let txHash: Hex;
+  try {
+    txHash = await transport.publicClient.sendRawTransaction({
+      serializedTransaction,
+    });
+  } catch (err) {
+    // Privacy: surface only the error class name + a structured tag; never
+    // include the serialized transaction (which contains the signature) or
+    // the raw RPC error payload (which may quote bytes).
+    const tag = err instanceof Error ? err.name : 'unknown';
+    throw new SweepError(`sweep broadcast failed (${tag})`);
+  }
+
+  const receipt = await transport.publicClient.waitForTransactionReceipt({
+    hash: txHash,
+  });
+
+  const swept: SweepReceipt = {
+    txHash,
+    destination,
+    token: ETH_SENTINEL,
+    blockNumber: receipt.blockNumber,
+  };
+  return swept;
+}
+
+/**
+ * Sweep the entire ERC20 balance from a stealth address to a destination.
+ *
+ * The stealth address must already hold enough ETH to pay gas for the
+ * ERC20 transfer. Funding it from another account links the two — see
+ * privacy notes below.
+ *
+ * @param transport - ShroudFi transport
+ * @param stealthPrivateKey - one-time stealth private key (see sweepETH note)
+ * @param token - ERC20 contract address
+ * @param destination - final address that receives swept tokens
+ * @param options - optional fee/nonce overrides
+ *
+ * @remarks Phase 1: self-funded sweep. The stealth address pays its own gas in ETH,
+ * which creates a gas-funding correlation vector documented in research (Umbra deanonymization
+ * heuristic H2). This will be addressed in Phase 5 by a gasless relayer flow.
+ *
+ * @remarks Balance/nonce/gas-price are queried separately before signing. Callers running
+ * sweeps concurrently against the same stealth address should pass an explicit `nonce` in
+ * options to avoid races. Stack traces of thrown errors should NOT be logged by callers —
+ * they may contain RPC payload metadata.
+ */
+export async function sweepERC20(
+  transport: ShroudFiTransport,
+  stealthPrivateKey: Hex,
+  token: Address,
+  destination: Address,
+  options?: SendOptions,
+): Promise<SweepReceipt> {
+  if (!destination || destination === ZERO_ADDRESS) {
+    throw new SweepError('Invalid destination');
+  }
+  if (!token || token === ZERO_ADDRESS) {
+    throw new SweepError('Invalid token');
+  }
+
+  const account = privateKeyToAccount(stealthPrivateKey);
+
+  const tokenBalance = (await transport.publicClient.readContract({
+    address: token,
+    abi: ERC20Abi,
+    functionName: 'balanceOf',
+    args: [account.address],
+  })) as bigint;
+
+  if (tokenBalance === 0n) {
+    throw new InsufficientBalanceError();
+  }
+
+  const ethBalance = await transport.publicClient.getBalance({
+    address: account.address,
+  });
+
+  const gasCost = await resolveGasCost(
+    transport,
+    ERC20_TRANSFER_GAS_ESTIMATE,
+    options,
+  );
+
+  if (ethBalance < gasCost) {
+    throw new InsufficientBalanceError();
+  }
+
+  const data = encodeFunctionData({
+    abi: ERC20Abi,
+    functionName: 'transfer',
+    args: [destination, tokenBalance],
+  });
+
+  const chain = transport.chain;
+  const nonce =
+    options?.nonce ??
+    (await transport.publicClient.getTransactionCount({
+      address: account.address,
+    }));
+
+  const { maxFeePerGas, maxPriorityFeePerGas } = await suggestEip1559Fees(
+    transport,
+    options,
+  );
+
+  const serializedTransaction = await account.signTransaction({
+    to: token,
+    value: 0n,
+    data,
+    gas: ERC20_TRANSFER_GAS_ESTIMATE,
+    maxFeePerGas,
+    maxPriorityFeePerGas,
+    nonce,
+    chainId: chain.id,
+    type: 'eip1559',
+  });
+
+  let txHash: Hex;
+  try {
+    txHash = await transport.publicClient.sendRawTransaction({
+      serializedTransaction,
+    });
+  } catch (err) {
+    const tag = err instanceof Error ? err.name : 'unknown';
+    throw new SweepError(`sweep broadcast failed (${tag})`);
+  }
+
+  const receipt = await transport.publicClient.waitForTransactionReceipt({
+    hash: txHash,
+  });
+
+  const swept: SweepReceipt = {
+    txHash,
+    destination,
+    token,
+    blockNumber: receipt.blockNumber,
+  };
+  return swept;
+}

package/src/types.ts

@@ -0,0 +1,30 @@
+import type { Address, Hash, Hex } from 'viem';
+
+export interface SendOptions {
+  readonly gasMultiplier?: bigint;
+  readonly maxFeePerGas?: bigint;
+  readonly maxPriorityFeePerGas?: bigint;
+  readonly nonce?: number;
+}
+
+export interface PaymentReceipt {
+  readonly txHash: Hash;
+  readonly stealthAddress: Address;
+  readonly ephemeralPubKey: Hex;
+  readonly viewTag: number;
+  readonly blockNumber: bigint;
+  readonly token: Address;
+}
+
+export interface SweepReceipt {
+  readonly txHash: Hash;
+  readonly destination: Address;
+  readonly token: Address;
+  readonly blockNumber: bigint;
+}
+
+export interface PreparedStealthPayment {
+  readonly stealthAddress: Address;
+  readonly ephemeralPubKey: Hex;
+  readonly viewTag: number;
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist/esm",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["dist", "test", "node_modules"]
+}