Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ Where to ask questions, follow announcements, file issues, or reach the team abo

| Purpose | Where to go | Link |
| --- | --- | --- |
| General questions, chat with the community, get help while using the Aave v4 Lending Dashboard | Discord | [discord.gg/qwTzSmtP](https://discord.gg/qwTzSmtP) |
| General questions, chat with the community, get help while using the TBV Testnet app | Discord | [discord.gg/qwTzSmtP](https://discord.gg/qwTzSmtP) |
| Announcements, release notes, status updates | Twitter / X | [@babylonlabs_io](https://x.com/babylonlabs_io) |
| Real-time chat (alternative to Discord) | Telegram | [t.me/babyloncommunity](https://t.me/babyloncommunity) |
| Source code, issue tracker, SDK | GitHub | [github.com/babylonlabs-io](https://github.com/babylonlabs-io) |
Expand All @@ -21,7 +21,7 @@ Where to ask questions, follow announcements, file issues, or reach the team abo

## Where to ask what

* **Stuck mid-flow on the Aave v4 Lending Dashboard:** Discord, in the Testnet support channel
* **Stuck mid-flow on the TBV Testnet app:** Discord, in the Testnet support channel
* **Found a bug in the UI or contracts (non-security):** open an issue on GitHub
* **Question about how something works conceptually:** start with [Quickstart](/trustless-bitcoin-vault/use-for-lending/quickstart/) and [TBV vs alternatives](/trustless-bitcoin-vault/start-here/tbv-vs-alternatives/), then ask in Discord
* **Lost your WOTS keypair and claimer artifacts:** if the Vault Provider for that vault is also unresponsive, contact the team to initiate Security Council recovery. See [Withdraw & redeem](/trustless-bitcoin-vault/use-for-lending/withdraw-and-redeem/) for the self-claim path's input requirements
Expand Down
2 changes: 1 addition & 1 deletion docs/trustless-bitcoin-vault/reference/glossary.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,7 @@ borrows. See

**Depositor.** The Bitcoin holder who creates a vault to use BTC as collateral.
The depositor's keys are required at vault creation and at every
depositor-controlled release path. In lending contexts, the depositor is also
depositor-controlled release path. In borrowing workflows, the depositor is also
the borrower.

**Depositor claim output.** A small Bitcoin output produced by the PegIn
Expand Down
4 changes: 2 additions & 2 deletions docs/trustless-bitcoin-vault/start-here/how-it-works.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ Two safety properties are built into the peg-in flow:

## Activating a vault as collateral in Aave v4

An active vault is automatically supplied as collateral on the application chosen at peg-in. On activation, the BTC Vault Manager notifies the Aave v4 Adapter. The adapter mints an internal accounting token (**vaultBTC**) for the vault's BTC amount and supplies it to the **Babylon Core Spoke**, the dedicated Aave v4 market that accepts vaultBTC as collateral. The vault is appended to the depositor's lending position; subsequent activations add to the same position.
An active vault is automatically supplied as collateral on the application chosen at peg-in. On activation, the BTC Vault Manager notifies the Aave v4 Adapter. The adapter mints an internal accounting token (**vaultBTC**) for the vault's BTC amount and supplies it to the **Babylon Core Spoke**, the dedicated Aave v4 market that accepts vaultBTC as collateral. The vault is appended to the depositor's borrowing position; subsequent activations add to the same position.

A BTC vault is created for one specific application at peg-in and cannot be moved between applications later. The protocol is designed to support multiple applications, but each requires its own adapter and its own vaults; integration is not "out of the box".

Expand All @@ -56,7 +56,7 @@ With a single-vault position, any liquidation seizes the whole collateral backin

When a depositor is done with a vault, or when liquidation triggers, the vault enters the redemption flow on Bitcoin. The Bitcoin side knows only "redeem": the application layer translates withdrawal after repayment or liquidation into the redeem call. There are two main paths and one safety fallback.

**Path 1: withdrawal after repayment.** After repaying the loan, the depositor withdraws the vault from the lending position. This burns the corresponding vaultBTC and triggers vault redemption on the Bitcoin side. The protocol contracts emit a redemption event for the depositor to withdraw the vault on Ethereum, the Vault Provider submits a claim transaction on Bitcoin, and after the challenge period ends, the BTC is released to the depositor's Bitcoin address (minus the Vault Provider's commission).
**Path 1: withdrawal after repayment.** After repaying the debt, the depositor withdraws the vault from the borrowing position. This burns the corresponding vaultBTC and triggers vault redemption on the Bitcoin side. The protocol contracts emit a redemption event for the depositor to withdraw the vault on Ethereum, the Vault Provider submits a claim transaction on Bitcoin, and after the challenge period ends, the BTC is released to the depositor's Bitcoin address (minus the Vault Provider's commission).

**Path 2: liquidation.** If the position's health factor drops below 1.0, anyone can call the liquidation function on Ethereum. The liquidator repays part of the debt and the protocol seizes the necessary vaults. The seized vaults then enter the same redemption flow, with the claimer being a registered Application Vault Keeper (an arbitrageur in the Aave integration) who may or may not also be the liquidator that triggered the seizure. The over-seized value is returned to the depositor either as additional debt repayment on their behalf (the common case during partial-position liquidation) or, on full-position liquidation when all debt is covered, paid in WBTC. See [Liquidation risk](../use-for-lending/liquidation-risk.mdx).

Expand Down
6 changes: 3 additions & 3 deletions docs/trustless-bitcoin-vault/start-here/what-is-tbv.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -52,14 +52,14 @@ Beyond the chains themselves, residual trust sits with the protocol's governance

**The TBV protocol and the DeFi applications on top.**

![TBV two-layer model: TBV protocol layer under Aave v4 lending and future DeFi applications](/img/trustless-bitcoin-vault/confluence/start-here/what-is-tbv/TBV2-LAYERS.png)
![TBV two-layer model: TBV protocol layer under Aave v4 borrowing and future DeFi applications](/img/trustless-bitcoin-vault/confluence/start-here/what-is-tbv/TBV2-LAYERS.png)

* **The TBV protocol.** The core collateral protocol. It owns vault creation (peg-in), vault redemption (peg-out), the BABE-based proof-verification flow, and vault state.
* **DeFi applications on top.** Each integrated application defines its own product — lending, stablecoins, options, insurance — and is responsible for its own borrowing, liquidation, and reward logic. The first application is **Aave v4 lending**.
* **DeFi applications on top.** Each integrated application defines its own product — lending, stablecoins, options, insurance — and is responsible for its own borrowing, liquidation, and reward logic. The first application is the **Aave v4 borrowing integration**.

Each BTC vault is created for one specific application at vault creation. The protocol is designed for multiple applications, but a vault is bound to its application from creation and cannot be moved between applications. Future application integrations would each integrate through their own adapter and receive their own vaults.

On Testnet today, only the Aave v4 lending application is live. Most user-facing pages in these docs ([Borrow & repay](../use-for-lending/borrow-and-repay.mdx), [Withdraw & redeem](../use-for-lending/withdraw-and-redeem.mdx), [Liquidation risk](../use-for-lending/liquidation-risk.mdx)) describe how things work specifically within that integration. [How it works](./how-it-works.mdx) describes the TBV protocol flow at a higher level.
On Testnet today, only the Aave v4 borrowing integration is live. Most user-facing pages in these docs ([Borrow & repay](../use-for-lending/borrow-and-repay.mdx), [Withdraw & redeem](../use-for-lending/withdraw-and-redeem.mdx), [Liquidation risk](../use-for-lending/liquidation-risk.mdx)) describe how things work specifically within that integration. [How it works](./how-it-works.mdx) describes the TBV protocol flow at a higher level.

## What you can test today

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ sidebar_position: 2

# Contract Addresses

This page lists the deployed contract addresses for the current Trustless Bitcoin Vault (TBV) Testnet release on **Sepolia** (chain ID `11155111`). Depositors using the Aave v4 Lending Dashboard do not need to interact with contracts directly.
This page lists the deployed contract addresses for the current Trustless Bitcoin Vault (TBV) Testnet release on **Sepolia** (chain ID `11155111`). Depositors using the TBV Testnet app do not need to interact with contracts directly.

Addresses can change between Testnet releases. Always check this page before sending a transaction or interacting with a contract directly.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -113,6 +113,6 @@ Each Vault Provider sets its own commission per vault, taken in BTC from the red

## Related

* [Setup](./setup.mdx): wallets, networks, faucets, and the Aave v4 Lending Dashboard URL.
* [Setup](./setup.mdx): wallets, networks, faucets, and the TBV Testnet app URL.
* [Create a vault](../use-for-lending/create-a-vault.mdx): how vault caps and timing apply during peg-in.
* [Liquidation risk](../use-for-lending/liquidation-risk.mdx): how liquidation parameters affect a participant position.
8 changes: 4 additions & 4 deletions docs/trustless-bitcoin-vault/testnet-info/setup.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -6,15 +6,15 @@ sidebar_position: 1

# Setup

Reference for wallets, networks, faucets, and the Aave v4 Lending Dashboard URL used by the Trustless Bitcoin Vault (TBV) public testnet. The walkthrough that uses these values is on [Quickstart](../use-for-lending/quickstart.mdx). For the live numeric values of per-vault, per-position, and per-application caps, see [Protocol parameters](./protocol-parameters.mdx).
Reference for wallets, networks, faucets, and the TBV Testnet app URL used by the Trustless Bitcoin Vault (TBV) public testnet. The walkthrough that uses these values is on [Quickstart](../use-for-lending/quickstart.mdx). For the live numeric values of per-vault, per-position, and per-application caps, see [Protocol parameters](./protocol-parameters.mdx).

## Aave v4 Lending Dashboard
## TBV Testnet app

Open the Aave v4 Lending Dashboard to start a deposit (peg-in).
Open the TBV Testnet app to start a deposit (peg-in) and borrowing flow.

| Field | Value |
| --- | --- |
| Aave v4 Lending Dashboard URL | [https://btc-vaults.testnet.babylonlabs.io/](https://btc-vaults.testnet.babylonlabs.io/) |
| Testnet app URL | [https://btc-vaults.testnet.babylonlabs.io/](https://btc-vaults.testnet.babylonlabs.io/) |

## Prerequisites

Expand Down
4 changes: 2 additions & 2 deletions docs/trustless-bitcoin-vault/use-for-lending/_category_.json
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
{
"label": "Use TBV Testnet For Lending",
"label": "Use TBV Testnet For Borrowing",
Comment thread
web3jenks marked this conversation as resolved.
"position": 4,
"collapsible": true,
"collapsed": true,
"link": {
"type": "generated-index",
"description": "Depositor critical path for the Aave v4 integration on TBV: step-by-step walkthroughs from the first peg-in to redeeming BTC."
"description": "Borrower critical path for the Aave v4 integration on TBV: step-by-step walkthroughs from the first peg-in to redeeming BTC."
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ This page describes borrow and repay flows on the **Aave v4 integration** — th

This page covers borrowing USDC, USDT, or WBTC against an active vault, how interest accrues, and how to repay. The vault creation step that comes before is on [Create a vault](./create-a-vault.mdx). The redemption step that comes after is on [Withdraw & redeem](./withdraw-and-redeem.mdx).

An activated vault becomes usable collateral automatically: the activation transaction moves the vault to `InUse` and the contracts mint and supply the corresponding vaultBTC to the lending market. From there, the day-to-day life of a position is the standard DeFi borrow-and-repay loop, with vault-specific behaviour around collateral structure and liquidation. This page is the operating guide for that loop.
An activated vault becomes usable collateral automatically: the activation transaction moves the vault to `InUse` and the contracts mint and supply the corresponding vaultBTC to the Aave v4 market. From there, the day-to-day life of a position is the standard DeFi borrow-and-repay loop, with vault-specific behaviour around collateral structure and liquidation. This page is the operating guide for that loop.

:::info Public-testnet caps
Public-testnet caps on per-address total collateral and per-position vault count apply. See [Protocol parameters](../testnet-info/protocol-parameters.mdx) for the live numeric limits.
Expand Down Expand Up @@ -136,11 +136,11 @@ After all debt is repaid across all asset reserves, the position is eligible to

To grow a position over time, add more vaults.

Create and activate another vault. Once the activation transaction succeeds, the contract mints the additional vaultBTC and supplies it to the same lending position automatically.
Create and activate another vault. Once the activation transaction succeeds, the contract mints the additional vaultBTC and supplies it to the same borrowing position automatically.

Activating another vault:

* Mints additional vaultBTC and supplies it to the lending market.
* Mints additional vaultBTC and supplies it to the Aave v4 market.
* Increases the position's collateral value.
* Raises the health factor.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -157,7 +157,7 @@ vaultBTC for the vault's BTC amount is **automatically minted and supplied** to

![Vault supplied as collateral](/img/trustless-bitcoin-vault/confluence/use-for-lending/create-a-vault/screenshot-090-20260601-042948.png)

**Combine with other vaults.** Subsequent vault activations append to the same lending position automatically. Position-level limits apply; see [Protocol parameters](../testnet-info/protocol-parameters.mdx) for the current caps.
**Combine with other vaults.** Subsequent vault activations append to the same borrowing position automatically. Position-level limits apply; see [Protocol parameters](../testnet-info/protocol-parameters.mdx) for the current caps.

## Reorder vaults later

Expand Down
10 changes: 5 additions & 5 deletions docs/trustless-bitcoin-vault/use-for-lending/quickstart.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ This walkthrough goes through the **Aave v4 integration** — the first supporte

This page is the full happy path end to end: connect a wallet, deposit signet BTC, borrow stablecoins, repay, redeem. About 5 minutes of clicking, plus a ~2-hour wait for Bitcoin confirmations during peg-in and a ~3-day challenge window during redemption. Each step links to the matching deep page for full detail.

A Trustless Bitcoin Vault (TBV) locks BTC on the Bitcoin Network and makes it usable as collateral on Ethereum without bridges or wrapping. The Aave v4 Lending Dashboard drives a full peg-in, borrow, repay, and peg-out cycle end to end.
A Trustless Bitcoin Vault (TBV) locks BTC on the Bitcoin Network and makes it usable as collateral on Ethereum without bridges or wrapping. The TBV Testnet app drives a full peg-in, borrow, repay, and peg-out cycle end to end.

The public testnet runs on signet, a Bitcoin test network. The BTC and stablecoins involved have no monetary value. Some flows are still under active development; report issues to the team via the channels listed in [Community & support](../reference/community-and-support.mdx).

Expand All @@ -29,9 +29,9 @@ You need:

For the full list of supported wallets, network and RPC details, and faucet URLs, see [Setup](../testnet-info/setup.mdx).

## Step 1: Open the Aave v4 Lending
## Step 1: Open the TBV Testnet app

Navigate to the Aave v4 Lending Dashboard URL listed in [Setup](../testnet-info/setup.mdx).
Navigate to the TBV Testnet app URL listed in [Setup](../testnet-info/setup.mdx).

![App landing page in the pre-wallet state](/img/trustless-bitcoin-vault/confluence/use-for-lending/quickstart/image-20260527-084545.png)

Expand Down Expand Up @@ -65,7 +65,7 @@ The app then runs the off-chain setup automatically: authentication, signature c

The app recommends splitting your deposit into two vaults: a sacrificial vault sized to cover the protocol's expected seizure amount (placed first in liquidation order), and a protected vault holding the rest (placed second). At current public-testnet parameters, the sacrificial vault is the larger of the two. For the order-change UI, see [Reorder BTC vaults](./create-a-vault.mdx#reorder-vaults-later).

When the vault reaches **Verified** status, the app prompts you to **Activate**. Click it. The vault transitions to **Active**, and the protocol automatically supplies it to the lending position.
When the vault reaches **Verified** status, the app prompts you to **Activate**. Click it. The vault transitions to **Active**, and the protocol automatically supplies it as collateral to your borrowing position.

![Active vault in the Collateral section](/img/trustless-bitcoin-vault/use-for-lending/quickstart-06-activate-prompt.png)

Expand Down Expand Up @@ -159,4 +159,4 @@ For anything else, ask in the public-testnet support channel listed on [Communit

## You've completed a full cycle

Wallets connected, signet BTC locked, internal accounting supplied, stablecoins borrowed, repaid, and BTC recovered.
Wallets connected, signet BTC locked, collateral activated, stablecoins borrowed, repaid, and BTC recovered.
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ Redemption (peg-out) is the reverse of vault creation. It unlocks the bitcoin si

You have two routes to recover your BTC:

* **Normal exit.** Repay any outstanding debt, withdraw the vault from your lending position, and let the Vault Provider drive the Bitcoin claim. This is the common path.
* **Normal exit.** Repay any outstanding debt, withdraw the vault from your borrowing position, and let the Vault Provider drive the Bitcoin claim. This is the common path.
* **Depositor self-claim.** Broadcast the Bitcoin claim yourself using the Winternitz One-Time Signature (WOTS) key and claimer artifacts committed at vault creation, via the protocol's `watchtower` CLI tool. Use this if the Vault Provider is offline, slow, or refuses to act.

A third path exists but is not under your control: **liquidation redemption**. If your position is liquidated, the seized vault is redeemed by the liquidator, not by you. See [Liquidation risk](./liquidation-risk.mdx).
Expand Down Expand Up @@ -73,7 +73,7 @@ From the portal:
2. Each withdrawn vault transitions from `InUse` to `Available`, then on to `Redeemed`. `withdrawCollaterals` always starts redemption — vaults cannot be withdrawn into Available status and held there for later re-supply.
3. The contract emits two `VaultClaimableBy` events per vault: one naming the Vault Provider's BTC public key as claimer, and one naming your BTC public key. The second event is what enables self-claim.

From the depositor's point of view, `withdrawCollaterals` is a single transaction that removes vaults from the lending position and starts the Bitcoin claim.
From the depositor's point of view, `withdrawCollaterals` is a single transaction that removes vaults from the borrowing position and starts the Bitcoin claim.

## Step 3: Wait for the challenge period

Expand Down Expand Up @@ -129,7 +129,7 @@ If you lose *both* the WOTS file and the artifacts, and the Vault Provider is al

## What happens to vaultBTC

vaultBTC is an accounting token. It exists only while your BTC is supplying a lending position.
vaultBTC is an accounting token. It exists only while your BTC is backing a borrowing position.

* When you withdraw a vault, the corresponding vaultBTC is burned in the same transaction.
* Total vaultBTC supply always equals BTC currently held as active collateral across all positions in the integration.
Expand Down Expand Up @@ -157,7 +157,7 @@ The Ethereum-side actions complete in minutes. The Bitcoin-side challenge window

**A challenge is raised against your claim.** If the claim is legitimate, the claimer (Vault Provider or you, in self-claim) broadcasts `WronglyChallenged` to disprove the challenge. The challenger forfeits a bond. The payout proceeds.

**You cannot find the vault ID or position details.** Look up the position on the Aave v4 Lending Dashboard Collateral or Loans section. Programmatically, query `getPosition()` on the AaveAdapter with your address, or look up the vault registry by your depositor address.
**You cannot find the vault ID or position details.** Look up the position in the TBV Testnet app's Collateral or Loans section. Programmatically, query `getPosition()` on the AaveAdapter with your address, or look up the vault registry by your depositor address.

## Related pages

Expand Down
Loading