docs: Update docs and diagrams (#250)

Author: zguesmi

.gitignore

@@ -20,3 +20,6 @@ build/*.json
 contracts/hardhat-dependency-compiler/
 deployments/*hardhat*
 deployments/dev-*
+
+# Flattened Solidity file used to generate diagrams.
+flatten.sol

CHANGELOG.md

@@ -1,6 +1,7 @@
 # Changelog
 
 ## vNEXT
+- Update docs and diagrams (#250)
 - Support Arbitrum One (#248)
 - Save IexecLibOrders_v5 in config file (#242)
 - Migrate proxy to Diamond pattern (ERC-2535):

README.md

@@ -20,21 +20,24 @@ This repository contains the smart contract implementation of iExec's PoCo proto
 
 - [Contracts and Actors Architecture](./docs/README.md#contracts-and-actors-architecture)
 - [State diagrams](./docs/Statuses.md)
-- [Storage diagram (Boost)](./docs/uml/storage-IexecPocoBoostDelegate.svg)
 - [Nominal workflow sequence](./docs/README.md#nominal)
 - [Nominal workflow sequence w/ TEE](./docs/README.md#nominaltee)
 - [Boost workflow sequence](./docs/README.md#boost)
+- Storage diagrams
+    - [Diamond storage](./docs/uml/storage-diagram-diamond.svg)
+    - [PoCo storage](./docs/uml/storage-diagram-poco.svg)
 - UML classes related to:
-    - [IexecPocoDelegates](./docs/uml/class-uml-IexecPocoDelegates.svg)
-    - [IexecPocoBoostDelegate](./docs/uml/class-uml-IexecPocoBoostDelegate.svg)
+    - [IexecPoco1Facet & IexecPoco2Facet](./docs/uml/class-uml-IexecPocoFacets.svg)
+    - [IexecPocoBoostFacet](./docs/uml/class-uml-IexecPocoBoostFacet.svg)
     - [IexecEscrows](./docs/uml/class-uml-IexecEscrows.svg)
     - [iExec PoCo registries](./docs/uml/class-uml-dir-registries.svg)
     - [iExec PoCo libraries](./docs/uml/class-uml-dir-libs.svg)
-    - [iExec PoCo modules](./docs/uml/class-uml-dir-modules.svg)
+    - [iExec PoCo modules (facets)](./docs/uml/class-uml-dir-facets.svg)
 
 ## Documentation
 
 - [Solidity API documentation](./docs/solidity/index.md)
+<!-- TODO update with new documentation URL -->
 - [Full PoCo documentation](https://protocol.docs.iex.ec/key-concepts/proof-of-contribution)
 
 ## Audits
@@ -45,7 +48,7 @@ All contract audit files can be found in [audit/](./audit/) folder.
 
 ## Configure a deployment
 
-Starting from version 5, the PoCo uses a modular design based on [ERC1538](https://github.com/ethereum/EIPs/issues/1538). The migration scripts and tests will use different modules and deployment process depending on the required configuration. In particular, the configuration can use a [create2 factory](https://github.com/iExecBlockchainComputing/iexec-solidity/blob/master/contracts/Factory/GenericFactory.sol) for the deployment, and enable native token or ERC20 token based escrow depending on the targeted blockchain. This means that the codebase is the same on public blockchains (ERC20 based RLC) and dedicated sidechains (Native token based RLC).
+Starting from version 5, the PoCo uses a modular design based on [ERC-2535](https://eips.ethereum.org/EIPS/eip-2535). The migration scripts and tests will use different modules (facets) and deployment process depending on the required configuration. In particular, the configuration can use a [create2 factory](https://github.com/iExecBlockchainComputing/iexec-solidity/blob/master/contracts/Factory/GenericFactory.sol) for the deployment, and enable native token or ERC20 token based escrow depending on the targeted blockchain. This means that the codebase is the same on public blockchains (ERC20 based RLC) and dedicated sidechains (Native token based RLC).
 
 The configuration file is located in `./config/config.json`.
 
@@ -69,15 +72,15 @@ If you want to deploy the iExec PoCo V5 smart contracts on a new blockchain, the
 ## Additional configuration & environment variables
 
 Environment variable can be used to alter the configuration of a deployment:
-- **SALT**: if set, the `SALT` envvar will overwrite the salt parameter from the config. This can be useful to distinguish different deployments without modifying the config.
+- **SALT**: if set, the `SALT` env var will overwrite the salt parameter from the config. This can be useful to distinguish different deployments without modifying the config.
 
 Additionally, the migration process will look for some smart contracts before deploying new instances. This is true of the application, dataset and workerpool registries. Thus, if different marketplaces are deployed to the same network, they will share these registries.
 
 # Development
 
 ## Build
 
-The PoCo smart contracts are in the `./contracts` folder. Json artifacts, containing the contracts bytecode and ABI can be found in the `./build` folder. In case you need to regenerate them, you can use the following command:
+The PoCo smart contracts are in the `contracts/` folder. Json artifacts, containing the contracts bytecode and ABI can be found in the `artifacts/` folder. In case you need to regenerate them, you can use the following command:
 ```
 npm install
 npm run build
@@ -114,7 +117,7 @@ The automatic testing command uses the Hardhat network by default to run the tes
     If your blockchain listen to a port that is not 8545, or if the blockchain is on a different node, update the `hardhat.config.ts` configuration (network ports, accounts with mnemonic, ..) accordingly to the [Hardhat Configuration](https://hardhat.org/hardhat-runner/docs/config) documentation.
 3. Run tests
 ```
-npm run test
+npm run test -- --network <networkUrl>
 ```
 
 ## Deploy
@@ -123,7 +126,7 @@ The iExec PoCo contracts support automated deployment through both command-line
 
 ### Command Line Deployment
 
-You can deploy the smart contracts according to the [deploy/0_deploy.ts](./deploy/0_deploy.ts) content. This will automatically save some addresses of the deployed artifacts to the `./deployments` folder.
+You can deploy the smart contracts according to the [deploy/0_deploy.ts](./deploy/0_deploy.ts) content. This will automatically save addresses of the deployed artifacts to `deployments/` folder.
 
 To deploy using the CLI:
 
@@ -132,7 +135,7 @@ To deploy using the CLI:
 3. Run the deployment using:
 
 ```
-npx hardhat deploy --network <your network name>
+npm run deploy -- --network <your network name>
 ```
 
 Example with custom salt:
@@ -142,12 +145,12 @@ SALT=0x0000000000000000000000000000000000000000000000000000000000000001 npx hard
 ```
 
 
-### Manual Verification
+### Verification
 
-To manually verify contracts:
+To verify contracts:
 
 ```
-npx hardhat run ./scripts/verify.ts --network <your network name>
+npm run verify:all -- --network <your network name> # e.g. arbitrum
 ```
 
 This script automatically reads all deployed contract addresses and their constructor arguments from the deployment artifacts and verifies them on the relevant block explorer.
@@ -167,19 +170,19 @@ To render all UML diagrams:
 npm run uml
 ```
 
-### Render only class diagrams
+To render only class diagrams:
 
 ```
 npm run sol-to-uml
 ```
 
-### Render only .puml files
+To render only .puml files:
 
 ```
 npm run puml-to-links
 ```
 
-### Render only storage diagrams
+To render only storage diagrams:
 
 ```
 npm run storage-to-diagrams

contracts/facets/FacetBase.sol

@@ -6,7 +6,6 @@ pragma solidity ^0.6.0;
 import "../libs/PocoStorageLib.sol";
 import "../interfaces/IOwnable.sol";
 
-// Functions that were declared in ERC1538Store are re-declared here.
 // TODO use LibDiamond.contractOwner() when migrating all contracts to v8.
 
 /**

contracts/facets/FacetBase.v8.sol

@@ -6,7 +6,6 @@ pragma solidity ^0.8.0;
 import {IERC5313} from "@openzeppelin/contracts-v5/interfaces/IERC5313.sol";
 import {PocoStorageLib} from "../libs/PocoStorageLib.v8.sol";
 
-// Functions that were declared in ERC1538Store are re-declared here.
 // TODO use LibDiamond.contractOwner() when migrating all contracts to v8.
 
 /**

contracts/tools/diagrams/StorageDiagrams.sol

@@ -0,0 +1,20 @@
+// SPDX-FileCopyrightText: 2025 IEXEC BLOCKCHAIN TECH <[email protected]>
+// SPDX-License-Identifier: Apache-2.0
+
+pragma solidity ^0.8.0;
+
+import {LibDiamond} from "@mudgen/diamond-1/contracts/libraries/LibDiamond.sol";
+import {PocoStorageLib} from "../../libs/PocoStorageLib.v8.sol";
+
+// /!\ These contracts are only used to generate storage diagrams, they are not meant
+// to be deployed or used in any way.
+// PocoStorageLib and LibDiamond use namespaced storage which makes sol2uml unable to
+// generate diagrams directly, so these contracts provide their structs to sol2uml.
+
+contract DiamondStorageDiagram {
+    LibDiamond.DiamondStorage diamondStorage;
+}
+
+contract PocoStorageDiagram {
+    PocoStorageLib.PocoStorage pocoStorage;
+}

contracts/tools/testing/IexecPocoBoostCompositeDelegate.sol

@@ -1,8 +1,8 @@
-## Task statuses 
+## Task statuses
 
 Flows:
 - Nominal
-- "Contribute and finalize"
+- ContributeAndFinalize
 - Boost
 
 ```mermaid
@@ -22,7 +22,7 @@ flowchart TB
 ```
 ## Contributions statuses
 
-- Nominal and "contribute and finalize" flows
+- Nominal and ContributeAndFinalize flows
 
 ```mermaid
 flowchart TB