From f4dee08651cbb9f13b0c346df3a742178fefaca8 Mon Sep 17 00:00:00 2001 From: Marco Argentieri <3596602+tiero@users.noreply.github.com> Date: Thu, 30 Nov 2023 18:39:52 +0100 Subject: [PATCH] Improve copy (#25) --- .../blog/2023-11-10-liquidity-requirements.md | 2 +- website/docs/intro.md | 32 +++++++++++-------- website/docs/intro/boarding.md | 10 +++--- website/docs/intro/payments.md | 12 +++---- website/docs/{intro => }/nomenclature.md | 2 +- website/docusaurus.config.js | 12 +++---- 6 files changed, 36 insertions(+), 34 deletions(-) rename website/docs/{intro => }/nomenclature.md (98%) diff --git a/website/blog/2023-11-10-liquidity-requirements.md b/website/blog/2023-11-10-liquidity-requirements.md index 34e9066..cab1f6c 100644 --- a/website/blog/2023-11-10-liquidity-requirements.md +++ b/website/blog/2023-11-10-liquidity-requirements.md @@ -18,7 +18,7 @@ All transactions within Ark must be funded by the Ark Service Provider (ASP) in This post discusses some considerations on this topic and calculates the funding needs of the ASP. -Refer to [nomenclature docs](./docs/intro/nomenclature) for any doubt +Refer to [nomenclature docs](/docs//nomenclature) for any doubt ## Ark liquidity requirements diff --git a/website/docs/intro.md b/website/docs/intro.md index 539a236..7d62fb3 100644 --- a/website/docs/intro.md +++ b/website/docs/intro.md @@ -4,29 +4,35 @@ sidebar_position: 1 slug: / --- -Welcome to Ark's documentation. Here you can learn more about the protocol, how to join the Ark and spend your coins off-chain in a fast and secure way. +Welcome to Ark's documentation. Here you can learn more about the protocol, how to provide liquidity and spend your coins off-chain in a fast and secure way. -- Be part of the community [joining our Telegram channel](https://t.me/ark_network_community). -- To report bugs or ask for support [open an issue on the Github repository](https://github.com/ark-network/support/issues/new). -- To propose improvements on protocol [open an issue on the Github repository](https://github.com/ark-network/boats/issues/new). +## 🤔 Why Ark? -### What is Ark? +Bitcoin is the most secure and censorship blockchain in the world. However, it is not the fastest or the cheapest. Ark is a **second-layer** solution designed to help **scale Bitcoin transactions** by using a shared utxo model that enables confidential and off-chain payments through an intermediary server that can't steal your funds. -Ark is a second-layer solution designed to help scale Bitcoin transactions by using a shared utxo model that enables anonymous, off-chain payments through an untrusted intermediary called the Ark Service Provider (ASP). ASPs are always-on servers that provide liquidity to the network, similar to how Lightning service providers work. +## 👷‍♂️ How does it work? -Ark is a scaling category of its own and is not a state channel design or a rollup. Ark is a liquidity network like Lightning that operates without introducing liquidity constraints or a direct link between the sender and receiver. It uses virtual utxos, to enable anonymous, scalable, off-chain payments. + Start by reading the [Nomenclature](/docs/nomenclature.md) section to understand the key concepts and terminology used in Ark. Then, you can learn how to [Board the Ark](intro/boarding.md) and [Send Payments](intro/payments.md). Finally, you can learn how to [Leave the Ark](intro/leaving.md) and withdraw your funds back to the Bitcoin blockchain if the server is unresponsive. -## How does it work? +## 👶🏼 ELI5 -- [Nomenclature](intro/nomenclature.md) -- [Boarding the Ark](intro/boarding.md) -- [Sendinf Payments](intro/payments.md) -- [Leaving the Ark](intro/leaving.md) +Think of early private banks that issued banknotes in exchange for gold deposits. In Ark's case, instead of gold, Bitcoin on the first layer acts as the reserve. The key difference is that the Bitcoin blockchain faces issues like slow transaction times, high fees, and limited capacity for numerous transactions. -## Protocol Specifications +Imagine Alice has some digital gold (Bitcoin) and wants to use it for everyday transactions without actually moving the gold each time. She deposits her digital gold with a digital bank (Server) and gets a promise note. Now, whenever she wants to pay Bob, instead of moving the actual gold, she tells the digital bank to transfer the promise note to Bob. The bank prepares a new promise note for Bob and takes back Alice's note. + +This system is convenient but also has a safety net. If the digital bank disappears or fails, anyone can still get their digital gold back without needing the bank's help. This is like being able to withdraw your gold from the old private bank even if the bank closed down. But unlike the old banks, where you had to physically go and get your gold, in Ark, this process is digital and automated, ensuring that your digital gold is always safe and accessible. + + +## 🤓 Protocol Specifications [Learn more about Ark](specs/00-index.md) +## Stay in the loop + +- Be part of the community [joining our Telegram channel](https://t.me/ark_network_community). +- Ask questions and get help [on Stack Overflow](https://bitcoin.stackexchange.com/questions/tagged/ark). +- To propose improvements on protocol [open an issue on the Github repository](https://github.com/ark-network/boats/issues/new). + ## Copyright By contributing to this repository, you agree to license your work under the MIT license unless specified otherwise at the top of the file itself. Any work contributed where you are not the original author must contain its license header with the original author(s) and source. diff --git a/website/docs/intro/boarding.md b/website/docs/intro/boarding.md index b9c06ce..cbc9a74 100644 --- a/website/docs/intro/boarding.md +++ b/website/docs/intro/boarding.md @@ -12,17 +12,17 @@ Alice wants to board the Ark of a well-known Ark service provider (ASP). It requ ### The timeline of events -1. Alice creates a [Funding transaction](./nomenclature#funding-transaction) +1. Alice creates a [Funding transaction](/docs/nomenclature#funding-transaction) -2. Alice adds any inputs she wants to cover the values the [VTXO](./nomenclature#vtxo-1) she will receive, plus on-chain fees. +2. Alice adds any inputs she wants to cover the values the [VTXO](/docs/nomenclature#vtxo-1) she will receive, plus on-chain fees. 3. Alice adds an output with **two spending conditions**: - `(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: + - A covenant output that forces coins to be spent by a [Redeem transaction](/docs/nomenclature#redeem-transaction) with an output with **two** spending conditions: - `(Alice + ASP)` - `(Alice in 24 hours)` -4. Alice notifies ASP about the [Funding transaction](./nomenclature#funding-transaction) +4. Alice notifies ASP about the [Funding transaction](/docs/nomenclature#funding-transaction) -5. Alice has now a [VTXO](./nomenclature#vtxo-1). +5. Alice has now a [VTXO](/docs/nomenclature#vtxo-1). diff --git a/website/docs/intro/payments.md b/website/docs/intro/payments.md index fe0c928..9857fe1 100644 --- a/website/docs/intro/payments.md +++ b/website/docs/intro/payments.md @@ -14,12 +14,12 @@ Alice wants to send funds to Bob inside the Ark. ### Timeline of events -1. Alice tells ASP to send [VTXO](./nomenclature#vtxo-1) to Bob -2. ASP (with Alice) prepares next [Pool transaction](./nomenclature#pool-transaction-aka-ark-transaction) -3. Alice creates a [Forfeit transaction](./nomenclature#forfeit-transaction): +1. Alice tells ASP to send [VTXO](/docs/nomenclature#vtxo-1) to Bob +2. ASP (with Alice) prepares next [Pool transaction](/docs/nomenclature#pool-transaction-aka-ark-transaction) +3. Alice creates a [Forfeit transaction](/docs/nomenclature#forfeit-transaction): - spends from VTXO (1) via `Alice + ASP` - adds connector output from Pool transaction (2) as input - signs (SIGHASH_ALL) and sends it to the ASP -4. ASP broadcasts [Pool transaction](./nomenclature#pool-transaction-aka-ark-transaction) -5. Bob has now a new [VTXO](./nomenclature#vtxo-1) -6. For at most 4 weeks, Alice will be able to double spend her’s [VTXO](./nomenclature#vtxo-1), but if she does it, the ASP will have time to grab the funds from the [VTXO](./nomenclature#vtxo-1) to itself using the [Forfeit transaction](./nomenclature#forfeit-transaction) +4. ASP broadcasts [Pool transaction](/docs/nomenclature#pool-transaction-aka-ark-transaction) +5. Bob has now a new [VTXO](/docs/nomenclature#vtxo-1) +6. For at most 4 weeks, Alice will be able to double spend her’s [VTXO](/docs/nomenclature#vtxo-1), but if she does it, the ASP will have time to grab the funds from the [VTXO](/docs/nomenclature#vtxo-1) to itself using the [Forfeit transaction](/docs/nomenclature#forfeit-transaction) diff --git a/website/docs/intro/nomenclature.md b/website/docs/nomenclature.md similarity index 98% rename from website/docs/intro/nomenclature.md rename to website/docs/nomenclature.md index c5e1b15..64e3a98 100644 --- a/website/docs/intro/nomenclature.md +++ b/website/docs/nomenclature.md @@ -79,7 +79,7 @@ Periodic transaction crafted by the ASP that hits mainchain and creates new VTXO - Represents a binary tree of transactions - In an optimistic scenario, this tree is never revealed -![Docusaurus Plushie](../img/shared_output.png) +![Docusaurus Plushie](./img/shared_output.png) ### VTXO\* diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js index 392f033..ce7c444 100644 --- a/website/docusaurus.config.js +++ b/website/docusaurus.config.js @@ -98,9 +98,9 @@ const config = { href: 'https://bitcoin.stackexchange.com/questions/tagged/ark', }, { - label: 'Twitter', - href: 'https://twitter.com/ark-network', - }, + label: 'Github', + href: 'https://github.com/ark-network', + } ], }, { @@ -109,11 +109,7 @@ const config = { { label: 'Blog', to: '/blog', - }, - { - label: 'GitHub', - href: 'https://github.com/ark-network', - }, + } ], }, ],