Write Article
Create Collection
Import from medium
Sign in
POSTED 03 May 2018 00:40

Hacking on Aragon

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.

Setting up a dev environment

First you will need to install aragon-dev-cli:
npm install -g @aragon/cli
You will also need Truffle 4.0.5:
npm i -g truffle@4.0.5
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 locally

This command will deploy a DAO and everything you need, including installing your app on a local chain (that the command will start for you):
aragon run
In order to point the dapp to your local chain, you need to clone and follow the instructions in this pull request:

To open your DAO when you're running the dapp locally, go to http://localhost:3000/#/<your dao address>

Please note that this requires a local IPFS node to be running. Also, watch mode is not implemented yet, so when you make a change, you need to re-run the command.

Publising to the Rinkeby APM

In order to publish you need to create a keyfile in your local directory with the following values:
  "key": "<snip>"
  "rpc": "wss://",
  "ens": "0xfbae32d1cde628bc45f51efc8cc4fa1415447e"
Please note that you need to replace <snip> with private key with no password and that this key is only for Rinkeby, so it should only have Rinkeby Ether and you should never use it outside of the hackathon.

Save the file as .localkey.json in your home directory. You can now run the following command to publish your app:
aragon-dev-cli publish
  • Setting up a dev environment

  • Coding your app smart contracts and the arapp.json file

  • Building your app front-end

  • Running locally

  • Publising to the Rinkeby APM