@zircuit/ovault-evm 0.0.1

package/README.md

@@ -0,0 +1,141 @@
+## Installation
+
+```bash
+pnpm add @zircuit/ovault-evm
+```
+
+```bash
+npm install @zircuit/ovault-evm
+```
+
+## OVault SDK
+
+This is an SDK to make depositing/redeeming on OVaults simple.
+
+### Usage
+
+All information required can be retrieved by calling `OVaultSyncMessageBuilder.generateOVaultInputs`.
+
+You pass a `GenerateOVaultSyncInputsProps` object (see `src/types.ts`). Key points:
+
+- **`amount` is an unscaled string** (e.g. `"1.23"`)
+- **`tokenLocalDecimals`** is required to parse the unscaled amount into local-chain units
+- **`tokenHubDecimals`** should be the asset/share decimals on the **hub chain** (used for `previewDeposit` / `previewRedeem`)
+- **`txArgs`** is now an object: `{ base: [...], permitParams: [...] | null }`
+- Optional **EIP-2612** support via `supportsEip2612` + `sendWithPermit` / `depositAndSendWithPermit`
+
+```typescript
+{
+  srcEid: number,
+  hubEid: number,
+  dstEid: number,
+  walletAddress: `0x${string}`,
+  dstAddress?: `0x${string}`, // If no dstAddress is supplied, it's assumed to be the same as the source wallet address
+  vaultAddress: `0x${string}`,
+  composerAddress: `0x${string}`,
+  oftHubAddress: `0x${string}`,       // hub-chain underlying OFT (used for hub redeem quotes/fees)
+  vaultTokenAddress: `0x${string}`,   // source-chain VaultToken (shares) OFT address (used for spoke redeem quotes/fees)
+  hubChain: Chain, // This is a Viem chain definition
+  sourceChain: Chain, // This is a Viem chain definition
+  operation: OVaultSyncOperations,
+  amount: string, // unscaled string (e.g. "1.23")
+  tokenLocalDecimals: number,
+  tokenHubDecimals?: number,
+  slippage: number, // such as 0.01 for 1% slippage
+  buffer?: number,               // optional fee buffer (e.g. 0.3 => +30%)
+  referralCode?: string,         // optional referral code forwarded via oftCmd
+  oftAddress: `0x${string}`,      // source-chain OFT/OFTAdapter address
+  tokenAddress: `0x${string}`,    // source-chain ERC20 address (or 0x0 for native)
+  supportsEip2612?: boolean,
+  requiresZeroApprovalReset?: boolean,
+}
+```
+
+For full information about the input object check `GenerateOVaultSyncInputsProps` in `src/types.ts`.
+
+You will receive an `OVaultSyncInputs` object back containing all information you need to build the transaction.
+
+### Example
+
+#### Base Functionality
+
+Below is an example of how to deposit tokens using the Viem client on a server side environment.
+
+```typescript
+const input = {
+  srcEid: 40245, // eid for base-sepolia
+  hubEid: 40231, // eid for arbitrum-sepolia
+  dstEid: 40245, // eid for base-sepolia
+
+  // Optional. If dstAddress is not specified it will default to the walletAddress on the dst chain
+  dstAddress: "0x0000000000000000000000000000000000000000",
+  walletAddress: "0x0000000000000000000000000000000000000000",
+  vaultAddress: "0x0000000000000000000000000000000000000000",
+
+  // Address of the OVault Composer on the Hub Chain. Should implement IVaultComposerSync
+  composerAddress: "0x0000000000000000000000000000000000000000",
+  oftHubAddress: "0x0000000000000000000000000000000000000000",
+  vaultTokenAddress: "0x0000000000000000000000000000000000000000",
+
+  // Supply the Viem Chain Definitions for the hub and source chain. This is so the sdk can
+  // quote fees and perform read operations
+  hubChain: arbitrumSepolia,
+  sourceChain: baseSepolia,
+  operation: OVaultSyncOperations.DEPOSIT,
+  amount: "1.0", // unscaled string
+  tokenLocalDecimals: 18,
+  tokenHubDecimals: 18,
+  slippage: 0.01, // 1% slippage
+
+  // Address of the token/oft. The token is an ERC20. They can be the same address.
+  tokenAddress: "0x0000000000000000000000000000000000000000",
+  oftAddress: "0x0000000000000000000000000000000000000000",
+} as const;
+
+const inputs = await OVaultSyncMessageBuilder.generateOVaultInputs(input);
+const account = privateKeyToAccount("YOUR PRIVATE KEY HERE");
+
+const walletClient = createWalletClient({
+  account,
+  chain: srcChain.chain,
+  transport: http(),
+}).extend(publicActions);
+
+if (inputs.approval) {
+  // Approve token if required
+  const approvalTx = await walletClient.writeContract({
+    address: inputs.approval.tokenAddress,
+    abi: ERC20Abi,
+    functionName: "approve",
+    args: [inputs.approval.spender, inputs.approval.amount],
+  });
+  await walletClient.waitForTransactionReceipt({ hash: approvalTx });
+}
+
+const tx = await walletClient.writeContract({
+  address: inputs.contractAddress,
+  abi: inputs.abi,
+  value: inputs.messageFee.nativeFee,
+  functionName: inputs.contractFunctionName,
+  args: inputs.txArgs.base as any,
+});
+```
+
+For more example usage see `test/sdk/transfer.test.ts`.
+
+## Tracking transactions
+
+To track cross-chain progress, use:
+
+```ts
+import { trackOVaultSyncTransaction } from "@zircuit/ovault-evm"
+```
+
+`trackOVaultSyncTransaction(txHash, { sourceChain, hubChain, dstChain }, withdrawalInfo?)`
+
+If you are tracking withdrawals where multiple messages may exist, you can provide `withdrawalInfo` (`OVaultWithdrawalInfo`) so the tracker can pick the correct message index.
+
+## Development
+
+- **Build/typecheck**: `npm run -s sdk:build`
+- **Run SDK tests**: `npm run -s sdk:test`

