Documentation

C SDK

Native C implementation with minimal dependencies, optimized for embedded systems and performance-critical applications.

Installation

cd pkg/c
make

Quick Start

#include <lux_consensus.h>
#include <stdio.h>

int main() {
    // Initialize library
    lux_init();

    // Create engine config
    lux_config_t config = {
        .engine_type = LUX_ENGINE_CHAIN,
        .k = 20,
        .alpha = 15,
        .beta = 20,
        .max_outstanding = 1000
    };

    // Create consensus engine
    lux_engine_t* engine = lux_create_engine(&config);
    if (!engine) {
        fprintf(stderr, "Failed to create engine\n");
        return 1;
    }

    // Add a block
    lux_block_t block = {
        .id = 1,
        .parent_id = 0, // Genesis
        .height = 1,
        .data = NULL,
        .data_len = 0
    };

    if (lux_add_block(engine, &block) != LUX_SUCCESS) {
        fprintf(stderr, "Failed to add block\n");
        return 1;
    }

    // Process vote
    lux_vote_t vote = {
        .block_id = 1,
        .vote_type = LUX_VOTE_PREFERENCE
    };

    lux_record_vote(engine, &vote);

    // Check acceptance
    if (lux_is_accepted(engine, 1)) {
        printf("Block accepted!\n");
    }

    // Cleanup
    lux_destroy_engine(engine);
    lux_cleanup();

    return 0;
}

Compilation

# Compile with optimizations
gcc -O3 -o my_app my_app.c -llux_consensus -I/usr/local/include

# With debugging
gcc -g -O0 -o my_app my_app.c -llux_consensus -I/usr/local/include

API Reference

Initialization

void lux_init(void);
void lux_cleanup(void);
const char* lux_error_string(lux_error_t err);

Engine Management

lux_engine_t* lux_create_engine(const lux_config_t* config);
void lux_destroy_engine(lux_engine_t* engine);
const char* lux_engine_type_string(lux_engine_type_t type);

Block Operations

lux_error_t lux_add_block(lux_engine_t* engine, const lux_block_t* block);
lux_error_t lux_get_block(lux_engine_t* engine, uint16_t id, lux_block_t* block);
bool lux_is_accepted(lux_engine_t* engine, uint16_t block_id);
uint16_t lux_preference(lux_engine_t* engine);

Voting

lux_error_t lux_record_vote(lux_engine_t* engine, const lux_vote_t* vote);
int lux_get_vote_count(lux_engine_t* engine, uint16_t block_id);

Engine Types

typedef enum {
    LUX_ENGINE_CHAIN,  // Linear chain consensus
    LUX_ENGINE_DAG,    // Directed acyclic graph
    LUX_ENGINE_PQ      // Post-quantum consensus
} lux_engine_type_t;

Error Handling

typedef enum {
    LUX_SUCCESS = 0,
    LUX_ERROR_INVALID_PARAMS,
    LUX_ERROR_OUT_OF_MEMORY,
    LUX_ERROR_ENGINE_ERROR,
    LUX_ERROR_BLOCK_NOT_FOUND
} lux_error_t;

Performance

Test results on Apple M1 Max:

Total Tests: 33
Passed: 33 (100%)
Failed: 0

Performance: 1000 blocks in < 0.001 seconds
Throughput: > 1M blocks/sec
Memory: < 10 MB total footprint

Thread Safety

The C SDK uses read-write locks for thread safety:

// Safe for concurrent reads
bool is_accepted = lux_is_accepted(engine, block_id);
uint16_t pref = lux_preference(engine);

// Writes are synchronized
lux_add_block(engine, &block);
lux_record_vote(engine, &vote);

Memory Management

Zero-copy: Where possible
Hash tables: O(1) lookups
Custom allocators: Optional (use LUX_CUSTOM_ALLOCATOR)
No garbage collection: Manual memory management

Examples

Multi-Engine Setup

// Create multiple engines
lux_engine_t* chain = lux_create_engine(&chain_config);
lux_engine_t* dag = lux_create_engine(&dag_config);
lux_engine_t* pq = lux_create_engine(&pq_config);

// Use them independently
lux_add_block(chain, &block1);
lux_add_block(dag, &block2);
lux_add_block(pq, &block3);

Custom Data

// Attach custom data to blocks
uint8_t custom_data[] = {0x01, 0x02, 0x03, 0x04};
lux_block_t block = {
    .id = 1,
    .parent_id = 0,
    .height = 1,
    .data = custom_data,
    .data_len = sizeof(custom_data)
};

lux_add_block(engine, &block);

Testing

cd pkg/c
gcc -O3 -o test_consensus test/test_consensus.c src/consensus_engine.c -I include
./test_consensus

Expected output:

=== LUX CONSENSUS C TEST SUITE ===

=== INITIALIZATION ===
[PASS] Initialize library
[PASS] Cleanup library

=== ENGINE ===
[PASS] Create Chain engine
[PASS] Create DAG engine
[PASS] Create PQ engine

=== BLOCKS ===
[PASS] Add block
[PASS] Add duplicate block

=== VOTING ===
[PASS] Process preference vote
[PASS] Process confidence vote

=== PERFORMANCE ===
[PASS] Add 1000 blocks in < 1 second

🎉 ALL TESTS PASSED! 100% SUCCESS RATE

Documentation

On this page