@shroud-fi/payments 0.1.1 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shroud-fi/payments",
-  "version": "0.1.1",
+  "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.1",
-    "@shroud-fi/transport": "0.1.2"
+    "@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,
+  );
+}