Skip to main content

Agent

The Agent App executes interactions with external Ethereum addresses, including smart contracts. Along with the Vault contract, the Agent can also hold its own Treasury, which a Finance App can manage. Multiple Agents can be helpful for various reasons, such as maintaining numerous treasuries or scoping permissions to external smart contracts related to your DAO or protocol (by making the Agent an owner or admin).

Installing the App​

There are no parameters needed to install a new agent to your DAO. However, the Agent relies on a tight set of permissions to do anything useful. Review the "Granting permissions" section before proceeding. You can use this syntax to install the Agent:

install agent:new

Common Usage Example​

When installing an Agent, we recommend grating the Voting app with the TRANSFER_ROLE, EXECUTE_ROLE, and RUN_SCRIPT_ROLE so exec agent and act agent commands can be used.

load aragonos as ar

ar:connect <organizationAddress> token-manager voting (
  install agent:new
  grant voting agent:new TRANSFER_ROLE voting
  grant voting agent:new EXECUTE_ROLE voting
  grant voting agent:new RUN_SCRIPT_ROLE voting
)

An Agent is a Vault on steroids, so after filling the Agent with some tokens, we can create a vote like this to transfer 1 ANT to my address:

load aragonos as ar

ar:connect <organizationAddress> token-manager voting (
  exec agent transfer @token(ANT) @me 1e18
)
Installing Different App Versions
If you want to install a different version of an Aragon app other than the default, you can use this syntax:
install <appName> [parameters...] --version <versionNumber>

For example:

install voting:new @token(HNY) 90e16 20e16 3d --version 1.0.0

It would install a new Voting app, using version 1.0.0, with HNY as the voting token, 90% support required, 20% quorum, and three days vote duration.

Granting Permissions​

warning

This command can potentially burn a permission manager if it is set to the wrong address, making the permission unable to be changed in the future. This is because we usually want to set the main Voting app as the permission manager of all permissions.

The Agent is made to carry out the requests from other apps or DAO members. So please, take some time to consider what entities need access to your Agent.

To grant permissions, you will use the following syntax:

grant <entity> <app> <roleName> [defaultPermissionManager]

In practice, this would look like this:

grant voting agent EXECUTE_ROLE voting

It would allow the Voting app to interact with external contracts or addresses using the Agent app.

Here is an exhaustive list of roles for the Agent app:

  • EXECUTE_ROLE
    • Allows an entity to execute an external transaction through the Agent.
  • SAFE_EXECUTE_ROLE
    • Allows the given entity to perform the safeExecute function through the Agent.
  • TRANSFER_ROLE
    • Allows an entity to transfer tokens from the Agent's balance.
  • ADD_PROTECTED_TOKEN_ROLE
    • Allows this entity to add tokens to a list of tokens that cannot be spent or transferred while the Agent executes an action using safeExecute.
  • REMOVE_PROTECTED_TOKEN_ROLE
    • Allows this entity to remove tokens from a list of tokens that cannot be spent or transferred while the Agent executes an action using safeExecute.
  • ADD_PRESIGNED_HASH_ROLE
    • Allows this entity to add a presigned hash to the Agent. Learn more.
  • DESIGNATE_SIGNER_ROLE
    • Designates this entity as a signer for the Agent. Learn more.
  • RUN_SCRIPT_ROLE
    • Allows this entity to run an EVM script on the Agent.
Types of Entities

An entity is an Ethereum Address. It can be specified using the Ethereum Address directly, using the entity identifier, or using an address that represents any entity.

  • Specified Eth Address is expressed as the ETH address starting with 0x. Only this address will be the specified entity.
  • Identifier is the name of the internal Aragon App installed on your DAO, such as voting, token-manager (representing any token holder), or agent.
  • Anyone is expressed as ANY_ENTITY and can be any user visiting your DAO with a web wallet.
Grant via an Oracle
You can create a condition for a grant command to be issued by specifying an oracle app to check specific parameters, such as token ownership. Only if the oracle returns true then is the permission request approved. Here's the syntax of how to implement this:
grant <entity> <app> <roleName> [defaultPermissionManager] --oracle <oracleAppName>

An excellent example of that is the 1hive token oracle Aragon app, which is an ACL oracle that returns true when the address that acts has a specific token. So take a look at this example:

grant ANY_ENTITY voting CREATE_VOTES_ROLE voting --oracle token-oracle.open

This action would grant any entity permission to create votes if they have a specific token. The token and minimum amount of tokens needed to hold would be specified when the app is installed on the DAO.

