Skip to content

Hacking on Aragon (WIP)

This guide is intended to help developers who aren't familiar with the Aragon stack to get hacking quickly. We will walk you through setting up your development environment from scratch and provide links to relevant documentation.

Hacking on Aragon at a hackathon? Check out our past information about Aragon @ ETHDenver here!

Setting up a dev environment

First you will need to install aragon-dev-cli:

npm install -g @aragon/cli

Once aragon-dev-cli is installed, the easiest way to create your first Aragon app is by initializing the project with a template:

aragon-dev-cli init [your-app-name].open.aragonpm.eth [boilerplate: "react" or "bare", defaults to "react"]

The values to be decided are:

  • App name: the app's name in the community open.aragonpm.eth Aragon Package Manager registry on Rinkeby. That is our public registry where Repos can be created on a first come first serve basis. Please note that after publishing the package for the first time, you will own the repo name and subsequent attempts to register that package will fail.

  • Template: the template to initialize the frontend part of your app. Right now you can choose between react or bare.

Coding your app smart contracts and the arapp.json file

Note: the following assumes you will want to build an Aragon app that can be integrated into the main Aragon dapp. If you'd like to just build on top of the smart contract permissioning and upgradability features of aragonOS, you can build your smart contracts and frontend as a completely independent dapp using whatever tools you like.

The stock Aragon Apps are a good example of how to build aragonOS compatible apps.

A few takeaways to get started quick:

  • Just by subclassing from the AragonApp baseclass, your contract is supercharged into an Aragon App.
  • Add the auth modifier to any function that you wish to protect behind the ACL. The role modifier takes a bytes32 role identifier. In order for aragon-dev-cli to correctly auto-generate artifacts for your app, roles must be set like this (same constant name and hashed string):
bytes32 constant public MY_FUNC_ROLE = keccak256("MY_FUNC_ROLE");
function myFunc(...) auth(MY_FUNC_ROLE) external { ... }
  • You can modify the template and migrations of your app to accommodate it to your usecase, by default npm run deploy:rpc will migrate your contract, deploy a local APM registry and deploy an instance using a template. For more template examples, you can check the templates directory in aragon-apps.

  • In the arapp.json file, all basic app metadata resides. It serves as an intermediary file that aragon-dev-cli combines with some values that it extracts from the source code directly such as roles and notice descriptions from functions. aragon-dev-cli ends up producing an artifact.json file that is used by aragon.js to correctly display apps.

Building your app front-end

Apps are not only contracts, they're also a front-end. To run apps in a secure manner, they have been sandboxed and only allowed to communicate through another protocol (Aragon RPC) as opposed to using Web3 directly.

This is where aragon.js plays its part. We provide a simple JavaScript library that handles RPC calls to the main Aragon dapp (called the wrapper, because it "wraps" the apps).

To get started, run npm i @aragon/client. This library provides helper methods for doing contract calls, transactions and event filtering.

Aragon.js is built using RxJS observables. To learn more about them, please refer to the RxJS documentation here

An API reference for @aragon/client can be found here.

Application state

Aragon.js is built around an event-sourced approach, so to build up your application state, we encourage you to listen for events and cache the application state.

Transactions and permission escalation

Transactions sent from apps to the wrapper are not executed directly - instead, they're what we call intents. Apps publish an intent to the wrapper, and the wrapper will traverse the ACL looking for possible paths whereby this intent can be fullfilled. To learn more about this, read about permission escalation here.

There is a full guide on how to build a simple Aragon app here.

Background jobs

Your application can specify a file that will be run inside a WebWorker in manifest.json under the script key.

As a rule of thumb, it is a good idea to build up your application state and send notifications from your WebWorker. Your front-end should just listen for changes in the application state (app.state()) and render that.

Running app inside the Aragon client

aragon-dev-cli playground

(If this doesn't work, ping Oliver)

Publising to the Rinkeby APM

aragon-dev-cli publish


Even though this guide goes through all the necessary steps taken to build an Aragon App, there is probably more things you will need to build a complex app:

  • aragonOS documentation: Explains the design philosophy of the smart contract system, how to build apps that will fit well with the rest of the system and all different components in depth. Also has a pretty good description of the Aragon Package Manager.

  • aragon-ui toolkit: Fairly complete UI toolkit for React apps that will make your app look as an Aragon native app.

  • aragon.js documentation: rather than full web3, Aragon apps use a specialized library for building apps.

  • aragon-dev-cli

Making it real

If you are enjoying working on Aragon, here are a few steps to get even deeper in the Aragon rabbit-hole:

  • Come to an Aragon organized/sponsored hackathon: we are going to be doing a few this year and it is the perfect setting to hack on a project for a weekend having some members of the team nearby to help. Best way to stay up to date is via Twitter or by checking the hackathons directory in this repo.

  • Apply for an Aragon Nest grant: You can check the currently accepted proposals looking for a team to make them a reality, or if you think you have an idea that would positively impact the Aragon and/or Ethereum ecosystem, create a new proposal. Grants are given to teams to support development of projects for a 3 month to 18 month timespan.

  • Help us push the boundaries of decentralized governance in Aragon Labs where we are working on multiple hard governance problems and making all the results of our research aragonOS compatible.

x doesn't work, y isn't documented, Aragon sucks

We are making a pretty big effort on developer tooling and documentation, so if you found something you feel we could improve please, fill an issue or let us know directly in the Aragon chat #dev channel.