Admin Plugin

Project

The root folder of the repo includes two subfolders:

.
├── packages/contracts
│ ├── src
│ ├── deploy
│ ├── test
│ ├── utils
│ ├── ...
│ └── package.json
│
├── packages/subgraph
│ ├── src
│ ├── scripts
│ ├── manifest
│ ├── tests
│ ├── utils
│ ├── ...
│ └── package.json
│
├── ...
└── package.json

The root-level package.json file contains global dev-dependencies for formatting and linting. After installing the dependencies with

yarn install

you can run the associated formatting and linting commands.

Formatting

yarn prettier:check

all .sol, .js, .ts, .json, and .yml files will be format-checked according to the specifications in .prettierrc file.With

yarn prettier:write

the formatting is applied.

Linting

With

yarn lint

.sol, .js, and .ts files in the subfolders are analyzed with solhint and eslint, respectively.

Setting Environment Variables

To be able to work on the contracts, make sure that you have created an .env file from the .env.example file and put in the API keys for

• Alchemy that we use as the web3 provider
• Alchemy Subgraphs that we use as the subgraph provider
• the block explorer that you want to use depending on the networks that you want to deploy to

Before deploying, you MUST also change the default hardhat private key (PRIVATE_KEY="0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80").

Contracts

This package is located in packages/contracts.

Install Dependencies

yarn install

Building

To build the contracts on EVM based networks:

yarn build

On Zksync:

yarn build:zksync

Testing

To test your contracts on EVM based networks, run

yarn test

On Zksync:

yarn test:zksync

Linting

Lint the Solidity and TypeScript code all together with

yarn lint

or separately with

yarn lint:sol

and

yarn lint:ts

Coverage

Generate the code coverage report with

yarn coverage

Gas Report

See the gas usage per test and average gas per method call with

REPORT_GAS=true yarn test

you can permanently enable the gas reporting by putting the REPORT_GAS=true into the .env file.

Deployment

The deploy scripts provided inside ./packages/contracts/deploy take care of

1. Creating an on-chain Plugin Repository for you through Aragon's factories with an unique ENS name.
2. Publishing the first version of your Plugin and associated PluginSetup contract in your repo from step 1.
3. Upgrade your plugin repository to the latest Aragon OSx protocol version.

Finally, it verifies all contracts on the block explorer of the chosen network.

You don't need to make changes to the deploy script. You only have to update the entries in packages/contracts/plugin-settings.ts as explained in the template usage guide.

Creating a Plugin Repository & Publishing Your Plugin

Deploy the contracts to the local Hardhat Network (being forked from the network specified in NETWORK_NAME in your .env file ) with

yarn deploy --tags CreateRepo,NewVersion

This will create a plugin repo and publish the first version (v1.1) of your plugin. By adding the tag TransferOwnershipToManagmentDao, the ROOT_PERMISSION_ID, MAINTAINER_PERMISSION_ID, and UPGRADE_REPO_PERMISSION_ID are granted to the management DAO and revoked from the deployer. You can do this directly

yarn deploy --tags CreateRepo,NewVersion,TransferOwnershipToManagmentDao

or at a later point by executing

yarn deploy --tags TransferOwnershipToManagmentDao

To deploy the contracts to a production network use the --network option, for example

yarn deploy --network sepolia --tags CreateRepo,NewVersion,TransferOwnershipToManagmentDao,Verification

This will create a plugin repo, publish the first version (v1.1) of your plugin, transfer permissions to the management DAO, and lastly verfiy the contracts on sepolia.

If you want to deploy a new version of your plugin afterwards (e.g., 1.2), simply change the VERSION entry in the packages/contracts/plugin-settings.ts file and use

yarn deploy --network sepolia --tags NewVersion,Verification

Note, that if the deploying account doesn't own the repo anymore, this will create a createVersionProposalData-sepolia.json containing the data for a management DAO signer to create a proposal publishing a new version.

Note, that if you include the CreateRepo tag after you've created your plugin repo already, this part of the script will be skipped.

Upgrading Your Plugin Repository

Upgrade your plugin repo on the local Hardhat Network (being forked from the network specified in NETWORK_NAME in your .env file ) with

yarn deploy --tags UpgradeRepo

Upgrade your plugin repo on sepolia with

yarn deploy --network sepolia --tags UpgradeRepo

This will upgrade your plugin repo to the latest Aragon OSx protocol version implementation, which might include new features and security updates. For this to work, make sure that you are using the latest version of this repository in your fork.

Note, that if the deploying account doesn't own the repo anymore, this will create a upgradeRepoProposalData-sepolia.json containing the data for a management DAO signer to create a proposal upgrading the repo.

If you want to run deployments against zksync, you can use:

yarn deploy:zksync --network zksyncSepolia --tags ...
yarn deploy:zksync --network zksyncMainnet --tags ...

Subgraph

Installing

In packages/subgraph, first run

yarn install

which will also run

yarn postinstall

subsequently, to build the ABI in the imported folder.

Building

Build the subgraph and

yarn build

which will first build the contracts (see Contracts / Building) with

yarn build:contracts

second the subgraph manifest with

yarn build:manifest

and finally the subgraph itself with

yarn build:subgraph

When running yarn build, it requires a plugin address, which is obtained from the configuration file located at subgraph/manifest/data/<network>.json, based on the network specified in your .env file under the SUBGRAPH_NETWORK_NAME variable. You do not need to provide a plugin address for building or testing purposes, but it becomes necessary when deploying the subgraph.

During development of the subgraph, you might want to clean outdated files that were build, imported, and generated. To do this, run

yarn clean

Testing

Test the subgraph with

yarn test

Linting

Lint the TypeScript code with

yarn lint

Coverage

Generate the code coverage with

yarn coverage

Deployment

To deploy the subgraph to the subgraph provider, write your intended subgraph name and version into the SUBGRAPH_NAME and SUBGRAPH_VERSION variables in the .env file that you created in the beginning and pick a network name SUBGRAPH_NETWORK_NAME being supported by the subgraph provider. Remember to place correctly the Plugin address on the network you are going to deploy to, you can do that by adding it on subgraph/manifest/data/<network>.json. Then run

yarn deploy

to deploy the subgraph and check your Alchemy subgraph dashboard for completion and possible errors.

License

This project is licensed under AGPL-3.0-or-later.