Owner: @Álvaro Castro-Castilla @Daniel Sanchez Quiros

Nomos C API Requirements

Goal

Enable simple Logos programs to interact with Nomos blockchain through a Node C API - for running and managing Nomos blockchain nodes

Node C API Requirements

1. Node Lifecycle Management

Based on Nomos service architecture with Overwatch pattern:

// Basic node instance
typedef struct NomosNode NomosNode;

// Node initialization with configuration
NomosNode* nomos_init(
    const char* config_yaml         // INPUT: YAML configuration file path
);                                  // OUTPUT: node instance or NULL

// Start all node services
void nomos_start(
    NomosNode* node                 // INPUT: node instance
    const char* error,				      // OUTPUT: error in case of failure
);                                  // OUTPUT: 0=success, 1=error

// Stop node gracefully
void nomos_stop(
    NomosNode* node                 // INPUT: node instance
    const char* error,				      // OUTPUT: error in case of failure
);                                  // OUTPUT: 0=success, 1=error

// Get node status
typedef struct {
    int is_running;                 // 0=stopped, 1=running
    char* node_id;                  // Node peer ID
    uint64_t block_height;          // Current block height
} NomosStatus;

void nomos_get_status(
    NomosNode* node,                // INPUT: node instance
    NomosStatus* status             // OUTPUT: status structure
);

2. Core Blockchain Operations

Based on nomos-core structures:

// Submit transaction to mempool
bool nomos_submit_transaction(
    NomosNode* node,                // INPUT: node instance
    const char* tx_json             // INPUT: transaction as JSON
    char**      error,				      // OUTPUT: error in case of failure
);                                  // OUTPUT: true=success, false=error

// Get block by height (from canonical chain)
void nomos_get_block(
    NomosNode* node,                // INPUT: node instance
    const char* block_id,           // INPUT: block id
    char** block_json               // OUTPUT: block data as JSON void if not found
    char** error,				            // OUTPUT: error in case of failure
);

// Get transaction by hash
void nomos_get_transaction(
    NomosNode* node,                // INPUT: node instance
    const char* tx_id,              // INPUT: transaction hash
    char** tx_json                  // OUTPUT: transaction data as JSON
    char** error,				            // OUTPUT: error in case of failure
);

3. Data Availability (nomos-da)

Based on NomosDA with:

// Submit data for availability
bool nomos_da_submit_data(
    NomosNode* node,                // INPUT: node instance
    const char* data,               // INPUT: data bytes
    size_t data_len,                // INPUT: data length
    char** commitment_json          // OUTPUT: KZG commitment as JSON
    char** error,				    // OUTPUT: error in case of failure
);

// Verify data availability, light node related
bool nomos_da_sample_blob(
    NomosNode* node,                // INPUT: node instance
    const char* blob_id,	          // INPUT: blob id
    char** error,				            // OUTPUT: error in case of failure
);                                  // OUTPUT: true=available, false=not available

4. Networking (nomos-libp2p)

Based on libp2p networking layer:

// Get peer information
void nomos_network_get_peers(
    NomosNode* node,                // INPUT: node instance
    char** peers_json               // OUTPUT: connected peers as JSON
);

Implementation Requirements

Error Handling