SC documentation improvements

source/mainnet/conf.py

@@ -368,6 +368,8 @@
  "./net/resources/legal": "net/resources/terms-and-conditions.html",
  "./en/mainnet/smart-contracts/onboarding-guide-solana-developers/index": "en/mainnet/smart-contracts/onboarding-guide-solana-developers/overview.html",
  "./net/references/grpc": "net/references/grpc2.html",
+ "./en/mainnet/smart-contracts/guides/contract-testing-guides": "./en/mainnet/smart-contracts/guides/integration-test-contract",
+ "./en/mainnet/smart-contracts/best-practices/index": "./en/mainnet/smart-contracts/best-practices/development",
 }
 
 # -- Tags that enables the .. only option ----------------

source/mainnet/net/guides/dapp-examples.rst

@@ -84,7 +84,8 @@ Select an example to see more information about it, such as a hosted dApp for yo
 .. dropdown:: Wallet test bench
 
  This tool is for testing wallets and shows a great overview of the available interactions between wallets and front end.
- Deploy and initialize scenarios are available on the browser wallet (will be implemented in the mobile wallets in the future).
+
+ Deploy and initialize scenarios are available on the |bw|.
 
  `Demo front end <https://wallet-test-bench.testnet.concordium.com/>`__ where you can test wallet interactions
 

source/mainnet/net/guides/developer-page.rst

@@ -7,22 +7,11 @@ Developer resources
 
 The following developer resources help you get started developing on the Concordium network.
 
-Official resources
-==================
+All of our repositories are on `GitHub <https://github.com/Concordium>`__.
 
-- See :ref:`Node setup<node-requirements>` for information about the requirements to run a node and the available platforms for nodes.
+.. dropdown:: Standards
 
-- See :ref:`SDKs and APIs<sdks-apis>` for links to SDKs and APIs for development
-
-- See :ref:`Smart contracts <introduction>` for general information about smart contracts
-
- - `Smart contract libraries <https://crates.io/crates/concordium-std>`_
-
- - To ease deployment and initialization, you can use the `Smart contract deploy and initialize tool <https://sctools.mainnet.concordium.software/>`__ instead of the process below. It works with the |bw| to deploy and initialize smart contracts to Mainnet and Testnet.
-
-- `GitHub <https://github.com/Concordium>`_
-
-- `Concordium standards and updates <https://proposals.concordium.software/>`_
+ - `Concordium standards and updates <https://proposals.concordium.software/>`_
 
  - `CIS-0 standard detections <https://proposals.concordium.software/CIS/cis-0.html>`_
 
@@ -32,35 +21,48 @@ Official resources
 
  - `CIS-3 sponsored transaction standard <https://proposals.concordium.software/CIS/cis-3.html>`_
 
-- See :ref:`How to create proofs for dApps and services <create-proofs>` for information about how to write statements that interact with Concordium wallets.
+.. dropdown:: Nodes
+
+ See :ref:`Node setup<node-requirements>` for information about the requirements to run a node and the available platforms for nodes.
 
-- For information about how to create proofs to verify identity for dApps and services see :ref:`Create proofs<create-proofs>`.
+ For testing purposes, a node is available on testnet to use when testing smart contracts and dApps. You can use this node for API calls of chain methods only with gRPC v2 and gRPC web. The address is node.testnet.concordium.com on port 20000 (gRPCv2 and gRPC-web). You can use this node for API calls of *chain methods only*. This node is maintained by Concordium, but Concordium does not guarantee availability. The status of this node is available on the `Testnet status page <https://status.testnet.concordium.software>`__.
 
-- See :ref:`dApp examples<dapp-examples>` for a list of dApp examples and their resources.
+.. dropdown:: SDKs and APIs
 
-- For testing purposes, a node is available on testnet to use when testing smart contracts and dApps. You can use this node for API calls of chain methods only with gRPC v2 and gRPC web. The address is node.testnet.concordium.com on port 20000 (gRPCv2 and gRPC-web). You can use this node for API calls of *chain methods only*. This node is maintained by Concordium, but Concordium does not guarantee availability. The status of this node is available on the `Testnet status page <https://status.testnet.concordium.software>`__.
+ The following SDKs and APIs exist for developing on the Concordium network.
 
-- The `VSCode extension <https://marketplace.visualstudio.com/items?itemName=Concordium.concordium-smart-contracts>`__ can help you develop Concordium smart contracts. The extension sets up the editor for development, installs the ``cargo-concordium`` smart contract development tool for all supported platforms, and provides commands in the editor for the essential workflows, such as building and testing smart contracts.
+ - :ref:`Concordium gRPC V2 API<grpc2-documentation>`
+ - `Concordium Rust SDK <https://github.com/Concordium/concordium-rust-sdk>`_
+ - `Concordium Javascript (Node / Web) SDK <https://github.com/Concordium/concordium-node-sdk-js>`_
+ - `Concordium Java SDK <https://github.com/Concordium/concordium-java-sdk>`_
+ - `Concordium .NET (C#) SDK <https://github.com/Concordium/concordium-net-sdk>`_
+ - `Concordium Rosetta SDK <https://github.com/Concordium/concordium-rosetta>`_
+ - `Concordium go SDK <https://github.com/Concordium/concordium-go-sdk>`_
 
