Merge pull request #315 from trilitech/staging

Update main from staging

docs/architecture.mdx → docs/architecture.md

@@ -2,11 +2,9 @@
 title: Architecture
 authors: Tim McMackin
 last_update:
-  date: 28 November 2023
+  date: 6 February 2024
 ---
 
-import LucidDiagram from '@site/src/components/LucidDiagram';
-
 The Tezos blockchain is composed of many Tezos nodes running around the world, complemented by other running daemons, such as bakers and accusers.
 These processes collaborate with the overall goal of maintaining the blockchain data in a decentralized manner.
 
@@ -15,7 +13,8 @@ Users interact with nodes through many different clients, including command-line
 
 This diagram shows a high-level view of the Tezos system:
 
-<LucidDiagram width="640px" height="480px" src="https://lucid.app/documents/embedded/d778aa2a-ad0a-4324-b235-ed3b35742c58" id="Uz-K28y3R8gJ" />
+![A high-level view of the Tezos system, including Tezos nodes, the blockchain data itself, an Indexer, and a few examples of clients](/img/architecture/architecture-overview.png)
+<!-- https://lucid.app/lucidchart/d778aa2a-ad0a-4324-b235-ed3b35742c58/edit -->
 
 ## The blockchain data
 
@@ -147,6 +146,11 @@ Some typical use cases for nodes are:
 Optionally, this node can open its RPC interface to serve different kinds of requests.
 - A node along with a baker, an accuser, and a signer can be used to bake new blocks, activity which ensures that the blockchain progresses and yields rewards in tokens.
 
+### Indexers and block explorers
+
+Indexers are off-chain applications that retrieve blockchain data, process it, and store it in a way that makes it easier to search and use.
+They are an important part of block explorers, which are applications that provide data about the blockchain.
+
 ## References
 
 For more information about the architecture of Tezos, see:
@@ -155,3 +159,5 @@ For more information about the architecture of Tezos, see:
 - [Tokens](./architecture/tokens)
 - [Smart Optimistic Rollups](./architecture/smart-rollups)
 - [Governance](./architecture/governance)
+- [Indexers](./developing/information/indexers)
+- [Block explorers](./developing/information/block-explorers)

docs/dApps.mdx

@@ -2,7 +2,7 @@
 title: Decentralized applications (dApps)
 authors: Benjamin Pilia, Tim McMackin
 last_update:
-  date: 12 January 2024
+  date: 30 January 2024
 ---
 
 import LucidDiagram from '@site/src/components/LucidDiagram';
@@ -17,31 +17,18 @@ In general, dApps have these parts:
 - **Backend**: An on-chain component that consists of one or more [smart contracts](./smart-contracts)
 
 The off-chain component can be nearly any kind of program, including a web application, mobile or desktop app, or command-line interface.
-It relies on wallets and tools to interact with the smart contract on behalf of a user's Tezos account.
+It relies on wallets and tools to interact with the smart contracts on behalf of a user's Tezos account.
 
-<LucidDiagram width="640px" height="480px" src="https://lucid.app/documents/embedded/8caf9ef1-11e4-454a-bbb6-ef4852515959" id=".4NXymECcQqz" />
+![Fundamental diagram of dApps, showing the frontend, indexer, and backend](/img/dApps/dapp-overview.png)
+{/* Source https://lucid.app/lucidchart/8caf9ef1-11e4-454a-bbb6-ef4852515959/edit?page=0_0# */}
 
 Some of these tools that allow an off-chain component to interact with smart contracts include:
 
 - [Taquito](./dApps/taquito), an SDK for JavaScript/TypeScript applications
