@upshiftfinance/sdk 0.0.0-stage → 0.1.0

package/lib/core/helpers/signer.js

@@ -0,0 +1,184 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isViemWalletClient = isViemWalletClient;
+exports.viemToEthersSigner = viemToEthersSigner;
+exports.normalizeSigner = normalizeSigner;
+exports.wrapSignerWithAttribution = wrapSignerWithAttribution;
+const ethers_1 = require("ethers");
+const attribution_1 = require("../attribution");
+/**
+ * Signer Compatibility Helpers
+ *
+ * Utilities for supporting both ethers and viem/wagmi signers.
+ * Provides conversion layer from viem WalletClient to ethers Signer.
+ */
+/**
+ * Type guard to check if a signer is from viem/wagmi
+ * @param signer The signer to check
+ * @returns True if the signer is a viem WalletClient
+ */
+function isViemWalletClient(signer) {
+    // Viem WalletClient has specific properties that ethers Signer doesn't
+    return !!(signer &&
+        typeof signer === 'object' &&
+        'account' in signer &&
+        'chain' in signer &&
+        'transport' in signer &&
+        typeof signer.writeContract === 'function');
+}
+function toBigInt(value) {
+    return value == null ? undefined : BigInt(value);
+}
+function toViemTransaction(tx) {
+    return {
+        to: tx.to ?? undefined,
+        data: tx.data,
+        accessList: tx.accessList,
+        value: toBigInt(tx.value),
+        gas: toBigInt(tx.gas),
+        gasPrice: toBigInt(tx.gasPrice),
+        maxFeePerGas: toBigInt(tx.maxFeePerGas),
+        maxPriorityFeePerGas: toBigInt(tx.maxPriorityFeePerGas),
+        nonce: tx.nonce == null ? undefined : Number(tx.nonce),
+    };
+}
+/**
+ * Convert a viem WalletClient to an ethers-compatible Signer.
+ *
+ * The account and chain are answered from the client itself, and
+ * transactions, personal messages and EIP-712 typed data are signed through
+ * the client's own `sendTransaction` / `signMessage` / `signTypedData`, so a
+ * local account (for example an embedded wallet built with
+ * `createWalletClient({ account, transport: http() })`) signs locally and
+ * broadcasts the raw transaction. Every other request goes to the client's
+ * transport.
+ *
+ * @param walletClient - Viem WalletClient from wagmi or viem
+ * @returns Ethers Signer that can be used with the SDK
+ */
+async function viemToEthersSigner(walletClient) {
+    if (!walletClient) {
+        throw new Error('WalletClient is required');
+    }
+    const { account, chain, transport } = walletClient;
+    if (!account) {
+        throw new Error('WalletClient must have an account');
+    }
+    const provider = new ethers_1.BrowserProvider({
+        request: async ({ method, params = [] }) => {
+            switch (method) {
+                case 'eth_accounts':
+                case 'eth_requestAccounts':
+                    return [account.address];
+                case 'eth_chainId':
+                    if (chain)
+                        return (0, ethers_1.toQuantity)(chain.id);
+                    break;
+                case 'eth_sendTransaction':
+                    return walletClient.sendTransaction({
+                        ...toViemTransaction(params[0]),
+                        account,
+                        chain,
+                    });
+                case 'personal_sign':
+                    return walletClient.signMessage({
+                        account,
+                        message: { raw: params[0] },
+                    });
+                case 'eth_signTypedData_v4':
+                    return walletClient.signTypedData({
+                        account,
+                        ...(typeof params[1] === 'string'
+                            ? JSON.parse(params[1])
+                            : params[1]),
+                    });
+            }
+            return transport.request({ method, params });
+        },
+    }, chain?.id);
+    return provider.getSigner(account.address);
+}
+/**
+ * Type guard to check if a signer is from ethers
+ * @param signer The signer to check
+ * @returns True if the signer is an ethers Signer or Wallet
+ */
+function isEthersSigner(signer) {
+    // Check for ethers Signer/Wallet properties
+    return (signer &&
+        typeof signer === 'object' &&
+        typeof signer.signMessage === 'function' &&
+        typeof signer.signTransaction === 'function' &&
+        (signer.provider !== undefined || signer._isSigner === true));
+}
+/**
+ * Normalize a signer to ensure it's ethers-compatible
+ * Accepts both ethers Signer and viem WalletClient
+ * @param signer Either an ethers Signer or viem WalletClient
+ * @returns Ethers-compatible Signer
+ */
+async function normalizeSigner(signer) {
+    // If it's already an ethers signer, return as-is
+    if (isEthersSigner(signer)) {
+        return signer;
+    }
+    // If it's a viem wallet client, convert it
+    if (isViemWalletClient(signer)) {
+        return viemToEthersSigner(signer);
+    }
+    // If we can't determine the type, throw an error
+    throw new Error('Invalid signer type. Expected ethers Signer, ethers Wallet, or viem WalletClient');
+}
+/**
+ * Wrap an ethers signer so every transaction it sends carries the active
+ * ERC-8021 attribution suffix (Base Builder Codes).
+ *
+ * Every ethers write in the SDK funnels through the wrapped signer's
+ * `sendTransaction`, so this single wrap attributes all vault writes. The
+ * wrapper is a Proxy — the caller's signer object is never mutated, so a
+ * signer reused outside the SDK sends unattributed transactions. Attribution
+ * state is read at send time, not wrap time; when no attribution is
+ * configured (see `IUpshiftBase.attribution`) the wrapper is a pass-through.
+ *
+ * Plain value transfers (no calldata) are never attributed, and calldata
+ * already ending in the ERC-8021 marker is left untouched. When the
+ * configured `chains` list requires a chain check and the transaction does
+ * not carry a `chainId`, the signer's provider network is consulted (one
+ * cached RPC call); if that lookup fails the transaction is sent
+ * unattributed.
+ *
+ * @param signer Normalized ethers Signer or Wallet.
+ * @returns A proxied signer with an attribution-aware `sendTransaction`.
+ */
+function wrapSignerWithAttribution(signer) {
+    return new Proxy(signer, {
+        get(target, prop) {
+            if (prop === 'sendTransaction') {
+                return async (tx) => {
+                    if (!(0, attribution_1.isAttributionEnabled)() || typeof tx?.data !== 'string') {
+                        return target.sendTransaction(tx);
+                    }
+                    let chainId = tx.chainId != null ? Number(tx.chainId) : undefined;
+                    if (chainId === undefined && target.provider) {
+                        try {
+                            chainId = Number((await target.provider.getNetwork()).chainId);
+                        }
+                        catch {
+                            // Unknown chain: fall through with chainId undefined. Under a
+                            // `chains` restriction that means no suffix — attributing a
+                            // chain we cannot identify risks breaking hardware-wallet
+                            // clear-signing for a gain we cannot confirm.
+                        }
+                    }
+                    const data = (0, attribution_1.appendAttributionSuffix)(tx.data, chainId);
+                    return target.sendTransaction(data === tx.data ? tx : { ...tx, data });
+                };
+            }
+            // `this`-bind reads to the target, not the proxy — ethers classes use
+            // private fields, which throw when methods run with a Proxy receiver.
+            const value = Reflect.get(target, prop, target);
+            return typeof value === 'function' ? value.bind(target) : value;
+        },
+    });
+}
+//# sourceMappingURL=signer.js.map

