Merge branch 'develop' into fix/scan-vuln-deps-workflow

.env.example

@@ -1,11 +1,11 @@
 # GENERAL
 
 ## The network used for testing purposes
-NETWORK_NAME="mainnet" #  ["mainnet", "goerli", "sepolia", "polygon", "polygonMumbai", "base", "baseGoerli", "arbitrum", "arbitrumGoerli"]
+NETWORK_NAME="sepolia" #  ["mainnet", "sepolia", "polygon", "polygonMumbai", "base", "baseSepolia", "arbitrum", "arbitrumSepolia"]
 
 # CONTRACTS
 
-## Hex encoded private keys separated by a comma `,`a
+## One or multiple hex encoded private keys separated by commas `,` replacing the hardhat default accounts.
 PRIVATE_KEY="0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80" # Default hardhat account 0 private key. DON'T USE FOR DEPLOYMENTS
 
 ## Infura credentials
@@ -29,4 +29,4 @@ GRAPH_KEY="zzzzzzzzzzzz"
 ## Subgraph
 SUBGRAPH_NAME="osx"
 SUBGRAPH_VERSION="v1.0.0"
-SUBGRAPH_NETWORK_NAME="mainnet" #  ["mainnet", "goerli", "sepolia", "polygon", "polygonMumbai", "base", "baseGoerli", "arbitrum", "arbitrumGoerli"]
+SUBGRAPH_NETWORK_NAME="mainnet" #  ["mainnet", "goerli", "sepolia", "polygon", "polygonMumbai", "base", "baseSepolia", "arbitrum", "arbitrumSepolia"]

.gitignore

@@ -21,8 +21,6 @@ packages/subgraph/tests/.bin
 .pnp.*
 coverage.json
 
-plugin-info-testing.json
-
 packages/subgraph/deploy-output.txt
 packages/subgraph/subgraph.yaml
 packages/subgraph/tests/.latest.json

USAGE_GUIDE.md

@@ -1,15 +1,41 @@
-# Developing a Plugin
+# Template Usage Guide
 
-## Contracts
+This guide will walk you through the process of writing the smart contract for a plugin and also creating the subgraph. It will cover the following topics:
 
