Last updated by Jamiu Idowu 7 days ago
Traditional decentralized applications have been integrated one by one over the years. Then, Oracles and Automators made it faster for developers, safer for operators, and more decentralized. However, we can not build all integrations this way as it’s not sustainable. It’s like reinventing the wheel over and over again, relying on expensive developers.
Meanwhile, as you may already know, Web2 apps have delegated a large part of their integrations to users. Today, most successful Web2 SaaS companies have their own marketplaces for integrations and users can configure the integrations themselves. Zapier further empowered anyone to integrate and connect 5000+ Web2 applications. Now, guess what? Same model can work for Web3 dApps and the solution is Grindery!
Grindery Flow empowers users with do-it-yourself (DIY) integrations. It is a decentralized system that can interact with smart contracts and Web2 APIs. It allows you to define workflows and create a unified, seamless on-, off-, and cross-chain integration.
In particular, Grindery Flow renders intuitive user interfaces for end users to create workflows using what we call CDS (connector declaration schema), an enhanced ABI in JSON format. In a nutshell, the CDS file defines how the Grindery workflow engine interacts with external systems. Perhaps, the question in your mind now is; how do you create a CDS file? We will cover that in the rest of this documentation.
The first step in creating a CDS 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, access the CDS editor and click on Create Connector . You will see a pop-up, select the appropriate blockchain, add the smart contract address, and click Continue.
If the editor is able to fetch the ABI of the smart contract automatically, the next page gives you the good news. You can click Continue to move on with the creation of the connector or click “review and edit the ABI”.
Note: An ABI (Application Binary Interface) provides a contract with the ability to interact with external apps and other smart contracts. In most cases, you don’t need to edit the ABI.
If the CDS editor is unable to fetch your ABI automatically, you need to go to your blockchain explorer site to obtain the ABI manually. The explorer site to check depends on your contract’s chain. For example, you can get the ABI for an Ethereum smart contract on Ether Scan .
Once you have your ABI, either automatically generated or manually pasted, click Continue .
A new page appears where you can provide details about your Connector. You are required to add the connector name and upload an icon. You can also provide a short description of the Connector. Afterwards, click Continue. Eureka! You have successfully created your CDS. The CDS will be automatically saved and can now be found in your CDS workspace.
To edit the CDS, click the three dots (next to Draft) for the respective CDS and choose Edit as shown in the figure below.
You will be taken to a new page where you can edit the CDS including the triggers and actions. Under the list of Triggers or Actions on the left-hand side of the page, click on the respective trigger or action you want to edit.
On the edit page, you will have three different tabs namely Settings, Operations and Input Fields respectively. On the Settings tab, you can do the following:
Ensure that you click Save (at the bottom-left corner) after making your changes.
Under the Input Field tab, you can add a new user input field by clicking the Add User Input Field shown in the figure below. In addition, to make changes to the existing input fields,, click on the three dots for the respective field and click Edit. This takes you to the form editor where you can edit the field. As you make you edits, you will see the changes being automatically effected on the right side of the page (showing you exactly how it will be eventually displayed). Once you are done, click Save .
There are also a few best practices and standards that you need to follow as you edit the CDS; they include the following:
Change the auto-generated generated name(s) of the triggers and actions 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. It is important to put the difference between triggers and actions into consideration when providing 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. Check out the schema of field definition here .
To avoid redundancy, do not use the words connector, trigger, action or field when providing “names” for a connector, trigger, action or an input 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.
An input 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 "firstname.lastname@example.org", 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.
You have just created a new Web3 Connector. You can publish your connector anytime you wish.