Skip to content

Commit

Permalink
docs: Adds instant finality subsection
Browse files Browse the repository at this point in the history
  • Loading branch information
matevz committed May 31, 2024
1 parent dc16879 commit 55c4148
Showing 1 changed file with 43 additions and 17 deletions.
60 changes: 43 additions & 17 deletions docs/guide.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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].

Expand Down

0 comments on commit 55c4148

Please sign in to comment.