# Individual Contract Integration Guide

This guide explains how to interact with the `yoVaults` smart contracts (`yoETH, yoUSD, yoBTC, yoEUR, yoGOLD`). These contracts implement the [ERC-4626](https://eips.ethereum.org/EIPS/eip-4626) Tokenized Vault Standard, enabling users and integrators to deposit ERC-20 tokens ("assets") and receive yield-bearing yoTokens in return. 

The guide outlines how to:

* Connect to the vaults with Ethers.js
* Use read functions (`previewDeposit`, `previewMint`, `previewRedeem`) to estimate outcomes
* Execute deposit and redemption transactions
* Understand how yoTokens ↔ assets conversion works

> All vaults follow the same contract interface and live on **Base chain (chain ID 8453) and on Ethereum mainnet (chain ID 1)**.

NOTE: yoGOLD is only available on Ethereum. 

***

## ⚙️ Setup

### Install Ethers

```bash
npm install ethers
```

### Connect to an RPC & Instantiate the Contract

```ts
import { ethers } from "ethers";
import abi from "./yoAbi.json"; // Use the ABI attached below 

const provider = new ethers.JsonRpcProvider("https://mainnet.base.org"); // or use any RPC for Ethereum chain
const signer = new ethers.Wallet(PRIVATE_KEY, provider);

const YO_VAULTS = {
  yoETH: "0x3a43aec53490cb9fa922847385d82fe25d0e9de7",
  yoUSD: "0x0000000f2eb9f69274678c76222b35eec7588a65",
  yoBTC: "0xbcbc8cb4d1e8ed048a6276a5e94a3e952660bcbc",
  ...,
};

const vault = new ethers.Contract(YO_VAULTS.yoETH, abi, signer); // Swap as needed
```

{% file src="<https://2576447856-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fwkm0XGONc7sDuNeJww6d%2Fuploads%2Fiui2UXkph3345QMUag7F%2FyoAbi.json?alt=media&token=19dffa44-4254-44dd-a00b-18c9265a5bab>" %}

***

## 🔍 Simulate with `preview*` and `convertTo` Functions

These functions estimate how many shares or assets you'll receive/spend before making a transaction or to price your position.

### Pricing your positions:

#### `maxWithdraw(owner)`

Returns the **maximum amount of assets** that can currently be withdrawn by the given address.

```ts
const maxAssets = await vault.maxWithdraw(await signer.getAddress());
```

#### `convertToAssets(shares)`

Estimate how many yoTokens you get for a given asset amount (excludes fees):

```ts
const yoTokens = await vault.convertToShares(ethers.parseUnits("1.0", 18));
```

### Quoting before building a transaction

#### `previewDeposit(assets)`

Estimate how many yoTokens you get for a given asset amount net of deposit fees:

```ts
const yoTokens = await vault.previewDeposit(ethers.parseUnits("1.0", 18));
```

#### `previewRedeem(shares)`

Estimate how many assets you'd get back when redeeming yoTokens net of withdrawal fees:

```ts
const assetsOut = await vault.previewRedeem(ethers.parseUnits("1.0", 18));
```

***

## ✍️ Execute Transactions

### `deposit(assets, receiver)`

Deposit a specific amount of assets and receive yoTokens in return:

```ts
const tx = await vault.deposit(
  ethers.parseUnits("1.0", 18),       // Assets to deposit
  await signer.getAddress()           // Receiver of yoTokens
);
await tx.wait();
```

***

### `redeem(yoTokens, receiver, owner)`

Burn yoTokens and receive assets in return. You **cannot request an exact asset amount**. See our Notes below.

```ts
const tx = await vault.redeem(
  ethers.parseUnits("1.0", 18),       // yoTokens to redeem
  await signer.getAddress(),          // Receiver of assets
  await signer.getAddress()           // Owner of shares
);
await tx.wait();
```

***

## &#x20;Recap: Share-to-Asset Logic

<table><thead><tr><th width="267.7734375">You Want To...</th><th width="125">Use This Function</th><th>Simulation Tool</th></tr></thead><tbody><tr><td>Deposit assets for yoTokens</td><td><code>deposit()</code></td><td><code>previewDeposit()</code></td></tr><tr><td>Mint exact amount of yoTokens</td><td><code>mint()</code> </td><td><code>previewMint()</code></td></tr><tr><td>Redeem yoTokens for assets</td><td><code>redeem()</code></td><td><code>previewRedeem()</code></td></tr></tbody></table>

***

## Notes

* All values must be parsed using correct decimals (e.g. `ethers.parseUnits("1.0", 18)`).
  * WETH / yoETH decimals: <mark style="color:red;">18</mark>&#x20;
  * cbBTC / yoBTC decimals: <mark style="color:red;">8</mark>
  * USDC / yoUSD decimals: <mark style="color:red;">6</mark>
  * USDT / yoUSDT decimals: <mark style="color:red;">6</mark>
  * EURC / yoEUR: <mark style="color:red;">6</mark>
  * XAUT / yoGOLD: <mark style="color:red;">6</mark>
* Only `redeem` is supported for withdrawals because depending on the withdrawal amount, the yoVault may not have enough available liquidity to fill the redeem order. In those cases, the withdrawal will remain pending for up to 24 hours. The protocol will fill the redeem order and send the assets automatically to the `receiver` specified in the `requestRedeem` transaction.&#x20;
* All the yoVaults follow the same ABI and differ only by address.