@shroud-fi/payments 0.1.0

package/dist/esm/payments.js

@@ -0,0 +1,261 @@
+/**
+ * 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 { decodeEventLog } from 'viem';
+import { generateStealthAddress } from '@shroud-fi/core';
+import { ShroudFiStealthAbi } from '@shroud-fi/transport';
+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) {
+    return `0x${viewTag.toString(16).padStart(2, '0')}`;
+}
+/**
+ * Convert a Uint8Array ephemeral pubkey to a 0x-prefixed hex string.
+ */
+function ephemeralPubKeyToHex(bytes) {
+    let hex = '0x';
+    for (const b of bytes) {
+        hex += b.toString(16).padStart(2, '0');
+    }
+    return 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) {
+    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, publicClient, ephemeralPubKey, viewTag, expectedToken) {
+    const receipt = 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;
+                // 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, contractAddress, metaAddress, valueWei, options) {
+    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;
+    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 = {
+        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;
+    try {
+        // viem's writeContract has a complex union signature - cast at the boundary.
+        txHash = (await wallet.writeContract(writeArgs));
+    }
+    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');
+}
+/**
+ * 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, contractAddress, metaAddress, token, amount, options) {
+    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;
+    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 = {
+        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;
+    try {
+        txHash = (await wallet.writeContract(writeArgs));
+    }
+    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);
+}
+//# sourceMappingURL=payments.js.map

package/dist/esm/payments.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"payments.js","sourceRoot":"","sources":["../../src/payments.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAE,cAAc,EAAE,MAAM,MAAM,CAAC;AACtC,OAAO,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAEzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAO1D,OAAO,EACL,wBAAwB,EACxB,eAAe,EACf,qBAAqB,EACrB,YAAY,GACb,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAExD;;;GAGG;AACH,SAAS,eAAe,CAAC,OAAe;IACtC,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAmB,CAAC;AACvE,CAAC;AAED;;GAEG;AACH,SAAS,oBAAoB,CAAC,KAAiB;IAC7C,IAAI,GAAG,GAAG,IAAI,CAAC;IACf,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,GAAG,IAAI,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACzC,CAAC;IACD,OAAO,GAAU,CAAC;AACpB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CACnC,WAA+B;IAE/B,IAAI,MAAM,CAAC;IACX,IAAI,CAAC;QACH,MAAM,GAAG,sBAAsB,CAAC,WAAW,CAAC,CAAC;IAC/C,CAAC;IAAC,MAAM,CAAC;QACP,wEAAwE;QACxE,MAAM,IAAI,qBAAqB,EAAE,CAAC;IACpC,CAAC;IACD,OAAO;QACL,cAAc,EAAE,MAAM,CAAC,cAAc;QACrC,eAAe,EAAE,oBAAoB,CAAC,MAAM,CAAC,eAAe,CAAC;QAC7D,OAAO,EAAE,MAAM,CAAC,OAAO;KACxB,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,KAAK,UAAU,mBAAmB,CAChC,MAAY,EACZ,YAA0B,EAC1B,eAAoB,EACpB,OAAe,EACf,aAAsB;IAEtB,MAAM,OAAO,GACX,MAAM,YAAY,CAAC,qBAAqB,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IAE7D,KAAK,MAAM,GAAG,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;QAC/B,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,cAAc,CAAC;gBAC7B,GAAG,EAAE,kBAAkB;gBACvB,IAAI,EAAE,GAAG,CAAC,IAAI;gBACd,MAAM,EAAE,GAAG,CAAC,MAAM;gBAClB,SAAS,EAAE,gBAAgB;aAC5B,CAAC,CAAC;YACH,IAAI,OAAO,CAAC,SAAS,KAAK,gBAAgB,EAAE,CAAC;gBAC3C,MAAM,IAAI,GAAG,OAAO,CAAC,IAIpB,CAAC;gBACF,6DAA6D;gBAC7D,KAAK,aAAa,CAAC;gBACnB,KAAK,IAAI,CAAC,MAAM,CAAC,CAAC,4DAA4D;gBAC9E,OAAO;oBACL,MAAM;oBACN,cAAc,EAAE,IAAI,CAAC,cAAc;oBACnC,eAAe;oBACf,OAAO;oBACP,WAAW,EAAE,OAAO,CAAC,WAAW;oBAChC,KAAK,EAAE,IAAI,CAAC,KAAK;iBAClB,CAAC;YACJ,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,uCAAuC;YACvC,SAAS;QACX,CAAC;IACH,CAAC;IACD,MAAM,IAAI,YAAY,CAAC,2CAA2C,CAAC,CAAC;AACtE,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,SAA4B,EAC5B,eAAwB,EACxB,WAA+B,EAC/B,QAAgB,EAChB,OAAqB;IAErB,IAAI,QAAQ,KAAK,EAAE,EAAE,CAAC;QACpB,MAAM,IAAI,eAAe,EAAE,CAAC;IAC9B,CAAC;IACD,MAAM,MAAM,GAAG,SAAS,CAAC,YAAY,CAAC;IACtC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,wBAAwB,EAAE,CAAC;IACvC,CAAC;IACD,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;IAC/B,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,wBAAwB,EAAE,CAAC;IACvC,CAAC;IAED,MAAM,QAAQ,GAAG,qBAAqB,CAAC,WAAW,CAAC,CAAC;IACpD,MAAM,WAAW,GAAG,eAAe,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IAEtD,MAAM,aAAa,GAAG,OAAO,EAAE,aAAa,IAAI,sBAAsB,CAAC;IACvE,IAAI,GAAuB,CAAC;IAC5B,IAAI,CAAC;QACH,MAAM,SAAS,GAAG,MAAM,SAAS,CAAC,YAAY,CAAC,mBAAmB,CAAC;YACjE,OAAO,EAAE,eAAe;YACxB,GAAG,EAAE,kBAAkB;YACvB,YAAY,EAAE,SAAS;YACvB,IAAI,EAAE,CAAC,QAAQ,CAAC,cAAc,EAAE,QAAQ,CAAC,eAAe,EAAE,WAAW,CAAC;YACtE,KAAK,EAAE,QAAQ;YACf,OAAO,EAAE,OAAO,CAAC,OAAO;SACzB,CAAC,CAAC;QACH,sEAAsE;QACtE,GAAG,GAAG,CAAC,SAAS,GAAG,aAAa,GAAG,GAAG,CAAC,GAAG,IAAI,CAAC;IACjD,CAAC;IAAC,MAAM,CAAC;QACP,yEAAyE;QACzE,gDAAgD;QAChD,GAAG,GAAG,SAAS,CAAC;IAClB,CAAC;IAED,MAAM,SAAS,GAA4B;QACzC,OAAO,EAAE,eAAe;QACxB,GAAG,EAAE,kBAAkB;QACvB,YAAY,EAAE,SAAS;QACvB,IAAI,EAAE,CAAC,QAAQ,CAAC,cAAc,EAAE,QAAQ,CAAC,eAAe,EAAE,WAAW,CAAC;QACtE,KAAK,EAAE,QAAQ;QACf,OAAO;QACP,KAAK,EAAE,SAAS,CAAC,KAAK;KACvB,CAAC;IACF,IAAI,GAAG,KAAK,SAAS;QAAE,SAAS,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC;IAC9C,IAAI,OAAO,EAAE,YAAY,KAAK,SAAS;QAAE,SAAS,CAAC,cAAc,CAAC,GAAG,OAAO,CAAC,YAAY,CAAC;IAC1F,IAAI,OAAO,EAAE,oBAAoB,KAAK,SAAS;QAC7C,SAAS,CAAC,sBAAsB,CAAC,GAAG,OAAO,CAAC,oBAAoB,CAAC;IACnE,IAAI,OAAO,EAAE,KAAK,KAAK,SAAS;QAAE,SAAS,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC;IAErE,IAAI,MAAY,CAAC;IACjB,IAAI,CAAC;QACH,6EAA6E;QAC7E,MAAM,GAAG,CAAC,MAAO,MAAM,CAAC,aAA+C,CACrE,SAAS,CACV,CAAS,CAAC;IACb,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,kDAAkD;QAClD,IAAI,GAAG,YAAY,YAAY;YAAE,MAAM,GAAG,CAAC;QAC3C,MAAM,IAAI,YAAY,CAAC,sCAAsC,CAAC,CAAC;IACjE,CAAC;IAED,IAAI,CAAC;QACH,MAAM,SAAS,CAAC,YAAY,CAAC,yBAAyB,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IAC3E,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,YAAY,CAAC,uCAAuC,CAAC,CAAC;IAClE,CAAC;IAED,OAAO,mBAAmB,CACxB,MAAM,EACN,SAAS,CAAC,YAAY,EACtB,QAAQ,CAAC,eAAe,EACxB,QAAQ,CAAC,OAAO,EAChB,4CAAuD,CACxD,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,SAA4B,EAC5B,eAAwB,EACxB,WAA+B,EAC/B,KAAc,EACd,MAAc,EACd,OAAqB;IAErB,IAAI,MAAM,KAAK,EAAE,EAAE,CAAC;QAClB,MAAM,IAAI,eAAe,EAAE,CAAC;IAC9B,CAAC;IACD,MAAM,MAAM,GAAG,SAAS,CAAC,YAAY,CAAC;IACtC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,wBAAwB,EAAE,CAAC;IACvC,CAAC;IACD,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;IAC/B,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,wBAAwB,EAAE,CAAC;IACvC,CAAC;IAED,MAAM,QAAQ,GAAG,qBAAqB,CAAC,WAAW,CAAC,CAAC;IACpD,MAAM,WAAW,GAAG,eAAe,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IAEtD,MAAM,aAAa,GAAG,OAAO,EAAE,aAAa,IAAI,sBAAsB,CAAC;IACvE,IAAI,GAAuB,CAAC;IAC5B,IAAI,CAAC;QACH,MAAM,SAAS,GAAG,MAAM,SAAS,CAAC,YAAY,CAAC,mBAAmB,CAAC;YACjE,OAAO,EAAE,eAAe;YACxB,GAAG,EAAE,kBAAkB;YACvB,YAAY,EAAE,WAAW;YACzB,IAAI,EAAE;gBACJ,QAAQ,CAAC,cAAc;gBACvB,KAAK;gBACL,MAAM;gBACN,QAAQ,CAAC,eAAe;gBACxB,WAAW;aACZ;YACD,OAAO,EAAE,OAAO,CAAC,OAAO;SACzB,CAAC,CAAC;QACH,sEAAsE;QACtE,GAAG,GAAG,CAAC,SAAS,GAAG,aAAa,GAAG,GAAG,CAAC,GAAG,IAAI,CAAC;IACjD,CAAC;IAAC,MAAM,CAAC;QACP,GAAG,GAAG,SAAS,CAAC;IAClB,CAAC;IAED,MAAM,SAAS,GAA4B;QACzC,OAAO,EAAE,eAAe;QACxB,GAAG,EAAE,kBAAkB;QACvB,YAAY,EAAE,WAAW;QACzB,IAAI,EAAE;YACJ,QAAQ,CAAC,cAAc;YACvB,KAAK;YACL,MAAM;YACN,QAAQ,CAAC,eAAe;YACxB,WAAW;SACZ;QACD,OAAO;QACP,KAAK,EAAE,SAAS,CAAC,KAAK;KACvB,CAAC;IACF,IAAI,GAAG,KAAK,SAAS;QAAE,SAAS,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC;IAC9C,IAAI,OAAO,EAAE,YAAY,KAAK,SAAS;QAAE,SAAS,CAAC,cAAc,CAAC,GAAG,OAAO,CAAC,YAAY,CAAC;IAC1F,IAAI,OAAO,EAAE,oBAAoB,KAAK,SAAS;QAC7C,SAAS,CAAC,sBAAsB,CAAC,GAAG,OAAO,CAAC,oBAAoB,CAAC;IACnE,IAAI,OAAO,EAAE,KAAK,KAAK,SAAS;QAAE,SAAS,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC;IAErE,IAAI,MAAY,CAAC;IACjB,IAAI,CAAC;QACH,MAAM,GAAG,CAAC,MAAO,MAAM,CAAC,aAA+C,CACrE,SAAS,CACV,CAAS,CAAC;IACb,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,GAAG,YAAY,YAAY;YAAE,MAAM,GAAG,CAAC;QAC3C,MAAM,IAAI,YAAY,CAAC,yCAAyC,CAAC,CAAC;IACpE,CAAC;IAED,IAAI,CAAC;QACH,MAAM,SAAS,CAAC,YAAY,CAAC,yBAAyB,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IAC3E,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,YAAY,CAAC,0CAA0C,CAAC,CAAC;IACrE,CAAC;IAED,OAAO,mBAAmB,CACxB,MAAM,EACN,SAAS,CAAC,YAAY,EACtB,QAAQ,CAAC,eAAe,EACxB,QAAQ,CAAC,OAAO,EAChB,KAAK,CACN,CAAC;AACJ,CAAC"}

package/dist/esm/send-to-wallet.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 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 } from 'viem';
+import type { StealthMetaAddress } from '@shroud-fi/core';
+import type { ShroudFiTransport } from '@shroud-fi/transport';
+import type { PaymentReceipt, SendOptions } from './types.js';
+/**
+ * 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;
+};
+/**
+ * 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 declare function lookupMetaAddress(transport: ShroudFiTransport, recipientWallet: Address): Promise<StealthMetaAddress | null>;
+/**
+ * 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 declare function sendToWallet(transport: ShroudFiTransport, recipientWallet: Address, asset: SendToWalletAsset, amount: bigint, options?: SendOptions): Promise<PaymentReceipt>;
+//# sourceMappingURL=send-to-wallet.d.ts.map

package/dist/esm/send-to-wallet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"send-to-wallet.d.ts","sourceRoot":"","sources":["../../src/send-to-wallet.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAqB,MAAM,MAAM,CAAC;AAEvD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAM1D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAE9D,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAY9D;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GAAG,KAAK,GAAG;IAAE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC;AAKpE;;;;;;;;GAQG;AACH,wBAAsB,iBAAiB,CACrC,SAAS,EAAE,iBAAiB,EAC5B,eAAe,EAAE,OAAO,GACvB,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAmCpC;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,YAAY,CAChC,SAAS,EAAE,iBAAiB,EAC5B,eAAe,EAAE,OAAO,EACxB,KAAK,EAAE,iBAAiB,EACxB,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,WAAW,GACpB,OAAO,CAAC,cAAc,CAAC,CAsBzB"}

package/dist/esm/send-to-wallet.js

@@ -0,0 +1,100 @@
+/**
+ * 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 { hexToBytes, isAddress } from 'viem';
+import { ERC6538_REGISTRY, ERC6538RegistryAbi, getShroudFiStealth, } from '@shroud-fi/transport';
+import { sendETHPayment, sendERC20Payment } from './payments.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;
+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, recipientWallet) {
+    if (!isAddress(recipientWallet) || recipientWallet === ZERO_ADDRESS) {
+        throw new InvalidRecipientError();
+    }
+    const raw = (await transport.publicClient.readContract({
+        address: ERC6538_REGISTRY,
+        abi: ERC6538RegistryAbi,
+        functionName: 'stealthMetaAddressOf',
+        args: [recipientWallet, SCHEME_ID],
+    }));
+    // 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, recipientWallet, asset, amount, options) {
+    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);
+}
+//# sourceMappingURL=send-to-wallet.js.map

package/dist/esm/send-to-wallet.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"send-to-wallet.js","sourceRoot":"","sources":["../../src/send-to-wallet.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,MAAM,CAAC;AAE7C,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEjE,OAAO,EACL,qBAAqB,EACrB,yBAAyB,EACzB,0BAA0B,GAC3B,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEzD,gFAAgF;AAChF,sEAAsE;AACtE,MAAM,qBAAqB,GAAG,CAAC,CAAC;AAShC,MAAM,qBAAqB,GAAG,EAAE,CAAC;AACjC,MAAM,2BAA2B,GAAG,qBAAqB,GAAG,CAAC,CAAC;AAE9D;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,SAA4B,EAC5B,eAAwB;IAExB,IAAI,CAAC,SAAS,CAAC,eAAe,CAAC,IAAI,eAAe,KAAK,YAAY,EAAE,CAAC;QACpE,MAAM,IAAI,qBAAqB,EAAE,CAAC;IACpC,CAAC;IACD,MAAM,GAAG,GAAG,CAAC,MACX,SAAS,CAAC,YACX,CAAC,YAAY,CAAC;QACb,OAAO,EAAE,gBAAgB;QACzB,GAAG,EAAE,kBAAkB;QACvB,YAAY,EAAE,sBAAsB;QACpC,IAAI,EAAE,CAAC,eAAe,EAAE,SAAS,CAAC;KACnC,CAAC,CAAQ,CAAC;IAEX,6DAA6D;IAC7D,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,CAAC,MAAM,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAEjD,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC;IAC9B,IAAI,KAAK,CAAC,MAAM,KAAK,2BAA2B,EAAE,CAAC;QACjD,MAAM,IAAI,yBAAyB,EAAE,CAAC;IACxC,CAAC;IACD,MAAM,cAAc,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,qBAAqB,CAAC,CAAC;IAC7D,MAAM,aAAa,GAAG,KAAK,CAAC,KAAK,CAAC,qBAAqB,CAAC,CAAC;IACzD,MAAM,OAAO,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC;IAClC,MAAM,OAAO,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC;IACjC,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QACzC,MAAM,IAAI,yBAAyB,EAAE,CAAC;IACxC,CAAC;IACD,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QACzC,MAAM,IAAI,yBAAyB,EAAE,CAAC;IACxC,CAAC;IACD,OAAO;QACL,cAAc;QACd,aAAa;QACb,QAAQ,EAAE,qBAAqB;KAChC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,SAA4B,EAC5B,eAAwB,EACxB,KAAwB,EACxB,MAAc,EACd,OAAqB;IAErB,IAAI,CAAC,SAAS,CAAC,eAAe,CAAC,IAAI,eAAe,KAAK,YAAY,EAAE,CAAC;QACpE,MAAM,IAAI,qBAAqB,EAAE,CAAC;IACpC,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,iBAAiB,CAAC,SAAS,EAAE,eAAe,CAAC,CAAC;IACjE,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QAClB,MAAM,IAAI,0BAA0B,CAAC,eAAe,CAAC,CAAC;IACxD,CAAC;IAED,MAAM,eAAe,GAAG,kBAAkB,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAE/D,IAAI,KAAK,KAAK,KAAK,EAAE,CAAC;QACpB,OAAO,cAAc,CAAC,SAAS,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;IAC3E,CAAC;IACD,OAAO,gBAAgB,CACrB,SAAS,EACT,eAAe,EACf,IAAI,EACJ,KAAK,CAAC,KAAK,EACX,MAAM,EACN,OAAO,CACR,CAAC;AACJ,CAAC"}

package/dist/esm/sweep.d.ts

@@ -0,0 +1,47 @@
+import type { Address, Hex } from 'viem';
+import type { ShroudFiTransport } from '@shroud-fi/transport';
+import type { SweepReceipt, SendOptions } from './types.js';
+/**
+ * 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 declare function sweepETH(transport: ShroudFiTransport, stealthPrivateKey: Hex, destination: Address, options?: SendOptions): Promise<SweepReceipt>;
+/**
+ * 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 declare function sweepERC20(transport: ShroudFiTransport, stealthPrivateKey: Hex, token: Address, destination: Address, options?: SendOptions): Promise<SweepReceipt>;
+//# sourceMappingURL=sweep.d.ts.map

package/dist/esm/sweep.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sweep.d.ts","sourceRoot":"","sources":["../../src/sweep.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,MAAM,CAAC;AAIzC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AA4F5D;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,QAAQ,CAC5B,SAAS,EAAE,iBAAiB,EAC5B,iBAAiB,EAAE,GAAG,EACtB,WAAW,EAAE,OAAO,EACpB,OAAO,CAAC,EAAE,WAAW,GACpB,OAAO,CAAC,YAAY,CAAC,CA2EvB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,UAAU,CAC9B,SAAS,EAAE,iBAAiB,EAC5B,iBAAiB,EAAE,GAAG,EACtB,KAAK,EAAE,OAAO,EACd,WAAW,EAAE,OAAO,EACpB,OAAO,CAAC,EAAE,WAAW,GACpB,OAAO,CAAC,YAAY,CAAC,CAsFvB"}