# EVM Actions

### Overview

EVM write operations require a connected wallet with a signer. The SDK supports all vault versions (`evm-0`, `evm-1`, `evm-2`) and automatically selects the correct contract ABI and function signatures.

### Setup

```typescript
import { ethers } from 'ethers';
import { AugustSDK } from '@augustdigital/sdk';

// Initialize SDK
const sdk = new AugustSDK({
  providers: {
    1: 'https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY',
  },
});

// Connect wallet and set signer
const provider = new ethers.BrowserProvider(window.ethereum);
const signer = await provider.getSigner();
sdk.evm.setSigner(signer);

const userAddress = await signer.getAddress();
```

### Vault Deposit

Deposit tokens into a vault. The SDK automatically handles different vault versions (`evm-0`, `evm-1`, `evm-2`) and adapter deposits.

```typescript
sdk.evm.vaultDeposit({
  target: string;
  wallet: string;
  amount: string | bigint | number;
  wait?: boolean;
  depositAsset?: string;  // Optional: for adapter deposits
  chainId?: number;       // Optional: for adapter routing
  poolName?: string;      // Optional: for adapter routing
}): Promise<string>
```

#### Vault Version Detection

The SDK automatically detects the vault version and uses the correct deposit method:

| Version     | Deposit Function                     | Parameters              | Use Case                   |
| ----------- | ------------------------------------ | ----------------------- | -------------------------- |
| `evm-0`     | `deposit(uint256, address)`          | 2 params                | Legacy vaults              |
| `evm-1`     | `deposit(uint256, address)`          | 2 params                | Standard vaults            |
| `evm-2`     | `deposit(address, uint256, address)` | 3 params                | Multi-asset vaults         |
| **Adapter** | Various                              | Depends on adapter type | Alternative token deposits |

**You don't need to specify the version** - the SDK detects it automatically from the vault's `version` field.

#### Parameters

| Parameter      | Type                         | Required | Description                               |
| -------------- | ---------------------------- | -------- | ----------------------------------------- |
| `target`       | `string`                     | Yes      | Vault contract address                    |
| `wallet`       | `string`                     | Yes      | User wallet address                       |
| `amount`       | `string \| bigint \| number` | Yes      | Amount to deposit                         |
| `wait`         | `boolean`                    | No       | Wait for confirmation (default: false)    |
| `depositAsset` | `string`                     | No       | Token to deposit (defaults to underlying) |
| `chainId`      | `number`                     | No       | Chain ID for adapter routing              |
| `poolName`     | `string`                     | No       | Pool name for adapter routing             |

#### Returns

Transaction hash as `string`

#### Example: Standard Deposit

```typescript
// Deposit underlying token
const txHash = await sdk.evm.vaultDeposit({
  target: '0x80E1048eDE66ec4c364b4F22C8768fc657FF6A42',
  wallet: userAddress,
  amount: '100', // 100 tokens
  wait: true,
});

console.log('Deposit successful:', txHash);
```

#### How It Works for Each Version

**EVM-0 & EVM-1 Vaults (Standard)**

**Contract Function:** `deposit(uint256 assets, address receiver)`

**Behavior:**

* Deposits the vault's underlying token only
* 2 parameters: amount and receiver
* Automatic approval of underlying token to vault

**Example:**

```typescript
// Upshift USDC (evm-1)
await sdk.evm.vaultDeposit({
  target: '0x80E1048eDE66ec4c364b4F22C8768fc657FF6A42',
  wallet: userAddress,
  amount: '100', // 100 USDC
  wait: true,
});
// SDK calls: vault.deposit(100e6, userAddress)
```

**EVM-2 Vaults (Multi-Asset)**

**Contract Function:** `deposit(address assetIn, uint256 amount, address receiver)`

**Behavior:**

* Accepts multiple whitelisted tokens (listed in `vault.depositAssets`)
* 3 parameters: asset address, amount, and receiver
* Automatic approval of selected token to vault

**Example:**

