@xinfin/osx-artifacts
v1.3.0-rc0
Published
The Aragon OSx Solidity contracts
Downloads
1
Keywords
Readme
Aragon OSx Protocol contracts
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
Get Started
To get started running your repository locally:
Copy .env.example
into a file called .env
or create a new one with these 3 keys defined:
# keys used for running tests
HARDHAT_DAO_ENS_DOMAIN=dao.eth
HARDHAT_PLUGIN_ENS_DOMAIN=plugin.eth
MANAGINGDAO_SUBDOMAIN=management
Run these commands on the project's root folder in your terminal:
npx hardhat accounts
npx hardhat compile
npx hardhat clean
npx hardhat test
npx hardhat node
npx hardhat help
REPORT_GAS=true npx hardhat test
npx hardhat coverage
npx hardhat run scripts/deploy.ts
TS_NODE_FILES=true npx ts-node scripts/deploy.ts
npx eslint '**/*.{js,ts}'
npx eslint '**/*.{js,ts}' --fix
npx prettier '**/*.{json,sol,md}' --check
npx prettier '**/*.{json,sol,md}' --write
npx solhint 'contracts/**/*.sol'
npx solhint 'contracts/**/*.sol' --fix
Documentation
You can find all documentation regarding how to use this protocol in Aragon's Developer Portal here.
Contributing
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.
Etherscan verification
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!"
Testing with Previous Contract Versions
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:
Step 1: Add the Previous Version as an Alias in package.json
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/[email protected]"
}
Step 2: Install Dependencies
Now, run the yarn install command to install the dependencies:
yarn install
Step 3: Update OSX_VERSION_ALIASES in the Script
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/'];
Step 4: Import the Contract in Your Solidity File
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} from '@aragon/osx-ethers-v1.2.0/{path_to_MyContract}';
import {MyContract____factory} from '@aragon/osx-ethers-v1.2.0/{path_to_MyContract__factory}';
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:
import {expect} from 'chai';
import {ethers} from 'hardhat';
import {SignerWithAddress} from '@nomiclabs/hardhat-ethers/signers';
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';
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]);
});
});
Performance optimizations
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.
Releases
Contract releases are tracked in Releases.md