How to use Overledger on Make

Introduction

The Overledger App on Make has available triggers and actions.

All of the triggers and actions fall into two main categories:

1. Reading Data

Overledger allows data to be read from the blockchain. Currently, the Make Overledger app allows users to read data from any smart contract functions.

2. Monitoring Data

Overledger allows for the possibility of monitoring either

  • Smart contracts events
  • Blockchain accounts for when a transaction is sent to or from a particular address.

In the Make Overledger app, users can create, read, update, and delete webhooks monitoring both smart contracts and blockchain accounts.
All of these categories of functionality share consistent input fields as well as having some additional bespoke fields, both of which will be discussed over the next few subsections.

3. Writing Data

Overledger allows data to be written to the blockchain, via transactions. Currently, the Make Overledger app allows users to prepare and execute the following types of transactions

  • Fungible Token Transfers
  • Non-Fungible Token Transfers
  • Smart Contract Function Invocations
  • Smart Contract Code Deployments
  • Native Asset Transfers

All of these categories of functionality share consistent input fields as well as having some additional bespoke fields, both of which will be discussed over the next few subsections.

Available Overledger Instance, Technology and Network Combinations

Each Make Overledger trigger and action requires you to define the Overledger Instance, the Blockchain Technology, and the Blockchain Network to interact with.

The currently available options on Make are listed in the following table:

Overledger environmentTechnologyNetwork
Sandboxethereumsepolia testnet
Sandboxethereumgoerli testnet
Sandboxethereumpolygon mumbai testnet
Sandboxethereumavalanche fuji testnet
Sandboxethereumxdc apothem testnet
Productionethereumethereum mainnet
Productionethereumpolygon mainnet
Productionethereumavalanche c-chain mainnet
Productionethereumxdc network mainnet

As you can see, the Sandbox Overledger instance allows you to connect to test blockchain networks (which hold no real-world value tokens), whereas the Production Overledger instance allows you to connect to the main blockchain networks (which hold tokens with a real value).

πŸ“˜

Make currently only supports the Ethereum blockchain technology. If necessary, additional technologies can be added to the Make integration in the future. Contact Quant if you have any questions regarding this.

1. Reading Data from a Blockchain

Reading data from a blockchain can be completed in one Make action in the Overledger app, called Read a Smart Contract Function.

Once you have selected this action and the Overledger platform account you will be using, then you should fill in the action input fields, which we describe below:

Select the Overledger Instance, Technology and Network

The possible options are listed above.

Select the Smart Contract Identifier

Overledger requires you to define the specific identifier of the smart contract you want to read from. For Ethereum technologies, this identifier is equal to the contract's address.

Select the Function Name

Overledger requires you to define the specific name of the smart contract function you want to read.

You will have to look at the smart contract code to understand the functions available for this contract. Potentially you will have the code available to you locally. Or you will need to go to a block explorer and search for that particular contract identifier and look at the code in the block explorer - if it is available.

πŸ“˜

Smart contract code might not have been uploaded to a block explorer as this is a manual and optional process conducted by the creator of the smart contract.

For example, we can see in the polygonscan block explorer here, that possible read function names include: (a) number; (b) readOneAInputOneAOutput; (c) readOneUIInputsTwoUIOutputOneTwoEight; (d) readTwoSInputsOneSOutput; and (e) readTwoUIInputsTwoUIOutputs.

Understand the Function's Input and Output Parameters

Overledger requires you to define the input and output parameters of the smart contract function you want to read from.

Each input parameter needs a type and value parameter. Whereas each output parameter requires a type parameter.