```typescript
// Get vault to see deposit options
const vault = await sdk.getVault({
  vault: '0x18EE038C114a07f4B08b420fb1E4149a4F357249',
  chainId: 1,
});

console.log(
  'Can deposit:',
  vault.depositAssets.map((a) => a.symbol),
);
// Output: ["USDC", "USDT", "DAI"]

// Deposit any whitelisted asset
await sdk.evm.vaultDeposit({
  target: vault.address,
  wallet: userAddress,
  amount: '100',
  depositAsset: '0xdAC17F958D2ee523a2206206994597C13D831ec7', // USDT
  chainId: 1,
  wait: true,
});
// SDK calls: vault.deposit(USDT_ADDRESS, 100e6, userAddress)
```

**Note:** For EVM-2 vaults, you can optionally specify `depositAsset`. If omitted, SDK uses the first asset in `depositAssets` array (usually the primary/underlying token).

**Adapter Vaults (Alternative Tokens)**

**Contract Functions:** Various depending on adapter type

**Behavior:**

* Enables deposits with tokens beyond the vault's standard accepted tokens
* Uses wrapper contracts or swap protocols
* Requires `depositAsset`, `chainId`, and sometimes `poolName` parameters

**Adapter Types:**

1. **Native Token Adapter** (e.g., ETH → wstETH)
   * Wraps native tokens before depositing
   * Uses `WrapperAdapter` contract
   * Example: Treehouse Growth
2. **Token Wrapper Adapter** (e.g., WETH → wstETH)
   * Wraps ERC20 tokens before depositing
   * Uses `WrapperAdapter` contract
   * Example: Treehouse Growth
3. **Swap Adapter** (e.g., USDC → WBTC)
   * Swaps tokens via Paraswap before depositing
   * Uses `PoolAdapter` contract
   * Example: BTC Multi-Token

**Example: Native ETH Deposit**

```typescript
// Treehouse Growth accepts: wstETH, WETH, ETH (via adapter)
await sdk.evm.vaultDeposit({
  target: '0x5Fde59415625401278c4d41C6beFCe3790eb357f',
  wallet: userAddress,
  amount: '1.0', // 1 ETH
  depositAsset: '0x0000000000000000000000000000000000000000', // Native ETH
  chainId: 1,
  poolName: 'Treehouse Growth',
  wait: true,
});
// SDK calls: wrapperAdapter.depositETH() with value
```

**Example: WETH Deposit (via adapter)**

```typescript
await sdk.evm.vaultDeposit({
  target: '0x5Fde59415625401278c4d41C6beFCe3790eb357f',
  wallet: userAddress,
  amount: '1.0',
  depositAsset: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2', // WETH
  chainId: 1,
  poolName: 'Treehouse Growth',
  wait: true,
});
// SDK calls: wrapperAdapter.deposit() after approving WETH
```

**Example: Swap Adapter Deposit**

```typescript
// BTC Multi-Token accepts WBTC but can swap from USDC
await sdk.evm.vaultDeposit({
  target: '0xBTCVaultAddress...',
  wallet: userAddress,
  amount: '10000', // 10,000 USDC
  depositAsset: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // USDC
  chainId: 1,
  poolName: 'BTC Multi-Token',
  wait: true,
});
// SDK:
// 1. Gets Paraswap quote (USDC → WBTC)
// 2. Approves USDC to PoolAdapter
// 3. Calls: poolAdapter.swapAndDeposit()
```

#### Automatic Detection Flow

```typescript
// Step 1: Get vault info
const vault = await sdk.getVault({ vault: vaultAddress, chainId: 1 });

// Step 2: SDK checks vault.version
if (vault.version === 'evm-2') {
  // Use 3-param deposit(address, uint256, address)
} else if (depositAsset && depositAsset !== vault.underlying.address) {
  // Use adapter logic
} else {
  // Use 2-param deposit(uint256, address)
}

// Step 3: SDK handles approvals automatically
// Step 4: SDK calls correct contract method
```

#### When to Use Each Parameter

| Parameter      | Required     | Use When                                      |
| -------------- | ------------ | --------------------------------------------- |
| `target`       | ✅ Always     | Vault address                                 |
| `wallet`       | ✅ Always     | User's address                                |
| `amount`       | ✅ Always     | Deposit amount                                |
| `wait`         | ❌ Optional   | Want to wait for confirmation                 |
| `depositAsset` | ⚠️ Sometimes | Using adapter OR EVM-2 with non-primary token |
| `chainId`      | ⚠️ Sometimes | Using adapter                                 |
| `poolName`     | ⚠️ Sometimes | Using adapter (helps with routing)            |

