Check the arduino
directory on Github for header files and samples.
The Kenshi IoT SDK for Arduino/ESP32 implements the Kenshi Deep Index MQL API. Since
the API endpoint for the Kenshi Deep Index MQL API is available only over HTTPS, you
need to have a secure network Client.
On ESP32 the HTTPS connection is handled by the SDK automatically; all you need is to
be connected to a Wi-Fi access point. On certain Arduino boards, however, you need to
manage the HTTPS connection yourself. For example, on Arduino MKR 1010, you should use
an instance of "WiFiSSLClient", but you won't need to register the Kenshi/AWS root
certificate as it is already shipped with the Arduino MKR 1010. Refer to the developer
documentation of your board to learn how you can install a root certificate. Check
"The Kenshi root certificate" section on this page
to learn how to get the certificate.
Once you are connected to the internet and have the Kenshi SSL certificate set up, you
can create instances of MQL or SyncTask and start making requests. To make a query, you
must use the MongoDB Query Language. You will receive MongoDocuments in response. Refer
to the Kenshi MQL documentation to learn more about
the query language or the response schema.
Kenshi IoT SDK for Arduino/ESP32 uses the ArduinoJson
package for building queries and parsing MQL responses. To learn more, refer to the
ArduinoJson documentation.
Full examples are provided for Arduino MKR 1010 and ESP32 on Kenshi IoT SDK
repository on
Github.
This section lists all enum, class, and other objects exported by "Kenshi.h".
This enum contains all the blockchains supported by this SDK.
Use values from this enum to initialize your MQL objects.
/**
* @brief Blockchain enum.
* Contains all Kenshi MQL supported
* blockchains. Use this to initialize
* your MQL objects.
*/
enum Blockchain {
FantomTestnet,
FantomMainnet,
BinanceTestnet,
BinanceMainnet,
EthereumGoerli,
EthereumMainnet,
ArbitrumGoerli,
ArbitrumMainnet,
AvalancheTestnet,
AvalancheMainnet,
PolygonMumbai,
PolygonMainnet,
AuroraTestnet,
AuroraMainnet,
BitgertTestnet,
BitgertMainnet
};This class allows communicating with the Kenshi Deep Index MQL endpoint.
To initialize an instance of this class, you need an API key, the address
of the API key owner, and a blockchain from the Blockchain enum.
On Arduino, you need to pass a network Client instance to the "runQuery"
method of the MQL class. This instance can be any network Client instance
such as WiFiClient, EthernetClient or GSMClient.
class MQL {
private:
char *_apiKey;
char *_owner;
Blockchain _blockchain;
public:
/**
* @brief Construct a new MQL object
*
* @param apiKey: Your MQL API key
* @param owner: Your MQL API key owner
* @param blockchain: Blockchain to query
* (Use the Blockchain enum)
*/
MQL(char *apiKey, char *owner, Blockchain blockchain);
/**
* @brief Returns an instance of MongoQuery
* for you to fill. Use this to create your
* query.
* @note Assigns 1024 bytes to the query object
* @return MongoQuery
*/
MongoQuery initQuery();
/**
* @brief Returns an instance of MongoQuery
* for you to fill. Use this to create your
* query.
* @param size: Assign `size` bytes to the
* query object
* @return MongoQuery
*/
MongoQuery initQuery(int size);
/**
* @brief Get the payload string for a query
*
* @param query: A MongoQuery instance, returned
* from an `initQuery` call.
* @return String: JSON representation of `query`
*/
String getPayload(MongoQuery query);
/**
* @brief Runs `query` against the Kenshi data
* clusters and return the results
* @note Use this on Arduino
* @param client: An instance of Arduino
* Client (e.g. WiFiClient, EthernetClient
* and GSMClient.)
* @param query: A MongoQuery instance, returned
* from an `initQuery` call.
* @return MongoDocuments: An instance of JsonArray.
* Read Kenshi MQL docs for the schema.
*/
MongoDocuments runQuery(Client &client, MongoQuery query);
/**
* @brief Runs `query` against the Kenshi data
* clusters and return the results
* @note Use this on ESP32
* @param query: A MongoQuery instance, returned
* from an `initQuery` call.
* @return MongoDocuments: An instance of JsonArray.
* Read Kenshi MQL docs for the schema.
*/
MongoDocuments runQuery(MongoQuery query);
};The SyncTask class can be used to check on the sync state of
a certain task. This is useful when you only want to process
the events emitted after your device starts up.
class SyncTask {
private:
char *_taskId;
public:
/**
* @brief Construct a new Sync Task object
*
* @param taskId: Your Kenshi Sync task ID
*/
SyncTask(char *taskId);
/**
* @brief Get the last synced block number
* @note Use this on ESP32 boards
* @return uint: Last synced block number
*/
uint getLastSyncedBlock();
/**
* @brief Get the last synced block number
* @note Use this on Arduino boards
* @param client: An instance of Arduino
* Client (e.g. WiFiClient, EthernetClient
* and GSMClient.)
* @return uint: Last synced block number
*/
uint getLastSyncedBlock(Client &client);
};This is the root certificate for the "api.kenshi.io" domain. You need to pass this
to your secure Client instance on specific boards.
char *kenshiRootCert;Check the zephyr
directory on Github for header files and samples.
The Kenshi IoT SDK for Zephyr comes with a lower level API compared to the Arduino
library and is meant for advanced users. This library supports any HTTPS-capable
development board supported by Zephyr.
For normal usage, the SDK defines four C preprocessor macros. The "MQL_INIT" macro
is used to define initialize MQL structs and functions required for building, parsing,
and serializing MQL queries and MQL responses. The "MQL_CALLBACK" is used to define
a callback to be called when the MQL responses are ready. The "MQL_QUERY" macro is
used to create an MQL query, and the "MQL_GET_EVENTS" is used afterwards to send the
created query.
For more advanced usage, you can check the "kenshi.h" header file.
This section lists all enum, class, and other objects exported by "kenshi.h".
This macro is used to initialize the structs and functions needed to build, parse,
and serialize MQL queries.
/**
* @brief Initialize an MQL query
*
* @param mql_name: Name this specific MQL query.
* All generated functions and structs will be prefixed
* with this.
* @param event_count: Buffer size for receiving events.
* Defines the maximum number of events that can be received
* in one MQL transaction.
* @param args...: Name of the blockchain event arguments.
* For example, you can pass `from, to, amount` for `Transfer`
* event.
*
* @example:
*
* MQL_INIT(my_mql, 16, from, to, amount);
*/
#define MQL_INIT(mql_name, event_count, args...)This macro is used to create a callback to be called when the MQL
results are ready.
/**
* @brief Create a callback for MQL results
*
* @param mql_name: Name of the initialized MQL query.
* @param entries: Name of the entries parameter.
*
* @example:
*
* MQL_CALLBACK(my_mql, my_entries) {
* printk("block.hash: %sn", my_entries[0].block.hash);
* }
*/
#define MQL_CALLBACK(mql_name, entries)This macro is used to create an MQL query.
/**
* @brief Create an MQL query
*
* @param mql_name: Name of the initialized MQL query.
* @param buf_name: Buffer name to store the serialized query.
* @param values...: MQL query. Not all MQL query options are
* available for Zephyr. Check "Kenshi.h" to learn what's possible.
*
* @example:
*
* MQL_QUERY(my_mql, my_query_string,
* {.blockchain = "binance-mainnet",
* .apikey = MQL_API_KEY,
* .owner = MQL_API_KEY_OWNER,
* .query = {
* .block_address = MQL_CONTRACT_ADDRESS,
* .block_number = {.gte = 17633890, .lte = 17633892},
* }});
*/
#define MQL_QUERY(mql_name, buf_name, values...)This macro is used to send an MQL query and wait for a response.
/**
* @brief Send an MQL query
*
* @param mql_name: Name of the initialized MQL query.
* @param query: Buffer name that stores the serialized query.
* @param buffer_size: Size of the buffer to receive HTTP
* packets. Currently the entire MQL response needs to fit in
* this buffer, this behavior might change in the future.
*
* @example:
*
* MQL_GET_EVENTS(my_mql, my_query_string, 2048);
*/
#define MQL_GET_EVENTS(mql_name, query, buffer_size)On this page
- IoT SDK library reference
- Arduino/ESP32 library
- Arduino/ESP32 library usage guide
- Arduino/ESP32 library reference
- The Blockchain enum
- The MQL class
- The SyncTask class
- The Kenshi root certificate
- Zephyr RTOS
- Zephyr library usage guide
- Zephyr library reference
- The MQL_INIT macro
- The MQL_CALLBACK macro
- The MQL_QUERY macro
- The MQL_GET_EVENTS macro
