Skip to content

Commit dd42546

Browse files
AndresQuijanoAndresQuijano
authored
Merge pull request #931 from rsksmart/fly2187_docs_update
docs: update devportal documentation
2 parents a305034 + 28a4feb commit dd42546

File tree

3 files changed

+320
-77
lines changed

3 files changed

+320
-77
lines changed

‎.github/workflows/devPortal-update.yml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -48,10 +48,10 @@ jobs:
4848
BASE_DST="devportal/docs/02-developers/06-integrate/02-flyover"
4949
5050
#####################################
51-
# Usecases #
51+
# Overview #
5252
#####################################
5353
TEMP_FILE="temp_index.md"
54-
tail -n +2 ${BASE_SRC}/docs/Usecases.md > ${TEMP_FILE}
54+
tail -n +2 ${BASE_SRC}/docs/Overview.md > ${TEMP_FILE}
5555
TRANSFORMED_FILE="transformed/index.md"
5656
echo "---" > ${TRANSFORMED_FILE}
5757
echo "sidebar_label: RBTC Flyover" >> ${TRANSFORMED_FILE}

‎docs/Overview.md‎

Lines changed: 318 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,318 @@
1+
# rBTC Flyover
2+
3+
Flyover is Rootstock's fast bridge for BTC ↔ rBTC. Instead of waiting ~17 hours for PowPeg, a Liquidity Provider (LP) advances funds after a few confirmations. The user gets their rBTC or BTC in 20–60 minutes, depending on the amount.
4+
5+
```
6+
PowPeg:
7+
User sends BTC → waits ~17 hours → receives rBTC
8+
9+
Flyover:
10+
User sends BTC → LP advances rBTC in 20–60 min → LP gets refunded later via PowPeg
11+
```
12+
13+
---
14+
15+
## PowPeg vs Flyover
16+
17+
| | PowPeg | Flyover |
18+
| --- | --- | --- |
19+
| **Core mechanism** | Federated 2-Way Peg (HSMs + PoW) | LP advances funds, settles via PowPeg |
20+
| **Peg-in speed** | ~17 hours (100 Bitcoin confirmations) | 20–60 min |
21+
| **Peg-out speed** | ~34 hours (4,000 Rootstock confirmations) | 20–60 min |
22+
| **Fees** | Network fees only | 0.15% LP fee + network fees * |
23+
| **Minimum peg-in** | 0.005 BTC | 0.00500001 BTC |
24+
| **Minimum peg-out** | 0.004 rBTC | 0.004 rBTC |
25+
| **Maximum** | None | 15 BTC / 15 rBTC * |
26+
| **Trust model** | PowPeg federation | LP intermediation, settles through PowPeg |
27+
28+
Flyover's speed depends on the amount: smaller amounts need fewer Bitcoin confirmations and settle faster; larger amounts need more.
29+
30+
* The LP fee is set by each LP. 0.15% is the current default but may vary.
31+
* Maximum transfer limits are set by the LP and will increase over time.
32+
33+
---
34+
35+
## How Flyover Works
36+
37+
### Peg-In: BTC to rBTC
38+
39+
```mermaid
40+
flowchart LR
41+
subgraph off["Off-Chain"]
42+
A["User requests quote"] --> B["LP returns quote"]
43+
B --> C["User accepts quote"]
44+
C --> D["LP returns deposit address"]
45+
end
46+
47+
subgraph btc["Bitcoin"]
48+
E["User sends BTC<br>to deposit address"]
49+
E --> F["Wait for<br>confirmations"]
50+
end
51+
52+
subgraph rsk["Rootstock"]
53+
G["LP calls callForUser<br>→ User receives rBTC"]
54+
G --> H["LP registers peg-in<br>→ Bridge refunds LP"]
55+
end
56+
57+
off --> btc --> rsk
58+
59+
style off fill:#f9f9f9,stroke:#999
60+
style btc fill:#f7931a22,stroke:#f7931a
61+
style rsk fill:#00b41e22,stroke:#00b41e
62+
```
63+
64+
**1. Get a quote**
65+
The user requests a quote through the PowPeg App. The quote shows the amount of rBTC the user will receive, fees, required Bitcoin confirmations, and a time estimate.
66+
67+
**2. Accept the quote**
68+
The user must carefully review the quote details — including the amount, fees, confirmations required, and time estimate — and explicitly accept it before proceeding. Once the user accepts, the LP generates a unique Bitcoin deposit address tied to this specific quote. The address is derived from the quote hash — every transaction gets its own address.
69+
70+
**3. Deposit BTC**
71+
The user sends BTC to the deposit address. The LP monitors Bitcoin and waits for the required number of confirmations.
72+
73+
**4. LP delivers rBTC**
74+
Once confirmed, the LP calls the Liquidity Bridge Contract (LBC) on Rootstock to send rBTC to the user's address.
75+
76+
**5. LP claims refund (background)**
77+
The LP registers the peg-in with the Rootstock Bridge, providing a Merkle proof of the Bitcoin transaction. The Bridge verifies the proof and refunds the LP the original amount plus the fee. This is invisible to the user.
78+
79+
#### Sequence Diagram
80+
81+
```mermaid
82+
sequenceDiagram
83+
actor User
84+
participant App as PowPeg App
85+
participant LBC as Liquidity Bridge Contract
86+
participant LP as Liquidity Provider
87+
participant BTC as Bitcoin Network
88+
participant Bridge as Rootstock Bridge
89+
90+
User->>App: Bridge BTC to rBTC
91+
App->>LP: Request quote
92+
LP-->>App: Quote + fees + time estimate
93+
App-->>User: Show quote
94+
95+
User->>App: Accept quote
96+
App->>LP: Accept quote
97+
LP-->>App: Unique deposit address
98+
App-->>User: Show deposit address
99+
100+
User->>BTC: Send BTC to deposit address
101+
102+
Note over LP: Monitors Bitcoin, waits for confirmations
103+
104+
LP->>LBC: callForUser (advance rBTC)
105+
LBC-->>User: rBTC received
106+
107+
Note over LP: Registers peg-in with Bridge (background)
108+
109+
LP->>Bridge: registerPegIn (Merkle proof of BTC tx)
110+
Bridge-->>LP: Refund (amount + fee)
111+
```
112+
113+
### Peg-Out: rBTC to BTC
114+
115+
```mermaid
116+
flowchart LR
117+
subgraph off["Off-Chain"]
118+
A["User requests quote"] --> B["LP returns quote"]
119+
B --> C["User accepts quote"]
120+
end
121+
122+
subgraph rsk["Rootstock"]
123+
D["User deposits rBTC<br>into LBC"]
124+
D --> E["Wait for<br>confirmations"]
125+
end
126+
127+
subgraph btc["Bitcoin"]
128+
F["LP sends BTC<br>→ User receives BTC"]
129+
end
130+
131+
subgraph settle["Rootstock Bridge"]
132+
G["LP proves BTC was sent<br>→ Bridge refunds LP"]
133+
end
134+
135+
off --> rsk --> btc --> settle
136+
137+
style off fill:#f9f9f9,stroke:#999
138+
style rsk fill:#00b41e22,stroke:#00b41e
139+
style btc fill:#f7931a22,stroke:#f7931a
140+
style settle fill:#f9f9f9,stroke:#999
141+
```
142+
143+
**1. Get a quote**
144+
The user requests a quote showing the BTC they'll receive, fees, and time estimate.
145+
146+
**2. Accept the quote**
147+
The LP reserves BTC liquidity and returns a signature.
148+
149+
**3. Deposit rBTC**
150+
The user deposits rBTC into the Liquidity Bridge Contract on Rootstock. The contract locks the funds and emits an event that the LP monitors.
151+
152+
**4. LP sends BTC**
153+
Once the rBTC deposit has enough Rootstock confirmations, the LP sends BTC to the user's Bitcoin address.
154+
155+
**5. LP claims refund (background)**
156+
The LP submits a Merkle proof of the BTC payment to the Liquidity Bridge Contract and settles through the Rootstock Bridge. This happens in the background.
157+
158+
#### Sequence Diagram
159+
160+
```mermaid
161+
sequenceDiagram
162+
actor User
163+
participant App as PowPeg App
164+
participant LBC as Liquidity Bridge Contract
165+
participant LP as Liquidity Provider
166+
participant BTC as Bitcoin Network
167+
participant Bridge as Rootstock Bridge
168+
169+
User->>App: Bridge rBTC to BTC
170+
App->>LP: Request peg-out quote
171+
LP-->>App: Quote + fees + time estimate
172+
App-->>User: Show quote
173+
174+
User->>App: Accept quote
175+
App->>LP: Accept quote
176+
LP-->>App: Signature
177+
178+
User->>LBC: Deposit rBTC (via PowPeg App)
179+
LBC-)LP: Deposit event
180+
181+
Note over LP: Waits for Rootstock confirmations
182+
183+
LP->>BTC: Send BTC to user's address
184+
BTC-->>User: BTC received
185+
186+
Note over LP: Proves BTC was sent, claims refund (background)
187+
188+
LP->>LBC: refundPegOut (Merkle proof)
189+
LP->>Bridge: Initiate peg-out for settlement
190+
Bridge-->>LP: Refund BTC + fees
191+
```
192+
193+
---
194+
195+
## Security
196+
197+
Flyover builds on PowPeg — live since 2018 with 100% uptime and operational excellence — and inherits its security guarantees.
198+
199+
### Non-Custodial
200+
201+
The LP never has access to user funds. In a peg-in, user BTC goes directly to a PowPeg federation-controlled address. In a peg-out, user rBTC is locked in the Liquidity Bridge Contract (LBC), which acts as the trusted third party instead of the federation. In both cases, the LP advances funds from its own separate balance and cannot access, redirect, or withhold user funds at any point in the process.
202+
203+
### Trust Model
204+
205+
| | What happens | Enforced by |
206+
| --- | --- | --- |
207+
| **Quote negotiation** | User and LP agree on terms off-chain | LP signs quote cryptographically |
208+
| **Fund movement** | BTC deposited to federation address (peg-in) or rBTC locked in LBC (peg-out) | On-chain — Bitcoin network / Rootstock smart contract |
209+
| **LP delivery** | LP advances funds to user | On-chain — LBC verifies and records |
210+
| **Settlement** | LP claims refund via Merkle proof | On-chain — Rootstock Bridge verifies proof |
211+
| **Deadlines** | Every quote has time limits for deposit and delivery | On-chain — LBC enforces deadlines |
212+
213+
**What the user does not need to trust:**
214+
- The LP with their BTC — it goes directly to the PowPeg federation, not the LP
215+
- The LP to be honest — delivery and settlement are verified on-chain
216+
217+
**What the LP commits to:**
218+
- Advancing funds within the quoted deadline
219+
- Locking collateral in the LBC as a guarantee
220+
221+
### On-Chain Guarantees
222+
223+
The Liquidity Bridge Contract (LBC) enforces:
224+
225+
- **Quote terms** — the LP's signed quote is verified on-chain during settlement
226+
- **Collateral** — LPs must lock collateral before participating. Slashed if the LP fails to deliver.
227+
- **Deadlines** — if the LP misses the delivery deadline, collateral is slashed and the user receives a refund in rBTC
228+
- **Merkle proofs** — LP settlement requires cryptographic proof that funds were sent
229+
230+
Quote negotiation happens off-chain. Everything else — fund custody, delivery, deadlines, settlement — is enforced on-chain.
231+
232+
### Failure Scenarios
233+
234+
| Scenario | Outcome |
235+
| --- | --- |
236+
| **LP doesn't deliver within deadline** | LP's collateral is slashed. User receives a refund in rBTC. |
237+
| **LP goes offline before accepting a quote** | No transaction starts. User can choose another LP, PowPeg, or aggregated routes. |
238+
| **User doesn't deposit in time** | Quote expires. No funds are moved. |
239+
240+
### Audited
241+
242+
The Liquidity Bridge Contract is audited. The PowPeg Bridge is a core Rootstock protocol component, live since 2018 with 100% uptime and operational excellence.
243+
244+
---
245+
246+
## Key Concepts
247+
248+
### Liquidity Bridge Contract (LBC)
249+
250+
The smart contract on Rootstock that coordinates Flyover transactions. It holds quotes, verifies proofs, manages LP collateral, and handles refunds.
251+
252+
**Contract addresses:**
253+
- Mainnet: `0xaa9caf1e3967600578727f975f283446a3da6612`
254+
- Testnet: `0xc2a630c053d12d63d32b025082f6ba268db18300`
255+
256+
### Fees
257+
258+
| Fee | Description |
259+
| --- | --- |
260+
| **LP fee** | Set by each LP. Currently 0.15% of the transaction value |
261+
| **Network fees** | Bitcoin transaction fees + Rootstock gas |
262+
263+
All fees are shown in the quote before you confirm.
264+
265+
### Limits
266+
267+
| | Minimum | Maximum |
268+
| --- | --- | --- |
269+
| Peg-in | 0.00500001 BTC | 15 BTC * |
270+
| Peg-out | 0.004 rBTC | 15 rBTC * |
271+
272+
* Maximum transfer limits are set by the LP and will increase over time.
273+
274+
---
275+
276+
## Who Is Flyover For?
277+
278+
### Institutional Users
279+
280+
Flyover supports institutional custody through MPC wallet integration. Fordefi is supported today (using a segwit vault) for both peg-in and peg-out operations.
281+
282+
- Predictable timing (20–60 min) with clear deadlines in every quote
283+
- Transparent fees — 0.15% + network fees, shown upfront
284+
- Non-custodial — the LP never has access to your funds
285+
- Transaction limits at 15 BTC / 15 rBTC, increasing over time
286+
- Programmatic access via the Flyover SDK
287+
288+
### Liquidity Providers
289+
290+
LPs provide liquidity in rBTC and BTC, earning fees on every transaction. An LP can be an exchange, a wallet provider, an institution, or an individual with sufficient capital.
291+
292+
**Requirements:**
293+
- Rootstock node and Bitcoin node (private, dedicated — not public nodes)
294+
- MongoDB instance
295+
- Minimum collateral: 0.06 rBTC
296+
- Wallet setup (local keystore or custodial integration)
297+
298+
See [LP Onboarding](/developers/integrate/flyover/LP/) for setup instructions and [LP Management](/developers/integrate/flyover/LP/management/) for the management API.
299+
300+
### Developers and Integrators
301+
302+
The Flyover SDK provides JavaScript/TypeScript tools for integrating Flyover into wallets, dApps, exchanges, and other applications.
303+
304+
```
305+
npm install @rsksmart/flyover-sdk
306+
```
307+
308+
See [Flyover SDK Integration](/developers/integrate/flyover/sdk/) for the full guide.
309+
310+
---
311+
312+
## Resources
313+
314+
- [Flyover Protocol Paper](https://eprint.iacr.org/2023/086.pdf) — formal protocol design and security analysis
315+
- [Flyover SDK on GitHub](https://github.com/rsksmart/flyover-sdk)
316+
- [LP Onboarding](/developers/integrate/flyover/LP/)
317+
- [LP Management API](/developers/integrate/flyover/LP/management/)
318+
- [PowPeg App](https://powpeg.rootstock.io)

0 commit comments

Comments
 (0)