Skip to content

Commit

Permalink
Merge pull request #55 from bitlayer-org/feature/v2-doc
Browse files Browse the repository at this point in the history
Feature/v2 doc
  • Loading branch information
miaohaifeng authored Jan 6, 2025
2 parents b866a0a + 6a86803 commit 5308366
Show file tree
Hide file tree
Showing 60 changed files with 7,321 additions and 780 deletions.
19 changes: 19 additions & 0 deletions docs/Finality/UserGuides/GetTestToken.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
---
sidebar_position: 1
---

# How to get Test Token?

## Bitcoin Testnet3 Faucet

Here are some resources for obtaining Bitcoin Testnet3 tokens:

- [TheFaucet](https://www.thefaucet.org/Bitcoin/Test3)
- [Coinfaucet](https://coinfaucet.eu/en/btc-testnet/)

## Ethereum Sepolia Faucet

Here are some resources for obtaining Ethereum Sepolia tokens:

- [Alchemy](https://www.alchemy.com/faucets/ethereum-sepolia)
- [QuickNode](https://faucet.quicknode.com/ethereum/sepolia)
50 changes: 50 additions & 0 deletions docs/Finality/UserGuides/HowtoMint.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
---
sidebar_position: 50
---

# How to Mint ?

## Prerequisites


To get started, ensure you have wallets supporting BTC and EVM-compatible addresses, you can get test tokens from the [links](./GetTestToken.md).

- Bitcoin Testnet3
- Wallet: [UniSat](https://unisat.io/) , [OKX Web3](https://www.okx.com/web3)
- Ethereum Sepolia Testnet
- Wallet: [MetaMask](https://metamask.io/), [OKX Web3](https://www.okx.com/web3), [Coinbase Wallet
](https://www.coinbase.com/wallet)


## 1. Connect Bitcoin Wallet

#### 1.1 Connect Bitcoin Testnet3, and Sign in.
![Connect Bitcoin Wallet](/img/Finality/tutorial/connect-wallet.png)

#### 1.2 Confirm address and amount

Enter amount within 0.0001~0.001, and input your Sepolia address(If you have connected an EVM wallet, your EVM receiving address will be automatically filled in.).
![Connect Bitcoin Wallet](/img/Finality/tutorial/confirm-address-amount.png)


## 2. Pick your funding UTXOs
Please ensure the selected UTXOs are not associated with derivative assets like BRC20.
If UTXOs you choosed containes more BTC than you mint, extra BTC will back to your BTC address

![Pick your funding UTXOs](/img/Finality/tutorial/pick-your-funding-utxo.png)


## 3. Generate address for Deposit
The Finality Bridge Network will generate a smart contract which will accept you BTC according to your peg-in request.
You can view the logic rules of this smart contract through a visualized diagram.
![Generate address for Deposit](/img/Finality/tutorial/generate-address-for-deposit.png)
![graph.png](/img/Finality/tutorial/graph.png)

## 4. Make your BTC Deposit
Confirm all information and transfer your BTC.
![Make your BTC Deposit](/img/Finality/tutorial/make-your-btc-deposit.png)

## 5. Mint your YBTC on Ethereum
This operation will cost 20-30Mins, it is safe to close the window. Minting process will continue as a background process and will not be interrupted.

![Mint your YBTC on Ethereum](/img/Finality/tutorial/mint-your-ybtc-on-ethereum.png)
6 changes: 6 additions & 0 deletions docs/Finality/UserGuides/_category_.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
{
"label": "User Guides",
"position": 9,
"link": null,
"collapsed": false
}
6 changes: 6 additions & 0 deletions docs/Finality/_category_.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
{
"label": "Finality Bridge",
"position": 4,
"link": null,
"collapsed": false
}
31 changes: 31 additions & 0 deletions docs/Finality/overview.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
---
sidebar_position: 1
sidebar_label: Overview
---

# Overview

In the rapidly evolving landscape of blockchain technology, the challenge of securely bridging Bitcoin with other blockchain networks has remained a persistent focus of innovation. Finality Bridge, developed by Bitlayer, emerges as a groundbreaking solution that leverages the power of BitVM2 to create a trust-minimized bridge for Bitcoin interoperability. This technological advancement represents a significant leap forward in addressing the fundamental challenges that have long plagued cross-chain Bitcoin transfers.

As a standalone product operating independently of Bitlayer's layer 2 infrastructure, Finality Bridge introduces a novel approach to Bitcoin bridging that prioritizes security and trust minimization while maintaining practical functionality. Its ability to support multiple target chains, including Ethereum, EVM-compatible chains like Bitlayer, and non-EVM chains like Solana, positions it as a versatile solution for the growing demands of cross-chain interoperability in the Bitcoin ecosystem.

## Evolution of Bitcoin Bridges

The journey toward achieving secure and efficient Bitcoin bridges has been marked by distinct evolutionary stages, each representing significant progress in addressing the fundamental challenges of cross-chain interoperability. Understanding this evolution provides crucial context for appreciating the revolutionary nature of Finality Bridge's approach.

The first generation of Bitcoin bridges emerged with solutions like Wrapped Bitcoin (wBTC), which relied entirely on centralized custodians and control mechanisms. While functional, these solutions required users to place complete trust in a single entity or small group of entities, fundamentally contradicting the decentralized ethos of blockchain technology.

Second-generation bridges introduced distributed control mechanisms while maintaining centralized custody. These Multi-Party Computation (MPC) bridges represented an important step forward in security by distributing control across multiple parties. However, they still relied on custodial services, creating persistent vulnerabilities in the system.

The third generation brought sophisticated middleware chain-assisted bridges, exemplified by solutions like tBTC. These implementations featured distributed custody systems backed by Proof-of-Stake incentives, marking significant advancement in decentralization while still facing limitations in security guarantees and trust assumptions.

With the advent of fourth-generation solutions, exemplified by Finality Bridge powered by BitVM2 technology, we witness a fundamental shift toward trust minimization. This approach moves beyond previous limitations by implementing sophisticated smart contract mechanisms on Bitcoin itself, despite the network's limited native smart contract capabilities.

Looking ahead, the theoretical fifth generation of Bitcoin bridges promises complete trustlessness, though this advancement remains contingent on future Bitcoin protocol upgrades. This forward-looking perspective helps contextualize Finality Bridge's position as a crucial stepping stone toward truly trustless cross-chain interoperability.

Two critical limitations plagued previous generations of bridges:

1. The requirement for honest majority assumptions, which created systemic vulnerabilities that could potentially compromise the entire bridge system.
2. The mismatch between security levels of wrapped Bitcoin and other DeFi assets, introducing inconsistencies in the broader ecosystem's security model.

Fourth-generation solutions like Finality Bridge directly address these limitations through innovative architectural approaches and security mechanisms, establishing new standards for Bitcoin bridge security and reliability.
80 changes: 80 additions & 0 deletions docs/Finality/protocol.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,80 @@
---
sidebar_position: 2
sidebar_label: Finality Bridge Protocol
---

# Finality Bridge Protocol

The Finality Bridge Protocol represents a sophisticated mechanism for enabling secure and decentralized interoperability between Bitcoin and other blockchain ecosystems. By leveraging innovative technologies such as BitVM smart contracts and fraud-proof mechanisms, it establishes a trust-minimized environment where funds can be transferred across chains while preserving the integrity of Bitcoin's foundational principles. This article delves into the architecture and operations of the protocol, with a particular focus on its components on Bitcoin, its interaction with target chains, and the intricate processes that govern its functionality.

## Bridge Contract on Bitcoin

At the heart of the Finality Bridge Protocol lies the bridge contract on Bitcoin, which is constructed using BitVM smart contract technology. This approach is particularly well-suited for building bridge protocols due to its ability to emulate smart contract functionality on Bitcoin, a platform traditionally limited in this regard. BitVM achieves this by utilizing pre-signed transaction graphs that define all possible execution paths, ensuring that funds remain secure and accessible only through predefined conditions.

One of the key advantages of BitVM smart contracts is their inherent trust-minimization. A peg-in user, for instance, will only deposit funds after verifying that the correct smart contract has been generated and published. This ensures that no party is harmed if the user chooses not to proceed. Furthermore, the security model operates under a "1-of-N" assumption, meaning that as long as one committee member deletes their private key after signing, it becomes impossible to introduce unauthorized exits for the bridge funds. This design ensures that the bridge contract secures the funds without relying on custodianship, aligning with Bitcoin's decentralized ethos.

For more details on the principles and mechanics of BitVM smart contracts, refer to the [BitVM documentation](https://github.com/bitlayer-org/bitlayer-org.github.io/blob/feature/v2-doc/docs/Learn/Technologies/bitvm-smart-contract.md).

### Bridge Instance Lifecycle

Each peg-in request initiates the creation of a new bridge instance, which is governed by its own BitVM smart contract. This contract meticulously defines all potential exits for the peg-in funds, ensuring that once the funds enter the target chain, they can only be withdrawn back to Bitcoin through the smart contract. This guarantees that no external entity can bypass the contract and access the locked funds.

The lifecycle of a bridge instance is characterized by three distinct states:
1. **Inactive**: The initial state before the peg-in funds are locked in the BitVM smart contract.
2. **Active**: Once the peg-in funds are secured within the contract, the instance transitions to an active state, enabling operations such as peg-out.
3. **Finished**: When all peg-in funds are returned to Bitcoin, the instance concludes its lifecycle by transitioning to the finished state.

### User Operations: Peg-in and Peg-out

The protocol supports two primary user operations: peg-in and peg-out. During a peg-in, users lock their BTC in a BitVM smart contract, which results in the minting of YBTC—a token representation of BTC—on the target chain. Each YBTC token is pegged 1:1 to BTC, ensuring value parity. Conversely, a peg-out involves burning YBTC on the target chain to withdraw an equivalent amount of BTC from the BitVM smart contract. While the peg-in process is relatively straightforward, the peg-out operation introduces additional complexities, which are addressed through innovative mechanisms discussed later in this article.

### The Role of the Presigning Committee

To facilitate the secure operation of each bridge instance, a presigning committee is elected. This committee is responsible for reviewing and pre-signing the transaction graph that governs the BitVM smart contract. To ensure fungibility of funds across different bridge instances, the size of the presigning committee is standardized. Notably, the protocol allows peg-in users to join the presigning committee, further enhancing security by incentivizing honest behavior. Peg-in users have a vested interest in protecting their funds, motivating them to act in accordance with the protocol's rules, such as deleting their private keys after signing.

### Handling Dynamic Elements and Unpredictable Inputs

A significant challenge in BitVM smart contracts is managing dynamic elements, particularly the unpredictability of peg-out users. Since the beneficiary and amount of peg-in funds must be predetermined during the contract's construction, only a limited set of users can initially receive the funds. This rigidity introduces operational inefficiencies.

To address this, the protocol employs a "front-and-reclaim" scheme. Brokers act as intermediaries, fronting the peg-out requests with their own liquidity and subsequently reclaiming the funds from the BitVM smart contract. This approach not only resolves the predictability issue but also ensures that users experience seamless operations without being constrained by the contract's static nature.

## Bridge Contract on Target Chain

The Finality Bridge Protocol is designed to support multiple target chains, including Ethereum and Bitcoin rollups like Bitlayer. The architecture of the bridge contract on the target chain varies depending on the chain's specific design, particularly its light client implementation. This adaptability ensures that the protocol can operate efficiently across diverse blockchain ecosystems.

### Example: Ethereum Mainnet and Bitlayer Rollup

On Ethereum, the bridge contract integrates with Ethereum's light client to verify transactions and manage the minting and burning of YBTC tokens. Similarly, on Bitcoin rollups like Bitlayer, the bridge contract is tailored to interact with the rollup's unique consensus and state verification mechanisms. These variations highlight the protocol's flexibility and its ability to accommodate the nuances of different blockchain platforms.

## End-to-End Operations

### Peg-in: Locking BTC in the Smart Contract

The peg-in process begins with the generation of an N-of-N multisig by the presigning committee. This multisig acts as the custodian of the smart contract, ensuring that no single entity can unilaterally access the funds. Once the peg-in user verifies the correctness of the contract, they transfer their BTC to the multisig, effectively locking the funds in the smart contract. The deletion of private keys by committee members further ensures the trust-minimized nature of the protocol.

### Peg-out: Front-and-Reclaim Procedure

The peg-out process is facilitated by brokers, who play a crucial role in bridging the gap between the static nature of the smart contract and the dynamic requirements of users. When a peg-out user burns YBTC on the target chain, they initiate a peg-out request by partially signing a Bitcoin transaction. The broker validates the request, transfers the requested BTC to the user, and subsequently reclaims the funds from the smart contract.

The reclaim process is inherently optimistic. The broker submits a reclaim request on-chain, which is finalized if no challenges are raised within a predefined window. However, if a challenge arises, a dispute resolution game is triggered. This game, based on fraud proofs, determines the validity of the reclaim request. If the challenge succeeds, the broker's request is rejected, and their deposit is forfeited. This mechanism ensures that the complexity of the process is offloaded to the broker, who charges a fee for their service.

## Fraud Proofs for Reclaim Procedure

Fraud proofs are an integral part of the reclaim process, ensuring that invalid requests are identified and rejected. The procedure relies on the **Reclaim Checker**, a program that verifies the validity of reclaim requests. The actual verification is performed using a Groth16 zero-knowledge proof (ZKP), which provides computational efficiency and scalability.

### Proving and Verifying State Transitions

The broker must generate a ZKP to prove that the reclaim request satisfies the conditions defined by the Reclaim Checker. This includes verifying that the burn occurred on the target chain and that the fronting transaction took place on Bitcoin's canonical chain. The proof is processed off-chain using a chunked Groth16 verifier, which generates shared values for on-chain verification.

On Bitcoin, the verification process involves the following steps:
1. The broker commits to the ZK verifier result.
2. A vigilante verifies the ZK proof off-chain and raises a challenge if inconsistencies are found.
3. The broker reveals all shared values on-chain.
4. The vigilante executes each chunk sequentially to identify discrepancies.
5. If the replayed chunk's result differs from the broker's commitment, the reclaim request is rejected, and the broker's deposit is forfeited.

This layered approach ensures that the protocol remains secure, scalable, and aligned with Bitcoin's decentralized principles.

---

By combining the robustness of BitVM smart contracts with the efficiency of zero-knowledge proofs and fraud-proof mechanisms, the Finality Bridge Protocol establishes a reliable framework for cross-chain interoperability. Its design not only addresses the limitations of Bitcoin's scripting capabilities but also sets a new standard for trust-minimized bridging solutions in the blockchain ecosystem.
Loading

0 comments on commit 5308366

Please sign in to comment.