Revoking Permissions​

To remove permission from an entity, follow this syntax:

revoke <entity> <app> <roleName> [removePermissionManager=false]

In practice, this could look like this:

revoke voting agent TRANSFER_ROLE

It would remove the ability for the Voting app to transfer funds held by the Agent while keeping the Permission Manager in place should this permission need to be modified in the future.

Internal Actions​

Using the exec command, we can create internal actions.

We'll use the transfer function to show the syntax of the exec command. The base syntax looks like this:

exec agent[:<id>] transfer <token> <to> <amount>

For example:

load aragonos as ar

ar:connect exampleDAO token-manager voting (
  exec agent transfer @token(ANT) agent:1 100e18
)

It would create a vote to transfer 100 ANT tokens from the first Agent to the second Agent, given a second Agent is installed.

Below is an exhaustive list of all possible internal actions you can perform with the Agent app. In addition, we will identify the function in the contract and outline any parameters and permissions you need and the expected syntax to run them.

safeExecute
Executes the specified action to an external contract while preventing protected tokens from being spent.

Parameters​

  • target - The address of the external contract you want to interact with. (address)
  • data - Calldata for the action. (bytes)

Permissions​

The entity executing the action via the Agent will need the SAFE_EXECUTE_ROLE role.

Syntax​

exec agent safeExecute <target> <data>
addProtectedToken

It will add a specified token address to a list of tokens that cannot be spent or transferred while executed by the Agent using safeExecute.

Parameters​

  • token - The token address of the token you want to protect.

Permissions​

The entity executing the action via the Agent will need the ADD_PROTECTED_TOKEN_ROLE role. (address)

Syntax​

exec agent addProtectedtoken <token>
removeProtectedToken

It will remove a specified token address from a list of tokens that cannot be spent or transferred while executed by the Agent using safeExecute.

Parameters​

  • token - The token address of the token you want to remove from the protected tokens list. (address)

Permissions​

The entity executing the action via the Agent will need the REMOVE_PROTECTED_TOKEN_ROLE role.

Syntax​

exec agent removeProtectedtoken <token>
presignHash

Identifies a hash that will automatically be considered signed.

Parameters​

  • hash - The hash that will be considered signed automatically. (bytes)

Permissions​

The entity executing the action via the Agent will need the ADD_PRESIGNED_HASH_ROLE role.

Syntax​

exec agent presignHash <hash>
setDesignatedSigner

Sets an address as the designated signer of the app, which then can sign messages on behalf of the app.

Parameters​

  • address - The address of the entity you want to designate as the signer. (address)

Permissions​

The entity executing the action via the Agent will need the DESIGNATE_SIGNER_ROLE role.

Syntax​

exec agent setDesignatedSigner <address>
transfer

Transfers tokens from the Agent to a specified address.

Parameters​

  • token - The token contract address of the token you wish to transfer. (address)
  • to - The address to send tokens to. (address)
  • value - The number of tokens you wish to send, considering the decimal precision. (uint256)

Permissions​

The entity executing the action via the Agent will need the TRANSFER_ROLE role.

Syntax​

exec agent transfer <token> <to> <value>

External Actions​

The Agent uses the act command to interact with external entities such as smart contracts. The entity wishing to execute an external action will need the role RUN_SCRIPT_ROLE. The syntax is as follows:

act <agent> <targetAddress> <function> [inputParameters]

The functions for a given verified smart contract can be found on the write or write proxy page in the network's block explorer. For example, here is the contract for the DAI Stablecoin. We can use the basic task of sending DAI to another address to showcase the syntax for act:

load aragonos as ar

ar:connect exampleDAO token-manager voting (
  act agent @token(DAI) transfer(address,uint256) @me 100e18
)

As you can see, we use the helpers @token and @me to retrieve the required addresses.

A complete example could be to approve and deposit 1,000 DAI from the Agent to the Aave Lending Pool V2: (0x7d2768de32b0b80b7a3454c06bdac94a69ddc7a9).

load aragonos as ar
set $aaveLendingPool 0x7d2768de32b0b80b7a3454c06bdac94a69ddc7a9

ar:connect exampleDAO token-manager voting (
  act agent @token(DAI) approve(address,unint256) $aaveLendingPool 1000e18
  act agent $aaveLendingPool deposit(address,uint256,address,uint16) @token(DAI) 1000e18 agent 0
)

For an exhaustive list of functions that Agent can perform, check out the contract's code on Github.