Aragon website • Developer Portal • Join our Developer Community

Aragon OSx Protocol

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.

• Contracts: the protocol source code (solidity).
• Artifacts: the ABI and the contract addresses (per network)

NPM packages:

• @aragon/osx-artifacts: The deployed addresses, contract ABI's and bytecode

For more information on the individual packages, please read the respective README.md.

Audits

OSx smart contracts undergo regular audits.

v1.4.0

Halborn: audit report

• Commit ID: e0ba7b60b08fa1665ecac92dc12ea89e4245e7dc
• Started: 2024-11-18
• Finished: 2025-02-13

v1.3.0

Code4rena: link 1, link 2

• Commit ID: a2461ae61a8c4cc833a117120b76e306936f5e1c
• Started: 2023-03-03
• Finished: 2023-03-10

Halborn: link 1, link 2

• Commit ID: 0ad8cad2bb661fbd53086d097d11228304d9b73e
• Started: 2023-05-29
• Finished: 2023-06-13

v1.0.0

Halborn: link 1, link 2

• Commit ID: cb0621dc5185a73240a6ca33fccc7698f059fdf5
• Started: 2023-02-07
• Finished: 2023-02-24

ABI and artifacts

Check out the artifacts folder to get the deployed addresses and the contract ABIs.

Releases

The artifacts package is released by merging a PR that bumps npm-artifacts/package.json#version. CI tags and publishes automatically on merge — see npm-artifacts/README.md.

Contributing

See CONTRIBUTING.md for security reporting, PR expectations, and the SemVer classification rules used when bumping the protocol version.

Security

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.

Setup

You need Foundry and just. All Solidity dependencies are tracked as git submodules — no NPM, Yarn, or Node toolchain required.

git clone https://github.com/aragon/osx
cd osx
git submodule update --init --recursive
just build

How the Aragon OSx protocol works

To review the contracts powering the Aragon OSx protocol, feel free to head to src/.

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 member 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.

Core Contracts

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:

1. 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
2. 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.
3. Plugins: Any custom functionality can be added or removed through plugins, allowing you to fully customize your DAO. 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 diagram shows an example DAO setup:

An example 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 a DeFi-related plugin is allowed to invest in a certain external contract.

Framework Contracts

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. The PluginRepoFactory contract creates a PluginRepo 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.
  • The Member Registry: Permissionless self-registration of DAO members under a parent ENS domain. Members claim a subdomain, the registry grants per-node resolver approval so they manage their own ENS records (avatar, addr, contenthash) directly, and governance can revoke entries. See src/framework/member/MemberRegistry.sol.
• 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.

Plugins

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.

Aragon-built plugins live in their own repositories — see the Aragon GitHub organization.

Tests

just test                  # run unit tests via the just-foundry recipe
forge test                 # or invoke forge directly
forge test --gas-report    # include gas usage per test

Fork tests live under test/fork/ and run against a real RPC; standard CI excludes them. Run them locally with the appropriate RPC URL set.

See the Foundry book for advanced options.

Deployment

The split:

• Full OSx protocol bring-up on a new chain (core + plugins + ENS + Management DAO) is the job of aragon/protocol-factory — refer to its checklist.
• Component-level deploys and upgrades (e.g., MemberRegistry; future modernized registrars) live in this repo as scripts/Deploy<Component>.s.sol / scripts/Upgrade<Component>.s.sol. They run under just deploy-<component> / just predeploy-<component> (the predeploy- recipe dry-runs the same script without broadcasting), broadcast + verify via just-foundry, and print encoded governance actions for the Management DAO multisig.

See DEPLOYMENT.md for the component-deploy checklist (pre/post steps, ceremony coordination).