bitpro가 원문에서 글자만 모은 내용이에요. 표·그림·수식은 빠지거나 깨질 수 있어요. 전체 4쪽 중 3쪽
a specific transaction is suspicious, the corresponding LP tokens will be frozen through the contract’s `freezeShares()` method. Frozen LP tokens cannot be redeemed for underlying assets. The suspicious capital will also be detained per CEX's request.
4. **Blacklist**: If Lorenzo identifies a risk associated with a specific liquidity provider, the wallet address will be added to the blacklist via the contract’s `addBlacklist()` method. Wallets on the blacklist cannot perform any operation on Lorenzo's vault platform.
5. **Monitoring API**: Users can query the current blacklists and frozen asset lists through [the partner API](/docs/financial-abstraction-layer/api-documentation).
# Business Flow
<figure><img src="https://3057728637-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Ftbitm06J0ATMxDbw8njN%2Fuploads%2FUX2nOOTBj6cCm3u4R4tt%2Fbusiness_flow.jpeg?alt=media&token=616e292e-5ccf-46bf-927b-559978b0c790" alt=""><figcaption></figcaption></figure>
1. **Onboarding**: Users approve the vault contract to transfer underlying assets.
2. **Deposit**: Vault transfers assets into custody wallets and issues LP tokens.
3. **Yield Generation**: Off-chain trading engines operate via exchange APIs.
4. **Settlement**: Profits and losses are reported back on-chain; NAV is updated.
5. **Withdrawal**: Users burn LP tokens to redeem underlying assets plus accrued yield.
# API Documentation
## Interface Conventions
* All interface routes carry versions.
* To avoid significant impact on upstream and downstream partners, interfaces within the current version, once released, strive to avoid changes and pursue stability in parameter names, parameter types, and request routing.
## Basic Information
* Partner APIs support RESTful requests and Websocket connections. RESTful request parameters are passed in JSON format.
* Development environment BaseURL: <https://cedefi.lorenzo-dev.xyz>
* The universal return format is JSON.
## Access Control
* **Authentication**
* Each interface has its own independent authentication type. Authentication is not required by default.
* Authentication fields include: IP address, API key, secret signature, whilelistlist, etc.
* **Rate limit**
* RESTful requests can be rate limited. E.g., no more than 5 requests per second for each IP address .
* Websocket connection can also pose subscription limits and communication frequency limits.
## Interface Description
* `/partner/v1/vault/list`
* Function description
> GET request;
>
> This interface can obtain all currently running vaults.
* Request parameters: None
* Return value
<table data-header-hidden><thead><tr><th width="177.109375"></th><th width="160.97265625"></th><th></th></tr></thead><tbody><tr><td><strong>Field name</strong></td><td><strong>Field description</strong></td><td><strong>Remarks</strong></td></tr><tr><td><code>address</code></td><td>Vault address</td><td></td></tr><tr><td><code>vaultType</code></td><td>Vault type</td><td>Such as <code>simple</code>/<code>composed</code>/<code>link</code>, etc</td></tr></tbody></table>
* `/partner/v1/vault/all`
* Function description
> GET request;
>
> This interface returns a list of all vaults on the platform.
* Request parameters: None
* Return value
<table data-header-hidden><thead><tr><th width="167.23046875"></th><th width="166.05078125"></th><th></th></tr></thead><tbody><tr><td><strong>Field name</strong></td><td><strong>Field description</strong></td><td><strong>Remarks</strong></td></tr><tr><td><code>address</code></td><td>Vault address</td><td></td></tr><tr><td><code>vaultType</code></td><td>Vault type</td><td>Such as <code>simple</code>/<code>composed</code>/<code>link</code>, etc</td></tr><tr><td><code>status</code></td><td>Vault status</td><td><code>working</code>: running; <code>stop</code>: permanent stop; <code>pause</code>: pause;</td></tr></tbody></table>
* `/partner/v1/vault/basic`
* Function description
> Get request;
>
> The interface obtains the current basic information of the vault based on the vault address: `unitNAV`, `PnL`, `APR7d`, `APR30d`, `Chains` distributed、`symbol`、`userAmount`、`TVL`、`underlying`
* Request parameters
<pre class="language-json" data-line-numbers><code class="lang-json">{
"address": "0xdAC17F958D2ee523a2206206994597C13D831ec7"
}
</code></pre>
* Return value
<table data-header-hidden><thead><tr><th width="197.76171875"></th><th width="280.97265625"></th><th></th></tr></thead><tbody><tr><td><strong>Field name</strong></td><td><strong>Field description</strong></td><td><strong>Remarks</strong></td></tr><tr><td><code>address</code></td><td>Vault contract address</td><td></td></tr><tr><td><code>unitNAV</code></td><td>Net worth of funds</td><td></td></tr><tr><td><code>PnL</code></td><td>Yield value</td><td></td></tr><tr><td><code>APR7d</code></td><td>7-Day yield</td><td></td></tr><tr><td><code>APR30d</code></td><td>30-Day yield</td><td></td></tr><tr><td><code>Chains</code></td><td>Chain deployed on by vault</td><td>Ethereum, BSC, etc.</td></tr><tr><td><code>Symbol</code></td><td>Asset symbol</td><td>enzoBTC, finBTC, etc.</td></tr><tr><td><code>userAmount</code></td><td>Current number of participants</td><td></td></tr><tr><td><code>TVL</code></td><td>Current Total Value Locked</td><td>Unit: currency standard</td></tr><tr><td><code>underlying</code></td><td>Underlying assets of the vault</td><td>BTC, ETH, etc.</td></tr></tbody></table>
* `/partner/v1/vault/freeze/list`
* Function description
> GET request;
>
> This interface queries the current vault's blacklist and frozen asset list based on the vault address.
>
> If the returned list is empty, then nothing has been blacklisted or frozen.
* Request parameters
<pre class="language-json" data-line-numbers><code class="lang-json">{
"address": "0xdAC17F958D2ee523a2206206994597C13D831ec7"
}
</code></pre>
* Return value (as list element)
<table data-header-hidden><thead><tr><th width="171.64453125"></th><th width="276.546875"></th><th></th></tr></thead><tbody><tr><td><strong>Field name</strong></td><td><strong>Field description</strong></td><td><strong>Remarks</strong></td></tr><tr><td><code>UserAddr</code></td><td>Address of the blacklisted user</td><td></td></tr><tr><td><code>Amount</code></td><td>Amount of frozen asset</td><td>Value is after dividing 10^18</td></tr><tr><td><code>AssetAddr</code></td><td>Token address of the frozen asset</td><td></td></tr><tr><td><code>FreezeTime</code></td><td>The most recent frozen time</td><td>UTC timestamp;<br>The same asset of a user can be frozen multiple times</td></tr><tr><td><code>Chain</code></td><td>Chain deployed on by vault</td><td>Ethereum, BSC, etc.</td></tr><tr><td><code>Symbol</code></td><td>Asset symbol</td><td>enzoBTC, finBTC, etc.</td></tr></tbody></table>
* `/partner/v1/vault/performance`
* Function description
> GET request;
>
> This interface obtains the past performance of the vault based on its vault address: `unitNAV`, `PnL`, `Symbol`, `APR7d`, `APR30d`, `StartTime`, `EndTime`, `TVL`.
* Request parameters
<pre class="language-json" data-line-numbers><code class="lang-json">{
"address": "0xdAC17F958D2ee523a2206206994597C13D831ec7"
}
</code></pre>
* Return value
<table data-header-hidden><thead><tr><th width="188.796875"></th><th></th><th></th></tr></thead><tbody><tr><td><strong>Field name</strong></td><td><strong>Field description</strong></td><td><strong>Remarks</strong></td></tr><tr><td><code>unitNAV</code></td><td>Net worth of funds</td><td></td></tr><tr><td><code>PnL</code></td><td>Yield value</td><td></td></tr><tr><td><code>APR7d</code></td><td>7-Day yield</td><td></td></tr><tr><td><code>APR30d</code></td><td>30-Day yield</td><td></td></tr><tr><td><code>Symbol</code></td><td>Asset symbol</td><td>enzoBTC, finBTC, etc.</td></tr><tr><td><code>StartTime</code></td><td>Start time</td><td>Timestamp</td></tr><tr><td><code>EndTime</code></td><td>End time</td><td>Timestamp</td></tr><tr><td><code>TVL</code></td><td>Total Value Locked</td><td>Currency standard</td></tr></tbody></table>
* `/partner/v1/vault/por`
* Function description
> GET request;
>
> This interface obtains the proof of reserve information corresponding to the vault address.
* Request parameters
<pre class="language-json" data-line-numbers><code class="lang-json">{
"address": "0xdAC17F958D2ee523a2206206994597C13D831ec7"
}
</code></pre>
* Return value
<table data-header-hidden><thead><tr><th width="131.1484375"></th><th width="249.3203125"></th><th></th></tr></thead><tbody><tr><td><strong>Field name</strong></td><td><strong>Field description</strong></td><td><strong>Remarks</strong></td></tr><tr><td><code>method</code></td><td>Proof of reserve method id</td><td><p>1: Balance snapshot; </p><p>2: merkel tree</p><p>3: zk-snark</p><p>4: Third-party centralized audit<br>...</p></td></tr><tr><td><code>content</code></td><td>Content of proof of reserve certificate</td><td>String content or download link</td></tr></tbody></table>
* `/partner/v1/InitOrUpdate`
* Function description
> POST request;
>
> Update a partner's information if the partner's name exists; otherwise, create a new partner and populate necessary information.
>
> Mostly used for onboarding trading partners, e.g., quantitative trading teams.
* Request parameters
<table data-header-hidden><thead><tr><th width="162.25390625"></th><th></th><th></th></tr></thead><tbody><tr><td><strong>Field name</strong></td><td><strong>Field description</strong></td><td><strong>Remarks</strong></td></tr><tr><td><code>Name</code></td><td>Name of the partner</td><td>Needs to be globally unique</td></tr><tr><td><code>Style</code></td><td>Style of the partner</td><td>Balance, growth, etc.</td></tr><tr><td><code>Logo</code></td><td>URL of the partner's logo</td><td></td></tr><tr><td><code>AssetClass</code></td><td>Asset class</td><td></td></tr><tr><td><code>Category</code></td><td>Asset catalog</td><td></td></tr></tbody></table>
# Example: How to Create a Lorenzo OTF Vault for a Trading Strategy
The following are the steps to create a `finBTC` test vault on BSC Testnet. `finBTC` is the name of the OFT token.
1. First, determinine the type of the underlying asset. Here we use the test token BBTC.
2. Create 3 custody wallets, each receives 20%, 30%, 50% of the deposited BBTC tokens, respectively.
3. Add the 3 wallets to `CeDeFiManager` by calling the method `addPortfolios(address[])`. Only these portfolios can be used for creating a vault.
4. Create the vault for BBTC by invoking the `creataVault()` method of `CeDeFiManager` :
{% code lineNumbers="true" %}
```typescript
const [admin] = await ethers.getSigners();
const minDepositAmount = ethers.parseEther("1");
const minWithdrawAmount = ethers.parseEther("0.5");
const pp1 = ethers.parseEther("0.2"); // 20%
const pp2 = ethers.parseEther("0.3"); // 30%
const pp3 = ethers.parseEther("0.5"); // 50%
const CeDeFiManager = await ethers.getContractAt('CeDeFiManager', DebugContracts.Manager)
let t = await CeDeFiManager.connect(admin).createVault(
1, // yield type 1 means SimpleVault
"Fin BTC", // name of this vault
"finBTC", // symbol of this vault
"0x4636E9e38121d3bB7773Ff63a85d1bF97c17d00f", // address of underlying asset
minDepositAmount,
minWithdrawAmount,
["0x40209e58D76492387eab68607F3731F4c4faB24c",
"0xeEA32E607235Ca6A18e2FC30Bb22421d9E2A7564",
"0x96c1FA3793804e140E5c4a6A91966485d677c6aD"
],
[pp1, pp2, pp3]
);
await t.wait();
console.log(`createVault: ${t.hash}`);
```
{% endcode %}
5. Now the vault is created and users can deposit BBTC to this vault from Lorenzo frontend.
# Example: How to Use Lorenzo OTF Vaults
To *deposit/withdraw* assets to/from Lorenzo OTF vaults, please follow the following steps:
## Deposit
1. Approve your underlying asset to the vault contract for the desired amount. The deposit amount must be greater than the `minDepositAmount` value set in the vault.
2. Compose a transaction to call the `depoist(uint256)` method on the vault and submit the transaction.
3. On receiving the transaction:
1. The vault first transfers the underlying asset in by calling `transferFrom()`.
2. The vault then dispatches the underlying assets to its portfolios' wallet addresses.
3. The vault finally mints LP tokens to the depositor. For calculation details, please refer to [the previous section](/docs/financial-abstraction-layer/technical-design/lp-tokens-and-unit-nav-calculation). 
## Request Withdrawal
1. First, determine the amount of LP token shares to withdraw and invoke the `requestWithdraw(uint256)` method on the vault contract. The amount of shares must be greater than the `minWithdrawAmount` value set in the vault. If the amount of shares is less than `minWithdrawAmount`, all of the balance must be withdrawn at once.
2. After the transaction is submitted successfully, a `requestId` is returned for later completing the final withdrawal. If the user submits multiple withdrawal requests within the same settlement period, the amount of requested LP tokens is accumulated and associated to only **one** `requestId`.
3. The requested amount of LP tokens are locked instead of being immediately burnt until the final withdrawal settlement.
4. Wait 5\~8 days until the $$UnitNAV$$ is finalized for the current settlement period.
## Withdraw
1. After the $$UnitNAV$$ is finalized, the final withdrawal settlement can proceed.
2. Invoke the `withdraw(unint256 reqeustId)` method on the vault with the prefiously received `requestId`.
3. After the transaction is submitted, the corresponding amount of underlying assets is returned. The received amount $$R\_{underlying}=\Delta{shares}\times{UnitNAV \_ {n}}$$, and $$\Delta{shares}$$ of LP tokens are burnt.
# Testnet Configuration
The information of smart contracts deployed on BSC Testnet.
<table><thead><tr><th>Chain</th><th width="196.16015625">Contract Name</th><th width="424.99609375">Contract Address</th><th width="560.19921875">Comments</th></tr></thead><tbody><tr><td>BSC Testnet</td><td>CeDeFiManager</td><td>0x1cF7e24f5939F4AdEb5a9C9C9dD4848c8FEEEda7</td><td>Entrypoint contract for Lorenzo Universal Financial Abstraction Layer.</td></tr><tr><td>BSC Testnet</td><td>FinBTC Vault</td><td>0xb71317102C11590F72FFAe92Dd8aB70318C37e19</td><td>An Instance of the <code>CustodyVault</code> contract, which receives the test token BBTC as its underlying asset.</td></tr><tr><td>BSC Testnet</td><td>Test BBTC Token</td><td>0x4636E9e38121d3bB7773Ff63a85d1bF97c17d00f</td><td>ERC20 test token address of BBTC.</td></tr><tr><td>BSC Testnet</td><td>Custody Wallet1</td><td>0x40209e58D76492387eab68607F3731F4c4faB24c</td><td>Custody wallet of a portfolio for BBTC.</td></tr><tr><td>BSC Testnet</td><td>Custody Wallet2</td><td>0xeEA32E607235Ca6A18e2FC30Bb22421d9E2A7564</td><td></td></tr><tr><td>BSC Testnet</td><td>Custody Wallet3</td><td>0x96c1FA3793804e140E5c4a6A91966485d677c6aD</td><td></td></tr></tbody></table>
# Bitcoin Liquidity Layer
Despite Bitcoin holding over **$1.3 trillion** in market capitalization and accounting for nearly **50%** of the entire crypto market, its integration into DeFi remains surprisingly limited. As of today, **less than 0.3%** of total BTC supply is actively represented in DeFi protocols, with **Wrapped BTC (wBTC)**—the most popular BTC wrapper—holding under **160,000 BTC**, equivalent to less than **0.8%** of total circulating Bitcoin. This stark imbalance underscores a significant inefficiency: trillions of dollars in BTC value are sitting idle, disconnected from the high-yield opportunities and composability of DeFi.
Lorenzo's **Bitcoin Liquidity Layer** is built to close this gap. By offering infrastructure for issuing a suite of BTC-native derivative tokens—including wrapped, staked, and structured yield-bearing formats—Lorenzo enables scalable and secure Bitcoin participation in DeFi. This unlocks passive BTC into active capital, powering lending, yield farming, structured products, and broader financial utility across decentralized markets. Lorenzo aims to make Bitcoin not just a store of value, but also a core productive asset in the DeFi economy.
# stBTC: Babylon BTC Liquid Staking Token
After Bitcoin liquidity has been staked into Babylon, Lorenzo issues *Liquid Staking Tokens (LST)*, which includes the *Liquid Principal Tokens (LPT)* stBTC. In addition, stBTC holders receives *Yield Accruing Tokens (YAT)*, which contains staking yields and also Lorenzo Points.
#### stBTC: The Babylon staking LPT <a href="#stbtc-the-babylon-staking-lpt" id="stbtc-the-babylon-staking-lpt"></a>
LPTs do not have to be in the same form for Bitcoin staking, but Lorenzo promotes stBTC, the LPT for Babylon staking. Using stBTCs, if a user stakes 10 BTCs, for example, to a non-slashable PoS chain in the Babylon ecosystem, Lorenzo will return the user 10 stBTCs. The user will later use the 10 stBTCs to reclaim the staked principle of 10 BTCs.
## stBTC Issuance and Settlement
<div data-full-width="false"><figure><img src="https://docs.lorenzo-protocol.xyz/~gitbook/image?url=https%3A%2F%2F3127159353-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FO2IxV7UUnOLeIt1TpThj%252Fuploads%252F2X7u5KcPnJdBJd6jT1aH%252Fbtc-staking-token-2-1.png%3Falt%3Dmedia%26token%3Dec40d4e4-96d8-4173-8c1e-1b2c2efd720e&width=768&dpr=4&quality=100&sign=cfd91473&sv=2" alt="" width="563"><figcaption><p>Bitcoin staking token issuance and settlement.</p></figcaption></figure></div>
For every BTC staked in Babylon, Lorenzo issues stBTC, stBTC is the first LPT created on Lorenzo Protocol.
Settlement of stBTC is not a trivial task. For example, Alice stakes 10 BTCs and gets 10 stBTCs in return. After some thoughtful trading, by the time Alice unstakes, Alice owns 15 stBTCs, which would be honored with 15 stBTCs. As a result, the settlement system should be able to take the 5 additional BTCs from other stakers and give them to Alice. This also indicates that the settlement system has to be able to move stakers’ Bitcoins around.
To achieve this capability, the straightforward option is to build a centralized settlement system for Bitcoin staking. In this case, Lorenzo is the entity to freely move stakers’ BTCs around, without inherent guarantees to the stakers that Lorenzo will not misuse the BTCs under its management. Another option is to build a fully decentralized settlement system on Bitcoin Layer 1, which is the ultimate goal of Lorenzo in the long run. However, due to the limited programmability of today’s Bitcoin network, is it infeasible to build it any time soon.
As a result, Lorenzo adopts a third option, a *CeDeFi* way. Lorenzo will work with Staking Agents, a limited group of trustworthy Bitcoin institutions, to issue and settle Bitcoin staking tokens. When a user stakes to a ticker listed on Lorenzo, the user has to deposit BTCs to a Staking Agent and request the Staking Agent to stake to the project related to the ticker. The Staking Agent is then obligated to:
1. Complete timely staking.
2. Upload staking proof to Lorenzo.
3. Issue LPTs and YATs for the staking transaction on Lorenzo based on the rules defined by the ticker.
4. Transfer the LPTs and YATs generated to the staker’s address.
Only qualified institutions will be whitelisted to take stakers’ BTCs for delegated staking and issue stBTC and YATs. The whitelist is subject to change and misbehavior of a Staking Agent could cause the Staking Agent to be disqualified.
stBTC holders will receive YATs containing staking yields when holding stBTC. YAT could be used to claim the underlying yield (points, ERC20, NFT, etc). When a user unstakes stBTC, the project, Lorenzo Protocol will return the BTC principal to the Staking Agent, and the staker should ask the creator of the BLSP to settle the BTC staked.
***Currently, Lorenzo itself is the only Staking Agent.*** If staker stakes with other Staking Agents in the future, since Lorenzo프로젝트로 돌아가기