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
matevz committed May 31, 2024
1 parent dc16879 commit 996ed46
Showing 1 changed file with 66 additions and 40 deletions.
106 changes: 66 additions & 40 deletions docs/guide.mdx
View file
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 All @@ -105,42 +114,59 @@ message and logs (emitted events).

### `from` Address is Zero for Unsigned Calls

The `from` address using of calls is derived from a signature attached to the call.
Unsigned calls have their sender set to the zero address. This allows contract authors
to write getters that release secrets to authenticated callers, but without
requiring a transaction to be posted on-chain.
The `from` address using of calls is derived from a signature attached to the
call. Unsigned calls have their sender set to the zero address. This allows
contract authors to write getters that release secrets to authenticated callers
(e.g. by checking the `msg.sender` value), but without requiring a transaction
to be posted on-chain.

### Override `receive` and `fallback` when Funding the Contract

In Ethereum, you can fund a contract by sending Ether along the transaction in
two ways:

1. a transaction must call a *payable* function in the contract, or
2. not specifying any function to call (i.e. empty *calldata*). In this case,
the payable `receive()` and/or `fallback()` functions need to be defined.
If no such functions exist, the transaction will revert.
2. not calling any specific function (i.e. empty *calldata*). In this case,
the payable `receive()` and/or `fallback()` functions need to be defined in
the contract. 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
finalized.

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].


[@oasisprotocol/sapphire-paratime]: https://www.npmjs.com/package/@oasisprotocol/sapphire-paratime
[the repo]: https://github.com/oasisprotocol/sapphire-paratime/tree/main/clients

Expand Down Expand Up @@ -354,41 +380,41 @@ docker run -it -p8545:8545 -p8546:8546 ghcr.io/oasisprotocol/sapphire-localnet
After a while, the tool will show you something like this:

```
sapphire-localnet 2024-05-21-gita256999 (oasis-core: 23.0.11-git8b45ece, sapphire-paratime: 0.7.3-testnet, oasis-web3-gateway: 5.0.1-gita256999)
sapphire-localnet 2024-05-28-git37b7166 (oasis-core: 24.0-gitfb49717, sapphire-paratime: 0.7.3-testnet, oasis-web3-gateway: 5.1.0)

* Starting oasis-net-runner with sapphire...
* Waiting for Postgres to start....
* Waiting for Oasis node to start....
* Waiting for Postgres to start...
* Waiting for Oasis node to start.....
* Starting oasis-web3-gateway...
* Bootstrapping network (this might take a minute)...
* Waiting for key manager......
* Populating accounts...

Available Accounts
==================
(0) 0xD72686fa546E7db3059Ab7c9EBd8D8D36D55e2B8 (10000 TEST)
(1) 0xe3392eBBB500ba63fb299C3Defaa4B2c1d4Debde (10000 TEST)
(2) 0xe691f8AA4956AF75eFD1fAEcDdCd97D6005f6d28 (10000 TEST)
(3) 0xB9193994d0821e76ce86b947fcE9E4A060658bB4 (10000 TEST)
(4) 0x9b9dDb47fF31a4Cf7d9a35FC69A34785C740dd35 (10000 TEST)
(0) 0x41b0C13e747F8Cb1c4E980712504437cb1792327 (10000 TEST)
(1) 0xa521f94f8a38b1d027D526017EB229327B9D6cA0 (10000 TEST)
(2) 0x1e0f8369215D6C5Af5E14eD6A0D6ae7372776A79 (10000 TEST)
(3) 0xB60cA28B491747a27C057AdBF3E71F3CCC52332C (10000 TEST)
(4) 0x88D7d924e521a6d07008a373D5b33281148ffEDc (10000 TEST)

Private Keys
==================
(0) 0xf419a48e651b68237b64045340036860b736e57430fd6b6269348b45a3a02a4c
(1) 0x8fd8347f30bdeca501777093beb464c7df049f042f379dc90d7c8e56068353d2
(2) 0xcc57ace9e658d041ae0a97451e92f0986e8685bfdd3cbea2a9b808733e037447
(3) 0x92c704ecc72cd8e318fc5c4891fc4c3ffee368d8e280aba6eae99248323faf09
(4) 0x9b4c1384be57849daec2574188565e4f81cababb368f8b90fcf6feb02f1d784e
(0) 0x617346c545d62b8213ea907acf1b570a7405683e2c6dcaf963fc21fd677e0c56
(1) 0xf82d6e09208b0bd44a397f7e73b05c564e6c9f70b151ee7677e2bb8d6ce5d882
(2) 0xeb2f21d20086f3dd6bfe7184dad1cb8b0fb802f27b1334e836a19eda0a43a1c2
(3) 0x82b0203d6063992b1052004b90411c45d4f3afab696346f006e74c6abd8f855e
(4) 0x7179c6e1add3a2993822653b9c98fe606f47fb6d4c0d0d81b31b067cf6bb5f83

HD Wallet
==================
Mnemonic: kind soccer lucky cream another choice horn poem gloom sock interest announce
Mnemonic: coach genre beach child crunch champion tell adult critic peace canoe stable
Base HD Path: m/44'/60'/0'/0/%d

WARNING: The chain is running in ephemeral mode. State will be lost after restart!

* Listening on http://localhost:8545 and ws://localhost:8546. Chain ID: 0x5afd
* Container start-up took 61 seconds, node log level is set to warn.
* Container start-up took 66 seconds, node log level is set to warn.
```

Those familiar with local dApp environments will find the output above similar
Expand Down

0 comments on commit 996ed46

Please sign in to comment.