@zircuit/ovault-evm 0.0.1

package/src/oVaultSync/transfer.ts

@@ -0,0 +1,742 @@
+import {
+  createPublicClient,
+  encodeAbiParameters,
+  encodeFunctionData,
+  erc20Abi,
+  http,
+  pad,
+  stringToHex,
+} from "viem";
+import { OFTAbi } from "../contracts/OFT";
+import { OVaultComposerSyncAbi } from "../contracts/OVaultComposerSync";
+import { ERC4626_ABI } from "../contracts/ERC4626";
+import { Options } from "@layerzerolabs/lz-v2-utilities";
+import { ERC20Abi } from "../contracts/ERC20";
+import { EIP2612_ABI } from "../contracts/EIP2612";
+import {
+  OVaultSyncInputs,
+  SendParams,
+  SendParamsInput,
+  GenerateOVaultSyncInputsProps,
+  OVaultSyncOperations,
+  OVaultCoreInputs,
+} from "../types";
+import { CHAINS, CLUSTERS } from "../addresses";
+
+const EXTRA_GAS_COMPOSE = 300_000n;
+
+export class OVaultSyncMessageBuilder {
+  private static getFormattedRefCode(code?: string): `0x${string}` {
+    return code
+      ? (stringToHex(code, { size: 32 }) as `0x${string}`)
+      : ("0x" as `0x${string}`);
+  }
+
+  /**
+   * Parse a string amount to BigInt with specified decimals, always truncating (never rounding up)
+   * This is critical for LayerZero operations to avoid precision issues
+   */
+  private static parseUnitsTruncate(value: string, decimals: number): bigint {
+    const strValue = String(value);
+    const [integerPart, decimalPart = ""] = strValue.split(".");
+    const truncatedDecimalPart = decimalPart
+      .slice(0, decimals)
+      .padEnd(decimals, "0");
+    const combined = integerPart + truncatedDecimalPart;
+    return BigInt(combined);
+  }
+
+  /**
+   * LayerZero uses 6 shared decimals for cross-chain transfers.
+   * This function removes dust below the 6 decimal precision that LayerZero won't transfer.
+   * For tokens with >6 decimals, this prevents quoteSend failures due to precision loss.
+   */
+  private static removeLzDust(amount: bigint, decimals: number): bigint {
+    if (decimals <= 6) return amount;
+    const dust = 10n ** BigInt(decimals - 6);
+    return (amount / dust) * dust;
+  }
+
+  static buildComposeArgument(input: SendParamsInput, messageFee: bigint) {
+    // For the default OVault, the compose argument is just the hub to dst chain send params
+    // However, if you are using a custom OVault, you can have a custom compose argument
+    return encodeAbiParameters(
+      [
+        {
+          type: "tuple",
+          name: "sendParams",
+          components: [
+            { name: "dstEid", type: "uint32" },
+            { name: "to", type: "bytes32" },
+            { name: "amountLD", type: "uint256" },
+            { name: "minAmountLD", type: "uint256" },
+            { name: "extraOptions", type: "bytes" },
+            { name: "composeMsg", type: "bytes" },
+            { name: "oftCmd", type: "bytes" },
+          ],
+        },
+        {
+          type: "uint256",
+          name: "minMsgValue",
+        },
+      ],
+      [this.buildHubToDstChainSendParams(input), messageFee],
+    );
+  }
+
+  /**
+   * Build the send params for the hub chain to the dst chain.
+   *
+   * @param input - The input parameters for the OVault.
+   * @returns The send params for the hub chain to the dst chain.
+   */
+  static buildHubToDstChainSendParams(input: SendParamsInput) {
+    const {
+      srcEid,
+      hubEid,
+      dstEid,
+      dstAddress,
+      dstAmount,
+      minDstAmount,
+      referralCode,
+    } = input;
+
+    const srcIsHubChain = srcEid === hubEid;
+
+    // This is for a basic OFT send, so the enforced options should be enough
+    const options = Options.newOptions();
+    return {
+      dstEid: dstEid,
+      to: pad(dstAddress, { size: 32 }),
+      amountLD: dstAmount,
+      minAmountLD: minDstAmount,
+      extraOptions: options.toHex() as `0x${string}`,
+      composeMsg: "0x" as `0x${string}`,
+      oftCmd: srcIsHubChain
+        ? this.getFormattedRefCode(referralCode)
+        : ("0x" as `0x${string}`),
+    };
+  }
+
+  /**
+   * Quote the amount of shares or assets that will be received from the OVault.
+   *
+   * @param input - The input parameters for the OVault.
+   * @returns The amount of shares or assets that will be received from the OVault.
+   */
+  static async quoteOVaultOutput(
+    input: GenerateOVaultSyncInputsProps,
+  ): Promise<{
+    dstAmount: bigint;
+    minDstAmount: bigint;
+  }> {
+    const {
+      operation,
+      vaultAddress,
+      hubChain,
+      slippage,
+      srcEid,
+      dstEid,
+      hubEid,
+    } = input;
+
+    const client = createPublicClient({
+      chain: hubChain,
+      transport: http(input.hubRpcUrl),
+    });
+    if (input.amount == null || input.tokenHubDecimals == null) {
+      throw new Error("inputs cannot be null");
+    }
+    let amountInHubDecimals = this.parseUnitsTruncate(
+      input.amount,
+      input.tokenHubDecimals,
+    );
+    // Only remove LayerZero dust if this is a cross-chain operation
+    // LayerZero is involved if source or destination is not the hub chain
+    const isCrossChain = srcEid !== hubEid || dstEid !== hubEid;
+    if (isCrossChain) {
+      amountInHubDecimals = this.removeLzDust(
+        amountInHubDecimals,
+        input.tokenHubDecimals,
+      );
+    }
+
+    const outputAmount = await client.readContract({
+      address: vaultAddress,
+      abi: ERC4626_ABI,
+      functionName:
+        operation === OVaultSyncOperations.DEPOSIT
+          ? "previewDeposit"
+          : "previewRedeem",
+      args: [amountInHubDecimals],
+    });
+
+    if (slippage < 0.001)
+      throw new Error("Slippage must be greater or equal to 0.001 (0.1%)");
+    if (outputAmount === 0n) throw new Error("Output amount is too small");
+
+    const slippageAmount =
+      (outputAmount * BigInt(Number(slippage.toFixed(3)) * 1000)) / 1000n;
+
+    return {
+      dstAmount: outputAmount,
+      minDstAmount: outputAmount - slippageAmount,
+    };
+  }
+
+  /**
+   * Calculate the message fee for the hub chain. This is the fee that it costs to send a message from the hub chain to the dst chain.
+   *
+   * @param input - The input parameters for the OVault.
+   * @param useWalletAddress
+   * @returns The message fee for the hub chain.
+   */
+  static async calculateHubChainFee(
+    input: SendParamsInput,
+    useWalletAddress = true,
+  ) {
+    const {
+      srcEid,
+      operation,
+      amount,
+      composerAddress,
+      hubChain,
+      dstEid,
+      hubEid,
+      oftHubAddress,
+      vaultAddress,
+      buffer,
+    } = input;
+
+    // If the dst chain is the same as the hub chain, then we don't need to calculate the fee
+    // as we are already on the hub chain, so "send" on the OFT will not be called.
+    if (dstEid === hubEid) {
+      return {
+        nativeFee: 0n,
+        lzTokenFee: 0n,
+      };
+    }
+
+    const client = createPublicClient({
+      chain: hubChain,
+      transport: http(input.hubRpcUrl),
+    });
+
+    const hubSendParams = this.buildHubToDstChainSendParams(input);
+
+    // Determine the target OFT based on operation:
+    // - For deposits: shares are sent via share OFT
+    // - For redeems: assets are sent via asset OFT
+    const targetOft =
+      operation === OVaultSyncOperations.DEPOSIT ? vaultAddress : oftHubAddress;
+
+    if (srcEid === hubEid) {
+      // For same-chain operations, use wallet address. For cross-chain, we could use
+      // the OFT address since the wallet may not have the tokens yet.
+      if (!useWalletAddress) {
+        throw new Error("Wallet address is required");
+      }
+      const quote = await client.readContract({
+        address: composerAddress,
+        abi: OVaultComposerSyncAbi,
+        functionName: "quoteSend",
+        args: [input.walletAddress, targetOft, amount, hubSendParams],
+      });
+
+      return {
+        nativeFee: this.increaseByBuffer(quote.nativeFee, buffer),
+        lzTokenFee: this.increaseByBuffer(quote.lzTokenFee, buffer),
+      };
+    }
+
+    // We check directly on the OFT to get the message fee as the vault address or the share OFT address
+    // won't have shares or assets balance as we burn them.
+    // This is different to the original LZ implementation, where they use
+    // OFT adapter for the shares token in accounting chain (the tokens are locked in that case,
+    // not burned). In their case, they always call VaultComposer, for maxDeposit/maxRedeem checks.
+    const quote = await client.readContract({
+      address: targetOft,
+      abi: OFTAbi,
+      functionName: "quoteSend",
+      args: [hubSendParams as never, false],
+    });
+
+    return {
+      nativeFee: this.increaseByBuffer(quote.nativeFee, buffer),
+      lzTokenFee: this.increaseByBuffer(quote.lzTokenFee, buffer),
+    };
+  }
+
+  static async getMessageFee(sendParams: SendParams, input: SendParamsInput) {
+    const {
+      operation,
+      oftAddress,
+      vaultTokenAddress,
+      sourceChain,
+      srcEid,
+      hubEid,
+      buffer,
+    } = input;
+
+    const client = createPublicClient({
+      chain: sourceChain,
+      transport: http(input.sourceRpcUrl),
+    });
+
+    // If the src chain is the same as the hub chain, then the way to calculate the message fee is the same
+    // as calculating the hub chain fee as we are already on the hub chain.
+    if (srcEid === hubEid) {
+      return this.calculateHubChainFee(input, true);
+    }
+
+    const sendingOftAddress =
+      operation === OVaultSyncOperations.DEPOSIT
+        ? oftAddress
+        : vaultTokenAddress;
+
+    // If we are not on the hub chain, then we need to call the OFT's quoteSend function to get the message fee.
+    const messageFee = await client.readContract({
+      address: sendingOftAddress,
+      abi: OFTAbi,
+      functionName: "quoteSend",
+      args: [sendParams as never, false],
+    });
+
+    return {
+      nativeFee: this.increaseByBuffer(messageFee.nativeFee, buffer),
+      lzTokenFee: this.increaseByBuffer(messageFee.lzTokenFee, buffer),
+    };
+  }
+
+  static increaseByBuffer(amount: bigint, buffer: number = 0) {
+    if (!buffer || buffer <= 0) {
+      return amount;
+    }
+
+    const flatNumber = BigInt((buffer * 100).toFixed(0));
+
+    const bufferAmount = (amount * flatNumber) / 100n;
+    return amount + bufferAmount;
+  }
+
+  static async buildSendParams(input: SendParamsInput) {
+    const {
+      amount,
+      srcEid,
+      composerAddress,
+      hubEid,
+      dstAmount,
+      minDstAmount,
+      referralCode,
+    } = input;
+
+    const options = Options.newOptions();
+
+    const srcIsHubChain = srcEid === hubEid;
+
+    if (srcIsHubChain) {
+      return this.buildHubToDstChainSendParams(input);
+    }
+
+    // If the src chain is not the same as the hub chain, then the first message will be an LzCompose
+    // so we need to add the executor option
+    const hubMessageFee = await this.calculateHubChainFee(
+      {
+        ...input,
+        dstAmount,
+        minDstAmount,
+      },
+      false,
+    );
+
+    const extraGas = input.hubLzComposeGasLimit ?? EXTRA_GAS_COMPOSE;
+    options.addExecutorComposeOption(0, extraGas, hubMessageFee.nativeFee);
+
+    return {
+      // If the src chain is not the same as the hub chain, then the first message will be to the hub chain
+      // so we need to set the dstEid to the hub chain EID
+      dstEid: hubEid,
+      to: pad(composerAddress, { size: 32 }),
+      amountLD: amount,
+      minAmountLD: amount,
+      extraOptions: options.toHex() as `0x${string}`,
+      composeMsg: this.buildComposeArgument(input, hubMessageFee.nativeFee),
+      oftCmd: this.getFormattedRefCode(referralCode),
+    };
+  }
+
+  static async buildApproval(input: SendParamsInput) {
+    const {
+      tokenAddress,
+      sourceChain,
+      composerAddress,
+      srcEid,
+      hubEid,
+      amount,
+      walletAddress,
+      vaultTokenAddress,
+      oftAddress,
+      operation,
+      supportsEip2612,
+      requiresZeroApprovalReset,
+    } = input;
+
+    let spender: `0x${string}` | null = null;
+    let approvingTokenAddress: `0x${string}` | null = null;
+    const srcIsHubChain = srcEid === hubEid;
+
+    // 1. We are locking the base token on a spoke chain (UnderlyingOFTAdapter)
+    //    In this case, we need to approve the OFTAdapter to spend the base token.
+    if (!srcIsHubChain && operation == OVaultSyncOperations.DEPOSIT) {
+      approvingTokenAddress = tokenAddress;
+      spender = oftAddress;
+      // 2. We are depositing the base token on the hub chain
+      //    In this case, we need to approve the VaultComposer to spend the base token (depositAndSend).
+    } else if (srcIsHubChain && operation == OVaultSyncOperations.DEPOSIT) {
+      approvingTokenAddress = tokenAddress;
+      spender = composerAddress;
+      // 3. We are requesting a withdrawal on a spoke chain (VaultToken)
+      //    No need, as it's handled by OFT.send in VaultToken
+    } else if (!srcIsHubChain && operation == OVaultSyncOperations.REDEEM) {
+      return;
+      // 4. We are requesting a withdrawal on the hub chain (Vault)
+      //    In this case, we need to approve the Composer to spend the shares.
+    } else if (srcIsHubChain && operation == OVaultSyncOperations.REDEEM) {
+      approvingTokenAddress = vaultTokenAddress;
+      spender = composerAddress;
+    }
+
+    // If we couldn't determine spender/token, there's nothing to approve
+    if (!approvingTokenAddress || !spender) {
+      return;
+    }
+
+    const client = createPublicClient({
+      chain: sourceChain,
+      transport: http(input.sourceRpcUrl),
+    });
+
+    const allowance = await client.readContract({
+      address: approvingTokenAddress,
+      abi: ERC20Abi,
+      functionName: "allowance",
+      args: [walletAddress, spender],
+    });
+
+    if (allowance >= amount) {
+      // We have enough allowance, so we don't need to approve
+      return;
+    }
+
+    // Check if the asset supports EIP-2612 permit
+    // Only use permit for deposits with the base token (not vault shares)
+    const usePermit =
+      operation === OVaultSyncOperations.DEPOSIT && supportsEip2612 === true;
+
+    if (usePermit) {
+      try {
+        const [nonceResult, tokenNameResult, tokenVersionResult] =
+          await client.multicall({
+            contracts: [
+              {
+                address: approvingTokenAddress as `0x${string}`,
+                abi: EIP2612_ABI,
+                functionName: "nonces",
+                args: [walletAddress],
+              },
+              {
+                address: approvingTokenAddress as `0x${string}`,
+                abi: erc20Abi,
+                functionName: "name",
+              },
+              {
+                address: approvingTokenAddress as `0x${string}`,
+                abi: EIP2612_ABI,
+                functionName: "version",
+              },
+            ],
+          });
+
+        if (
+          nonceResult.status !== "success" ||
+          tokenNameResult.status !== "success"
+        ) {
+          throw new Error("Failed to fetch permit data");
+        }
+
+        const tokenVersion =
+          tokenVersionResult.status !== "success"
+            ? "1"
+            : (tokenVersionResult.result as string);
+
+        return {
+          tokenAddress: approvingTokenAddress,
+          amount,
+          spender,
+          usePermit: true,
+          nonce: nonceResult.result as bigint,
+          tokenName: tokenNameResult.result as string,
+          tokenVersion,
+        };
+      } catch (error) {
+        // If nonce fetch fails, fall back to regular approval
+        console.warn(
+          "Failed to fetch nonce for permit, falling back to approval:",
+          error,
+        );
+      }
+    }
+
+    // Some tokens (like USDT) require approval to be set to 0 before changing to a new value
+    // If there's an existing non-zero allowance, we need a two-step approval
+    const needsResetApproval =
+      requiresZeroApprovalReset && allowance > 0n && allowance < amount;
+
+    return {
+      tokenAddress: approvingTokenAddress,
+      amount,
+      spender,
+      usePermit: false,
+      needsResetApproval,
+    };
+  }
+
+  /**
+   * Resolve a {@link OVaultCoreInputs} into the full
+   * {@link GenerateOVaultSyncInputsProps} using the built-in address registry.
+   */
+  static resolveCoreInputs(
+    core: OVaultCoreInputs,
+  ): GenerateOVaultSyncInputsProps {
+    const {
+      sourceChain,
+      destinationChain,
+      token,
+      operation,
+      amount,
+      walletAddress,
+      dstAddress,
+      slippage = 0.01,
+      buffer = 0.3,
+      supportsEip2612 = false,
+      hubLzComposeGasLimit,
+      referralCode,
+    } = core;
+
+    const cluster = CLUSTERS[token];
+    if (!cluster) {
+      throw new Error(`Unsupported token: ${token}`);
+    }
+
+    const srcMeta = CHAINS[sourceChain];
+    const dstMeta = CHAINS[destinationChain];
+    const hubMeta = CHAINS[cluster.hubChain];
+
+    const srcDeployment = cluster.chains[sourceChain];
+    if (!srcDeployment) {
+      throw new Error(
+        `Token ${token} is not deployed on ${sourceChain}`,
+      );
+    }
+    const hubDeployment = cluster.chains[cluster.hubChain];
+
+    const srcIsHub = srcMeta.eid === hubMeta.eid;
+
+    // Token decimals: deposits use the underlying token decimals (always 6
+    // for USDC/USDT); redeems on spoke chains use VaultToken decimals (18).
+    const tokenLocalDecimals =
+      operation === OVaultSyncOperations.DEPOSIT
+        ? cluster.hubDecimals
+        : srcIsHub
+          ? cluster.hubDecimals
+          : 18;
+
+    return {
+      srcEid: srcMeta.eid,
+      hubEid: hubMeta.eid,
+      dstEid: dstMeta.eid,
+      walletAddress,
+      dstAddress,
+
+      sourceChain: srcMeta.viemChain,
+      hubChain: hubMeta.viemChain,
+
+      vaultAddress: hubDeployment.vault,
+      composerAddress: hubDeployment.composer,
+      oftHubAddress: hubDeployment.oft,
+      vaultTokenAddress: srcIsHub ? hubDeployment.vault : srcDeployment.vault,
+
+      oftAddress:
+        operation === OVaultSyncOperations.DEPOSIT
+          ? srcDeployment.oft
+          : srcDeployment.vault,
+      tokenAddress:
+        operation === OVaultSyncOperations.DEPOSIT
+          ? srcDeployment.token
+          : srcDeployment.vault,
+
+      operation,
+      amount,
+      tokenLocalDecimals,
+      tokenHubDecimals: cluster.hubDecimals,
+      slippage,
+      buffer,
+      supportsEip2612,
+      requiresZeroApprovalReset: cluster.requiresZeroApprovalReset,
+      hubLzComposeGasLimit,
+      referralCode,
+      hubRpcUrl: core.rpcUrls?.[cluster.hubChain],
+      sourceRpcUrl: core.rpcUrls?.[sourceChain],
+    };
+  }
+
+  /**
+   * Generate the inputs for the OVault.
+   *
+   * @param input - The input parameters for the OVault.
+   * @returns Inputs to call contracts to perform Deposit or Redeem on the OVault.
+   */
+  static async generateOVaultInputs(
+    input: OVaultCoreInputs,
+  ): Promise<OVaultSyncInputs> {
+    const resolved: GenerateOVaultSyncInputsProps = this.resolveCoreInputs(input as OVaultCoreInputs)
+    const {
+      srcEid,
+      hubEid,
+      dstEid,
+      operation,
+      amount, // amount should be not scaled (string)
+      dstAddress,
+      walletAddress: refundAddress,
+      composerAddress,
+      oftAddress, // OFT/OFTAdapter on the source chain
+      vaultTokenAddress, // VaultToken address on the source chain
+      tokenLocalDecimals,
+    } = resolved;
+
+    // Calculates the minimum amount based on the slippage
+    const outputAmount = await this.quoteOVaultOutput(resolved);
+
+    // Parse the amount
+    let amountInLocalDecimals = this.parseUnitsTruncate(
+      amount,
+      tokenLocalDecimals,
+    );
+
+    // Only remove LayerZero dust if this is a cross-chain operation
+    // LayerZero is involved if source or destination is not the hub chain
+    const isCrossChain = srcEid !== hubEid || dstEid !== hubEid;
+    if (isCrossChain) {
+      amountInLocalDecimals = this.removeLzDust(
+        amountInLocalDecimals,
+        tokenLocalDecimals,
+      );
+    }
+
+    if (amountInLocalDecimals === 0n) {
+      throw new Error("Amount is too small");
+    }
+
+    const fullInputParams = {
+      ...resolved,
+      amount: amountInLocalDecimals,
+      dstAmount: outputAmount.dstAmount,
+      minDstAmount: outputAmount.minDstAmount,
+      dstAddress: dstAddress ?? refundAddress,
+    };
+
+    const sendParams = await this.buildSendParams(fullInputParams);
+    const messageFee = await this.getMessageFee(sendParams, fullInputParams);
+
+    const srcIsHubChain = srcEid === hubEid;
+
+    const approvalData = await this.buildApproval(fullInputParams);
+
+    if (!srcIsHubChain) {
+      // Spoke chain: use 'send' or 'sendWithPermit' for deposits
+      const usePermit =
+        approvalData?.usePermit && operation === OVaultSyncOperations.DEPOSIT;
+
+      return {
+        messageFee,
+        dstAmount: {
+          amount: outputAmount.dstAmount,
+          minAmount: outputAmount.minDstAmount,
+        },
+        approval: approvalData,
+        txArgs: {
+          base: [sendParams, messageFee, refundAddress],
+          permitParams: usePermit ? ["deadline", "v", "r", "s"] : null,
+        },
+        contractFunctionName: usePermit ? "sendWithPermit" : "send",
+        contractAddress:
+          operation == OVaultSyncOperations.DEPOSIT
+            ? oftAddress
+            : vaultTokenAddress,
+        abi: OFTAbi,
+      };
+    }
+
+    // Hub chain: use 'depositAndSend' or 'depositAndSendWithPermit' for deposits
+    const usePermit =
+      approvalData?.usePermit && operation === OVaultSyncOperations.DEPOSIT;
+
+    return {
+      messageFee,
+      dstAmount: {
+        amount: outputAmount.dstAmount,
+        minAmount: outputAmount.minDstAmount,
+      },
+      approval: approvalData,
+      txArgs: {
+        base: [amountInLocalDecimals, sendParams, refundAddress ?? dstAddress],
+        permitParams: usePermit ? ["deadline", "v", "r", "s"] : null,
+      },
+      contractFunctionName:
+        operation === OVaultSyncOperations.DEPOSIT
+          ? usePermit
+            ? "depositAndSendWithPermit"
+            : "depositAndSend"
+          : "redeemAndSend",
+      contractAddress: composerAddress,
+      abi: OVaultComposerSyncAbi,
+    };
+  }
+
+  /**
+   * Encode to avoid ABI-union incompatibility that arises when passing the
+   * discriminated-union `OVaultSyncInputs` directly to viem's `writeContract`.
+   *
+   * @param inputs     - The output from `generateOVaultInputs`.
+   * @param permitArgs - Optional permit arguments (`[deadline, v, r, s]`) to
+   *                     append when using the EIP-2612 permit flow.
+   */
+  static encodeTransactionRequest(
+    inputs: OVaultSyncInputs,
+    permitArgs?: readonly [
+      bigint,
+      number | bigint,
+      `0x${string}`,
+      `0x${string}`,
+    ],
+  ): { to: `0x${string}`; data: `0x${string}`; value: bigint } {
+    const args: readonly unknown[] = permitArgs
+      ? [...inputs.txArgs.base, ...permitArgs]
+      : inputs.txArgs.base;
+
+    // generateOVaultInputs always produces a consistent abi/functionName/args
+    // tuple, but the discriminated union prevents encodeFunctionData from
+    // resolving the correlation across variants.
+    const data = encodeFunctionData({
+      abi: inputs.abi,
+      functionName: inputs.contractFunctionName,
+      args,
+    } as Parameters<typeof encodeFunctionData>[0]);
+
+    return {
+      to: inputs.contractAddress,
+      data,
+      value: inputs.messageFee.nativeFee,
+    };
+  }
+}