#### Quick Reference: Vault Versions

How to check which version a vault uses:

```typescript
const vault = await sdk.getVault({ vault: vaultAddress, chainId: 1 });
console.log('Version:', vault.version); // "evm-0", "evm-1", or "evm-2"
console.log('Has adapters:', vault.depositAssets.length > 1);
```

**Common Vaults by Version:**

| Vault Name       | Version | Deposit Tokens                | Notes            |
| ---------------- | ------- | ----------------------------- | ---------------- |
| Upshift USDC     | `evm-1` | USDC only                     | Standard deposit |
| Upshift USDT     | `evm-1` | USDT only                     | Standard deposit |
| Treehouse Growth | `evm-1` | wstETH, WETH, ETH             | Has adapters     |
| Kelp TAC rsETH   | `evm-1` | rsETH, stETH, ETHx, WETH, ETH | Has adapters     |
| Wild USD         | `evm-2` | USDC, USDT, DAI               | Multi-asset      |
| BTC Multi-Token  | `evm-1` | WBTC, USDC (via swap)         | Has swap adapter |

#### Decision Tree

```
Do you have a depositAsset parameter?
│
├─ NO → Standard deposit with underlying token
│        ├─ EVM-0/1: 2-param deposit
│        └─ EVM-2: 3-param deposit with first depositAsset
│
└─ YES → Is depositAsset different from underlying?
         │
         ├─ NO → Standard deposit (same as above)
         │
         └─ YES → Is vault EVM-2 with depositAsset whitelisted?
                  │
                  ├─ YES → Multi-asset deposit (3-param)
                  │
                  └─ NO → Adapter deposit
                           ├─ Native token? → Wrapper adapter
                           ├─ Different ERC20? → Swap adapter
                           └─ Wrapped version? → Wrapper adapter
```

### Adapter Deposits

Deposit with alternative tokens beyond the vault's underlying asset.

#### Check Available Tokens

```typescript
const vault = await sdk.getVault({ vault: vaultAddress, chainId: 1 });

console.log('Supported deposit tokens:');
vault.depositAssets.forEach((asset) => {
  console.log(`- ${asset.symbol}: ${asset.address}`);
});
```

#### Deposit with Alternative Token

```typescript
// Get vault info
const vault = await sdk.getVault({
  vault: '0x5Fde59415625401278c4d41C6beFCe3790eb357f', // Treehouse
  chainId: 1,
});

// Deposit WETH instead of wstETH
const txHash = await sdk.evm.vaultDeposit({
  target: vault.address,
  wallet: userAddress,
  amount: '1.0',
  depositAsset: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2', // WETH
  chainId: 1,
  wait: true,
});
```

#### Deposit Native ETH

```typescript
// Deposit native ETH (zero address)
await sdk.evm.vaultDeposit({
  target: '0x5Fde59415625401278c4d41C6beFCe3790eb357f',
  wallet: userAddress,
  amount: '1.0',
  depositAsset: '0x0000000000000000000000000000000000000000', // Native ETH
  chainId: 1,
  poolName: 'Treehouse Growth',
  wait: true,
});
```

#### Supported Adapter Vaults

| Vault            | Supported Tokens       | Type                    |
| ---------------- | ---------------------- | ----------------------- |
| Treehouse Growth | wstETH, WETH, ETH      | Native deposits         |
| Kelp TAC rsETH   | stETH, ETHx, WETH, ETH | Native deposits         |
| BTC Multi-Token  | WBTC, cbBTC, tBTC      | Swap adapter (Paraswap) |
| AVAX Strategy    | WAVAX, AVAX            | Native deposits         |

### Request Withdrawal

Request to withdraw tokens from a vault. Subject to lag period before claiming.

```typescript
sdk.evm.vaultRequestRedeem({
  target: string;
  wallet: string;
  amount: string | bigint | number;
  wait?: boolean;
}): Promise<string>
```

#### Parameters

| Parameter | Type                         | Required | Description                |
| --------- | ---------------------------- | -------- | -------------------------- |
| `target`  | `string`                     | Yes      | Vault contract address     |
| `wallet`  | `string`                     | Yes      | User wallet address        |
| `amount`  | `string \| bigint \| number` | Yes      | Amount of shares to redeem |
| `wait`    | `boolean`                    | No       | Wait for confirmation      |

