Contract Action Templates
1. Description
Contract Action Templates enable admins of communities within Common to execute contract actions in a low code environment. Contract actions include changes or updates to the underlying smart contract such as proposals, token transfers, delegations etc. To use Contract Action Templates you will need to be an admin of a community on Common
The smart contracts currently supported for Contract Action Templates are:
Governor (Alpha/Bravo/OpenZeppelin)
ERC721/ERC1155
ERC20
AAVE
MolochDAO
How It Works
Navigate to the community you are an admin of using search or the sidebar. Within the community page, navigate to Contracts under Admin Capabilities
Click on Add Contract in the right top corner. This will prompt you to add the Contract Address for your smart contract. The Contract ABI file will be visible once you add a Contract Address that is valid and supported (refer list above for supported contract types)
Once you add a contract it will be available for community admins to connect to specific Contract Action Templates
Click on Enable action to bring up the Contract Action Form. You can either select from existing Contract Action Templates that are available or create a new Contract Action Template.
To create a new Contract Action Template, click on create new template. Add the name of the Contract Action this would execute, and add the relevant JSON blob. Refer to developer documentation on how to do this (link). Here is a list of contract action templates that you can create (link)
Select the Contract Action Template from the dropdown and fill out the details specific to the contract action that you want to execute
Select where you’d like this Contract Action Form available for the community to use
Create Sidebar (image)
Create Dropdown (image)
Types of templates
A non-exhaustive list of the types of templates that you can create using different contract types
Governor
Treasury Spend Proposal: A template that makes it easy to create a treasury spend proposal. Takes in as inputs a recipient, request amount, and other relevant metadata.
Vote Casting: Vote cast template takes in as inputs proposal id and decision (yes / no / abstain), enabling communities to vote on a proposal
Parameter Change: A template that makes it easy to update a parameter on the protocol owned by the Governor contract
ERC721/ERC1155
SendTo: Send and receive tokens
DelegateTo: This template allows you to delegate tokens to an address. This can be used if you want to delegate your votes to another member in the community
ERC20
DelegateTo: This template allows you to delegate tokens to an address. This can be used if you want to delegate your votes to another member in the community
SendTo: Send and receive tokens
AAVE
Treasury Spend Proposal: A template that makes it easy to create a treasury spend proposal. Takes in as inputs a recipient, request amount, and other relevant metadata.
Vote Casting: Vote cast template takes in as inputs proposal id and decision (yes / no / abstain), enabling communities to vote on a proposal
Parameter Change: A template that makes it easy to update a parameter on the protocol owned by the Governor contract
MolochDAO
Submit Proposal
Submit Vote
Proposal Processing
Rage Quit
Update Delegates
2. Using Contract Action Templates
Contract Action Template Schema
Schema v1.0
Creating Contract Action Templates
What is “creating” a template?
Creating a new Contract Action Template (CAT) is the process of identifying a contract type (i.e. ERC20), building a JSON blob meeting the template schema (see above), and uploading it to Common via the Create Template UI.
After a Contract Action Template is created, it is available to be linked to ANY contract with the same ABI. For instance, if you create a CAT for an ERC20 contract, any ERC20 contract linked to a specific Common community will be able to use an instance of the template to build a Contract Action Form (CAF).
Creating a CAT does not mean that your community will have immediate access to the associated Contract Action Form. See the section below for details on linking the CAT to your community and generating usable forms.
Structure of Contract Action Templates
Contract Action Templates are JSON blobs that consist of two main fields:
form_fields
andtx_template
The
form_fields
is used to define the appearance and behavior of the Contract Action Form (the UI that will be rendered to users of your template). All subfields should be defined per our UI Registry (see below). The interactive fields you create will be assigned a “field-ref” so their values can be used to format a transaction.The
tx_template
is used to define how these fields are formatted into a valid contract action. Here, the “field-refs” assigned in the prior section are used as inputs into a contract method call.Within the
tx_template
field there are 3 main fieldsmethod
: The name of the method the template should callargs
: An object with the methods arguments keys and “field-ref” valuestx_params
: An object with transaction parameters(ie value, gas, etc)
Example
UI Registry
Our v1.0 Contract Action Templates support a set of Common UI components that will be used to build your Contract Action Form. These elements are subfields of the
form_field
in your template. They include:Text Fields
Description: A simple text field to provide written context in the form.
Shape:
Text Inputs
Description: An input component to accept dynamic input from the user. Includes a “formatter” field to define a validation function on the input.
Shape:
Dividers
Description: A simple divider component to break up the form visually.
Shape:
Dropdowns
Description: A multi select dropdown to allow users to choose on option from a predefined set.
Shape:
Functions
Description: Functions are a special case for situations where function data needs to be encoded as a parameter for a parent functions(ie governance calldata)
Shape:
Going forward we plan to support more UI components, but these are sufficient for most use cases!
Validating Contract Action Templates
When you attempt to create a new template, Common will validate your template before allowing you to upload. Templates that do not meet your schema definition will be flagged as invalid in the UI, and will not be successfully uploaded to the platform.
Be aware that your template may be valid according to our schema but invalid as a way to construct the specific contract method call you intend. This can result in a Contract Action Form that is not functional. Be sure to double check the contract method in question to ensure your inputs match the expected parameters.
Constraints / Limitations
Only one method call can be called per template
Methods added to function type fields are not validated against the target contract ABI.
Confirm encoded calldata before sending and run local test transactions
Payable methods can not currently be templated
Examples of Templates
ERC20, Send Template
ERC20Delegate, Delegation Template
Delegate Cash, “Delegate To” Template
Governor, Treasury Spend Template
Governor, Parameter Change Template
Governor, Vote Casting Template
Aave, Treasury Spend
3. Connecting a CAT to your Community
Once a CAT is created (by you or any other Common user) it can be connected to your Common community and used to generate a Contract Action Form. This section will assume a CAT has already been created. As an example, we will use the ERC20 Send Template to walk through this process.
Steps to connect:
Adding a contract to your community
Identify an ERC20 contract relevant to your community. Visit the /contracts page in your community, and click “add contract”
Input the contract address. The ABI should auto populate- if you need to use a different ABI just paste it into the field. Click Add
Connecting a CAT
On the /contracts page, you should now see your contract
Assuming a CAT has been created for the ABI in question, you will see the “enable action” button appear. Click that button to open the contract action form:
Here, you select several fields:
Template (the CAT you want to connect)
Display Name (the name you want to appear in the link your Contract Action Form)
Action details
Slug (the url where your form will be served, i.e.
mycommunity/<contract-address>/my-link-name
)Display Option (where the button to view the CAF will be displayed)
Add the connection and you should see the CAT displayed below your contract in the /contracts page.
4. Using a Contract Action Form
We will continue with our example of an ERC20 Transfer template from the previous section.
Click “New My Token Transfer” in the dropdown.
You will see the Contract Action Form as defined by the template! Simply add content to the fields as needed.
After clicking create, you will be asked to confirm the transaction. Upon doing so, the transaction will be formatted and your wallet will ask you to confirm.
If the transaction was successful, a confirmation toast will alert you at the bottom of the screen. You can also check your wallet for transaction confirmation, as usual.
Last updated