> For the complete documentation index, see [llms.txt](https://docs.sierra.money/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sierra.money/building-with-sierra/smart-contract-integration.md).

# Smart Contract Integration

### Overview

Learn how to integrate with the Sierra's vaults directly through their respective smart contract.

Sierra's vaults, like SIERRA and SPLUS, are deployed on Ethereum mainnet. Lenders deposit USDC and receive vault tokens, then redeem them for USDC by requesting a withdrawal and claiming it once processed. The vault is permissionless, any wallet can interact with the smart contract to make deposits and withdrawals.

On-chain integrations are read and write. For vault-level reporting data such as APY, TVL and reserve allocations, see the [API Integration](https://docs.sierra.money/splus/splus-api-integration) page.

### Terminology

Sierra Vault tokens implement many of the ERC-4626 and ERC-20 standards. In some cases, the terminology used in the product differs from the code. The main differences are:

<table data-search="false"><thead><tr><th>Term in Code</th><th>Display Name</th></tr></thead><tbody><tr><td>Pool</td><td>Vault</td></tr><tr><td>Shares</td><td>Vault Tokens (i.e. SPLUS or SIERRA)</td></tr><tr><td>Assets</td><td>USDC</td></tr><tr><td>Redeem / Redemption</td><td>Withdrawal</td></tr><tr><td><mark style="color:$success;"><code>uuid</code></mark></td><td>Withdrawal Request ID</td></tr></tbody></table>

### Decimals / Formatting

The contract returns numerical values that should be converted using the following conventions to calculate the display value. All amounts you pass to the contract use the same base units.<br>

<table><thead><tr><th>Type</th><th width="149.49609375">Decimals</th><th>Example in Code</th><th>Example in Display</th></tr></thead><tbody><tr><td>assets</td><td>6</td><td>1000000</td><td>1 USDC</td></tr><tr><td>shares</td><td>6</td><td>1000000</td><td>1 Vault Token</td></tr><tr><td>Exchange Rate</td><td>18</td><td>1000261149376738066</td><td>1.000261</td></tr></tbody></table>

### Getting Started

Sierra Vaults are built on permissionless smart contracts that anyone can read from or build against. Start by viewing the verified contract on Etherscan, which lists every function and the source code.

<table><thead><tr><th width="238.34375">Item</th><th>Value</th></tr></thead><tbody><tr><td>Network</td><td>Ethereum Mainnet</td></tr><tr><td>Vault Address</td><td><p>SIERRA: <mark style="color:$success;"><code>0xBcEb5f6877d979EC621AE694dA1102CB95691aD3</code></mark></p><p>SPLUS: <mark style="color:$success;"><code>0x7706b1a531A7A8cB4c26D24CDc9ae4094a3e0302</code></mark></p></td></tr><tr><td>Vault Token</td><td>SIERRA or SPLUS (ERC-20)</td></tr><tr><td>Liquidity Asset</td><td>USDC. Call <mark style="color:$success;"><code>asset()</code></mark> for its contract address</td></tr><tr><td>Block Explorer</td><td><p><a href="https://etherscan.io/address/0x7706b1a531A7A8cB4c26D24CDc9ae4094a3e0302">SIERRA vault on Etherscan</a></p><p><a href="https://etherscan.io/address/0x7706b1a531A7A8cB4c26D24CDc9ae4094a3e0302">SPLUS vault on Etherscan</a></p></td></tr></tbody></table>

**Note:** Sierra Vault Tokens implements the OpenZeppelin ERC-1967 Upgradeable Beacon Proxy pattern. Always send calls to the vault address above, and use **Read as Proxy** and **Write as Proxy** on Etherscan for the current function list.

**Using Etherscan:**&#x20;

1. Open the vault on Etherscan and select **Contract**.
2. **Read as Proxy:** expand a function, enter inputs and select **Query**. No wallet is needed. Values reflect the latest block.
3. **Write as Proxy:** select **Connect to Web3**, connect your wallet, enter inputs in base units, select **Write** and confirm. You pay gas in ETH.
4. **Transactions** shows each call by method (Deposit, Request Redeem, Claim). **Events** shows decoded events, including the uuid of each withdrawal request.

**Important Functions:**&#x20;

As a Lender, there are only a handful of functions you will ever need to call: <mark style="color:$success;">`deposit`</mark> to make an investment, <mark style="color:$success;">`requestRedeem`</mark> to request a withdrawal, <mark style="color:$success;">`claim`</mark> to collect it, and the read functions under Query Data to check balances. The contract also has administrative functions, such as setting the exchange rate and processing withdrawals. These are restricted to the Sierra Protocol team, and a call to them from a Lender wallet reverts.

### Make Investments

**Note:** SPLUS is permissionless, so no whitelisting is required. You need USDC in your wallet and enough ETH to pay for gas. [Restricted Addresses](https://docs.sierra.money/additional-resources/jurisdictional-restrictions) cannot interact with the vault.

To make an investment, you must first call the following function on the USDC contract to create a spending allowance for the vault.

```
function approve(address spender, uint256 amount) external returns (bool);
```

...where <mark style="color:$success;">`spender`</mark> is the Vault address and <mark style="color:$success;">`amount`</mark> is the number of assets you'd like to deposit (6 decimals).

Once the allowance is approved, call the following function on the vault...

```
function deposit(uint256 assets, address lender) external returns (uint256 shares);
```

...where <mark style="color:$success;">`assets`</mark> is the number of assets you'd like to deposit (6 decimals) and <mark style="color:$success;">`lender`</mark> is your wallet address, which must be the wallet sending the transaction. It will return the number of vault tokens minted (6 decimals), at the current exchange rate. To estimate this first, call <mark style="color:$success;">`convertToShares(assets)`</mark>. The vault emits an event <mark style="color:$success;">`PoolDeposit`</mark>.

### Request Withdrawals

Withdrawals are a two-step process: you request a withdrawal, then claim the USDC once Sierra has processed it. To make a withdrawal request, you must call the following function.

```
function requestRedeem(uint256 shares) external returns (uint256);
```

...where <mark style="color:$success;">`shares`</mark> is the number of vault tokens you wish to redeem (6 decimals). It will return the net  withdrawal request amount in assets (6 decimals), after the redemption fees. The gross amount is emitted as <mark style="color:$success;">`assets`</mark> in <mark style="color:$success;">`RedeemRequested`</mark>, and the fee as <mark style="color:$success;">`fee`</mark> in <mark style="color:$success;">`RedeemRequestClaimMode`</mark> (also readable via <mark style="color:$success;">`withdrawExtra(uuid).fee`</mark>).&#x20;

**Note:** each request has an ID, <mark style="color:$success;">`uuid`</mark>, emitted in the <mark style="color:$success;">`RedeemRequested(lender, assets, shares, uuid)`</mark> event. Save it: you need it to claim.

The USDC amount is set at the exchange rate when you make the request, and any withdrawal fee (see <mark style="color:$success;">`withdrawExtra(uuid).fee`</mark>) is deducted when you claim. Requested vault tokens stay in your balance but are reserved and cannot be transferred.

### Claim Withdrawals

To check whether a request is ready to claim, call...

```
function isClaimable(bytes32 uuid) external view returns (bool);
```

Once it returns <mark style="color:$success;">`true`</mark>, call the following function from the wallet that made the request...

```
function claim(bytes32 uuid) external;
```

...where <mark style="color:$success;">`uuid`</mark> is the withdrawal request ID. The vault sends the USDC, less any withdrawal fee, to your wallet, burns the redeemed vault tokens and emits <mark style="color:$success;">`RedeemClaimed`</mark>.

### Withdrawal Lifecycle

A withdrawal moves from requested to claimable to claimed. You act at the first and last steps.

<img src="https://1817609868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNPqgzecn0shbjxLPNGaH%2Fuploads%2FfwKq5gTuX9uqQmAYDagx%2Funknown.png?alt=media&amp;token=4c028f2f-24a9-48c0-8faa-0f9696d0f129" alt="" height="143" width="602">

Watch for <mark style="color:$success;">`ClaimsOpened`</mark>, or poll <mark style="color:$success;">`isClaimable(uuid)`</mark>, to know when to claim.

### Query Data

All position and vault data can be read from the contract. Anyone can call these functions; no wallet or API token is needed. Values reflect the latest block; for a past block, query an archive node at that block number.

**Get Balances**

<table><thead><tr><th width="389.4296875">Functions</th><th width="223.98828125">Returns</th><th>Units</th></tr></thead><tbody><tr><td><mark style="color:$success;"><code>balanceOf(address account)</code></mark></td><td>Vault tokens held, including any reserved for open requests</td><td>6 Decimals</td></tr><tr><td><mark style="color:$success;"><code>assetBalanceOf(address lender)</code></mark></td><td>Those vault tokens valued in assets at the current exchange rate</td><td>6 Decimals</td></tr><tr><td><mark style="color:$success;"><code>exchangeRate()</code></mark></td><td>Assets per vault token at the current block</td><td>18 Decimals</td></tr><tr><td><mark style="color:$success;"><code>convertToAssets(uint256 shares)</code></mark> / <mark style="color:$success;"><code>convertToShares(uint256 assets)</code></mark></td><td>Convert between vault tokens and assets at the current exchange rate</td><td>6 Decimals</td></tr></tbody></table>

**Get Account Overview**

To get a full summary for a wallet, you can call the following function...

```
function getLYTPoolAccountState(address lender) external view returns (ILYTPoolAccountState memory);

```

and it will return the following data:

```
struct ILYTPoolAccountState {
  address poolAddr; // the contract address of the vault
  address accountAddr; // the wallet address for the account
  address liquidityAssetAddr; // the contract address for the liquidity asset (USDC)
  uint256 tokenBalance; // vault tokens held, including any reserved for open requests (6 decimals)
  uint256 assetBalance; // vault tokens x current exchange rate (6 decimals)
  uint256 maxWithdrawRequest; // the largest withdrawal request the wallet can make now, in assets (6 decimals)
  uint256 maxRedeemRequest; // the largest withdrawal request the wallet can make now, in shares (6 decimals)
  uint256 requestedSharesOf; // open withdrawal requests, in shares (6 decimals)
  uint256 requestedAssetsOf; // open withdrawal requests, in assets (6 decimals)
  uint256 assetsDeposited; // total deposits to date (6 decimals)
  uint256 assetsWithdrawn; // total withdrawals to date (6 decimals)
}
```

To track a wallet's open withdrawal requests, filter <mark style="color:$success;">`RedeemRequested`</mark> events by <mark style="color:$success;">`lender`</mark>, then call <mark style="color:$success;">`isClaimable(uuid)`</mark> for each.

**Get Vault Overview State**

To get the current state of the vault, you can call the following function...

```
function getLYTPoolOverviewState() external view returns (ILYTPoolOverviewState memory);
```

and it will return the following data:&#x20;

```
struct ILYTPoolOverviewState {
  address poolAddr; // the contract address of the vault
  uint256 state; // the current state of the vault, e.g. active or paused 
  uint256 totalAssetsDeposited; // total assets deposited to date (6 decimals)
  uint256 totalAssetsWithdrawn; // total assets withdrawn to date (6 decimals)
  uint256 totalAssets; // vault tokens outstanding valued in assets (6 decimals)
  uint256 totalShares; // the total amount of vault tokens outstanding (6 decimals)
  uint256 exchangeRate; // the current exchange rate (18 decimals)
  uint256 exchangeRateAtSetDay; // the exchange rate on the day it was last set (18 decimals)
  uint256 exchangeRateSetDay; // the day the exchange rate was last set (Unix time / 86400)
  uint256 exchangeRateChangeRate; // the rate the exchange rate changes per compounding period (18 decimals)
  uint256 exchangeRateCompoundingRate; // the rate applied each compounding interval (18 decimals)
  uint256 exchangeRateAtMaturity; // the exchange rate at maturity (18 decimals)
  uint256 exchangeRateMaturityDay; // the maturity day (Unix time / 86400)
  uint256 interestRate; // the reported interest rate in basis points, e.g. 500 = 5.00%
  uint256 indicativeInterestRate; // the reported indicative rate in basis points 
  uint256 collateralRate; // the reported collateral rate in basis points
  ILYTPoolWithdraw[] activeWithdraws; // open withdrawal requests
}
```

### Common Errors

<table data-search="false"><thead><tr><th>Error</th><th>Likely Cause</th></tr></thead><tbody><tr><td>USDC transfer revert</td><td>USDC allowance or balance is lower than the deposit</td></tr><tr><td><mark style="color:$success;"><code>PoolInvalidState</code></mark></td><td><mark style="color:$success;"><code>lender</code></mark> is not the sending wallet, or the vault is not accepting deposits or requests</td></tr><tr><td><mark style="color:$success;"><code>PoolPaused</code></mark></td><td>The vault is paused</td></tr><tr><td><mark style="color:$success;"><code>ZeroAmount/InvalidAccess</code></mark></td><td>The amount is zero or too small to convert</td></tr><tr><td><mark style="color:$success;"><code>DailyMintLimitExceeded</code></mark></td><td>The vault's daily deposit limit has been reached; try again the next day</td></tr><tr><td><mark style="color:$success;"><code>RedeemExceedsBalance</code></mark></td><td>The request is larger than your unreserved vault tokens</td></tr><tr><td><mark style="color:$success;"><code>RedeemBelowMinimum</code></mark></td><td>The request is below the minimum withdrawal amount</td></tr><tr><td><mark style="color:$success;"><code>TooManyOpenRequests / InvalidRedemptions</code></mark></td><td>The vault, or your wallet, has reached its limit of open requests, respectively.</td></tr><tr><td><mark style="color:$success;"><code>NotClaimable</code></mark></td><td>The request has not been processed yet</td></tr><tr><td><mark style="color:$success;"><code>NotClaimant</code></mark></td><td>The claim was not sent from the wallet that made the request</td></tr><tr><td><mark style="color:$success;"><code>RedemptionNotFound</code></mark></td><td>The <mark style="color:$success;"><code>uuid</code></mark> is wrong, or the request was already claimed or cancelled</td></tr><tr><td><mark style="color:$success;"><code>BlacklistedAddress</code></mark></td><td>The wallet is restricted from using the vault</td></tr></tbody></table>

### Events

| Event                                                  | Emitted When                                          | Key Field                                                                                  |
| ------------------------------------------------------ | ----------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| <mark style="color:$success;">`PoolDeposit`</mark>     | A deposit is made                                     | <mark style="color:$success;">`lender, assets, shares`</mark>                              |
| <mark style="color:$success;">`RedeemRequested`</mark> | A withdrawal request is created                       | <mark style="color:$success;">`lender, assets, shares, uuid`</mark>                        |
| <mark style="color:$success;">`ClaimsOpened`</mark>    | Requests made before a cut-off block become claimable | <mark style="color:$success;">`uuid, cutoffBlock, assetsOpened`</mark>                     |
| <mark style="color:$success;">`RedeemClaimed`</mark>   | A request is claimed                                  | <mark style="color:$success;">`lender, shares, assets, fee, uuid, fundsDestination`</mark> |
| <mark style="color:$success;">`RedeemCancelled`</mark> | A request is cancelled                                | <mark style="color:$success;">`lender, shares, assets, uuid`</mark>                        |
| <mark style="color:$success;">`ExchangeRateSet`</mark> | The exchange rate is updated                          | <mark style="color:$success;">`_exchangeRate, interestRate`</mark>                         |
| <mark style="color:$success;">`Transfer`</mark>        | Vault tokens are minted, burned or transferred        | <mark style="color:$success;">`from, to, value`</mark>                                     |