#### Returns

Transaction hash as `string`

#### Example

```typescript
// Request to redeem 50 vault shares
const txHash = await sdk.evm.vaultRequestRedeem({
  target: '0x80E1048eDE66ec4c364b4F22C8768fc657FF6A42',
  wallet: userAddress,
  amount: '50',
  wait: true,
});

console.log('Redemption requested:', txHash);
console.log('Wait for lag period before claiming');

// Check when you can claim
const { availableRedemptions } = await sdk.getVaultAvailableRedemptions({
  vault: '0x80E1048eDE66ec4c364b4F22C8768fc657FF6A42',
  wallet: userAddress,
  chainId: 1,
});
```

#### Behavior

The SDK automatically:

1. Detects vault version
2. Uses correct function signature:
   * EVM-0/1: `requestRedeem(uint256, address, address)` (3 params)
   * EVM-2: `requestRedeem(uint256, address)` (2 params)
3. Converts amount to proper decimals
4. Submits transaction

### Claim Redemption

Claim tokens from a completed redemption request.

```typescript
sdk.evm.vaultRedeem({
  target: string;
  wallet: string;
  wait?: boolean;
  year: string;
  month: string;
  day: string;
  receiverIndex: string;
}): Promise<string>
```

#### Parameters

| Parameter       | Type      | Required | Description                   |
| --------------- | --------- | -------- | ----------------------------- |
| `target`        | `string`  | Yes      | Vault contract address        |
| `wallet`        | `string`  | Yes      | User wallet address           |
| `year`          | `string`  | Yes      | Year from redemption request  |
| `month`         | `string`  | Yes      | Month from redemption request |
| `day`           | `string`  | Yes      | Day from redemption request   |
| `receiverIndex` | `string`  | Yes      | Receiver index                |
| `wait`          | `boolean` | No       | Wait for confirmation         |

#### Returns

Transaction hash as `string`

#### Example

```typescript
// Get available redemptions
const { availableRedemptions } = await sdk.getVaultAvailableRedemptions({
  vault: vaultAddress,
  wallet: userAddress,
  chainId: 1,
});

// Claim first available redemption
if (availableRedemptions.length > 0) {
  const redemption = availableRedemptions[0];

  const txHash = await sdk.evm.vaultRedeem({
    target: vaultAddress,
    wallet: userAddress,
    year: redemption.year.raw,
    month: redemption.month.raw,
    day: redemption.day.raw,
    receiverIndex: '0',
    wait: true,
  });

  console.log('Claimed:', redemption.amount.normalized, 'tokens');
}
```

### Token Approval

Approve vault to spend tokens. Usually called automatically by `vaultDeposit`.

```typescript
sdk.evm.vaultApprove({
  target: string;
  wallet: string;
  amount: string | bigint | number;
  wait?: boolean;
}): Promise<string | undefined>
```

#### Returns

* Transaction hash if approval was needed
* `undefined` if allowance already sufficient

#### Example

```typescript
// Manually approve before deposit
const txHash = await sdk.evm.vaultApprove({
  target: vaultAddress,
  wallet: userAddress,
  amount: '1000',
  wait: true,
});

if (txHash) {
  console.log('Approval tx:', txHash);
} else {
  console.log('Already approved');
}
```

### Check Allowance

Check current token allowance for a vault.

```typescript
sdk.evm.vaultAllowance({
  target: string;
  wallet: string;
}): Promise<INormalizedNumber>
```

#### Example

```typescript
const allowance = await sdk.evm.vaultAllowance({
  target: vaultAddress,
  wallet: userAddress,
});

console.log('Current allowance:', allowance.normalized);

if (BigInt(allowance.raw) < BigInt(depositAmount)) {
  console.log('Need to approve more');
}
```

### Examples

#### Complete Deposit Flow

