Ember Protocol SDK

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.

Overview

The Ember Protocol SDK is a TypeScript library that enables developers to interact with 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 (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
• VaultAdminCalls: Vault-specific administrative functions
• TxBuilder: Transaction building utilities

Installation

npm install @ember-finance/sdk

or

yarn add @ember-finance/sdk

Usage

SUI Chain - User Deposit Example

import { EmberVaults } from "@ember-finance/sdk";
import { SuiJsonRpcClient } from "@mysten/sui/jsonRpc";
import { Ed25519Keypair } from "@mysten/sui/keypairs/ed25519";

// Setup SUI client and signer
const suiClient = new SuiJsonRpcClient({
    url: "https://fullnode.mainnet.sui.io",
    network: "mainnet"
});
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.

Traditional Approach (Two Transactions)

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);

New Approach: Single Transaction with EIP-2612 Permit (Recommended)

The new depositWithPermit and mintWithPermit methods allow depositing in a single transaction without requiring a separate approval transaction. This uses EIP-2612 permit signatures.

import { EmberVaults, signPermitSimple } from "@ember-finance/sdk";
import { ethers } from "ethers";

// Setup (same as above)
const provider = new ethers.JsonRpcProvider("https://eth-mainnet.g.alchemy.com/v2/YOUR_API_KEY");
const signer = new ethers.Wallet(privateKey, provider);

const ember = new EmberVaults({
    chainType: "evm",
    signer,
    provider,
    deployment,
    environment: "prod"
});

const vaultAddress = deployment.contracts.vaults["USDC Vault"].proxyAddress;
const underlyingAsset = deployment.contracts.vaults["USDC Vault"].baseToken;
const depositAmount = "1000000"; // 1 USDC (6 decimals)

// Generate permit signature (off-chain, no gas cost)
const permitSig = await signPermitSimple(
    signer,
    underlyingAsset,
    "USD Coin", // Token name (must match token's EIP-2612 name)
    vaultAddress,
    depositAmount
);

// null means the token's permit domain couldn't be verified against its
// DOMAIN_SEPARATOR(), so the permit would be rejected: approve + deposit instead
let result;
if (permitSig) {
    // Deposit with permit in a SINGLE transaction (no separate approval needed!)
    result = await ember.user.depositWithPermit(vaultAddress, depositAmount, permitSig);
} else {
    await ember.user.approveToken(underlyingAsset, vaultAddress, depositAmount);
    result = await ember.user.deposit(vaultAddress, depositAmount);
}

console.log("Deposit successful:", result);

EVM - Deposit to a Different Receiver

// Deposit, with shares going to a different address
const result = await ember.user.deposit(
    vaultAddress,
    depositAmount,
    { receiver: "0xRecipientAddress..." }
);

EVM - Mint Specific Shares (ERC-4626)

Traditional Approach (Requires Approval)

// Mint a specific number of shares (vault will pull required assets)
const sharesToMint = "1000000000000000000"; // 1e18 shares

// Must approve first
await ember.user.approveTokenMax(underlyingAsset, vaultAddress);

await ember.user.mint(vaultAddress, sharesToMint);

// Mint to a different receiver
await ember.user.mint(vaultAddress, sharesToMint, {
    receiver: "0xRecipientAddress..."
});

Single Transaction with Permit

import { signPermitSimple } from "@ember-finance/sdk";

const sharesToMint = "1000000000000000000"; // 1e18 shares

// Generate permit signature for a high amount (vault will pull exact amount needed)
const permitSig = await signPermitSimple(
    signer,
    underlyingAsset,
    "USD Coin",
    vaultAddress,
    "115792089237316195423570985008687907853269984665640564039457584007913129639935" // max uint256
);

// null means the token's permit domain couldn't be verified: use the two-step
// approve + mint flow above instead
if (permitSig) {
    // Mint with permit in single transaction
    await ember.user.mintWithPermit(vaultAddress, sharesToMint, permitSig);

    // Or mint to a different receiver
    // await ember.user.mintWithPermit(vaultAddress, sharesToMint, permitSig, {
    //     receiver: "0xRecipientAddress..."
    // });
}

EVM - Redeem Shares (Initiate Withdrawal)

// 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

// 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

The main entry point for interacting with the Ember Protocol:

// 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, requires approval)
• depositWithPermit: Deposit assets using EIP-2612 permit (single transaction, no approval needed) ✨ NEW
• mint: Mint specific shares by depositing required assets (ERC-4626 standard, requires approval)
• mintWithPermit: Mint shares using EIP-2612 permit (single transaction, no approval needed) ✨ NEW
• redeemShares: Redeem shares to initiate withdrawal request
• cancelPendingWithdrawalRequest: Cancel pending withdrawal requests
• approveToken: Approve token spending
• approveTokenMax: Approve maximum token spending