-You can watch a video about how to use the VSCode extension.
+ The following NPM libraries are useful for building web-based dApps:
 
-.. image:: https://img.youtube.com/vi/9qjcsGDeveg/maxresdefault.jpg
- :alt: video about smart contract lifecycle
- :target: https://www.youtube.com/watch?v=9qjcsGDeveg
+ - `@concordium/react-components <https://www.npmjs.com/package/@concordium/react-components>`_ (for React projects).
+ - `@concordium/wallet-connectors <https://www.npmjs.com/package/@concordium/wallet-connectors>`_ (for connecting to wallets in non-React projects).
+ - `@concordium/web-sdk <https://www.npmjs.com/package/@concordium/web-sdk>`_ (for interacting with a chain).
+ - `@concordium/ccd-js-gen <https://www.npmjs.com/package/@concordium/ccd-js-gen>`_ (for generating smart contract clients in JavaScript).
 
-- An external `transaction logger <https://github.com/Concordium/concordium-transaction-logger>`_ service
+.. dropdown:: Smart contracts
 
-Concordium Proof Explorer
--------------------------
+ See :ref:`Smart contracts <introduction>` for general information about smart contracts, including a list of the available :ref:`smart contract development tools<sc-dev-tools>` to make creation, testing, and deployment easier.
+
+ - `Smart contract libraries <https://crates.io/crates/concordium-std>`_
 
-If you want to familiarize yourself with how proofs work and can be constructed, you can use the `Concordium Proof Explorer <https://web3id-proof-explorer.testnet.concordium.com/>`__ to create proofs and send them to a |bw| to see how they interact with account credentials and verifiable credentials. The Concordium Proof Explorer works on Testnet. You can use the `Web3Id Issuer Front End <https://web3id-issuer-frontend.testnet.concordium.com/>`__ to create verifiable credential to test with the proof explorer.
+.. dropdown:: Proofs
 
-.. _example-dapps:
+ - See :ref:`How to create proofs for dApps and services <create-proofs>` for information about how to write statements that interact with Concordium wallets.
 
-Example dApps
--------------
+ - For information about how to create proofs to verify identity for dApps and services see :ref:`Create proofs<create-proofs>`.
 
-Concordium has a selection of example dApps that you can clone to make your own dApps or for inspiration. Additionally, all of these example dApps are hosted so you can try the functionality on Concordium's testnet.
+ If you want to familiarize yourself with how proofs work and can be constructed, you can use the `Concordium Proof Explorer <https://web3id-proof-explorer.testnet.concordium.com/>`__ to create proofs and send them to a |bw| to see how they interact with account credentials and verifiable credentials. The Concordium Proof Explorer works on Testnet. You can use the `Web3Id Issuer Front End <https://web3id-issuer-frontend.testnet.concordium.com/>`__ to create verifiable credential to test with the proof explorer.
+
+.. dropdown:: dApps
+
+ Concordium has a selection of example dApps that you can clone to make your own dApps or for inspiration. Additionally, all of these example dApps are hosted so you can try the functionality on Concordium's testnet.
 
  - Piggy bank: :ref:`Piggy bank tutorial<piggy-bank>` / `Piggy bank dApp <https://piggybank.testnet.concordium.com>`__
  - wCCD: :ref:`wCCD tutorial<wCCD>` / `wCCD dApp <https://wccd.testnet.concordium.com/>`_
@@ -69,47 +71,51 @@ Concordium has a selection of example dApps that you can clone to make your own
  - eSealing: :ref:`eSealing tutorial<eSealing>` / `eSealing dApp <https://esealing.testnet.concordium.com>`_
  - signMessage: `Front end code <https://github.com/Concordium/concordium-dapp-examples/tree/main/signMessage>`__ / `signMessage dApp <http://signmessage.testnet.concordium.com/>`__
 
-.. _block-explorers:
+ For a full list of dApp examples and resources, see :ref:`dApp examples<dapp-examples>`.
 
-Block explorers
----------------
+.. dropdown:: Block explorers and analytics
 
-The following are links to the block, node, and status explorers.
+ .. _block-explorers:
 
-Concordium status pages
-^^^^^^^^^^^^^^^^^^^^^^^
+ The following are links to the block, node, and status explorers.
 
-For information about the status pages, see :ref:`Status pages<dashboards>`.
+ **Concordium status pages**
 