package/dist/addresses.d.ts

@@ -0,0 +1,41 @@
+import type { Chain as ViemChain } from "viem";
+export type SupportedChainName = "ethereum" | "base";
+export interface ChainMeta {
+    /** LayerZero Endpoint ID */
+    eid: number;
+    /** viem Chain object */
+    viemChain: ViemChain;
+}
+export declare const CHAINS: Record<SupportedChainName, ChainMeta>;
+export type SupportedToken = "usdc" | "usdt";
+interface ClusterChainDeployment {
+    /** UnderlyingOFT (hub) or UnderlyingOFTAdapter (spoke) */
+    oft: `0x${string}`;
+    /** Vault (hub) or VaultToken (spoke) */
+    vault: `0x${string}`;
+    /** Underlying ERC-20 token address on this chain */
+    token: `0x${string}`;
+}
+interface HubChainDeployment extends ClusterChainDeployment {
+    composer: `0x${string}`;
+}
+interface ClusterConfig {
+    hubChain: "base";
+    /** Token decimals on the hub chain */
+    hubDecimals: number;
+    /** Whether the token requires resetting approval to 0 before setting a new value (e.g. USDT) */
+    requiresZeroApprovalReset: boolean;
+    /** Per-chain deployments keyed by chain name */
+    chains: Partial<Record<SupportedChainName, ClusterChainDeployment>> & {
+        /** Hub chain always present and includes composer */
+        base: HubChainDeployment;
+    };
+}
+/**
+ * Built-in address registry
+ *
+ * Hub chain is always **Base** for all clusters.
+ */
+export declare const CLUSTERS: Record<SupportedToken, ClusterConfig>;
+export {};
+//# sourceMappingURL=addresses.d.ts.map

