damm-sdk 1.4.20 → 1.4.22

package/src/integrations/ccip/ccip.router.ts

@@ -0,0 +1,172 @@
+import { ethers } from "ethers";
+import ccipRouterAbi from "./ccip.router.abi";
+import type { Call, HexString, Unwrapable } from "../../types";
+import { createCall } from "../../types";
+import type { Address } from "viem";
+
+const ccipRouterInterface = new ethers.utils.Interface(ccipRouterAbi as any);
+
+/**
+ * CCIP chain selectors (uint64).
+ * Source: https://docs.chain.link/ccip/directory/mainnet
+ * Verified on-chain 2026-04-13 via typeAndVersion() on each Router.
+ */
+export const CCIP_CHAIN_SELECTORS: Readonly<Record<number, string>> = Object.freeze({
+    1: "5009297550715157269", // Mainnet
+    42161: "4949039107694359620", // Arbitrum
+    8453: "15971525489660198786", // Base
+    10: "3734403246176062136", // Optimism
+    137: "4051577828743386545", // Polygon
+    56: "11344663589394136015", // BSC
+    143: "8481857512324358265", // Monad
+});
+
+/**
+ * Get the CCIP chain selector for a given chain ID.
+ * @throws if the chain is not supported
+ */
+export const getCCIPChainSelector = (chainId: number): string => {
+    const selector = CCIP_CHAIN_SELECTORS[chainId];
+    if (!selector) {
+        throw new Error(`CCIP: No chain selector for chainId ${chainId}`);
+    }
+    return selector;
+};
+
+// ─── EVM2AnyMessage struct ───────────────────────────────────────────────
+
+export type CCIPTokenAmount = Readonly<{
+    token: Address;
+    amount: bigint;
+}>;
+
+export type EVM2AnyMessage = Readonly<{
+    /** abi.encode(destinationAddress) */
+    receiver: HexString;
+    /** Empty (0x) for token-only transfers */
+    data: HexString;
+    /** Tokens to bridge */
+    tokenAmounts: readonly CCIPTokenAmount[];
+    /** address(0) = pay fee in native ETH/MON */
+    feeToken: Address;
+    /** Extra args (0x for defaults) */
+    extraArgs: HexString;
+}>;
+
+// ─── getFee ──────────────────────────────────────────────────────────────
+
+export type GetFeeArgs = Readonly<{
+    destinationChainSelector: string;
+    message: EVM2AnyMessage;
+}>;
+
+/**
+ * Encode calldata for Router.getFee(destinationChainSelector, message).
+ * Use this to quote the CCIP fee via an RPC call.
+ */
+export const CCIPGetFeeCalldata = (args: GetFeeArgs): HexString => {
+    return ccipRouterInterface.encodeFunctionData("getFee", [
+        args.destinationChainSelector,
+        {
+            receiver: args.message.receiver,
+            data: args.message.data,
+            tokenAmounts: args.message.tokenAmounts.map((t) => ({
+                token: t.token,
+                amount: t.amount,
+            })),
+            feeToken: args.message.feeToken,
+            extraArgs: args.message.extraArgs,
+        },
+    ]) as HexString;
+};
+
+/**
+ * Build a Call for Router.getFee (read-only, value=0).
+ */
+export const CCIPGetFeeTrx = ({
+    routerAddress,
+    args,
+}: {
+    routerAddress: Address;
+    args: GetFeeArgs;
+}): Unwrapable<Call> => {
+    return createCall({
+        operation: 0,
+        to: routerAddress,
+        data: CCIPGetFeeCalldata(args),
+        value: 0n,
+    });
+};
+
+// ─── ccipSend ────────────────────────────────────────────────────────────
+
+export type CCIPSendArgs = Readonly<{
+    destinationChainSelector: string;
+    message: EVM2AnyMessage;
+    /** Native fee (from getFee). The Router does NOT refund excess. */
+    nativeFee: bigint;
+}>;
+
+/**
+ * Encode calldata for Router.ccipSend(destinationChainSelector, message).
+ */
+export const CCIPSendCalldata = (args: CCIPSendArgs): HexString => {
+    return ccipRouterInterface.encodeFunctionData("ccipSend", [
+        args.destinationChainSelector,
+        {
+            receiver: args.message.receiver,
+            data: args.message.data,
+            tokenAmounts: args.message.tokenAmounts.map((t) => ({
+                token: t.token,
+                amount: t.amount,
+            })),
+            feeToken: args.message.feeToken,
+            extraArgs: args.message.extraArgs,
+        },
+    ]) as HexString;
+};
+
+/**
+ * Build a Call for Router.ccipSend with msg.value = nativeFee.
+ */
+export const ccipSendTrx = ({
+    routerAddress,
+    args,
+}: {
+    routerAddress: Address;
+    args: CCIPSendArgs;
+}): Unwrapable<Call> => {
+    return createCall({
+        operation: 0,
+        to: routerAddress,
+        data: CCIPSendCalldata(args),
+        value: args.nativeFee,
+    });
+};
+
+// ─── Helper: build EVM2AnyMessage for a single token bridge ──────────────
+
+/**
+ * Build a standard EVM2AnyMessage for bridging a single token.
+ * Receiver = abi.encode(destinationAddress), feeToken = address(0) (native).
+ */
+export const buildCCIPMessage = ({
+    receiver,
+    token,
+    amount,
+}: {
+    receiver: Address;
+    token: Address;
+    amount: bigint;
+}): EVM2AnyMessage => {
+    // Pad receiver to 32 bytes (abi.encode(address))
+    const receiverEncoded = ("0x" + receiver.slice(2).padStart(64, "0")) as HexString;
+
+    return Object.freeze({
+        receiver: receiverEncoded,
+        data: "0x" as HexString,
+        tokenAmounts: Object.freeze([Object.freeze({ token, amount })]),
+        feeToken: "0x0000000000000000000000000000000000000000" as Address,
+        extraArgs: "0x" as HexString,
+    });
+};

