@ember-finance/sdk 1.0.29 → 1.1.1

package/README.md

@@ -1,8 +1,8 @@
 # Ember Protocol SDK
 
-A comprehensive TypeScript SDK for interacting with the Ember Protocol on the Sui
-blockchain. This SDK provides a complete set of tools for managing vaults, handling user
-operations, and administering the protocol.
+A comprehensive TypeScript SDK for interacting with the Ember Protocol on both SUI and
+EVM-compatible blockchains. This SDK provides a complete set of tools for managing vaults,
+handling user operations, and administering the protocol.
 
 [![npm version](https://badge.fury.io/js/@ember-finance%2Fsdk.svg)](https://www.npmjs.com/package/@ember-finance/sdk)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
@@ -10,15 +10,22 @@ operations, and administering the protocol.
 ## Overview
 
 The Ember Protocol SDK is a TypeScript library that enables developers to interact with
-the Ember Protocol's vault system on the Sui blockchain. The protocol allows users to
-deposit assets into vaults, receive receipt tokens, and participate in yield-generating
-strategies.
+the Ember Protocol's vault system on both SUI and EVM-compatible blockchains. The protocol
+allows users to deposit assets into vaults, receive shares, and participate in
+yield-generating strategies.
+
+### Supported Chains
+
+-   **SUI** - Full support for SUI blockchain
+-   **EVM** - Support for Ethereum and EVM-compatible chains (using ethers.js v6)
+    -   EVM vaults implement the **ERC-4626** tokenized vault standard
+    -   The vault contract itself is the share token (ERC20)
 
 ### Architecture
 
 The SDK is built around several key classes:
 
--   **EmberVaults**: Main entry point for vault interactions
+-   **EmberVaults**: Main entry point for vault interactions (supports both SUI and EVM)
 -   **AdminCalls**: Administrative functions for protocol management
 -   **UserCalls**: User-facing operations for deposits and withdrawals
 -   **OperatorCalls**: Operator functions for vault management
@@ -37,6 +44,172 @@ or
 yarn add @ember-finance/sdk
 ```
 
+## Usage
+
+### SUI Chain - User Deposit Example
+
+```typescript
+import { EmberVaults } from "@ember-finance/sdk";
+import { SuiClient, Ed25519Keypair } from "@mysten/sui.js";
+
+// Setup SUI client and signer
+const suiClient = new SuiClient({ url: "https://fullnode.mainnet.sui.io" });
+const keypair = Ed25519Keypair.fromSecretKey(privateKeyBytes);
+
+// Initialize EmberVaults for SUI
+const ember = new EmberVaults({
+    chainType: "sui",
+    network: "mainnet",
+    suiClient,
+    signer: keypair,
+    environment: "prod" // "prod" | "staging" | "dev"
+});
+
+// Fetch deployment configuration from API
+await ember.init();
+
+// Get vault information
+const vaultId = ember.parser.getVaultIdFromName("USDC Vault");
+
+// Deposit assets into the vault
+const depositAmount = "1000000"; // 1 USDC (6 decimals)
+const result = await ember.user.depositAsset(vaultId, depositAmount);
+
+console.log("Deposit successful:", result);
+```
+
+### EVM Chain - User Deposit Example (ERC-4626)
+
+The EVM vaults implement the ERC-4626 tokenized vault standard. The vault contract itself
+is the share token, so there's no separate receipt token.
+
+```typescript
+import { EmberVaults } from "@ember-finance/sdk";
+import { ethers } from "ethers";
+
+// Setup ethers provider and signer
+const provider = new ethers.JsonRpcProvider("https://eth-mainnet.g.alchemy.com/v2/YOUR_API_KEY");
+const signer = new ethers.Wallet(privateKey, provider);
+
+// EVM deployment configuration (can be fetched from API or provided directly)
+const deployment = {
+    network: "ethereum",
+    chainId: "1",
+    contracts: {
+        protocolConfig: {
+            proxyAddress: "0x...",
+            // ... other config
+        },
+        vaults: {
+            "USDC Vault": {
+                proxyAddress: "0x...",
+                baseToken: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC
+                // ... other config
+            }
+        },
+        receiptTokens: {
+            // Note: For ERC-4626, the vault is the share token
+        }
+    }
+};
+
+// Initialize EmberVaults for EVM
+const ember = new EmberVaults({
+    chainType: "evm",
+    signer,
+    provider,
+    deployment,
+    environment: "prod"
+});
+
+// Or fetch deployment from API
+// await ember.init();
+
+const vaultAddress = deployment.contracts.vaults["USDC Vault"].proxyAddress;
+const underlyingAsset = deployment.contracts.vaults["USDC Vault"].baseToken;
+const depositAmount = "1000000"; // 1 USDC (6 decimals)
+
+// Step 1: Approve token spending (required for EVM)
+await ember.user.approveTokenMax(underlyingAsset, vaultAddress);
+
+// Step 2: Deposit assets (ERC-4626 standard: deposit(assets, receiver))
+// Receiver defaults to caller
+const result = await ember.user.deposit(vaultAddress, depositAmount);
+
+console.log("Deposit successful:", result);
+
+// Optional: Wait for receipt and get events
+const resultWithEvents = await ember.user.deposit(
+    vaultAddress,
+    depositAmount,
+    { waitForReceipt: true }
+);
+
+console.log("Events:", resultWithEvents.events);
+```
+
+### EVM - Deposit to a Different Receiver
+
+```typescript
+// Deposit, with shares going to a different address
+const result = await ember.user.deposit(
+    vaultAddress,
+    depositAmount,
+    { receiver: "0xRecipientAddress..." }
+);
+```
+
+### EVM - Mint Specific Shares (ERC-4626)
+
+```typescript
+// Mint a specific number of shares (vault will pull required assets)
+const sharesToMint = "1000000000000000000"; // 1e18 shares
+
+await ember.user.mint(vaultAddress, sharesToMint);
+
+// Mint to a different receiver
+await ember.user.mint(vaultAddress, sharesToMint, {
+    receiver: "0xRecipientAddress..."
+});
+```
+
+### EVM - Redeem Shares (Initiate Withdrawal)
+
+```typescript
+// Redeem shares to initiate a withdrawal request
+// Note: Withdrawal requests are processed by operators, not immediate
+const shares = "500000000000000000000"; // shares to redeem
+
+// Redeem to self (default)
+await ember.user.redeemShares(vaultAddress, shares);
+
+// Redeem to a different receiver
+await ember.user.redeemShares(vaultAddress, shares, {
+    receiver: "0xRecipientAddress..."
+});
+```
+
+### Type-Safe Chain Access
+
+```typescript
+// Check chain type at runtime
+if (ember.isSui()) {
+    // TypeScript knows this is SUI
+    const suiClient = ember.suiClient;
+    // ... SUI-specific operations
+}
+
+if (ember.isEvm()) {
+    // TypeScript knows this is EVM
+    const provider = ember.provider;
+    // ... EVM-specific operations
+}
+
+// Get strongly-typed chain-specific instance
+const suiEmber = ember.asSui();  // throws if not SUI
+const evmEmber = ember.asEvm();  // throws if not EVM
+```
+
 ## Core Components
 
 ### EmberVaults
@@ -44,55 +217,92 @@ yarn add @ember-finance/sdk
 The main entry point for interacting with the Ember Protocol:
 
 ```typescript
-class EmberVaults {
-  suiClient: SuiClient;
-  signer: Signer;
-  parser: DeploymentParser;
-  walletAddress: string;
-  txBuilder: TxBuilder;
-  network: string;
-  admin: AdminCalls;
-}
+// Common properties available for both chains
+ember.chainType     // "sui" | "evm"
+ember.vaultsApi     // VaultsApi - same for both chains
+ember.api           // AccountsApi - same for both chains
+ember.parser        // Deployment parser (chain-specific)
+ember.txBuilder     // Transaction builder (chain-specific)
+ember.admin         // Admin calls (chain-specific)
+ember.operator      // Operator calls (chain-specific)
+ember.vaultAdmin    // Vault admin calls (chain-specific)
+ember.user          // User calls (chain-specific)
+ember.deployment    // Deployment config (chain-specific)
 ```
 
 ### User Operations (UserCalls)
 
 Handle user-facing vault operations:
 
+**EVM (ERC-4626):**
+
+-   **deposit**: Deposit assets and receive shares (ERC-4626 standard)
+-   **mint**: Mint specific shares by depositing required assets (ERC-4626 standard)
+-   **redeemShares**: Redeem shares to initiate withdrawal request
+-   **cancelPendingWithdrawalRequest**: Cancel pending withdrawal requests
+-   **approveToken**: Approve token spending
+-   **approveTokenMax**: Approve maximum token spending
+
+**SUI:**
+
 -   **depositAsset**: Deposit assets into a vault
 -   **mintShares**: Mint vault shares with specific amount
 -   **redeemShares**: Redeem shares for underlying assets
--   **requestWithdrawal**: Request withdrawal with time delay
--   **cancelWithdrawalRequest**: Cancel pending withdrawal requests
+-   **cancelPendingWithdrawalRequest**: Cancel pending withdrawal requests
 
 ### Admin Functions (AdminCalls)
 
 Protocol-level administrative functions:
 
--   **createVault**: Create new vaults
--   **updateAdmin**: Update vault admin addresses
 -   **updateMaxFeePercentage**: Update protocol fee limits
--   **pauseProtocol**: Emergency protocol controls
+-   **pauseNonAdminOperations**: Emergency protocol controls
+-   **updatePlatformFeeRecipient**: Update fee recipient
+-   **setBlacklistedAccount**: Manage blacklisted accounts
+-   **updateVaultAdmin**: Update vault admin address
 
 ### Operator Functions (OperatorCalls)
 
 Vault operator management functions:
 
 -   **collectPlatformFee**: Collect accumulated fees
--   **chargePlatformFee**: Charge fees from vault
 -   **processWithdrawalRequests**: Process pending withdrawals
--   **updateVaultRate**: Update vault exchange rates
--   **withdrawFromVault**: Direct vault withdrawals
--   **depositToVault**: Direct vault deposits
+-   **updateVaultRate**: Update vault exchange rates (rate manager role)
+-   **withdrawFromVaultWithoutRedeemingShares**: Withdraw for strategy execution
 
 ### Vault Admin Functions (VaultAdminCalls)
 
-Vault-specific administrative controls:
+Vault-specific administrative controls (called via ProtocolConfig on EVM):
 
--   **setMinWithdrawalShares**: Configure minimum withdrawal amounts
--   **setSubAccount**: Manage vault sub-accounts
+-   **updateVaultMinWithdrawableShares**: Configure minimum withdrawal amounts
+-   **setVaultSubAccount**: Manage vault sub-accounts
 -   **updateVaultOperator**: Change vault operators
--   **updateVaultPausedStatus**: Pause/unpause individual vaults
+-   **updateVaultRateManager**: Change rate manager
+-   **setVaultPausedStatus**: Pause/unpause vault operations
+-   **updateVaultFeePercentage**: Update vault fee percentage
+-   **updateVaultMaxTVL**: Update maximum TVL
+-   **updateVaultRateUpdateInterval**: Update rate update interval
+-   **updateVaultName**: Update vault name
+
+## ERC-4626 Compatibility (EVM)
+
+The EVM vaults are fully ERC-4626 compliant:
+
+| ERC-4626 Method                     | SDK Method                                 | Notes                             |
+| ----------------------------------- | ------------------------------------------ | --------------------------------- |
+| `asset()`                           | -                                          | Returns underlying asset address  |
+| `deposit(assets, receiver)`         | `user.deposit(vault, assets, {receiver?})` | Deposit assets, get shares        |
+| `mint(shares, receiver)`            | `user.mint(vault, shares, {receiver?})`    | Mint shares by depositing assets  |
+| `withdraw(assets, receiver, owner)` | N/A                                        | Not supported, use `redeemShares` |
+| `redeem(shares, receiver, owner)`   | N/A                                        | Not supported, use `redeemShares` |
+| `totalAssets()`                     | -                                          | Read via contract                 |
+| `convertToShares(assets)`           | -                                          | Read via contract                 |
+| `convertToAssets(shares)`           | -                                          | Read via contract                 |
+| `previewDeposit(assets)`            | -                                          | Read via contract                 |
+| `previewMint(shares)`               | -                                          | Read via contract                 |
+
+Note: Standard ERC-4626 `withdraw` and `redeem` are not supported due to the vault's async
+withdrawal mechanism. Use `redeemShares` to initiate a withdrawal request, which will be
+processed by vault operators.
 
 ## License