Developer SDK

C examples

Install the SDK · View source on GitHub ↗

provider/provider.h

c
/* Declarations shared by the files of the C provider example
 * (PROVIDER_CONTRACT.md): main.c runs the commands, session.c runs the
 * provider device, status.c and state.c hold the status rules and the
 * installation state, json.c reads the json values that the sdk returns, and
 * selftest.c checks the rules. Only main.c and session.c call the sdk, so
 * `make self-test` builds the other files into a self-test that never loads
 * the sdk library; urnetwork_sdk.h is included here for its constants. */
#ifndef UR_PROVIDER_H
#define UR_PROVIDER_H

/* POSIX 2008 with its XSI part (mkstemp, SA_ONSTACK), and on macOS the full
 * system headers (O_NOFOLLOW, mkdtemp). Every file includes this header
 * first, before any system header. */
#ifndef _WIN32
#define _XOPEN_SOURCE 700
#define _DARWIN_C_SOURCE
#endif

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <stdlib.h>
#include <string.h>

#ifdef _WIN32
#ifndef WIN32_LEAN_AND_MEAN
#define WIN32_LEAN_AND_MEAN
#endif
#include <windows.h>
#else
#include <pthread.h>
#endif

#include <urnetwork_sdk.h>

/* ----- commands and exit codes (main.c) ----- */

/* Exit codes, for supervisors (background/README.md). */
enum {
  /* a requested stop: Ctrl-C, SIGTERM */
  UR_PROVIDER_EXIT_STOPPED = 0,
  /* any other failure; supervisors restart after a delay */
  UR_PROVIDER_EXIT_FAILURE = 1,
  /* a configuration or credential problem that a restart does not fix
   * (sysexits EX_CONFIG) */
  UR_PROVIDER_EXIT_CONFIG = 78,
  /* an unknown command line is a configuration problem */
  UR_PROVIDER_EXIT_USAGE = UR_PROVIDER_EXIT_CONFIG,
};

#define UR_PROVIDER_USAGE "usage: provider [run] | --self-test | --version"

/* The forms of the command line. */
typedef enum {
  UR_PROVIDER_COMMAND_RUN,
  UR_PROVIDER_COMMAND_SELF_TEST,
  UR_PROVIDER_COMMAND_VERSION,
  /* anything else: print the usage and exit with UR_PROVIDER_EXIT_USAGE */
  UR_PROVIDER_COMMAND_USAGE,
} ur_provider_command;

/* The command that the arguments name: no argument or `run` runs the
 * provider. */
static inline ur_provider_command ur_provider_parse_command(int argc,
                                                            char **argv) {
  if (argc <= 1 || (argc == 2 && !strcmp(argv[1], "run")))
    return UR_PROVIDER_COMMAND_RUN;
  if (argc == 2 && !strcmp(argv[1], "--self-test"))
    return UR_PROVIDER_COMMAND_SELF_TEST;
  if (argc == 2 && !strcmp(argv[1], "--version"))
    return UR_PROVIDER_COMMAND_VERSION;
  return UR_PROVIDER_COMMAND_USAGE;
}

/* ----- small shared helpers ----- */

/* A mutex that guards state shared with sdk callbacks. */
#ifdef _WIN32
typedef SRWLOCK ur_mutex;
#define UR_MUTEX_INITIALIZER SRWLOCK_INIT
/* Prepares a mutex that has no static initializer. */
static inline void ur_mutex_init(ur_mutex *mutex) { InitializeSRWLock(mutex); }
/* Takes the mutex. */
static inline void ur_mutex_lock(ur_mutex *mutex) {
  AcquireSRWLockExclusive(mutex);
}
/* Releases the mutex. */
static inline void ur_mutex_unlock(ur_mutex *mutex) {
  ReleaseSRWLockExclusive(mutex);
}
/* Ends the mutex; a slim reader/writer lock needs no cleanup. */
static inline void ur_mutex_destroy(ur_mutex *mutex) { (void)mutex; }
#else
typedef pthread_mutex_t ur_mutex;
#define UR_MUTEX_INITIALIZER PTHREAD_MUTEX_INITIALIZER
/* Prepares a mutex that has no static initializer. */
static inline void ur_mutex_init(ur_mutex *mutex) {
  pthread_mutex_init(mutex, NULL);
}
/* Takes the mutex. */
static inline void ur_mutex_lock(ur_mutex *mutex) {
  pthread_mutex_lock(mutex);
}
/* Releases the mutex. */
static inline void ur_mutex_unlock(ur_mutex *mutex) {
  pthread_mutex_unlock(mutex);
}
/* Ends the mutex. */
static inline void ur_mutex_destroy(ur_mutex *mutex) {
  pthread_mutex_destroy(mutex);
}
#endif