package/lib/core/helpers/swap-router.d.ts

@@ -0,0 +1,269 @@
+import { type Signer, type Wallet } from 'ethers';
+import type { IAddress, IContractRunner, IGetOriginInfoOptions, IOriginInfo, ISwapRouterDepositResult, ISwapRouterDepositResultOptions } from '../../types';
+/**
+ * Resolve the `SwapRouter` address for a chain.
+ *
+ * @param chainId - EVM chain ID.
+ * @returns The router address, or `undefined` if no SwapRouter is deployed.
+ * @example
+ * ```ts
+ * const router = getSwapRouterAddress(1);
+ * // '0xC11c6d8fD8FfFB2045d57b149125C44414d8160B'
+ * ```
+ */
+export declare function getSwapRouterAddress(chainId: number): IAddress | undefined;
+/**
+ * Resolve the human-readable display name of the `SwapRouter` periphery
+ * contract for a chain.
+ *
+ * The contract exposes no name on-chain, so this reads the SDK-maintained
+ * {@link SWAP_ROUTER_NAMES} registry. Intended for UI surfaces that label the
+ * contract a swap-and-deposit routes through (e.g. a "Router" row in a
+ * transaction overview) — display metadata only, never routing logic.
+ *
+ * @param chainId - EVM chain ID.
+ * @returns The display name (e.g. `'Upshift Swap Router'`), or `undefined`
+ *   when no SwapRouter is deployed on the chain — callers should omit the
+ *   label rather than show an address.
+ * @example
+ * ```ts
+ * const name = getSwapRouterName(1);
+ * // 'Upshift Swap Router'
+ * ```
+ */
+export declare function getSwapRouterName(chainId: number): string | undefined;
+/**
+ * Whether a vault is eligible for the any-token `SwapRouter` deposit surface
+ * (swap tokens). Address comparison is case-insensitive.
+ *
+ * This gates the (flag-controlled) swap-router deposit UI and can fail-fast a
+ * {@link swapRouterDeposit} call. It does **not** affect {@link vaultDeposit},
+ * which never swaps (see `getDepositRoute` for when it uses the router).
+ *
+ * @param vaultAddress - Upshift vault address.
+ * @returns `true` when the vault is in {@link SWAP_ROUTER_ELIGIBLE_VAULTS}.
+ * @deprecated Superseded by {@link getSwapRouterEligibleVaults}, which resolves
+ * eligibility from the backend `swaps_enabled` flag instead of this static
+ * snapshot. Kept functional as
+ * the zero-RPC sync fallback (seed data, fail-fast checks); migrate UI gates
+ * to the async resolver.
+ */
+export declare function isSwapRouterEligible(vaultAddress: IAddress): boolean;
+/**
+ * @deprecated Renamed to {@link isSwapRouterEligible} (itself now superseded by
+ * {@link getSwapRouterEligibleVaults}, the `swaps_enabled` resolver). The
+ * meaning also changed: it no longer implies `vaultDeposit` routes the vault
+ * through the SwapRouter (that behavior was removed) — it only reports
+ * swap-router *eligibility* for the opt-in deposit surface. Kept as an alias
+ * for one release; migrate to the async resolver.
+ */
+export declare const vaultUsesSwapRouter: typeof isSwapRouterEligible;
+/**
+ * Normalize an optional origin code to the value to send on-chain.
+ *
+ * Returns the caller-supplied code when present (an explicit all-zero
+ * sentinel opts one call out), otherwise the SDK instance's
+ * `attribution.originCode` when `chainId` is in
+ * {@link ORIGIN_ATTRIBUTION_CHAINS} (Ethereum mainnet only), otherwise the
+ * default (all-zero) sentinel from {@link ORIGIN_CODES}. Validates that any
+ * supplied code is exactly 32 bytes (66 chars including the `0x` prefix);
+ * the on-chain SwapRouter reverts with `InvalidOrigin` otherwise, but
+ * surfacing the failure here as a typed SDK error gives partners a
+ * grepable Sentry event instead of a generic `execution reverted`.
+ *
+ * @param provided - Optional caller-supplied origin code.
+ * @param chainId - Chain the deposit is sent on. The instance code is never
+ *   returned without it, or on a chain outside
+ *   {@link ORIGIN_ATTRIBUTION_CHAINS}.
+ * @returns The 32-byte origin code to pass to the router.
+ * @throws {@link UpshiftValidationError} when `provided` is not a 32-byte hex string.
+ */
+export declare function resolveOriginCode(provided?: `0x${string}`, chainId?: number): `0x${string}`;
+/**
+ * Resolves the real, post-execution outcome of a SwapRouter deposit from its
+ * mined transaction receipt. The SwapRouter contract itself emits no
+ * deposit/amount-out event — only the vault does, via its own `Deposit` event
+ * — so this decodes that log directly rather than trusting the pre-trade quote
+ * a UI shows before the user submits (the true post-swap amount depends on
+ * execution-time price and can differ from that estimate).
+ *
+ * Works for both vault generations without the caller resolving the version
+ * first: evm-1 (ERC-4626-style `Deposit(sender, owner, assets, shares)`) and
+ * evm-2 (`Deposit(assetIn, amountIn, shares, senderAddr, receiverAddr)`) have
+ * different event signatures (different topic0), so both are registered and
+ * whichever matches the vault's actual log is decoded.
+ *
+ * @param signer - ethers `Signer` or `Wallet` connected to a provider (used
+ *   read-only here — no transaction is sent).
+ * @param options - {@link ISwapRouterDepositResultOptions}.
+ * @returns The decoded {@link ISwapRouterDepositResult}, or `null` if the
+ *   receipt isn't found yet or carries no `Deposit` log from `vault` (e.g. the
+ *   hash is wrong, or the tx hasn't mined).
+ * @throws {@link UpshiftValidationError} if `signer` has no connected provider.
+ * @worstCaseRpcCalls 1 — a single `getTransactionReceipt` call; decoding is
+ *   local.
+ * @example
+ * ```ts
+ * const hash = await upshiftSdk.evm.swapRouterDeposit({ ... });
+ * const result = await upshiftSdk.evm.getSwapRouterDepositResult({
+ *   txHash: hash,
+ *   vault: '0x74ad2f789ed583dbd141bbdafc673fe1f033718b',
+ * });
+ * // result?.amountOut — actual reference-asset amount received after the swap
+ * ```
+ */
+export declare function getSwapRouterDepositResult(signer: Signer | Wallet, { txHash, vault }: ISwapRouterDepositResultOptions): Promise<ISwapRouterDepositResult | null>;
+/**
+ * Read how an origin code is registered on a chain's `SwapRouter`: whether it
+ * exists, its origin fee, and its fee collector.
+ *
+ * Check a partner code with this before configuring it as
+ * `attribution.originCode` — the router reverts every deposit carrying an
+ * unregistered code with `InvalidOrigin`. A code is registered when its
+ * collector is non-zero (`addOrigin` always sets one); a zero-fee code is
+ * still registered but never emits `OriginFeeApplied`. Cached per (chain,
+ * router, code) for 5 minutes.
+ *
+ * @param options - {@link IGetOriginInfoOptions}.
+ * @returns {@link IOriginInfo}; `registered: false` with a zero fee and
+ *   collector, and no RPC, on a chain with no SwapRouter deployment.
+ * @throws {@link UpshiftValidationError} when `originCode` is not a 32-byte hex
+ *   string.
+ * @throws {@link UpshiftSDKError} when the `origins(bytes32)` read fails.
+ * @worstCaseRpcCalls 1 — one `origins(bytes32)` call; none on a cache hit.
+ * @example
+ * ```ts
+ * const info = await getOriginInfo({ chainId: 1, originCode, rpcUrl });
+ * if (!info.registered) throw new Error('origin code is not registered');
+ * ```
+ */
+export declare function getOriginInfo({ chainId, originCode, rpcUrl, }: IGetOriginInfoOptions): Promise<IOriginInfo>;
+/**
+ * {@link getOriginInfo} without input validation, reading through a caller
+ * runner (created lazily, only on a cache miss). Shared with the deposit-route
+ * resolver so both hit the same cache entry.
+ * @internal
+ */
+export declare function readOriginInfo(chainId: number, originCode: `0x${string}`, runner: () => IContractRunner): Promise<IOriginInfo>;
+/**
+ * Read whether a Tokenized Vault V2 restricts depositors with a senders
+ * whitelist (KYC), cached for 5 minutes like the router reads.
+ *
+ * The v2 SwapRouter accepts any vault, so this is the check that keeps KYC
+ * vaults off the router: such a vault only accepts deposits from whitelisted
+ * senders, so a router deposit either reverts `SenderNotWhitelisted` or, on an
+ * implementation that checks only `msg.sender`, would let any wallet deposit
+ * through a whitelisted router.
+ *
+ * @param runner - Provider or signer used for the read.
+ * @param chainId - Chain the vault is on (part of the cache key).
+ * @param vault - Tokenized Vault V2 address.
+ * @returns `true` when `sendersWhitelistAddress()` is non-zero.
+ * @throws When the `sendersWhitelistAddress()` read fails. Callers wrap it in
+ *   their own error handling.
+ * @worstCaseRpcCalls 1 — one `sendersWhitelistAddress()` call; none on a cache hit.
+ * @internal
+ */
+export declare function readVaultHasSendersWhitelist(runner: IContractRunner, chainId: number, vault: IAddress): Promise<boolean>;
+/**
+ * Read whether a chain's `SwapRouter` is paused (`isPaused()`), cached for 15
+ * seconds. Every router entry point (`deposit`, `swapAndDeposit`,
+ * `depositNativeToken`) reverts with `ContractIsPaused` while the router is
+ * paused, so callers check this before routing a deposit or sending an
+ * approval to the router.
+ *
+ * @param runner - Contract runner (provider or signer) used for the read.
+ * @param chainId - EVM chain ID.
+ * @returns `true` while the router is paused; `false` when it is not, or on a
+ *   chain with no SwapRouter (no RPC).
+ * @throws When the `isPaused()` read fails. Callers wrap it in
+ *   {@link UpshiftSDKError}.
+ * @worstCaseRpcCalls 1 — one `isPaused()` call; none on a cache hit.
+ * @internal
+ */
+export declare function readSwapRouterPaused(runner: IContractRunner, chainId: number): Promise<boolean>;
+/**
+ * Resolve the ERC-20 tokens currently whitelisted for the `SwapRouter` on a
+ * chain — the any-token set a UI can offer as swap-and-deposit inputs.
+ *
+ * The router exposes its allowlist only as `mapping(address => bool)
+ * whitelistedTokens` with **no on-chain enumeration**, so this cannot be a
+ * single view call. It runs in two stages:
+ *  1. Scan the router's `TokenEnabled(address)` event history (from the chain's
+ *     {@link SWAP_ROUTER_DEPLOY_BLOCKS} floor, in `eth_getLogs` chunks sized by
+ *     {@link determineBlockSkipInternal}) to reconstruct the candidate set of
+ *     every token ever enabled.
+ *  2. Re-read `whitelistedTokens(token)` for each candidate — batched via
+ *     Multicall3 where verified, else per-call — and keep only those the
+ *     mapping currently returns `true` for. This step makes later disables (and
+ *     disable-then-re-enable) correct without replaying `TokenDisabled`, and is
+ *     the fail-closed source of truth: a token surfaces only on a definite
+ *     on-chain `true`.
+ *
+ * The resolved list is cached per chain for 5 minutes — the allowlist changes
+ * only via an admin `enableToken`/`disableToken` transaction, so a short TTL
+ * keeps the (multi-RPC) scan off the hot path without going stale for long.
+ *
+ * @param chainId - EVM chain ID. Chains without a {@link SWAP_ROUTER_ADDRESSES}
+ *   entry resolve to `[]` with no RPC.
+ * @param options - `rpcUrl` (required) must point at `chainId`'s network;
+ *   `fromBlock` overrides the default deploy-block scan floor (e.g. to widen a
+ *   scan on a chain missing from {@link SWAP_ROUTER_DEPLOY_BLOCKS}).
+ * @returns Checksummed addresses of the currently-whitelisted tokens, deduped.
+ *   Empty when no router is deployed or none are enabled. Callers still filter
+ *   out a given vault's natively-accepted assets (those deposit without a swap).
+ * @throws UpshiftValidationError when `rpcUrl` is missing/empty.
+ * @throws UpshiftSDKError when an `eth_getLogs` chunk fails — surfaced (not
+ *   swallowed) so a partial scan never masquerades as a complete allowlist.
+ * @worstCaseRpcCalls 1 `eth_blockNumber` + ⌈(head − deploy block) ÷ window⌉
+ *   `eth_getLogs` chunks + 1 Multicall3 `eth_call`, where `window` is
+ *   {@link determineBlockSkipInternal} (10k blocks on mainnet, 1k on
+ *   HyperEVM). The chunk count grows with the router's on-chain age (on
+ *   mainnet roughly one more chunk every ~1.4 days since the deploy block,
+ *   already in the tens), not with candidate count. Chunks run at most 8 at a
+ *   time, so a cold scan never opens more than 8 concurrent requests.
+ * @example
+ * ```ts
+ * const tokens = await getSwapRouterWhitelistedTokens(1, {
+ *   rpcUrl: 'https://eth-mainnet.example/v2/KEY',
+ * });
+ * // ['0xA0b8…', '0xdAC1…', '0xC02a…', '0x2260…']  (USDC, USDT, WETH, WBTC)
+ * ```
+ */
+export declare function getSwapRouterWhitelistedTokens(chainId: number, options: {
+    rpcUrl: string;
+    fromBlock?: number;
+}): Promise<IAddress[]>;
+/**
+ * Resolve the vaults that offer the any-token `SwapRouter` deposit surface
+ * (swap tokens) on a chain: every vault the Upshift API marks `swaps_enabled`,
+ * on a chain with a SwapRouter.
+ *
+ * SwapRouter v2 has no on-chain vault registry, so the backend `swaps_enabled`
+ * flag is the source of truth. It fails closed: a vault without the flag, or
+ * with it `false`, is excluded. It only gates swap tokens — a normal deposit
+ * of an asset the vault accepts routes through the router whatever the flag
+ * (see {@link getDepositRoute}).
+ *
+ * App-level policy (e.g. excluding vaults with their own OVault deposit flow)
+ * remains the caller's responsibility.
+ *
+ * @param chainId - EVM chain ID. Chains without a {@link SWAP_ROUTER_ADDRESSES}
+ *   entry resolve to `[]` with no request.
+ * @param _options - Kept for compatibility; `rpcUrl` and `fromBlock` are no
+ *   longer read.
+ * @returns Checksummed addresses of the chain's `swaps_enabled` vaults. Empty
+ *   when no router is deployed or no vault has the flag.
+ * @throws When the Upshift API vault-list request fails.
+ * @worstCaseRpcCalls 0 — one Upshift API request (the vault list, cached for
+ *   15 minutes), no RPC.
+ * @example
+ * ```ts
+ * const vaults = await getSwapRouterEligibleVaults(1);
+ * // ['0x74aD…718b', '0xE9B7…9D32']
+ * ```
+ */
+export declare function getSwapRouterEligibleVaults(chainId: number, _options?: {
+    rpcUrl?: string;
+    fromBlock?: number;
+}): Promise<IAddress[]>;