diff --git a/website/docs/learn/boarding.md b/website/docs/learn/boarding.md index f4a4502..cc2943d 100644 --- a/website/docs/learn/boarding.md +++ b/website/docs/learn/boarding.md @@ -7,22 +7,46 @@ title: 'Boarding the Ark' Alice wants to board the Ark of a well-known Ark service provider (ASP). It requires an on-chain transaction. -- Alice must be online **at least once every 4 weeks** to keep her funds safe. -- If ASP is unresponsive, Alice can claim her funds back in 24 hours. +Depending on the type of [Boarding transaction](./nomenclature#boarding-transaction) chosen by the ASP, the timeline is different. -### Timeline of events +### 🧳 Boarding with Luggage -1. Alice creates a [Funding transaction](./nomenclature#funding-transaction) +- Alice must be online **at least once every 4 weeks** to keep her funds safe +- If ASP is unresponsive, Alice can claim her funds back in **24 hours** +- Easier for the ASP since all VTXOs are born equal +- To unlock the boarding address Alice needs to make two transactions: -2. Alice adds any inputs she wants to cover the values the [VTXO](./nomenclature#vtxo-1) she will receive, plus on-chain fees. +```mermaid +flowchart LR + V["VTXO's timeout after 24 hrs"] + Covenant --> V +``` -3. Alice adds an output with **two spending conditions**: +#### Timeline of events - - `(ASP in 1 month)` - - A covenant output that forces coins to be spent by a [Redeem transaction](./nomenclature#redeem-transaction) with an output with **two** spending conditions: +1. Alice creates a [Boarding transaction](./nomenclature#with-luggage) +2. Alice adds any inputs she wants to cover the values the [VTXO](./nomenclature#vtxo-1) she will receive, plus on-chain fees +3. Alice adds an output with **2 spending paths**: + - This funds will belong to the ASP after 4 weeks: + - `(ASP after 4w)` + - A covenant output that forces coins to be spent by a [VTXO](./nomenclature#vtxo) with an output script with **2** spending paths: - `(Alice + ASP)` - - `(Alice in 24 hours)` + - `(Alice after 24h)` +4. Alice notifies ASP about the [Boarding transaction](./nomenclature#with-luggage) +5. Alice has now a promise of a [VTXO](./nomenclature#vtxo-1) enforced by a covenant -4. Alice notifies ASP about the [Funding transaction](./nomenclature#funding-transaction) +### 🎒 Boarding without Luggage -5. Alice has now a [VTXO](./nomenclature#vtxo-1). +- Alice don't need to worry about being online to maintain access to her funds after boarding +- If ASP is unresponsive, Alice can claim her funds back in **1 year** +- ASP must be aware of the timeout on the [Boarding transaction](./nomenclature#with-luggage) to prevent double spending + +#### Timeline of events + +1. Alice creates a [Boarding transaction](./nomenclature#without-luggage) +2. Alice adds any inputs she wants to cover the values the [VTXO](./nomenclature#vtxo-1) she will receive, plus on-chain fees. +3. Alice adds an output with **2** spending paths: + - `(Alice + ASP)` + - `(Alice after 1y)` +4. Alice notifies ASP about the [Boarding transaction](./nomenclature#without-luggage) +5. Alice can have this deposit to be accepted as if it were a normal [VTXO](./nomenclature#vtxo-1) born in an Ark [Pool transaction](./nomenclature#pool-transaction-aka-ark-transaction) diff --git a/website/docs/learn/nomenclature.md b/website/docs/learn/nomenclature.md index 9a7bfec..d08c93c 100644 --- a/website/docs/learn/nomenclature.md +++ b/website/docs/learn/nomenclature.md @@ -1,7 +1,9 @@ --- sidebar_position: 1 title: 'Nomenclature' +toc_max_heading_level: 5 --- + :::info 🚧 This page is currently under development, and some concepts may not be entirely accurate. We greatly value your feedback and contributions. If you have any suggestions, corrections, or would like to submit edits, please do so through the pull request link available at the bottom of each page. ::: @@ -36,24 +38,59 @@ Periodic transaction crafted by the ASP that hits mainchain and creates new VTXO ## Transactions -**Note:** In an optimistic scenario, transactions marked with a **\*** should never hit onchain. +### Notes -### Funding transaction +- In an optimistic scenario, transactions marked with a **\*** should never hit onchain. +- All time periods used on timelocks (**5s**, **24h**, **4w**, **1y**) are arbitrary: any ASP can use different values. -- When Alice wants to enter the Ark +### Legend -| Inputs | Outputs (locking script) | -| ------------------- | ----------------------------------- | -| Alice’s segwit UTXO | `(Alice + ASP) or (ASP in 1 month)` | +- **A**: Alice pubkey +- **ASP**: ASP pubkey +- **cov\*\*(script)**: covenant that forces the spending transaction to have a mandatory first output with the **script** +- **and(A,B)**: both conditions needed to unlock +- **or(A,B)**: only one condition needed to unlock +- **and(A, or(S, after(24h)**: (Alice and Server) or (Alice after 24h) -### Redeem transaction\* +### VTXO\* -- Insurance for Alice, in case the ASP becomes unresponsive. -- Allows Alice to receive funds back from the Ark after a grace period ie. 24 hours +- A Virtual UTXO: it looks like an UTXO but it should never hit onchain, thus a Virtual UTXO -| Inputs | Outputs | -| ------------------------------------------ | -------------------------------------- | -| Funding transaction spending `Alice + ASP` | `(Alice + ASP) or (Alice in 24 hours)` | +| Inputs | Outputs | +| ---------------------------- | ------------------------------------ | +| Boarding or Pool transaction | `(Alice + ASP) or (Alice after 24h)` | + +### Boarding transaction + +There are 2 different ways a user can board the Ark: + +- With luggage +- Without luggage + +Different ASPs can use different ways for users to board their Ark. + +#### With luggage + +- Initially proposed by [Steven Roose](https://roose.io/presentations/understanding-ark.pdf) +- Alice funds an output that can be **accepted as a VTXO** in a future round +- A covenant forces the creation of an output with the same script as [**VTXO**](#VTXO). No need for interactivity after funding it, anyone can spend. +- **ASP** can unlock after a timeout ie. _8 weeks_ +- Alice is **required to be online** to maintain access to funds: after the timeout, ASP becomes the only owner funds + +| Inputs | Outputs | +| ------------ | ----------------------------------------------------------- | +| Alice’s UTXO | `(ASP after 4w) or cov((Alice + ASP) or (Alice after 24h))` | + +#### Without luggage + +- Initially proposed by [Burak](https://lists.linuxfoundation.org/pipermail/bitcoin-dev/2023-May/021694.html) +- Alice funds an output that can be **accepted as a VTXO** in a future round +- If ASP is not cooperative, **Alice** can unlock after a timeout ie. _8 weeks_ +- Alice is **not required to be online** to maintain access to funds: after the timeout, she becomes the only owner of the funds + +| Inputs | Outputs | +| ------------ | ----------------------------------- | +| Alice’s UTXO | `(Alice after 1y) or (Alice + ASP)` | ### Forfeit transaction\* @@ -61,34 +98,42 @@ Periodic transaction crafted by the ASP that hits mainchain and creates new VTXO - Before the ASP funds Bob’s VTXO in the next Pool transaction, he must receive this transaction signed by Alice - Uses a connector from the next Pool transaction to achieve atomicity -| Inputs | Outputs | -| ----------------------------------------- | ------- | -| Redeem transaction spending `Alice + ASP` | `ASP` | -| Connector from next Pool transaction | +| Inputs | Outputs | +| ------------------------------------ | ------- | +| VTXO spending `Alice + ASP` | `ASP` | +| Connector from next Pool transaction | ### Pool transaction (aka Ark transaction) - Funded by the ASP, creates VTXOs -- After 4 weeks, the ASP can get their funds back -- Multisig `n-of-n` where `n` is the number of participants +- Has at least two outputs: + - A shared output with a VTXOs tree + - A connectors output with a connectors tree - A new transaction is broadcasted every 5 seconds -| Inputs | Outputs | -| -------- | ------------------------------------------- | -| ASP UTXO | Shared output: `n-of-n or (ASP in 1 month)` | +| Inputs | Outputs | +| -------- | ----------------- | +| ASP UTXO | Shared output | +| | Connectors output | ### Shared output (aka Shared UTXO) - Represents a binary tree of transactions - In an optimistic scenario, this tree is never revealed +- Each leaf on this tree represents a VTXO -![Chart of a Shared Output](/img/shared_output.png) - -### VTXO\* - -- Similar to Redeem transaction -- Can be broadcasted anytime, on the condition that previous transactions on the transaction tree (up to the Pool transaction) are confirmed or broadcasted at the same time - -| Inputs | Outputs | -| --------------------------------------- | -------------------------------------- | -| Previous transaction on the binary tree | `(Alice + ASP) or (Alice in 24 hours)` | +```mermaid +flowchart LR + subgraph Onchain + shared(Shared output) + end + subgraph Virtual + tx1(TX 1) --> tx2(TX 2) + tx1 --> tx3(TX 3) + tx2 --> v1(VTXO 1) + tx2 --> v2(VTXO 2) + tx3 --> v3(VTXO 3) + tx3 --> v4(VTXO 4) + end + shared --> tx1 +``` diff --git a/website/static/img/shared_output.png b/website/static/img/shared_output.png index 8bec03e..3fb6f5b 100644 Binary files a/website/static/img/shared_output.png and b/website/static/img/shared_output.png differ