/* Owned bytes; data is NULL when length is 0. */
typedef struct {
  uint8_t *data;
  size_t length;
} ur_bytes;

/* Frees the bytes and empties them. */
static inline void ur_bytes_free(ur_bytes *bytes) {
  free(bytes->data);
  bytes->data = NULL;
  bytes->length = 0;
}

/* An owned copy of a string, NULL for NULL or when out of memory. */
static inline char *ur_provider_copy_string(const char *text) {
  if (!text)
    return NULL;
  size_t size = strlen(text) + 1;
  char *copy = malloc(size);
  if (copy)
    memcpy(copy, text, size);
  return copy;
}

/* Room for an error message, a path and a status line. */
#define UR_PROVIDER_ERROR_CAPACITY 512
#define UR_PROVIDER_PATH_CAPACITY 4096
#define UR_PROVIDER_LINE_CAPACITY 512
/* a canonical uuid and its terminator */
#define UR_PROVIDER_ID_CAPACITY 37

/* ----- json values (json.c) ----- */

/* The kind of a json value; none is a missing member or a malformed
 * document. */
typedef enum {
  UR_JSON_NONE = 0,
  UR_JSON_NULL,
  UR_JSON_FALSE,
  UR_JSON_TRUE,
  UR_JSON_NUMBER,
  UR_JSON_STRING,
  UR_JSON_ARRAY,
  UR_JSON_OBJECT,
} ur_json_type;

/* One json value: a span of the document it was read from. */
typedef struct {
  ur_json_type type;
  const char *text;
  size_t length;
} ur_json_value;

ur_json_value ur_json_parse(const char *text, size_t length);
ur_json_value ur_json_member(ur_json_value object, const char *key);
bool ur_json_int64(ur_json_value value, int64_t *number);
char *ur_json_string(ur_json_value value);

/* ----- status (status.c) ----- */

extern const char ur_provider_consent_disclaimer[];

#define UR_PROVIDER_STATE_STOPPED "stopped"
/* the platform disconnected this client for its network's client limit, and
 * the sdk holds off reconnecting until the retry time */
#define UR_PROVIDER_STATE_CLIENT_LIMIT "client limit"
#define UR_PROVIDER_STATE_STARTING "starting"
#define UR_PROVIDER_STATE_PAUSED "paused"
#define UR_PROVIDER_STATE_PROVIDING "providing"

/* the payout wallet before the first wallet read finishes */
#define UR_PROVIDER_PAYOUT_WALLET_CHECKING "checking"
/* the payout wallet when the first wallet read failed */
#define UR_PROVIDER_PAYOUT_WALLET_UNAVAILABLE "unavailable"
/* the payout wallet when no wallet is mapped */
#define UR_PROVIDER_PAYOUT_WALLET_NOT_SET "not set"

#define UR_PROVIDER_PAYOUT_WALLET_SCOPE_HOTKEY "hotkey"
#define UR_PROVIDER_PAYOUT_WALLET_SCOPE_PROVIDER "this provider"
#define UR_PROVIDER_PAYOUT_WALLET_SCOPE_NETWORK "network"
#define UR_PROVIDER_PAYOUT_WALLET_SCOPE_ANOTHER_PROVIDER "another provider"

/* The consent_scope of a network's hotkey delegation entry in GET /sn/wallet.
 * Hotkey delegations come with a later server and sdk change, which adds the
 * sdk's own constant; the app only labels the entry. */