package/src/integrations/ccip/index.ts

@@ -0,0 +1,19 @@
+export { default as CCIPRouterAbi } from "./ccip.router.abi";
+export {
+    // Chain selectors
+    CCIP_CHAIN_SELECTORS,
+    getCCIPChainSelector,
+    // getFee
+    CCIPGetFeeCalldata,
+    CCIPGetFeeTrx,
+    // ccipSend
+    CCIPSendCalldata,
+    ccipSendTrx,
+    // Helper
+    buildCCIPMessage,
+    // Types
+    type CCIPTokenAmount,
+    type EVM2AnyMessage,
+    type GetFeeArgs,
+    type CCIPSendArgs,
+} from "./ccip.router";

package/src/integrations/enso/enso.route.api.ts

@@ -0,0 +1,127 @@
+/**
+ * Enso Shortcuts API client.
+ *
+ * Fetches a swap route from Enso's public `/v1/shortcuts/route` endpoint and
+ * returns the raw `tx.data` (which is always `routeSingle` calldata — see
+ * `enso.ts` for the rewrap into `safeRouteSingle`).
+ *
+ * API reference: https://docs.enso.build/pages/api-reference/shortcuts/route
+ */
+
+import type { Address } from "viem";
+import type { HexString } from "../../types";
+
+export const ENSO_API_BASE = "https://api.enso.finance" as const;
+
+/**
+ * Raw response shape from the Enso route endpoint. We only model the fields
+ * we use; Enso returns many more (amountOut, priceImpact, route, …) that are
+ * intentionally ignored.
+ */
+export type EnsoRouteResponse = Readonly<{
+    tx: Readonly<{
+        to: HexString;
+        data: HexString;
+        value: string;
+    }>;
+}>;
+
+export type EnsoRouteArgs = Readonly<{
+    chainId: number;
+    /** Caller address — also used as `receiver` by default. */
+    fromAddress: Address;
+    /** Destination for the swap output. Typically equal to `fromAddress` (the Safe). */
+    receiver: Address;
+    tokenIn: Address;
+    tokenOut: Address;
+    /** Decimal string, no decimals adjustment — matches token units. */
+    amountIn: string;
+    /**
+     * Slippage in integer basis points (e.g. 20 = 0.2%, 300 = 3%).
+     *
+     * Enso's `slippage` param is a number string in bips. Passing a decimal
+     * like `0.2` triggers a 400 Bad Request ("slippage must be a number
+     * string").
+     */
+    slippageBips: number;
+    /** Optional Enso API key for 10 rps; no key = 1 rps global limit. */
+    apiKey?: string;
+    /** Override the API base URL (useful for tests). */
+    apiBase?: string;
+}>;
+
+export class EnsoRouteApiError extends Error {
+    readonly status: number;
+    readonly statusText: string;
+    readonly tokenIn: Address;
+    readonly tokenOut: Address;
+
+    constructor({
+        status,
+        statusText,
+        tokenIn,
+        tokenOut,
+    }: {
+        status: number;
+        statusText: string;
+        tokenIn: Address;
+        tokenOut: Address;
+    }) {
+        super(`Enso route API request failed with status ${status} (${statusText}) for swap ${tokenIn} -> ${tokenOut}`);
+        this.name = "EnsoRouteApiError";
+        this.status = status;
+        this.statusText = statusText;
+        this.tokenIn = tokenIn;
+        this.tokenOut = tokenOut;
+    }
+}
+
+/**
+ * Fetch a shortcut route from Enso. Always returns `routeSingle` calldata —
+ * use `rewrapRouteSingleAsSafeRouteSingle` in `enso.ts` to convert to
+ * `safeRouteSingle` before submitting on-chain if your Safe's Zodiac scope
+ * only permits safeRouteSingle.
+ */
+export const fetchEnsoRoute = async (args: EnsoRouteArgs): Promise<EnsoRouteResponse> => {
+    const {
+        chainId,
+        fromAddress,
+        receiver,
+        tokenIn,
+        tokenOut,
+        amountIn,
+        slippageBips,
+        apiKey,
+        apiBase = ENSO_API_BASE,
+    } = args;
+
+    const params = new URLSearchParams({
+        chainId: String(chainId),
+        fromAddress,
+        receiver,
+        tokenIn,
+        tokenOut,
+        amountIn,
+        slippage: String(slippageBips),
+    });
+
+    const headers: Record<string, string> = { Accept: "application/json" };
+    if (apiKey) {
+        headers["Authorization"] = `Bearer ${apiKey}`;
+    }
+
+    const response = await fetch(`${apiBase}/api/v1/shortcuts/route?${params.toString()}`, {
+        headers,
+    });
+
+    if (!response.ok) {
+        throw new EnsoRouteApiError({
+            status: response.status,
+            statusText: response.statusText,
+            tokenIn,
+            tokenOut,
+        });
+    }
+
+    return (await response.json()) as EnsoRouteResponse;
+};