package/dist/addresses.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"addresses.d.ts","sourceRoot":"","sources":["../src/addresses.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,IAAI,SAAS,EAAE,MAAM,MAAM,CAAC;AAO/C,MAAM,MAAM,kBAAkB,GAAG,UAAU,GAAG,MAAM,CAAC;AAErD,MAAM,WAAW,SAAS;IACxB,4BAA4B;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,wBAAwB;IACxB,SAAS,EAAE,SAAS,CAAC;CACtB;AAED,eAAO,MAAM,MAAM,EAAE,MAAM,CAAC,kBAAkB,EAAE,SAAS,CAG/C,CAAC;AAMX,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,MAAM,CAAC;AAM7C,UAAU,sBAAsB;IAC9B,0DAA0D;IAC1D,GAAG,EAAE,KAAK,MAAM,EAAE,CAAC;IACnB,wCAAwC;IACxC,KAAK,EAAE,KAAK,MAAM,EAAE,CAAC;IACrB,oDAAoD;IACpD,KAAK,EAAE,KAAK,MAAM,EAAE,CAAC;CACtB;AAED,UAAU,kBAAmB,SAAQ,sBAAsB;IACzD,QAAQ,EAAE,KAAK,MAAM,EAAE,CAAC;CACzB;AAED,UAAU,aAAa;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,sCAAsC;IACtC,WAAW,EAAE,MAAM,CAAC;IACpB,gGAAgG;IAChG,yBAAyB,EAAE,OAAO,CAAC;IACnC,gDAAgD;IAChD,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,kBAAkB,EAAE,sBAAsB,CAAC,CAAC,GAAG;QACpE,qDAAqD;QACrD,IAAI,EAAE,kBAAkB,CAAC;KAC1B,CAAC;CACH;AAED;;;;GAIG;AACH,eAAO,MAAM,QAAQ,EAAE,MAAM,CAAC,cAAc,EAAE,aAAa,CAqC1D,CAAC"}

package/dist/addresses.js

@@ -0,0 +1,48 @@
+import { mainnet, base } from "viem/chains";
+export const CHAINS = {
+    ethereum: { eid: 30101, viemChain: mainnet },
+    base: { eid: 30184, viemChain: base },
+};
+/**
+ * Built-in address registry
+ *
+ * Hub chain is always **Base** for all clusters.
+ */
+export const CLUSTERS = {
+    usdc: {
+        hubChain: "base",
+        hubDecimals: 6,
+        requiresZeroApprovalReset: false,
+        chains: {
+            base: {
+                oft: "0xd7aBC360dfcF1B6dD0a03138235e12A2bc1c1C8B",
+                vault: "0x03067bbD0d41E3Fe4A0bb6ca67c99e7352Da4CAE",
+                composer: "0xBb801ED781dF31F660cC743bEf7Bb9D04B030923",
+                token: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+            },
+            ethereum: {
+                oft: "0xd58E8c1c83d598aD76B5f0E26B4a25cdB885d190",
+                vault: "0x07C898e77310870770f88d18a01009cB65A1c1a9",
+                token: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+            },
+        },
+    },
+    usdt: {
+        hubChain: "base",
+        hubDecimals: 6,
+        requiresZeroApprovalReset: true,
+        chains: {
+            base: {
+                oft: "0x264D6474802Ef8bc1bc05F89F7d640D1E93c5330",
+                vault: "0x25d90ABd6c1E8DCCD40932D2fdD2Cd381bfc832D",
+                composer: "0x16cE6D9576A411911e62b6073F1cc9d1347ad96B",
+                token: "0x820266ecC2D268B0fBbD2aA3a1bdf28d12582Bbc",
+            },
+            ethereum: {
+                oft: "0x2D342De4c58a871b3525740C58a1C112D5835865",
+                vault: "0x8ADbeA709B31A564f9750A280EC2690aD1cf470A",
+                token: "0xdAC17F958D2ee523a2206206994597C13D831ec7",
+            },
+        },
+    },
+};

package/dist/contracts/EIP2612.d.ts

@@ -0,0 +1,14 @@
+export declare const EIP2612_ABI: {
+    inputs: {
+        name: string;
+        type: string;
+    }[];
+    name: string;
+    outputs: {
+        name: string;
+        type: string;
+    }[];
+    stateMutability: string;
+    type: string;
+}[];
+//# sourceMappingURL=EIP2612.d.ts.map

package/dist/contracts/EIP2612.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EIP2612.d.ts","sourceRoot":"","sources":["../../src/contracts/EIP2612.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,WAAW;;;;;;;;;;;;GAqCvB,CAAC"}

package/dist/contracts/EIP2612.js