- - `Mainnet status page <https://status.mainnet.concordium.software>`_
+ - `Mainnet status page <https://status.mainnet.concordium.software>`__
 
  - `Testnet status page <https://status.testnet.concordium.software>`__
 
-CCDScan
-^^^^^^^
+ For information about the status pages, see :ref:`Status pages<dashboards>`.
 
-For information about CCDScan, see :ref:`CCDScan<ccd-scan>`.
+ **CCDScan**
 
  - `CCDScan <https://ccdscan.io>`_
 
-Grafana® node dashboard
-^^^^^^^^^^^^^^^^^^^^^^^
+ For information about CCDScan, see :ref:`CCDScan<ccd-scan>`.
 
-For node runners using Grafana, Concordium provides a node performance dashboard using the exposed Prometheus metrics. You can `download it from the Grafana marketplace <https://grafana.com/grafana/dashboards/18983-concordium-node-external/>`__.
+ **Grafana® node dashboard**
 
-Social media and support
-------------------------
+ For node runners using Grafana, Concordium provides a node performance dashboard using the exposed Prometheus metrics. You can `download it from the Grafana marketplace <https://grafana.com/grafana/dashboards/18983-concordium-node-external/>`__.
 
-- `Discourse <https://support.concordium.software/>`_
+ **Transaction logger**
 
-- `Telegram <https://t.me/concordium_official>`_
+ An external `transaction logger <https://github.com/Concordium/concordium-transaction-logger>`_ service
 
-- `Discord <https://discord.com/invite/xWmQ5tp>`_
+ **Indexers**
 
-Community resources
-===================
+ See :ref:`Indexers<indexers-intro>` for more information.
+
+.. dropdown:: Social media and support
+
+ - `Concordium's official support <https://support.concordium.software/>`_
+
+ - `Telegram <https://t.me/concordium_official>`_
+
+ - `Discord <https://discord.com/invite/xWmQ5tp>`_
+
+.. dropdown:: Community resources
 
-- `Block explorer built by a user in the Netherlands <https://concordium-explorer.nl/>`_
+ - `Block explorer built by a user in the Netherlands <https://concordium-explorer.nl/>`_
 
 .. toctree::
  :hidden:

source/mainnet/net/index.rst

@@ -41,12 +41,12 @@ index
 
  Introduction <../smart-contracts/general/introduction>
  Quick start guide <../smart-contracts/guides/quick-start>
- Contract development guides <../smart-contracts/guides/contract-dev-guides>
- Contract testing guides <../smart-contracts/guides/contract-testing-guides>
- On-chain guides <../smart-contracts/guides/on-chain-index>
- Best practices <../smart-contracts/best-practices/index>
  Ethereum developer onboarding <../smart-contracts/onboarding-guide-ethereum-developers/faq>
  Solana developer onboarding <../smart-contracts/onboarding-guide-solana-developers/overview>
+ Contract development guides <../smart-contracts/guides/contract-dev-guides>
+ Test contracts <../smart-contracts/guides/integration-test-contract>
+ On-chain guides <../smart-contracts/guides/on-chain-index>
+ Best practices <../smart-contracts/best-practices/development>
  References <../smart-contracts/references/index>
  V0 smart contracts <../smart-contracts-v0/sc-v0-rollup>
 

source/mainnet/net/indexers/intro.rst

@@ -1,3 +1,5 @@
+.. _indexers-intro:
+
 =================
 What are indexers
 =================

source/mainnet/net/indexers/subquery.rst

@@ -1,3 +1,5 @@
+.. _subquery:
+
 ========
 SubQuery
 ========

source/mainnet/smart-contracts/best-practices/development.rst

@@ -4,7 +4,8 @@
 Development best practices
 ==========================
 
-This document provides guidelines for developing smart contracts.
+This document provides guidelines for developing smart contracts, including best practices for smart contract development, audit, information about common pitfalls and security vulnerabilities, and how to avoid them.
+
 It starts with some general thoughts about smart contract development and then gives more details about writing smart contracts in Rust for Concordium.
 
 Mindset
@@ -15,7 +16,7 @@ Smart contract development involves many risks that do not show up in, for examp
 - the cost of mistakes is very high;
 - possibilities for fixing bugs are limited;
 - the area is evolving constantly, with new vulnerabilities being discovered regularly;
-- malicious parties deliberately try to break your contract, for example, to steal the funds from the contract account.
+- malicious parties deliberately try to break your contract, for example, to steal the funds from the contract or account.
 
 Therefore, it is not sufficient to defend your code against known vulnerabilities.
 You can think about smart contracts as mission-critical software, or software for embedded devices rather than a web application.
@@ -66,8 +67,7 @@ Concordium Rust Smart Contracts
 ===============================
 
 This section provides recommendations for developing smart contracts in Rust.