package/src/integrations/enso/enso.router.abi.ts

@@ -0,0 +1,48 @@
+/**
+ * Enso RouterV2 — minimal ABI covering the entry points we use:
+ *
+ *   routeSingle(Token tokenOut, bytes data)
+ *   safeRouteSingle(Token tokenIn, Token tokenOut, address receiver, bytes data)
+ *
+ * `Token` is Enso's internal struct `{ uint8 tokenType, bytes data }` where:
+ *   - tokenType = 0 (Native):  data = abi.encode(uint256 amount)
+ *   - tokenType = 1 (ERC20):   data = abi.encode(address token, uint256 amount)
+ *
+ * We intentionally expose only these two selectors — we never call the Enso
+ * router with routeMulti / safeRouteMulti / delegate variants from any DAMM
+ * context, and shipping their ABIs here would just invite unaudited usage.
+ */
+
+const tokenTuple = {
+    name: "token",
+    type: "tuple",
+    components: [
+        { name: "tokenType", type: "uint8" },
+        { name: "data", type: "bytes" },
+    ],
+} as const;
+
+export default [
+    {
+        name: "routeSingle",
+        type: "function",
+        stateMutability: "payable",
+        inputs: [
+            { ...tokenTuple, name: "tokenOut" },
+            { name: "data", type: "bytes" },
+        ],
+        outputs: [],
+    },
+    {
+        name: "safeRouteSingle",
+        type: "function",
+        stateMutability: "payable",
+        inputs: [
+            { ...tokenTuple, name: "tokenIn" },
+            { ...tokenTuple, name: "tokenOut" },
+            { name: "receiver", type: "address" },
+            { name: "data", type: "bytes" },
+        ],
+        outputs: [],
+    },
+] as const;

