New vertex

Initializing a new vertex.

Each device needs to initialize the Vertices SDK before being able to use it by calling the function vertices_new() and passing the vertex configuration. Let's see what are the configuration parameters needed.

The provider

The provider is the remote API that will be interrogated to interact with the blockchain. In the case of the Algorand API, an HTTP REST API is being used. It comprises 4 pieces of information:

• url: the base URL, in the case of Algorand we can think about Algoexplorer, Purestake, or even your local node (localhost). Make sure to provide the API on the network you want. The Testnet will always be used in the examples.

• port: the server port for the HTTP connection.

• header: some API providers require a specific header to pass an authorization token, for example, that's the case of Purestake. The header field will let the user pass those specific headers. Other headers might be appended as well in the HTTP calls.

• cert_pem: some HTTP clients need the provider certificates. That's not the case on Unix when using libcurl but the ESP32 example needs the certificate to be linked into the program.

To get the Algoexplorer certificates from the command line:

openssl s_client -showcerts -verify 5 -connect api.testnet.algoexplorer.io:443

Now that we have gathered the provider information, we can create the structure encapsulating it:

static provider_info_t algoexplorer_provider =
    {.url = (char *) "https://api.testnet.algoexplorer.io", 
    .port = 0, 
    .header = (char *) ""};

static provider_info_t purestake_provider =
    {.url = (char *) "https://testnet-algorand.api.purestake.io/ps2", 
    .port = 0, 
    .header = (char *) "x-api-key:xxx"}; // replace the xxx with your token

The event handler

The user needs to implement a callback function that must be passed when initializing the library:

static ret_code_t
vertices_evt_handler(vtc_evt_t *evt)
{ 
    /* to be implemented in the next chapter */ 
}

The next chapter will be dedicated to understanding and responding to the different events emitted by the library.

Initialization

We can now create the vertex configuration structure and try to init the library. Below is the content of the minimum main.c file:

#include <stdio.h>
#include "vertices.h"

static provider_info_t algoexplorer_provider =
    {.url = (char *) "https://api.testnet.algoexplorer.io", 
    .port = 0, 
    .header = (char *) ""};

static ret_code_t
vertices_evt_handler(vtc_evt_t *evt)
{
    /* to be implemented in the next chapters */
    
    return VTC_ERROR_INTERNAL;
}

int main(int argc, char *argv[])
{
    printf("Hello world\n");

    // vertex configuration
    vertex_t vertex = {
        .provider = &algoexplorer_provider,
        .vertices_evt_handler = vertices_evt_handler
    };

    // create new vertex
    ret_code_t err_code = vertices_new(&vertex);
    VTC_ASSERT(err_code);

    return 0;
}

Compile and Run

Let's compile and run the example to see what's happening:

$ cd build && cmake .. && make myproject
[  0%] Built target cjson
[ 80%] Built target mbedcrypto
[100%] Built target vertices
[100%] Linking C executable myproject
[100%] Built target myproject

$ ./myproject/myproject
Hello world
🔴 [/Users/cyril/Documents/work/vertices/porting_guide/external/c-vertices-sdk/src/http_weak.c:24] Weak implementation of http_init
🔴 [/Users/cyril/Documents/work/vertices/porting_guide/external/c-vertices-sdk/src/vertices_errors.c:23] Fatal error: 0x3 /Users/cyril/Documents/work/vertices/porting_guide/myproject/main.c:29

Weak implementation of http_init is printed along with a fatal error from main.c:29, meaning the Vertices library initialization failed with code error: 0x3.

Weak implementation

The Vertices SDK provides a weak implementation of the HTTP functions: init, get, post & close. Implementing those functions cannot be done right from the SDK as we don't know the target you are trying to use and the underlying HTTP stack.

Fortunately, the next chapter will be dedicated to implementing those functions on your target.

Here is the link to our implementation of the above step 🤩