EVMcrispr

EVMcrispr is still in active development and its API might change until it reaches 1.0.

A TypeScript library for Aragon-based DAOs that allows you to encode a series of actions into an EVM script that can be sent to forwarder apps.

Actions can be thought of as events performed by some entity inside a DAO such as installing apps, granting or revoking permissions, minting tokens, withdrawing funds, etc.

Documentation

Check out the documentation for an in-depth explanation of the API.

How does it work?

EVMcrispr offers two main methods to create EVM scripts containing actions: encode() and forward() (this one encodes the actions and forwards it afterwards).

Both methods receive two parameters: a group of the encoded actions and a group of forwarder apps used to forward the aforementioned actions.

The library exposes a series of methods that allows you to encode different actions such as installing an app, revoking a permission, etc. The idea is to invoke this methods inside an encode() or forward() to build the script. Here is an example of it:

await evmcrispr.forward(
  [
    evmcrispr.installNewApp(app, params),
    evmcrispr.addPermissions([permission1, permission2, permission3]),
    evmcrispr.revokePermission(permission, removeManager),
    // ...
  ],
  // forwarder apps path.
  [forwarder1, forwarder2]
);

The same EVMscript can be encoded using the evmcl template:

await evmcripsr.forward(
  evmcl`
    install ${app} ${param1} ${param2}
    grant ${entity1} ${app1} ${role1} ${permissionManager}
    grant ${entity2} ${app2} ${role1} ${permissionManager}
    grant ${entity3} ${app3} ${role3} ${permissionManager}
    revoke ${entity4} ${app4} ${role4} ${removeManager}
  `, // ...
  [forwarder1, forwarder2]
);

To facilitate the EVM script creation, you can use identifiers to reference DAO apps instead of using the contract address directly.

Below you can find a full example:

await evmcrispr.forward(
  evmcl`
    install wrapped-hooked-token-manager.open:membership-tm ${token} false 0
    install voting:membership-voting ${token} ${suppPct} ${minQuorumPct} ${voteTime}
    grant ANY_ENTITY voting:membership-voting CREATE_VOTES_ROLE
    grant voting:membership-voting wrapped-hooked-token-manager.open:membership-tm MINT_ROLE
    grant voting:membership-voting wrapped-hooked-token-manager.open:membership-tm BURN_ROLE
    exec wrapped-hooked-token-manager.open:membership-tm mint ${address} 2e18
  `,
  ["token-manager:1", "voting"]
);

Set up

1. Add the following dependency to your project:

   yarn add @commonsswarm/evmcrispr

2. Import the EVMcrispr class and the evmcl template:

   Import { EVMcrispr, evmcl } from '@commonsswarm/evmcrispr'

3. Create a new EVMcrispr by using the static method crate(). It receives an ether's Signer object and the DAO address to connect to:

   const evmcrispr = await EVMcrispr.create(signer, daoAddress);

4. Use the EVMcrispr's encode or forward functions to pass an array of actions, or an evmcl script.

Parametric permission utils

The following utils can be used to encode complex permission parameters:

• arg(i): Can be used to compare the ith parameter with a given value.
• oracle(address): Can be used to check the output of an external contract
• blocknumber: Can be used to compare a given value with the block number.
• timestamp: Can be used to compare a given value with the block timestamp.
• not(param): Can be used to negate a parameter.
• and(param1, param2): Can be used to compose two parameters with the AND logical function.
• or(param1, param2): Same as previous one with the OR logical function.
• xor(param1, param2): Same as the previous one with the XOR logical function.
• iif(param).then(param).else(param): Ternary operator for more complex logic expressions.

They can be used within the forth parameter of addPermission(entity, app, role, params) function.

Other examples

Below you can find some script examples that use EVMcrispr:

• Commons Upgrade script
• App installation script

Contributing

We welcome community contributions!

Please check out our open Issues to get started.