@wayne-zhang/ovault-evm 0.0.1

package/README.md

@@ -0,0 +1,141 @@
+## Installation
+
+```bash
+pnpm add @wayne-zhang/ovault-evm
+```
+
+```bash
+npm install @wayne-zhang/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 "@wayne-zhang/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`