Permit Utilities (EVM): ✨ NEW

• signPermitSimple: Generate EIP-2612 permit signature with automatic nonce, deadline and EIP-712 domain; returns null if the domain doesn't match the token's DOMAIN_SEPARATOR()
• signPermit: Generate EIP-2612 permit signature with custom parameters
• resolvePermitDomain: Get a token's EIP-712 permit domain (EIP-5267 eip712Domain(), else token name with version(), defaulting to "1")
• getPermitNonce: Get current permit nonce for a user

SUI:

• depositAsset: Deposit assets into a vault
• mintShares: Mint vault shares with specific amount
• redeemShares: Redeem shares for underlying assets
• cancelPendingWithdrawalRequest: Cancel pending withdrawal requests

Admin Functions (AdminCalls)

Protocol-level administrative functions:

• updateMaxFeePercentage: Update protocol fee limits
• 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
• processWithdrawalRequests: Process pending withdrawals
• updateVaultRate: Update vault exchange rates (rate manager role)
• withdrawFromVaultWithoutRedeemingShares: Withdraw for strategy execution

Vault Admin Functions (VaultAdminCalls)

Vault-specific administrative controls (called via ProtocolConfig on EVM):

• updateVaultMinWithdrawableShares: Configure minimum withdrawal amounts
• setVaultSubAccount: Manage vault sub-accounts
• updateVaultOperator: Change vault operators
• 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

EIP-2612 Permit Support (EVM) ✨ NEW

The Ember vaults now support EIP-2612 permit signatures, allowing users to deposit or mint shares in a single transaction without requiring a separate approval transaction. This significantly improves the user experience by:

• Reducing gas costs (one transaction instead of two)
• Eliminating the need to wait for approval transaction confirmation
• Providing a smoother, faster deposit flow

How Permit Works

EIP-2612 allows users to sign an off-chain message (no gas cost) that authorizes the vault to spend their tokens. This signature is then included in the deposit/mint transaction, which handles both the approval and the deposit atomically.

Using Permit with the SDK

import { EmberVaults, signPermitSimple } from "@ember-finance/sdk";

// 1. Generate permit signature (off-chain, no gas)
const permitSig = await signPermitSimple(
    signer,
    tokenAddress,
    "USD Coin", // Token name (must match EIP-2612 name)
    vaultAddress,
    amount
);

// 2. Deposit with permit (single transaction), or approve + deposit if no permit
if (permitSig) {
    await ember.user.depositWithPermit(vaultAddress, amount, permitSig);
} else {
    await ember.user.approveToken(tokenAddress, vaultAddress, amount);
    await ember.user.deposit(vaultAddress, amount);
}

Advanced Permit Usage

For more control over the permit parameters:

import { signPermit, getPermitNonce } from "@ember-finance/sdk";

// Get current nonce for the user
const nonce = await getPermitNonce(tokenAddress, userAddress, provider);

// Set custom deadline (e.g., 24 hours from now)
const deadline = BigInt(Math.floor(Date.now() / 1000) + 86400);

// Get chain ID
const network = await provider.getNetwork();
const chainId = network.chainId;

// Sign permit with custom parameters
const permitSig = await signPermit(
    signer,
    tokenAddress,
    "USD Coin",
    vaultAddress,
    amount,
    deadline,
    nonce,
    chainId
);

// Use the permit
await ember.user.depositWithPermit(vaultAddress, amount, permitSig);

Important Notes

• Token Support: The underlying token must support EIP-2612 permit. Most modern tokens (USDC, DAI, etc.) support this standard.
• Token Name: For tokens that implement EIP-5267 eip712Domain(), the domain is read from the token and the name you pass is ignored. For other tokens, the name must match the token's EIP-2612 domain name exactly.
• Version: If the token has no version(), "1" is assumed. Pass version to signPermit to override; the domain is then used exactly as given.
• No permit: signPermitSimple checks the domain against the token's DOMAIN_SEPARATOR() and returns null if they differ. Fall back to approve + deposit. signPermit does not make this check.
• Deadline: Permit signatures have a deadline. After the deadline, the signature becomes invalid.
• Nonce: Each permit signature uses a nonce. Once used, the nonce increments and the signature cannot be reused.

ERC-4626 Compatibility (EVM)

The EVM vaults are fully ERC-4626 compliant:

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.

Releasing

The SDK lives in ember-mono at typescript/library/ember-sdk. @ember-finance/sdk is published by the monorepo's .github/workflows/ember_sdk_publish.yaml using npm OIDC trusted publishing. There is no npm token — npm authorises that one workflow file by exact filename, so all three publish paths live in it and the file must not be renamed.

Bump version in package.json in the PR. npm versions are immutable, so the workflow fails early if that version is already published; to retry a failed publish, dispatch the workflow rather than pushing another tag.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Built with ❤️ by the Ember Protocol team