How to use Overledger on Pipedream
Introduction
The Overledger App on Pipedream has available triggers and actions.
All of the triggers and actions fall into three main categories:
1. Reading Data
Overledger allows data to be read from the blockchain. Currently, the Pipedream 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 Pipedream Overledger app, users can create, read, update and 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 Pipedream Overledger app allows users to prepare and execute the following types of transactions
- Smart Contract Function Invocations
Available Overledger Instance, Technology and Network Combinations
Each Pipedrem 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 Pipedream are listed in the following table:
Overledger environment | Technology | Network |
---|---|---|
Sandbox | ethereum | sepolia testnet |
Sandbox | ethereum | goerli testnet |
Sandbox | ethereum | polygon mumbai testnet |
Sandbox | ethereum | avalanche fuji testnet |
Sandbox | ethereum | xdc apothem testnet |
Production | ethereum | ethereum mainnet |
Production | ethereum | polygon mainnet |
Production | ethereum | avalanche c-chain mainnet |
Production | ethereum | xdc 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).
Pipedream currently only supports the Ethereum blockchain technology. If necessary, additional technologies can be added to the Pipedream 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 Pipedream action in the Overledger app, called Read from a Smart Contract.
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 ( Smart Contract Id)
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 etherscan 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 Pipedream 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 Pipedream.
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:
Output Parameters with just the type:
(a) number - requiring no inputs and one uint256 type output.
Response body example:
Pipedrean does not support the input parameters as an array of objects ( Object[]) - this means the inputs Objects have to be converted to a JSON string which is then parsed within the Overledger integration to get the required objects for the Overledger request. You may need to use a JSON formatter to stringify your objects
(b) readOneAInputOneAOutput - requiring one address type input and one address type output.
Input Fields example:
Output Parameters example:
(b) readOneAInputOneAOutput - requiring one address
type input and one address
type output.
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:
Output Parameters:
(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:
e) readTwoUIInputsTwoUIOutputs - requiring two uint type inputs and two uint type outputs.
Input Fields example:
Output Parameters construct:
(e) readTwoUIInputsTwoUIOutputs - requiring two uint type inputs and two uint type outputs.
Response body example:
2. Monitoring Data on a Blockchain
Registering to monitor a smart contract or blockchain account can be completed in one Pipedream source. This is done by clicking the add Trigger button and then searching for the Overledger app. You will then have a choice from two sources New Account Event (instant) or New Smart Contract Event (instant):
- New Account Event (instant) - Monitoring transactions sent to or from a particular address.
- New Smart Contract Event - Monitoring events fired (emitted) from a smart contract.
In Pipedream these trigger webhooks are called sources and they have slightly different properties and capabilities to actions like read from a smart contract.
Select the Overledger Instance, Technology and Network
The possible options are listed above.
Select the Account Address (Id) or Smart Contract Id
In the following examples, for the smart contract monitoring testing we will be using the 'Basic Parameter Type Event Testing Contract' deployed on the ethereum sepolia test network at this address 0x0B13CE1dC7E2f04494E0d0A6B48D63641397e8Eb.
Therefore the smart contract identifier of this smart contract is 0x0B13CE1dC7E2f04494E0d0A6B48D63641397e8Eb.
Whereas for the account testing, we will be using the non-smart contract account at this address 0xd7E24ae42EB4adE276dB9291e8098E7dB94e1cc3.
Therefore the identifier of this account is 0xd7E24ae42EB4adE276dB9291e8098E7dB94e1cc3.
Example Request and Responses
This Pipedream 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 Pipedream examples we present the following screenshots:
(i) Create a smart contract trigger.
Input Fields:
(i) Create a smart contract webhook. Response body/call back data:
The response body for a trigger or action is stored in a steps object within pipedream and the different parts of this object can be accessed and used in following steps of the workflow:
(ii) Create an account trigger. Input Fields:
Input Fields:
(i) Create an account webhook. Response body/callback data:
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 or from the monitored address or a transaction will have to trigger a smart contract event.
Manage your trigger/sources
Now that your webhook is up and running, through Pipedream actions in your workflow you can manipulate the data as wanted using the steps object which contains all the returned information from previous steps. Use in custom code, create new webhooks and send the data desired endpoints and so on and so forth. Within the user dashboard you can access these triggers in the sources section where you can pause, modify, delete or configure as required:
3. Writing Data to a Blockchain
Writing data to a blockchain can be completed in three Pipedream actions in the Overledger app. These actions need to follow the prepare-sign-execute Overledger flow, which is described here. These are options for each stage of the flow.
- Prepare a transaction: choose the Pipedream action: Prepare a Smart Contract Transaction
- Sign transaction: choose the Pipedream action: Sign a Transaction
- Execute transaction: choose the Pipedream action: Execute Signed Transaction
Once you have selected the actions and the Overledger platform account you will be using, then you should fill in the action input fields
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 Pipedream action.
Example request and response:
This example prepares a transaction that calls the function 'writeOneSInput' from this contract on the Ethereum Sepolia Testnet from the sender account 0xd7E24ae42EB4adE276dB9291e8098E7dB94e1cc3. This function requires one string parameter, which is instantiated as "should increase the number by 4".
Input Fields example:
Response body example 1:
Response body example 2:
Sign Transaction
The second stage of the process is to sign the transaction that was just prepared. Pipedream has one action to sign all types of prepared transactions: Sign a Transaction. Bare in mind the format the data/response coming in from the previous Prepare transaction action as this data may need to be manipulated accordingly. e.g:
RequestId from prepare-transaction 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.
Execute a Signed Smart Contract Invoke Transaction
This Pipedream action is required to execute transactions prepared via the action: Prepare a Smart Contract Transaction.
Example request and response:
Input Fields example:
Taking the signed Transaction from the previous sign a transaction step:
Response body example:
The transaction created can be found in transactions on etherscan for that address.
Updated about 2 months ago