@@ -0,0 +1,38 @@
+export const EIP2612_ABI = [
+    {
+        inputs: [
+            { name: "owner", type: "address" },
+            { name: "spender", type: "address" },
+            { name: "value", type: "uint256" },
+            { name: "deadline", type: "uint256" },
+            { name: "v", type: "uint8" },
+            { name: "r", type: "bytes32" },
+            { name: "s", type: "bytes32" },
+        ],
+        name: "permit",
+        outputs: [],
+        stateMutability: "nonpayable",
+        type: "function",
+    },
+    {
+        inputs: [{ name: "owner", type: "address" }],
+        name: "nonces",
+        outputs: [{ name: "", type: "uint256" }],
+        stateMutability: "view",
+        type: "function",
+    },
+    {
+        inputs: [],
+        name: "DOMAIN_SEPARATOR",
+        outputs: [{ name: "", type: "bytes32" }],
+        stateMutability: "view",
+        type: "function",
+    },
+    {
+        inputs: [],
+        name: "version",
+        outputs: [{ name: "", type: "string" }],
+        stateMutability: "view",
+        type: "function",
+    },
+];

package/dist/contracts/ERC20.d.ts

@@ -0,0 +1,169 @@
+export declare const ERC20Abi: readonly [{
+    readonly constant: true;
+    readonly inputs: readonly [];
+    readonly name: "name";
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "string";
+    }];
+    readonly payable: false;
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly constant: false;
+    readonly inputs: readonly [{
+        readonly name: "_spender";
+        readonly type: "address";
+    }, {
+        readonly name: "_value";
+        readonly type: "uint256";
+    }];
+    readonly name: "approve";
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "bool";
+    }];
+    readonly payable: false;
+    readonly stateMutability: "nonpayable";
+    readonly type: "function";
+}, {
+    readonly constant: true;
+    readonly inputs: readonly [];
+    readonly name: "totalSupply";
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+    readonly payable: false;
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly constant: false;
+    readonly inputs: readonly [{
+        readonly name: "_from";
+        readonly type: "address";
+    }, {
+        readonly name: "_to";
+        readonly type: "address";
+    }, {
+        readonly name: "_value";
+        readonly type: "uint256";
+    }];
+    readonly name: "transferFrom";
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "bool";
+    }];
+    readonly payable: false;
+    readonly stateMutability: "nonpayable";
+    readonly type: "function";
+}, {
+    readonly constant: true;
+    readonly inputs: readonly [];
+    readonly name: "decimals";
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint8";
+    }];
+    readonly payable: false;
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly constant: true;
+    readonly inputs: readonly [{
+        readonly name: "_owner";
+        readonly type: "address";
+    }];
+    readonly name: "balanceOf";
+    readonly outputs: readonly [{
+        readonly name: "balance";
+        readonly type: "uint256";
+    }];
+    readonly payable: false;
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly constant: true;
+    readonly inputs: readonly [];
+    readonly name: "symbol";
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "string";
+    }];
+    readonly payable: false;
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly constant: false;
+    readonly inputs: readonly [{
+        readonly name: "_to";
+        readonly type: "address";
+    }, {
+        readonly name: "_value";
+        readonly type: "uint256";
+    }];
+    readonly name: "transfer";
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "bool";
+    }];
+    readonly payable: false;
+    readonly stateMutability: "nonpayable";
+    readonly type: "function";
+}, {
+    readonly constant: true;
+    readonly inputs: readonly [{
+        readonly name: "_owner";
+        readonly type: "address";
+    }, {
+        readonly name: "_spender";
+        readonly type: "address";
+    }];
+    readonly name: "allowance";
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+    readonly payable: false;
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly payable: true;
+    readonly stateMutability: "payable";
+    readonly type: "fallback";
+}, {
+    readonly anonymous: false;
+    readonly inputs: readonly [{
+        readonly indexed: true;
+        readonly name: "owner";
+        readonly type: "address";
+    }, {
+        readonly indexed: true;
+        readonly name: "spender";
+        readonly type: "address";
+    }, {
+        readonly indexed: false;
+        readonly name: "value";
+        readonly type: "uint256";
+    }];
+    readonly name: "Approval";
+    readonly type: "event";
+}, {
+    readonly anonymous: false;
+    readonly inputs: readonly [{
+        readonly indexed: true;
+        readonly name: "from";
+        readonly type: "address";
+    }, {
+        readonly indexed: true;
+        readonly name: "to";
+        readonly type: "address";
+    }, {
+        readonly indexed: false;
+        readonly name: "value";
+        readonly type: "uint256";
+    }];
+    readonly name: "Transfer";
+    readonly type: "event";
+}];
+//# sourceMappingURL=ERC20.d.ts.map

