augustdigital-sdk 8.20.1

package/lib/core/helpers/signer.js

@@ -0,0 +1,145 @@
+"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');
+}
+/**
+ * Convert a viem WalletClient to an ethers-compatible Signer
+ * Uses the walletClient as a provider and wraps it for ethers compatibility
+ * @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');
+    }
+    // Create an EIP-1193 provider from the wallet client
+    const { account, chain, transport } = walletClient;
+    if (!account) {
+        throw new Error('WalletClient must have an account');
+    }
+    // Create a custom transport that uses the walletClient
+    const provider = new ethers_1.BrowserProvider({
+        request: async ({ method, params }) => {
+            // Use the wallet client's transport for all requests
+            if (method === 'eth_sendTransaction') {
+                // For transactions, use writeContract or sendTransaction
+                const [tx] = params;
+                return walletClient.sendTransaction({
+                    ...tx,
+                    account,
+                    chain,
+                });
+            }
+            // For all other requests, use the transport directly
+            return transport({ chain }).request({ method, params });
+        },
+    }, chain?.id);
+    // Get the signer from the provider
+    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 `IAugustBase.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).
+ *
+ * @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.getAttributionSuffix)() || 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, which
+                            // appends regardless of a `chains` restriction —
+                            // over-attribution is harmless, under-attribution loses data.
+                        }
+                    }
+                    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,211 @@
+import { type Signer, type Wallet } from 'ethers';
+import type { IAddress, 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);
+ * // '0xAC771209FF2b71EECfF6E85a9AD01db8Ff2618B0'
+ * ```
+ */
+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
+ * (the SwapRouter is `enableVault`-ed for it on-chain). 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 is always the native/multiasset/adapter path.
+ *
+ * @param vaultAddress - August vault address.
+ * @returns `true` when the vault is in {@link SWAP_ROUTER_ELIGIBLE_VAULTS}.
+ * @deprecated Superseded by {@link getSwapRouterEligibleVaults}, which resolves
+ * eligibility from the router's on-chain `VaultEnabled` history + current
+ * `vaultInfo` registration 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 on-chain-derived 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, 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.
+ * @returns The 32-byte origin code to pass to the router.
+ * @throws {@link AugustValidationError} when `provided` is not a 32-byte hex string.
+ */
+export declare function resolveOriginCode(provided?: `0x${string}`): `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 AugustValidationError} if `signer` has no connected provider.
+ * @worstCaseRpcCalls 1 — a single `getTransactionReceipt` call; decoding is
+ *   local.
+ * @example
+ * ```ts
+ * const hash = await augustSdk.evm.swapRouterDeposit({ ... });
+ * const result = await augustSdk.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>;
+/**
+ * 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 AugustValidationError when `rpcUrl` is missing/empty.
+ * @throws AugustSDKError when an `eth_getLogs` chunk fails — surfaced (not
+ *   swallowed) so a partial scan never masquerades as a complete allowlist.
+ * @worstCaseRpcCalls On mainnet, 1 `eth_blockNumber` + ~4 `eth_getLogs` chunks
+ *   (router-lifetime ÷ 50k-block window) + 1 Multicall3 `eth_call` ≈ 6; scales
+ *   with the router's on-chain age, not with candidate count.
+ * @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 currently eligible for the any-token `SwapRouter` deposit
+ * surface on a chain — i.e. every vault the router has `enableVault`-ed that is
+ * still registered on-chain.
+ *
+ * The router stores registrations as `mapping(address => VaultInfo) vaultInfo`
+ * with **no on-chain enumeration**, so (exactly like
+ * {@link getSwapRouterWhitelistedTokens}) this runs in two stages:
+ *  1. Scan the router's `VaultEnabled(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 vault ever enabled.
+ *  2. Re-read `vaultInfo(vault)` for each candidate — batched via Multicall3
+ *     where verified, else per-call — and keep only those whose
+ *     `referenceAsset != address(0)` (an unregistered vault reverts with
+ *     `InvalidVault` at deposit time). This makes later disables correct
+ *     without replaying `VaultDisabled`, and is the fail-closed source of
+ *     truth: a vault surfaces only on a definite on-chain registration.
+ *
+ * This is the dynamic successor to the static
+ * {@link SWAP_ROUTER_ELIGIBLE_VAULTS} snapshot / {@link isSwapRouterEligible}.
+ * It reports **on-chain eligibility only** — app-level policy (e.g. excluding
+ * OVault-enabled vaults that have their own deposit flow) remains the caller's
+ * responsibility, as does the flag gating of the UI surface.
+ *
+ * The resolved list is cached per chain for 5 minutes — registrations change
+ * only via an admin `enableVault`/`disableVault` 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.
+ * @returns Checksummed addresses of the currently-registered eligible vaults,
+ *   deduped. Empty when no router is deployed or none are registered.
+ * @throws AugustValidationError when `rpcUrl` is missing/empty.
+ * @throws AugustSDKError when an `eth_getLogs` chunk fails — surfaced (not
+ *   swallowed) so a partial scan never masquerades as the complete set.
+ * @worstCaseRpcCalls On mainnet, 1 `eth_blockNumber` + ~4 `eth_getLogs` chunks
+ *   (router-lifetime ÷ 50k-block window) + 1 Multicall3 `eth_call` ≈ 6; scales
+ *   with the router's on-chain age, not with candidate count.
+ * @example
+ * ```ts
+ * const vaults = await getSwapRouterEligibleVaults(1, {
+ *   rpcUrl: 'https://eth-mainnet.example/v2/KEY',
+ * });
+ * // ['0x74aD…718b', '0xE9B7…9D32']  (Sentora USD, Upshift Core USDC)
+ * ```
+ */
+export declare function getSwapRouterEligibleVaults(chainId: number, options: {
+    rpcUrl: string;
+    fromBlock?: number;
+}): Promise<IAddress[]>;