From 55c4148d144220f5cf06d884fbf7eb08c947cb2a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matev=C5=BE=20Jekovec?= Date: Thu, 30 May 2024 13:27:43 +0200 Subject: [PATCH] docs: Adds instant finality subsection --- docs/guide.mdx | 60 ++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 43 insertions(+), 17 deletions(-) diff --git a/docs/guide.mdx b/docs/guide.mdx index 09aefd269..7314f0a71 100644 --- a/docs/guide.mdx +++ b/docs/guide.mdx @@ -24,16 +24,17 @@ your contract to a non-confidential EVM network (e.g., Ropsten, Emerald). The Oasis Network consists of the consensus layer and a number of ParaTimes. ParaTimes are independent replicated state machines that settle transactions using the consensus layer (to learn more, check the [Oasis Network -Overview][overview chapter]). Sapphire is a ParaTime which implements the Ethereum -Virtual Machine (EVM). +Overview][overview chapter]). Sapphire is a ParaTime which implements the +Ethereum Virtual Machine (EVM). The minimum and also expected block time in Sapphire is **6 seconds**. Any Sapphire transaction will require at least this amount of time to be executed, and probably no more. -ParaTimes, Sapphire included, are not allowed to directly access your tokens stored -in consensus layer accounts. You will need to _deposit_ tokens from your consensus -account to Sapphire. Consult the [Manage your Tokens][how-to-deposit-rose] chapter to learn more. +ParaTimes, Sapphire included, are not allowed to directly access your tokens +stored in consensus layer accounts. You will need to _deposit_ tokens from your +consensus account to Sapphire. Consult the [Manage your +Tokens][how-to-deposit-rose] chapter to learn more. [overview chapter]: https://github.com/oasisprotocol/docs/blob/main/docs/general/oasis-network/README.mdx @@ -74,15 +75,23 @@ ParaTime. ## Sapphire vs Ethereum Sapphire is generally compatible with Ethereum, the EVM, and all the user and -developer tooling that you are already used to. In addition to confidentiality -features, you get a few extra benefits including the ability to generate private -entropy, and make signatures on-chain. An example of a dApp that uses both is an -HSM contract that generates an Ethereum wallet and signs transactions sent to it -via transactions. +developer tooling that you are used to. In addition to confidentiality +features, you get a few extra benefits including the ability to **generate +private entropy**, and **make signatures on-chain**. An example of a dApp that +uses both is an HSM contract that generates an Ethereum wallet and signs +transactions sent to it via transactions. There are also a few breaking changes compared to Ethereum though, but we think -that you'll quickly grasp them. Otherwise, Sapphire is like Emerald, a fast, -cheap Ethereum. +that you'll quickly grasp them: + +- [Encrypted Contract State](#encrypted-contract-state) +- [End-to-End Encrypted Transactions and Calls](#end-to-end-encrypted-transactions-and-calls) +- [`from` Address is Zero for Unsigned Calls](#from-address-is-zero-for-unsigned-calls) +- [Override `receive` and `fallback` when Funding the Contract](#override-receive-and-fallback-when-funding-the-contract) +- [Instant Finality](#instant-finality) + +Read below to learn more about them. Otherwise, Sapphire is like Emerald, a +fast, cheap Ethereum. ### Encrypted Contract State @@ -123,20 +132,37 @@ If no such functions exist, the transaction will revert. The behavior described above is the same in Sapphire when using EVM transactions to fund a contract. -However, the Oasis network also uses [Oasis-native transactions] such as a +However, the Oasis Network also uses [Oasis-native transactions] such as a deposit to a ParaTime account or a transfer. In this case, **you will be able to fund the contract's account even though the contract may not implement payable `receive()` or `fallback()`!** Or, if these functions do exist, **they will not -be triggered**. You can send such Oasis-native transactions by using the [Oasis CLI] for example. +be triggered**. You can send such Oasis-native transactions by using the [Oasis +CLI] for example. [Oasis-native transactions]: https://github.com/oasisprotocol/docs/blob/main/docs/general/manage-tokens/README.mdx [Oasis CLI]: https://github.com/oasisprotocol/cli/blob/master/docs/README.md +### Instant Finality + +The Oasis Network is a proof of stake network where 2/3+ of the validator nodes +need to verify each block in order to consider it final. However, in Ethereum +the signatures of those validator nodes can be submitted minutes after the block +is proposed, which makes the block proposal mechanism independent of the +validation, but adds uncertainty if and when will the proposed block actually be +finalised. + +In the Oasis Network, the 2/3+ of **signatures** need to be provided immediately +after the block is proposed and **the network will halt, until the required +number signatures are provided**. This means that you can rest assured that any +validated block is final. As a consequence, the cross-chain bridges are more +responsive yet safe on the Oasis Network. + ## Integrating Sapphire -Once ROSE tokens are [deposited into Sapphire][how-to-deposit-rose], it should be painless for users to begin -using dApps. To achieve this ideal user experience, we have to modify the dApp a little, -but it's made simple by our compatibility library, [@oasisprotocol/sapphire-paratime]. +Once ROSE tokens are [deposited into Sapphire][how-to-deposit-rose], it should +be painless for users to begin using dApps. To achieve this ideal user +experience, we have to modify the dApp a little, but it's made simple by our +compatibility library, [@oasisprotocol/sapphire-paratime]. There are compatibility layers in other languages, which may be found in [the repo].