-### Writing Your Plugin
+- [Dependency Installation](#dependency-installation)
+- [Contracts](#contracts)
+
+  - [Adapt the contracts](#adapt-template-contracts)
+  - [testing](#testing)
+    - [Unit Testing](#unit-testing)
+    - [Integration Testing](#integration-testing)
+  - [Deployment Scripts](#deployment-scripts)
+
+- [Subgraph](#subgraph)
+  - [Included scripts and `.env` file](#included-scripts-and-env-file)
+  - [Creating a Subgraph](#creating-a-subgraph)
+    - [`manifest/subgraph.placeholder.yaml`](#manifestsubgraphplaceholderyaml)
+    - [`schema.graphql`](#schemagraphql)
+  - [Handlers](#handlers)
+  - [testing](#testing-1)
+
+## Dependency Installation
+
+Before you begin, make sure you installed the necessary dependencies.
+For detailed instructions, refer to the [README](README.md).
+
+# Contracts
+
+## Adapt template contracts
+
+This template contains the boilerplate and it uses `MyPlugin` as the contracts names, in order to adapt them according to your needs follow the following steps:
 
 1. Go to the `packages/contracts/src` folder and
 
    - adapt and rename the `MyPlugin.sol` plugin implementation contract (see [our docs](https://devs.aragon.org/docs/osx/how-to-guides/plugin-development/upgradeable-plugin/implementation)).
    - adapt and rename the `MyPluginSetup.sol` plugin setup contract (see [our docs](https://devs.aragon.org/docs/osx/how-to-guides/plugin-development/upgradeable-plugin/setup)).
 
-2. Once finished, adapt the
+2. adapt the release and build metadata for the plugin:
 
    - `build-metadata.json` and
    - `release-metadata.json`
@@ -76,20 +102,91 @@ The standard deploy scripts in the `packages/contracts/deploy` should already be
 - `99_verification/10_verify-contracts.ts`
   - verifies all deployed contracts
 
+# Subgraph
+
+## Included scripts and `.env` file
+
+The current repo contains a set of 3 scripts to help you get started with your subgraph. These scripts are located in the `scripts` folder and are the following:
+
+- `build-manifest.sh`: Builds the `subgraph.yaml` file from the `subgraph.template.yaml` file.
+- `build-subgraph.sh`: Builds the subgraph from the `subgraph.yaml` file generated by the `build-manifest.sh` script.
+- `deploy-subgraph.sh`: Deploys the subgraph.
+
+These 3 scripts can be called with the `yarn` command:
+
+```bash
+# Build the subgraph.yaml file
+yarn build:manifest
+# Build the subgraph
+yarn build:subgraph
+# Deploy the subgraph
+yarn deploy
+```
+
+**REMEMBER**: You need to build the contracts before building the subgraph. You can do that by running `yarn build:contracts`
+
+If you use `yarn build` it will build the contracts, the subgraph.yaml file and the subgraph in that order.
+
+This scripts depend on the `.env` file located in the root of the repo. This file contains some variables that are relevant for this scripts. The variables are the following:
+
+```bash
+# SUBGRAPH
+
+## The Graph credentials
+GRAPH_KEY="zzzzzzzzzzzz"
+
 ## Subgraph
+SUBGRAPH_NAME="osx"
+SUBGRAPH_VERSION="v1.0.0"
+SUBGRAPH_NETWORK_NAME="mainnet" #  ["mainnet", "goerli", "sepolia", "polygon", "polygonMumbai", "base", "baseSepolia", "arbitrum", "arbitrumSepolia"]
+```
+
+- `GRAPH_KEY`: This key will be used for deploying the subgraph.
+- `SUBGRAPH_NAME`: The name of the subgraph.
+- `SUBGRAPH_VERSION`: The version of the subgraph.
+- `SUBGRAPH_NETWORK_NAME`: The network where the subgraph will be deployed. This will be used for generating the subgraph.yaml file.
+
+Editing this variables you can change how the subgraph is built and deployed.
+
+## Creating a Subgraph
+
+### `manifest/subgraph.placeholder.yaml`
+
+The first step to create a subgraph is to create or edit the `subgraph.placeholder.yaml` file. This file is located in the `manifest` folder. This file contains the template for the `subgraph.yaml` file. This file is used by the `build-manifest.sh` script to generate the `subgraph.yaml` file. You can find more information about the `subgraph.yaml` file [here](https://thegraph.com/docs/define-a-subgraph#the-subgraph-manifest).
+
+You will see that the `subgraph.placeholder.yaml` file contains some placeholders that will be replaced by the `build-manifest.sh` script. These placeholders are the following:
 
-### Handling Events
+- `{{dataSources.PluginSetupProcessors}}`: The object containing the processors for the plugin setup events.
+- `{{startBlock}}`: The block number where the subgraph will start indexing.
+- `{{address}}`: The address of the contract that will be indexed.
+- `{{network}}`: The network where the contract is deployed.
 
-The `packages/subgraph/src` folder contains a `plugin` and `osx` subfolder.
+These placeholders are substituted using [mustache](https://mustache.github.io/).
 
-In `plugint.ts` inside the `plugin` folder, you can add plugin-related event handlers.
+The files containing the replacement values are stored in `manifest/data`. Here you can find a JSON file for each network. The name of the file is the name of the network. For example, the file for the mainnet network is `mainnet.json`. This file contains a property called `dataSources` which holds the information about the contract that will be indexed. In this case, we are only indexing one contract but you can index multiple contracts by adding more objects to the `dataSources` object.
+
+### `schema.graphql`
+
+The second step to create a subgraph is to define the schema. The schema is defined in the `schema.graphql` file located in the `subgraph` folder. This file contains the GraphQL schema that will be used for querying the subgraph. The schema is defined using the GraphQL Schema Definition Language (SDL). You can find more information about it [here](https://graphql.org/learn/schema/).
+
+Here you can add your custom entities and how they are related to each other. You can find more information about the schema [here](https://thegraph.com/docs/define-a-subgraph#defining-the-schema).
+
+## Handlers
+
+Events handler functions are associated with the events in the `subgraph.yaml` file and defined in the `src` folder.
+
+The `src` folder contains a `plugin` and `osx` subfolder.
+In `plugin.ts` inside the `plugin` folder, you can add plugin-related event handlers.
 In `pluginSetupProcessor.ts` inside the `osx` folder, you can add plugin-setup-processor-related event handlers that your plugin might require.
 
-Finally, the events and event handlers must then be linked together in the `subgraph.placeholder.yaml` inside the `packages/subgraph/manifest` folder.
+For the `MyPlugin` example, two handlers are already provided:
 
-### Testing
+- `handleInstallationPrepared`: Handles the `InstallationPrepared` event. This event is emitted when the installation is prepared. This event contains the `installationId` and the handler will create a new `PluginEntity` entity with the `installationId` as the id.
+- `handleNumberStored`: Handles the `NumberStored` event. And stores the number in the `pluginEntity` entity in the `number` property.
+
+## Testing
 
-The `packages/subgraph/test` folder contains a `plugin` and `osx` subfolder where the tests for the event handlers from the previous section are written.
+This template uses [matchstick-as](https://github.com/LimeChain/matchstick) framework for unit testing.
+Similar to the `src` folder, the `test` folder contains a `plugin` and `osx` subfolder, where the tests for the event handlers from the previous section are written.
 
-In `plugint.ts` inside the `plugin` folder, you can test the plugin-related event handlers.
-In `pluginSetupProcessor.ts` inside the `osx` folder, you can test plugin-setup-processor-related event handlers that your plugin might require.
+In `plugin.test.ts` inside the `plugin` folder, you can test the plugin-related event handlers. In `pluginSetupProcessor.test.ts` inside the `osx` folder, you can test plugin-setup-processor-related event handlers that your plugin might require.

packages/contracts/.solcover.js

@@ -1,7 +1,7 @@
 module.exports = {
-  istanbulReporter: ['html', 'lcov'],
+  istanbulReporter: ['html', 'lcov', 'text'],
   providerOptions: {
     privateKey: process.env.PRIVATE_KEY,
   },
-  skipFiles: ['test'],
+  skipFiles: ['mocks'],
 };

packages/contracts/deploy/00_info/01_info.ts

@@ -0,0 +1,54 @@
+import {
+  AragonOSxAsciiArt,
+  getProductionNetworkName,
+  isLocal,
+} from '../../utils/helpers';
+import {getNetworkByNameOrAlias} from '@aragon/osx-commons-configs';
+import {DeployFunction} from 'hardhat-deploy/types';
+import {HardhatRuntimeEnvironment} from 'hardhat/types';
+import path from 'path';
+
+/**
+ * Prints information about the used/forked network and initial deployer wallet balance.
+ * @param {HardhatRuntimeEnvironment} hre
+ */
+const func: DeployFunction = async function (hre: HardhatRuntimeEnvironment) {
+  console.log(AragonOSxAsciiArt);
+  console.log(`${'-'.repeat(60)}`);
+  console.log(`\n✨ ${path.basename(__filename)}:`);
+
+  const [deployer] = await hre.ethers.getSigners();
+  if (isLocal(hre)) {
+    const productionNetworkName: string = getProductionNetworkName(hre);
+
+    console.log(
+      `Simulated deployment on local network '${hre.network.name}'. Forking production network '${productionNetworkName}'...`
+    );
+
+    // Fork the network provided in the `.env` file
+    const networkConfig = getNetworkByNameOrAlias(productionNetworkName)!;
+    await hre.network.provider.request({
+      method: 'hardhat_reset',
+      params: [
+        {
+          forking: {
+            jsonRpcUrl: networkConfig.url,
+          },
+        },
+      ],
+    });
+  } else {
+    console.log(`Production deployment on network '${hre.network.name}'.`);
+  }
+
+  console.log(
+    `Using account '${
+      deployer.address
+    }' with a balance of ${hre.ethers.utils.formatEther(
+      await deployer.getBalance()
+    )} native tokens.`
+  );
+};
+
+export default func;
+func.tags = ['Info', 'CreateRepo', 'NewVersion', 'UpgradeRepo'];