diff --git a/docs/trustless-bitcoin-vault/reference/community-and-support.mdx b/docs/trustless-bitcoin-vault/reference/community-and-support.mdx index 10cafe83..c32ff118 100644 --- a/docs/trustless-bitcoin-vault/reference/community-and-support.mdx +++ b/docs/trustless-bitcoin-vault/reference/community-and-support.mdx @@ -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) | @@ -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 diff --git a/docs/trustless-bitcoin-vault/reference/glossary.mdx b/docs/trustless-bitcoin-vault/reference/glossary.mdx index 8c01ea1a..9b66455b 100644 --- a/docs/trustless-bitcoin-vault/reference/glossary.mdx +++ b/docs/trustless-bitcoin-vault/reference/glossary.mdx @@ -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 diff --git a/docs/trustless-bitcoin-vault/start-here/how-it-works.mdx b/docs/trustless-bitcoin-vault/start-here/how-it-works.mdx index c44a3400..4d350aa9 100644 --- a/docs/trustless-bitcoin-vault/start-here/how-it-works.mdx +++ b/docs/trustless-bitcoin-vault/start-here/how-it-works.mdx @@ -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". @@ -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). diff --git a/docs/trustless-bitcoin-vault/start-here/safety-and-trust-assumptions.mdx b/docs/trustless-bitcoin-vault/start-here/safety-and-trust-assumptions.mdx new file mode 100644 index 00000000..5de2c9f1 --- /dev/null +++ b/docs/trustless-bitcoin-vault/start-here/safety-and-trust-assumptions.mdx @@ -0,0 +1,146 @@ +--- +title: Safety & trust assumptions +sidebar_position: 4 +--- + +# Safety & trust assumptions + +A [Trustless Bitcoin Vault (TBV)](./what-is-tbv.mdx) is designed so that the depositor never has to trust a third party for the safety of the deposited BTC — subject only to the protocol's own cryptographic invariants and the chains it runs on. The accounting token used on Ethereum is vaultBTC. This page describes the protocol's safety guarantees, the optional roles other parties play, how a depositor can participate without trusting any of them, the operational pause states, the risk surface, and the caveats that apply specifically to the open Testnet release. + +![TBV trust model: depositor, Vault Provider, Application Vault Keepers, Universal Challengers, and Security Council around the Bitcoin vault](/img/trustless-bitcoin-vault/confluence/start-here/safety-and-trust-assumptions/7.png) + +## The core property: trust is optional and removable + +The protocol's trust model has two principles that distinguish it from custodial or bridge-based alternatives: + +* **Trust is optional.** Every safety-critical role another party plays in the protocol can also be played by the depositor themselves, using the keys and artifacts held since vault creation. The participants are conveniences. The depositor never *has* to trust any of them. + +In the strongest form, a depositor can step in for every operational role in the protocol: + +* **Self-host their own Vault Provider.** From peg-in onward, a depositor can run their own Vault Provider node and bypass third-party providers entirely. The Vault Provider role is operational coordination (driving setup, generating proofs, broadcasting claim transactions on Bitcoin); nothing about it requires a third party. +* **Self-claim during redemption.** Using the WOTS keypair and claimer artifacts held since peg-in, the depositor can broadcast the Claim, Assert, and Payout transactions themselves via a command-line tool the protocol ships. No cooperation from any other participant is required. +* **Self-challenge a fraudulent claim.** Using the BABE artifacts received at peg-in, the depositor (or any party they delegate) can compose a `ChallengeAssert` and block a fraudulent claim — without depending on any Universal Challenger being honest or online. +* **Self-refund a stalled peg-in.** Via the Pre-PegIn refund timelock, the depositor can recover BTC unilaterally if activation never completes. + +There is no third party that the BTC holder *has to* trust. That is what makes the protocol trustless. + +## Application isolation + +A BTC vault is created for one specific application at peg-in and cannot be moved between applications. This means a bug or policy change in any single registered application affects only that application: the BTC stays in its Bitcoin-side script and the depositor's recovery paths (refund and self-claim) still work, regardless of what happens on the application side. + +## Non-custodial guarantees + +Three mechanisms keep BTC custody with the depositor at all times. + +* **Pre-signed exit paths.** Every release path is constructed and signed at vault creation, before any BTC moves. The depositor's signatures are explicitly required, along with the Application Vault Keepers' co-signatures and the Universal Challengers' attestations. After creation, no participant can single-handedly prevent a valid spend along those paths, and no participant can fabricate a new one. +* **On-chain refund timelocks.** The Pre-PegIn output includes a refund leaf with a timelock (`tRefund` = 3 days on Testnet). If activation does not complete within the configured window, the depositor can sign the refund path with the depositor key and recover BTC unilaterally. +* **Protocol-level fraud detection.** The depositor (or any Universal Challenger or Application Vault Keeper) can verify every claim against Ethereum state. A claim made without a valid `VaultRedeemable` event cannot defend itself against a challenge — the claimer's bond is forfeited and the BTC stays in the vault. + +No single party, including the Vault Provider, can unilaterally release a depositor's BTC. Every canonical spend requires either the depositor's signatures or the depositor's pre-committed authorization established at vault creation. + +## Where BTC can go: a small pre-agreed destination set + +The BTC held in a vault can only ever be released along the spending paths committed at vault creation. Those paths terminate at a small, pre-agreed set of destinations: + +* The depositor's own Bitcoin address — via the repayment path (the Vault Provider drives the claim, taking the commission), depositor self-claim, or the Pre-PegIn refund. +* The Bitcoin address of an arbitrageur (Application Vault Keeper) — on liquidation paths. + +This set is fixed when the vault is created and is enforced by Bitcoin's consensus rules through the Taproot script. Even in a catastrophic bug elsewhere in the system, BTC in an existing vault cannot leave this set: doing so would require a Bitcoin spend that was never signed and is not encoded in any leaf of the script. Bitcoin will not accept such a spend. + +As an additional security mechanism, a **Security Council** can block payouts in catastrophic-bug scenarios (such as a total failure of the zero-knowledge proof system) by broadcasting a `CouncilNoPayout` transaction. The Security Council can prevent BTC from being released to a fraudulent claimer, but cannot redirect BTC anywhere — its only on-chain power is to block. The Security Council keys are not part of the destination set above; they are signers for blocking, not recipients of BTC. + +## No rehypothecation + +The collateral cannot be transferred, rehypothecated, lent out, or repurposed by any participant. Each vault is a single Bitcoin output bound by its Taproot script at creation. The vaultBTC accounting token on Ethereum is restricted by the contracts that issue it: it is minted automatically when a vault is activated as collateral on a registered application, burned when the vault is withdrawn or liquidated, and is not freely transferable as a general-purpose asset. There is no protocol path along which a third party can route a depositor's BTC into a different position, an internal balance sheet, or an off-protocol product. + +## What each actor is trusted to do + +The protocol involves four actor types. None has custody of BTC. Each one performs a convenience that the depositor could otherwise perform independently — or, in the case of the Vault Provider, self-host. The full description of each actor's responsibilities is on [TBV Protocol actors](../technical-details/protocol-actors.mdx). + +### Vault Provider + +* **What it does as a convenience:** drives liveness during peg-in and peg-out, generates valid zero-knowledge proofs of redemption, broadcasts the claim and payout transactions on Bitcoin. +* **What the depositor can do instead:** + * **Self-host at peg-in.** The depositor can run their own Vault Provider node and bypass any third-party provider for the entire vault lifecycle. The Vault Provider role is operational coordination; nothing about it requires a third party. + * **Self-claim at redemption.** Using the WOTS keypair and claimer artifacts held since peg-in, the depositor can drive the Bitcoin claim themselves via a command-line tool the protocol ships. + + Either way, the Vault Provider is a convenience, not a required intermediary. +* **No custody:** a Vault Provider cannot construct any spend that was not committed at vault creation, and cannot release BTC outside the pre-signed paths. + +### Application Vault Keeper (AVK) + +* **What it does as a convenience:** liveness during peg-in setup, and acts as the arbitrageur of last resort during liquidation settlement on an application-by-application basis. AVKs are redundant within an application — only one of them needs to be operational at any given step. +* **What the depositor can do instead:** AVK co-signatures are needed at vault creation, but at redemption time the depositor's signatures alone are sufficient on the depositor self-claim path. +* **No custody:** as with the Vault Provider, no AVK spend can be assembled that was not committed at vault creation. + +### Universal Challenger + +* **What it does as a convenience:** watches every claim transaction across applications and broadcasts a `ChallengeAssert` if it detects a fraudulent proof. Universal Challengers are a redundant security countermeasure layered on top of the depositor's own ability to challenge. +* **What the depositor can do instead:** the depositor (or the depositor's Vault Provider acting on behalf of the depositor) can challenge a fraudulent claim themselves. The depositor receives a parallel `VaultClaimableBy` event and has the BABE artifacts needed to compose a ChallengeAssert. Universal Challengers are convenient because they are always online and they monitor every vault, but the property "a fraudulent claim can always be blocked" does not depend on any Universal Challenger being honest or online — it is the depositor's own ability to challenge that makes the protocol trustless. +* **Set composition:** the Universal Challenger set is a static, versioned registry. It is not planned to open up to permissionless participation. +* **Failure mode:** if every Universal Challenger, every Application Vault Keeper for a vault, *and* the depositor is offline through the assert timelock, the Security Council can intervene with `CouncilNoPayout` before payout completes. + +### Security Council + +* **What it does as a convenience:** signs emergency `CouncilNoPayout` transactions by quorum when the protocol cannot resolve a situation algorithmically — for example, a catastrophic failure in the zero-knowledge proof system. Also handles depositor-recovery escalation if the depositor loses their self-claim artifacts. +* **What removability means:** the Security Council is an early-life safety net. As the protocol matures, the council's quorum and key set are intended to be retired or replaced with an open challenger-and-keeper market. +* **No custody:** the council has no custody role. Its only on-chain power is to prevent a payout in cases that the standard mechanism cannot resolve. The council cannot direct BTC to any address. + +## Depositor recovery paths + +### Refund if peg-in does not complete + +The Pre-PegIn HTLC output has a refund leaf with a `tRefund` timelock (3 days on Testnet). If activation does not occur within the activation window (`pegInActivationTimeout`, ~48 hours), the vault enters the `Expired` state. The depositor can then sign the refund path with the depositor key and broadcast a refund transaction on Bitcoin to recover the BTC. The refund timelock is set such that `tRefund` falls after the normal activation window plus a safety margin, so it cannot trigger accidentally during a healthy peg-in. If the vault expired specifically because off-chain setup failed (i.e. `pegInAckTimeout` exceeded before Verified), the peg-in fee is also refunded. + +### Self-claim if the Vault Provider does not initiate the claim + +At peg-in, the depositor commits a Winternitz One-Time Signature (WOTS) public key on-chain and downloads claimer artifacts (transaction graph and BABE session data). The protocol generates depositor-as-claimer pre-signed transactions alongside the standard Vault-Provider-as-claimer transactions, and the PegIn transaction produces a small depositor claim output controlled solely by the depositor's key. When a vault is redeemable and the Vault Provider has not initiated the Bitcoin-side claim, the depositor runs a command-line tool the protocol ships with the WOTS keypair file and the artifacts as inputs; the tool broadcasts the Claim, Assert, and Payout transactions. Self-claim follows the same challenge period as a Vault-Provider-initiated claim and reaches the same payout address: the depositor's own. + +### Self-challenge if the Universal Challengers do not act + +If a fraudulent claim is posted against a depositor's vault and no Universal Challenger picks it up, the depositor (or any party they delegate, including their Vault Provider) can compose and broadcast a ChallengeAssert themselves using the BABE artifacts. This is the protocol's last line of defense before the Security Council backstop and is what makes the trust model independent of any specific Universal Challenger being honest. + +### Self-host the Vault Provider + +Before peg-in, a depositor can choose to run their own Vault Provider node and use it as the vault's provider. This removes any dependency on third-party Vault Provider services for the entire life of the vault — peg-in coordination, off-chain setup, ZK proof generation at peg-out, and claim broadcasting on Bitcoin are all performed by infrastructure the depositor controls. The protocol does not distinguish a self-hosted Vault Provider from a third-party one; the only requirements are on-chain registration and the standard ACK / signature flows. + +## Operational pause states + +The protocol supports two pause states for operational safety, both governed by the Security Council quorum: + +* **Soft pause.** Blocks new deposits, borrows, and withdrawals. Repay, liquidate, and Vault Swap operations remain available. +* **Full pause.** Blocks all on-chain state-changing actions on the Aave application surface. The depositor refund path on Bitcoin and the depositor WOTS self-claim are never blocked by a protocol pause, because they execute on Bitcoin using pre-signed transactions and the depositor's own keys. + +## Risk surface + +* **Smart-contract risk.** The Ethereum contracts (`BTCVaultRegistry`, `AaveAdapter`, the vaultBTC token, the Babylon Core Spoke, `CapPolicy`, `FeeEscrow`) are subject to standard smart-contract risk. The current Testnet is beta software and may change as issues are found. +* **Smart-contract upgradability and governance.** Several protocol contracts are upgradeable through governance. An upgrade can change protocol behavior and may also be required to follow Ethereum upgrades for compatibility. Mitigations: upgrades go through a TimelockController so changes are publicly visible before they take effect; existing vaults retain the parameter version active at their creation, which limits the scope of changes that can affect a live vault. +* **Oracle risk.** The liquidation health factor depends on a BTC/USD price oracle. Liquidation settlement and fairness payment additionally use a WBTC/USD oracle. A stale or manipulated price could trigger a liquidation at an incorrect price, or fail to trigger one when needed. +* **Bitcoin reorganization risk.** The peg-in confirmation depth and the timelocks on Pre-PegIn and Vault outputs are calibrated against expected Bitcoin reorg behavior. Deeper-than-expected reorgs would extend timing rather than enable theft. +* **ZK system soundness.** A bug in the SP1 proof system or its on-chain Groth16 verifier could in principle allow a fraudulent proof to pass verification. Mitigations: independent Universal Challenger replay using the BABE garbled circuit instances; the depositor's own self-challenge ability; Security Council intervention before the assert timelock expires. +* **BABE / BitVM3 construction.** A flaw in the BABE construction or in specific garbled circuit primitives could weaken fraud detection on Bitcoin. The protocol generates many candidate GC instances per claimer-challenger pair (307 on Testnet) and retains 6 after the cut-and-choose — multiple instances provide redundancy. Security Council intervention is the final backstop. +* **Ethereum light client correctness.** The on-Ethereum verification of Bitcoin-side vault state and the on-Bitcoin verification of Ethereum burn events both rely on the Ethereum execution and consensus layers being live and correct, and on the receipt-inclusion proof pipeline being implemented correctly. A bug in the light-client logic or a deep Ethereum consensus failure could cause a stuck or incorrect verification. Mitigations: standard Ethereum staking economic security; Universal Challenger replay; Security Council intervention. +* **Vault Provider unavailability.** Covered by the WOTS self-claim path, plus the option of self-hosting the Vault Provider from peg-in. A depositor never depends on a third-party Vault Provider to recover BTC, provided they have either self-hosted or backed up their WOTS file and claimer artifacts. +* **Universal Challenger collusion or downtime.** Even if every Universal Challenger fails to challenge a fraudulent claim within the assert timelock, the depositor can self-challenge using the BABE artifacts. If the depositor is also unable to act, the Security Council can broadcast `CouncilNoPayout`. +* **Security Council compromise.** The council can sign a `NoPayout` but cannot move funds. Compromise of the council reduces emergency-recovery capacity; it does not enable theft of BTC from any vault. +* **Vault Swap liquidity dependency.** Permissionless liquidations draw WBTC from the Aave Hub. If Hub WBTC liquidity or the Vault Swap allowance is insufficient, permissionless liquidations revert. Liquidations can still proceed via direct redemption by registered arbitrageurs, but the pool of available liquidators narrows. The protocol mitigates this with an amount-based cap on total BTC onboarded to the Aave application. + +## Trust set evolution: public testnet to mainnet + +On the current public testnet release, the Vault Provider, Application Vault Keepers (3 for the Aave application: RockX, Babylon 0, Babylon 1), and Universal Challengers (3 protocol-wide: Altlayer, Babylon 0, Babylon 1) are operated by the Babylon team and external partner organizations for testing purposes. The Security Council is a 3-of-5 multisig held by team-controlled keys. + +Mainnet will expand each set and gradually retire multi-sig safety nets as system stability allows: + +* Multiple independent Vault Providers competing on commission and reliability — plus the option for any depositor to self-host their own Vault Provider. +* Wider Application Vault Keeper set per application, including additional external operators. +* Universal Challenger set may add additional external operators over time; it is not planned to become permissionless. +* Security Council expanded with independent signers as a transitional measure; long-term path is to retire the council entirely once the protocol matures. + +## Public testnet caveats + +The current Testnet uses signet BTC, not mainnet BTC. Funds on signet have no economic value. The contracts and supporting services on Testnet are beta software and may change between releases. + +* Protocol contracts may be redeployed or upgraded during the Testnet phase. Existing test positions may be reset between deployments. Vault state, balances, and addresses are not guaranteed to persist across upgrades. +* The test app, the Vault Provider, and other supporting services operate on a best-effort liveness basis. Brief outages are expected. +* Per-application and per-address BTC caps are conservatively set on Testnet. These limits will grow as the protocol matures. +* Bugs and unexpected behavior should be reported through the channels listed on [Community & support](../reference/community-and-support.mdx). diff --git a/docs/trustless-bitcoin-vault/start-here/what-is-tbv.mdx b/docs/trustless-bitcoin-vault/start-here/what-is-tbv.mdx index ad02372c..3fda688f 100644 --- a/docs/trustless-bitcoin-vault/start-here/what-is-tbv.mdx +++ b/docs/trustless-bitcoin-vault/start-here/what-is-tbv.mdx @@ -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 diff --git a/docs/trustless-bitcoin-vault/technical-details/_category_.json b/docs/trustless-bitcoin-vault/technical-details/_category_.json new file mode 100644 index 00000000..76b3dc37 --- /dev/null +++ b/docs/trustless-bitcoin-vault/technical-details/_category_.json @@ -0,0 +1,10 @@ +{ + "label": "Technical Details", + "position": 5, + "collapsible": true, + "collapsed": true, + "link": { + "type": "generated-index", + "description": "Optional deeper reading: protocol architecture, actors, and the Aave v4 application layer. Not required to use the product on Testnet." + } +} diff --git a/docs/trustless-bitcoin-vault/technical-details/aave-v4-integration.mdx b/docs/trustless-bitcoin-vault/technical-details/aave-v4-integration.mdx new file mode 100644 index 00000000..bb57acfa --- /dev/null +++ b/docs/trustless-bitcoin-vault/technical-details/aave-v4-integration.mdx @@ -0,0 +1,126 @@ +--- +title: Aave v4 integration +sidebar_position: 3 +--- + +# Aave v4 integration + +This page describes **the Aave v4 integration** — the first DeFi application registered with the TBV protocol. TBV itself is application-agnostic and lives one layer below this: it owns vault creation, redemption, and security. Aave v4 is one specific consumer of vaultBTC. For the underlying protocol, see [How it works](../start-here/how-it-works.mdx) and [Protocol architecture](./protocol-architecture.mdx). For the layered overview, see [What is TBV?](../start-here/what-is-tbv.mdx) → "Two layers". + +The Trustless Bitcoin Vault (TBV) protocol is application-agnostic at the registry level. Aave v4 is the first DeFi integration, plugging into the ApplicationRegistry via the AaveAdapter contract. The collateral asset on this integration is vaultBTC, the accounting token described later on this page. In the Aave v4 integration, the Application Vault Keepers act as arbitrageurs. + +## Architecture + +Aave v4 organizes lending into a hub-and-spoke architecture: + +* **Aave v4 Hub.** Central liquidity contract. Lenders supply borrowable assets (USDC, USDT, WBTC) to the Hub and earn interest. The Hub holds the aggregate liquidity for each asset and manages interest rate calculations. +* **Babylon Core Spoke.** A dedicated, isolated lending market for vaultBTC collateral. Has its own risk parameters independent from other spokes. Draws borrowable assets from the Aave v4 Hub when a depositor borrows; restores them to the Hub on repay. +* **AaveAdapter.** The user-facing entry point. Coordinates adding vaults as collateral, borrowing, repaying, withdrawing, and triggering redemption. Calls into the depositor's position proxy and through it to the Babylon Core Spoke. +* **AaveAdapterPositionProxy.** Per-depositor proxy contract that holds the depositor's isolated borrowing position. Deployed deterministically on first deposit. One proxy per depositor address; multiple vaults can back the single position held by that proxy. The proxy isolates each depositor's borrowing position from every other depositor's — a bug or attack affecting one position cannot bleed into another. + +A borrow flows through the layers: depositor, AaveAdapter, position proxy, Babylon Core Spoke, Aave v4 Hub. The Hub releases the borrowed tokens; they travel back the same path to the depositor. Repays follow the inverse direction. + +Two supporting contracts handle registration and read access: + +* **AaveAdapterConfig.** Manages LLP registration (BTCVaultSwap and any future LLPs), position-size parameters, and borrow-delegation resolver registration. Gated by the protocol's TimelockController. +* **AaveAdapterLens.** Read-only contract for aggregated state queries (positions, vaults, reserves). + +## vaultBTC + +vaultBTC is an ERC-20 token used as the collateral asset on the Babylon Core Spoke. Key properties: + +* **8 decimals,** matching Bitcoin's satoshi precision. 1 vaultBTC = 1 BTC = 100,000,000 satoshis. +* **Mint and burn only.** vaultBTC is minted only when a vault is added as collateral and burned only when the vault is withdrawn or liquidated. No other minting paths exist. +* **Just-in-time supply.** Total vaultBTC in circulation equals the BTC actively backing borrowing positions. A vault that exists but has not been added as collateral has no vaultBTC associated. +* **Transfer whitelist.** vaultBTC can only move between authorized protocol contracts: the Babylon Core Spoke, the Aave v4 Hub, the AaveAdapter, and the depositor's position proxy. Any transfer to an arbitrary address reverts. There is no vaultBTC market and no secondary trading. +* **Pricing.** The Babylon Core Spoke uses a Chainlink BTC/USD oracle to determine the USD value of vaultBTC for health factor calculations. Since each unit represents one satoshi of real Bitcoin, the price feed tracks BTC directly. Liquidation settlement and fairness payment additionally use a Chainlink WBTC/USD oracle (WBTC trades very close to but slightly below BTC parity). + +The accounting role of vaultBTC means it never exists in user-controlled wallets. Its mint, burn, and transfer paths are all initiated through the AaveAdapter, ensuring that the supply invariant (total vaultBTC equals total locked BTC in active positions) holds at all times. + +## Borrowable assets + +Reserves available on the Babylon Core Spoke at Testnet: + +* USDC +* USDT +* WBTC + +Each asset has per-asset Hub-level configuration: + +* **Add cap:** maximum amount that can be supplied to the Hub. +* **Draw cap:** maximum amount that can be borrowed from the Hub by all spokes combined (10,000,000 units per asset on Testnet). +* **Hub liquidity fee:** Aave's reserve factor charged on accrued interest (set per asset at the Hub level). +* **Interest rate strategy:** the contract determining borrowing rates as a function of utilization (kinked model — see [Protocol parameters](../testnet-info/protocol-parameters.mdx) for per-asset values). + +Each asset accrues interest continuously based on utilization (ratio of borrows to supply). Higher utilization yields higher rates, incentivizing repayment and additional supply. + +The depositor's debt for a given asset is tracked using two share components on the position proxy: drawn shares (principal) and premium shares (interest). As interest accrues, the share-to-value ratio increases, so the same shares correspond to a larger debt over time. To check current debt, query `getUserTotalDebt(proxyAddress, reserveId)` on the Babylon Core Spoke. + +Current numeric values for Testnet (caps and rates) are listed on the [Protocol parameters](../testnet-info/protocol-parameters.mdx) page. + +## Operations + +Operations on the AaveAdapter, in lifecycle order: + +* `activateVault(vaultId, ...)`. Called by `BTCVaultRegistry.activateVaultWithSecret`: deploys per-depositor position proxy (if first vault), mints vaultBTC, supplies as collateral. The vault is automatically added to the depositor's position on activation. +* `borrowFromCorePosition(uint256 debtReserveId, uint256 amount, address receiver)`. Borrows the specified amount of the chosen asset against the position. Validates that the resulting health factor stays above 1.0. +* `repayToCorePosition(address borrower, uint256 debtReserveId, uint256 amount)`. Repays debt. Anyone may repay another depositor's debt. +* `withdrawCollaterals(bytes32[] vaultsToWithdraw)`. Removes the listed vaults from the position and initiates their redemption. Validates that the resulting health factor stays above 1.0 if any debt remains. +* `reorderVaults(uint256[] newOrder)`. Reorders the vaults in the position. The new order determines liquidation seizure order. +* `liquidate(address borrower, bytes32 directBtcRedeemKey, uint256[] amounts, uint256[] priorityOrder)`. Direct-redemption liquidation path — permissioned. Requires the liquidator to be a registered arbitrageur (Application Vault Keeper) with a Bitcoin redeem key. +* `liquidateWithLLP(address borrower, address llp, ...)`. Permissionless LLP-routed liquidation path. Triggered when the position's health factor drops below 1.0. The seized vault is escrowed in the LLP (BTCVaultSwap by default) and the liquidator receives WBTC immediately. + +The AaveAdapterLens contract exposes corresponding read-only queries: position state, vault state per vault, reserve state per asset. + +## Liquidation model and settlement + +A position becomes liquidatable when its health factor drops below 1.0. Two liquidation paths exist on the AaveAdapter: + +* **Direct-redemption (`liquidate`) — permissioned.** The liquidator is a registered arbitrageur (Application Vault Keeper). They repay the necessary debt and redeem the seized vault directly to a Bitcoin redeem key. +* **LLP-routed (`liquidateWithLLP`) — permissionless.** Any Ethereum address can trigger. The liquidator repays the debt and receives WBTC immediately from the LLP; the seized vault enters LLP escrow for later acquisition by an arbitrageur. BTCVaultSwap is the default LLP. + +### Full-vault constraint + +UTXOs are indivisible: a Bitcoin output cannot be partially spent. The protocol therefore seizes vaults whole, never fractionally. A vault's BTC amount cannot be split between the liquidator and the depositor as part of the same liquidation. + +### Partial-position support + +A position holds one or more vaults. When liquidation is triggered, the protocol walks the ordered vault list (prefix walk) and seizes the minimum subset needed to restore the health factor to the target health factor (1.24 on Testnet). Vaults at the front of the list are seized first. + +* If a small subset of vaults is enough to restore the health factor, the rest remain in the depositor's position. This is partial-position liquidation. +* If the position is severely underwater or contains only one vault, all of it is seized. The position closes. + +The depositor controls the vault order. The recommended pattern is two vaults: a sacrificial vault at the front (sized to cover the expected seizure target) and a protected vault later (kept if possible). The relative sizes depend on the target health factor — at Testnet THF = 1.24, the sacrificial vault is the larger of the two. The app computes the optimal split dynamically. + +### Fairness mechanism + +Because vault granularity may overshoot what a perfectly divisible liquidation would seize, the over-seizure surplus is returned to the depositor: + +* **Fairness payment** is paid to the depositor in WBTC (provided by the liquidator on full-position liquidation) when the surplus exceeds remaining debt. The over-seizure value is not paid at the raw BTC price — it is discounted using the ratio of debt liquidated to collateral liquidated. For example, if Aave cleared $24,000 of debt for $25,000 of seized collateral, each dollar of seized collateral is valued at ~$0.96 for fairness purposes. This prevents the depositor from receiving more fairness value than the liquidation economics justify. +* **Fairness debt repay** reduces the depositor's remaining debt when the surplus is less than remaining debt. No WBTC is paid out; the depositor's debt position shrinks by the surplus amount. + +The fairness mechanism is what distinguishes this protocol's liquidation from a naive full-vault model: the depositor is not punished for the indivisibility of UTXOs. Note that WBTC trades very close to but slightly below BTC parity (~0.9975) — fairness payments reflect the WBTC/USD oracle. + +### LLP framework + +Permissionless liquidation on Ethereum, combined with multi-day BTC settlement on Bitcoin, requires a liquidity bridge. The Liquidation Liquidity Provider (LLP) framework solves this: + +* Liquidators receive instant WBTC liquidity from an LLP when seizing a vault via `liquidateWithLLP`. +* The LLP escrows the seized vault. +* A registered arbitrageur (Application Vault Keeper) later acquires the escrowed vault for WBTC and finalizes the BTC redemption on Bitcoin. + +The WBTC liquidity comes from the WBTC reserve on the Aave v4 Hub. When a liquidation occurs, the LLP draws WBTC from that reserve, pays the liquidator, and later replenishes the reserve when an arbitrageur acquires the escrowed vault. + +Multiple LLPs can register through `AaveAdapterConfig.registerLLP(address llp)`, gated by the TimelockController. The depositor's fairness settlement is paid through the LLP that handles their liquidation. + +### BTCVaultSwap (default LLP) + +The first registered LLP is BTCVaultSwap. It is registered as its own Aave Hub spoke for WBTC liquidity, distinct from the Babylon Core Spoke. Its flow: + +1. Liquidator calls `swapVaultForWbtc(vaultId)` after liquidation. +2. The vault enters BTCVaultSwap escrow. +3. The liquidator receives WBTC immediately, drawn from the Aave v4 Hub's WBTC reserve. +4. A registered arbitrageur monitors escrowed vaults. They acquire one by calling `swapWbtcForVault(vaultId, maxWbtcIn)`, paying the Hub debt (principal + accrued interest). Acquisition is first-come-first-served on Ethereum — the first successful `swapWbtcForVault` call wins the vault. +5. The arbitrageur acquires vault ownership. They then initiate the standard peg-out flow on Bitcoin: a ZK proof of the burn event, the claim transaction, the challenge period, and the payout. + +Hub interest accrues on escrowed vaults over time. If interest erodes the arbitrageur's profit margin, the vault becomes unprofitable to purchase. Anyone can top up the accrued interest via `repayVaultInterest`, extending the profitable purchase window. diff --git a/docs/trustless-bitcoin-vault/technical-details/protocol-actors.mdx b/docs/trustless-bitcoin-vault/technical-details/protocol-actors.mdx new file mode 100644 index 00000000..d70c1f77 --- /dev/null +++ b/docs/trustless-bitcoin-vault/technical-details/protocol-actors.mdx @@ -0,0 +1,131 @@ +--- +title: Protocol actors +sidebar_position: 2 +--- + +# TBV Protocol actors + +The actors described below are conveniences. Every safety-critical action they perform can also be performed by the depositor independently, using artifacts and keys held since vault creation. Trust is optional and removable — see [Safety & trust assumptions](../start-here/safety-and-trust-assumptions.mdx) for the full framing. + +The [Trustless Bitcoin Vault (TBV)](../start-here/what-is-tbv.mdx) protocol involves four actor types, each with a distinct operational role. None of them has custody of BTC, and none of them is a required intermediary — the depositor can step in for any of them at any time. This page describes what each actor does at the protocol level. + +## Who runs these actors today + +On the current Beta Testnet release, all four actor types are operated by Babylon and a small set of partner organizations: + +* **Vault Provider:** 1 provider operated by Babylon at launch. Additional providers can register over time. +* **Application Vault Keepers (Aave application):** 3 operators (RockX, Babylon 0, Babylon 1). +* **Universal Challengers:** 3 challengers protocol-wide, one operated by an external infrastructure partner and two by Babylon. +* **Security Council:** 5 BTC keys with a 3-of-5 quorum, held by Babylon at Testnet. + +The Testnet configuration is intentionally conservative — small partner sets to allow tight operational coordination during beta. Mainnet will widen each set, with multiple independent Vault Providers, expanded Application Vault Keeper and Universal Challenger registries, and an independent-signer Security Council. The Security Council multi-sig is a transitional safety net; it can be retired entirely as the protocol matures. + +## Vault Provider + +The Vault Provider coordinates the lifecycle of a vault. It is the party that drives the peg-in setup forward, posts the data the protocol needs on-chain, and generates the zero-knowledge proofs that gate redemption on Bitcoin. + +### What the Vault Provider does + +* **Peg-in coordination.** When a depositor submits a vault creation request, the Vault Provider detects the on-chain event and constructs the pre-signed transaction graph in concert with the Vault Keepers and Universal Challengers committed to that vault. +* **PegIn input signature collection and posting.** The Vault Provider collects the PegIn input signatures from every party and posts them on-chain in batched form via `submitPeginInputSignatureBatch()`. This provides data availability: even if the Vault Provider later goes offline, the signatures needed to construct and broadcast the PegIn transaction are recoverable from Ethereum. +* **ACK submission.** The Vault Provider collects acknowledgments from every participant and submits them on-chain. The vault transitions from `Pending` to `Verified` once the contract has accepted the required ACKs. ACK submission requires verification that the Pre-PegIn transaction is confirmed to at least the configured depth on Bitcoin (12 confirmations on signet; 6 on mainnet). +* **PegIn transaction broadcast.** After the depositor reveals the activation secret on Ethereum, the Vault Provider constructs the full PegIn witness using the collected signatures and the revealed secret, and broadcasts the PegIn transaction on Bitcoin. The vault becomes `Active`. +* **ZK proof generation.** When a vault is redeemed, the Vault Provider generates an aggregated SP1 proof of the corresponding Ethereum burn event. Generation runs on an SP1 prover (locally or via an external prover service), typically on GPU hardware (5-10 minutes per vault). The proof is compressed to a Groth16 form that fits inside a Bitcoin Taproot script and is verified through BitVM3-style garbled circuits. +* **Bitcoin claim management.** The Vault Provider broadcasts the Claim and Payout transactions on Bitcoin during the redemption process and monitors for any challenge. + +### What the depositor can do instead + +If the Vault Provider becomes unresponsive, the depositor can drive the Bitcoin claim themselves using the WOTS keypair and claimer artifacts held since peg-in, via a command-line tool the protocol ships. The Vault Provider is a convenience, not a required intermediary. + +### Commission + +Each Vault Provider sets its own commission, taken in BTC at peg-out from the redemption payout, at or above a protocol-enforced floor (`minVpCommissionBps`, currently 1% on Testnet). The commission rate is **embedded in the pre-signed Payout transactions at vault creation** — the depositor signs off on the exact amount before any BTC moves, and the rate cannot change for that vault. + +### Registration + +Vault Providers register on-chain by submitting an Ethereum address, a Bitcoin x-only public key, and a BTC Proof of Possession (a BIP-322 signature proving control of the Bitcoin key). A VP registers for one specific application; the same VP cannot serve vaults across multiple applications without separate registrations. + +## What is a Vault Keeper? + +Vault Keeper is the umbrella term covering application-scoped Vault Keepers and protocol-wide Universal Challengers. The Aave v4 integration uses **Application Vault Keepers (AVKs)** as its application-specific operators and arbitrageurs. Universal Challengers are protocol-level monitors that watch claims across applications. + +## Application Vault Keeper (AVK) + +Application Vault Keepers are application-scoped participants who serve as the economic backstop for vault security. In the context of the [Aave v4 integration](./aave-v4-integration.mdx), the AVKs act as **arbitrageurs**. + +### What the AVK does + +* **Transaction graph participation.** During vault creation, each AVK constructs its own transaction graph and cross-signs with the Vault Provider. This ensures multiple independent parties hold the pre-signed transactions needed for every vault outcome. The graphs include Winternitz One-Time Signature (WOTS) commitments used by the challenge mechanism. +* **PegIn input signing.** Each AVK signs the Pre-PegIn HTLC spend as part of the off-chain protocol. The signatures are required to construct the final PegIn witness. +* **ACK submission.** Each AVK submits an on-chain acknowledgment confirming graph setup, signature collection, and verification of the Pre-PegIn confirmation depth. +* **Arbitrage in liquidation settlement.** The protocol routes liquidation settlement through a Liquidation Liquidity Provider (LLP); `BTCVaultSwap` is the default LLP. Liquidators on the permissionless `liquidateWithLLP` path swap seized vaults for instant WBTC liquidity via BTCVaultSwap; the seized vault enters escrow until an arbitrageur acquires it (via `swapWbtcForVault`, paying the Hub debt plus a commission) and finalizes the BTC redemption on Bitcoin. The arbitrageur role is permissioned — only registered Application Vault Keepers can acquire escrowed vaults, because they must have pre-signed the vault's transaction graph at creation. +* **Challenge participation.** As holders of pre-signed transaction graphs, AVKs can participate in the challenge mechanism if they detect a fraudulent claim against a vault they co-signed. + +### What the depositor can do instead + +AVK co-signatures are needed at vault creation, but at redemption time the depositor's signatures alone are sufficient on the depositor self-claim path. + +### Registration + +AVKs are registered per application through `BTCVaultRegistry`. Each application maintains a versioned set of AVK key pairs (Ethereum + Bitcoin). A set version is immutable once active: rotation produces a new version that applies only to vaults created after the rotation. Vaults already in flight retain the set version live at their creation. + +## Universal Challenger + +Universal Challengers are protocol-level fraud monitors. Their role is to detect and challenge fraudulent proof submissions during the vault redemption process, regardless of which application a vault belongs to. + +### What the Universal Challenger does + +* **Fraud monitoring.** The Universal Challenger watches every Claim transaction posted on Bitcoin and verifies the associated proof against Ethereum state. A claim that lacks a matching `VaultRedeemable` event on Ethereum cannot be backed by a valid proof. +* **Challenge execution.** When fraud is detected, the Universal Challenger broadcasts a `ChallengeAssert` transaction (split as `ChallengeAssertX` and `ChallengeAssertY` to fit Bitcoin script size limits) within the assert timelock (`timelockAssert` = 432 BTC blocks ≈ 3 days on Testnet). The challenge transactions verify the claimer's WOTS signatures against the BABE garbled circuit instances established at peg-in. If the claim cannot be defended, the challenger broadcasts `NoPayout` after the disprove timelock (`timelockChallengeAssert` ≈ 18 hours) expires and the claimer's bond is forfeited. +* **PegIn input signing.** Universal Challengers sign the Pre-PegIn HTLC spend during peg-in. Each signature is bound to that vault's specific Pre-PegIn HTLC output, which prevents cross-vault signature replay. +* **Taproot commitment.** Universal Challenger Bitcoin public keys are committed into every vault's Taproot script tree. This commitment is what gives the challenger the cryptographic standing to dispute a claim on Bitcoin. + +### What the depositor can do instead + +If a fraudulent claim is posted and no Universal Challenger picks it up, the depositor (or any party they delegate, including their Vault Provider) can compose and broadcast a `ChallengeAssert` themselves using the BABE artifacts received at peg-in. Universal Challengers are convenient because they are always online and they monitor every vault, but the property "a fraudulent claim can always be blocked" does not depend on any Universal Challenger being honest or online — it is the depositor's own ability to challenge that makes the protocol trustless. + +### Set composition and registration + +Universal Challengers are registered at the protocol level rather than per application, through `ProtocolParams`. They are stored as a static, versioned array of Ethereum and Bitcoin key pairs. Each vault records the Universal Challenger set version active at its creation; that set is fixed for the vault's lifetime. The set may add additional external operators over time, but it is not planned to become permissionless. + +## Security Council + +The Security Council is a quorum of off-chain signers whose Bitcoin public keys are committed in the protocol's versioned offchain parameters. The council serves as the emergency backstop for scenarios the standard mechanism cannot resolve — including when the depositor themselves cannot act. On the current Testnet, the council has 5 keys with a 3-of-5 quorum. It is a transitional safety net intended to be retired as the protocol matures. + +### What the Security Council does + +* **Emergency intervention.** If the standard challenge mechanism fails to prevent a fraudulent payout, or if a critical protocol issue requires immediate action, the council can act. +* **CouncilNoPayout transactions.** The council's on-chain power is to produce a `CouncilNoPayout` transaction by quorum, blocking payout on a specific vault. The council cannot direct BTC to any address; it can only prevent release. +* **Operational pause states.** The council can place the protocol into a soft pause (blocking new peg-ins and new borrows) or a full pause (blocking all state-changing actions except depositor recovery paths). The depositor's refund path and WOTS self-claim are never affected by a protocol pause, because they execute on Bitcoin using pre-signed transactions and the depositor's own keys. See [Safety & trust assumptions](../start-here/safety-and-trust-assumptions.mdx) for the pause-state matrix. +* **Depositor-recovery escalation.** If a depositor loses both their WOTS keypair file and their claimer artifacts (the two inputs to self-claim) and the Vault Provider is also unresponsive, the Security Council can authorize recovery through the multi-sig path. + +### Configuration + +Council keys and quorum thresholds are set through `ProtocolParams` as versioned offchain parameters. Changes create a new parameter version and apply only to newly created vaults. The Security Council is not involved in normal protocol operation. + +## Summary of responsibilities + +| Actor | Registered | Versioned | Main responsibility | Testnet count | +| --- | --- | --- | --- | --- | +| Vault Provider | Per application | Per-vault immutable (each vault picks one VP for life) | Peg-in coordination, ZK proof generation, claim and payout broadcast, commission | 1 at launch | +| Application Vault Keeper | Per application | Yes (versioned set) | Transaction graph co-signing, PegIn input signatures, liquidation arbitrage, challenge participation | 3 for the Aave app | +| Universal Challenger | Protocol-level (via `ProtocolParams`) | Yes (versioned set) | Fraud monitoring across all applications, challenge execution | 3 protocol-wide | +| Security Council | Protocol-level (off-chain params) | Yes (versioned set) | Emergency intervention and operational pauses; retirable as protocol matures | 5 keys, 3-of-5 quorum | + +## Bonds and economic incentives + +Several actors post bonds that get forfeited on misbehavior — the protocol's standing economic incentive to behave honestly. + +* **Claimer bond:** posted by whoever broadcasts the Claim transaction (Vault Provider in the standard path, depositor in self-claim, liquidator in the direct-redemption path). Forfeited if a `ChallengeAssert` succeeds against the claim. +* **Challenger bond:** posted by whoever broadcasts the `ChallengeAssert`. Forfeited if the claimer broadcasts `WronglyChallenged` proving the challenge was incorrect. + +Successful challenges and successful disproofs each award the forfeited bond to the winning party. This funds Universal Challenger monitoring (a single honest challenger can earn by spotting fraud) and disincentivizes spurious challenges. + +## Permissioned and permissionless participation + +The protocol is designed to progressively decentralize participation. Two protocol surfaces have permissionless elements: + +* **Fraud monitoring.** Anyone can monitor for fraudulent claims by running a watcher and checking Ethereum-side events. Broadcasting an on-chain `ChallengeAssert` requires being a registered Universal Challenger in the current `ProtocolParams` set; the registry is governed at the protocol level. The Testnet roadmap includes progressive opening of the challenger set so additional operators can earn challenger rewards by successfully disputing invalid claims. +* **Liquidation triggering.** Calling `liquidateWithLLP` on the Ethereum side is permissionless: any address can call the function once a position's health factor drops below 1.0. The direct-redemption variant `liquidate` requires being a registered arbitrageur (with a Bitcoin redeem key). Permissionless liquidation ensures positions are liquidated promptly regardless of which dedicated parties are running. + +For the underlying protocol mechanics that connect these actors, see [Protocol architecture](./protocol-architecture.mdx). For definitions of the protocol-specific terms used throughout this page, see [Glossary](../reference/glossary.mdx). diff --git a/docs/trustless-bitcoin-vault/technical-details/protocol-architecture.mdx b/docs/trustless-bitcoin-vault/technical-details/protocol-architecture.mdx new file mode 100644 index 00000000..c1269a4e --- /dev/null +++ b/docs/trustless-bitcoin-vault/technical-details/protocol-architecture.mdx @@ -0,0 +1,157 @@ +--- +title: Protocol architecture +sidebar_position: 1 +--- + +# Protocol architecture + +The components and participants below are conveniences. Every safety-critical action they perform can also be performed by the depositor independently, using artifacts and keys held since vault creation. Trust is optional and removable — see [Safety & trust assumptions](../start-here/safety-and-trust-assumptions.mdx) for the full framing. + +The Trustless Bitcoin Vault (TBV) protocol spans three layers: Bitcoin-side scripts and transactions, Ethereum-side contracts, and off-chain participant software. The first two are protocol-defined and application-agnostic. Specific DeFi integrations such as Aave v4 plug into the Ethereum-side coordination contract. The on-Ethereum accounting collateral token used by the Aave v4 integration is vaultBTC. + +![Protocol architecture: Bitcoin vaults, trustless protocol participants, Babylon protocol contracts, and Aave v4 integration](/img/trustless-bitcoin-vault/confluence/technical-details/protocol-architecture/10.png) + +## System components + +### On Bitcoin + +Each vault's BTC sits in a Taproot output with multiple spending leaves covering the legitimate outcomes: repayment, liquidation, depositor refund (if peg-in stalls), and challenge response. + +Before BTC reaches the vault output, it sits briefly in a Pre-PegIn HTLC output that gates activation on the depositor revealing a hashlock secret on Ethereum. The Pre-PegIn transaction also includes a small CPFP anchor output (BIP-86 keypath) for fee bumping if Bitcoin mempool fees spike during the confirmation wait. The subsequent PegIn transaction produces two outputs: the main vault Taproot output, and a small depositor claim output controlled solely by the depositor — used as the structural anchor for the depositor self-claim path. + +Around the vault output, the protocol maintains a pre-signed transaction graph: every legitimate spend path is constructed and signed by all required participants at vault creation. After creation, no party can fabricate a new spend; only the pre-signed transactions can move BTC. + +### On Ethereum + +The core Ethereum contracts coordinate vault state and integrations: + +* **BTCVaultRegistry:** per-vault state (Pending/Verified/Active/Redeemed/Expired), the depositor's hashlock, and the depositor's WOTS commitment. Emits events for off-chain participants. +* **BTCVaultsMetadataRegistry:** publishes Vault Provider RPC endpoints for peer discovery. +* **ProtocolParams:** versioned protocol parameters (timelocks, confirmation depth, actor sets, Security Council keys). +* **ApplicationRegistry:** lists DeFi applications approved to receive vaults. Currently only the AaveAdapter is registered. +* **CapPolicy:** per-application and per-address BTC exposure caps, enforced at vault activation. +* **FeeEscrow:** collects the multi-component peg-in fee and distributes it to the Vault Provider, Universal Challengers, and Application Vault Keepers. +* **AaveAdapter:** user-facing entry point for the Aave v4 integration. +* **BTCVaultSwap:** default Liquidation Liquidity Provider for the Aave v4 integration. Registered as its own Aave Hub spoke for WBTC liquidity, distinct from the Babylon Core Spoke for vaultBTC collateral. + +The protocol is application-agnostic at the registry level. Additional applications can register subject to governance approval. + +### Off-chain + +Off-chain refers to participant software and protocols, not centralized infrastructure. Three categories: + +* **Protocols:** the BABE cut-and-choose protocol establishes garbled circuit instances between claimer-challenger pairs at vault creation. Signature exchange among participants assembles the transaction graph. The SP1 zero-knowledge proof pipeline (run by an SP1 prover, locally or via an external prover service, on GPU hardware) generates the proofs needed for peg-out claims. +* **Participants:** the Depositor, the Vault Provider, Vault Keepers, and Universal Challengers each run vault management software. The Security Council holds emergency multi-sig keys (3 of 5 quorum on Testnet). Per-actor responsibilities are on [TBV Protocol actors](./protocol-actors.mdx). +* **Storage:** Vault Keepers store garbled circuit artifacts needed for fraud detection. The depositor also receives a copy of their own claimer artifacts plus a WOTS keypair file, both required for the self-claim fallback. + +## Vault lifecycle and states + +A vault occupies one of five states stored in the BTCVaultRegistry: Pending, Verified, Active, Redeemed, or Expired. + +State transitions: + +* **Pending to Verified.** All required acknowledgments collected via on-chain calls. The Pre-PegIn transaction is confirmed to the required depth on Bitcoin. +* **Pending or Verified to Expired.** One of two distinct timeouts expires: `pegInAckTimeout` (~24 hours) if off-chain setup doesn't complete and acknowledgments aren't collected; or `pegInActivationTimeout` (~48 hours from creation) if the depositor never reveals the activation secret for an already-Verified vault. +* **Verified to Active.** The depositor calls `activateVaultWithSecret(vaultId, s, activationMetadata)` on the BTCVaultRegistry. The contract verifies `SHA256(s) == hashlock`. On success, the vault transitions to Active and the protocol uses the secret to assemble the final PegIn witness. +* **Active to Redeemed.** Triggered by depositor exit (`withdrawCollaterals`), application liquidation (`liquidate` or `liquidateWithLLP`), or a direct redemption call. The vault transfers ownership to the claimer, the corresponding vaultBTC is burned (if the vault was in use), and a VaultClaimableBy event is emitted for both the Vault Provider and the depositor. + +Once a vault is Redeemed, the BTC enters the redemption flow on Bitcoin. The on-Ethereum state is terminal. + +When a vault expires, the Pre-PegIn HTLC output remains spendable via the refund leaf after the `T_refund` Bitcoin-side timelock (3 days on Testnet). The depositor recovers the BTC unilaterally by signing the refund spend. `T_refund` is set such that it occurs after the normal activation window plus a safety margin, ensuring the depositor cannot accidentally refund during the normal activation window. + +## Peg-in mechanism + +Peg-in registers a vault on Ethereum and locks BTC on Bitcoin. The flow runs through 12 stages organized into four phases. Total latency to Active is approximately **two hours on signet**, dominated by the wait for Bitcoin confirmations. + +### Phase 1: initiation (stages 1-2) + +During this phase, the depositor: (a) generates a 32-byte secret `s` and the hashlock `h = SHA256(s)`; (b) broadcasts the Pre-PegIn Bitcoin transaction, which locks the BTC into the HTLC Taproot address committed to the hashlock; (c) submits the peg-in request to the BTCVaultRegistry via `submitPeginRequest`, including the depositor's Ethereum address, Bitcoin public key, BIP-322 proof of Bitcoin key possession, the Pre-PegIn and PegIn transaction structures, the chosen Vault Provider, and the WOTS public key hash commitment. + +The app may broadcast a batched Pre-PegIn with up to 10 HTLC outputs (one per vault) for multi-vault peg-ins; this saves on Bitcoin fees and ensures atomic creation. + +### Phase 2: cryptographic setup (stages 3-5) + +While confirmations accumulate on Bitcoin: + +* **Stage 3 (depositor authentication):** the depositor authenticates to the Vault Provider using a challenge-response anchor (or BIP-322 fallback). A CBOR Web Token is issued for the peg-in session. +* **Stage 4 (WOTS keypair setup):** the depositor generates a Winternitz One-Time Signature (WOTS) keypair. The public key hash is committed in the vault's on-chain record. WOTS keeps the ChallengeAssert transaction size under 10 kvB. +* **Stage 5 (BABE setup):** the Vault Provider and Vault Keepers run the BABE cut-and-choose protocol. They generate 307 candidate garbled circuit instances per claimer-challenger pair, of which 6 are retained for dispute resolution. The remaining 301 are revealed to verify honest construction — that is the cut-and-choose's security guarantee. + +### Phase 3: signatures and acknowledgments (stages 6-10) + +* **Stage 6 (transaction graph creation):** participants construct and pre-sign every spend path: Claim, Assert, ChallengeAssertX/Y, Payout, NoProof, NoPayout. Each also signs the PegIn input (the spend of the Pre-PegIn HTLC). +* **Stage 7 (PegIn signatures data availability):** the Vault Provider posts collected PegIn input signatures on-chain via `submitPeginInputSignatureBatch()`. This ensures signatures remain available even if the Vault Provider goes offline. +* **Stage 8 (depositor payout signatures):** the depositor signs the payout transactions (Schnorr signatures over Taproot script-path spending) and returns them to the Vault Provider. +* **Stage 9 (acknowledgment collection):** each participant signs an on-chain acknowledgment. Once all are collected, the vault transitions to Verified. If this doesn't happen before `pegInAckTimeout` (~24 hours), the vault expires and the peg-in fee is refunded. +* **Stage 10 (artifact distribution):** garbled circuit artifacts are exchanged out-of-band. The depositor receives their own copy of the artifacts plus their WOTS keypair file — these are required for the self-claim fallback if the Vault Provider ever becomes unresponsive during redemption. + +### Phase 4: activation (stages 11-12) + +* **Stage 11 (secret reveal and vault activation):** the depositor calls `activateVaultWithSecret(vaultId, s, activationMetadata)` on the BTCVaultRegistry. The contract verifies the hashlock and the activation timeout window (`pegInActivationTimeout`, ~48 hours from creation), transitions the vault to Active, and notifies the registered application. For the Aave v4 integration, this deploys the depositor's position proxy (if first vault), mints vaultBTC for the vault's BTC amount, and supplies it as collateral to the Babylon Core Spoke. (`activationMetadata` is empty for default self-borrow.) +* **Stage 12 (PegIn broadcast):** any party (typically the Vault Provider) observing the activation event constructs the final PegIn witness using the revealed secret and the collected on-chain signatures, and broadcasts the transaction on Bitcoin. Once confirmed, the BTC is in its vault output. The PegIn transaction produces both the main vault output and a small depositor claim output (controlled solely by the depositor's key) that anchors the self-claim path. + +## Peg-out mechanism + +Peg-out releases the BTC on Bitcoin after a vault is redeemed on Ethereum. Three on-Ethereum triggers transition a vault from Active to Redeemed: + +* The depositor calls `depositorRedeem(vaultId)` after withdrawing collateral. +* An application-specific liquidation transfers ownership to the liquidator. Two function variants exist on the AaveAdapter: `liquidate(...)` for direct BTC redemption by registered arbitrageurs, and `liquidateWithLLP(...)` for permissionless liquidation that escrows the seized vault in an LLP (BTCVaultSwap by default). +* The depositor triggers a redemption directly (for example, via the activate-and-redeem shortcut). + +In all cases, the BTCVaultRegistry emits two VaultClaimableBy events — one for the Vault Provider's BTC public key and one for the depositor's BTC public key — identifying the authorized claimers. The Vault Provider drives the standard path; the depositor's event enables the WOTS self-claim fallback. + +### The 4-stage burn event proof + +To claim BTC on Bitcoin, the claimer (typically the Vault Provider) generates a zero-knowledge proof that the corresponding burn event happened on the finalized Ethereum chain. The proof is built in four stages: + +* **Stage 1 (beacon finality):** proves a specific Ethereum beacon chain block has been finalized by the consensus layer. +* **Stage 2 (execution finality):** links the beacon block to the execution block containing the burn transaction. +* **Stage 3 (receipt inclusion):** proves the BurnExecuted event log exists in the receipt of that block. +* **Stage 4 (Groth16 compression):** aggregates the previous three stages into a 128-byte Groth16 proof with a 32-byte public input. + +Generation runs on an SP1 prover (locally or via an external prover service), typically on GPU hardware, and takes 5-10 minutes per vault. + +### Bitcoin-side claim flow + +With the proof generated, the claimer follows the Bitcoin-side flow: + +* **Claim transaction.** Spends from the vault's Taproot output via the appropriate leaf (repayment, liquidation, or refund). +* **Assert transaction.** Includes WOTS signature commitments to the proof. Broadcast within the assert window (`timelockAssert` = 432 BTC blocks ≈ 3 days on Testnet). +* **Challenge window.** During `timelockAssert`, any Universal Challenger (or Vault Keeper) can broadcast a ChallengeAssert transaction to dispute the proof. +* **Payout.** If no challenge arrives within the window, the claimer broadcasts the Payout transaction. The BTC is released to the claimer's Bitcoin address, minus the Vault Provider's commission deducted on the depositor's payout path. + +If a ChallengeAssert is raised, the flow moves to dispute resolution. + +### If the Vault Provider goes offline + +The depositor's parallel `VaultClaimableBy` event authorizes the depositor as a claimer using the depositor's WOTS key plus the locally-stored claimer artifacts from Stage 10. The same Claim, Assert, and Payout transactions are followed, but signed by the depositor instead of the Vault Provider. + +## Challenge and dispute resolution + +Bitcoin's native scripts cannot directly verify ZK proofs. Verification happens through the BitVM3-style mechanism: a Bitcoin-script-only technique that uses pre-committed garbled circuits (from BABE setup) and WOTS commitments to enforce the proof's correctness using only Bitcoin's existing primitives. Two challenge paths cover the two adversarial scenarios. + +### Block a malicious claim + +A claim is malicious when no valid Ethereum burn event corresponds to the BTC the claimer is trying to take. + +* The claimer broadcasts the Claim and Assert transactions as usual. The Assert commits WOTS signatures of an invalid proof. +* A Universal Challenger or Vault Keeper detects the invalid proof and replays it under the BABE input labels established during peg-in. They broadcast ChallengeAssertX/Y on Bitcoin. The depositor can also broadcast this challenge directly using their own BABE artifacts if no other challenger acts. +* The claimer cannot reveal a refuting secret because no valid proof exists. They cannot post a WronglyChallenged response. +* After the disprove timelock (`timelockChallengeAssert` = 108 BTC blocks ≈ 18 hours on Testnet) expires, the challenger broadcasts NoPayout, finalizing the dispute. The claimer's bond is forfeited; the malicious claim is permanently blocked. + +### Block a malicious challenge + +A challenge is malicious when the claimer's proof is genuinely valid but a challenger raises a ChallengeAssert anyway (in error or maliciously). + +* The claimer extracts the witness from the ChallengeAssert transaction and decrypts the output label. +* The claimer broadcasts a WronglyChallenged transaction revealing the recovered label. This is only possible if the claim was truly valid; the garbled circuit construction makes it computationally infeasible otherwise. +* After the assert timelock (`timelockAssert`) expires, the claimer broadcasts the Payout transaction. The BTC is released as expected. The challenger's bond is forfeited. + +### Timelock parameters + +Two timelocks govern the dispute window. The total claim-to-payout wait is approximately three days. + +* `timelockAssert` **(challenge window):** 432 BTC blocks (~3 days) — window for any Universal Challenger or Vault Keeper to submit a ChallengeAssert. +* `timelockChallengeAssert` **(claimer disprove time):** 108 BTC blocks (~18 hours) — window for the claimer to disprove a challenge via WronglyChallenged. + +Both are versioned offchain parameters. Existing vaults retain the values from when they were created. diff --git a/docs/trustless-bitcoin-vault/testnet-info/contract-addresses.mdx b/docs/trustless-bitcoin-vault/testnet-info/contract-addresses.mdx index 88379dce..eaa8eb08 100644 --- a/docs/trustless-bitcoin-vault/testnet-info/contract-addresses.mdx +++ b/docs/trustless-bitcoin-vault/testnet-info/contract-addresses.mdx @@ -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. diff --git a/docs/trustless-bitcoin-vault/testnet-info/protocol-parameters.mdx b/docs/trustless-bitcoin-vault/testnet-info/protocol-parameters.mdx index bf665e65..839b7802 100644 --- a/docs/trustless-bitcoin-vault/testnet-info/protocol-parameters.mdx +++ b/docs/trustless-bitcoin-vault/testnet-info/protocol-parameters.mdx @@ -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. diff --git a/docs/trustless-bitcoin-vault/testnet-info/setup.mdx b/docs/trustless-bitcoin-vault/testnet-info/setup.mdx index aded6f0f..b217efb3 100644 --- a/docs/trustless-bitcoin-vault/testnet-info/setup.mdx +++ b/docs/trustless-bitcoin-vault/testnet-info/setup.mdx @@ -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 diff --git a/docs/trustless-bitcoin-vault/use-for-lending/_category_.json b/docs/trustless-bitcoin-vault/use-for-lending/_category_.json index 3a6dfecf..ed471d48 100644 --- a/docs/trustless-bitcoin-vault/use-for-lending/_category_.json +++ b/docs/trustless-bitcoin-vault/use-for-lending/_category_.json @@ -1,10 +1,10 @@ { - "label": "Use TBV Testnet For Lending", + "label": "Use TBV Testnet For Borrowing", "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." } } diff --git a/docs/trustless-bitcoin-vault/use-for-lending/borrow-and-repay.mdx b/docs/trustless-bitcoin-vault/use-for-lending/borrow-and-repay.mdx index dfd58008..e754b481 100644 --- a/docs/trustless-bitcoin-vault/use-for-lending/borrow-and-repay.mdx +++ b/docs/trustless-bitcoin-vault/use-for-lending/borrow-and-repay.mdx @@ -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. @@ -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. diff --git a/docs/trustless-bitcoin-vault/use-for-lending/create-a-vault.mdx b/docs/trustless-bitcoin-vault/use-for-lending/create-a-vault.mdx index d5cf9cae..d3c36ae4 100644 --- a/docs/trustless-bitcoin-vault/use-for-lending/create-a-vault.mdx +++ b/docs/trustless-bitcoin-vault/use-for-lending/create-a-vault.mdx @@ -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 diff --git a/docs/trustless-bitcoin-vault/use-for-lending/quickstart.mdx b/docs/trustless-bitcoin-vault/use-for-lending/quickstart.mdx index 062e04c1..546f039e 100644 --- a/docs/trustless-bitcoin-vault/use-for-lending/quickstart.mdx +++ b/docs/trustless-bitcoin-vault/use-for-lending/quickstart.mdx @@ -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). @@ -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) @@ -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) @@ -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. diff --git a/docs/trustless-bitcoin-vault/use-for-lending/withdraw-and-redeem.mdx b/docs/trustless-bitcoin-vault/use-for-lending/withdraw-and-redeem.mdx index 7a03eb76..e7f1571f 100644 --- a/docs/trustless-bitcoin-vault/use-for-lending/withdraw-and-redeem.mdx +++ b/docs/trustless-bitcoin-vault/use-for-lending/withdraw-and-redeem.mdx @@ -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). @@ -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 @@ -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. @@ -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 diff --git a/docusaurus.config.js b/docusaurus.config.js index 2ffb49df..0dbe3189 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -119,27 +119,11 @@ const plugins = [ from: '/guides/overview/bitcoin-vault/', to: '/trustless-bitcoin-vault/start-here/what-is-tbv/', }, - // Phase-2 TBV docs are kept off the public-testnet release path + // Legacy TBV aliases { from: '/trustless-bitcoin-vault/tbv-vs-alternatives/', to: '/trustless-bitcoin-vault/start-here/tbv-vs-alternatives/', }, - { - from: '/trustless-bitcoin-vault/start-here/safety-and-trust-assumptions/', - to: '/trustless-bitcoin-vault/start-here/what-is-tbv/', - }, - { - from: '/trustless-bitcoin-vault/technical-details/protocol-architecture/', - to: '/trustless-bitcoin-vault/start-here/what-is-tbv/', - }, - { - from: '/trustless-bitcoin-vault/technical-details/protocol-actors/', - to: '/trustless-bitcoin-vault/start-here/what-is-tbv/', - }, - { - from: '/trustless-bitcoin-vault/technical-details/aave-v4-integration/', - to: '/trustless-bitcoin-vault/start-here/what-is-tbv/', - }, // Staking research/security moved under Bitcoin Staking { from: '/guides/research/', diff --git a/static/img/trustless-bitcoin-vault/confluence/start-here/safety-and-trust-assumptions/7.png b/static/img/trustless-bitcoin-vault/confluence/start-here/safety-and-trust-assumptions/7.png new file mode 100644 index 00000000..f8f8dd10 Binary files /dev/null and b/static/img/trustless-bitcoin-vault/confluence/start-here/safety-and-trust-assumptions/7.png differ diff --git a/static/img/trustless-bitcoin-vault/confluence/technical-details/protocol-architecture/10.png b/static/img/trustless-bitcoin-vault/confluence/technical-details/protocol-architecture/10.png new file mode 100644 index 00000000..fb2de87b Binary files /dev/null and b/static/img/trustless-bitcoin-vault/confluence/technical-details/protocol-architecture/10.png differ