Merge branch 'staging' into rework-testing

docs/architecture.mdx

@@ -151,7 +151,7 @@ Optionally, this node can open its RPC interface to serve different kinds of req
 
 For more information about the architecture of Tezos, see:
 
-- [Accounts](./architecture/accounts)
+- [Accounts and addresses](./architecture/accounts)
 - [Tokens](./architecture/tokens)
 - [Smart Optimistic Rollups](./architecture/smart-rollups)
 - [Governance](./architecture/governance)

docs/architecture/accounts.md

@@ -1,21 +1,27 @@
 ---
-title: Accounts
+title: Accounts and addresses
 authors: "Tim McMackin"
 last_update:
-  date: 29 December 2023
+  date: 10 January 2024
 ---
 
+## Accounts
+
 Tezos uses these types of accounts:
 
-- Classic accounts (also known as _implicit accounts_) store tez (ꜩ) and tickets.
-These accounts have addresses that start with "tz1", "tz2", "tz3" or "tz4."
-Any wallet application or the Octez command-line tool can create implicit accounts.
+- User accounts (sometimes known as _implicit accounts_) store tez (ꜩ) and tickets.
+Any wallet application or the Octez command-line tool can create user accounts.
 
-- Smart contract accounts (also known as _originated accounts_) store immutable code, mutable storage, tez (ꜩ), and tickets.
-Smart contracts have addresses that start with "KT1."
+- Smart contract accounts (sometimes known as _originated accounts_) store immutable code, mutable storage, tez (ꜩ), and tickets.
 See [Smart contracts](../smart-contracts).
 
-- Smart Rollup accounts are another type of originated account.
-Their addresses start with `SR1`.
+## Addresses
+
+- User accounts have addresses that start with "tz1", "tz2", "tz3" or "tz4."
+
+- Smart contracts have addresses that start with "KT1."
+
+- Smart Rollups have addresses, but are not accounts because they cannot store tez.
+Their addresses start with "SR1".
 They have a tree of commitments attached to them.
 See [Smart Optimistic Rollups](./smart-rollups).

docs/architecture/smart-rollups.mdx

