# Module Channel ## Overview The Channel module provides secure communication channels and packet management for the Cellframe SDK. This module implements encryption, authentication, and reliable transmission protocols for inter-node communication, enabling secure data exchange between blockchain network participants with support for multiple channel types and protocols. *Based on: `dap_chain_ch.h`, `dap_chain_ch.c`, `dap_chain_ch_pkt.h`, `dap_chain_ch_pkt.c`* ## Document Structure - [[#Overview|Overview]] - [[#Channel Architecture|Channel Architecture]] - [[#Base Channel Framework|Base Channel Framework]] - [[#Channel Types|Channel Types]] - [[#Chain Network Channel|Chain Network Channel - Core blockchain communication]] - [[#Chain Network Service Channel|Chain Network Service Channel - Service-specific communication]] - [[#Communication Protocols|Communication Protocols]] - [[#Error Codes|Error Codes]] - [[#Typical Examples|Typical Examples]] ## Channel Architecture ### Base Channel Framework All channels in the Cellframe SDK inherit from the base stream channel framework that provides standardized communication interfaces. ```c typedef struct dap_stream_ch { dap_stream_ch_id_t id; // Channel identifier dap_stream_worker_t *stream_worker; // Associated stream worker void *internal; // Channel-specific data dap_stream_ch_callbacks_t callbacks; // Channel callbacks } dap_stream_ch_t; ``` **Channel IDs:** - `DAP_STREAM_CH_CHAIN_NET_ID` ('N') - Chain network channel - `DAP_STREAM_CH_NET_SRV_ID` ('R') - Network service channel ## Channel Types ### Chain Network Channel Implements core blockchain communication protocols for node-to-node data exchange. #### Channel Structures ```c typedef struct dap_stream_ch_chain_net { dap_stream_ch_chain_net_callback_packet_t notify_callback; // Packet notification callback dap_stream_ch_t *ch; // Base channel void *notify_callback_arg; // Callback argument } dap_stream_ch_chain_net_t; typedef struct dap_chain_ch_validator_test { struct { uint8_t version[32]; // Node version information uint8_t flags; // Status flags (autoproc, order, online, etc.) uint32_t sign_size; // Signature size uint8_t sign_correct; // Signature verification status uint8_t overall_correct; // Overall validation status } DAP_ALIGN_PACKED header; byte_t sign[]; // Digital signature data } DAP_ALIGN_PACKED dap_chain_ch_validator_test_t; ``` **Validator Test Flags:** - `A_PROC` (0x01) - Autoproc set - `F_ORDR` (0x02) - Order exists - `A_ONLN` (0x04) - Auto online - `A_UPDT` (0x08) - Auto update - `D_SIGN` (0x40) - Data signed - `F_CERT` (0x80) - Certificate found ### dap_stream_ch_chain_net_pkt_hdr_t Header structure for chain network packets. ```c typedef struct stream_ch_chain_net_pkt_hdr { uint8_t version; // Protocol version byte_t padding; // Padding byte for alignment uint16_t data_size; // Size of packet data dap_chain_net_id_t net_id; // Network identifier } DAP_ALIGN_PACKED dap_stream_ch_chain_net_pkt_hdr_t; ``` **Fields:** - `version` - Protocol version (DAP_STREAM_CH_CHAIN_NET_PKT_VERSION) - `padding` - Alignment padding byte - `data_size` - Size of the packet data in bytes - `net_id` - Target network identifier ### dap_stream_ch_chain_net_pkt_t Complete chain network packet with header and data. ```c typedef struct dap_stream_ch_chain_net_pkt { dap_stream_ch_chain_net_pkt_hdr_t hdr; // Packet header uint8_t data[]; // Variable packet data } DAP_ALIGN_PACKED dap_stream_ch_chain_net_pkt_t; ``` **Fields:** - `hdr` - Packet header with version, size, and network information - `data` - Variable-length packet payload data #### Chain Network Operations ##### `dap_stream_ch_chain_net_init()` Initializes the chain network channel system. ```c int dap_stream_ch_chain_net_init(); ``` **Returns:** - `0` - Success - `-1` - Initialization failed ##### `dap_stream_ch_chain_net_from_session_data_extract_node_addr()` Extracts node address from session data. ```c dap_chain_node_addr_t dap_stream_ch_chain_net_from_session_data_extract_node_addr(uint32_t a_session_id); ``` **Parameters:** - `a_session_id` (uint32_t) - Session identifier **Returns:** - Node address structure ### Chain Network Service Channel Implements service-specific communication channels for blockchain services. #### Service Channel Structures ```c typedef struct dap_stream_ch_chain_net_srv { dap_chain_net_srv_uid_t srv_uid; // Service unique identifier dap_stream_ch_t *ch; // Base channel dap_stream_ch_uuid_t ch_uuid; // Channel UUID dap_stream_ch_chain_net_srv_callback_packet_t notify_callback; // Packet callback void *notify_callback_arg; // Callback argument } dap_stream_ch_chain_net_srv_t; ``` #### Service Request Structure ```c typedef struct dap_stream_ch_chain_net_srv_pkt_request_hdr { dap_chain_net_id_t net_id; // Target network ID dap_chain_hash_fast_t tx_cond; // Conditional transaction hash dap_chain_net_srv_uid_t srv_uid; // Service UID char token[DAP_CHAIN_TICKER_SIZE_MAX]; // Token ticker dap_chain_hash_fast_t client_pkey_hash; // Client public key hash dap_chain_hash_fast_t order_hash; // Order hash } DAP_ALIGN_PACKED dap_stream_ch_chain_net_srv_pkt_request_hdr_t; typedef struct dap_stream_ch_chain_net_srv_pkt_request { dap_stream_ch_chain_net_srv_pkt_request_hdr_t hdr; // Request header uint8_t data[]; // Request data } DAP_ALIGN_PACKED dap_stream_ch_chain_net_srv_pkt_request_t; ``` #### Service Data Packet Structure ```c typedef struct dap_stream_ch_chain_net_srv_pkt_data_hdr { uint8_t version; // Protocol version uint16_t data_size; // Data size uint8_t padding; // Padding byte uint32_t usage_id; // Usage identifier dap_chain_net_srv_uid_t srv_uid; // Service UID } DAP_ALIGN_PACKED dap_stream_ch_chain_net_srv_pkt_data_hdr_t; typedef struct dap_stream_ch_chain_net_srv_pkt_data { dap_stream_ch_chain_net_srv_pkt_data_hdr_t hdr; // Data header uint8_t data[]; // Payload data } DAP_ALIGN_PACKED dap_stream_ch_chain_net_srv_pkt_data_t; ``` #### Service Channel Operations ##### `dap_stream_ch_chain_net_srv_init()` Initializes a service channel for a specific service. ```c int dap_stream_ch_chain_net_srv_init(dap_chain_net_srv_t *a_srv); ``` **Parameters:** - `a_srv` (dap_chain_net_srv_t *) - Service instance **Returns:** - `0` - Success - `-1` - Initialization failed ##### `dap_stream_ch_chain_net_srv_pkt_data_write()` Writes data packet to service channel. ```c size_t dap_stream_ch_chain_net_srv_pkt_data_write( dap_stream_ch_t *a_ch, dap_chain_net_srv_uid_t a_srv_uid, uint32_t a_usage_id, const void *a_data, size_t a_data_size ); ``` **Parameters:** - `a_ch` (dap_stream_ch_t *) - Channel instance - `a_srv_uid` (dap_chain_net_srv_uid_t) - Service UID - `a_usage_id` (uint32_t) - Usage identifier - `a_data` (const void *) - Data to send - `a_data_size` (size_t) - Data size **Returns:** - Number of bytes written ## Communication Protocols ### Packet Types ```c // Request and response types #define DAP_STREAM_CH_CHAIN_NET_SRV_PKT_TYPE_REQUEST 0x01 #define DAP_STREAM_CH_CHAIN_NET_SRV_PKT_TYPE_SIGN_REQUEST 0x10 #define DAP_STREAM_CH_CHAIN_NET_SRV_PKT_TYPE_SIGN_RESPONSE 0x11 #define DAP_STREAM_CH_CHAIN_NET_SRV_PKT_TYPE_NOTIFY_STOPPED 0x20 #define DAP_STREAM_CH_CHAIN_NET_SRV_PKT_TYPE_DATA 0x30 #define DAP_STREAM_CH_CHAIN_NET_SRV_PKT_TYPE_RESPONSE_DATA 0x31 #define DAP_STREAM_CH_CHAIN_NET_SRV_PKT_TYPE_NEW_TX_COND_REQUEST 0x40 #define DAP_STREAM_CH_CHAIN_NET_SRV_PKT_TYPE_NEW_TX_COND_RESPONSE 0x41 #define DAP_STREAM_CH_CHAIN_NET_SRV_PKT_TYPE_RESPONSE_SUCCESS 0xf0 #define DAP_STREAM_CH_CHAIN_NET_SRV_PKT_TYPE_RESPONSE_ERROR 0xff // Connection testing #define DAP_STREAM_CH_CHAIN_NET_SRV_PKT_TYPE_CHECK_REQUEST 0x50 #define DAP_STREAM_CH_CHAIN_NET_SRV_PKT_TYPE_CHECK_RESPONSE 0x51 ``` ### Channel Comparison | Channel Type | Primary Function | Protocol | Use Cases | |--------------|------------------|----------|-----------| | **Chain Network** | Core Communication | Node-to-node messaging | Block propagation, validator testing | | **Chain Network Service** | Service Communication | Service-specific protocols | Exchange, voting, staking services | ## Error Codes ### Service Channel Error Codes ```c // Service errors #define DAP_STREAM_CH_CHAIN_NET_SRV_PKT_TYPE_RESPONSE_ERROR_CODE_SERVICE_NOT_FOUND 0x00000100 #define DAP_STREAM_CH_CHAIN_NET_SRV_PKT_TYPE_RESPONSE_ERROR_CODE_SERVICE_CH_NOT_FOUND 0x00000101 #define DAP_STREAM_CH_CHAIN_NET_SRV_PKT_TYPE_RESPONSE_ERROR_CODE_SERVICE_IN_CLIENT_MODE 0x00000102 // Network errors #define DAP_STREAM_CH_CHAIN_NET_SRV_PKT_TYPE_RESPONSE_ERROR_CODE_NETWORK_NOT_FOUND 0x00000200 #define DAP_STREAM_CH_CHAIN_NET_SRV_PKT_TYPE_RESPONSE_ERROR_CODE_NETWORK_NO_LEDGER 0x00000201 #define DAP_STREAM_CH_CHAIN_NET_SRV_PKT_TYPE_RESPONSE_ERROR_CODE_NETWORK_IS_OFFLINE 0x00000202 // Transaction errors #define DAP_STREAM_CH_CHAIN_NET_SRV_PKT_TYPE_RESPONSE_ERROR_CODE_TX_COND_NOT_FOUND 0x00000400 #define DAP_STREAM_CH_CHAIN_NET_SRV_PKT_TYPE_RESPONSE_ERROR_CODE_TX_COND_NO_COND_OUT 0x00000401 #define DAP_STREAM_CH_CHAIN_NET_SRV_PKT_TYPE_RESPONSE_ERROR_CODE_TX_COND_NOT_ENOUGH 0x00000402 // Receipt errors #define DAP_STREAM_CH_CHAIN_NET_SRV_PKT_TYPE_RESPONSE_ERROR_CODE_RECEIPT_CANT_FIND 0x00000500 #define DAP_STREAM_CH_CHAIN_NET_SRV_PKT_TYPE_RESPONSE_ERROR_CODE_RECEIPT_NO_SIGN 0x00000501 // General errors #define DAP_STREAM_CH_CHAIN_NET_SRV_PKT_TYPE_RESPONSE_ERROR_CODE_ALLOC_MEMORY_ERROR 0x00BADA55 #define DAP_STREAM_CH_CHAIN_NET_SRV_PKT_TYPE_RESPONSE_ERROR_CODE_UNKNOWN 0xffffffff ``` ## Typical Examples ### Chain Network Channel Example ```c #include <dap_stream_ch_chain_net.h> void chain_net_channel_example() { log_it_info("=== Chain Network Channel Example ==="); // Step 1: Initialize chain network channel system int init_result = dap_stream_ch_chain_net_init(); if (init_result != 0) { log_it_error("✗ Failed to initialize chain network channel: %d", init_result); return; } log_it_info("✓ Chain network channel system initialized"); // Step 2: Extract node address from session uint32_t session_id = 12345; // Example session ID dap_chain_node_addr_t node_addr = dap_stream_ch_chain_net_from_session_data_extract_node_addr(session_id); // Convert node address to string for logging char *node_addr_str = dap_chain_node_addr_to_str(&node_addr); if (node_addr_str) { log_it_info("✓ Node address extracted: %s", node_addr_str); DAP_DELETE(node_addr_str); } else { log_it_error("✗ Failed to extract node address from session %u", session_id); } // Step 3: Simulate validator test data dap_chain_ch_validator_test_t test_data = {0}; // Set version information strncpy((char*)test_data.header.version, "1.0.0", sizeof(test_data.header.version) - 1); // Set status flags test_data.header.flags = A_PROC | A_ONLN | D_SIGN | F_CERT; test_data.header.sign_size = 64; // Example signature size test_data.header.sign_correct = 1; test_data.header.overall_correct = 1; // Validate test data bool is_autoproc = (test_data.header.flags & A_PROC) != 0; bool is_online = (test_data.header.flags & A_ONLN) != 0; bool is_signed = (test_data.header.flags & D_SIGN) != 0; bool has_cert = (test_data.header.flags & F_CERT) != 0; log_it_info("Validator test status:"); log_it_info(" Autoproc: %s", is_autoproc ? "✓" : "✗"); log_it_info(" Online: %s", is_online ? "✓" : "✗"); log_it_info(" Signed: %s", is_signed ? "✓" : "✗"); log_it_info(" Certificate: %s", has_cert ? "✓" : "✗"); log_it_info(" Overall status: %s", test_data.header.overall_correct ? "VALID" : "INVALID"); log_it_info("Chain network channel example completed"); } ``` ### Service Channel Communication Example ```c #include <dap_stream_ch_chain_net_srv.h> void service_channel_example() { log_it_info("=== Service Channel Communication Example ==="); // Step 1: Setup service channel (assuming service exists) dap_chain_net_srv_t *service = dap_chain_net_srv_get(0x2); // Exchange service if (!service) { log_it_error("✗ Exchange service not found"); return; } // Step 2: Initialize service channel int init_result = dap_stream_ch_chain_net_srv_init(service); if (init_result != 0) { log_it_error("✗ Failed to initialize service channel: %d", init_result); return; } log_it_info("✓ Service channel initialized for service UID: 0x%x", service->uid.uint32); // Step 3: Prepare service request packet dap_stream_ch_chain_net_srv_pkt_request_t request = {0}; // Set network ID request.hdr.net_id.uint64 = 0x0123456789abcdef; // Set service UID request.hdr.srv_uid.uint32 = 0x2; // Exchange service // Set token ticker strncpy(request.hdr.token, "CELL", DAP_CHAIN_TICKER_SIZE_MAX - 1); // Set example hashes (normally these would be real hashes) memset(&request.hdr.tx_cond, 0x11, sizeof(dap_chain_hash_fast_t)); memset(&request.hdr.client_pkey_hash, 0x22, sizeof(dap_chain_hash_fast_t)); memset(&request.hdr.order_hash, 0x33, sizeof(dap_chain_hash_fast_t)); log_it_info("✓ Service request packet prepared"); log_it_info(" Network ID: 0x%016" PRIx64, request.hdr.net_id.uint64); log_it_info(" Service UID: 0x%x", request.hdr.srv_uid.uint32); log_it_info(" Token: %s", request.hdr.token); // Step 4: Simulate data packet transmission const char *test_data = "Exchange order request data"; size_t data_size = strlen(test_data); uint32_t usage_id = 1001; // Note: This would normally be called with a real channel log_it_info("✓ Simulating data packet transmission:"); log_it_info(" Usage ID: %u", usage_id); log_it_info(" Data size: %zu bytes", data_size); log_it_info(" Data: %s", test_data); log_it_info("Service channel communication example completed"); } ``` --- *See also: [[Modules/Module Service|Module Service]], [[Modules/Module Chain Network|Module Chain Network]], [[ETC/Architecture Overview|Architecture Overview]]*