-- The [Tezos SDK for Unity](./unity), a toolkit for Unity applications
+- The [Tezos SDK for Unity](./unity), a toolkit for the [Unity](https://unity.com/) game development platform
 - [Taqueria](https://taqueria.io/), a development platform for dApps
 
-## Sample dApps
-
-For example dApps, see [Sample dApps](./dApps/samples).
-
-## Best practices
-
-Good programming and design practices make dApps easier to use and provide a better user experience.
-See [Best practices and avoiding flaws](./dApps/best-practices).
-
-## dApp tasks
-
-For information on typical tasks that dApps do, see:
-
-- [Connecting to wallets](./dApps/wallets)
-- [Sending transactions](./dApps/sending-transactions)
+The next pages in this section illustrate dApps with [examples](./dApps/samples), detail the main steps when developing dApps such as [Connecting to wallets](./dApps/wallets) and [Sending transactions](./dApps/sending-transactions), and introduce some [best practices](./dApps/best-practices)
 
 ## Tutorials
 

docs/developing/dev-environments.md

@@ -48,4 +48,4 @@ To test smart contracts and dApps, you can use these test environments:
 - Test networks behave like Tezos Mainnet but have differences that make it easier to test on them, such as faucets that provide free tokens and reduced block times for faster testing.
 - Sandbox environments like [Flextesa](https://tezos.gitlab.io/flextesa/) run Tezos nodes locally on your computer in a sandbox mode.
 
-For more information about test environments, see [Using sandboxes and testnets](./testnets).
+For more information about test environments, see [Testing on sandboxes and testnets](./testnets).

docs/developing/octez-client/accounts.md

@@ -24,7 +24,7 @@ octez-client show address local_account
 
 The account address (technically the hash of the public key) starts with `tz1`, `tz2`, or `tz3`.
 You can use this address to send tez to this account, such as from a faucet if you are using a testnet.
-See [Using sandboxes and testnets](../testnets).
+See [Testing on sandboxes and testnets](../testnets).
 
 <!-- TODO
 ## Importing pregenerated accounts

docs/smart-contracts/testing.md → docs/developing/testing.md

@@ -1,14 +1,36 @@
 ---
-title: Testing smart contracts
+title: Testing locally
 authors: 'Yuxin Li'
 last_update:
-  date: 6 November 2023
+  date: 23 January 2024
 ---
 
-## Introduction
-Tezos blockchain smart contracts are immutable after deployment, so you must rigorously test to ensure functionality, prevent errors, and avoid potential financial losses. Importantly, contract testing doesn't require any tokens or a wallet account to execute.
+Tezos smart contracts are immutable after deployment, so you must rigorously test them before deploying them to ensure functionality, prevent errors, and avoid potential financial losses. Importantly, contract testing doesn't require any tokens or a wallet account to execute.
 
-High-level languages come with tools to help write tests, and some testing tools can be used independently of the language used to write the smart contract.
+## Tools for local testing
+
+- The Michelson interpreter is an OCaml function that can be used by tools to simulate a call to any entry point of any smart contract, given an initial value of the storage and parameters. Some programming languages like LIGO or SmartPy use this as part of their testing frameworks.
+
+- The mockup mode of `octez-client` can be used to test contract calls and other features such as some RPC calls, all without running an actual node, saving the time of going through the consensus mechanism and waiting to get blocks created and validated. Tools like Completium, built by the team behind the Archetype language, use this for their testing framework. Find out more in the [documentation of the mockup mode](https://tezos.gitlab.io/user/mockup.html).
+
+   For example, when you compile the contract in the tutorial [Create a smart contract](../tutorials/smart-contract) to Michelson, its first line defines the parameter type that the contract accepts:
+
+   ```
+   parameter (or (unit %reset) (or (int %decrement) (int %increment)))
+   ```
+
+   You can call this contract in mockup mode by passing the compiled contract file, the storage value as a Michelson expression, and the parameter value to pass as a Michelson expression.
+   For example, this command sets the storage to 4 and passes 5 to the `Increment` entrypoint:
+
+   ```bash
+   octez-client --mode mockup run script Counter.tz on storage 4 and input "(Right (Right 5))"
+   ```
+
+   The response in the console shows the new value of the storage and any operations emitted.
+
+## Testing in high-level languages
+
+High-level languages come with tools to help write tests locally, and some testing tools can be used independently of the language used to write the smart contract.
 For example, [SmartPy](https://smartpy.io/manual/scenarios/overview) includes syntax dedicated to testing.
 
 The following SmartPy test code snippet is for a Tezos smart contract that acts like a calculator. The code defines a series of tests to check the functionality of the calculator contract.
@@ -34,11 +56,7 @@ if "templates" not in __name__:
 ```
 The test scenario runs these operations sequentially and would check if all operations execute as expected and if the final result matches the expected value.
 
-## Prerequisites
-- Set up an wallet account on Tezos with some tez to pay the fees
-- Ensure that you have obtained the [Tezos client](../developing/octez-client/installing)
-
-# Structure of a test scenario
+## Structure of a test scenario
 
 A test scenario usually consists of the following steps:
 
@@ -88,4 +106,7 @@ For more information about avoiding flaws in contracts, see [Avoiding flaws](htt
 - SmartPy: [Tests and scenarios](https://smartpy.io/manual/scenarios/overview)
 - LIGO: [Testing LIGO](https://ligolang.org/docs/advanced/testing)
 
-Upon test successful, you can deploy your smart contract!
+## Next steps
+
+When you're done testing contracts locally, you can deploy them to a test network and test them there.
+See [Testing on sandboxes and testnets](./testnets).