@zircuit/ovault-evm 0.0.1

package/src/types.ts

@@ -0,0 +1,260 @@
+import { Chain as ViemChain } from "viem";
+import { OFTAbi } from "./contracts/OFT";
+import { OVaultComposerSyncAbi } from "./contracts/OVaultComposerSync";
+import { ERC4626_ABI } from "./contracts/ERC4626";
+import type { SupportedChainName, SupportedToken } from "./addresses";
+
+export enum OVaultSyncOperations {
+  DEPOSIT = "deposit",
+  REDEEM = "redeem",
+}
+
+// --- Tracking helpers ---
+export type OVaultWithdrawalInfo = {
+  index: bigint | number | string;
+  initiator: `0x${string}`;
+};
+
+export type OVaultMessageWithTxHash = {
+  source?: { tx?: { txHash?: `0x${string}` } };
+};
+
+export interface SendParamsInput {
+  srcEid: number;
+  hubEid: number;
+  dstEid: number;
+  dstAddress: `0x${string}`;
+  walletAddress: `0x${string}`;
+  referralCode?: string;
+
+  vaultAddress: `0x${string}`;
+  oftHubAddress: `0x${string}`;
+  composerAddress: `0x${string}`;
+  vaultTokenAddress: `0x${string}`;
+
+  // The Viem chain object for the hub chain. Require user to pass in the hub chain object so that
+  // not every viem chain needs to be bundled with the SDK.
+  hubChain: ViemChain;
+
+  // The Viem chain object for the source chain
+  sourceChain: ViemChain;
+
+  // Deposit or redeem
+  operation: OVaultSyncOperations;
+
+  // This is the amount of tokens to send
+  amount: bigint;
+
+  tokenHubDecimals?: number;
+
+  dstAmount: bigint;
+  // This is the minimum amount of tokens to receive. If you are sending the OFT Asset,
+  // then this is the minimum amount of shares to receive.
+  minDstAmount: bigint;
+
+  slippage: number; // How much slippage to allow for the redemption. This is a percentage, so 0.01 = 1%
+
+  oftAddress: `0x${string}`;
+  tokenAddress: `0x${string}`; // If a hex code equal to 0x0, then the native token is being sent
+
+  // Optional capability/quirk flags for approvals
+  supportsEip2612?: boolean;
+  requiresZeroApprovalReset?: boolean;
+
+  // The gas limit for the hub chain. Only needed if the hub chain is not the same as the source chain.
+  // Defaults to 375_000 for cross chain operations and 175_000 for same chain operations.
+  hubLzComposeGasLimit?: bigint;
+
+  // Additional percentage to add to the message fee calculation, rounded to the nearest whole percentage.
+  // For example, `0.05` and `0.051` both yield an extra 5%, while `0.055` yields 6%.
+  buffer?: number;
+
+  // Optional custom RPC URLs. When provided, these are used instead of the
+  // chain's default public RPC to avoid rate limiting.
+  hubRpcUrl?: string;
+  sourceRpcUrl?: string;
+}
+
+export type GenerateOVaultSyncInputsProps = Omit<
+  SendParamsInput,
+  | "dstAmount"
+  | "minDstAmount"
+  | "dstAddress"
+  | "hubChainSourceAmount"
+  | "amount"
+> & {
+  // Unscaled (human-readable) amount string (e.g. "1.23")
+  amount: string;
+  // Decimals for parsing the unscaled amount into local chain units
+  tokenLocalDecimals: number;
+  dstAddress?: `0x${string}`;
+};
+
+/**
+ * Simplified input for `generateOVaultInputs`. The SDK resolves all contract
+ * addresses, EIDs, chain objects, and decimals from the built-in registry.
+ *
+ * @example
+ * ```ts
+ * const result = await OVaultSyncMessageBuilder.generateOVaultInputs({
+ *   sourceChain: "ethereum",
+ *   destinationChain: "base",
+ *   token: "USDC",
+ *   operation: OVaultSyncOperations.DEPOSIT,
+ *   amount: "100",
+ *   walletAddress: "0x...",
+ * });
+ * ```
+ */
+export interface OVaultCoreInputs {
+  /** Chain where the user submits the transaction */
+  sourceChain: SupportedChainName;
+  /** Chain where tokens/shares are delivered */
+  destinationChain: SupportedChainName;
+  /** Token to deposit or redeem */
+  token: SupportedToken;
+  /** Deposit or redeem */
+  operation: OVaultSyncOperations;
+  /** Human-readable amount (e.g. "100" or "1.5") */
+  amount: string;
+  /** User's wallet address */
+  walletAddress: `0x${string}`;
+
+  // --- Optional overrides ---
+  /** Destination address (defaults to walletAddress) */
+  dstAddress?: `0x${string}`;
+  /** Slippage tolerance as a decimal (0.01 = 1%). Defaults to 0.01. */
+  slippage?: number;
+  /** Extra percentage buffer on the message fee. Defaults to 0.3 (30%). */
+  buffer?: number;
+  /** Whether the token supports EIP-2612 permit. Defaults to false. */
+  supportsEip2612?: boolean;
+  /** Override the LZ compose gas limit for cross-chain operations. */
+  hubLzComposeGasLimit?: bigint;
+  /** Referral code */
+  referralCode?: string;
+  /** Custom RPC URLs keyed by chain name. Avoids public RPC rate limits. */
+  rpcUrls?: Partial<Record<SupportedChainName, string>>;
+}
+
+/**
+ * The send parameters for the OVault. Pass this to the OFT or OVaultComposer to send the tokens.
+ *
+ * @typedef {Object} SendParams
+ * @property {number} dstEid - The destination chain ID.
+ * @property {`0x${string}`} to - The address of the destination contract.
+ * @property {bigint} amountLD - The amount of tokens to send.
+ * @property {bigint} minAmountLD - The minimum amount of tokens to receive.
+ * @property {`0x${string}`} extraOptions - The extra options for the OVault.
+ * @property {`0x${string}`} composeMsg - The compose message for the OVault.
+ * @property {`0x${string}`} oftCmd - The OFT command for the OVault.
+ */
+export interface SendParams {
+  dstEid: number;
+  to: `0x${string}`;
+  amountLD: bigint;
+  minAmountLD: bigint;
+  extraOptions: `0x${string}`;
+  composeMsg: `0x${string}`;
+  oftCmd: `0x${string}`;
+}
+
+/**
+ * The message fee for the OVault.
+ *
+ * @typedef {Object} MessageFee
+ * @property {bigint} nativeFee - The native fee for the OVault.
+ * @property {bigint} lzTokenFee - The LZ token fee for the OVault.
+ */
+export interface MessageFee {
+  nativeFee: bigint;
+  lzTokenFee: bigint;
+}
+
+/**
+ * The inputs for the OVault.
+ *
+ * @typedef {Object} OVaultInputs
+ * @property {MessageFee} messageFee - The message fee for the OVault.
+ * @property {`0x${string}`} contractAddress - The address of the contract to call.
+ * @property {Object} dstAmount - The amount of tokens to send.
+ * @property {Object} approval - The approval parameters for the OVault. If undefined, then no approval is needed.
+ * @property {Object} txArgs - The transaction arguments for the OVault.
+ */
+export type OVaultSyncInputs = {
+  messageFee: MessageFee;
+  contractAddress: `0x${string}`;
+  dstAmount: {
+    amount: bigint;
+    minAmount: bigint;
+  };
+  approval?: {
+    tokenAddress: `0x${string}`;
+    amount: bigint;
+    spender: `0x${string}`;
+    usePermit?: boolean;
+    nonce?: bigint;
+    tokenName?: string;
+    tokenVersion?: string;
+    needsResetApproval?: boolean;
+  };
+} & (
+  | {
+      txArgs: {
+        base: [SendParams, MessageFee, `0x${string}`];
+        permitParams: ["deadline", "v", "r", "s"] | null;
+      };
+      contractFunctionName: "send" | "sendWithPermit";
+      abi: typeof OFTAbi;
+    }
+  | {
+      txArgs: {
+        base: [bigint, SendParams, `0x${string}`];
+        permitParams: ["deadline", "v", "r", "s"] | null;
+      };
+      contractFunctionName:
+        | "depositAndSendWithPermit"
+        | "depositAndSend"
+        | "redeemAndSend";
+      abi: typeof OVaultComposerSyncAbi;
+    }
+  | {
+      txArgs: {
+        base: [bigint, `0x${string}`];
+        permitParams: null;
+      };
+      contractFunctionName: "deposit";
+      abi: typeof ERC4626_ABI;
+    }
+  | {
+      txArgs: {
+        base: [bigint, `0x${string}`, `0x${string}`];
+        permitParams: null;
+      };
+      contractFunctionName: "redeem";
+      abi: typeof ERC4626_ABI;
+    }
+);
+
+export enum OVaultTransactionStep {
+  SOURCE_CHAIN_TRANSACTION = "sourceChainTransaction",
+  SOURCE_TO_HUB_LZ_TRANSACTION = "sourceToHubLzTransaction",
+  HUB_CHAIN_TRANSACTION = "hubChainTransaction",
+  HUB_TO_DST_LZ_TRANSACTION = "hubToDstLzTransaction",
+  DST_CHAIN_TRANSACTION = "dstChainTransaction",
+  COMPLETED = "completed",
+}
+
+export enum OVaultFailureReason {
+  UNKNOWN = "unknown",
+}
+
+export interface OVaultTransactionStatus {
+  step: OVaultTransactionStep;
+
+  // If the transaction failed, this will be set
+  failureReason?: OVaultFailureReason;
+
+  // If the transaction was refunded, this will be set
+  refunded?: boolean;
+}