Skip to main content
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 instnce 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,
  AvalancheTestnet,
  AvalancheMainnet,
  PolygonMumbai,
  PolygonMainnet,
  AuroraTestnet,
  AuroraMainnet
};
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 respons 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)