#define UR_PROVIDER_SN_WALLET_CONSENT_SCOPE_HOTKEY "hotkey"

/* Distinct clients are counted up to this many; beyond it the count is a
 * lower bound, shown with a trailing "+". */
#define UR_PROVIDER_CLIENTS_SERVED_LIMIT (100 * 1000)

/* One status snapshot. The strings are borrowed: constants, or the session's
 * wallet address. */
typedef struct {
  const char *state;
  /* the end of the client limit hold in unix milliseconds, shown with the
   * client limit state; 0 when unknown */
  int64_t client_limit_retry_time;
  size_t clients_served;
  bool clients_served_at_limit;
  int64_t data_provided_byte_count;
  /* a coldkey ss58 address, or one of the payout wallet texts */
  const char *payout_wallet;
  /* NULL unless payout_wallet is an address */
  const char *payout_wallet_scope;
} ur_provider_status;

/* The client limit status json of the sdk, read. */
typedef struct {
  /* URNET_CLIENT_LIMIT_STATUS_NONE or URNET_CLIENT_LIMIT_STATUS_EXCEEDED */
  char status[32];
  /* the end of the hold in unix milliseconds, 0 without a hold */
  int64_t retry_time;
} ur_provider_client_limit_status;

/* The distinct clients that held a contract with this provider since the app
 * started. Safe for concurrent use: the sdk delivers contract details on its
 * own threads. */
typedef struct {
  size_t limit;
  ur_mutex state_lock;
  /* an open addressing set of owned peer keys */
  char **peer_keys;
  size_t capacity;
  size_t count;
  bool at_limit;
} ur_provider_clients_served;

void ur_provider_print_line(const char *line);
void ur_provider_format_byte_count(int64_t byte_count, char *text,
                                   size_t capacity);
void ur_provider_status_text(const char *state,
                             int64_t client_limit_retry_time, char *text,
                             size_t capacity);
void ur_provider_status_line(const ur_provider_status *status, char *line,
                             size_t capacity);
void ur_provider_status_key(const ur_provider_status *status, char *key,
                            size_t capacity);
const char *ur_provider_state(int64_t provide_mode,
                              const char *client_limit_status,
                              bool provide_paused, bool provide_enabled,
                              bool provider_connected);
const char *ur_provider_payout_wallet_scope(const char *wallet_consent_scope,
                                            const char *wallet_client_id,
                                            const char *client_id);
int64_t ur_provider_data_provided_byte_count(const char *packet_stats_json);
void ur_provider_read_client_limit_status(
    const char *client_limit_status_json,
    ur_provider_client_limit_status *client_limit_status);
bool ur_provider_contract_peer_key(const char *contract_details_json,
                                   bool receive, char *peer_key,
                                   size_t capacity);
char *ur_provider_payout_wallet(const char *sn_wallet_json,
                                const char *client_id, const char **scope);
bool ur_provider_wallet_read_succeeded(const char *result_json,
                                       const char *error);
void ur_provider_clients_served_init(ur_provider_clients_served *served,
                                     size_t limit);
void ur_provider_clients_served_add(ur_provider_clients_served *served,
                                    const char *contract_details_json,
                                    bool receive);
void ur_provider_clients_served_count(ur_provider_clients_served *served,
                                      size_t *count, bool *at_limit);
void ur_provider_clients_served_free(ur_provider_clients_served *served);

/* ----- installation state (state.c) ----- */

#define UR_PROVIDER_CLIENT_JWT_FILE_NAME "client.jwt"
#define UR_PROVIDER_INSTANCE_ID_FILE_NAME "instance-id"
#define UR_PROVIDER_IDENTITY_FILE_NAME "identity.json"
/* the largest state file the app reads */
#define UR_PROVIDER_STATE_FILE_BYTE_LIMIT (64 * 1024)
#define UR_PROVIDER_IDENTITY_VERSION 1

/* identity.json. An identity belongs to one client: a newly provisioned client
 * gets a new identity. */
typedef struct {
  int version;
  char client_id[UR_PROVIDER_ID_CAPACITY];
  ur_bytes client_key_seed;
  ur_bytes provide_tls_certificate_pem;
  ur_bytes provide_tls_private_key_pem;
  ur_bytes extender_key_seed;
} ur_provider_identity;

