Last updated by Jamiu Idowu 20 days ago
This documentation empowers you with everything you need to know to create CDS for Web3 systems. CDS are essentially enhanced ABIs in JSON format that allows Grindery Nexus to render intuitive user interfaces for end users to create workflows. In a nutshell, they define how the Grindery Nexus workflow engine interacts with external systems.
To get the best out of this documentation, here are the housekeeping duties:
The first step in creating a CDS file is to get the contract address of the decentralized application on a specific chain. Based on the housekeeping requirements listed earlier, it is assumed that you understand how to obtain a contract address. For instance, the address may be for an Ethereum smart contract.
Next, you need to obtain the Application Binary Interface (ABI) of the smart contract in a blockchain explorer site, depending on the contract’s chain. As you know, an ABI provides a contract with the ability to interact with external apps and other smart contracts.
For example, you can get the ABI for an Ethereum smart contract on Ether Scan .
Open our ABI to CDS converter . Then, paste the ABI in the appropriate box and click Convert . A preliminary CDS will be generated. Copy the CDS and save it as a JSON file.
Now, it’s time to edit the preliminary CDS you just generated. This is perhaps the only step that takes a little time while creating a CDS file. See the preliminary CDS as a raw material that needs to be processed (edited) into a finished good (final CDS file).
To edit the CDS, do the following:
First, change the auto-generated “key” and “name” at the beginning of the CDS file to a proper key and a human-readable name, respectively, such that users can understand the smart contract to which the CDS belongs.
Then, review all triggers and actions as well as their associated fields. This can be done as follows:
Change generated name(s) to a more descriptive name(s) wherever possible. You may have to consult the documentation or source code of the smart contract to understand its purpose.
Provide user-friendly descriptions. At this juncture, it is important to put the difference between triggers and actions into consideration to provide appropriate descriptions. A trigger is an event that starts the connector app while an action activates a smart contract call. Both trigger and action schemas have four compulsory fields each: key, name, display and operation.
If you have a parameter that you need to choose from a list of values, add ‘choices’ to the field definition to specify the values. Check out the schema of field definition here .
There are also a few best practices and standards that you need to follow as you edit the CDS; they include the following:
To avoid redundancy, do not use the words connector, trigger, action or field when providing “names” for connector, trigger, action and field.
The “descriptions” for connector, trigger and action should be short (about 1-2 sentences). You should aim to clarify exactly what the connector/trigger/action does. Also, avoid repeating the “name” in the descriptions.
Trigger and action "operation" has two optional properties: "outputFields" and "sample". If a trigger or an action returns any data after being executed, it should be added to those properties. "outputFields" is an array of fields, similar to "inputFields", and it follows the same schema. "Sample” is an object with example output, where "key" represents a key of one of the output fields, and value is a sample value for that field.
Field can have a "placeholder" (optional), which should provide an example input. This will helps users understand the format of the value. It should not repeat the "label”. For instance, the “email” placeholder can be "email@example.com", not "Enter your email".
Field can have a "helpText". When not empty, the "i" icon will be added near the field label. Hovering on it will show you a tooltip. Help text can have more than one sentence, but you should aim to keep it as short as possible. It should only contain additional helpful information. You do not need to repeat a label or placeholder in the text. For example, if the field label represents a "recipient address", the helpText can provide information on where to get the address.
Connectors can have an "icon" property. Although it is optional, it is always good to include an icon in the connector. The icon must be a base64 encoded image string while the image should be in SVG or PNG format, with 24x24px size and transparent background.
Finally, submit the newly created CDS JSON file by creating a pull request here . The file should be saved to /cds/web3 folder.