package/src/integrations/enso/enso.ts

@@ -0,0 +1,172 @@
+/**
+ * Enso RouterV2 transaction builders.
+ *
+ * Enso's `/v1/shortcuts/route` API only returns `routeSingle(Token tokenOut,
+ * bytes data)` calldata. Our Zodiac Roles scopes only permit the stricter
+ * 4-arg `safeRouteSingle(Token tokenIn, Token tokenOut, address receiver,
+ * bytes data)`, which validates tokenIn consumption and an explicit receiver.
+ *
+ * The shortcut `bundle` payload is identical between the two entry points —
+ * safeRouteSingle just layers additional validation on top — so we fetch the
+ * route once, extract the bundle, and re-encode as safeRouteSingle.
+ *
+ * Workflow:
+ *   ensoSafeRouteSingleTrx({ api args, routerAddress })
+ *     → fetchEnsoRoute(...)                                  (HTTP)
+ *     → rewrapRouteSingleAsSafeRouteSingle(...)              (pure)
+ *     → createCall({ to: routerAddress, data, … })           (Unwrapable<Call>)
+ */
+
+import { decodeFunctionData, encodeAbiParameters, encodeFunctionData, type Address } from "viem";
+import type { Call, HexString, Unwrapable } from "../../types";
+import { createCall } from "../../types";
+import ensoRouterAbi from "./enso.router.abi.ts";
+import { fetchEnsoRoute, type EnsoRouteArgs, type EnsoRouteResponse } from "./enso.route.api.ts";
+
+// --- Token struct --------------------------------------------------------
+
+export enum EnsoTokenType {
+    Native = 0,
+    ERC20 = 1,
+}
+
+export type EnsoToken = Readonly<{
+    tokenType: EnsoTokenType;
+    data: HexString;
+}>;
+
+const ZERO_ADDRESS: Address = "0x0000000000000000000000000000000000000000";
+
+const isNativeToken = (token: Address): boolean => token.toLowerCase() === ZERO_ADDRESS;
+
+/**
+ * Encode a token as Enso's `Token` struct:
+ *   - ERC20:  (tokenType=1, abi.encode(address, uint256))
+ *   - Native: (tokenType=0, abi.encode(uint256))
+ */
+export const encodeEnsoToken = (token: Address, amount: bigint): EnsoToken => {
+    if (isNativeToken(token)) {
+        return {
+            tokenType: EnsoTokenType.Native,
+            data: encodeAbiParameters([{ type: "uint256" }], [amount]),
+        };
+    }
+    return {
+        tokenType: EnsoTokenType.ERC20,
+        data: encodeAbiParameters([{ type: "address" }, { type: "uint256" }], [token, amount]),
+    };
+};
+
+// --- routeSingle → safeRouteSingle rewrap --------------------------------
+
+const ROUTE_SINGLE_SELECTOR = "0xb94c3609" as const;
+
+export class UnexpectedEnsoSelectorError extends Error {
+    readonly selector: string;
+    constructor(selector: string) {
+        super(
+            `Expected routeSingle selector ${ROUTE_SINGLE_SELECTOR}, got ${selector}. ` +
+                `The Enso API may have changed its output format.`,
+        );
+        this.name = "UnexpectedEnsoSelectorError";
+        this.selector = selector;
+    }
+}
+
+export type RewrapArgs = Readonly<{
+    routeSingleCalldata: HexString;
+    tokenIn: Address;
+    amountIn: bigint;
+    receiver: Address;
+}>;
+
+/**
+ * Decode `routeSingle(tokenOut, bundle)` calldata, then re-encode as
+ * `safeRouteSingle(tokenIn, tokenOut, receiver, bundle)` using the same
+ * bundle payload. The bundle is byte-identical; only the wrapper changes.
+ *
+ * Throws `UnexpectedEnsoSelectorError` if the input doesn't start with the
+ * routeSingle selector — a fail-fast guard in case Enso's API ever switches
+ * output format.
+ */
+export const rewrapRouteSingleAsSafeRouteSingle = (args: RewrapArgs): HexString => {
+    const { routeSingleCalldata, tokenIn, amountIn, receiver } = args;
+
+    const selector = routeSingleCalldata.slice(0, 10).toLowerCase();
+    if (selector !== ROUTE_SINGLE_SELECTOR) {
+        throw new UnexpectedEnsoSelectorError(selector);
+    }
+
+    const decoded = decodeFunctionData({
+        abi: ensoRouterAbi,
+        data: routeSingleCalldata,
+    });
+
+    if (decoded.functionName !== "routeSingle") {
+        throw new UnexpectedEnsoSelectorError(selector);
+    }
+    const [tokenOutStruct, bundle] = decoded.args as readonly [EnsoToken, HexString];
+
+    const tokenInStruct = encodeEnsoToken(tokenIn, amountIn);
+
+    return encodeFunctionData({
+        abi: ensoRouterAbi,
+        functionName: "safeRouteSingle",
+        args: [tokenInStruct, tokenOutStruct, receiver, bundle],
+    }) as HexString;
+};
+
+// --- High-level helper: fetch route + rewrap + build Call ----------------
+
+export class EnsoUnexpectedRouterError extends Error {
+    readonly got: Address;
+    readonly expected: Address;
+    constructor(got: Address, expected: Address) {
+        super(
+            `Enso API routed to ${got} but we expected RouterV2 ${expected}. ` +
+                `Unsupported routing (e.g. EnsoWallet / ShortcutsDelegate) — aborting.`,
+        );
+        this.name = "EnsoUnexpectedRouterError";
+        this.got = got;
+        this.expected = expected;
+    }
+}
+
+export type EnsoSafeRouteSingleTrxArgs = EnsoRouteArgs &
+    Readonly<{
+        /** Address of the Enso RouterV2 on the target chain. Must match the scope in Zodiac Roles. */
+        routerAddress: Address;
+    }>;
+
+/**
+ * Fetch an Enso route and return a `safeRouteSingle` call ready to be added
+ * to a MultisendBuilder.
+ *
+ * Aborts (throws) if Enso's API returns a tx targeting any address other than
+ * the provided RouterV2 — this protects against the API silently switching to
+ * EnsoWallet or EnsoShortcutsDelegate, neither of which our Zodiac scope
+ * permits.
+ */
+export const ensoSafeRouteSingleTrx = async (args: EnsoSafeRouteSingleTrxArgs): Promise<Unwrapable<Call>> => {
+    const { routerAddress, tokenIn, amountIn, receiver } = args;
+
+    const route: EnsoRouteResponse = await fetchEnsoRoute(args);
+
+    if (route.tx.to.toLowerCase() !== routerAddress.toLowerCase()) {
+        throw new EnsoUnexpectedRouterError(route.tx.to as Address, routerAddress);
+    }
+
+    const safeRouteSingleCalldata = rewrapRouteSingleAsSafeRouteSingle({
+        routeSingleCalldata: route.tx.data,
+        tokenIn,
+        amountIn: BigInt(amountIn),
+        receiver,
+    });
+
+    return createCall({
+        to: routerAddress,
+        data: safeRouteSingleCalldata,
+        operation: 0,
+        value: BigInt(route.tx.value || "0"),
+    });
+};

package/src/integrations/enso/index.ts

@@ -0,0 +1,3 @@
+export { default as ensoRouterAbi } from "./enso.router.abi";
+export * from "./enso";
+export * from "./enso.route.api";

package/src/integrations/index.ts

@@ -13,6 +13,7 @@ export * from "./slipstream";
 export * from "./morphoVault";
 export * from "./merkl";
 export * from "./oft";
+export * from "./ccip";
 export * from "./cctp";
 export * from "./erc721";
 export * from "./iporFusion";
@@ -23,3 +24,4 @@ export * from "./fluidLite";
 export * from "./weth";
 export * from "./pendle";
 export * from "./wormhole";
+export * from "./enso";