/* The installation state loaded at start. */
typedef struct {
  char state_dir[UR_PROVIDER_PATH_CAPACITY];
  /* owned */
  char *client_jwt;
  /* the client_id claim of client_jwt */
  char client_id[UR_PROVIDER_ID_CAPACITY];
  char instance_id[UR_PROVIDER_ID_CAPACITY];
  /* false on first run, and when the stored identity belongs to another
   * client: the device then makes a new identity, which the app saves */
  bool has_identity;
  ur_provider_identity identity;
} ur_provider_config;

/* The outcome of reading a state file. */
typedef enum {
  UR_PROVIDER_READ_OK,
  UR_PROVIDER_READ_MISSING,
  UR_PROVIDER_READ_FAILED,
} ur_provider_read_result;

char *ur_provider_environment_state_dir(void);
bool ur_provider_path_join(char *path, size_t capacity, const char *dir,
                           const char *name);
bool ur_provider_check_state_dir(const char *state_dir, char *error,
                                 size_t capacity);
ur_provider_read_result ur_provider_read_private_file(const char *path,
                                                      ur_bytes *data,
                                                      char *error,
                                                      size_t capacity);
bool ur_provider_write_private_file(const char *path, const void *data,
                                    size_t length, char *error,
                                    size_t capacity);
bool ur_provider_make_private_dir(const char *path, char *error,
                                  size_t capacity);
bool ur_provider_make_temp_dir(char *path, size_t capacity);
bool ur_provider_remove_path(const char *path, bool dir);
bool ur_provider_random_bytes(uint8_t *data, size_t length);
char *ur_provider_base64_encode(const uint8_t *data, size_t length);
bool ur_provider_base64_decode(const char *text, size_t length, bool url,
                               ur_bytes *data);
bool ur_provider_parse_uuid(const char *text, size_t length,
                            char uuid[UR_PROVIDER_ID_CAPACITY]);
bool ur_provider_new_uuid(char uuid[UR_PROVIDER_ID_CAPACITY]);
bool ur_provider_parse_client_jwt_client_id(
    const char *client_jwt, char client_id[UR_PROVIDER_ID_CAPACITY],
    char *error, size_t capacity);
bool ur_provider_load_or_create_instance_id(
    const char *state_dir, char instance_id[UR_PROVIDER_ID_CAPACITY],
    char *error, size_t capacity);
bool ur_provider_load_identity(const char *state_dir, const char *client_id,
                               ur_provider_identity *identity, bool *found,
                               char *error, size_t capacity);
bool ur_provider_save_identity(const char *state_dir,
                               const ur_provider_identity *identity,
                               char *error, size_t capacity);
void ur_provider_identity_free(ur_provider_identity *identity);
bool ur_provider_load_config(const char *state_dir, ur_provider_config *config,
                             char *error, size_t capacity);
void ur_provider_config_free(ur_provider_config *config);

/* ----- the running provider (session.c) ----- */

/* One run of the provider: the network space manager, the provider device and
 * its subscriptions. The wallet fields belong to the thread that runs it. */
typedef struct {
  const ur_provider_config *config;
  uint64_t manager;
  uint64_t space;
  uint64_t api;
  uint64_t device;
  uint64_t subs[4];
  /* the mapped coldkey, owned; NULL while payout_wallet_text is shown */
  char *payout_wallet_address;
  /* checking, unavailable or not set */
  const char *payout_wallet_text;
  /* the scope label of payout_wallet_address */
  const char *payout_wallet_scope;
} ur_provider_session;

void ur_provider_request_stop(void);
bool ur_provider_session_open(ur_provider_session *session,
                              const ur_provider_config *config, char *error,
                              size_t capacity);
int ur_provider_session_run(ur_provider_session *session);
void ur_provider_session_close(ur_provider_session *session);

/* ----- self-test (selftest.c) ----- */

bool ur_provider_self_test(char *failure, size_t capacity);
int ur_provider_self_test_main(void);

#endif