For each Ethereum technology based network, Overledger supports the three core categories of Solidity types described here:

  • Basic Types: uint, int, string, address, bool, bytes, any of the following {uint8,uint16,...,uint248,uint256} and any of the following {bytes1,bytes2,...bytes31,bytes32}
  • Dynamic Array Types: {uint[],int[],string[],address[],bool[], bytes[]}, any of the following {uint8[],uint16[],...,uint248[],uint256[]} and any of the following {bytes1[],bytes2[],...bytes31[],bytes32[]}
  • Fixed Array Types: {uint[X],int[X],string[X],address[X],bool[X],bytes[X], any of the following {uint8[X],uint16[X],...,uint248[X],uint256[X]} and any of the following {bytes1[X],bytes2[X],...bytes31[X],bytes32[X]}, where X is an unsigned integer.

For example, we can see in the etherscan block explorer here, that possible read function options include:

  • (a) the number function - requiring no inputs and one uint256 type output;
  • (b) the readOneAInputOneAOutput function - requiring one address type input and one address type output;
  • (c) the readOneUIInputsTwoUIOutputOneTwoEight function - requiring one uint128 type input and two uint128 type outputs;
  • (d) the readTwoSInputsOneSOutput function - requiring two string type inputs and one string type output;
  • (e) the readTwoUIInputsTwoUIOutputs function - requiring two uint type inputs and two uint type outputs.

Example Request and Responses

This Make Overledger action for reading smart contract data relates to the Overledger Platform API found here

Below, we provide screenshots of example smart contract reads through Zapier.

πŸ“˜

The contract used for testing is a simple one where all the read functions have very basic functionality - to return the same value as given in the input.

(a) number - requiring no inputs and one uint256 type output.

Input Fields example:

(a) number - requiring no inputs and one uint256 type output.

Response body example:

(b) readOneAInputOneAOutput - requiring one address type input and one address type output.

Input Fields example:

(b) readOneAInputOneAOutput - requiring one address type input and one address type output.

Response body example:

(c) readOneUIInputsTwoUIOutputOneTwoEight - requiring one uint128 type input and two uint128 type outputs.

Input Fields example:

(c) readOneUIInputsTwoUIOutputOneTwoEight - requiring one uint128 type input and two uint128 type outputs.

Response body example:

(d) readTwoSInputsOneSOutput - requiring two string type inputs and one string type output.

Input Fields example:

(d) readTwoSInputsOneSOutput - requiring two string type inputs and one string type output.

Response body example:

2. Monitoring Data on a Blockchain

Registering to monitor a smart contract or blockchain account can be completed in one Zapier action, called Create a Webhook in the Overledger app.

Once you have selected this action and the Overledger platform account you will be using, then you should fill in the action input fields, which we describe below:

Select the Overledger Instance, Technology and Network

The possible options are listed above.

Select the Webhook Type and Address

Overledger requires you to define the specific webhook type and the address.

Overledger supports two types of webhooks:

Account: Monitoring transactions sent to or from a particular address.
Smart Contract: Monitoring events fired (emitted) from a smart contract.

You should select the webhook type you prefer and then input the address, which will be equal to the smart contract identifier, should you want to monitor a particular smart contract.

In the following examples, for the smart contract monitoring testing we will be using the 'Basic Parameter Type Event Testing Contract' deployed on the polygon mumbai network at this address 0x8590d37d55049de2555f0f9541325e7fe6b19b17.

Therefore the smart contract identifier of this smart contract is 0x8590d37d55049de2555f0f9541325e7fe6b19b17.

Whereas for the account testing, we will be using the non-smart contract account at this address0x1789d90438333751fdcca0d03d8952168b99ef02.

Therefore the identifier of this account is 0x1789d90438333751fdcca0d03d8952168b99ef02

Example Request and Responses

This Make Overledger action relates to the two different Overledger APIs found here for the smart contract webhook type and here for the account webhook type.

For our Make examples we present the following screenshots:

(i) Create a smart contract webhook.

Input Fields:

(i) Create a smart contract webhook. Response body:

(ii) Create an account webhook. Input Fields:

(ii) Create an account webhook. Response body:

Await callback data

Once the monitoring has been setup, Overledger will serve data as and when it occurs. To trigger this process a transaction will have to be sent to the monitored address (for the account webhook type to fire), and additionally this transaction will have to trigger a smart contract event (for the smart contract webhook type to fire).

For our Make examples we present the following example data:

(i) Create a smart contract webhook. callback data:

The following is example callback data received for an example webhookId when a smart contract emits an event.

{  
  "type": "smartContractEvent",  
  "webhookId": "6c964253-4b10-43a5-a812-9b30e92275a3",  
  "location": {  
    "technology": "ethereum",  
    "network": "polygon mumbai testnet"  
  },  
  "smartContractEventUpdateDetails": {  
    "smartContractId": "0x8590d37d55049de2555f0f9541325e7fe6b19b17",  
    "nativeData": {  
      "removed": false,  
      "logIndex": 0,  
      "transactionIndex": 0,  
      "transactionHash": "0xde2bbf9704d726ff395eb78217e9acb226b0ecb0b609021cccd7e67d99763db2",  
      "blockHash": "0x6d1a13d15fd0a90f361d3e368830bbe45c628382c4533d10f1a23ae699c781cc",  
      "blockNumber": "0x28b2471",  
      "address": "0x8590d37d55049de2555f0f9541325e7fe6b19b17",  
      "data": "0x0000000000000000000000001789d90438333751fdcca0d03d8952168b99ef02",  
      "topics": [  
        "0x2d1801d4e6df986759c8582affebc974bcf0cacfd5d2ab120eb776efa53dffa2"  
      ]  
    }  
  }  
}

To parse this callback data correctly, you will need to have access to the smart contract code to understand it. Please refer here to understand how to decode smart contract events.

(ii) Create an account webhook. Callback data:

Account callback data is simpler than smart contract callback data, making it easier to understand. Below is example callback data received for an example webhookId when a transaction is sent to or from the monitored address.

{  
  "type": "account",  
  "webhookId": "20f6ce08-04b4-4ce4-94eb-e2304a0737af",  
  "accountId": "0x282f70d5af34aedaac479b12a08e189bbee83066",  
  "location": {  
    "technology": "ethereum",  
    "network": "polygon mumbai testnet"  
  },  
  "transactionId": "0xd65c16e476a5ad5fa89ffe14512bd7984e575a4370ac86ccfb88202da20f9262"  
}

Manage your webhook

Now that your webhook is up and running, through one Make action in the Overledger app, you can do the following:

  • Read the webhook via the Read a Webhook action;
  • Update it (by providing a new callback URL) via the Update a Webhook action; or
  • Delete it via the Delete a Webhook action.
  • Additionally, you can read all the webhooks associated with this clientId via the Read Webhooks action.

3. Writing Data to a Blockchain

Writing data to a blockchain can be completed in three Make actions in the Overledger app. These actions need to follow the prepare-sign-execute Overledger flow, which is described here. There are multiple options for each stage of the flow.

  1. Prepare transaction: choose one of the following Make actions Prepare a Transfer of Fungible Tokens, Prepare a Transfer of a Non-Fungible Token, Prepare a Smart Contract Transaction, Prepare a Smart Contract Deployment Transaction or Prepare a Native Asset Transfer.
  2. Sign transaction: choose the Make action Sign a Transaction.
  3. Execute transaction: choose one of the following Make actions Execute a Signed Token Transfer Transaction, Execute a Smart Contract Invoke Transaction, Execute a Smart Contract Deployment Transaction, or Execute a Native Asset Transfer.

❗️

Choose the correct pair of preparation and execution actions:

Note that you will need to choose the correct pair of preparation and execution actions:

  • Prepare a Transfer of Fungible Tokens requires Execute a Signed Token Transfer Transaction
  • Prepare a Transfer of a Non-Fungible Token requires Execute a Signed Token Transfer Transaction
  • Prepare a Smart Contract Transaction requires Execute a Smart Contract Invoke Transaction
  • Prepare a Smart Contract Deployment Transaction requires Execute a Smart Contract Deployment Transaction
  • Prepare a Native Asset Transfer requires Execute a Native Asset Transfer

Each pair will of course need a sign transaction action in the middle, for example:

Once you have selected the actions and the Overledger platform account you will be using, then you should fill in the action input fields, which we describe below:

Prepare Transaction

The first stage of the process is to understand which type of transaction you want to prepare and execute. Make has different actions for each type, as introduced above and explained in more detail in the following subsections:

Prepare a Transfer of Fungible Tokens

If you want to move a fungible token of the QRC20 type, ERC20 type, or an extension of either, you can use this Make action.

❗️

Account Balance:

the signing account will need to own the amount of tokens that you want to transfer.

Example request and response:

This example prepares a transaction that will move 2 of these fungible tokens on the Ethereum Sepolia Testnet from the sender account 0xF1652f7fD9f4186A7Bc5D23dD04Aa88951A90609 to the receiving account 0x1789d90438333751fDCcA0D03d8952168b99eF02.

❗️

Token Amount Decimals:

Note that there is no decimal place used on ethereum blockchains. But you have to put into the token amount the number of zeros that correspond to the number of decimal places that the token has.

Input Fields example:

Response body example:

Prepare a Transfer of a Non-Fungible Token

If you want to move a fungible token of the QRC721 type, ERC721 type, or an extension of either, you can use this Make action.

❗️

Token Ownership:

the signing account will need to own the NFT token that you want to transfer.

Example request and response:

This example prepares a transaction that will move NFT number 4 of these non fungible tokens on the Ethereum Sepolia Testnet from the sender account 0xF1652f7fD9f4186A7Bc5D23dD04Aa88951A90609 to the receiving account 0x1789d90438333751fDCcA0D03d8952168b99eF02.

Input Fields example:

Response body example:

Prepare a Smart Contract Transaction

If you want to call a non-transfer function of a token contract, or call any other smart contract function, then you can use this Make action.

Example request and response:

This example prepares a transaction that calls the function 'writeOneAInput' from this contract on the Ethereum Sepolia Testnet from the sender account 0xF1652f7fD9f4186A7Bc5D23dD04Aa88951A90609. This function requires one address parameter, which is instantiated as 0x1789d90438333751fDCcA0D03d8952168b99eF02.

Input Fields example:

Response body example:

Prepare a Smart Contract Deployment Transaction

If you want to deploy a new smart contract, then you can use this Make action.

To deploy a smart contract on an Ethereum-based blockchain, you will need to understand that what is deployed on the blockchain is not the user-understandable code (e.g. Solidity), but it is instead the machine-readable bytecode. When a smart contract is deployed in a transaction, if the smart contract constructor function requires input parameters, then these need to be provided. Therefore the deployed bytecode is made up of two parts:

  1. Compiled Smart Contract Code
  2. Complied Smart Contract Constructor Parameters

There are two ways to provide Overledger with this information, both of which will be covered in the examples below.

First example request and response:

This example provides Overledger with the compiled smart contract bytecode and separately the smart contract constructor parameters in the Overledger standardised format. Given this request, Overledger will take the given smart contract constructor parameters, format them correctly, and attach them at the end of the contract bytecode in order to create a correctly formatted transaction.

Input Fields example:

❗️

Constructor Parameters Should Not be Provided Twice:

In the above example, the constructor parameters are added in the standardise manner via the "Constructor Parameters" section, and are therefore not embedded at the end of the "Contract Bytecode" section.

πŸ“˜

Contract Bytecode Without Constructor Parameters:

This can be retrieved from multiple locations. For instance, if your Solidity code is in the online Remix Integrated Development Environment, then you can retrieve the contract bytecode without constructor parameters, after you have compiled your contract, via the 'Solidity Compiler' tab and the 'Bytecode' button, e.g.:

Response body example:

Second example request and response:

This example provides Overledger with both of the compiled smart contract code and the compiled smart contract constructor parameters as one bytecode.

Input Fields example:

❗️

Constructor Parameters should not be provided twice:

In the above example, the constructor parameters are embedded at the end of the "Contract Bytecode" and hence they are not added in the standardise manner via the "Constructor Parameters" section, which is instead left empty (i.e. []).

πŸ“˜

Contract Bytecode With Constructor Parameters:

This can be retrieved from multiple locations. For instance, if your Solidity code is in the online Remix Integrated Development Environment, then you can retrieve the contract bytecode with constructor parameters, after you have compiled your contract and you have instantiated the constructor parameters, via the 'Deploy and Run Transactions' tab and the 'Calldata' button, e.g.:

Response body example:

Prepare a Native Asset Transfer

If you want to transfer the native asset of the blockchain (e.g. ETH or Ethereum, MATIC for polygon, AVAX for Avalanche or XDC for the XDC Network), then you can use this Make action.

Example request and response:

Input Fields example:

Response Body Example:

Sign Transaction

The second stage of the process is to sign the transaction that was just prepared. Make has one action to sign all types of prepared transactions: Sign a Transaction. Due to the way Make formats the responses from the Prepare transaction actions, before we sign a transaction there will need to be a Transform to JSON action, e.g.:

Example request and response:

The JSON action, simply takes the nativeData parameter returned from the prepare transaction action:

And converts it to a JSON string. See the following response:

Now moving onto the input fields example for the 'Sign a Transaction' action, note that it utilitises the output of the JSON action as well as outputs from a previous transaction prepare step:

❗️

Key Id:

The provided Key Id needs to be equal to the address of an account that is present in the provided Transaction Signing Responder (Authorise).

πŸ“˜

Transaction Signing Responder (TSR) Name:

If you are using your own TSR (i.e. Authorise), then you will need to change CTA (testnet TSR hosted by Quant) to your own TSR identifier

Response body example:

Execute Transaction

The third and final stage of the process is to execute the particular transaction that you have prepared and signed. Make has different actions for each type of transaction, as explained in the following subsections:

Execute a Signed Token Transfer Transaction

This Make action is required to execute transactions prepared via the actions: Prepare a Transfer of Fungible Tokens or Prepare a Transfer of a Non-Fungible Token.

Example request and response:

Input Fields example:

Response body example:

The transaction created can be found here.

Execute a Signed Smart Contract Invoke Transaction

This Make action is required to execute transactions prepared via the action: Prepare a Smart Contract Transaction.

Example request and response:

Input Fields example:

Response body example:

The transaction created can be found here.

Execute a Signed Smart Contract Deployment Transaction

This Make action is required to execute transactions prepared via the action: Prepare a Smart Contract Deployment Transaction.

This Make action works regardless of if the user provided both the compiled smart contract code and the compiled smart contract constructor parameters as one bytecode, or if the user provided the constructor parameters in a separate standardised manner.

Example request and response:

Input Fields example:

Response body example:

The transaction created can be found here, and the resulting smart contract can be found here.

Execute a Signed Native Asset Transfer

This Make action is required to execute transactions prepared via action: Prepare a Native Asset Transfer.

Example request and response:

Input Fields example:

Response body example:

🚧

Under construction

TBC