The Aragon OSx protocol is the foundation layer of the new Aragon stack. It allows users to create, manage, and customize DAOs in a way that is lean, adaptable, and secure.
Within this monorepo, you will be able to find 3 individual packages:
- Contracts: the Aragon OSx protocol contracts.
- Subgraph: contains all code generating our subgraph and event indexing.
- Contract-ethers: contains the connection between the ethers package and our contracts.
The contents of this repository are distributed via 3 different NPM packages:
@bosagora/osx
: The source files, including the protocol contracts and interfaces@bosagora/osx-artifacts
: The contracts bytecode and ABI to use the protocol or deploy it@bosagora/osx-ethers
: The TypeScript wrappers to use the protocol or deploy it using ethers.js
For more information on the individual packages, please read the respective README.md
.
The core smart contracts have been audited by Halborn.
- Security audit report
- The commit ID: cb0621dc5185a73240a6ca33fccc7698f059fdf5
- February 24th 2023
We'd love to hear what you think! If you want to build this with us, please find a detailed contribution guide in the CONTRIBUTION_GUIDE.md
file here.
Start by running yarn install
in the project root in your terminal.
Since the repo is set up as yarn workspace, all the linking is done automatically.
To review the contracts powering the Aragon OSx protocol, feel free to head to packages/contracts
.
The Aragon OSx protocol architecture is composed of two key sections:
- Core contracts: the primitives the end user will interact with. It is composed of mostly 3 parts:
- DAO contract: the main contract of our core. It holds a DAO's assets and possible actions.
- Permissions: govern interactions between the plugins, DAOs, and any other address - allowing them (or not) to execute actions on behalf of and within the DAO.
- Plugins: base templates of plugins to build upon.
- Framework contracts: in charge of creating and registering each deployed DAO or plugin. It contains:
- DAO and Plugin Repository Factories: creates DAOs or plugins.
- DAO and Plugin Registries: registers into our protocol those DAOs or plugins.
- Plugin Setup Processor: installs and uninstalls plugins into DAOs.
Additionally to those two sections, we have developed several plugins DAOs can easily install upon creation. These are:
- Token Voting plugin: enables token holders to vote yes, no or abstain on incoming DAO proposals
- Multisig plugin: enables DAO governance based on approval from a pre-defined members list.
- Addresslist Voting plugin: enables a pre-defined set of addresses to vote yes, no or abstain in a "one address, one vote" mode
- Admin plugin: enables full access to an account needing to perform initial maintenance tasks without unnecessary overhead
Let's dive into more detail on each of these sections.
The Core Contracts describe how every DAO generated by the Aragon OSx protocol will be set up. It is very lean by design and constitutes the most critical aspects of our architecture.
In a nutshell, each DAO is composed of 3 interconnecting components:
- The DAO contract: The DAO contract is where the core functionality of the DAO lies. It is the contract in charge of:
- Representing the identity and metadata of the DAO (ENS name, logo, description, other metadata)
- Holding and managing the treasury assets
- Executing arbitrary actions to:
- transfer assets
- call its own functions
- call functions in external contracts
- Providing general technical utilities like callback handling and others
- Permissions: Permissions are an integral part of any DAO and the center of our protocol architecture. The Permissions manager manages permissions for the DAO by specifying which addresses have permission to call distinct functions on contracts associated with your DAO. This Permissions manager lives inside the DAO contract.
- Plugins: Any custom functionality can be added or removed through plugins, allowing you to fully customize your DAO. You'll find some base templates of plugins within the
plugins
folder of the Core Contracts. Some examples of plugins that DAOs could install are:- Governance (e.g., token voting, one-address one-vote)
- Asset management (e.g., ERC-20 or NFT minting, token streaming, DeFi)
- Membership (governing budget allowances, access gating, curating a member list)
The following graphic shows an exemplary DAO setup:
An examplary DAO setup showing interactions between the three core contract pieces triggered by different user groups: The DAO
and PermissionManager
contract in blue and red, respectively, as well as two Plugin
contracts in green. Bear in mind, the DAO
and Permission Manager
components both coexist within the same DAO
contract. Function calls are visualized as black arrows and require permission checks (red, dashed arrow). In this example, the permission manager determines whether the token voting plugin can execute actions on the DAO, a member can change its settings, or if an DeFi-related plugin is allowed to invest in a certain, external contract.
In contrast, the Framework Contracts are in charge of creating and registering DAOs and plugins. Additionally, these contracts contain the PluginSetupProcessor
which installs, uninstalls, and updates plugins into DAOs upon request.
- Factories and Registries
- The DAO Factory: In charge of deploying instances of a new DAO based on the parameters given, including which plugins to install and additional metadata the DAO has (like a name, description, etc).
- The DAO Registry: In charge of registering DAOs into our protocol so plugins can easily access all DAO instances within our protocol. It is also in charge of giving DAOs subdomains for easier access.
- The Plugin Factory: A
PluginRepo
is the repository of versions for a given plugin. ThePluginRepoFactory
contract creates aPluginRepo
instance for each plugin, so that plugins can update their versioning without complexity in a semantic way similar to the App Store. - The Plugin Registry: In charge of registering the
PluginRepo
addresses into our protocol so that DAOs can access all plugins published in the protocol.
- Plugin Setup Processor: The processor is the manager for plugins. It installs, uninstalls, and upgrades plugins for DAOs based on the instructions provided by the plugin setup.
For a more detailed description of each of these components, please visit our Developer Portal.
Each plugin consists of two key components:
- The Plugin Logic: contains the logic for each plugin; the main functionality the plugin extends for the DAO. Can be linked to other helper contracts if needed.
- The Plugin Setup: contains the installation, uninstallation, and upgrade instructions for a plugin into a DAO.
You can find all plugins built by the Aragon team here.
The Aragon OSx contracts emits events that get indexed within our subgraph
. This subgraph
, whose source code can be found here, is what then fuels the Aragon SDK.
The contract-ethers package is the NPM package that provides ethers.js
wrappers to use the Aragon OSx contracts.
To run tests, run these commands in the 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
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.
To deploy contracts, run these commands in your terminal:
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
You can find more details about our deployment checklist here.
To release a new version of the NPM packages and the contracts add one of these labels release:patch
, release:minor
and release:major
.
This triggers the deployment of the contracts to the networks defined under packages/contracts/networks.json
. Merges to develop
triggers a release to testnets and merges to main
releases to the mainnets.
The labels also indicate how the npm packages will be bumped to the next version:
Label | Version bump |
---|---|
release:patch | patch bump for @bosagora/osx and @bosagora/osx-ethers |
release:minor | minor bump for @bosagora/osx and @bosagora/osx-ethers |
release:major | major bump for @bosagora/osx and @bosagora/osx-ethers |
Certain actions can be triggered via a command to a pull request. To issue a command just comment on a pull request with one of these commands.
Command | Description |
---|---|
/mythx partial (quick | standard | deep) |
Scans the changed files for this pull request |
/mythx full (quick | standard | deep) |
Scans the all files for this pull request |
/release (patch | minor | major) |
Adds the proper release label to this pull request |
/subgraph (patch | minor | major) |
Adds the proper subgraph release label to this pull request |