```typescript
// 1. Get vault and check options
const vault = await sdk.getVault({ vault: vaultAddress, chainId: 1 });

console.log('Deposit options:');
vault.depositAssets.forEach((asset) => {
  console.log(`- ${asset.symbol}`);
});

// 2. Check if vault accepts deposits
if (vault.isDepositPaused) {
  throw new Error('Vault deposits are paused');
}

// 3. Check user balance
const tokenContract = new ethers.Contract(
  vault.depositAssets[0].address,
  ['function balanceOf(address) view returns (uint256)'],
  provider,
);
const balance = await tokenContract.balanceOf(userAddress);

// 4. Deposit
const txHash = await sdk.evm.vaultDeposit({
  target: vault.address,
  wallet: userAddress,
  amount: '100',
  wait: true,
});

console.log('Success:', txHash);
```

#### Complete Withdrawal Flow

```typescript
// 1. Check user position
const position = await sdk.getVaultPositions({
  vault: vaultAddress,
  wallet: userAddress,
  chainId: 1,
});

if (position[0].walletBalance.raw === '0') {
  throw new Error('No balance to withdraw');
}

// 2. Request redemption
const requestTx = await sdk.evm.vaultRequestRedeem({
  target: vaultAddress,
  wallet: userAddress,
  amount: '50',
  wait: true,
});

console.log('Redemption requested:', requestTx);

// 3. Wait for lag period...
await new Promise((resolve) => setTimeout(resolve, vault.lagDuration * 1000));

// 4. Check if ready to claim
const { availableRedemptions } = await sdk.getVaultAvailableRedemptions({
  vault: vaultAddress,
  wallet: userAddress,
  chainId: 1,
});

// 5. Claim
if (availableRedemptions.length > 0) {
  const redemption = availableRedemptions[0];
  const claimTx = await sdk.evm.vaultRedeem({
    target: vaultAddress,
    wallet: userAddress,
    year: redemption.year.raw,
    month: redemption.month.raw,
    day: redemption.day.raw,
    receiverIndex: '0',
    wait: true,
  });

  console.log('Claimed:', claimTx);
}
```

#### Multi-Asset Vault Deposit

```typescript
// Get EVM-2 vault
const vault = await sdk.getVault({
  vault: '0x18EE038C114a07f4B08b420fb1E4149a4F357249',
  chainId: 1,
});

console.log('Vault version:', vault.version); // "evm-2"
console.log('Deposit assets:', vault.depositAssets.length);

// Deposit any whitelisted asset
const selectedAsset = vault.depositAssets[0];

const txHash = await sdk.evm.vaultDeposit({
  target: vault.address,
  wallet: userAddress,
  amount: '100',
  depositAsset: selectedAsset.address, // Required for evm-2
  chainId: 1,
  wait: true,
});
```

### Error Handling

```typescript
try {
  await sdk.evm.vaultDeposit({
    target: vaultAddress,
    wallet: userAddress,
    amount: '100',
    wait: true,
  });
} catch (error) {
  if (error.message.includes('insufficient balance')) {
    console.error('Not enough tokens');
  } else if (error.message.includes('Deposit failed')) {
    console.error('Transaction reverted');
  } else if (error.message.includes('user rejected')) {
    console.error('User cancelled transaction');
  } else {
    console.error('Error:', error.message);
  }
}
```

### Best Practices

#### 1. Always Check Vault Status

```typescript
const vault = await sdk.getVault({ vault, chainId });

if (vault.isDepositPaused) {
  throw new Error('Deposits are currently paused');
}

if (vault.isWithdrawalPaused) {
  throw new Error('Withdrawals are currently paused');
}
```

#### 2. Verify Deposit Cap

```typescript
const vault = await sdk.getVault({ vault, chainId });

const remaining = BigInt(vault.maxSupply.raw) - BigInt(vault.totalSupply.raw);
console.log(
  'Remaining capacity:',
  ethers.formatUnits(remaining, vault.decimals),
);
```

#### 3. Show User Expected Output

```typescript
// For standard deposits, use previewDeposit
const vaultContract = new ethers.Contract(
  vaultAddress,
  ['function previewDeposit(uint256) view returns (uint256)'],
  provider,
);

const expectedShares = await vaultContract.previewDeposit(
  ethers.parseUnits('100', vault.decimals),
);

console.log(
  'You will receive:',
  ethers.formatUnits(expectedShares, vault.decimals),
  'shares',
);
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.augustdigital.io/developers/typescript-sdk/code-examples/evm-actions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.