## Overview Comprehensive network infrastructure providing distributed blockchain networking, node coordination, ledger management, and service integration for the Cellframe SDK. This module implements the complete networking layer including network topology management, node discovery and communication, transaction ledger coordination, cross-chain operations, and distributed service infrastructure. *Based on: `dap_chain_net.h`, `dap_chain_net.c`, `dap_chain_node.h`, `dap_chain_node.c`, `dap_chain_ledger.h`, `dap_chain_ledger.c`, `dap_chain_net_srv.h`, `dap_chain_net_srv.c`, `dap_chain_net_tx.h`, `dap_chain_net_tx.c`, `dap_chain_net_anchor.h`, `dap_chain_net_anchor.c`, `dap_chain_net_decree.h`, `dap_chain_net_decree.c`, `dap_chain_net_balancer.h`, `dap_chain_net_balancer.c`, `dap_chain_node_client.h`, `dap_chain_node_client.c`, `dap_chain_node_dns_server.h`, `dap_chain_node_dns_server.c`, `dap_chain_node_dns_client.h`, `dap_chain_node_dns_client.c`* ## Document Structure - [[#Overview|Overview]] - [[#Network Core|Network Core]] - Core network infrastructure and lifecycle management - [[#Node Management|Node Management]] - Node discovery, registration, and communication - [[#Ledger Operations|Ledger Operations]] - Distributed transaction ledger and balance management - [[#Transaction Processing|Transaction Processing]] - Transaction validation, routing, and processing - [[#Cross-Chain Operations|Cross-Chain Operations]] - Anchoring, bridging, and interoperability - [[#Network Services|Network Services]] - Service discovery, ordering, and management - [[#Network Balancing|Network Balancing]] - Load balancing and network optimization - [[#DNS Resolution|DNS Resolution]] - Name resolution and discovery services --- ## Network Core *Based on: `dap_chain_net.h`, `dap_chain_net.c`* ### Overview Core network infrastructure providing fundamental networking functionality including network lifecycle management, state machine operations, multi-chain coordination, and distributed consensus support. ### Document Structure - [[#Overview|Overview]] - [[#Enumerations|Enumerations]] - [[#dap_chain_net_state_t|dap_chain_net_state_t - Network state machine values]] - [[#dap_chain_net_json_rpc_error_list|dap_chain_net_json_rpc_error_list - JSON-RPC error codes]] - [[#Structures|Structures]] - [[#dap_chain_net_t|dap_chain_net_t - Main network structure]] - [[#Functions|Functions]] - [[#Network Lifecycle Functions|Network Lifecycle Functions]] ### Enumerations #### dap_chain_net_state_t Network state machine values for managing network lifecycle. ```c typedef enum dap_chain_net_state { NET_STATE_LOADING = 0, // Network loading and initialization NET_STATE_OFFLINE, // Network offline (not connected) NET_STATE_LINKS_PREPARE, // Preparing network links NET_STATE_LINKS_CONNECTING, // Establishing network connections NET_STATE_LINKS_ESTABLISHED, // Network links established NET_STATE_SYNC_CHAINS, // Synchronizing blockchain data NET_STATE_ONLINE // Network fully operational } dap_chain_net_state_t; ``` **State Transitions:** - `LOADING` → `OFFLINE` - Initial network loading completed - `OFFLINE` → `LINKS_PREPARE` - Starting network connection process - `LINKS_PREPARE` → `LINKS_CONNECTING` - Beginning link establishment - `LINKS_CONNECTING` → `LINKS_ESTABLISHED` - Network links successfully established - `LINKS_ESTABLISHED` → `SYNC_CHAINS` - Starting blockchain synchronization - `SYNC_CHAINS` → `ONLINE` - Network fully synchronized and operational #### dap_chain_net_json_rpc_error_list JSON-RPC error codes for network operations. ```c enum dap_chain_net_json_rpc_error_list { DAP_CHAIN_NET_JSON_RPC_OK, // Operation successful DAP_CHAIN_NET_JSON_RPC_INVALID_PARAMETER_HASH = DAP_JSON_RPC_ERR_CODE_METHOD_ERR_START, // Invalid hash parameter DAP_CHAIN_NET_JSON_RPC_CAN_NOT_PARAMETER_NET_REQUIRE, // Required network parameter missing DAP_CHAIN_NET_JSON_RPC_WRONG_NET, // Wrong network specified DAP_CHAIN_NET_JSON_RPC_MANY_ARGUMENT_FOR_COMMAND_NET_LIST, // Too many arguments for net list command DAP_CHAIN_NET_JSON_RPC_UNDEFINED_PARAMETER_COMMAND_STATS, // Undefined parameter for stats command DAP_CHAIN_NET_JSON_RPC_UNDEFINED_PARAMETER_COMMAND_GO, // Undefined parameter for go command DAP_CHAIN_NET_JSON_RPC_UNDEFINED_PARAMETER_ADDR_COMMAND_INFO, // Undefined address parameter for info command DAP_CHAIN_NET_JSON_RPC_CANT_CALCULATE_HASH_FOR_ADDR, // Cannot calculate hash for address DAP_CHAIN_NET_JSON_RPC_CAN_NOT_GET_CLUSTER, // Cannot get cluster DAP_CHAIN_NET_JSON_RPC_UNDEFINED_PARAMETERS_COMMAND_LINK, // Undefined parameters for link command DAP_CHAIN_NET_JSON_RPC_UNDEFINED_PARAMETERS_COMMAND_SYNC, // Undefined parameters for sync command DAP_CHAIN_NET_JSON_RPC_UNDEFINED_PARAMETERS_CA_ADD, // Undefined parameters for CA add DAP_CHAIN_NET_JSON_RPC_CAN_NOT_FIND_CERT_CA_ADD, // Cannot find certificate for CA add DAP_CHAIN_NET_JSON_RPC_CAN_NOT_KEY_IN_CERT_CA_ADD, // Cannot get key from certificate for CA add DAP_CHAIN_NET_JSON_RPC_CAN_SERIALIZE_PUBLIC_KEY_CERT_CA_ADD, // Cannot serialize public key for CA add DAP_CHAIN_NET_JSON_RPC_DATABASE_ACL_GROUP_NOT_DEFINED_FOR_THIS_NETWORK_CA_ADD, // Database ACL group not defined for CA add DAP_CHAIN_NET_JSON_RPC_CAN_NOT_SAVE_PUBLIC_KEY_IN_DATABASE, // Cannot save public key in database DAP_CHAIN_NET_JSON_RPC_DATABASE_ACL_GROUP_NOT_DEFINED_FOR_THIS_NETWORK_CA_LIST, // Database ACL group not defined for CA list DAP_CHAIN_NET_JSON_RPC_UNKNOWN_HASH_CA_DEL, // Unknown hash for CA delete DAP_CHAIN_NET_JSON_RPC_DATABASE_ACL_GROUP_NOT_DEFINED_FOR_THIS_NETWORK_CA_DEL, // Database ACL group not defined for CA delete DAP_CHAIN_NET_JSON_RPC_CAN_NOT_FIND_CERT_CA_DEL, // Cannot find certificate for CA delete DAP_CHAIN_NET_JSON_RPC_INVALID_PARAMETER_COMMAND_CA, // Invalid parameter for CA command DAP_CHAIN_NET_JSON_RPC_NO_POA_CERTS_FOUND_POA_CERTS, // No PoA certificates found DAP_CHAIN_NET_JSON_RPC_UNKNOWN_SUBCOMMANDS // Unknown subcommand }; ``` ### Structures #### dap_chain_net_t Main network structure containing complete network configuration, state, and operational data. ```c typedef struct dap_chain_net { struct { dap_chain_net_id_t id; // Network unique identifier char name[DAP_CHAIN_NET_NAME_MAX + 1]; // Human-readable network name char gdb_nodes[DAP_CHAIN_NET_NAME_MAX + sizeof(s_gdb_nodes_postfix) + 1]; // Node database key const char *gdb_groups_prefix; // Database group prefix for organization const char *native_ticker; // Native token ticker symbol dap_list_t *keys; // List of PoA certificates for network dap_chain_t *chains; // Double-linked list of blockchain chains dap_ledger_t *ledger; // Network transaction ledger uint256_t fee_value; // Standard network transaction fee dap_chain_addr_t fee_addr; // Fee collection address dap_chain_net_id_t *bridged_networks; // Array of bridged network IDs uint16_t bridged_networks_count; // Number of bridged networks dap_config_t *config; // Network configuration object bool mempool_autoproc; // Automatic mempool processing flag } pub; UT_hash_handle hh, hh2; // Hash table handles for indexing uint8_t pvt[]; // Private network data } dap_chain_net_t; ``` **Public Fields:** - `id` - Unique 64-bit network identifier for network addressing and routing - `name` - Human-readable network name (maximum 32 characters) - `gdb_nodes` - Database key for storing network node list information - `gdb_groups_prefix` - Database group prefix for organizing network data - `native_ticker` - Native token ticker symbol for the network's primary currency - `keys` - List of Proof-of-Authority certificates for network validation - `chains` - Double-linked list of all blockchain chains operating in the network - `ledger` - Network's distributed transaction ledger for balance tracking - `fee_value` - Standard transaction fee amount in network's native token - `fee_addr` - Address where transaction fees are collected - `bridged_networks` - Array of network IDs allowed for cross-chain transactions - `bridged_networks_count` - Number of networks in the bridged networks array - `config` - Network configuration object containing all network parameters - `mempool_autoproc` - Flag indicating automatic mempool processing **Private Fields:** - `hh, hh2` - Hash table handles for efficient network lookup operations - `pvt[]` - Variable-length private data area for internal network state ### Functions #### Network Lifecycle Functions #### `dap_chain_net_init()` Initialize the network module subsystem. ```c int dap_chain_net_init(void); ``` **Returns:** - `0` - Success - `negative value` - Error code **Error Conditions:** - Returns non-zero if network initialization fails **Description:** Initializes the network module, sets up data structures, and prepares the system for network operations. #### `dap_chain_net_by_name()` Find network by name. ```c dap_chain_net_t *dap_chain_net_by_name(const char *a_name); ``` **Parameters:** - `a_name` (const char*) - Network name to search for **Returns:** - `network pointer` - Found network structure - `NULL` - Network not found **Error Conditions:** - Returns NULL if name is NULL - Returns NULL if network doesn't exist **Description:** Searches for and returns a network structure by its name. #### `dap_chain_net_state_go_to()` Change network state to specified target state. ```c int dap_chain_net_state_go_to(dap_chain_net_t *a_net, dap_chain_net_state_t a_new_state); ``` **Parameters:** - `a_net` (dap_chain_net_t*) - Network to change state - `a_new_state` (dap_chain_net_state_t) - Target state **Returns:** - `0` - State change successful - `negative value` - State change failed **Error Conditions:** - Returns error if network is NULL - Returns error if state transition is invalid **Description:** Transitions the network to a new operational state following the state machine. #### `dap_chain_net_deinit()` Deinitialize the network module subsystem. ```c void dap_chain_net_deinit(void); ``` **Description:** Cleans up network module resources and shuts down the network subsystem. #### `dap_chain_net_test_init()` Initialize network module for testing purposes. ```c int dap_chain_net_test_init(); ``` **Returns:** - `0` - Test initialization successful - `negative value` - Test initialization failed **Description:** Initializes the network module with test-specific configuration for unit testing. #### `dap_chain_net_load_all()` Load all networks from configuration. ```c void dap_chain_net_load_all(); ``` **Description:** Loads all configured networks from the system configuration and initializes them. #### `dap_chain_net_try_online_all()` Attempt to bring all networks online. ```c void dap_chain_net_try_online_all(); ``` **Description:** Attempts to transition all loaded networks to online state. #### `dap_chain_net_get_target_state()` Get the target state for a network. ```c dap_chain_net_state_t dap_chain_net_get_target_state(dap_chain_net_t *a_net); ``` **Parameters:** - `a_net` (dap_chain_net_t*) - Network to query **Returns:** - `dap_chain_net_state_t` - Target state of the network **Description:** Returns the target state that the network is trying to reach. #### `dap_chain_net_get_state()` Get the current state of a network. ```c dap_chain_net_state_t dap_chain_net_get_state(dap_chain_net_t *l_net); ``` **Parameters:** - `l_net` (dap_chain_net_t*) - Network to query **Returns:** - `dap_chain_net_state_t` - Current state of the network **Description:** Returns the current operational state of the network. #### `dap_chain_net_start()` Start a network (bring it online). ```c int dap_chain_net_start(dap_chain_net_t *a_net); ``` **Parameters:** - `a_net` (dap_chain_net_t*) - Network to start **Returns:** - `0` - Network started successfully - `negative value` - Start failed **Description:** Initiates the network startup process to bring it online. #### `dap_chain_net_stop()` Stop a network. ```c bool dap_chain_net_stop(dap_chain_net_t *a_net); ``` **Parameters:** - `a_net` (dap_chain_net_t*) - Network to stop **Returns:** - `true` - Network stopped successfully - `false` - Stop failed **Description:** Stops the network and transitions it to offline state. #### `dap_chain_net_links_establish()` Establish network links. ```c int dap_chain_net_links_establish(dap_chain_net_t *a_net); ``` **Parameters:** - `a_net` (dap_chain_net_t*) - Network to establish links for **Returns:** - `0` - Links established successfully - `negative value` - Link establishment failed **Description:** Establishes network connections and links for the specified network. #### `dap_chain_net_sync()` Synchronize network chains. ```c int dap_chain_net_sync(dap_chain_net_t *a_net); ``` **Parameters:** - `a_net` (dap_chain_net_t*) - Network to synchronize **Returns:** - `0` - Synchronization initiated successfully - `negative value` - Synchronization failed **Description:** Initiates blockchain synchronization for the network. #### `dap_chain_net_delete()` Delete a network and free all resources. ```c void dap_chain_net_delete(dap_chain_net_t *a_net); ``` **Parameters:** - `a_net` (dap_chain_net_t*) - Network to delete **Description:** Completely removes the network and frees all associated resources. #### `dap_chain_net_proc_mempool()` Process the network's mempool. ```c void dap_chain_net_proc_mempool(dap_chain_net_t *a_net); ``` **Parameters:** - `a_net` (dap_chain_net_t*) - Network whose mempool to process **Description:** Processes pending transactions in the network's mempool. #### `dap_chain_net_set_flag_sync_from_zero()` Set flag to sync network from zero. ```c void dap_chain_net_set_flag_sync_from_zero(dap_chain_net_t *a_net, bool a_flag_sync_from_zero); ``` **Parameters:** - `a_net` (dap_chain_net_t*) - Network to configure - `a_flag_sync_from_zero` (bool) - Flag to enable sync from zero **Description:** Sets the flag to synchronize the network from the beginning (block 0). #### `dap_chain_net_get_flag_sync_from_zero()` Get the sync from zero flag status. ```c bool dap_chain_net_get_flag_sync_from_zero(dap_chain_net_t *a_net); ``` **Parameters:** - `a_net` (dap_chain_net_t*) - Network to query **Returns:** - `true` - Sync from zero is enabled - `false` - Sync from zero is disabled **Description:** Returns the current status of the sync from zero flag. #### `dap_chain_net_by_id()` Find network by identifier. ```c dap_chain_net_t *dap_chain_net_by_id(dap_chain_net_id_t a_id); ``` **Parameters:** - `a_id` (dap_chain_net_id_t) - Network identifier to search for **Returns:** - `network pointer` - Found network structure - `NULL` - Network not found **Description:** Searches for and returns a network structure by its identifier. #### `dap_chain_net_get_acl_idx()` Get ACL index for a network. ```c uint16_t dap_chain_net_get_acl_idx(dap_chain_net_t *a_net); ``` **Parameters:** - `a_net` (dap_chain_net_t*) - Network to query **Returns:** - `uint16_t` - ACL index for the network **Description:** Returns the Access Control List index associated with the network. #### `dap_chain_net_id_by_name()` Get network ID by name. ```c dap_chain_net_id_t dap_chain_net_id_by_name(const char *a_name); ``` **Parameters:** - `a_name` (const char*) - Network name to search for **Returns:** - `dap_chain_net_id_t` - Network identifier - `0` - Network not found **Description:** Returns the network identifier for a given network name. #### `dap_chain_net_get_chain_by_name()` Get chain by name within a network. ```c dap_chain_t *dap_chain_net_get_chain_by_name(dap_chain_net_t *l_net, const char *a_name); ``` **Parameters:** - `l_net` (dap_chain_net_t*) - Network to search in - `a_name` (const char*) - Chain name to search for **Returns:** - `chain pointer` - Found chain structure - `NULL` - Chain not found **Description:** Searches for a chain by name within the specified network. #### `dap_chain_net_get_chain_by_id()` Get chain by ID within a network. ```c dap_chain_t *dap_chain_net_get_chain_by_id(dap_chain_net_t *l_net, dap_chain_id_t a_chain_id); ``` **Parameters:** - `l_net` (dap_chain_net_t*) - Network to search in - `a_chain_id` (dap_chain_id_t) - Chain identifier to search for **Returns:** - `chain pointer` - Found chain structure - `NULL` - Chain not found **Description:** Searches for a chain by identifier within the specified network. #### `dap_chain_net_get_cur_addr_int()` Get current node address as integer. ```c uint64_t dap_chain_net_get_cur_addr_int(dap_chain_net_t *l_net); ``` **Parameters:** - `l_net` (dap_chain_net_t*) - Network context **Returns:** - `uint64_t` - Current node address as 64-bit integer **Description:** Returns the current node's address in integer format. #### `dap_chain_net_get_cur_cell()` Get current cell for a network. ```c dap_chain_cell_id_t *dap_chain_net_get_cur_cell(dap_chain_net_t *l_net); ``` **Parameters:** - `l_net` (dap_chain_net_t*) - Network to query **Returns:** - `cell_id pointer` - Current cell identifier - `NULL` - No current cell **Description:** Returns the current cell identifier for the network. #### `dap_chain_net_get_role()` Get the role of the current node in the network. ```c dap_chain_node_role_t dap_chain_net_get_role(dap_chain_net_t *a_net); ``` **Parameters:** - `a_net` (dap_chain_net_t*) - Network to query **Returns:** - `dap_chain_node_role_t` - Current node's role in the network **Description:** Returns the role of the current node within the specified network. --- ## Node Management *Based on: `dap_chain_node.h`, `dap_chain_node.c`, `dap_chain_node_client.h`, `dap_chain_node_client.c`* ### Overview Node management infrastructure providing node discovery, registration, communication protocols, and network participation coordination. ### Document Structure - [[#Overview|Overview]] - [[#Enumerations|Enumerations]] - [[#dap_chain_node_client_state_t|dap_chain_node_client_state_t - Node client connection states]] - [[#Structures|Structures]] - [[#dap_chain_node_info_old_t|dap_chain_node_info_old_t - Legacy node information structure]] - [[#dap_chain_node_info_t|dap_chain_node_info_t - Node information structure]] - [[#dap_chain_node_states_info_t|dap_chain_node_states_info_t - Node state information]] - [[#dap_chain_node_client_t|dap_chain_node_client_t - Node client structure]] - [[#Functions|Functions]] - [[#Node Registration Functions|Node Registration Functions]] ### Enumerations #### dap_chain_node_client_state_t Connection states for node client connections. ```c typedef enum dap_chain_node_client_state { NODE_CLIENT_STATE_ERROR = -1, // Connection error state NODE_CLIENT_STATE_DISCONNECTED = 0, // Client disconnected NODE_CLIENT_STATE_PING = 3, // Ping state NODE_CLIENT_STATE_PONG = 4, // Pong response state NODE_CLIENT_STATE_CONNECTING = 5, // Connection in progress NODE_CLIENT_STATE_ESTABLISHED = 100, // Connection established NODE_CLIENT_STATE_CHECKED = 130, // Connection checked NODE_CLIENT_STATE_VALID_READY = 140 // Connection valid and ready } dap_chain_node_client_state_t; ``` ### Structures #### dap_chain_node_info_old_t Legacy node information structure for backward compatibility. ```c typedef struct dap_chain_node_info_old { struct { dap_chain_node_addr_t address; // Node network address dap_chain_cell_id_t cell_id; // Cell identifier uint32_t links_number; // Number of links struct in_addr ext_addr_v4; // External IPv4 address struct in6_addr ext_addr_v6; // External IPv6 address uint16_t ext_port; // External port char alias[240]; // Node alias (legacy size) dap_chain_node_addr_t owner_address; // Owner address uint64_t blocks_events; // Block events count } DAP_ALIGN_PACKED hdr; dap_chain_node_addr_t links[]; // Array of linked node addresses } DAP_ALIGN_PACKED dap_chain_node_info_old_t; ``` **Fields:** - `hdr.address` - Node's network address for identification - `hdr.cell_id` - Cell identifier for network location - `hdr.links_number` - Number of connected links - `hdr.ext_addr_v4` - External IPv4 address for connections - `hdr.ext_addr_v6` - External IPv6 address for connections - `hdr.ext_port` - External port for incoming connections - `hdr.alias` - Human-readable node alias (legacy 240 character limit) - `hdr.owner_address` - Address of the node owner - `hdr.blocks_events` - Count of block events processed - `links[]` - Variable-length array of linked node addresses #### dap_chain_node_info_t Node information structure for network participant registration and discovery. ```c typedef struct dap_chain_node_info { dap_chain_node_addr_t address; // Node's unique network address dap_chain_cell_id_t cell_id; // Cell identifier for node location char alias[64]; // Human-readable node alias name uint16_t ext_port; // External port for connections uint8_t ext_host_len; // Length of external host address char ext_host[]; // Variable-length external host address } DAP_ALIGN_PACKED dap_chain_node_info_t; ``` **Fields:** - `address` - Node's unique network address for identification and routing - `cell_id` - Cell identifier specifying the node's logical location in the network - `alias` - Human-readable node alias name (maximum 64 characters) - `ext_port` - External port number for incoming connections - `ext_host_len` - Length of the external host address string - `ext_host[]` - Variable-length external host address (IP or domain name) #### dap_chain_node_states_info_t Node state information for balancing and monitoring. ```c typedef struct dap_chain_node_states_info { dap_link_info_t link_info; // Link information dap_chain_node_role_t role; // Node role in network uint64_t events_count; // Number of events processed uint64_t atoms_count; // Number of atoms processed uint32_t downlinks_count; // Number of downlinks dap_nanotime_t timestamp; // Last update timestamp } dap_chain_node_states_info_t; ``` **Fields:** - `link_info` - Information about network link status and quality - `role` - Role of the node in the network (validator, full node, etc.) - `events_count` - Total number of events processed by the node - `atoms_count` - Total number of atoms processed by the node - `downlinks_count` - Number of downstream connections - `timestamp` - Timestamp of last state update #### dap_chain_node_client_t Node client structure for managing connections to other nodes. ```c typedef struct dap_chain_node_client { dap_chain_node_client_state_t state; // Current connection state dap_chain_cell_id_t cell_id; // Cell identifier dap_client_t *client; // Client connection object dap_stream_worker_t *stream_worker; // Stream worker for handling data dap_chain_t *cur_chain; // Current chain being updated dap_chain_cell_t *cur_cell; // Current cell being updated dap_stream_ch_t *ch_chain_net; // Chain network channel dap_stream_ch_uuid_t ch_chain_net_uuid; // Chain network channel UUID dap_stream_ch_t *ch_chain_net_srv; // Chain network service channel dap_stream_ch_uuid_t ch_chain_net_srv_uuid; // Chain network service channel UUID dap_chain_node_info_t *info; // Node information dap_chain_net_t *net; // Associated network char last_error[128]; // Last error message dap_events_socket_uuid_t esocket_uuid; // Event socket UUID pthread_cond_t wait_cond; // Wait condition variable pthread_mutex_t wait_mutex; // Wait mutex dap_chain_node_addr_t remote_node_addr; // Remote node address bool is_connected; // Connection status flag dap_timerfd_t *sync_timer; // Synchronization timer dap_timerfd_t *reconnect_timer; // Reconnection timer dap_chain_node_client_callbacks_t callbacks; // Connection callbacks dap_chain_node_client_notify_callbacks_t notify_callbacks; // Notification callbacks void *callbacks_arg; // Callback argument } dap_chain_node_client_t; ``` **Fields:** - `state` - Current state of the client connection - `cell_id` - Cell identifier for network location - `client` - Underlying client connection object - `stream_worker` - Worker thread for handling stream data - `cur_chain` - Chain currently being synchronized or updated - `cur_cell` - Cell currently being processed - `ch_chain_net` - Channel for chain network communication - `ch_chain_net_uuid` - UUID of the chain network channel - `ch_chain_net_srv` - Channel for chain network services - `ch_chain_net_srv_uuid` - UUID of the chain network service channel - `info` - Information about the remote node - `net` - Network this client belongs to - `last_error` - Buffer containing last error message - `esocket_uuid` - UUID of the event socket - `wait_cond` - Condition variable for synchronization - `wait_mutex` - Mutex for thread synchronization - `remote_node_addr` - Address of the remote node - `is_connected` - Flag indicating connection status - `sync_timer` - Timer for synchronization operations - `reconnect_timer` - Timer for reconnection attempts - `callbacks` - Structure containing connection callbacks - `notify_callbacks` - Structure containing notification callbacks - `callbacks_arg` - Argument passed to callback functions ### Functions #### Node Registration Functions #### `dap_chain_node_alias_register()` Register a node alias in the network. ```c bool dap_chain_node_alias_register(dap_chain_net_t *a_net, const char *a_alias, dap_chain_node_addr_t *a_addr); ``` **Parameters:** - `a_net` (dap_chain_net_t*) - Target network - `a_alias` (const char*) - Alias name to register - `a_addr` (dap_chain_node_addr_t*) - Node address **Returns:** - `true` - Registration successful - `false` - Registration failed **Error Conditions:** - Returns false if alias already exists - Returns false if address is invalid **Description:** Registers a human-readable alias for a node address in the network. #### `dap_chain_node_info_save()` Save node information to the network database. ```c int dap_chain_node_info_save(dap_chain_net_t *l_net, dap_chain_node_info_t *node_info); ``` **Parameters:** - `l_net` (dap_chain_net_t*) - Target network - `node_info` (dap_chain_node_info_t*) - Node information to save **Returns:** - `0` - Save successful - `negative value` - Save failed **Error Conditions:** - Returns error if network is NULL - Returns error if node info is invalid **Description:** Saves node information to the network's node database for discovery. --- ## Ledger Operations *Based on: `dap_chain_ledger.h`, `dap_chain_ledger.c`* ### Overview Distributed transaction ledger providing balance tracking, transaction validation, token management, and consensus coordination across the network. ### Document Structure - [[#Overview|Overview]] - [[#Enumerations|Enumerations]] - [[#dap_ledger_check_error_t|dap_ledger_check_error_t - Ledger validation error codes]] - [[#Structures|Structures]] - [[#dap_ledger_t|dap_ledger_t - Network ledger structure]] - [[#Functions|Functions]] - [[#Ledger Management Functions|Ledger Management Functions]] ### Enumerations #### dap_ledger_check_error_t Ledger validation error codes for transaction processing. ```c typedef enum dap_ledger_check_error { DAP_LEDGER_CHECK_OK = 0, // Validation successful DAP_LEDGER_CHECK_INVALID_ARGS, // Invalid arguments provided DAP_LEDGER_CHECK_INVALID_SIZE, // Invalid transaction size DAP_LEDGER_CHECK_ALREADY_CACHED, // Transaction already in cache DAP_LEDGER_CHECK_PARSE_ERROR, // Transaction parsing error DAP_LEDGER_CHECK_APPLY_ERROR, // Transaction application error DAP_LEDGER_CHECK_NOT_ENOUGH_MEMORY, // Insufficient memory DAP_LEDGER_CHECK_INTEGER_OVERFLOW, // Integer overflow detected DAP_LEDGER_CHECK_NOT_ENOUGH_VALID_SIGNS, // Insufficient valid signatures DAP_LEDGER_CHECK_TICKER_NOT_FOUND, // Token ticker not found DAP_LEDGER_CHECK_ZERO_VALUE, // Zero value transaction DAP_LEDGER_CHECK_ADDR_FORBIDDEN, // Address is forbidden DAP_LEDGER_CHECK_WHITELISTED, // Address is whitelisted /* Additional TX validation codes */ DAP_LEDGER_TX_CHECK_PREV_TX_NOT_FOUND, // Previous transaction not found DAP_LEDGER_TX_CHECK_EMISSION_NOT_FOUND, // Token emission not found DAP_LEDGER_TX_CHECK_SUM_INS_NOT_EQUAL_SUM_OUTS, // Input/output sum mismatch DAP_LEDGER_TX_CHECK_NOT_ENOUGH_FEE, // Insufficient transaction fee } dap_ledger_check_error_t; ``` ### Structures #### dap_ledger_t Network ledger structure for distributed transaction management and balance tracking. ```c typedef struct dap_ledger { dap_chain_net_t *net; // Associated network reference void *_internal; // Internal ledger implementation } dap_ledger_t; ``` **Fields:** - `net` - Pointer to the associated network this ledger belongs to - `_internal` - Opaque pointer to internal ledger implementation and state data ### Functions #### Ledger Management Functions #### `dap_ledger_calc_balance()` Calculate balance for an address. ```c uint256_t dap_ledger_calc_balance(dap_ledger_t *a_ledger, const dap_chain_addr_t *a_addr, const char *a_token_ticker); ``` **Parameters:** - `a_ledger` (dap_ledger_t*) - Ledger to query - `a_addr` (const dap_chain_addr_t*) - Address to check - `a_token_ticker` (const char*) - Token ticker symbol **Returns:** - `uint256_t` - Current balance - `0` - No balance or error **Error Conditions:** - Returns 0 if address is invalid - Returns 0 if token doesn't exist **Description:** Calculates the current balance of a specific token for an address. #### `dap_ledger_init()` Initialize the ledger subsystem. ```c int dap_ledger_init(); ``` **Returns:** - `0` - Initialization successful - `negative value` - Initialization failed **Description:** Initializes the ledger subsystem and prepares it for operation. #### `dap_ledger_deinit()` Deinitialize the ledger subsystem. ```c void dap_ledger_deinit(); ``` **Description:** Cleans up ledger subsystem resources and shuts it down. #### `dap_ledger_create()` Create a new ledger for the network. ```c dap_ledger_t *dap_ledger_create(dap_chain_net_t *a_net, uint16_t a_flags); ``` **Parameters:** - `a_net` (dap_chain_net_t*) - Associated network - `a_flags` (uint16_t) - Ledger configuration flags **Returns:** - `ledger pointer` - Created ledger structure - `NULL` - Creation failed **Error Conditions:** - Returns NULL if network is NULL - Returns NULL if memory allocation fails **Description:** Creates a new ledger instance for transaction management in the network. #### `dap_ledger_handle_free()` Free ledger handle and resources. ```c void dap_ledger_handle_free(dap_ledger_t *a_ledger); ``` **Parameters:** - `a_ledger` (dap_ledger_t*) - Ledger to free **Description:** Frees the ledger handle and all associated resources. #### `dap_ledger_set_local_cell_id()` Set local cell ID for ledger operations. ```c void dap_ledger_set_local_cell_id(dap_ledger_t *a_ledger, dap_chain_cell_id_t a_local_cell_id); ``` **Parameters:** - `a_ledger` (dap_ledger_t*) - Ledger to configure - `a_local_cell_id` (dap_chain_cell_id_t) - Local cell identifier **Description:** Sets the local cell identifier for ledger operations. #### `dap_ledger_tx_add()` Add transaction to ledger. ```c int dap_ledger_tx_add(dap_ledger_t *a_ledger, dap_chain_datum_tx_t *a_tx, dap_hash_fast_t *a_tx_hash, bool a_from_threshold, dap_ledger_datum_iter_data_t *a_datum_index_data); ``` **Parameters:** - `a_ledger` (dap_ledger_t*) - Target ledger - `a_tx` (dap_chain_datum_tx_t*) - Transaction to add - `a_tx_hash` (dap_hash_fast_t*) - Transaction hash - `a_from_threshold` (bool) - Whether transaction is from threshold - `a_datum_index_data` (dap_ledger_datum_iter_data_t*) - Datum index data **Returns:** - `0` - Transaction added successfully - `negative value` - Add failed **Description:** Adds a transaction to the ledger with validation and indexing. #### `dap_ledger_tx_load()` Load transaction into ledger. ```c int dap_ledger_tx_load(dap_ledger_t *a_ledger, dap_chain_datum_tx_t *a_tx, dap_chain_hash_fast_t *a_tx_hash, dap_ledger_datum_iter_data_t *a_datum_index_data); ``` **Parameters:** - `a_ledger` (dap_ledger_t*) - Target ledger - `a_tx` (dap_chain_datum_tx_t*) - Transaction to load - `a_tx_hash` (dap_chain_hash_fast_t*) - Transaction hash - `a_datum_index_data` (dap_ledger_datum_iter_data_t*) - Datum index data **Returns:** - `0` - Transaction loaded successfully - `negative value` - Load failed **Description:** Loads a transaction into the ledger without validation. #### `dap_ledger_tx_remove()` Remove transaction from ledger. ```c int dap_ledger_tx_remove(dap_ledger_t *a_ledger, dap_chain_datum_tx_t *a_tx, dap_hash_fast_t *a_tx_hash); ``` **Parameters:** - `a_ledger` (dap_ledger_t*) - Target ledger - `a_tx` (dap_chain_datum_tx_t*) - Transaction to remove - `a_tx_hash` (dap_hash_fast_t*) - Transaction hash **Returns:** - `0` - Transaction removed successfully - `negative value` - Remove failed **Description:** Removes a transaction from the ledger. #### `dap_ledger_tx_add_check()` Check and add transaction to ledger. ```c int dap_ledger_tx_add_check(dap_ledger_t *a_ledger, dap_chain_datum_tx_t *a_tx, size_t a_datum_size, dap_hash_fast_t *a_datum_hash); ``` **Parameters:** - `a_ledger` (dap_ledger_t*) - Target ledger - `a_tx` (dap_chain_datum_tx_t*) - Transaction to check and add - `a_datum_size` (size_t) - Size of transaction datum - `a_datum_hash` (dap_hash_fast_t*) - Datum hash **Returns:** - `0` - Transaction checked and added successfully - `negative value` - Check or add failed **Description:** Validates and adds a transaction to the ledger. #### `dap_ledger_token_add()` Add token to ledger. ```c int dap_ledger_token_add(dap_ledger_t *a_ledger, byte_t *a_token, size_t a_token_size); ``` **Parameters:** - `a_ledger` (dap_ledger_t*) - Target ledger - `a_token` (byte_t*) - Token data - `a_token_size` (size_t) - Size of token data **Returns:** - `0` - Token added successfully - `negative value` - Add failed **Description:** Adds a token definition to the ledger. #### `dap_ledger_token_load()` Load token into ledger. ```c int dap_ledger_token_load(dap_ledger_t *a_ledger, byte_t *a_token, size_t a_token_size); ``` **Parameters:** - `a_ledger` (dap_ledger_t*) - Target ledger - `a_token` (byte_t*) - Token data - `a_token_size` (size_t) - Size of token data **Returns:** - `0` - Token loaded successfully - `negative value` - Load failed **Description:** Loads a token definition into the ledger without validation. #### `dap_ledger_token_add_check()` Check and add token to ledger. ```c int dap_ledger_token_add_check(dap_ledger_t *a_ledger, byte_t *a_token, size_t a_token_size); ``` **Parameters:** - `a_ledger` (dap_ledger_t*) - Target ledger - `a_token` (byte_t*) - Token data - `a_token_size` (size_t) - Size of token data **Returns:** - `0` - Token checked and added successfully - `negative value` - Check or add failed **Description:** Validates and adds a token definition to the ledger. #### `dap_ledger_token_get_auth_signs_valid()` Get number of valid authorization signatures for token. ```c size_t dap_ledger_token_get_auth_signs_valid(dap_ledger_t *a_ledger, const char *a_token_ticker); ``` **Parameters:** - `a_ledger` (dap_ledger_t*) - Target ledger - `a_token_ticker` (const char*) - Token ticker symbol **Returns:** - `size_t` - Number of valid authorization signatures **Description:** Returns the number of valid authorization signatures for a token. #### `dap_ledger_token_get_auth_signs_total()` Get total number of authorization signatures for token. ```c size_t dap_ledger_token_get_auth_signs_total(dap_ledger_t *a_ledger, const char *a_token_ticker); ``` **Parameters:** - `a_ledger` (dap_ledger_t*) - Target ledger - `a_token_ticker` (const char*) - Token ticker symbol **Returns:** - `size_t` - Total number of authorization signatures **Description:** Returns the total number of authorization signatures for a token. #### `dap_ledger_token_get_emission_rate()` Get emission rate for token. ```c uint256_t dap_ledger_token_get_emission_rate(dap_ledger_t *a_ledger, const char *a_token_ticker); ``` **Parameters:** - `a_ledger` (dap_ledger_t*) - Target ledger - `a_token_ticker` (const char*) - Token ticker symbol **Returns:** - `uint256_t` - Emission rate for the token **Description:** Returns the emission rate for a specific token. #### `dap_ledger_token_emission_add()` Add token emission to ledger. ```c int dap_ledger_token_emission_add(dap_ledger_t *a_ledger, byte_t *a_token_emission, size_t a_token_emission_size, dap_hash_fast_t *a_emission_hash); ``` **Parameters:** - `a_ledger` (dap_ledger_t*) - Target ledger - `a_token_emission` (byte_t*) - Token emission data - `a_token_emission_size` (size_t) - Size of emission data - `a_emission_hash` (dap_hash_fast_t*) - Emission hash **Returns:** - `0` - Emission added successfully - `negative value` - Add failed **Description:** Adds a token emission to the ledger. #### `dap_ledger_token_emission_load()` Load token emission into ledger. ```c int dap_ledger_token_emission_load(dap_ledger_t *a_ledger, byte_t *a_token_emission, size_t a_token_emission_size, dap_hash_fast_t *a_token_emission_hash); ``` **Parameters:** - `a_ledger` (dap_ledger_t*) - Target ledger - `a_token_emission` (byte_t*) - Token emission data - `a_token_emission_size` (size_t) - Size of emission data - `a_token_emission_hash` (dap_hash_fast_t*) - Token emission hash **Returns:** - `0` - Emission loaded successfully - `negative value` - Load failed **Description:** Loads a token emission into the ledger without validation. #### `dap_ledger_token_emission_add_check()` Check and add token emission to ledger. ```c int dap_ledger_token_emission_add_check(dap_ledger_t *a_ledger, byte_t *a_token_emission, size_t a_token_emission_size, dap_chain_hash_fast_t *a_emission_hash); ``` **Parameters:** - `a_ledger` (dap_ledger_t*) - Target ledger - `a_token_emission` (byte_t*) - Token emission data - `a_token_emission_size` (size_t) - Size of emission data - `a_emission_hash` (dap_chain_hash_fast_t*) - Emission hash **Returns:** - `0` - Emission checked and added successfully - `negative value` - Check or add failed **Description:** Validates and adds a token emission to the ledger. #### `dap_ledger_emission_for_stake_lock_item_add()` Add emission for stake lock item. ```c int dap_ledger_emission_for_stake_lock_item_add(dap_ledger_t *a_ledger, const dap_chain_hash_fast_t *a_tx_hash); ``` **Parameters:** - `a_ledger` (dap_ledger_t*) - Target ledger - `a_tx_hash` (const dap_chain_hash_fast_t*) - Transaction hash **Returns:** - `0` - Emission added successfully - `negative value` - Add failed **Description:** Adds an emission for a stake lock item to the ledger. #### `dap_ledger_tx_poa_signed()` Check if transaction is PoA signed. ```c bool dap_ledger_tx_poa_signed(dap_ledger_t *a_ledger, dap_chain_datum_tx_t *a_tx); ``` **Parameters:** - `a_ledger` (dap_ledger_t*) - Target ledger - `a_tx` (dap_chain_datum_tx_t*) - Transaction to check **Returns:** - `true` - Transaction is PoA signed - `false` - Transaction is not PoA signed **Description:** Checks if a transaction has Proof of Authority signatures. #### `dap_ledger_deduct_tx_tag()` Deduct transaction tag from ledger. ```c bool dap_ledger_deduct_tx_tag(dap_ledger_t *a_ledger, dap_chain_datum_tx_t *a_tx, char **a_service_name, dap_chain_net_srv_uid_t *uid, dap_chain_tx_tag_action_type_t *action); ``` **Parameters:** - `a_ledger` (dap_ledger_t*) - Target ledger - `a_tx` (dap_chain_datum_tx_t*) - Transaction to process - `a_service_name` (char**) - Output service name - `uid` (dap_chain_net_srv_uid_t*) - Output service UID - `action` (dap_chain_tx_tag_action_type_t*) - Output action type **Returns:** - `true` - Tag deducted successfully - `false` - Deduction failed **Description:** Deducts transaction tags and returns service information. #### `dap_ledger_tx_action_str_to_action_t()` Convert action string to action type. ```c dap_chain_tx_tag_action_type_t dap_ledger_tx_action_str_to_action_t(const char *a_str); ``` **Parameters:** - `a_str` (const char*) - Action string **Returns:** - `dap_chain_tx_tag_action_type_t` - Action type **Description:** Converts a string representation of an action to its enum type. #### `dap_ledger_service_add()` Add service to ledger. ```c int dap_ledger_service_add(dap_chain_net_srv_uid_t a_uid, char *tag_str, dap_ledger_tag_check_callback_t a_callback); ``` **Parameters:** - `a_uid` (dap_chain_net_srv_uid_t) - Service UID - `tag_str` (char*) - Tag string - `a_callback` (dap_ledger_tag_check_callback_t) - Tag check callback **Returns:** - `0` - Service added successfully - `negative value` - Add failed **Description:** Adds a service with tag checking callback to the ledger. #### `dap_ledger_tx_calculate_main_ticker_()` Calculate main ticker for transaction. ```c dap_chain_token_ticker_str_t dap_ledger_tx_calculate_main_ticker_(dap_ledger_t *a_ledger, dap_chain_datum_tx_t *a_tx, int *a_ledger_rc); ``` **Parameters:** - `a_ledger` (dap_ledger_t*) - Target ledger - `a_tx` (dap_chain_datum_tx_t*) - Transaction to analyze - `a_ledger_rc` (int*) - Output ledger return code **Returns:** - `dap_chain_token_ticker_str_t` - Main ticker for transaction **Description:** Calculates the main token ticker for a transaction. #### `dap_ledger_purge()` Purge ledger data. ```c void dap_ledger_purge(dap_ledger_t *a_ledger, bool a_preserve_db); ``` **Parameters:** - `a_ledger` (dap_ledger_t*) - Target ledger - `a_preserve_db` (bool) - Whether to preserve database **Description:** Purges ledger data, optionally preserving the database structure. #### `dap_ledger_count()` Get total count of ledger items. ```c unsigned dap_ledger_count(dap_ledger_t *a_ledger); ``` **Parameters:** - `a_ledger` (dap_ledger_t*) - Target ledger **Returns:** - `unsigned` - Total count of ledger items **Description:** Returns the total count of items in the ledger. #### `dap_ledger_count_from_to()` Get count of ledger items in time range. ```c uint64_t dap_ledger_count_from_to(dap_ledger_t *a_ledger, dap_nanotime_t a_ts_from, dap_nanotime_t a_ts_to); ``` **Parameters:** - `a_ledger` (dap_ledger_t*) - Target ledger - `a_ts_from` (dap_nanotime_t) - Start timestamp - `a_ts_to` (dap_nanotime_t) - End timestamp **Returns:** - `uint64_t` - Count of items in time range **Description:** Returns the count of ledger items within a specified time range. #### `dap_ledger_tx_hash_is_used_out_item()` Check if transaction hash is used as output item. ```c bool dap_ledger_tx_hash_is_used_out_item(dap_ledger_t *a_ledger, dap_chain_hash_fast_t *a_tx_hash, int a_idx_out, dap_hash_fast_t *a_out_spender); ``` **Parameters:** - `a_ledger` (dap_ledger_t*) - Target ledger - `a_tx_hash` (dap_chain_hash_fast_t*) - Transaction hash - `a_idx_out` (int) - Output index - `a_out_spender` (dap_hash_fast_t*) - Output spender hash **Returns:** - `true` - Transaction hash is used as output - `false` - Transaction hash is not used **Description:** Checks if a transaction hash is used as an output item. #### `dap_ledger_is_used_reward()` Check if reward is used. ```c bool dap_ledger_is_used_reward(dap_ledger_t *a_ledger, dap_hash_fast_t *a_block_hash, dap_hash_fast_t *a_sign_pkey_hash); ``` **Parameters:** - `a_ledger` (dap_ledger_t*) - Target ledger - `a_block_hash` (dap_hash_fast_t*) - Block hash - `a_sign_pkey_hash` (dap_hash_fast_t*) - Signing public key hash **Returns:** - `true` - Reward is used - `false` - Reward is not used **Description:** Checks if a reward has been used. #### `dap_ledger_get_final_chain_tx_hash()` Get final chain transaction hash. ```c dap_hash_fast_t dap_ledger_get_final_chain_tx_hash(dap_ledger_t *a_ledger, dap_chain_tx_item_type_t a_cond_type, dap_chain_hash_fast_t *a_tx_hash, bool a_unspent_only); ``` **Parameters:** - `a_ledger` (dap_ledger_t*) - Target ledger - `a_cond_type` (dap_chain_tx_item_type_t) - Condition type - `a_tx_hash` (dap_chain_hash_fast_t*) - Transaction hash - `a_unspent_only` (bool) - Only unspent transactions **Returns:** - `dap_hash_fast_t` - Final chain transaction hash **Description:** Returns the final chain transaction hash for a condition type. #### `dap_ledger_get_first_chain_tx_hash()` Get first chain transaction hash. ```c dap_hash_fast_t dap_ledger_get_first_chain_tx_hash(dap_ledger_t *a_ledger, dap_chain_datum_tx_t *a_tx, dap_chain_tx_out_cond_subtype_t a_cond_type); ``` **Parameters:** - `a_ledger` (dap_ledger_t*) - Target ledger - `a_tx` (dap_chain_datum_tx_t*) - Transaction - `a_cond_type` (dap_chain_tx_out_cond_subtype_t) - Condition subtype **Returns:** - `dap_hash_fast_t` - First chain transaction hash **Description:** Returns the first chain transaction hash for a condition subtype. #### `dap_ledger_tx_check_recipient()` Check transaction recipient. ```c bool dap_ledger_tx_check_recipient(dap_ledger_t* a_ledger, dap_chain_hash_fast_t* a_tx_prev_hash, dap_chain_addr_t *a_addr); ``` **Parameters:** - `a_ledger` (dap_ledger_t*) - Target ledger - `a_tx_prev_hash` (dap_chain_hash_fast_t*) - Previous transaction hash - `a_addr` (dap_chain_addr_t*) - Address to check **Returns:** - `true` - Address is valid recipient - `false` - Address is not valid recipient **Description:** Checks if an address is a valid recipient for a transaction. #### `dap_ledger_check_condition_owner()` Check condition owner. ```c bool dap_ledger_check_condition_owner(dap_ledger_t *a_ledger, dap_hash_fast_t *a_tx_hash, dap_chain_tx_out_cond_subtype_t a_cond_subtype, int a_out_idx, dap_sign_t *a_owner_sign); ``` **Parameters:** - `a_ledger` (dap_ledger_t*) - Target ledger - `a_tx_hash` (dap_hash_fast_t*) - Transaction hash - `a_cond_subtype` (dap_chain_tx_out_cond_subtype_t) - Condition subtype - `a_out_idx` (int) - Output index - `a_owner_sign` (dap_sign_t*) - Owner signature **Returns:** - `true` - Owner check passed - `false` - Owner check failed **Description:** Checks if a signature is valid for a condition owner. #### `dap_chain_ledger_voting_verificator_add()` Add voting verificator to ledger. ```c int dap_chain_ledger_voting_verificator_add(dap_chain_ledger_voting_callback_t a_callback, dap_chain_ledger_voting_delete_callback_t a_callback_delete); ``` **Parameters:** - `a_callback` (dap_chain_ledger_voting_callback_t) - Voting callback - `a_callback_delete` (dap_chain_ledger_voting_delete_callback_t) - Delete callback **Returns:** - `0` - Verificator added successfully - `negative value` - Add failed **Description:** Adds a voting verificator with callbacks to the ledger. #### `dap_ledger_datum_iter_delete()` Delete datum iterator. ```c void dap_ledger_datum_iter_delete(dap_ledger_datum_iter_t *a_iter); ``` **Parameters:** - `a_iter` (dap_ledger_datum_iter_t*) - Iterator to delete **Description:** Deletes a datum iterator and frees associated resources. #### `dap_ledger_tx_add_notify()` Add transaction add notification callback. ```c void dap_ledger_tx_add_notify(dap_ledger_t *a_ledger, dap_ledger_tx_add_notify_t a_callback, void *a_arg); ``` **Parameters:** - `a_ledger` (dap_ledger_t*) - Target ledger - `a_callback` (dap_ledger_tx_add_notify_t) - Notification callback - `a_arg` (void*) - Callback argument **Description:** Adds a callback to be notified when transactions are added to the ledger. #### `dap_ledger_bridged_tx_notify_add()` Add bridged transaction notification callback. ```c void dap_ledger_bridged_tx_notify_add(dap_ledger_t *a_ledger, dap_ledger_bridged_tx_notify_t a_callback, void *a_arg); ``` **Parameters:** - `a_ledger` (dap_ledger_t*) - Target ledger - `a_callback` (dap_ledger_bridged_tx_notify_t) - Notification callback - `a_arg` (void*) - Callback argument **Description:** Adds a callback to be notified when bridged transactions are processed. #### `dap_ledger_datum_is_blacklisted()` Check if datum is blacklisted. ```c bool dap_ledger_datum_is_blacklisted(dap_ledger_t *a_ledger, dap_hash_fast_t a_hash); ``` **Parameters:** - `a_ledger` (dap_ledger_t*) - Target ledger - `a_hash` (dap_hash_fast_t) - Datum hash **Returns:** - `true` - Datum is blacklisted - `false` - Datum is not blacklisted **Description:** Checks if a datum hash is in the blacklist. #### `dap_ledger_cache_enabled()` Check if ledger cache is enabled. ```c bool dap_ledger_cache_enabled(dap_ledger_t *a_ledger); ``` **Parameters:** - `a_ledger` (dap_ledger_t*) - Target ledger **Returns:** - `true` - Cache is enabled - `false` - Cache is disabled **Description:** Returns whether the ledger cache is enabled. #### `dap_ledger_set_cache_tx_check_callback()` Set cache transaction check callback. ```c void dap_ledger_set_cache_tx_check_callback(dap_ledger_t *a_ledger, dap_ledger_cache_tx_check_callback_t a_callback); ``` **Parameters:** - `a_ledger` (dap_ledger_t*) - Target ledger - `a_callback` (dap_ledger_cache_tx_check_callback_t) - Cache check callback **Description:** Sets a callback for cache transaction checking. #### `dap_ledger_load_end()` Signal end of ledger loading. ```c void dap_ledger_load_end(dap_ledger_t *a_ledger); ``` **Parameters:** - `a_ledger` (dap_ledger_t*) - Target ledger **Description:** Signals the end of ledger loading process. #### `dap_ledger_get_blockchain_time()` Get blockchain time from ledger. ```c dap_time_t dap_ledger_get_blockchain_time(dap_ledger_t *a_ledger); ``` **Parameters:** - `a_ledger` (dap_ledger_t*) - Target ledger **Returns:** - `dap_time_t` - Current blockchain time **Description:** Returns the current blockchain time from the ledger. --- ## Transaction Processing *Based on: `dap_chain_net_tx.h`, `dap_chain_net_tx.c`* ### Overview Transaction processing infrastructure providing transaction validation, routing, fee calculation, and network-wide transaction coordination. ### Document Structure - [[#Overview|Overview]] - [[#Enumerations|Enumerations]] - [[#s_com_tx_create_json_err_t|s_com_tx_create_json_err_t - JSON transaction creation error codes]] - [[#dap_chain_net_tx_search_type_t|dap_chain_net_tx_search_type_t - Transaction search types]] - [[#Structures|Structures]] - [[#dap_chain_datum_tx_spends_item_t|dap_chain_datum_tx_spends_item_t - Transaction spending item]] - [[#dap_chain_datum_tx_spends_items_t|dap_chain_datum_tx_spends_items_t - Transaction spending items collection]] - [[#dap_chain_datum_tx_cond_list_item_t|dap_chain_datum_tx_cond_list_item_t - Conditional transaction list item]] - [[#Functions|Functions]] - [[#Transaction Processing Functions|Transaction Processing Functions]] ### Enumerations #### s_com_tx_create_json_err_t Error codes for JSON transaction creation operations. ```c typedef enum s_com_tx_create_json_err { DAP_CHAIN_NET_TX_CREATE_JSON_OK = 0, // Operation successful DAP_CHAIN_NET_TX_CREATE_JSON_REQUIRE_PARAMETER_JSON = DAP_JSON_RPC_ERR_CODE_METHOD_ERR_START, // JSON parameter required DAP_CHAIN_NET_TX_CREATE_JSON_CAN_NOT_OPEN_JSON_FILE, // Cannot open JSON file DAP_CHAIN_NET_TX_CREATE_JSON_WRONG_JSON_FORMAT, // Wrong JSON format DAP_CHAIN_NET_TX_CREATE_JSON_REQUIRE_PARAMETER_NET, // Network parameter required DAP_CHAIN_NET_TX_CREATE_JSON_NOT_FOUNT_NET_BY_NAME, // Network not found by name DAP_CHAIN_NET_TX_CREATE_JSON_NOT_FOUNT_CHAIN_BY_NAME, // Chain not found by name DAP_CHAIN_NET_TX_CREATE_JSON_NOT_FOUNT_ARRAY_ITEMS, // Array items not found DAP_CHAIN_NET_TX_CREATE_JSON_INVALID_ITEMS, // Invalid items DAP_CHAIN_NET_TX_CREATE_JSON_CAN_NOT_ADD_TRANSACTION_TO_MEMPOOL, // Cannot add transaction to mempool DAP_CHAIN_NET_TX_CREATE_JSON_WRONG_ARGUMENTS // Wrong arguments provided } s_com_tx_create_json_err_t; ``` #### dap_chain_net_tx_search_type_t Transaction search types for different search scopes. ```c typedef enum dap_chain_net_tx_search_type { TX_SEARCH_TYPE_LOCAL, // Search local, in memory, possible load from drive TX_SEARCH_TYPE_CELL, // Request to network if not full node, search inside shard TX_SEARCH_TYPE_CELL_UNSPENT, // Request for unspent txs in cell TX_SEARCH_TYPE_NET, // Search in whole network, request from other cells if needed TX_SEARCH_TYPE_NET_UNSPENT, // Search in whole network but only unspent TX_SEARCH_TYPE_CELL_SPENT, // Request for spent txs in cell TX_SEARCH_TYPE_BLOCKCHAIN // Search in blockchain } dap_chain_net_tx_search_type_t; ``` ### Structures #### dap_chain_datum_tx_spends_item_t Individual transaction spending item for tracking transaction relationships. ```c typedef struct dap_chain_datum_tx_spends_item { dap_chain_datum_tx_t *tx; // Transaction pointer dap_hash_fast_t tx_hash; // Transaction hash dap_chain_tx_out_cond_t *out_cond; // Output condition dap_chain_tx_in_cond_t *in_cond; // Input condition dap_chain_datum_tx_t *tx_next; // Next transaction in chain UT_hash_handle hh; // Hash table handle } dap_chain_datum_tx_spends_item_t; ``` **Fields:** - `tx` - Pointer to the transaction data structure - `tx_hash` - Hash of the transaction for identification - `out_cond` - Output condition for conditional transactions - `in_cond` - Input condition for conditional transactions - `tx_next` - Pointer to the next transaction in spending chain - `hh` - Hash table handle for efficient lookup #### dap_chain_datum_tx_spends_items_t Collection of transaction spending items for input/output tracking. ```c typedef struct dap_chain_datum_tx_spends_items { dap_chain_datum_tx_spends_item_t *tx_outs; // Transaction outputs dap_chain_datum_tx_spends_item_t *tx_ins; // Transaction inputs } dap_chain_datum_tx_spends_items_t; ``` **Fields:** - `tx_outs` - Hash table of transaction outputs being spent - `tx_ins` - Hash table of transaction inputs being consumed #### dap_chain_datum_tx_cond_list_item_t Conditional transaction list item for managing conditional transactions. ```c typedef struct dap_chain_datum_tx_cond_list_item { dap_hash_fast_t hash; // Transaction hash dap_chain_datum_tx_t *tx; // Transaction pointer } dap_chain_datum_tx_cond_list_item_t; ``` **Fields:** - `hash` - Hash of the conditional transaction - `tx` - Pointer to the conditional transaction data ### Functions #### Transaction Processing Functions #### `dap_chain_net_verify_datum_for_add()` Verify datum before adding to chain. ```c int dap_chain_net_verify_datum_for_add(dap_chain_t *a_chain, dap_chain_datum_t *a_datum, dap_hash_fast_t *a_datum_hash); ``` **Parameters:** - `a_chain` (dap_chain_t*) - Target chain - `a_datum` (dap_chain_datum_t*) - Datum to verify - `a_datum_hash` (dap_hash_fast_t*) - Datum hash **Returns:** - `0` - Verification successful - `error code` - Verification failed **Error Conditions:** - Returns error if datum is invalid - Returns error if verification fails **Description:** Verifies a datum before adding it to the blockchain. --- ## Cross-Chain Operations *Based on: `dap_chain_net_anchor.h`, `dap_chain_net_anchor.c`, `dap_chain_net_decree.h`, `dap_chain_net_decree.c`* ### Overview Cross-chain operations provide interoperability between different blockchain networks through anchoring mechanisms and decree management. This includes anchor creation for cross-chain verification, decree processing for network governance, and bridge operations for asset transfers. ### Document Structure - [[#Overview|Overview]] - [[#Decree Management|Decree Management]] - Network governance and decree processing - [[#Anchor Operations|Anchor Operations]] - Cross-chain verification and anchoring --- ## Decree Management *Based on: `dap_chain_net_decree.h`, `dap_chain_net_decree.c`* ### Overview Decree management provides network governance functionality through decree processing, verification, and application. Decrees are network-level governance decisions that can modify network parameters, add/remove validators, or implement policy changes. ### Structures #### dap_chain_net_decree_t Network decree structure for governance operations. ```c typedef struct dap_chain_net_decree { dap_list_t *pkeys; // List of public keys for decree signing uint16_t num_of_owners; // Total number of decree owners uint16_t min_num_of_owners; // Minimum required owners for decree approval } dap_chain_net_decree_t; ``` **Fields:** - `pkeys` - List of public keys authorized to sign decrees - `num_of_owners` - Total number of decree owners/validators - `min_num_of_owners` - Minimum number of signatures required for decree approval ### Functions #### `dap_chain_net_decree_init()` Initialize decree management for a network. ```c int dap_chain_net_decree_init(dap_chain_net_t *a_net); ``` **Parameters:** - `a_net` (dap_chain_net_t*) - Network to initialize decree management for **Returns:** - `0` - Success - `negative value` - Error code **Error Conditions:** - Returns non-zero if decree initialization fails - Returns non-zero if network is invalid **Description:** Initializes decree management system for the specified network, setting up data structures and validation mechanisms. #### `dap_chain_net_decree_deinit()` Deinitialize decree management for a network. ```c int dap_chain_net_decree_deinit(dap_chain_net_t *a_net); ``` **Parameters:** - `a_net` (dap_chain_net_t*) - Network to deinitialize decree management for **Returns:** - `0` - Success - `negative value` - Error code **Error Conditions:** - Returns non-zero if decree deinitialization fails - Returns non-zero if network is invalid **Description:** Cleans up decree management system for the specified network, freeing resources and removing decree data. #### `dap_chain_net_decree_purge()` Purge all decree data from a network. ```c void dap_chain_net_decree_purge(dap_chain_net_t *a_net); ``` **Parameters:** - `a_net` (dap_chain_net_t*) - Network to purge decree data from **Returns:** - `void` - No return value **Description:** Removes all decree data and resets decree management state for the specified network. #### `dap_chain_net_decree_apply()` Apply a decree to a blockchain chain. ```c int dap_chain_net_decree_apply(dap_hash_fast_t *a_decree_hash, dap_chain_datum_decree_t *a_decree, dap_chain_t *a_chain, bool a_anchored); ``` **Parameters:** - `a_decree_hash` (dap_hash_fast_t*) - Hash of the decree to apply - `a_decree` (dap_chain_datum_decree_t*) - Decree data to apply - `a_chain` (dap_chain_t*) - Target blockchain chain - `a_anchored` (bool) - Whether the decree is anchored in the blockchain **Returns:** - `0` - Success - `negative value` - Error code **Error Conditions:** - Returns non-zero if decree application fails - Returns non-zero if decree validation fails - Returns non-zero if chain is invalid **Description:** Applies a validated decree to the specified blockchain chain, executing the governance decision. #### `dap_chain_net_decree_verify()` Verify a decree's validity and signatures. ```c int dap_chain_net_decree_verify(dap_chain_net_t *a_net, dap_chain_datum_decree_t *a_decree, size_t a_data_size, dap_chain_hash_fast_t *a_decree_hash); ``` **Parameters:** - `a_net` (dap_chain_net_t*) - Network context for verification - `a_decree` (dap_chain_datum_decree_t*) - Decree to verify - `a_data_size` (size_t) - Size of decree data - `a_decree_hash` (dap_chain_hash_fast_t*) - Expected decree hash **Returns:** - `0` - Success (decree is valid) - `negative value` - Error code **Error Conditions:** - Returns non-zero if decree verification fails - Returns non-zero if signatures are invalid - Returns non-zero if decree format is invalid **Description:** Verifies the decree's cryptographic signatures and validates its format and content. #### `dap_chain_net_decree_load()` Load a decree from the blockchain. ```c int dap_chain_net_decree_load(dap_chain_datum_decree_t *a_decree, dap_chain_t *a_chain, dap_chain_hash_fast_t *a_decree_hash); ``` **Parameters:** - `a_decree` (dap_chain_datum_decree_t*) - Buffer to load decree into - `a_chain` (dap_chain_t*) - Blockchain chain to load from - `a_decree_hash` (dap_chain_hash_fast_t*) - Hash of decree to load **Returns:** - `0` - Success - `negative value` - Error code **Error Conditions:** - Returns non-zero if decree loading fails - Returns non-zero if decree not found - Returns non-zero if chain is invalid **Description:** Loads a decree from the specified blockchain chain using its hash. #### `dap_chain_net_decree_get_by_hash()` Retrieve a decree by its hash. ```c dap_chain_datum_decree_t *dap_chain_net_decree_get_by_hash(dap_chain_net_t *a_net, dap_hash_fast_t *a_hash, bool *is_applied); ``` **Parameters:** - `a_net` (dap_chain_net_t*) - Network context - `a_hash` (dap_hash_fast_t*) - Hash of decree to retrieve - `is_applied` (bool*) - Output parameter indicating if decree is applied **Returns:** - `decree pointer` - Found decree structure - `NULL` - Decree not found **Error Conditions:** - Returns NULL if hash is invalid - Returns NULL if decree not found in network **Description:** Retrieves a decree from the network's decree storage by its hash. #### `dap_chain_net_decree_reset_applied()` Reset the applied status of a decree. ```c int dap_chain_net_decree_reset_applied(dap_chain_net_t *a_net, dap_chain_hash_fast_t *a_decree_hash); ``` **Parameters:** - `a_net` (dap_chain_net_t*) - Network context - `a_decree_hash` (dap_chain_hash_fast_t*) - Hash of decree to reset **Returns:** - `0` - Success - `negative value` - Error code **Error Conditions:** - Returns non-zero if decree not found - Returns non-zero if reset operation fails **Description:** Resets the applied status of a decree, allowing it to be reapplied if needed. --- ## Anchor Operations *Based on: `dap_chain_net_anchor.h`, `dap_chain_net_anchor.c`* ### Overview Cross-chain verification and anchoring infrastructure providing secure and reliable communication between different networks. ### Document Structure - [[#Overview|Overview]] - [[#Functions|Functions]] - [[#Anchor Functions|Anchor Functions]] ### Functions #### Anchor Functions #### `dap_chain_net_anchor_create()` Create cross-chain anchor. ```c int dap_chain_net_anchor_create(dap_chain_net_t *a_net, dap_chain_hash_fast_t *a_block_hash, dap_chain_net_id_t a_target_net_id); ``` **Parameters:** - `a_net` (dap_chain_net_t*) - Source network - `a_block_hash` (dap_chain_hash_fast_t*) - Block hash to anchor - `a_target_net_id` (dap_chain_net_id_t) - Target network ID **Returns:** - `0` - Anchor created successfully - `negative value` - Creation failed **Description:** Creates a cross-chain anchor for interoperability. --- ## Network Services *Based on: `dap_chain_net_srv.h`, `dap_chain_net_srv.c`* ### Overview Network service infrastructure providing service discovery, ordering, session management, and distributed service coordination. ### Document Structure - [[#Overview|Overview]] - [[#Functions|Functions]] - [[#Service Management Functions|Service Management Functions]] ### Functions #### Service Management Functions #### `dap_chain_net_srv_order_create()` Create service order. ```c dap_chain_net_srv_order_t *dap_chain_net_srv_order_create(dap_chain_net_t *a_net, dap_chain_net_srv_uid_t a_srv_uid); ``` **Parameters:** - `a_net` (dap_chain_net_t*) - Network - `a_srv_uid` (dap_chain_net_srv_uid_t) - Service UID **Returns:** - `order pointer` - Created order - `NULL` - Creation failed **Description:** Creates a new service order in the network. --- ## Network Balancing *Based on: `dap_chain_net_balancer.h`, `dap_chain_net_balancer.c`* ### Overview Network load balancing infrastructure providing node selection, traffic distribution, and network optimization. ### Document Structure - [[#Overview|Overview]] - [[#Enumerations|Enumerations]] - [[#dap_balancer_type_t|dap_balancer_type_t - Balancer types]] - [[#Structures|Structures]] - [[#dap_chain_net_links_t|dap_chain_net_links_t - Network links information]] - [[#dap_balancer_link_request_t|dap_balancer_link_request_t - Link request structure]] - [[#Functions|Functions]] - [[#Balancing Functions|Balancing Functions]] ### Enumerations #### dap_balancer_type_t Types of network balancers available. ```c typedef enum dap_balancer_type { DAP_CHAIN_NET_BALANCER_TYPE_HTTP, // HTTP-based balancer DAP_CHAIN_NET_BALANCER_TYPE_DNS // DNS-based balancer } dap_balancer_type_t; ``` **Values:** - `DAP_CHAIN_NET_BALANCER_TYPE_HTTP` - Uses HTTP protocol for load balancing - `DAP_CHAIN_NET_BALANCER_TYPE_DNS` - Uses DNS protocol for load balancing ### Structures #### dap_chain_net_links_t Network links information structure for node connectivity. ```c typedef struct dap_chain_net_links { uint64_t count_node; // Number of nodes byte_t nodes_info[]; // Variable-length node information array } DAP_ALIGN_PACKED dap_chain_net_links_t; ``` **Fields:** - `count_node` - Total number of nodes in the network links - `nodes_info[]` - Variable-length array containing node information data #### dap_balancer_link_request_t Request structure for balancer link operations. ```c typedef struct dap_balancer_link_request { const char *host_addr; // Host address for connection uint16_t host_port; // Host port for connection dap_chain_net_t *net; // Target network dap_worker_t *worker; // Worker thread for processing uint16_t required_links_count; // Number of required links dap_balancer_request_info_t *request_info; // Request information dap_balancer_type_t type; // Balancer type } dap_balancer_link_request_t; ``` **Fields:** - `host_addr` - Host address string for the balancer connection - `host_port` - Port number for the balancer connection - `net` - Pointer to the target network for balancing - `worker` - Worker thread that will process the balancing request - `required_links_count` - Number of links required for the request - `request_info` - Additional request information and context - `type` - Type of balancer to use (HTTP or DNS) ### Functions #### Balancing Functions #### `dap_chain_net_balancer_get_best_node()` Get best node for connection. ```c dap_chain_node_info_t *dap_chain_net_balancer_get_best_node(dap_chain_net_t *a_net); ``` **Parameters:** - `a_net` (dap_chain_net_t*) - Network **Returns:** - `node info pointer` - Best available node - `NULL` - No suitable node found **Description:** Selects the best node for connection based on load balancing criteria. --- ## DNS Resolution *Based on: `dap_chain_node_dns_server.h`, `dap_chain_node_dns_server.c`, `dap_chain_node_dns_client.h`, `dap_chain_node_dns_client.c`* ### Overview DNS resolution infrastructure providing name resolution, node discovery, and distributed naming services. ### Document Structure - [[#Overview|Overview]] - [[#Enumerations|Enumerations]] - [[#dap_dns_query_type_t|dap_dns_query_type_t - DNS query types]] - [[#dap_dns_error_t|dap_dns_error_t - DNS error codes]] - [[#Structures|Structures]] - [[#dap_dns_message_flags_bits_t|dap_dns_message_flags_bits_t - DNS message flags]] - [[#dap_dns_message_flags_t|dap_dns_message_flags_t - DNS message flags union]] - [[#dap_dns_zone_hash_t|dap_dns_zone_hash_t - DNS zone hash table entry]] - [[#dap_dns_server_t|dap_dns_server_t - DNS server structure]] - [[#Functions|Functions]] - [[#DNS Functions|DNS Functions]] ### Enumerations #### dap_dns_query_type_t DNS query types for different kinds of DNS operations. ```c typedef enum _dap_dns_query_type_t { DNS_QUERY_TYPE_STANDARD, // Standard DNS query DNS_QUERY_TYPE_INVERSE, // Inverse DNS query DNS_QUERY_TYPE_STATUS // Status query } dap_dns_query_type_t; ``` **Values:** - `DNS_QUERY_TYPE_STANDARD` - Standard forward DNS lookup - `DNS_QUERY_TYPE_INVERSE` - Reverse DNS lookup (PTR records) - `DNS_QUERY_TYPE_STATUS` - DNS server status query #### dap_dns_error_t DNS error codes for DNS operations. ```c typedef enum _dap_dns_error_t { DNS_ERROR_NONE, // No error DNS_ERROR_FORMAT, // DNS message parsing error DNS_ERROR_FAILURE, // Internal server error DNS_ERROR_NAME, // Name does not exist (authoritative servers only) DNS_ERROR_NOT_SUPPORTED, // Query type not implemented DNS_ERROR_REFUSED // Operation refused } dap_dns_error_t; ``` **Values:** - `DNS_ERROR_NONE` - Operation completed successfully - `DNS_ERROR_FORMAT` - DNS message format error or parsing failure - `DNS_ERROR_FAILURE` - Internal server error occurred - `DNS_ERROR_NAME` - Requested name does not exist (authoritative servers) - `DNS_ERROR_NOT_SUPPORTED` - Query type not supported by server - `DNS_ERROR_REFUSED` - Server refused to process the request ### Structures #### dap_dns_message_flags_bits_t DNS message flags structure for detailed flag access. ```c typedef struct _dap_dns_message_flags_bits_t { int rcode : 4; // Response code (answer only) int z : 3; // Reserved, must be zero int ra : 1; // Recursion available (answer only) int rd : 1; // Recursion desired (copied to answer) int tc : 1; // Message truncated int aa : 1; // Authoritative answer (answer only) int opcode : 4; // Query type (copied to answer) int qr : 1; // Query/Response flag (0=query, 1=response) } dap_dns_message_flags_bits_t; ``` **Fields:** - `rcode` - Response code: 0=no error, 1=format error, 2=server failure, 3=name error, 4=not supported, 5=refused - `z` - Reserved field, must be zero - `ra` - Recursion available flag (set in responses) - `rd` - Recursion desired flag (set in queries, copied to responses) - `tc` - Truncation flag (message was truncated) - `aa` - Authoritative answer flag (set in authoritative responses) - `opcode` - Operation code: 0=standard, 1=inverse, 2=status, 3-15=reserved - `qr` - Query/Response flag: 0=query, 1=response #### dap_dns_message_flags_t DNS message flags union for easy access. ```c typedef union _dap_dns_message_flags_t { dap_dns_message_flags_bits_t flags; // Bitfield access int val; // Integer access } dap_dns_message_flags_t; ``` **Fields:** - `flags` - Bitfield structure for individual flag access - `val` - Integer representation for easy manipulation #### dap_dns_zone_hash_t DNS zone hash table entry for zone management. ```c typedef struct _dap_dns_zone_hash_t { char *zone; // Zone name dap_dns_zone_callback_t callback; // Zone callback function UT_hash_handle hh; // Hash table handle } dap_dns_zone_hash_t; ``` **Fields:** - `zone` - DNS zone name string - `callback` - Callback function for handling zone operations - `hh` - Hash table handle for efficient lookup #### dap_dns_server_t DNS server structure for managing DNS service. ```c typedef struct _dap_dns_server_t { dap_server_t *instance; // Server instance dap_dns_zone_hash_t *hash_table; // Zone hash table } dap_dns_server_t; ``` **Fields:** - `instance` - Underlying server instance for network operations - `hash_table` - Hash table containing registered DNS zones ### Functions #### DNS Functions #### `dap_chain_node_dns_server_init()` Initialize DNS server functionality. ```c int dap_chain_node_dns_server_init(); ``` **Returns:** - `0` - Success - `negative value` - Error code **Description:** Initializes the DNS server component for node name resolution. #### `dap_chain_node_dns_client_init()` Initialize DNS client functionality. ```c int dap_chain_node_dns_client_init(); ``` **Returns:** - `0` - Success - `negative value` - Error code **Description:** Initializes the DNS client component for resolving node names. --- ## Typical Examples ### Network Initialization and Management Example ```c #include <dap_chain_net.h> void network_management_example() { log_it(L_INFO, "=== Network Management Example ==="); // Step 1: Initialize network module int result = dap_chain_net_init(); if (result != 0) { log_it(L_ERROR, "✗ Failed to initialize network module: %d", result); return; } log_it(L_INFO, "✓ Network module initialized successfully"); // Step 2: Find network by name const char *network_name = "Backbone"; dap_chain_net_t *net = dap_chain_net_by_name(network_name); if (!net) { log_it(L_ERROR, "✗ Network '%s' not found", network_name); return; } log_it(L_INFO, "✓ Found network '%s' with ID: 0x%016llx", net->pub.name, net->pub.id.uint64); // Step 3: Check network state and transition to online dap_chain_net_state_t current_state = dap_chain_net_get_state(net); if (current_state != NET_STATE_ONLINE) { result = dap_chain_net_state_go_to(net, NET_STATE_ONLINE); if (result == 0) { log_it(L_INFO, "✓ Network transition to online initiated"); } else { log_it(L_ERROR, "✗ Failed to transition network: %d", result); } } log_it(L_INFO, "✓ Network management example completed"); } ``` ### Comprehensive Node and Ledger Operations Example ```c #include <dap_chain_node.h> #include <dap_chain_ledger.h> void comprehensive_operations_example() { log_it(L_INFO, "=== Comprehensive Operations Example ==="); // Step 1: Get network and components dap_chain_net_t *net = dap_chain_net_by_name("Backbone"); if (!net) { log_it(L_ERROR, "✗ Failed to get network"); return; } dap_ledger_t *ledger = net->pub.ledger; if (!ledger) { log_it(L_ERROR, "✗ Network ledger not available"); return; } // Step 2: Register node information dap_chain_node_info_t *node_info = DAP_NEW_Z_SIZE(dap_chain_node_info_t, sizeof(dap_chain_node_info_t) + 16); node_info->address.uint64 = 0x123456789ABCDEF0; node_info->cell_id.uint64 = 0x0001; strncpy(node_info->alias, "example_node", sizeof(node_info->alias) - 1); node_info->ext_port = 8079; node_info->ext_host_len = 15; strcpy(node_info->ext_host, "192.168.1.100"); int result = dap_chain_node_info_save(net, node_info); if (result == 0) { log_it(L_INFO, "✓ Node information saved successfully"); } else { log_it(L_ERROR, "✗ Failed to save node information: %d", result); } // Step 3: Check ledger balance dap_chain_addr_t test_addr = {0}; test_addr.data.addr_ver = 0x01; memset(test_addr.data.hash, 0xAB, sizeof(test_addr.data.hash)); const char *token_ticker = "CELL"; uint256_t balance = dap_ledger_calc_balance(ledger, &test_addr, token_ticker); if (!IS_ZERO_256(balance)) { char *balance_str = dap_chain_balance_to_coins(balance); log_it(L_INFO, "✓ Address balance: %s %s", balance_str, token_ticker); DAP_DELETE(balance_str); } else { log_it(L_INFO, "✓ Address has zero balance"); } // Step 4: Cleanup DAP_DELETE(node_info); log_it(L_INFO, "✓ Comprehensive operations example completed"); } ``` --- *See also: [[Modules/Module Chain|Module Chain]], [[Modules/Module Wallet|Module Wallet]], [[ETC/Development Guide|Development Guide]]*