@@ -0,0 +1,172 @@
+---
+title: Smart Rollups
+authors: 'Nomadic Labs, TriliTech, Tim McMackin'
+last_update:
+  date: 18 January 2024
+---
+
+import LucidDiagram from '@site/src/components/LucidDiagram';
+
+Smart Rollups play a crucial part in providing high scalability on Tezos.
+They handle logic in a separate environment that can run transactions at a much higher rate and can use larger amounts of data than the main Tezos network.
+
+The transactions and logic that Smart Rollups run is called _layer 2_ to differentiate it from the main network, which is called _layer 1_.
+
+Anyone can run a node based on a Smart Rollup to execute its code and verify that other nodes are running it correctly, just like anyone can run nodes, bakers, and accusers on layer 1.
+This code, called the _kernel_, runs in a deterministic manner and according to a given semantics, which guarantees that results are reproducible by any rollup node with the same kernel.
+The semantics is precisely defined by a reference virtual machine called a proof-generating virtual machine (PVM), able to generate a proof that executing a program in a given context results in a given state.
+During normal execution, the Smart Rollup can use any virtual machine that is compatible with the PVM semantics, which allows the Smart Rollup to be more efficient.
+
+Using the PVM and optionally a compatible VM guarantees that if a divergence in results is found, it can be tracked down to a single elementary step that was not executed correctly by some node.
+In this way, multiple nodes can run the same rollup and each node can verify the state of the rollup.
+
+For a tutorial on Smart Rollups, see [Deploy a Smart Rollup](../tutorials/smart-rollup).
+
+For reference on Smart Rollups, see [Smart Optimistic Rollups](https://tezos.gitlab.io/active/smart_rollups.html) in the Octez documentation.
+
+This diagram shows a high-level view of how Smart Rollups interact with layer 1:
+
+<LucidDiagram width="640px" height="480px" src="https://lucid.app/documents/embedded/1e176e48-5c1a-457c-af3e-2f66d3c1b893" id="iB96FUquB~sm" />
+
+## Uses for Smart Rollups
+
+- Smart Rollups allow you to run large amounts of processing and manipulate large amounts of data that would be too slow or expensive to run on layer 1.
+
+- Smart Rollups can run far more transactions per second than layer 1.
+
+- Smart Rollups allow you to avoid some transaction fees and storage fees.
+
+- Smart Rollups can retrieve data from outside the blockchain in specific ways that smart contracts can't.
+
+- Smart Rollups can implement different execution environments, such as execution environments that are compatible with other blockchains.
+For example, Smart Rollups enable [Etherlink](https://www.etherlink.com/), which makes it possible to run EVM applications (originally written for Ethereum) on Tezos.
+
+## Communication
+
+Smart Rollups have access to two sources of information: the rollup inbox and the reveal data channel.
+These are the only sources of information that rollups can use.
+In particular, Smart Rollup nodes cannot communicate directly with each other; they do not have a peer-ro-peer communication channel like layer 1 nodes.
+
+### Rollup inbox
+
+Each layer 1 block has a _rollup inbox_ that contains messages from layer 1 to all rollups.
+Anyone can add a message to this inbox and all messages are visible to all rollups.
+Smart Rollups filter the inbox to the messages that they are interested in and act on them accordingly.
+
+The messages that users add to the rollup inbox are called _external messages_.
+For example, users can add messages to the inbox with the Octez client `send smart rollup message` command.
+
+Similarly, smart contracts can add messages in a way similar to calling a smart contract entrypoint, by using the Michelson `TRANSFER_TOKENS` instruction.
+The messages that smart contracts add to the inbox are called _internal messages_.
+
+Each block also contains the following internal messages, which are created by the protocol:
+
+- `Start of level`, which indicates the beginning of the block
+- `Info per level`, which includes the timestamp and block hash of the preceding block
+- `End of level`, which indicates the end of the block
+
+Smart Rollup nodes can use these internal messages to know when blocks begin and end.
+
+### Reveal data channel
+
+Smart Rollups can request arbitrary information through the _reveal data channel_.
+Importantly, as opposed to internal and external messages, the information that passes through the reveal data channel does not pass through layer 1, so it is not limited by the bandwidth of layer 1 and can include large amounts of data.
+
+The reveal data channel supports these requests:
+
+- A rollup node can request an arbitrary data page up to 4KB if it knows the blake2b hash of the page, known as _preimage requests_.
+To transfer more than 4KB of data, rollups must use multiple pages, which may contain hashes that point to other pages.
+
+- A rollup node can request information about the rollup, including the address and origination level of the rollup, known as _metadata requests_.
+
+{/*
+TODO how is this data provided?
+Where does it come from?
+Do we need instructions on how to provide data?
+Eventually include:
+  - importing data from a DAC certificate (which can contain anything ultimately, including a kernel to upgrade to)
+  - revealing data from the (WIP) DAL
+*/}
+
+## Smart Rollup lifecycle
+
+The general flow of a Smart Rollup goes through these phases:
+
+1. Origination: A user called the _rollup operator_ originates the Smart Rollup to layer 1 and one or more users start nodes based on that Smart Rollup to independently verify its operation.
+1. Commitment periods: The Smart Rollup nodes receive the messages in the Smart Rollup inbox, run processing based on those messages, generate but do not run outbox messages, and publish a hash of their state at the end of the period, called a commitment.
+1. Refutation periods: Nodes can publish a concurrent commitment to refute a published commitment.
+1. Triggering outbox messages: When the commitment can no longer be refuted, any client can trigger outbox messages, which create transactions.
+
+Here is more information on each of these phases:
+
+{/* TODO diagram of commitment periods and refutation periods? */}
+
+### Origination
+
+Like smart contracts, users deploy Smart Rollups to layer 1 in a process called _origination_.
+
+The origination process stores data about the rollup on layer 1, including:
+
+- An address for the rollup, which starts with `sr1`
+- The type of proof-generating virtual machine (PVM) for the rollup, which defines the execution engine of the rollup kernel; currently only the `wasm_2_0_0` PVM is supported
+- The installer kernel, which is a WebAssembly program that allows nodes to download and install the complete rollup kernel
+- The Michelson data type of the messages it receives from layer 1
+- The genesis commitment that forms the basis for commitments that rollups nodes publish in the future
+
+After it is originated, anyone can run a Smart Rollup node based on this information.
+
+### Commitment periods
+
+Starting from the rollup origination level, levels are partitioned into _commitment periods_ of 60 consecutive layer 1 blocks.
+During each commitment period, each rollup node receives the messages in the rollup inbox, processes them, and updates its state.
+
+Because Smart Rollup nodes behave in a deterministic manner, their states should all be the same if they have processed the same inbox messages with the same kernel starting from the same origination level.
+This state is referred to as the "state of the rollup."
+
+At the end of a commitment period, the next commitment period starts.
+
+Any time after each commitment period, at least one rollup node must publish a hash of its state to layer 1, which is called its _commitment_.
+Each commitment builds on the previous commitment, and so on, back to the genesis commitment from when the Smart Rollup was originated.
+
+Nodes must stake 10,000 tez along with their commitments.
+When nodes make identical commitments, their stakes are combined into a single stake for the commitment.
+
+### Refutation periods
+
+Because the PVM is deterministic and all of the inputs are the same for all nodes, any honest node that runs the same Smart Rollup produces the same commitment.
+As long as nodes publish matching commitments, they continue running normally.
+
+When the first commitment for a past commitment period is published, a refutation period starts, during which any rollup node can publish its own commitment for the same commitment period, especially if it did not achieve the same state.
+During the refutation period for a commitment period, if two or more nodes publish different commitments, two of them play a _refutation game_ to identify the correct commitment.
+The nodes automatically play the refutation game by stepping through their logic using the PVM to identify the point at which they differ.
+At this point, the PVM is used to identify the correct commitment, if any.
+
+Each refutation game has one of two results:
+
+- Neither commitment is correct.
+In this case, the protocol burns both commitments' stakes and eliminates both commitments.
+
+- One commitment is correct and the other is not.
+In this case, the protocol eliminates the incorrect commitment, burns half of the incorrect commitment's stake, and gives the other half to the correct commitment's stake.
+
+This refutation game happens as many times as is necessary to eliminate incorrect commitments.
+Because the node that ran the PVM correctly is guaranteed to win the refutation game, a single honest node is enough to ensure that the Smart Rollup is running correctly.
+This kind of Smart Rollup is called a Smart Optimistic Rollup because the commitments are assumed to be correct until they are proven wrong by an honest rollup node.
+
+When there is only one commitment left, either because all nodes published identical commitments during the whole refutation period or because this commitment won the refutation games and eliminated all other commitments, then this correct commitment can be _cemented_ by a dedicated layer 1 operation and becomes final and unchangeable.
+The commitments for the next commitment period build on the last cemented commitment.
+
+The refutation period lasts 2 weeks on Mainnet; it can be different on other networks.
+
+### Triggering outbox messages
+
+Smart Rollups can generate transactions to run on layer 1, but those transactions do not run immediately.
+When a commitment includes layer 1 transactions, these transactions go into the Smart Rollup outbox and wait for the commitment to be cemented.
+
+After the commitment is cemented, clients can trigger transactions in the outbox with the Octez client `execute outbox message` command.
+When they trigger a transaction, it runs like any other call to a smart contract.
+For more information, see [Triggering the execution of an outbox message](https://tezos.gitlab.io/shell/smart_rollup_node.html?highlight=triggering) in the Octez documentation.
+
+## Examples
+
+For examples of Smart Rollups, see this repository: https://gitlab.com/tezos/kernel-gallery.

docs/architecture/tokens.md

@@ -21,7 +21,7 @@ One exception is tickets, which are directly stored and managed by smart contrac
 To learn about tokens, see these tutorials:
 
 - [Create an NFT](../tutorials/create-an-nft)
-- [Build your first app on Tezos](../tutorials/build-your-first-app)
+- [Build a simple web application](../tutorials/build-your-first-app)
 
 ## Fungible and non-fungible tokens
 

docs/dApps.mdx

@@ -47,6 +47,6 @@ For information on typical tasks that dApps do, see:
 
 These tutorials cover dApps of different complexities:
 
-- For a simple dApp, see [Build your first app on Tezos](./tutorials/build-your-first-app)
+- For a simple dApp, see [Build a simple web application](./tutorials/build-your-first-app)
 - For a dApp that mints NFTs, see [Mint NFTs from a web app](./tutorials/create-an-nft/nft-web-app)
 - For a large dApp that allows users to buy and sell NFTs, see [Build an NFT marketplace](./tutorials/build-an-nft-marketplace)

docs/dApps/sending-transactions.md

@@ -82,7 +82,7 @@ try {
 }
 ```
 
-For examples of calling smart contracts, see tutorials such as [Build your first app on Tezos](../tutorials/build-your-first-app) or [Create a contract and web app that mints NFTs](../tutorials/create-an-nft/nft-taquito).
+For examples of calling smart contracts, see tutorials such as [Build a simple web application](../tutorials/build-your-first-app) or [Create a contract and web app that mints NFTs](../tutorials/create-an-nft/nft-taquito).
 
 For more information about using Taquito, see [Smart contracts](https://tezostaquito.io/docs/smartcontracts) in the Taquito documentation.
 

docs/dApps/taquito.md

@@ -89,13 +89,13 @@ Tezos.setWalletProvider(wallet)
 
 ## Getting data from the Tezos blockchain
 
-Taquito provides methods to get different types of data from the Tezos blockchain, for example, the balance of an implicit account, the storage of a contract or token metadata.
+Taquito provides methods to get different types of data from the Tezos blockchain, for example, the balance of a user account, the storage of a contract or token metadata.
 
 > Note: querying data from the blockchain doesn't create a new transaction.
 
 ### Getting the balance of an account
 
-Taquito allows developers to get the current balance in tez of an implicit account. The `getBalance` method is available on the instance of the TezosToolkit and requires a parameter of type `string` that represents the address of the account.
+Taquito allows developers to get the current balance in tez of a user account. The `getBalance` method is available on the instance of the TezosToolkit and requires a parameter of type `string` that represents the address of the account.
 
 The returned value is of type `BigNumber`:
 

docs/dApps/wallets.md

@@ -29,7 +29,7 @@ The primary tools that dApps use to connect to wallets are:
 ## Beacon and Taquito
 
 Most of the time, dApps use Beacon and Taquito together for a straightforward way to connect to wallets and submit transactions.
-For an example, see the tutorial [Build your first app on Tezos](../tutorials/build-your-first-app).
+For an example, see the tutorial [Build a simple web application](../tutorials/build-your-first-app).
 
 ### Connecting to wallets
 
@@ -49,7 +49,7 @@ const address = await wallet.getPKH();
 When this code runs, Beacon opens a popup window that guides the user through connecting their wallet.
 
 Then the application can send transactions to Tezos.
-See [Part 3: Sending transactions](../tutorials/build-your-first-app/sending-transactions) in the tutorial [Build your first app on Tezos](../tutorials/build-your-first-app).
+See [Part 3: Sending transactions](../tutorials/build-your-first-app/sending-transactions) in the tutorial [Build a simple web application](../tutorials/build-your-first-app).
 
 ### Reconnecting to wallets
 

docs/overview/common-applications.md

@@ -22,7 +22,7 @@ Tezos is being used by the French Armies and Gendarmerie's Information Center to
 
 In recent years, the concept of Central Bank Digital Currencies (CBDCs) has gained traction, with several countries around the world exploring their own CBDC projects. Société Générale carried out a series of successful tests [using Tezos](https://decrypt.co/112127/societe-generales-crypto-division-lands-regulatory-approval-france) to explore the potential of CBDCs. In September 2020, the bank announced that it had completed a pilot program using a custom-built version of the Tezos blockchain to simulate the issuance and circulation of CBDCs. The pilot involved testing the technology's ability to handle transactions, make payments, and settle transactions in a digital environment.
 
-The Califonia DMV is also using Tezos for its project to [put car titles on the blockchain](https://fortune.com/crypto/2023/01/26/california-announces-dmv-run-blockchain-through-partnership-with-tezos/).
+The California DMV is also using Tezos for its project to [put car titles on the blockchain](https://fortune.com/crypto/2023/01/26/california-announces-dmv-run-blockchain-through-partnership-with-tezos/).
 
 [Sword Group](https://www.sword-group.com/2020/09/28/sword-launches-tezos-digisign/) an international technology company, launched DigiSign, an open-source tool built on Tezos that enables users to digitally sign, certify, and verify the authenticity of digital documents.