Skip to main content

Finance

The Finance App will allow you to keep track of your DAO's finances, and each app can only interact with funds held in one Ethereum Address. Having multiple Finance Apps will allow you to manage various treasuries.

Installing the App​

The syntax is as follows to install the app:

install finance:new <vaultAddress> <periodDuration>

To Install the Voting App you'll need to include two parameters:

  • vault
    • This is the address of the installed Vault or Agent where the Finance app will manage funds.
  • periodDuration
    • This is the budgeting period duration. This parameter is required but only relevant if you plan to use the budgeting feature (currently not on the UI).

Common Usage Example​

You can install a Vault (or an Agent) alongside the Finance app and set up these permissions.

load aragonos as ar

ar:connect exampleDAO token-manager voting (
  install vault:new
  install finance:new vault:new 30d
  grant finance:new vault:new TRANSFER_ROLE voting
  grant voting finance:new CREATE_PAYMENTS_ROLE voting
)
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.

To grant permissions, you'll use the following syntax:

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

In practice, this would look like this:

grant voting finance CREATE_PAYMENTS_ROLE voting

It would allow the Voting app to create payments on the Finance app.

Before installing an app, you should consider any permissions needed to fit your purposes. Here is an exhaustive list of roles for the Voting app:

  • CREATE_PAYMENTS_ROLE
    • Allows an entity to create a payment request
  • CHANGE_PERIOD_ROLE
    • Allows an entity the budget period
  • CHANGE_BUDGETS_ROLE
    • Allows an entity to modify the budget for the set period
  • EXECUTE_PAYMENTS_ROLE
    • Allows an entity to execute payments
  • MANAGE_PAYMENTS_ROLE
    • Allows an entity to manage payments
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.

Some functionalities that have not yet been added to the UI are already present in the contract, including creating budgets and setting budget periods. You can create and manage these on the DAO but will have no practical way to interact with them on the UI, and you can learn more in the Aragon developer documentation.

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 finance EXECUTE_PAYMENTS_ROLE

It would remove the ability for the Voting app to execute a payment 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 newImmediatePayment function to show the syntax of the exec command. The base syntax looks like this:

exec finance[:<id>] newImmediatePayment <token> <to> <amount> <description>

For example:

load aragonos as ar

ar:connect exampleDAO token-manager voting (
  exec finance newImmediatePayment @token(ANT) 0x62Bb362d63f14449398B79EBC46574F859A6045D 100e18 "payment for documentation work"
)

It would request to send 100 ANT tokens to 0x62Bb362d63f14449398B79EBC46574F859A6045D with the context of "payment for documentation work", which would show up on a DAO vote.

Below is an exhaustive list of all possible actions you can perform with the Finance 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.

deposit

It will deposit approved ERC20 or ETH tokens into the Vault managed by the Finance app.

Parameters​

  • token - The address of the token you wish to deposit. (address)
  • amount - The number of tokens you wish to deposit. Take note of the token's decimal precision. (uint256)
  • reference - The reason for the deposit. (string)

Permissions​

No additional permissions are needed to perform this function.

Syntax​

exec finance deposit <token> <amount> <reference>

newImmediatePayment

It will create a new payment submission, requesting tokens in the Finance app's specified Vault.

Parameters​

  • token - The address of the token you request payment. (address)
  • receiver - The entity's address that will receive the tokens. (address)
  • amount - The number of tokens being requested. Take note of the token's decimal precision. (uint256)
  • reference - The reason for the deposit. (string)

Permissions​

The entity creating the action will need the CREATE_PAYMENTS_ROLE role.

Syntax​

exec finance newImmediatePayment <token> <receiver> <amount> <reference>
newScheduledPayment

It sets up a recurring payment scheduled for a specified amount of time at set intervals with a specified token.

Parameters​

  • token - The address of the token you request payment. (address)
  • receiver - The entity's address that will receive the tokens. (address)
  • amount - The number of tokens being requested. Take note of the token's decimal precision. (uint256)
  • initialPaymentTime - The timestamp of the first payment creation. (unint64)
  • interval - The amount of time between one payment and the next. (uint64)
  • maxExecutions - The maximum instances a payment can be executed. (uint64)
  • reference - The reason for the deposit. (string)

Permissions​

The entity creating the action will need the CREATE_PAYMENTS_ROLE role.

Syntax​

exec finance newScheduledPayment <token> <receiver> <amount> <initialPaymentTime> <interval> <maxExecutions> <reference>
setPeriodDuration

Changes the accounting period duration used for establishing periodic budgets.

Parameters​

  • periodDuration - The amount of time you want to change the budget duration. (uint64)

Permissions​

The entity creating the action will need the CHANGE_PERIOD_ROLE role.

Syntax​

exec finance setPeriodDuration <periodDuration>
setBudget

It will establish a budget, setting a cap on the amount of a specified token that can be paid out in each period.

Parameters​

  • token - The address of the token you wish to set a budget for.
  • amount - The maximum amount of specified tokens that can be paid out within the budget.

Permissions​

The entity creating the action will need the CHANGE_BUDGETS_ROLE role.

Syntax​

exec finance setBudget <token> <amount>
removeBudget

It removes any set budget for the specified token.

Parameters​

  • token - The address of the token you wish to remove a budget for.

Permissions​

The entity creating the action will need the CHANGE_BUDGETS_ROLE role.

Syntax​

exec finance removeBudget <token> <amount>
executePayment

Execute a pending payment.

Parameters​

  • paymentId - The numerical identifier of the pending payment. (uint256)

Permissions​

The entity that will execute the payment needs the EXECUTE_PAYMENTS_ROLE role.

Syntax​

exec finance executePayment <paymentId>
receiverExecutePayment

It allows the payment recipient to execute it without needing the EXECUTE_PAYMENTS_ROLE.

Parameters​

  • paymentId - The numerical identifier of the pending payment. (uint256)

Permissions​

No permissions are needed to execute this function, except the caller must be the payment recipient address.

Syntax​

exec finance receiverExecutePayment <paymentId>
setPaymentStatus

Can activate or disable a regular payment.

Parameters​

  • paymentId - The numerical identifier of the payment you wish to change the status of. (uint256)
  • active - Whether to change the payment status to active (true) or disabled (false). (boolean)

Permissions​

The entity wishing to change the payment status will need the MANAGE_PAYMENTS_ROLE role.

Syntax​

exec finance setPaymentStatus <paymentId> <active>
recoverToVault

It sends the entire holdings of a specified token held by this contract to the Vault/Agent. You can use it in case tokens are mistakenly sent to this contract.

Parameters​

  • token - The address of the token you wish to recover to the Vault.

Permissions​

No permissions are needed to perform this function.

Syntax​

exec finance recoverToVault <token>