package/dist/contracts/ERC20.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ERC20.d.ts","sourceRoot":"","sources":["../../src/contracts/ERC20.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA6NX,CAAC"}

package/dist/contracts/ERC20.js

@@ -0,0 +1,222 @@
+export const ERC20Abi = [
+    {
+        constant: true,
+        inputs: [],
+        name: "name",
+        outputs: [
+            {
+                name: "",
+                type: "string",
+            },
+        ],
+        payable: false,
+        stateMutability: "view",
+        type: "function",
+    },
+    {
+        constant: false,
+        inputs: [
+            {
+                name: "_spender",
+                type: "address",
+            },
+            {
+                name: "_value",
+                type: "uint256",
+            },
+        ],
+        name: "approve",
+        outputs: [
+            {
+                name: "",
+                type: "bool",
+            },
+        ],
+        payable: false,
+        stateMutability: "nonpayable",
+        type: "function",
+    },
+    {
+        constant: true,
+        inputs: [],
+        name: "totalSupply",
+        outputs: [
+            {
+                name: "",
+                type: "uint256",
+            },
+        ],
+        payable: false,
+        stateMutability: "view",
+        type: "function",
+    },
+    {
+        constant: false,
+        inputs: [
+            {
+                name: "_from",
+                type: "address",
+            },
+            {
+                name: "_to",
+                type: "address",
+            },
+            {
+                name: "_value",
+                type: "uint256",
+            },
+        ],
+        name: "transferFrom",
+        outputs: [
+            {
+                name: "",
+                type: "bool",
+            },
+        ],
+        payable: false,
+        stateMutability: "nonpayable",
+        type: "function",
+    },
+    {
+        constant: true,
+        inputs: [],
+        name: "decimals",
+        outputs: [
+            {
+                name: "",
+                type: "uint8",
+            },
+        ],
+        payable: false,
+        stateMutability: "view",
+        type: "function",
+    },
+    {
+        constant: true,
+        inputs: [
+            {
+                name: "_owner",
+                type: "address",
+            },
+        ],
+        name: "balanceOf",
+        outputs: [
+            {
+                name: "balance",
+                type: "uint256",
+            },
+        ],
+        payable: false,
+        stateMutability: "view",
+        type: "function",
+    },
+    {
+        constant: true,
+        inputs: [],
+        name: "symbol",
+        outputs: [
+            {
+                name: "",
+                type: "string",
+            },
+        ],
+        payable: false,
+        stateMutability: "view",
+        type: "function",
+    },
+    {
+        constant: false,
+        inputs: [
+            {
+                name: "_to",
+                type: "address",
+            },
+            {
+                name: "_value",
+                type: "uint256",
+            },
+        ],
+        name: "transfer",
+        outputs: [
+            {
+                name: "",
+                type: "bool",
+            },
+        ],
+        payable: false,
+        stateMutability: "nonpayable",
+        type: "function",
+    },
+    {
+        constant: true,
+        inputs: [
+            {
+                name: "_owner",
+                type: "address",
+            },
+            {
+                name: "_spender",
+                type: "address",
+            },
+        ],
+        name: "allowance",
+        outputs: [
+            {
+                name: "",
+                type: "uint256",
+            },
+        ],
+        payable: false,
+        stateMutability: "view",
+        type: "function",
+    },
+    {
+        payable: true,
+        stateMutability: "payable",
+        type: "fallback",
+    },
+    {
+        anonymous: false,
+        inputs: [
+            {
+                indexed: true,
+                name: "owner",
+                type: "address",
+            },
+            {
+                indexed: true,
+                name: "spender",
+                type: "address",
+            },
+            {
+                indexed: false,
+                name: "value",
+                type: "uint256",
+            },
+        ],
+        name: "Approval",
+        type: "event",
+    },
+    {
+        anonymous: false,
+        inputs: [
+            {
+                indexed: true,
+                name: "from",
+                type: "address",
+            },
+            {
+                indexed: true,
+                name: "to",
+                type: "address",
+            },
+            {
+                indexed: false,
+                name: "value",
+                type: "uint256",
+            },
+        ],
+        name: "Transfer",
+        type: "event",
+    },
+];