A guide to FLOW CDS

How to create a CDS file for FLOW

Are you planning to create a CDS file for an event from a Flow chain? We’ve got you covered. This documentation will give you everything you need to create a CDS file for the Flow blockchain. 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.

Before you get started

To get the best out of this documentation, here are the housekeeping duties:
  • Have experience with the Flow blockchain and smart contract
  • Understand how to write and edit a JSON file.

Creating a CDS for FLOW

You can create a CDS file for the Flow blockchain in two ways. The first way is to write a CDS file manually from scratch, while the second way is to edit an existing CDS file. For the second method, you only need to change specific details in an existing CDS to customize the file to suit your requirement. It should be noted that the first method will normally take a little more time to complete (compared to the second option) since you are starting from scratch. However, whichever method you adopt, it’s good to check out a sample CDS for FLOW before getting started.

Key Elements in a FLOW CDS

Whether you intend to write your CDS from scratch or edit an existing one, there are some key elements that must be in the file. They are highlighted in this section.

A. First things First

  1. inputFields must have a computed field (meaning it is hidden from the user) of _grinderyChain; its default value must be flow:mainnet.
  1. inputFields must have a _grinderyContractAddress field for entering the contract address; this may be hidden from the user.
  1. You can obtain the field name of events from the contract page on Flow Blockchain Explorer. Check out this example for reference.

B. Signature! Signature!! Signature!!!

The signature of an event is constructed from one primary event with any number of secondary events. For instance, take a look at the sample signature below:
Image without caption
This means that Grindery monitors the TokensDeposited event and then merges the first TokensWithdrawn event in the same transaction while having the same amount field as the primary event. This is critical given that a transfer event is separated into “withdraw” and “deposit” events, and one transaction may contain multiple events in the same type. You can check out a sample transaction here. Ensure that you navigate to the event tab.

C. Best Practices to follow

There are also a few best practices and standards that you need to follow as you edit the CDS; they include the following:
  • For triggers, actions, and their associated fields, ensure that the name(s) are as descriptive as possible.
  • Provide user-friendly descriptions. Here, it is important to consider the difference between triggers and actions 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.
  • Use camelCase for connector, trigger, action and field ‘keys’. This is important for consistency.
  • 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 protected]", 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.

Eureka 🎉! You just created a CDS file for FLOW

Finally, submit the newly created CDS JSON file by creating a pull request here. The file should be saved to /cds/web3 folder.