bitpro가 원문에서 글자만 모은 내용이에요. 표·그림·수식은 빠지거나 깨질 수 있어요. 전체 13쪽 중 1쪽
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
This site has an agentic ask interface you may use to query the documentation dynamically by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.zircuit.com/index.md?ask=<question>&goal=<user_goal>
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
---
# Overview
<figure><img src="https://3252263143-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fp2pPzGBdConDaqw5tnHs%2Fuploads%2FTFX9irzvupogRuGw8T6u%2Fimage.png?alt=media&token=9407a50d-ff9b-4e24-a5e7-c9f8627a05c8" alt=""><figcaption></figcaption></figure>
Zircuit Finance is a secure platform bringing institutional-grade strategies onchain.
The platform was created to address persistent credit and security risks by combining traditional risk frameworks, enforceable protections, and transparent reporting with onchain execution. Zircuit Finance integrates trusted institutions and top DeFi protocols to diversify exposure across regulated and decentralized venues.
Our vaults hold products from institutions that include: Fidelity, WisdomTree, Monarq Asset Management, Forteus, FalconX, B2C2 and more.
**Key Platform Specs**
* 8-11% APR on USDT and USDC
* 0% Management Fee
* 20% Performance Fee
* No Deposit Minimums
* 14-21 Day Withdrawal
* Base & Ethereum Network Support
**These are the yield sources for Zircuit Finance:**
<table><thead><tr><th>Yield Source</th><th width="96.3436279296875">APR</th><th>Strategy</th><th width="137.1475830078125">Withdrawal Liquidity</th><th>Website</th></tr></thead><tbody><tr><td>Monarq</td><td>11-15%</td><td>Quantitative Delta Neutral Fund</td><td>T+14</td><td><a href="https://www.monarq-am.com/">Link</a></td></tr><tr><td>Fidelity</td><td>3-4%</td><td>Money Market Fund</td><td>T+1</td><td><a href="https://institutional.fidelity.com/app/funds-and-products/9053/fidelity-treasury-digital-fund-onchain-class-fyoxx.html">Link</a></td></tr><tr><td>Aave</td><td>2-4%</td><td>DeFi Lending</td><td>Instant</td><td><a href="https://aave.com/">Link</a></td></tr><tr><td>Morpho</td><td>2-4%</td><td>DeFi Lending</td><td>Instant</td><td><a href="https://morpho.org/">Link</a></td></tr><tr><td>WisdomTree</td><td>3-4%</td><td>Money Market Fund</td><td>T+1</td><td><a href="https://www.wisdomtreeconnect.com/digital-funds/money-market/wtgxx">Link</a></td></tr></tbody></table>
Zircuit plans to onboard additional strategies for diversification, including:
<table><thead><tr><th width="147.3983154296875">Yield Source</th><th width="130.4322509765625">APR</th><th width="190.9141845703125">Strategy</th><th>Website</th></tr></thead><tbody><tr><td>FalconX</td><td>8-15%</td><td>Lending</td><td><a href="https://www.falconx.io/">Link</a></td></tr><tr><td>RockawayX</td><td>8-10%</td><td>Market Neutral Fund</td><td><a href="https://rockawayx.com/">Link</a></td></tr><tr><td>Forteus</td><td>5-15%</td><td>Multi-manager Delta Neutral Fund</td><td><a href="https://forteus.com/">Link</a></td></tr><tr><td>B2C2</td><td>5-12%</td><td>Options</td><td><a href="https://www.b2c2.com/">Link</a></td></tr></tbody></table>
And also Zircuit plans to adding support for Bitcoin (BTC) and Ethereum (ETH) vaults.
# Zircuit Finance Vaults
Zircuit Finance Vaults lets you deposit funds into a single, universal vault. This vault automatically finds and invests in the best yield-generating strategies across multiple blockchains, handling all the complex cross-chain logic for you. It's designed to be highly modular, making it easy to add new strategies and bridging technologies.
#### Key Features
* **Single-Chain UX, Multi-Chain Execution**: For example, deposit on one chain, earn on another, withdraw to Ethereum
* **Unified Accounting**: One source of truth for vault valuation and share pricing
* **Modular Strategy System**: Easy to add new yield strategies without modifying core vault logic
* **Multi-Bridge Support**: Pluggable bridge adapters (LayerZero, native L2 bridges, etc.)
* **Security-First Design**: Role-based access control, replay protection, queue-based withdrawals
### Architecture Overview
<table><thead><tr><th width="172.07421875">Term</th><th>Definition</th></tr></thead><tbody><tr><td>Accounting Chain</td><td>The single chain that hosts the canonical Vault and maintains price-per-share. Acts as source of truth. </td></tr><tr><td>Strategy Chain</td><td>Any chain where yield strategies are deployed. Has <code>StrategyManager</code> and actual strategy contracts.</td></tr><tr><td>Entrypoint Chain</td><td>Any chain where users can deposit/withdraw. Has <code>VaultToken</code> (shares) and UnderlyingOFTAdapter (asset wrapper).</td></tr><tr><td>VaultToken (e.g. zvUSDC)</td><td>The omnichain-enabled share token representing ownership in the vault (exists on entrypoint chains)</td></tr></tbody></table>
### User Flows
#### Flow 1: Deposit from Entrypoint Chain
{% @mermaid/diagram content="sequenceDiagram
participant User
participant Frontend
participant EC as Entrypoint Chain
participant Zircuit as Accounting Chain<br/>(Zircuit)
```
User->>Frontend: Initiate deposit (1000 USDC)
Frontend->>Frontend: Calculate LayerZero fee
Frontend->>EC: Approve USDC to UnderlyingOFTAdapter
User->>EC: Confirm transaction
Frontend->>EC: UnderlyingOFTAdapter.send(...)
User->>EC: Confirm transaction (with LZ fee)
EC->>Zircuit: LayerZero message
Zircuit->>Zircuit: Mint zvUSDC shares
Zircuit->>EC: Send shares to user
Frontend->>Frontend: Poll for shares balance
Frontend->>User: Show success (950 zvUSDC)" %}
```
#### Flow 2: Withdrawal to Destination Chain
{% @mermaid/diagram content="sequenceDiagram
participant User
participant Frontend
participant EC as Entrypoint Chain
participant Zircuit as Accounting Chain<br/>(Zircuit)
```
User->>Frontend: Initiate withdrawal (500 zvUSDC)
Frontend->>Frontend: Calculate LayerZero fee
Frontend->>EC: VaultToken.send(...)
User->>EC: Confirm transaction
EC->>Zircuit: Send shares to Zircuit
Note over Zircuit: Withdrawal queued<br/>Requires keeper processing
Frontend->>Frontend: Poll withdrawal status
Note over Frontend: May take minutes to hours
Zircuit->>EC: Keeper processes, sends USDC
EC->>User: Receive 526 USDC
Frontend->>User: Show success" %}
```
{% hint style="info" %}
The use of Zircuit as the accounting chain on this page is just as example; the actual accounting chain will differ.
{% endhint %}
# Vault Integration Guide
The OVault SDK simplifies depositing and redeeming tokens on OVaults, which are cross-chain ERC-4626 vaults built on top of LayerZero.
1. [Overview](#overview)
2. [Installation](#installation)
3. [Core Concepts](#core-concepts)
4. [Quick Start](#quick-start)
5. [SDK guide repository](#sdk-guide-repository)
6. [Operations](#operations)
7. [Input Parameter Reference](#input-parameter-reference)
8. [Slippage and Fee Buffer](#slippage-and-fee-buffer)
9. [Tracking Transactions](#tracking-transactions)
10. [Error Reference](#error-reference)
### Overview
* Quoting vault outputs (`previewDeposit` / `previewRedeem`)
* Building LayerZero send parameters including compose messages
* Calculating cross-chain messaging fees
* Determining required token approvals (including EIP-2612 permit support)
* Resolving all contract addresses, EIDs, and decimals from a built-in registry
* Tracking deposits & redeems
### Installation
```bash
npm install @zircuit/ovault-evm
# or
pnpm add @zircuit/ovault-evm
```
### Core Concepts
#### Hub and Spoke Architecture
OVaults use a hub-and-spoke model:
* **Hub chain** — the chain where the ERC-4626 vault contract lives. All deposits and redeems ultimately execute here. The hub chain is always **Base**.
* **Spoke chains** — other supported chains where users hold the underlying asset or vault shares (as OFTs). example: **Ethereum**.
* **Source chain** — the chain the user is initiating the transaction from.
* **Destination chain** — the chain where the user wants to receive tokens after the operation completes.
#### Chain Topology Shorthand
The SDK internally handles four routing scenarios, named by the relationship between source, hub, and destination:
| Scenario | Source = Hub | Destination = Hub | Description |
| -------- | ------------ | ----------------- | ------------------------------------------------------------------------------- |
| **BBB** | Yes | Yes | All on the hub chain. Single transaction, no cross-chain messaging. |
| **BBA** | Yes | No | User is on the hub chain, tokens go to a spoke chain after vault operation. |
| **ABB** | No | Yes | User is on a spoke chain, tokens arrive on the hub chain after vault operation. |
| **ABA** | No | No | Fully cross-chain: spoke → hub → spoke (or another chain). |
#### Simplified Inputs
The SDK provides a built-in address registry for all deployed contracts. You only need to specify chain names, a token name, and the operation.
### Quick Start
```typescript
import { createWalletClient, http, publicActions } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { mainnet } from "viem/chains";
import {
OVaultSyncMessageBuilder,
OVaultSyncOperations,
CHAINS,
} from "@zircuit/ovault-evm";
const account = privateKeyToAccount("0xYOUR_PRIVATE_KEY");
const walletClient = createWalletClient({
account,
chain: mainnet,
transport: http(),
}).extend(publicActions);
// 1. Build the inputs
const inputs = await OVaultSyncMessageBuilder.generateOVaultInputs({
sourceChain: "ethereum",
destinationChain: "ethereum",
token: "usdc",
operation: OVaultSyncOperations.DEPOSIT,
amount: "1",
walletAddress: account.address,
slippage: 0.01,
buffer: 0.3,
referralCode: "ZIRCUIT",
});
// 2. Approve if needed
if (inputs.approval && !inputs.approval.usePermit) {
const approveTx = await walletClient.writeContract({
address: inputs.approval.tokenAddress,
abi: [{
name: "approve", type: "function", stateMutability: "nonpayable",
inputs: [{ name: "spender", type: "address" }, { name: "amount", type: "uint256" }],
outputs: [{ type: "bool" }],
}],
functionName: "approve",
args: [inputs.approval.spender, inputs.approval.amount],
});
await walletClient.waitForTransactionReceipt({ hash: approveTx });
}
// 3. Send the main transaction
const txRequest = OVaultSyncMessageBuilder.encodeTransactionRequest(inputs);
const txHash = await walletClient.sendTransaction(txRequest);
console.log("Submitted:", txHash);
```
### SDK Guide Repository
<https://github.com/zircuit-labs/vault-integration-guide>
### Operations
#### Deposit
Set `operation: OVaultSyncOperations.DEPOSIT`.
* The user provides the **underlying asset** amount.
* The vault mints **shares** in exchange.
* Shares are sent cross-chain to the destination chain if different from the hub.
**What `generateOVaultInputs` selects internally:**
| Source = Hub? | EIP-2612? | Contract | Function |
| ------------- | --------- | ------------------ | -------------------------- |
| No | No | OFT (`oftAddress`) | `send` |
| No | Yes | OFT (`oftAddress`) | `sendWithPermit` |
| Yes | No | OVaultComposerSync | `depositAndSend` |
| Yes | Yes | OVaultComposerSync | `depositAndSendWithPermit` |
#### Redeem
Set `operation: OVaultSyncOperations.REDEEM`.
* The user provides the **share** amount to burn.
* The vault returns the **underlying asset** in exchange.
* Assets are sent cross-chain to the destination chain if different from the hub.
**What `generateOVaultInputs` selects internally:**
| Source = Hub? | Contract | Function |
| ------------- | ------------------ | --------------- |
| No | VaultToken OFT | `send` |
| Yes | OVaultComposerSync | `redeemAndSend` |
**Withdrawal queue**
Redemptions are **not executed immediately**. When the user calls `redeemAndSend` (either directly on the hub or via a cross-chain compose), the VaultComposer enqueues the request into a **withdrawal queue** instead of redeeming from the vault in the same transaction.
**How it works:**
1. The user's shares are transferred into the VaultComposer and a `WithdrawalRequest` event is emitted with a queue `index`.
2. A **keeper** (an account with the `WITHDRAWAL_MANAGER` role) calls `processWithdrawals(ids, extraFees)` to batch-fulfill one or more queued entries. This is the transaction that actually calls `vault.redeem()` and sends the resulting underlying assets to the user's destination chain.
3. The user may **cancel** a pending withdrawal by calling `cancelWithdrawal(id)`, which returns their shares and prepaid fees. Cancellation is only possible before the keeper has processed the entry.
### Input Parameter Reference
All parameters are passed as a single `OVaultCoreInputs` object to `generateOVaultInputs`.
#### Required
| Parameter | Type | Description |
| ------------------ | ---------------------- | ----------------------------------------------------------------------------------- |
| `sourceChain` | `"ethereum" \| "base"` | Chain where the user submits the transaction. |
| `destinationChain` | `"ethereum" \| "base"` | Chain where the user wants to receive tokens. |
| `token` | `"usdc" \| "usdt"` | Token to deposit or redeem. |
| `operation` | `OVaultSyncOperations` | `DEPOSIT` or `REDEEM`. |
| `amount` | `string` | Human-readable unscaled amount (e.g. `"1.23"`). |
| `walletAddress` | `` `0x${string}` `` | The user's wallet address. Also used as the default refund and destination address. |
#### Optional
| Parameter | Type | Default | Description |
| ---------------------- | --------------------------------------------- | --------------- | -------------------------------------------------------------------------------------------------------- |
| `dstAddress` | `` `0x${string}` `` | `walletAddress` | Where tokens are delivered on the destination chain. |
| `slippage` | `number` | `0.01` | Fractional slippage tolerance. Minimum `0.001` (0.1%). Example: `0.01` = 1%. |
| `buffer` | `number` | `0.3` | Additional fractional buffer on the LayerZero messaging fee. `0.3` = +30%. |
| `supportsEip2612` | `boolean` | `false` | Attempt gasless permit instead of a separate `approve` tx. Only applies to deposits. |
| `hubLzComposeGasLimit` | `bigint` | `300_000n` | Gas limit for the `lzCompose` call on the hub chain. |
| `referralCode` | `string` | — | Optional referral code forwarded via `oftCmd` (max 32 bytes). |
| `rpcUrls` | `Partial<Record<SupportedChainName, string>>` | — | Custom RPC URLs keyed by chain name (e.g. `{ ethereum: "https://..." }`). Avoids public RPC rate limits. |
### Tracking Transactions
After submitting a transaction, use `trackOVaultSyncTransaction` to poll the cross-chain status:
```typescript
import { trackOVaultSyncTransaction, CHAINS } from "@zircuit/ovault-evm";
const status = await trackOVaultSyncTransaction(
txHash,
{
sourceChain: CHAINS.ethereum.viemChain,
hubChain: CHAINS.base.viemChain,
dstChain: CHAINS.ethereum.viemChain,
},
);
console.log(status.step);
```
#### Transaction Steps
The returned `step` is an `OVaultTransactionStep` enum value:
| Step | Description |
| ------------------------------ | --------------------------------------------------------------------- |
| `SOURCE_CHAIN_TRANSACTION` | The source-chain transaction is pending or failed. |
| `SOURCE_TO_HUB_LZ_TRANSACTION` | Waiting for LayerZero to deliver the message to the hub. |
| `HUB_CHAIN_TRANSACTION` | The hub-chain compose is pending, executing, or failed. |
| `HUB_TO_DST_LZ_TRANSACTION` | Waiting for LayerZero to deliver the output to the destination chain. |
| `DST_CHAIN_TRANSACTION` | The destination-chain receive is pending. |
| `COMPLETED` | The full operation is complete. |
#### Returned Fields
```typescript
{
step: OVaultTransactionStep;
failureReason?: OVaultFailureReason; // "unknown" — the only value currently
refunded?: boolean; // true if the hub refunded the user's tokens
destinationTxHash?: `0x${string}`; // final tx hash on the destination chain
hubTxHash?: `0x${string}`; // compose tx hash on the hub chain
}
```
### Slippage and Fee Buffer
#### Slippage
`slippage` controls the minimum acceptable output from the vault operation. It applies to the vault's `previewDeposit` / `previewRedeem` quote:
```
minDstAmount = previewOutput - (previewOutput × slippage)
```
The contract reverts with `SlippageExceeded` if the actual output is below `minDstAmount`.
* Minimum allowed: `0.001` (0.1%)
* Default: `0.01` (1%)
#### Fee Buffer
`buffer` adds a safety margin on top of the quoted LayerZero messaging fee. This protects against fee fluctuations between quote time and execution time:
```
effectiveFee = quotedFee + (quotedFee × buffer)
```
* Default: `0.3` (30%)
* Any excess native fee is refunded to `walletAddress` by LayerZero.
#### Tracking Withdrawals
When multiple redemptions are processed in a single transaction, pass `withdrawalInfo` so the tracker selects the correct LayerZero message:
```typescript
const status = await trackOVaultSyncTransaction(
txHash,
{ sourceChain: CHAINS.base.viemChain, hubChain: CHAINS.base.viemChain, dstChain: CHAINS.ethereum.viemChain },
{
index: withdrawalIndex, // bigint | number | string
initiator: walletAddress, // address that initiated the redeem
},
);
```
### Error Reference
#### SDK-level errors (thrown before transaction submission)
| Error message | Cause |
| ----------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `"Unsupported token: <token>"` | The token is not in the built-in registry. |
| `"Token <token> is not deployed on <chain>"` | The token/chain combination does not exist in the registry. |
| `"Amount is too small"` | After LayerZero dust removal, the scaled amount rounded down to zero. Increase the amount. |
| `"Output amount is too small"` | `previewDeposit` / `previewRedeem` returned zero. The amount is below the vault's minimum. |
| `"Slippage must be greater or equal to 0.001 (0.1%)"` | `slippage` was set below the minimum. |
| `"inputs cannot be null"` | `amount` or `tokenHubDecimals` was `null` / `undefined`. |
# Zircuit Finance Addresses
***
## **Base**
**USDC**
| Contract | Address |
| ------------------ | --------------------------------------------------------------------------------------------------------------------- |
| AccountingReceiver | [0x7fCeB53b2959861D29057361158a2B41cAAffD68](https://basescan.org/address/0x7fCeB53b2959861D29057361158a2B41cAAffD68) |
| StrategyManager | [0xf7E745658fa6f1fe8f2CAb47861a273991Cd3374](https://basescan.org/address/0xf7E745658fa6f1fe8f2CAb47861a273991Cd3374) |
| UnderlyingOFT | [0xd7aBC360dfcF1B6dD0a03138235e12A2bc1c1C8B](https://basescan.org/address/0xd7aBC360dfcF1B6dD0a03138235e12A2bc1c1C8B) |
| VaultComposer | [0xBb801ED781dF31F660cC743bEf7Bb9D04B030923](https://basescan.org/address/0xBb801ED781dF31F660cC743bEf7Bb9D04B030923) |
| Vault | [0x03067bbD0d41E3Fe4A0bb6ca67c99e7352Da4CAE](https://basescan.org/address/0x03067bbD0d41E3Fe4A0bb6ca67c99e7352Da4CAE) |
**USDT**
| Contract | Address |
| ------------------ | -------------------------------------------------------------------------------------------------프로젝트로 돌아가기