| id | title | sidebar_label |
|---|---|---|
guides-use-agent |
How to use Aragon Agent |
Agent app |
The Agent app (or Aragon Agent) is an Aragon app that can be installed in any Aragon DAO. It's main feature is its ability to perform arbitrary calls to contracts. This means it can be thought of as the external interface of a DAO.
Put another way:
Aragon Agent is a fully-fledged Ethereum account owned by an Aragon organization. It's like a multi-signature account on steroids that enables organizations to interact with any Ethereum contract or protocol. Trading tokens on 0x or Uniswap, opening a Maker CDP, managing names in ENS, owning digital LAND parcels, or even breeding digital cats. Source
In technical terms, it's a superset of the Vault app, which means it can hold valuable assets ((ETH and ERC-20 tokens).
Concretely, the Agent app allows for things like:
-
An Aragon DAO to interact with other Ethereum smart contracts or protocols without the need to implement a custom Aragon app for every protocol.
-
Members of DAOs to identify themselves as their DAO when using any Ethereum dApp.
-
An Aragon DAO to participate as a stakeholder in another DAO.
Before we start, you'll need to head over to Aragon and create a new DAO with the democracy template.
If you're not sure how to do that, please have a look at this section of our User Guide.
The first thing you'll be asked to do is to choose the network for your organization. For the purposes of this guide we'll choose the Ethereum Testnet (Rinkeby).
Later on, you'll be asked to set three parameters for your organisation -- the support, the minimum acceptance quorum, and the vote duration.
We'll go with the following (sensible) defaults:
- Support: 100%
- Min. Quorum: 0%
- Duration: 168 hours (or 1 week)
The aragonCLI (Command Line Interface) is what we use to create, interact with, and develop Aragon apps.
Install it from NPM by running the following command:
npm install -g @aragon/cli
Hopefully, it downloaded successfully 😊.
If not, you should take a quick look at the installing aragonCLI section of our troubleshooting guide. It should help diagnose and fix the problem.
If that still doesn't fix things 😟, please reach out to us at the #dev-help channel on the Aragon Chat. We're more than happy to help.
Note that even if you've already installed the CLI, you might want to reinstall it to make sure you're up to date with the latest version.
Now that we've downloaded aragonCLI 🎉, we're ready to install the Agent app.
aragonCLI installs the aragon dao commands. We use these to interact directly with our DAO from the command line. They're also available directly using the dao shortcut.
We'll use the the dao install command to install the Agent app.
dao install takes two arguments:
- The address or aragonID name of an Aragon DAO.
- The package name of an Aragon app published to aragonPM (e.g. vault or vault.aragonpm.eth).
So in our case, to install the Agent app, we'll run:
dao install <your organisation name> agent --environment aragon:rinkeby --apm.ipfs.rpc https://ipfs.eth.aragon.network/ipfs/
You should see that after dao install <your organisation's name> agent we pass in two global options: --enviroment and --apm.ipfs.rpc.
The --environment option allows us to specify the network we want to use. In our case we've created our organization on rinkeby so we pass in aragon:rinkeby.
Note that if we had chosen the Ethereum Mainnet as the network for our organization we would have passed aragon:mainnet instead of aragon:rinkeby as the argument to --environment.
The --apm.ipfs.rpc option allows us to point to an IPFS node that has the files we are looking for. In our case we're pointing it to the aragon network IPFS node.
We can also run our own IPFS node by running aragon ipfs in another terminal window.
Running a local IPFS node allows us to run the same command without the --apm.ipfs.rpc option (since the --apm.ipfs.rpc option defaults to http://localhost:5001).
However, since IPFS propogation is slow, it's better to point directly to the aragon IPFS node.
Note that this step will trigger a vote in the DAO, you'll need to vote yes to confirm the installation of the Agent app. This is a consequence of how democracy governance of the organization was set up.
- Click on the Voting app icon on the left. You should you have one open vote.
- Click on the View vote button. You should see a panel pop up on the right hand side.
- Scroll to the bottom of the panel and click on the big green Yes button.
- Sign the transaction and voila! That's all there is to it. When you click on the Voting app again you should see the vote has passed with a 100% Yes vote.
If you look at the end of the output of the dao install command you ran in the previous step, you should see the following:
ℹ Successfully executed: "Execute desired action as a token holder"
⚠ After the app instance is created, you will need to assign permissions to it for it appear as an app in the DAO
What does this mean exactly 😕?
It's telling us that although we've successfully installed the Agent app, before we can use it as part of our DAO we need to define who can access the app's functionality.
In other words, we need to define who (or which app) has permission to execute actions in the Agent app and who can re-grant and revoke that permission.
In this guide we're going to give the Voting app permissions to execute actions on behalf of the Agent app, and therefore on behalf of the DAO.
To assign these permissions we need to get a hold of the Ethereum address of the Agent app -- remember Agent is a fully-fledged Ethereum account -- as well as the address of the Voting app.
To do this we'll use the dao apps command.
dao apps takes one argument: the address or name of an aragon DAO.
By default it only returns apps with permissions. But we can use the --all option to get it to return apps without permissions.
From the command line run:
dao apps <your organization name> --all --environment aragon:rinkeby
You should see a table that looks something like this:
| App | Proxy address | Content |
|---|---|---|
| kernel@vundefined | 0xa25fb31870bc492d450012ae32dafa72af9e82c3 | (No UI available) |
| acl@vundefined | 0xfefb0cdb7a1fac257815d52ba82776f98dc70205 | (No UI available) |
| evmreg@vundefined | 0x9087db02300ef24b116daf0426b6ba22b28a0c79 | (No UI available) |
| [email protected] | 0x15a102f80ea3b1bd585a044e9b3c39a84c5f44e5 | ipfs:QmPjWU51opgTVnXwAhYAWasL2CaiYHqy2mXdXtzqfC8sKx |
| [email protected] | 0x952a18185da912984e0bc8a830ba98f8151976af | ipfs:QmeMabCnkA5BtTTszqqRztYKCXZqE9VQFH4Vx7dY9ue2nA |
| [email protected] | 0x4171f7ac1a4606b93093e8648e2f9a16c59cf3b1 | ipfs:QmeMLs4jHya89khHVSubLaao9cZW6ELZUoYPHkwCUwKBH7 |
| [email protected] | 0xbf07e1c74a72aa60df3ddf3115d15575d27e61e1 | ipfs:Qmb9Bv3J9AuXD5auY1WNwiJeohnYRhyso7XMULs7EZ8eTG |
Followed directly by another that looks like this:
| Permissionless app | Proxy address |
|---|---|
| 0x9ac98dc5f995bf0211ed589ef022719d1487e5cb2bab505676f0d084c07cf89a | 0x843bfA21a040E742ec32b8F6991e182D9655AF21 |
The permissionless app is the Agent app we've just installed. Its address is listed under Proxy address in the bottom table. In my case that's 0x843bfA21a040E742ec32b8F6991e182D9655AF21 . Yours will be slightly different.
The Voting app address can be found under the Proxy address column in the voting app row of the first table: 0x15a102f80ea3b1bd585a044e9b3c39a84c5f44e5 .
Once you've located your Agent and Voting app addresses, run the following command:
dao acl create <your organisation name> <your agent app address> EXECUTE_ROLE <your voting app address> <your voting app address> --environment aragon:rinkeby
You should see the following output:
✔ Generating transaction
✔ Sending transaction
✔ Successfully executed
If you've reached this stage, 😊🎉 Congratulations! 🎉😊 You've successfully given your Voting app permissions to execute actions on behalf of your Agent app!
Why did that work 😕?
Before we explain the dao acl create command we ran above we need to understand a little bit about how permissions in Aragon work.
Aragon uses an Access Control List (ACL) to control who can access your app's functionality.
This list contains a set of who has permission to execute an action in an Aragon app and who can re-grant or revoke that permission.
dao acl create is just the Aragon command used to create a permission in the ACL.
It takes 5 arguments:
- The name or main address of the DAO.
- The address of the app whose - permissions are being managed (WHO).
- The identifier or name of the role (WHERE).
- The address of the app (or entity) that is being granted the permission (WHAT).
- The address of the app (or entity) that will be able to grant that permission or revoke it (HOW).
Let's revisit an annotated version of the command we ran above:
dao acl create
1. <your organization name>
2. <your agent app address>
3. EXECUTE_ROLE
4. <your voting app address>
5. <your voting app address>
--environment aragon:rinkeby
You should see that in our case:
-
1 is the name of our organization.
-
2 is our organization's Agent app -- we are managing the permissions of our Agent app by allowing the Voting app to execute actions on behalf of it.
-
3 is the EXECUTE_ROLE -- The EXECUTE_ROLE is a role defined in the Agent app: it allows an entity to execute a specific action through the Agent app (could involve a token transfer).
-
4 is our organization's Voting app -- we are granting this role to our Voting app, this allows it to execute actions on behalf of our Agent app.
-
5 is our Voting app again -- we are assigning it as manager of the role, this allows it to grant or revoke the permissions of this role.
Note that, same as before, this command will trigger a vote in the DAO and you'll need to vote yes to confirm the new permissions you've granted the Voting app.
You can do this either by using the UI again or,now that you know how to get the address of your apps, by running:
dao exec <your organization name> <your voting app address> "vote" 1 true true --environment aragon:rinkeby --apm.ipfs.rpc https://ipfs.eth.aragon.network/ipfs/
dao exec is used to perform transactions in your DAO directly from the aragonCLI. It takes at least three arguments:
-
The first is always the name or address of the DAO you want to interact with. In our case this is our DAO's name.
-
The second is the address of the app where the action is being performed. In our case this is the Voting app.
-
The third is the name of the method being executed in the app: In our case the method is
vote. -
The remaining arguments are the arguments which the method -- in our case
vote-- will be exectuted with. We are passing in three:1,trueandtrue.-
The first (
1) is the id for the vote we want to interact with. This is always an integer. Vote ids start at 0 and increment by 1 each time a vote is created. -
The second (
true) specifies which was we want to vote:truemeans yes andfalsemeans no. -
And the third (
true) specifies whether the contract should check if a vote already has enough support to be executed. By executed we mean that even if everyone else voted against, the vote would still be approved. If that's the case, the vote is executed and immediately closed.truemeans check,falsemeans don't check.
-
It's easy to find vote ids from the UI: see the red circle.
If you rerun the command:
dao apps <your organization name> --all --environment aragon:rinkeby
You should see that your Agent app has been added to the bottom of the App table and that the Permissionless app table is now empty.
| App | Proxy address | Content |
|---|---|---|
| kernel@vundefined | 0xa25fb31870bc492d450012ae32dafa72af9e82c3 | (No UI available) |
| acl@vundefined | 0xfefb0cdb7a1fac257815d52ba82776f98dc70205 | (No UI available) |
| evmreg@vundefined | 0x9087db02300ef24b116daf0426b6ba22b28a0c79 | (No UI available) |
| [email protected] | 0x15a102f80ea3b1bd585a044e9b3c39a84c5f44e5 | ipfs:QmPjWU51opgTVnXwAhYAWasL2CaiYHqy2mXdXtzqfC8sKx |
| [email protected] | 0x952a18185da912984e0bc8a830ba98f8151976af | ipfs:QmeMabCnkA5BtTTszqqRztYKCXZqE9VQFH4Vx7dY9ue2nA |
| [email protected] | 0x4171f7ac1a4606b93093e8648e2f9a16c59cf3b1 | ipfs:QmeMLs4jHya89khHVSubLaao9cZW6ELZUoYPHkwCUwKBH7 |
| [email protected] | 0xbf07e1c74a72aa60df3ddf3115d15575d27e61e1 | ipfs:Qmb9Bv3J9AuXD5auY1WNwiJeohnYRhyso7XMULs7EZ8eTG |
| 0x9ac98dc5f995bf0211ed589ef022719d1487e5cb2bab505676f0d084c07cf89a | 0x843bfa21a040e742ec32b8f6991e182d9655af21 | ipfs:QmfNaBuQsaKE8at2ce9k2FU9dKs16WQqg4RPUHSNik1z9e |
| Permissionless app | Proxy address |
|---|
This confirms that the Agent app has been assigned permissions and is now an app in the DAO.
Note that 0x9ac98dc5f995bf0211ed589ef022719d1487e5cb2bab505676f0d084c07cf89a is just the general identifier for the version of Agent app you have installed.
You can also verify that permissions have been set properly through the UI:
- Click on the Permissions menu option in the left panel. You should see the Agent app at the end of the second row. Click on it.
- Under Actions available on this app should see that the Voting app now manages who has the ability to execute actions for the Agent app. Scroll down.
- Under Permissions set on this app you should see that Voting app is also allowed to execute actions on behalf of the Agent app.
Exactly the same as before, revisit step 0 of the Setup section above if you need reminding 😋.
We've now created two Democracy DAOs -- let's call them A and B. A has an Agent app, B doesn't. We want to allow A to vote in B.
Remember that A needs to be a tokenholder of B to be able to vote in B. And that A's Agent app acts as its external interface.
In other words, A's Agent app allows it to participate as a stakeholder in B.
It follows that to allow A to vote in B we need to mint a token for A's Agent app in B.
To do this run:
dao exec <name of dao B> <token manager app address of dao B> mint <agent app address of dao A> 1000000000000000000 --environment aragon:rinkeby --apm.ipfs.rpc https://ipfs.eth.aragon.network/ipfs/
Remember, you can find the addresses of the apps in any of your DAOs by running dao apps <organization name> --environment aragon:rinkeby.
As you can see, we are using the dao exec command to interact with the mint method of B's Token Manager app.
mint is used to create new tokens and assign them to a receiver. It takes two arguments: a receiver address and the amount of tokens to be created.
In our case the receiver is A's Agent App, and the amount of tokens to be created is 1.
However, you should notice that instead of writing 1 as the second argument to mint we've gone with 1000000000000000000.
This is because a token has 18 decimals, so 1 unit of a token is actually 0.000000000000000001 tokens. This is not what we want.
In order to mint a full token from the CLI we need to pass the full number, which will then be interpreted with 18 decimals.
In our case this is a 1 followed by eighteen 0s, or 1000000000000000000.
Finally, the usual warning: running the above command will trigger a vote in B to create and send a token to A's Agent App: we'll need to vote yes to confirm the minting of the token.
Do this either directly through the UI or by running:
dao exec <name of dao B> <voting app address of dao B> "vote" 0 true true --environment aragon:rinkeby --apm.ipfs.rpc https://ipfs.eth.aragon.network/ipfs/
As in step 2, we'll run dao exec again, except this time the first argument to mint will be the address of the third entity we want to add to B.
dao exec <name of dao B> <token manager app address of dao B> mint <third entity's address> 1000000000000000000 --environment aragon:rinkeby --apm.ipfs.rpc https://ipfs.eth.aragon.network/ipfs/
Running the above will create a vote in B. Again we'll need to vote yes to confirm the minting.
As before, you can either do this through the UI or run the same command we ran at the end of step 2 with one small modification:
This time the first argument to "vote" will be a 1 and not a 0, since the id of this new vote is 1. Remember that vote ids start at zero and increment by one each time a vote is created.
Next, we will use A's Agent app to vote yes to adding a third entity to B.
But before we do this, we need to introduce the dao act command.
According to the documentation:
dao actprovides some syntax sugar overdao execfor executing actions using Agent app instances in a DAO.
In plain english, dao act acts like dao exec except the first argument to dao act is an agent app address rather than a DAO address.
Another minor difference is that we need to pass in the full signature of the method we wish to execute.
For example, if we want to execute the vote method of a Voting app we need to pass in vote(unint256,bool,bool).
Now that you have a high-level understanding of dao act, you're ready to run the following command:
dao act <agent app address of dao A> <voting app address of dao B> "vote(uint256,bool,bool)" 1 true true --environment aragon:rinkeby
Finally, we need to confirm the vote in A.
Again, we can do this either through the UI or by running:
dao exec <name of dao A> <voting app address of dao A> "vote" 2 true true --environment aragon:rinkeby --apm.ipfs.rpc https://ipfs.eth.aragon.network/ipfs/
Note that we passed in a vote id of 2 as the first argument to vote. That's because this is the 3rd vote created in A, and vote ids start at 0.
If you've made it this far, congratulations! 😊🎉😊🎉
You've just used the Agent app to allow one Aragon organization to participate as a stakeholder in another!