@shroud-fi/transport 0.1.3 → 0.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shroud-fi/transport",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Pluggable viem-based transport + canonical Base mainnet deployment manifest for the ShroudFi privacy SDK.",
   "keywords": [
     "shroudfi",
@@ -25,7 +25,10 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "src",
+    "tsconfig.json",
+    "README.md"
   ],
   "peerDependencies": {
     "viem": "^2.21.0"

package/src/abis.ts

@@ -0,0 +1,288 @@
+export const ERC5564AnnouncerAbi = [
+  {
+    type: 'function',
+    name: 'announce',
+    inputs: [
+      { name: 'schemeId', type: 'uint256' },
+      { name: 'stealthAddress', type: 'address' },
+      { name: 'ephemeralPubKey', type: 'bytes' },
+      { name: 'metadata', type: 'bytes' },
+    ],
+    outputs: [],
+    stateMutability: 'nonpayable',
+  },
+  {
+    type: 'event',
+    name: 'Announcement',
+    inputs: [
+      { name: 'schemeId', type: 'uint256', indexed: true },
+      { name: 'stealthAddress', type: 'address', indexed: true },
+      { name: 'caller', type: 'address', indexed: true },
+      { name: 'ephemeralPubKey', type: 'bytes', indexed: false },
+      { name: 'metadata', type: 'bytes', indexed: false },
+    ],
+  },
+] as const;
+
+export const ShroudFiStealthAbi = [
+  {
+    type: 'function',
+    name: 'sendETH',
+    inputs: [
+      { name: 'stealthAddress', type: 'address' },
+      { name: 'ephemeralPubKey', type: 'bytes' },
+      { name: 'viewTag', type: 'bytes1' },
+    ],
+    outputs: [],
+    stateMutability: 'payable',
+  },
+  {
+    type: 'function',
+    name: 'sendERC20',
+    inputs: [
+      { name: 'stealthAddress', type: 'address' },
+      { name: 'token', type: 'address' },
+      { name: 'amount', type: 'uint256' },
+      { name: 'ephemeralPubKey', type: 'bytes' },
+      { name: 'viewTag', type: 'bytes1' },
+    ],
+    outputs: [],
+    stateMutability: 'nonpayable',
+  },
+  {
+    type: 'function',
+    name: 'ANNOUNCER',
+    inputs: [],
+    outputs: [{ name: '', type: 'address' }],
+    stateMutability: 'view',
+  },
+  {
+    type: 'function',
+    name: 'SCHEME_ID',
+    inputs: [],
+    outputs: [{ name: '', type: 'uint256' }],
+    stateMutability: 'view',
+  },
+  {
+    type: 'function',
+    name: 'ETH_TOKEN_ADDRESS',
+    inputs: [],
+    outputs: [{ name: '', type: 'address' }],
+    stateMutability: 'view',
+  },
+  {
+    type: 'event',
+    name: 'StealthPayment',
+    inputs: [
+      { name: 'stealthAddress', type: 'address', indexed: true },
+      { name: 'token', type: 'address', indexed: true },
+      { name: 'amount', type: 'uint256', indexed: false },
+    ],
+  },
+  { type: 'error', name: 'ZeroAddress', inputs: [] },
+  { type: 'error', name: 'ZeroAmount', inputs: [] },
+  { type: 'error', name: 'InsufficientETH', inputs: [] },
+  { type: 'error', name: 'ETHTransferFailed', inputs: [] },
+] as const;
+
+/**
+ * Minimal ABI for USDC's EIP-3009 `transferWithAuthorization`. Pulled out as
+ * a separate constant because not every ERC-20 supports it — only Circle's
+ * USDC contract and a handful of other authorization-capable tokens. Use
+ * `USDC_BY_CHAIN[chainId]` to address the right deployment.
+ *
+ * The `authorizationState` view is included so callers can confirm a nonce
+ * has not already been consumed before submitting.
+ */
+export const USDCAuthorizationAbi = [
+  {
+    type: 'function',
+    name: 'transferWithAuthorization',
+    inputs: [
+      { name: 'from', type: 'address' },
+      { name: 'to', type: 'address' },
+      { name: 'value', type: 'uint256' },
+      { name: 'validAfter', type: 'uint256' },
+      { name: 'validBefore', type: 'uint256' },
+      { name: 'nonce', type: 'bytes32' },
+      { name: 'v', type: 'uint8' },
+      { name: 'r', type: 'bytes32' },
+      { name: 's', type: 'bytes32' },
+    ],
+    outputs: [],
+    stateMutability: 'nonpayable',
+  },
+  {
+    type: 'function',
+    name: 'authorizationState',
+    inputs: [
+      { name: 'authorizer', type: 'address' },
+      { name: 'nonce', type: 'bytes32' },
+    ],
+    outputs: [{ name: '', type: 'bool' }],
+    stateMutability: 'view',
+  },
+  {
+    type: 'event',
+    name: 'AuthorizationUsed',
+    inputs: [
+      { name: 'authorizer', type: 'address', indexed: true },
+      { name: 'nonce', type: 'bytes32', indexed: true },
+    ],
+  },
+] as const;
+
+export const ERC20Abi = [
+  {
+    type: 'function',
+    name: 'balanceOf',
+    inputs: [{ name: 'account', type: 'address' }],
+    outputs: [{ name: '', type: 'uint256' }],
+    stateMutability: 'view',
+  },
+  {
+    type: 'function',
+    name: 'transfer',
+    inputs: [
+      { name: 'to', type: 'address' },
+      { name: 'amount', type: 'uint256' },
+    ],
+    outputs: [{ name: '', type: 'bool' }],
+    stateMutability: 'nonpayable',
+  },
+  {
+    type: 'function',
+    name: 'approve',
+    inputs: [
+      { name: 'spender', type: 'address' },
+      { name: 'amount', type: 'uint256' },
+    ],
+    outputs: [{ name: '', type: 'bool' }],
+    stateMutability: 'nonpayable',
+  },
+  {
+    type: 'function',
+    name: 'allowance',
+    inputs: [
+      { name: 'owner', type: 'address' },
+      { name: 'spender', type: 'address' },
+    ],
+    outputs: [{ name: '', type: 'uint256' }],
+    stateMutability: 'view',
+  },
+] as const;
+
+export const ShroudFiRelayerAbi = [
+  {
+    type: 'function',
+    name: 'sweepERC20WithPermit',
+    inputs: [
+      { name: 'token', type: 'address' },
+      { name: 'destination', type: 'address' },
+      { name: 'deadline', type: 'uint256' },
+      { name: 'v', type: 'uint8' },
+      { name: 'r', type: 'bytes32' },
+      { name: 's', type: 'bytes32' },
+    ],
+    outputs: [],
+    stateMutability: 'nonpayable',
+  },
+  {
+    type: 'function',
+    name: 'previewFee',
+    inputs: [{ name: 'grossAmount', type: 'uint256' }],
+    outputs: [
+      { name: 'fee', type: 'uint256' },
+      { name: 'net', type: 'uint256' },
+    ],
+    stateMutability: 'view',
+  },
+  {
+    type: 'function',
+    name: 'FEE_BPS',
+    inputs: [],
+    outputs: [{ name: '', type: 'uint16' }],
+    stateMutability: 'view',
+  },
+  {
+    type: 'function',
+    name: 'BPS_DENOMINATOR',
+    inputs: [],
+    outputs: [{ name: '', type: 'uint16' }],
+    stateMutability: 'view',
+  },
+  {
+    type: 'function',
+    name: 'TREASURY',
+    inputs: [],
+    outputs: [{ name: '', type: 'address' }],
+    stateMutability: 'view',
+  },
+  {
+    type: 'function',
+    name: 'treasury',
+    inputs: [],
+    outputs: [{ name: '', type: 'address' }],
+    stateMutability: 'view',
+  },
+  {
+    type: 'function',
+    name: 'trustedForwarder',
+    inputs: [],
+    outputs: [{ name: '', type: 'address' }],
+    stateMutability: 'view',
+  },
+  {
+    type: 'function',
+    name: 'isTrustedForwarder',
+    inputs: [{ name: 'forwarder', type: 'address' }],
+    outputs: [{ name: '', type: 'bool' }],
+    stateMutability: 'view',
+  },
+  {
+    type: 'event',
+    name: 'SweepRelayed',
+    inputs: [
+      { name: 'stealthAddress', type: 'address', indexed: true },
+      { name: 'token', type: 'address', indexed: true },
+      { name: 'destination', type: 'address', indexed: false },
+      { name: 'grossAmount', type: 'uint256', indexed: false },
+      { name: 'feeAmount', type: 'uint256', indexed: false },
+    ],
+  },
+  { type: 'error', name: 'InvalidToken', inputs: [] },
+  { type: 'error', name: 'InvalidDestination', inputs: [] },
+  { type: 'error', name: 'ZeroBalance', inputs: [] },
+  { type: 'error', name: 'PermitFailedAndNoAllowance', inputs: [] },
+  { type: 'error', name: 'TransferFailed', inputs: [] },
+] as const;
+
+export const ERC6538RegistryAbi = [
+  {
+    type: 'function',
+    name: 'registerKeys',
+    inputs: [
+      { name: 'schemeId', type: 'uint256' },
+      { name: 'stealthMetaAddress', type: 'bytes' },
+    ],
+    outputs: [],
+    stateMutability: 'nonpayable',
+  },
+  {
+    type: 'function',
+    name: 'stealthMetaAddressOf',
+    inputs: [
+      { name: 'registrant', type: 'address' },
+      { name: 'schemeId', type: 'uint256' },
+    ],
+    outputs: [{ name: '', type: 'bytes' }],
+    stateMutability: 'view',
+  },
+  {
+    type: 'function',
+    name: 'incrementNonce',
+    inputs: [{ name: 'schemeId', type: 'uint256' }],
+    outputs: [],
+    stateMutability: 'nonpayable',
+  },
+] as const;

package/src/addresses.ts

@@ -0,0 +1,102 @@
+import type { Address } from 'viem';
+
+/** Canonical ERC-5564 stealth announcement contract — same address every EVM chain (CREATE2). */
+export const ERC5564_ANNOUNCER = '0x55649E01B5Df198D18D95b5cc5051630cfD45564' as const;
+
+/** Canonical ERC-6538 stealth meta-address registry — same address every EVM chain (CREATE2). */
+export const ERC6538_REGISTRY = '0x6538E6bf4B0eBd30A8Ea093027Ac2422ce5d6538' as const;
+
+/**
+ * Canonical USDC (Circle-issued) contract addresses, keyed by chain id.
+ *
+ * Per-chain because USDC is NOT CREATE2-deterministic across chains — Circle
+ * deploys a native contract per network with a different address each time.
+ *
+ * Coverage (P6 v1):
+ *   - 8453  Base mainnet  — Circle-native USDC
+ *   - 84532 Base Sepolia  — Circle-native testnet USDC
+ *
+ * Both addresses verified against Circle's official deployment registry on
+ * 2026-06-03. Adding new chains: confirm via https://developers.circle.com/
+ * stablecoin/docs/usdc-on-other-chains before extending this map.
+ *
+ * Both contracts implement EIP-3009 `transferWithAuthorization` (the signing
+ * primitive x402's `exact` scheme depends on) AND EIP-2612 `permit` (the
+ * signing primitive `ShroudFiRelayer` uses). Either path drives sweeps for
+ * USDC stealth payments — see `@shroud-fi/payments` for the dispatch logic.
+ */
+export const USDC_BY_CHAIN: Readonly<Record<number, Address>> = Object.freeze({
+  8453: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+  84532: '0x036CbD53842c5426634e7929541eC2318f3dCF7e',
+} as const);
+
+/**
+ * EIP-712 domain metadata for USDC per chain. Required for client agents
+ * signing `TransferWithAuthorization` against the correct domain separator.
+ *
+ * USDC on Base mainnet + Sepolia both use the same domain shape (Circle's
+ * standard issuance contract). Other chains MAY differ — re-verify before
+ * extending.
+ */
+export const USDC_EIP712_DOMAIN_BY_CHAIN: Readonly<
+  Record<number, { readonly name: string; readonly version: string }>
+> = Object.freeze({
+  8453: Object.freeze({ name: 'USD Coin', version: '2' }),
+  84532: Object.freeze({ name: 'USDC', version: '2' }),
+} as const);
+
+// ---------------------------------------------------------------------------
+// EIP-3009 token registry (v0.1.1 — multi-currency x402)
+// ---------------------------------------------------------------------------
+
+/**
+ * EIP-3009 token entry. Pins everything `@shroud-fi/x402` and any future
+ * EIP-3009-using package needs to construct a valid `transferWithAuthorization`
+ * signature.
+ *
+ * Membership rule: a token belongs here ONLY if its on-chain contract
+ * implements EIP-3009 `transferWithAuthorization`. USDT (vanilla ERC-20),
+ * DAI (DAI-style permit), and most ERC-20s do NOT qualify.
+ */
+export interface Eip3009Token {
+  readonly symbol: 'USDC' | 'EURC';
+  readonly address: Address;
+  readonly decimals: number;
+  readonly domain: { readonly name: string; readonly version: string };
+}
+
+/**
+ * Per-chain EIP-3009 token list. Both x402 settlement (via
+ * `transferWithAuthorization`) and any future EIP-3009-based sweep paths
+ * read from here.
+ *
+ * Adding a new chain or token: VERIFY the contract on-chain (via
+ * `contract.name()` + `contract.version()`) before extending — the EIP-712
+ * domain MUST match exactly or signature recovery silently fails.
+ */
+export const EIP3009_TOKENS_BY_CHAIN: Readonly<
+  Record<number, ReadonlyArray<Eip3009Token>>
+> = Object.freeze({
+  8453: Object.freeze([
+    Object.freeze({
+      symbol: 'USDC' as const,
+      address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' as Address,
+      decimals: 6,
+      domain: Object.freeze({ name: 'USD Coin', version: '2' }),
+    }),
+    Object.freeze({
+      symbol: 'EURC' as const,
+      address: '0x60a3E35Cc302bFA44Cb288Bc5a4F316Fdb1adb42' as Address,
+      decimals: 6,
+      domain: Object.freeze({ name: 'EURC', version: '1' }),
+    }),
+  ]),
+  84532: Object.freeze([
+    Object.freeze({
+      symbol: 'USDC' as const,
+      address: '0x036CbD53842c5426634e7929541eC2318f3dCF7e' as Address,
+      decimals: 6,
+      domain: Object.freeze({ name: 'USDC', version: '2' }),
+    }),
+  ]),
+} as const);

package/src/chains.ts

@@ -0,0 +1 @@
+export { base, baseSepolia } from 'viem/chains';

package/src/create.ts

@@ -0,0 +1,19 @@
+import { createPublicClient, createWalletClient, http, type Chain } from 'viem';
+import { base, baseSepolia } from 'viem/chains';
+import { privateKeyToAccount } from 'viem/accounts';
+import type { ShroudFiTransport, ShroudFiTransportConfig } from './types.js';
+
+export function createTransport(config: ShroudFiTransportConfig): ShroudFiTransport {
+  const chain: Chain = config.chain === 'base' ? base : baseSepolia;
+  const transport = config.rpcUrl ? http(config.rpcUrl) : http();
+
+  const publicClient = createPublicClient({ chain, transport });
+
+  let walletClient: ShroudFiTransport['walletClient'];
+  if (config.privateKey) {
+    const account = privateKeyToAccount(config.privateKey);
+    walletClient = createWalletClient({ account, chain, transport });
+  }
+
+  return { publicClient, walletClient, chain } as ShroudFiTransport;
+}

package/src/deployments-helpers.ts

@@ -0,0 +1,153 @@
+import type { Address } from 'viem';
+import {
+  DEPLOYMENTS,
+  SHROUDFI_STEALTH_BY_CHAIN,
+  SHROUDFI_REGISTRAR_BY_CHAIN,
+  MOCK_ERC20_BY_CHAIN,
+  MOCK_ERC20_PERMIT_BY_CHAIN,
+  SHROUDFI_RELAYER_BY_CHAIN,
+  SHROUDFI_ETH_RELAYER_BY_CHAIN,
+} from './deployments.js';
+import type { DeploymentManifest } from './deployments.js';
+import {
+  USDC_BY_CHAIN,
+  USDC_EIP712_DOMAIN_BY_CHAIN,
+  EIP3009_TOKENS_BY_CHAIN,
+} from './addresses.js';
+import type { Eip3009Token } from './addresses.js';
+import { UnknownChainError } from './errors.js';
+
+export function getShroudFiStealth(chainId: number): Address {
+  const a = SHROUDFI_STEALTH_BY_CHAIN[chainId];
+  if (!a) throw new UnknownChainError(chainId);
+  return a;
+}
+
+export function getShroudFiRegistrar(chainId: number): Address {
+  const a = SHROUDFI_REGISTRAR_BY_CHAIN[chainId];
+  if (!a) throw new UnknownChainError(chainId);
+  return a;
+}
+
+/**
+ * MockERC20 lookup. Returns undefined for chains that don't carry one
+ * (e.g. mainnet — mocks are testnet-only).
+ */
+export function getMockERC20(chainId: number): Address | undefined {
+  return MOCK_ERC20_BY_CHAIN[chainId];
+}
+
+/**
+ * ShroudFiRelayer lookup. Returns undefined for chains where the relayer
+ * contract has not yet been deployed (e.g. before Wave 3 populates the manifest).
+ */
+export function getRelayer(chainId: number): Address | undefined {
+  return SHROUDFI_RELAYER_BY_CHAIN[chainId];
+}
+
+/**
+ * ShroudFiEthRelayer (P5.1) lookup. Returns undefined for chains where the
+ * EIP-7702 ETH gasless sweep contract has not yet been deployed.
+ */
+export function getEthRelayer(chainId: number): Address | undefined {
+  return SHROUDFI_ETH_RELAYER_BY_CHAIN[chainId];
+}
+
+/**
+ * MockERC20Permit lookup — the permit-capable ERC-20 mock used by the demo
+ * for both direct sweep AND gasless sweep paths. The original MockERC20
+ * (non-permit) remains in the manifest as a backward-compatibility entry
+ * but new code paths should prefer this one.
+ *
+ * Returns undefined for chains that don't carry a deployment (mainnet etc.).
+ */
+export function getMockERC20Permit(chainId: number): Address | undefined {
+  return MOCK_ERC20_PERMIT_BY_CHAIN[chainId];
+}
+
+/**
+ * Canonical USDC (Circle-issued) address lookup. Returns undefined for any
+ * chain not in the supported allowlist — callers should treat undefined as
+ * "USDC not available on this chain" and surface a clear error, NOT fall back
+ * to a zero address or a non-Circle token.
+ */
+export function getUSDC(chainId: number): Address | undefined {
+  return USDC_BY_CHAIN[chainId];
+}
+
+/**
+ * EIP-712 domain metadata (`name`, `version`) for USDC on a given chain.
+ * Required to sign `TransferWithAuthorization` for x402's `exact` scheme and
+ * for `ShroudFiRelayer` ERC-20 permit-based gasless sweeps.
+ *
+ * Returns undefined when USDC is not supported on the chain.
+ */
+export function getUSDCDomain(
+  chainId: number,
+): { readonly name: string; readonly version: string } | undefined {
+  return USDC_EIP712_DOMAIN_BY_CHAIN[chainId];
+}
+
+/**
+ * Boolean check — is USDC available (and supported by this SDK) on this chain?
+ */
+export function hasUSDC(chainId: number): boolean {
+  return chainId in USDC_BY_CHAIN;
+}
+
+// ---------------------------------------------------------------------------
+// EIP-3009 token registry helpers (v0.1.1 — multi-currency x402)
+// ---------------------------------------------------------------------------
+
+/**
+ * Look up an EIP-3009 token by chain id + on-chain address. Address comparison
+ * is case-insensitive — callers can pass either checksummed or lowercase form.
+ *
+ * Returns undefined when the chain has no EIP-3009 tokens registered OR the
+ * address is not one of them.
+ */
+export function getEip3009Token(
+  chainId: number,
+  address: string,
+): Eip3009Token | undefined {
+  const list = EIP3009_TOKENS_BY_CHAIN[chainId];
+  if (list === undefined) return undefined;
+  const needle = address.toLowerCase();
+  return list.find((t) => t.address.toLowerCase() === needle);
+}
+
+/**
+ * Look up an EIP-3009 token by symbol ('USDC', 'EURC'). Returns undefined
+ * for unknown chains or unsupported symbols (USDT, DAI, etc).
+ */
+export function getEip3009TokenBySymbol(
+  chainId: number,
+  symbol: string,
+): Eip3009Token | undefined {
+  const list = EIP3009_TOKENS_BY_CHAIN[chainId];
+  if (list === undefined) return undefined;
+  return list.find((t) => t.symbol === symbol);
+}
+
+/**
+ * Enumerate every EIP-3009 token registered for a given chain. Useful for
+ * surfacing the available-assets list in an x402 challenge or a UI picker.
+ * Returns the empty array for unknown chains.
+ */
+export function listEip3009Tokens(chainId: number): ReadonlyArray<Eip3009Token> {
+  return EIP3009_TOKENS_BY_CHAIN[chainId] ?? [];
+}
+
+export function getDeployment(chainId: number): DeploymentManifest {
+  const m = DEPLOYMENTS[chainId];
+  if (!m) throw new UnknownChainError(chainId);
+  return m;
+}
+
+export function hasDeployment(chainId: number): boolean {
+  return Boolean(DEPLOYMENTS[chainId]);
+}
+
+export function listDeployedChains(): readonly number[] {
+  return Object.keys(DEPLOYMENTS).map(Number);
+}

package/src/deployments.ts

@@ -0,0 +1,110 @@
+// AUTO-GENERATED FILE — DO NOT EDIT.
+// Source of truth: contracts/deployments/*.json
+// Regenerate via:  pnpm sync-deployments
+// (To produce/update a manifest entry, deploy via Foundry and capture the MANIFEST line.)
+
+import type { Address, Hex } from 'viem';
+
+export interface DeploymentManifest {
+  readonly chainId: number;
+  readonly chainName: string;
+  readonly deployedAt: string;
+  readonly deployer: Address;
+  readonly shroudfiStealth: Address;
+  readonly shroudfiRegistrar: Address;
+  readonly stealthSalt: Hex;
+  readonly registrarSalt: Hex;
+  readonly announcer: Address;
+  readonly registry: Address;
+  readonly block: number;
+  readonly blockscoutUrl?: string;
+  readonly mockERC20?: Address;
+  readonly mockERC20Block?: number;
+  readonly shroudfiRelayer?: Address;
+  readonly relayerTreasury?: Address;
+  readonly relayerForwarder?: Address;
+  readonly relayerBlock?: number;
+  readonly mockERC20Permit?: Address;
+  readonly mockERC20PermitBlock?: number;
+  readonly shroudfiEthRelayer?: Address;
+  readonly shroudfiEthRelayerBlock?: number;
+  readonly ethRelayerOperator?: Address;
+  readonly isExample?: boolean;
+}
+
+export const DEPLOYMENTS: Readonly<Record<number, DeploymentManifest>> = Object.freeze({
+    8453: Object.freeze({
+      chainId: 8453,
+      chainName: "Base",
+      deployedAt: "2026-06-02T23:30:00Z",
+      deployer: "0xBCB3E28150982F2EfeC615b4f8D15Cf1A1C418Aa",
+      shroudfiStealth: "0x4BC88813b09dDD6Ab530261200D706B397EcD0AB",
+      shroudfiRegistrar: "0xDbBB9Ebc61b800a3d3309A867a87439F706C1207",
+      stealthSalt: "0x36f380f35c71197d157fceabdd952cfe52e65d056c5d5cf73d72f407147c0961",
+      registrarSalt: "0xad705f075979fd59f9335b1123d73d1f3c73955b9fad97c337b25b6054fdf95d",
+      announcer: "0x55649E01B5Df198D18D95b5cc5051630cfD45564",
+      registry: "0x6538E6bf4B0eBd30A8Ea093027Ac2422ce5d6538",
+      block: 46825277,
+      blockscoutUrl: "https://base.blockscout.com",
+      shroudfiRelayer: "0x44f35ED32516AE8247aF5ec4ED5d5BEb501631d1",
+      relayerTreasury: "0x4B01C6eadD1663f5A7d792C24d8001c80EAE25b2",
+      relayerForwarder: "0xBCB3E28150982F2EfeC615b4f8D15Cf1A1C418Aa",
+      relayerBlock: 46825293,
+      shroudfiEthRelayer: "0x477c497F17cED01ff9c01D8a9Da1c019AFb31a66",
+      shroudfiEthRelayerBlock: 46825310,
+      ethRelayerOperator: "0xBCB3E28150982F2EfeC615b4f8D15Cf1A1C418Aa",
+    } as const satisfies DeploymentManifest),
+    84532: Object.freeze({
+      chainId: 84532,
+      chainName: "Base Sepolia",
+      deployedAt: "2026-05-31T20:48:00Z",
+      deployer: "0xdEBC95C65ACf33B6192981D132dd8B738Edb7ACc",
+      shroudfiStealth: "0x4BC88813b09dDD6Ab530261200D706B397EcD0AB",
+      shroudfiRegistrar: "0xDbBB9Ebc61b800a3d3309A867a87439F706C1207",
+      stealthSalt: "0x36f380f35c71197d157fceabdd952cfe52e65d056c5d5cf73d72f407147c0961",
+      registrarSalt: "0xad705f075979fd59f9335b1123d73d1f3c73955b9fad97c337b25b6054fdf95d",
+      announcer: "0x55649E01B5Df198D18D95b5cc5051630cfD45564",
+      registry: "0x6538E6bf4B0eBd30A8Ea093027Ac2422ce5d6538",
+      block: 42245336,
+      blockscoutUrl: "https://base-sepolia.blockscout.com",
+      mockERC20: "0xd2ab70198E62C958eCF81cc4AbD6c9108caa9649",
+      mockERC20Block: 42249078,
+      shroudfiRelayer: "0x598E511ad360D38d5895E426451DB5B384852b39",
+      relayerTreasury: "0x4B01C6eadD1663f5A7d792C24d8001c80EAE25b2",
+      relayerForwarder: "0xdEBC95C65ACf33B6192981D132dd8B738Edb7ACc",
+      relayerBlock: 42280627,
+      mockERC20Permit: "0xEA1F4516cB2D94E7A16bbc36fBECFB030d595dD5",
+      mockERC20PermitBlock: 42277427,
+      shroudfiEthRelayer: "0xC38530004A65993435E204dE6fEB666F6917a34E",
+      shroudfiEthRelayerBlock: 42328886,
+      ethRelayerOperator: "0xdEBC95C65ACf33B6192981D132dd8B738Edb7ACc",
+    } as const satisfies DeploymentManifest),
+} as const);
+
+export const SHROUDFI_STEALTH_BY_CHAIN: Readonly<Record<number, Address>> = Object.freeze({
+  8453: "0x4BC88813b09dDD6Ab530261200D706B397EcD0AB",
+  84532: "0x4BC88813b09dDD6Ab530261200D706B397EcD0AB",
+} as const);
+
+export const SHROUDFI_REGISTRAR_BY_CHAIN: Readonly<Record<number, Address>> = Object.freeze({
+  8453: "0xDbBB9Ebc61b800a3d3309A867a87439F706C1207",
+  84532: "0xDbBB9Ebc61b800a3d3309A867a87439F706C1207",
+} as const);
+
+export const MOCK_ERC20_BY_CHAIN: Readonly<Record<number, Address>> = Object.freeze({
+  84532: "0xd2ab70198E62C958eCF81cc4AbD6c9108caa9649",
+} as const);
+
+export const SHROUDFI_RELAYER_BY_CHAIN: Readonly<Record<number, Address>> = Object.freeze({
+  8453: "0x44f35ED32516AE8247aF5ec4ED5d5BEb501631d1",
+  84532: "0x598E511ad360D38d5895E426451DB5B384852b39",
+} as const);
+
+export const MOCK_ERC20_PERMIT_BY_CHAIN: Readonly<Record<number, Address>> = Object.freeze({
+  84532: "0xEA1F4516cB2D94E7A16bbc36fBECFB030d595dD5",
+} as const);
+
+export const SHROUDFI_ETH_RELAYER_BY_CHAIN: Readonly<Record<number, Address>> = Object.freeze({
+  8453: "0x477c497F17cED01ff9c01D8a9Da1c019AFb31a66",
+  84532: "0xC38530004A65993435E204dE6fEB666F6917a34E",
+} as const);

package/src/errors.ts

@@ -0,0 +1,13 @@
+export class UnknownChainError extends Error {
+  override readonly name: string = 'UnknownChainError';
+  constructor(chainId: number) {
+    super(`No ShroudFi deployment found for chainId ${chainId}`);
+  }
+}
+
+export class InvalidManifestError extends Error {
+  override readonly name: string = 'InvalidManifestError';
+  constructor(reason: string) {
+    super(`Invalid deployment manifest: ${reason}`);
+  }
+}

package/src/index.ts

@@ -0,0 +1,47 @@
+export { createTransport } from './create.js';
+export type { ShroudFiTransport, ShroudFiTransportConfig, SendOptions } from './types.js';
+export { base, baseSepolia } from './chains.js';
+export {
+  ERC5564_ANNOUNCER,
+  ERC6538_REGISTRY,
+  USDC_BY_CHAIN,
+  USDC_EIP712_DOMAIN_BY_CHAIN,
+  EIP3009_TOKENS_BY_CHAIN,
+} from './addresses.js';
+export type { Eip3009Token } from './addresses.js';
+export {
+  ERC5564AnnouncerAbi,
+  ERC6538RegistryAbi,
+  ShroudFiStealthAbi,
+  ShroudFiRelayerAbi,
+  ERC20Abi,
+  USDCAuthorizationAbi,
+} from './abis.js';
+export {
+  getShroudFiStealth,
+  getShroudFiRegistrar,
+  getMockERC20,
+  getMockERC20Permit,
+  getRelayer,
+  getEthRelayer,
+  getUSDC,
+  getUSDCDomain,
+  hasUSDC,
+  getEip3009Token,
+  getEip3009TokenBySymbol,
+  listEip3009Tokens,
+  getDeployment,
+  hasDeployment,
+  listDeployedChains,
+} from './deployments-helpers.js';
+export type { DeploymentManifest } from './deployments.js';
+export {
+  DEPLOYMENTS,
+  SHROUDFI_STEALTH_BY_CHAIN,
+  SHROUDFI_REGISTRAR_BY_CHAIN,
+  MOCK_ERC20_BY_CHAIN,
+  MOCK_ERC20_PERMIT_BY_CHAIN,
+  SHROUDFI_RELAYER_BY_CHAIN,
+  SHROUDFI_ETH_RELAYER_BY_CHAIN,
+} from './deployments.js';
+export { UnknownChainError, InvalidManifestError } from './errors.js';

package/src/types.ts

@@ -0,0 +1,19 @@
+import type { PublicClient, WalletClient, Chain, Transport } from 'viem';
+
+export interface ShroudFiTransportConfig {
+  readonly chain: 'base' | 'baseSepolia';
+  readonly rpcUrl?: string;
+  readonly privateKey?: `0x${string}`;
+}
+
+export interface ShroudFiTransport {
+  readonly publicClient: PublicClient<Transport, Chain>;
+  readonly walletClient?: WalletClient<Transport, Chain>;
+  readonly chain: Chain;
+}
+
+export interface SendOptions {
+  readonly maxFeePerGas?: bigint;
+  readonly maxPriorityFeePerGas?: bigint;
+  readonly nonce?: 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"]
+}