Welcome to the contracts powering the Aragon OSx Protocol!

Install the NPM package to import the solidity source files or the contract artifacts:

# solidity source files
yarn add @aragon/osx

# JSON ABI and bytecode
yarn add @aragon/osx-artifacts

Before starting make sure that you have created an .env file from the .env.example file and filled in the Alchemy API key. Feel free to add other API keys for the services that you want to use.

Now you can get started running your repository locally:

1. Install packages from the root folder with yarn
2. Change directory into this package (/pacakages/contracts)
3. Run yarn build to compile the contracts
4. Run yarn test to execute the test suite (this can take a while, so see performance optimizations for ways to speed up the tests).

Deployments use hardhat-deploy, and follow most of the conventions in the HH deploy docs.

See the deployment checklist for full details on how to deploy the contracts to a proper network.

When testing locally:

1. yarn deploy will run the test scripts against the local hardhat node.
2. yarn dev will spin up a persistent hardhat node and execute the deploy script against it automatically.
3. yarn deploy:reset will clear any prior deploy state stored by hardhat deploy.
4. yarn deploy:local will deploy a against a persistent localhost fork, clearing the deploy state between runs

Default values for all required environment variables are provided when running against hardhat, check the .env.example for details of what these are and what they mean.

The private key provided by default is a hardhat publically known key for 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266. Don't use it outside of a local development context.

Tests can be sped up if needed. See the test performance optimization section for more info.

You can find all documentation regarding how to use this protocol in Aragon's Developer Portal here.

If you like what we're doing and would love to support, please review our CONTRIBUTING_GUIDE.md here. We'd love to build with you.

If you believe you've found a security issue, we encourage you to notify us. We welcome working with you to resolve the issue promptly.

Security Contact Email: sirt@aragon.org

Please do not use the issue tracker for security issues.

To try out Etherscan verification, you first need to deploy a contract to an Ethereum testnet that's supported by Etherscan, such as goerli or sepolia.

In this project, copy the .env.example file to a file named .env, and then edit it to fill in the details. Enter your Etherscan API key, your Goerli node URL (eg from Alchemy), and the private key of the account which will send the deployment transaction. With a valid .env file in place, first deploy your contract:

hardhat run --network goerli scripts/sample-script.ts

Then, copy the deployment address and paste it in to replace DEPLOYED_CONTRACT_ADDRESS in this command:

npx hardhat verify --network goerli DEPLOYED_CONTRACT_ADDRESS "Hello, Hardhat!"

The @aragon/osx and @aragon/osx-ethers packages facilitate working with earlier versions of contracts by utilizing npm aliases. This is advantageous for testing contracts against varying versions without having to maintain multiple instances of the contracts within the repository.

Here's a step-by-step guide to import and test a contract from a previous version:

First, add an alias to your package.json under the dependencies section. This alias points to the specific version of the package you want to use.

For example, to use version 1.0.1 of the @aragon/osx package, add the following:

"dependencies": {
  "@aragon/osx-v1.0.1": "npm:@aragon/osx@1.0.1"
}

Now, run yarn to install the dependencies:

yarn install --ignore-scripts

Next, you need to inform the typechain generator script about this new alias. Open the script /scripts/osx-version-aliases.ts and append the alias name to the OSX_VERSION_ALIASES array:

export const OSX_VERSION_ALIASES = ['@aragon/osx-v1.0.1/'];

Now, you can import the desired contract using the alias you've set. Replace {path_to_contract} with the actual path to the contract within the osx package version you are using (in this example, version 1.0.1).

import '@aragon/osx-v1.0.1/{path_to_contract}.sol';

After successful contract compilation, TypeChain typings will be automatically generated. This will allow you to interact with the contract in a type-safe manner in your tests.

Here is a generic example of usage in a test:

import {MyContract____factory} from '@aragon/osx-ethers-v1.2.0/{path_to_MyContract__factory}';
import {MyContract} from '@aragon/osx-ethers-v1.2.0/{path_to_MyContract}';

describe('MyContract Test', function () {
  let myContract: MyContract;

  beforeEach(async function () {
    const signers = await ethers.getSigners();
    const myContractFactory = new MyContract__factory(signers[0]);
    myContract = await myContractFactory.deploy();
  });

  it('Should do something', async function () {
    const result = await myContract.someFunction();
    expect(result).to.equal(something);
  });
});

Please replace 'MyContract' with the actual name of your contract, and follow the same approach for the other placeholders (someFunction, something). This is an illustrative example; the actual test case will depend on the specific methods and functionality of your contract.

Example of usage in a test:

// chai-setup imports additional matchers used for mocking
import {expect} from './chai-setup';
import {
  DAO as DAO_V1_3_0,
  DAO__factory as DAO_V1_3_0_factory,
} from '@aragon/osx-ethers-v1.3.0/contracts/core/dao/DAO.sol';
import {SignerWithAddress} from '@nomiclabs/hardhat-ethers/signers';
import {ethers} from 'hardhat';

describe('Legacy Test Example', function () {
  let signers: SignerWithAddress[];
  let daoV1_3_0: DAO_V1_3_0;

  before(async function () {
    signers = await ethers.getSigners();
    const factory = new DAO_V1_3_0__factory(signers[0]);
    daoV1_3_0 = await DAO_V1_3_0.deployWithProxy<DAO_V1_3_0>(factory);
  });

  it('should be version 1.3.0', async function () {
    const result = await daoV1_3_0.protocolVersion();
    expect(result).to.equal([1, 3, 0]);
  });
});

There are 3 ways to run tests:

1. yarn test runs tests in sequence. Can take a while but is the default.

2. yarn test:parallel, depending on your hardware can be significantly faster and is generally good for most cases. See the hardhat docs for more information about parallelized testing. Not suitable for gas reports (see below)

3. yarn test:gas-report outputs a gas report. Cannot be run in parallel mode.

For faster runs of your tests and scripts, consider skipping ts-node's type checking by setting the environment variable TS_NODE_TRANSPILE_ONLY to 1 in hardhat's environment. For more details see the documentation.

Contract addresses can be obtained via the OSx artifacts NPM package.