Update main from staging, Feb 29

docs/architecture.md

@@ -104,7 +104,7 @@ For example, different bakers may implement different transaction selection stra
 
 The node accepts calls from clients through its RPC interface.
 It has control over which clients to accept calls from, which calls to accept, or whether to accept RPC calls at all.
-For more information on the RPC interface, see [The RPC protocol](./architecture/rpc).
+For more information on the RPC interface, see [The RPC interface](./architecture/rpc).
 
 ### The baker daemon
 

docs/architecture/governance.md

@@ -1,50 +1,84 @@
 ---
-title: Governance
+title: Governance and self-amendment
 last_update:
-  date: 3 July 2023
+  date: 27 February 2024
 ---
 
-## What is Self Amendment?
+Tezos incorporates a built-in, on-chain mechanism for proposing, selecting, testing, and activating protocol upgrades without the need to hard fork.
+This mechanism makes Tezos a self-amending blockchain and allows any user to propose changes to the [economic protocol](../architecture#the-tezos-self-amending-protocol), which defines the possible blockchain operations and how they are processed.
 
-Tezos is a self-amending blockchain network that incorporates an on-chain mechanism for proposing, selecting, testing, and activating protocol upgrades without the need to hard fork.
 
-## How Does It Work?
+This self-amendment process is separate from the less formal [Tezos Improvement Process](./governance/improvement-process).
 
-The self-amendment process is split into 5 periods: Proposal Period, Exploration Vote Period, Cooldown Period, Promotion Vote Period, and Adoption Period. Each of these periods lasts five baking cycles (i.e. 40,960 blocks at 30-second intervals or roughly 14 days, 5 hours), comprising roughly 2 months and 10 days.
+## Amendment periods
 
-Should there be any failure to proceed for a period, the whole process reverts to the Proposal Period, effectively restarting the whole process.
+The self-amendment process is split into 5 periods, whose scheduling and operation are automatically handled by the protocol, as follows:
 
-#### 1. Proposal Period
+1. Proposal period: delegates propose changes to the Tezos protocol by submitting proposals and upvoting protocol amendment proposals.
+If a quorum is met, the top-voted proposal moves to the next period.
+1. Exploration period: Users vote whether to consider the top-voted proposal
+1. Cooldown period: If a proposal is selected in the Exploration period, a Cooldown period starts before the final election is made. The community can continue testing the new protocol proposal and preparing their infrastructure, before the final decision is made.
+1. Promotion period: Users make a final vote on whether to apply the proposal
+1. Adoption period: Users adapt their code and infrastructure to the proposal, and at the end of the period it is activated automatically
 
-The Tezos amendment process begins with the Proposal Period, during which bakers can submit proposals on-chain. The baker submits the proposal by submitting the hash of the source code.
+Each period lasts five blockchain cycles (40,960 blocks at 30-second intervals or roughly 14 days, 5 hours), comprising roughly 2 months and 10 days.
 
-In each Proposal Period, bakers can submit up to 20 proposals. A proposal submission also counts as a vote, which is equivalent to the number of rolls in its staking balance at the start of the period. Other bakers can then vote on the proposals during the Proposal Period up to 20 times.
+Only [delegates](../overview/glossary#delegate) can vote on proposals.
+A delegate's voting power is the amount of tez that it has staked plus the tez that delegators have delegated to it, also called its _staking balance_.
 
-At the end of the Proposal Period, the network counts the proposal votes and the most-upvoted proposal proceeds to the Exploration Vote Period. If no proposals have been submitted or if there is a tie between proposals, a new Proposal Period begins.
+### 1. Proposal period
 
-#### 2. Exploration Vote Period
+The Tezos amendment process begins with the Proposal period, during which delegates can submit proposals to change the Tezos protocol.
+The delegate submits the proposal by submitting the hash of the source code.
 
-In the Exploration Vote Period, bakers may vote on the top-ranked proposal from the previous Proposal Period. Bakers get to vote either "Yea", "Nay", or "Pass" on a specific proposal. "Pass" just means to "not vote" on a proposal. As in the Proposal Period, a baker's vote is based on the number of rolls in its staking balance.
+Each delegate can submit up to 20 proposals in a single Proposal period.
+A proposal submission also counts as a vote, which is equivalent to the amount of tez in its staking balance at the start of the period.
+Other delegates can vote for up to 20 proposals during this period.
 
-At the end of the Exploration Vote Period, the network counts the votes. If voting participation (the total of “Yea,” “Nay,” and “Pass”) meets the target, and an 80% majority of non-abstaining bakers approve, the proposal proceeds to the Testing Period.
+At the end of the Proposal period, the network counts the proposal votes and if a quorum is met, the most-upvoted proposal proceeds to the Exploration period.
+If no proposals have been submitted or if there is a tie between proposals, no proposal proceeds and a new Proposal period begins.
 
-The voting participation target tries to match the exponential moving average of the past participation rate. If the voting participation fails to achieve the target or the 80% supermajority is not met, the amendment process restarts at the beginning of the Proposal Period
+### 2. Exploration period
 
-#### 3. Cooldown Period
+In the Exploration period, delegates vote on whether to consider the top-ranked proposal from the previous Proposal period.
+Delegates can vote either "Yea", "Nay", or "Pass" on that proposal.
+"Pass" means to "not vote" on a proposal.
+As in the Proposal period, a delegate's voting power is based on the amount of tez in its staking balance.
 
-Previously, during the voting process, a test chain would be spun up during the “testing period” which took place between the exploration and promotion voting periods. The intent was that this test chain be used to verify that the new proposal worked correctly, but in practice, the test chain has never been used in this manner and has caused significant operational problems to node operators.
+At the end of the Exploration period, the network counts the votes.
+To pass, the proposal must meet both of these standards:
 
-The Florence upgrade eliminates the test chain activation, the testing period has been retained but is now named the “cooldown period”. Instead, testing the protocol continues by using test chains that operate outside of the Mainnet voting process.
+- Quorum: A quorum of all of the voting power in the system must vote either "Yea", "Nay", or "Pass."
+The amount of the quorum changes dynamically based on previous votes, which allows the system to adjust to the amount of delegates that participate in voting.
 
-#### 4. Promotion Vote Period
+- Supermajority: The total voting power of the Yea votes must be greater than 80% of the total voting power of the Yea and Nay votes combined.
+Pass votes are not counted in this equation.
 
-At the end of the Testing Period, the Promotion Vote Period begins. In this period, the network decides whether to adopt the amendment based on off-chain discussions and its behavior during the Testing Period. As in the Exploration Vote Period, bakers submit their votes using the ballot operation, with their votes weighted proportionally to the number of rolls in their staking balance.
+If the proposal meets both of those standards, it moves to the Cooldown period.
+If not, it fails and a new Proposal period starts.
 
-At the end of the Promotion Vote Period, the network counts the number of votes. If the participation rate reaches the minimum quorum and an 80% supermajority of non-abstaining bakers votes “Yea,” then the proposal is activated as the new Mainnet. Otherwise, the process once more reverts to the Proposal Period. The minimum vote participation rate is set based on past participation rates.
+### 3. Cooldown period
 
-See [the full details of the governance process](https://medium.com/tezos/amending-tezos-b77949d97e1e).
+The Cooldown period is a delay in the process that gives users time to review and test the new version of the protocol.
+The community sets up test networks that use the new version of the protocol.
+Users verify that the protocol update works, see how their baking infrastructure works with it, and discusses the proposal.
 
-#### 5. Adoption Period
+### 4. Promotion period
 
-The Adoption Period provides a "cooldown" allowing developers and bakers some additional time to adapt their code and infrastructure to the upgrade based on the results of the Promotion Vote Period.
+At the end of the Cooldown period, the Promotion period begins, which is the last vote.
+In this period, users decide whether to adopt the proposal into Mainnet.
 
+The voting requirements are the same as in the Exploration period, including the quorum and supermajority.
+
+If the proposal passes, it moves to the Adoption period.
+If it fails, a new Proposal period starts.
+
+### 5. Adoption period
+
+The Adoption period is a delay in the process that gives developers and bakers additional time to adapt their code and infrastructure to the new protocol.
+At the end of the Adoption period, Mainnet automatically enables the new protocol and a new Proposal period begins.
+
+## References
+
+- [The Amendment (and Voting) Process](https://tezos.gitlab.io/active/voting.html) in the Octez documentation
+- [Amending Tezos](https://medium.com/tezos/amending-tezos-b77949d97e1e) on Medium

docs/architecture/rpc.md

@@ -1,13 +1,13 @@
 ---
-title: The RPC protocol
+title: The RPC interface
 authors: "Tim McMackin"
 last_update:
   date: 6 February 2023
 ---
 
-The Tezos RPC (Remote Procedure Call) protocol is a specification for a REST API that clients use to interact with Tezos nodes and nodes use to communicate with each other.
-Clients use this protocol to submit transactions and get information about the state of the blockchain, such as account balances and contract storage.
-Tezos nodes act as servers and accept HTTP requests from clients and other nodes via this protocol.
+The Tezos RPC (Remote Procedure Call) interface is a specification for a REST API that clients use to interact with Tezos nodes and nodes use to communicate with each other.
+Clients use this interface to submit transactions and get information about the state of the blockchain, such as account balances and contract storage.
+Tezos nodes act as servers and accept HTTP requests from clients and other nodes via this interface.
 
 Tezos RPC uses JSON to send and receive data, but it does not adhere to the JSON-RPC specification.
 

docs/architecture/tokens/FA1.2.md

@@ -2,7 +2,7 @@
 title: FA1.2 tokens
 authors: "Claude Barde, Aymeric Bethencourt, Tim McMackin"
 last_update:
-  date: 26 October 2023
+  date: 22 February 2024
 ---
 
 The FA1.2 standard is for _fungible tokens_, which are collections of identical, interchangeable tokens.
@@ -11,7 +11,7 @@ Commonly used FA1.2 tokens include kUSD and Ctez.
 
 Contracts that follow this standard keep a ledger that records how many tokens different accounts own.
 They have entrypoints that allow users to transfer tokens and limit the amount that can be transferred.
-They also have views that provide information such as the total amount of tokens and the amount of tokens that a specified account owns.
+They also have entrypoints that provide information such as the total amount of tokens and the amount of tokens that a specified account owns.
 
 For the full details of the FA1.2 standard, see [Tezos Improvement Proposal 7 (TZIP-7)](https://gitlab.com/tezos/tzip/-/blob/master/proposals/tzip-7/tzip-7.md), which defines the standard.
 
@@ -55,7 +55,7 @@ FA1.2 contracts must have these entrypoints:
   The transaction sender must be an address that has been authorized to transfer the tokens via the `approve` endpoint, even if the transaction sender and address that owns the tokens is the same address.
   After the transfer, the sender's allowance is decrease by the amount of tokens transferred.
 
-FA1.2 contracts must also have entrypoints that behave like views but run on the chain.
+FA1.2 contracts must also have entrypoints that provide information to other smart contracts.
 These entrypoints accept a contract address as a parameter and send a callback transaction to that address with information about the current state of the contract.
 They must not change the storage or generate any operations other than the callback transaction.
 

docs/architecture/tokens/FA2.md

@@ -2,7 +2,7 @@
 title: FA2 tokens
 authors: "Claude Barde, Aymeric Bethencourt, Tim McMackin"
 last_update:
-  date: 29 December 2023
+  date: 22 February 2024
 ---
 
 The FA2 standard supports several different token types, including:
@@ -58,20 +58,7 @@ Its parameters are a list of commands to add or remove operators for token owner
 The standard defines what happens when these entrypoints are called, the format of their parameters, and the errors that they create.
 For information about these requirements, see [TZIP-12](https://gitlab.com/tezos/tzip/-/blob/master/proposals/tzip-12/tzip-12.md).
 
-FA1.2 contracts can add any other entrypoints in addition to the required entrypoints.
-
-## Views
-
-FA2 contracts are not required to have any views, but the specification suggests these optional views.
-If any of them are implemented, all of them should be implemented, and they should be implemented with the parameters, return values, and behaviors that are defined in the standard:
-
-- `get_balance`: Returns the amount of tokens that a specified owner owns of the specified token ID
-- `total_supply`: Returns the total number of tokens of the specified token ID
-- `all_tokens`: Returns the list of all token IDs in the contract
-- `is_operator`: Returns true if the specified address is an operator for the specified token ID and owner address
-- `token_metadata`: Returns the metadata for the specified token ID
-
-FA1.2 contracts can add any other views in addition to the required views.
+FA2 contracts can add any other entrypoints in addition to the required entrypoints.
 
 ## Errors
 

docs/developing/information.md

@@ -16,9 +16,9 @@ For example, you can get the balance of an account with this command:
 octez-client get balance for tz1QCVQinE8iVj1H2fckqx6oiM85CNJSK9Sx
 ```
 
-## The RPC protocol
+## The RPC interface
 
-The [RPC](../architecture/rpc) protocol provides information about the blockchain that nodes use to communicate with each other.
+[The RPC interface](../architecture/rpc) provides information about the blockchain that nodes use to communicate with each other.
 This data is not always in the format that developers and dApps need.
 For example, the RPC interface does not provide a way to get information about a specific operation by its hash.
 

docs/developing/information/indexers.md

@@ -12,10 +12,10 @@ You can use indexers to provide the data that you need for your dApps.
 
 ## Why indexers are needed
 
-Tezos nodes store copies of blocks, but they provide only certain information about those blocks through the [RPC protocol](../../architecture/rpc).
+Tezos nodes store copies of blocks, but they provide only certain information about those blocks through the [RPC interface](../../architecture/rpc).
 
 For example, assume that you want information about an operation and all you have is its hash.
-The RPC protocol can't provide this information directly, so you would have to search each block until you found the block with this operation, which is very inefficient.
+The RPC interface can't provide this information directly, so you would have to search each block until you found the block with this operation, which is very inefficient.
 
 Instead, you can use an indexer that records information about each operation.
 This kind of indexer can provide information about a specific operation by its hash or a list of operations sent by a certain account.

docs/smart-contracts.mdx

@@ -2,7 +2,7 @@
 title: An introduction to smart contracts
 authors: 'Thomas Zoughebi, Aymeric Bethencourt, Maxime Fernandez, and Tim McMackin'
 last_update:
-  date: 18 October 2023
+  date: 15 February 2024
 ---
 
 import Figure from '@site/src/components/Figure';
@@ -34,6 +34,9 @@ A smart contract is composed of three elements:
 - Its [storage](./smart-contracts/storage): data that is dedicated to and can be read and written by the contract
 - Its code: one or more [entrypoints](./smart-contracts/entrypoints), which are a kind of function that can be called either from outside the chain or from other contracts
 
+The smart contract code is in the Michelson language, but several high-level languages exist to make it easier to write the code.
+See [Languages](./smart-contracts/languages).
+
 :::note VisualTez
 [VisualTez](https://visualtez.com/editor) allows you to visualize the fundamental logic of a smart contract without relying on any specific syntax.
 :::
@@ -53,18 +56,6 @@ Smart contracts can't do these things:
 - Change their code
 - Catch and respond to errors (see [Handling errors](./smart-contracts/logic/errors))
 
-## Smart contract languages
-
-The code of smart contracts is written in Michelson, a Turing-complete stack-based language that includes common features as well as some very specific blockchain-related features:
-
-- It doesn’t have variables but can manipulate data directly on a stack, through a set of stack manipulation instructions. For example, the _ADD_ instruction consumes two elements from the top of the stack and puts their sum on top of the stack.
-- It is strongly typed, with basic types such as integers, amounts of tez, strings, account addresses, as well as pairs, lists, key-value stores (big-maps), or pieces of code (lambdas).
-- It has limited access to data, and can only read data from its own storage, data passed as parameters during calls to its entrypoints, and a few special values such as the balance of the contract, the amount of tez sent to it during a call, and the creation time of the current block. It can also access a table of constants.
-
-Tezos has several popular high-level languages which offer more approachable syntaxes and a more familiar developer experience (e.g. local variables) compared to writing Michelson directly. While Michelson is the domain-specific smart contract language that was developed for Tezos, SmartPy and LIGO are the most popular and widely-supported languages for writing Tezos smart contracts.
-
-For more information about smart contract languages, see [Languages](./smart-contracts/languages).
-
 ## Features of Tezos smart contracts
 
 Tezos smart contracts support these features:

docs/smart-contracts/deploying.md

@@ -45,7 +45,7 @@ The high-level languages provide tools to compile the initial values of smart co
 For LIGO smart contracts, you can use the `ligo compile storage` command.
 For example, assume that a JsLIGO contract has a storage value that includes a list of integers, a string, and an integer:
 
-```ligolang
+```jsligo
 type storage = [
   list<int>,
   string,

docs/smart-contracts/entrypoints.md

@@ -34,7 +34,7 @@ An entrypoint may run logic based on:
 <!-- TODO link to Tezos library for address of caller/globals and table of contents -->
 
 Entrypoints cannot access information outside of Tezos, such as calling external APIs.
-If an entrypoint needs information from outside Tezos it must use oracles; see [Using and trusting Oracles](https://opentezos.com/smart-contracts/oracles/) on opentezos.com.
+If an entrypoint needs information from outside Tezos it must use oracles; see [Oracles](./oracles) and [Using and trusting Oracles](https://opentezos.com/smart-contracts/oracles/) on opentezos.com.
 
 The only effects that an entrypoint can have are changes to its storage and new operations that are run after the entrypoint completes.
 An entrypoint can call other entrypoints in its contract or entrypoints in other contracts.

docs/smart-contracts/events.md

@@ -27,7 +27,7 @@ For example, this contract stores a number and emits events when that amount cha
 
 JsLIGO
 
-```ligolang
+```jsligo
 type storage = int;
 
 @entry