-See :ref:`introduction` for basic information.
-
+See :ref:`Introduction to smart contracts<introduction>` for basic information.
 
 .. _best-practices-code-structure:
 

source/mainnet/smart-contracts/general/contract-instances.rst

@@ -4,8 +4,8 @@
 Smart contract instances
 ========================
 
-A **smart contract instance** is a smart contract module together with a
-specific state and an amount of CCD tokens.
+A :term:`smart contract instance<instance>` is a smart contract module together with a
+specific state and an amount of CCD tokens. A smart contract instance is often just called an *instance*.
 Multiple smart contract instances can be created from the same module.
 For example, for an :ref:`auction <auction>` contract, there could be multiple instances, each
 one dedicated to bidding for a specific item and with its own participants.
@@ -17,10 +17,6 @@ parameter.
 Its end result is required to be the initial smart contract state of the
 instance.
 
-.. note::
-
- A smart contract instance is often just called an *instance*.
-
 .. graphviz::
  :align: center
  :caption: Example of smart contract module containing two smart contracts:
@@ -65,8 +61,8 @@ or destroy CCD tokens.
 
 .. _contract-instances-init-on-chain:
 
-Instantiating a smart contract on-chain
-=======================================
+Instantiate a smart contract on-chain
+=====================================
 
 Every smart contract must contain a function for creating smart contract
 instances. Such a function is referred to as the *init function*.
@@ -96,11 +92,11 @@ transaction for attempting to create the instance is visible on-chain.
 .. seealso::
 
  See :ref:`initialize-contract` guide for how to initialize a
- contract in practice.
+ contract in practice. You can also watch a video about initializing smart contract instances.
 
-.. note::
-
- The *init function* has no return value.
+ .. image:: https://img.youtube.com/vi/SNm9xEegBKA/maxresdefault.jpg
+ :alt: video about initializing smart contract instances
+  :target: https://www.youtube.com/watch?v=SNm9xEegBKA
 
 Instance state
 ==============
@@ -117,8 +113,8 @@ held by a particular node in the tree.
 
  See :ref:`host-functions-state` for a reference of these functions.
 
-Interacting with an instance
-============================
+Interact with an instance
+=========================
 
 A smart contract can expose zero or more functions for interacting with an
 instance, referred to as *receive functions*.
@@ -140,8 +136,8 @@ To summarize, a transaction for smart-contract interaction includes:
 
 .. _contract-instances-logging-events:
 
-Logging events
-==============
+Log events
+==========
 
 Events can be logged during the execution of smart contract functions. This is
 the case for both init and receive functions. The logs are designed for
@@ -178,8 +174,8 @@ When initializing, updating, or invoking a smart contract, the following limits
 
  The log item and return value limits can not be reached in practice because the energy limit will kick in earlier.
 
-Invoking operations
-===================
+Invoke operations
+=================
 
 A receive function can use the host environment to invoke two types of
 operations during its execution.

source/mainnet/smart-contracts/general/contract-lifecycle.rst

@@ -0,0 +1,32 @@
+.. _sc-lifecycle:
+
+==============================
+Life cycle of a smart contract
+==============================
+
+A smart contract is first deployed to the chain as part of a :ref:`contract
+module <contract-module>`. After this a smart contract can be *initialized* to
+obtain a :ref:`smart contract instance <contract-instances>`. Finally a smart
+contract instance can be repeatedly updated according to its own logic.
+
+.. image:: images/smart-contract-lifecycle.png
+ :width: 100%
+ :alt: flow diagram with different actions
+
+#. In ``cargo-concordium`` :ref:`run the init command<setup-contract>` to start a new project.
+
+#. Edit your contract, including the entrypoints, functions, and parameters necessary to execute what is needed. If :ref:`using a schema<build-schema>`, make sure that the contract is prepared for this. You can also run your code off-chain for testing purposes.
+
+#. In ``cargo-concordium`` :ref:`run the build command<compile-module>` to build the Wasm module that can be deployed on chain.
+
+#. In ``concordium-client`` :ref:`run the deploy command<deploy-module>` to deploy the Wasm module. This makes the contract available on chain.
+
+#. In ``concordium-client`` :ref:`run the init command<initialize-contract>` to initialize the contract on chain. This gives you a new instance of the smart contract with a fresh state.
+
+#. In ``concordium-client`` you can then :ref:`run invoke<invoke-instance>` to simulate your contract and see how much energy it uses or to call a view entrypoint which returns some data derived from the contract state; use :ref:`show<inspect-instance>` to see the schema or parameters in the contract, or :ref:`update<interact-instance>` to execute transactions and update the state.
+
+You can also watch a video about the smart contract lifecycle.
+
+.. image:: https://img.youtube.com/vi/84_-C-4cK4E/maxresdefault.jpg
+ :alt: video about smart contract lifecycle
+ :target: https://www.youtube.com/watch?v=84_-C-4cK4E