Module Chain - Cellframe Wiki

## Overview Core blockchain logic and transaction processing providing the fundamental chain operations for the Cellframe SDK. This module implements the main blockchain infrastructure including chain management, cell organization, consensus interfaces, policy enforcement, and channel communications. *Based on: `dap_chain.h`, `dap_chain.c`, `dap_chain_block.h`, `dap_chain_block.c`, `dap_chain_block_cache.h`, `dap_chain_block_cache.c`, `dap_chain_cell.h`, `dap_chain_cell.c`, `dap_chain_cs.h`, `dap_chain_cs.c`, `dap_chain_gdb.h`, `dap_chain_gdb.c`, `dap_chain_tx.h`, `dap_chain_tx.c`* ## Common Core *Based on: `dap_chain.h`, `dap_chain.c`, `dap_chain_block.h`, `dap_chain_block.c`, `dap_chain_block_cache.h`, `dap_chain_block_cache.c`, `dap_chain_cell.h`, `dap_chain_cell.c`, `dap_chain_cs.h`, `dap_chain_cs.c`, `dap_chain_gdb.h`, `dap_chain_gdb.c`, `dap_chain_tx.h`, `dap_chain_tx.c`* ## Document Structure - [[#Overview|Overview]] - [[#Core Chain|Core Chain]] - Main chain structures and operations - [[#Overview|Overview]] - [[#Enumerations|Enumerations]] - [[#Structures|Structures]] - [[#Functions|Functions]] - [[#Chain Cell|Chain Cell]] - Cell management and storage - [[#Overview|Overview]] - [[#Structures|Structures]] - [[#Functions|Functions]] - [[#Chain Consensus|Chain Consensus]] - Consensus interface - [[#Chain Policy|Chain Policy]] - Policy management - [[#Chain Channels|Chain Channels]] - Channel operations - [[#Chain Transactions|Chain Transactions]] - Transaction processing --- ## Core Chain *Based on: `dap_chain.h` and `dap_chain.c`* ### Overview Main chain infrastructure providing core blockchain functionality including chain creation, atom management, iterator operations, callback systems, and synchronization management. **Key Responsibilities:** - Chain object lifecycle management (creation, deletion, configuration) - Atom (block) operations and verification - Chain iteration and data access patterns - Callback system for notifications and hooks - Chain synchronization state management - Datum processing and storage coordination - Thread-safe chain operations with read-write locks ### Document Structure - [[#Overview|Overview]] - [[#Enumerations|Enumerations]] - [[#dap_chain_atom_verify_res_t|dap_chain_atom_verify_res_t - Atom verification results]] - [[#dap_chain_iter_op_t|dap_chain_iter_op_t - Iterator operations]] - [[#dap_chain_type_t|dap_chain_type_t - Chain data types]] - [[#dap_chain_sync_state_t|dap_chain_sync_state_t - Chain synchronization states]] - [[#Structures|Structures]] - [[#dap_chain_atom_iter_t|dap_chain_atom_iter_t - Atom iterator structure]] - [[#dap_chain_datum_iter_t|dap_chain_datum_iter_t - Datum iterator structure]] - [[#dap_chain_t|dap_chain_t - Main chain structure]] - [[#dap_chain_atom_notifier_t|dap_chain_atom_notifier_t - Atom notification structure]] - [[#dap_chain_atom_confirmed_notifier_t|dap_chain_atom_confirmed_notifier_t - Atom confirmation notifier]] - [[#dap_chain_pvt_t|dap_chain_pvt_t - Chain private data structure]] - [[#Functions|Functions]] - [[#Chain Management|Chain Management]] - [[#Chain Operations|Chain Operations]] - [[#Chain Callbacks|Chain Callbacks]] - [[#Chain Utilities|Chain Utilities]] ### Enumerations #### dap_chain_atom_verify_res_t Atom verification result codes for consensus validation. ```c typedef enum dap_chain_atom_verify_res { ATOM_ACCEPT = 0, // Atom accepted and processed ATOM_PASS, // Atom skipped (not processed) ATOM_REJECT, // Atom rejected (invalid) ATOM_MOVE_TO_THRESHOLD, // Atom moved to threshold for later processing ATOM_FORK // Atom causes chain fork } dap_chain_atom_verify_res_t; ``` **Verification Results:** - `ATOM_ACCEPT` - Atom is valid and accepted into the chain - `ATOM_PASS` - Atom is skipped without processing (e.g., already exists) - `ATOM_REJECT` - Atom is invalid and rejected - `ATOM_MOVE_TO_THRESHOLD` - Atom moved to threshold pool for future processing - `ATOM_FORK` - Atom causes a chain fork condition #### dap_chain_iter_op_t Iterator operation types for chain traversal. ```c typedef enum dap_chain_iter_op { DAP_CHAIN_ITER_OP_FIRST, // Move to first element DAP_CHAIN_ITER_OP_LAST, // Move to last element DAP_CHAIN_ITER_OP_NEXT, // Move to next element DAP_CHAIN_ITER_OP_PREV // Move to previous element } dap_chain_iter_op_t; ``` #### dap_chain_type_t Chain datum types for different data categories. ```c typedef enum dap_chain_type { CHAIN_TYPE_INVALID = -1, // Invalid type CHAIN_TYPE_TOKEN = 1, // Token definitions CHAIN_TYPE_EMISSION = 2, // Token emissions CHAIN_TYPE_TX = 3, // Transactions CHAIN_TYPE_CA = 4, // Certificate authorities CHAIN_TYPE_SIGNER = 5, // Signing certificates CHAIN_TYPE_DECREE = 7, // Governance decrees CHAIN_TYPE_ANCHOR = 8, // Cross-chain anchors CHAIN_TYPE_MAX // Maximum type value } dap_chain_type_t; ``` #### dap_chain_sync_state_t Chain synchronization state machine values. ```c typedef enum dap_chain_sync_state { CHAIN_SYNC_STATE_SYNCED = -1, // Chain is fully synchronized CHAIN_SYNC_STATE_IDLE = 0, // No synchronization activity CHAIN_SYNC_STATE_WAITING = 1, // Waiting for sync packets CHAIN_SYNC_STATE_ERROR = 2 // Synchronization error occurred } dap_chain_sync_state_t; ``` ### Structures #### dap_chain_atom_iter_t Iterator structure for traversing chain atoms (blocks). ```c typedef struct dap_chain_atom_iter { dap_chain_t *chain; // Chain being iterated dap_chain_cell_id_t cell_id; // Current cell ID void *cur_item; // Current item pointer dap_chain_atom_ptr_t cur; // Current atom pointer size_t cur_size; // Current atom size dap_chain_hash_fast_t *cur_hash; // Current atom hash uint64_t cur_num; // Current atom number dap_time_t cur_ts; // Current atom timestamp } dap_chain_atom_iter_t; ``` **Fields:** - `chain` - Reference to the chain being iterated - `cell_id` - Cell identifier for the current position - `cur_item` - Generic pointer to current item - `cur` - Typed pointer to current atom - `cur_size` - Size of current atom in bytes - `cur_hash` - Hash of current atom - `cur_num` - Sequential number of current atom - `cur_ts` - Timestamp when atom was created #### dap_chain_datum_iter_t Iterator structure for traversing chain datums within atoms. ```c typedef struct dap_chain_datum_iter { dap_chain_t *chain; // Chain being iterated dap_chain_datum_t *cur; // Current datum pointer size_t cur_size; // Current datum size dap_chain_hash_fast_t *cur_hash; // Current datum hash dap_chain_hash_fast_t *cur_atom_hash; // Parent atom hash uint32_t action; // Current action type dap_chain_net_srv_uid_t uid; // Service UID filter int ret_code; // Return code char *token_ticker; // Token ticker filter void *cur_item; // Current item pointer } dap_chain_datum_iter_t; ``` **Fields:** - `chain` - Reference to the chain being iterated - `cur` - Current datum being processed - `cur_size` - Size of current datum - `cur_hash` - Hash of current datum - `cur_atom_hash` - Hash of atom containing current datum - `action` - Action type associated with datum - `uid` - Service UID for filtering - `ret_code` - Processing return code - `token_ticker` - Token ticker for filtering - `cur_item` - Generic item pointer #### dap_chain_t Main chain structure containing all chain state and operations. ```c typedef struct dap_chain { pthread_rwlock_t rwlock; // Read-write lock for thread safety dap_chain_id_t id; // Chain identifier dap_chain_net_id_t net_id; // Network identifier uint16_t load_priority; // Chain loading priority char *name; // Chain name char *net_name; // Network name bool is_datum_pool_proc; // Datum pool processing flag bool is_mapped; // Memory mapping flag atomic_int load_progress; // Loading progress indicator // Cell management dap_chain_cell_t *cells; // Nested cells hashtable dap_chain_cell_id_t active_cell_id; // Active cell identifier dap_chain_cell_id_t forking_cell_id; // Forking cell identifier // Datum type configuration uint16_t datum_types_count; // Number of allowed datum types dap_chain_type_t *datum_types; // Array of allowed datum types uint16_t default_datum_types_count; // Default datum types count dap_chain_type_t *default_datum_types; // Default datum types array uint16_t autoproc_datum_types_count; // Auto-processing types count uint16_t *autoproc_datum_types; // Auto-processing types array // Chain state uint64_t atom_num_last; // Last atom number dap_time_t blockchain_time; // Current blockchain time dap_chain_sync_state_t state; // Synchronization state // Authorization uint16_t authorized_nodes_count; // Number of authorized nodes dap_stream_node_addr_t *authorized_nodes_addrs; // Authorized node addresses // Linked list pointers struct dap_chain *next; // Next chain in list struct dap_chain *prev; // Previous chain in list pthread_rwlock_t cell_rwlock; // Cell-specific read-write lock // Callback functions for chain operations dap_chain_callback_new_cfg_t callback_created; dap_chain_callback_t callback_delete; dap_chain_callback_t callback_purge; dap_chain_callback_atom_t callback_atom_add; dap_chain_callback_atom_verify_t callback_atom_verify; dap_chain_callback_add_datums_t callback_add_datums; // Iterator callbacks dap_chain_callback_atom_iter_create_t callback_atom_iter_create; dap_chain_callback_atom_iter_get_t callback_atom_iter_get; dap_chain_callback_atom_iter_delete_t callback_atom_iter_delete; // Notification lists dap_list_t *atom_notifiers; // Atom notification callbacks dap_list_t *datum_notifiers; // Datum notification callbacks dap_list_t *datum_removed_notifiers; // Datum removal notifications dap_list_t *blockchain_timers; // Blockchain timer callbacks dap_list_t *atom_confirmed_notifiers; // Atom confirmation notifications dap_config_t *config; // Chain configuration void *_pvt; // Private data pointer void *_inheritor; // Inheritor object pointer } dap_chain_t; ``` **Key Fields:** - `rwlock` - Thread-safe access control for entire chain - `id`/`net_id` - Chain and network identification - `cells` - Hashtable of chain cells for data storage - `datum_types` - Configuration of allowed data types - `state` - Current synchronization state - Callback functions for extensible chain operations - Notification lists for event handling #### dap_chain_atom_notifier_t Notification structure for atom events. ```c typedef struct dap_chain_atom_notifier { dap_chain_callback_notify_t callback; // Notification callback function dap_proc_thread_t *proc_thread; // Processing thread void *arg; // Callback arguments } dap_chain_atom_notifier_t; ``` **Fields:** - `callback` - Function to call when atom events occur - `proc_thread` - Thread for processing notifications - `arg` - Arguments passed to callback function #### dap_chain_atom_confirmed_notifier_t Atom confirmation notifier for tracking confirmed blocks. ```c typedef struct dap_chain_atom_confirmed_notifier { uint64_t block_notify_cnt; // Number of blocks for confirmation dap_chain_callback_notify_t callback; // Callback function void *arg; // Callback argument } dap_chain_atom_confirmed_notifier_t; ``` **Fields:** - `block_notify_cnt` - Number of blocks required for confirmation notification - `callback` - Callback function to execute when atom is confirmed - `arg` - User-defined argument passed to callback function #### dap_chain_pvt_t Chain private data structure for internal implementation details. ```c typedef struct dap_chain_pvt { char *cs_name; // Consensus name char *file_storage_dir; // File storage directory path bool cs_started; // Consensus started flag bool need_reorder; // Reorder needed flag } dap_chain_pvt_t; ``` **Fields:** - `cs_name` - Name of the consensus mechanism being used - `file_storage_dir` - Directory path for file-based storage - `cs_started` - Flag indicating if consensus has been started - `need_reorder` - Flag indicating if chain reordering is needed ### Functions #### Chain Management ##### `dap_chain_init()` Initialize the chain subsystem. ```c int dap_chain_init(void); ``` **Returns:** - `0` - Initialization successful - `non-zero` - Initialization failed **Description:** Initializes global chain infrastructure and prepares the system for chain operations. ##### `dap_chain_deinit()` Deinitialize the chain subsystem. ```c void dap_chain_deinit(void); ``` **Description:** Cleans up global chain resources and shuts down the chain subsystem. ##### `dap_chain_create()` Create new chain instance. ```c dap_chain_t *dap_chain_create(const char *a_chain_net_name, const char *a_chain_name, dap_chain_net_id_t a_chain_net_id, dap_chain_id_t a_chain_id); ``` **Parameters:** - `a_chain_net_name` (`const char *`) - Network name - `a_chain_name` (`const char *`) - Chain name - `a_chain_net_id` (`dap_chain_net_id_t`) - Network identifier - `a_chain_id` (`dap_chain_id_t`) - Chain identifier **Returns:** - `dap_chain_t *` - Created chain structure - `NULL` - Creation failed **Error Conditions:** - Returns `NULL` if memory allocation fails or parameters are invalid ##### `dap_chain_delete()` Delete chain and free resources. ```c void dap_chain_delete(dap_chain_t *a_chain); ``` **Parameters:** - `a_chain` (`dap_chain_t *`) - Chain to delete **Description:** Frees all chain resources including cells, callbacks, and configuration. ##### `dap_chain_load_from_cfg()` Load chain from configuration. ```c dap_chain_t *dap_chain_load_from_cfg(const char *a_chain_net_name, dap_chain_net_id_t a_chain_net_id, dap_config_t *a_cfg); ``` **Parameters:** - `a_chain_net_name` (`const char *`) - Network name - `a_chain_net_id` (`dap_chain_net_id_t`) - Network identifier - `a_cfg` (`dap_config_t *`) - Configuration object **Returns:** - `dap_chain_t *` - Loaded chain - `NULL` - Loading failed #### Chain Operations ##### `dap_chain_find_by_id()` Find chain by identifier. ```c dap_chain_t *dap_chain_find_by_id(dap_chain_net_id_t a_chain_net_id, dap_chain_id_t a_chain_id); ``` **Parameters:** - `a_chain_net_id` (`dap_chain_net_id_t`) - Network identifier - `a_chain_id` (`dap_chain_id_t`) - Chain identifier **Returns:** - `dap_chain_t *` - Found chain - `NULL` - Chain not found ##### `dap_chain_load_all()` Load all chain data from storage. ```c int dap_chain_load_all(dap_chain_t *a_chain); ``` **Parameters:** - `a_chain` (`dap_chain_t *`) - Chain to load **Returns:** - `0` - Load successful - `non-zero` - Load failed ##### `dap_chain_save_all()` Save all chain data to storage. ```c int dap_chain_save_all(dap_chain_t *a_chain); ``` **Parameters:** - `a_chain` (`dap_chain_t *`) - Chain to save **Returns:** - `0` - Save successful - `non-zero` - Save failed ##### `dap_chain_get_atom_by_hash()` Get atom by hash from chain. ```c dap_chain_atom_ptr_t dap_chain_get_atom_by_hash(dap_chain_t *a_chain, dap_chain_hash_fast_t *a_atom_hash, size_t *a_atom_size); ``` **Parameters:** - `a_chain` (`dap_chain_t *`) - Chain to search - `a_atom_hash` (`dap_chain_hash_fast_t *`) - Atom hash to find - `a_atom_size` (`size_t *`) - Output parameter for atom size **Returns:** - `dap_chain_atom_ptr_t` - Pointer to found atom - `NULL` - Atom not found #### Chain Callbacks ##### `dap_chain_add_callback_notify()` Add atom notification callback. ```c void dap_chain_add_callback_notify(dap_chain_t *a_chain, dap_chain_callback_notify_t a_callback, dap_proc_thread_t *a_thread, void *a_arg); ``` **Parameters:** - `a_chain` (`dap_chain_t *`) - Chain to add callback to - `a_callback` (`dap_chain_callback_notify_t`) - Callback function - `a_thread` (`dap_proc_thread_t *`) - Processing thread - `a_arg` (`void *`) - Callback arguments ##### `dap_chain_add_callback_datum_index_notify()` Add datum indexing notification callback. ```c void dap_chain_add_callback_datum_index_notify(dap_chain_t *a_chain, dap_chain_callback_datum_notify_t a_callback, dap_proc_thread_t *a_thread, void *a_callback_arg); ``` **Parameters:** - `a_chain` (`dap_chain_t *`) - Chain to add callback to - `a_callback` (`dap_chain_callback_datum_notify_t`) - Callback function - `a_thread` (`dap_proc_thread_t *`) - Processing thread - `a_callback_arg` (`void *`) - Callback arguments #### Chain Utilities ##### `dap_chain_has_file_store()` Check if chain has file storage. ```c bool dap_chain_has_file_store(dap_chain_t *a_chain); ``` **Parameters:** - `a_chain` (dap_chain_t *) - Chain to check **Returns:** - `true` - Chain has file storage - `false` - Chain uses memory-only storage **Description:** Checks if the chain uses file-based storage or memory-only storage. ##### `dap_chain_info_dump_log()` Dump chain information to log. ```c void dap_chain_info_dump_log(dap_chain_t *a_chain); ``` **Parameters:** - `a_chain` (dap_chain_t *) - Chain to dump information for **Description:** Logs comprehensive chain information including configuration, state, and statistics. ##### `dap_chain_type_to_str()` Convert chain type to string representation. ```c const char *dap_chain_type_to_str(dap_chain_type_t a_chain_type); ``` **Parameters:** - `a_chain_type` (dap_chain_type_t) - Chain type to convert **Returns:** - `const char *` - String representation of chain type - `"UNKNOWN"` - For unrecognized types **Description:** Converts a chain type enum value to its string representation. ##### `dap_chain_add_callback_datum_removed_from_index_notify()` Add datum removal notification callback. ```c void dap_chain_add_callback_datum_removed_from_index_notify(dap_chain_t *a_chain, dap_chain_callback_datum_removed_notify_t a_callback, dap_proc_thread_t *a_thread, void *a_callback_arg); ``` **Parameters:** - `a_chain` (dap_chain_t *) - Chain to add callback to - `a_callback` (dap_chain_callback_datum_removed_notify_t) - Callback function - `a_thread` (dap_proc_thread_t *) - Processing thread - `a_callback_arg` (void *) - Callback arguments **Description:** Adds a callback to be notified when datums are removed from the chain index. ##### `dap_chain_atom_confirmed_notify_add()` Add atom confirmation notification callback. ```c void dap_chain_atom_confirmed_notify_add(dap_chain_t *a_chain, dap_chain_callback_notify_t a_callback, void *a_arg, uint64_t a_conf_cnt); ``` **Parameters:** - `a_chain` (dap_chain_t *) - Chain to add callback to - `a_callback` (dap_chain_callback_notify_t) - Callback function - `a_arg` (void *) - Callback arguments - `a_conf_cnt` (uint64_t) - Number of confirmations required **Description:** Adds a callback to be notified when atoms reach the specified confirmation count. ##### `dap_chain_add_callback_timer()` Add blockchain timer callback. ```c int dap_chain_add_callback_timer(dap_chain_t *a_chain, dap_chain_callback_blockchain_timer_t a_callback, void *a_callback_arg); ``` **Parameters:** - `a_chain` (dap_chain_t *) - Chain to add callback to - `a_callback` (dap_chain_callback_blockchain_timer_t) - Timer callback function - `a_callback_arg` (void *) - Callback arguments **Returns:** - `0` - Callback added successfully - `negative value` - Failed to add callback **Description:** Adds a timer callback that will be called periodically by the blockchain. ##### `dap_chain_atom_notify()` Notify about atom addition. ```c void dap_chain_atom_notify(dap_chain_cell_t *a_chain_cell, dap_hash_fast_t *a_hash, const uint8_t *a_atom, size_t a_atom_size, dap_time_t a_atom_time); ``` **Parameters:** - `a_chain_cell` (dap_chain_cell_t *) - Chain cell where atom was added - `a_hash` (dap_hash_fast_t *) - Atom hash - `a_atom` (const uint8_t *) - Atom data - `a_atom_size` (size_t) - Size of atom data - `a_atom_time` (dap_time_t) - Atom timestamp **Description:** Notifies all registered callbacks about a new atom being added to the chain. ##### `dap_chain_atom_remove_notify()` Notify about atom removal. ```c void dap_chain_atom_remove_notify(dap_chain_t *a_chain, dap_chain_cell_id_t a_cell_id, dap_time_t a_prev_atom_time); ``` **Parameters:** - `a_chain` (dap_chain_t *) - Chain where atom was removed - `a_cell_id` (dap_chain_cell_id_t) - Cell identifier - `a_prev_atom_time` (dap_time_t) - Previous atom timestamp **Description:** Notifies all registered callbacks about an atom being removed from the chain. ##### `dap_chain_datum_removed_notify()` Notify about datum removal. ```c void dap_chain_datum_removed_notify(dap_chain_cell_t *a_chain_cell, dap_hash_fast_t *a_hash, dap_chain_datum_t *a_datum); ``` **Parameters:** - `a_chain_cell` (dap_chain_cell_t *) - Chain cell where datum was removed - `a_hash` (dap_hash_fast_t *) - Datum hash - `a_datum` (dap_chain_datum_t *) - Removed datum **Description:** Notifies all registered callbacks about a datum being removed from the chain. ##### `dap_chain_atom_add_from_threshold()` Add atoms from threshold pool. ```c void dap_chain_atom_add_from_threshold(dap_chain_t *a_chain); ``` **Parameters:** - `a_chain` (dap_chain_t *) - Chain to process **Description:** Processes atoms from the threshold pool and adds them to the chain if conditions are met. ##### `dap_chain_get_atom_last_hash_num()` Get last atom hash and number. ```c bool dap_chain_get_atom_last_hash_num(dap_chain_t *a_chain, dap_chain_cell_id_t a_cell_id, dap_hash_fast_t *a_atom_hash, uint64_t *a_atom_num); ``` **Parameters:** - `a_chain` (dap_chain_t *) - Chain to query - `a_cell_id` (dap_chain_cell_id_t) - Cell identifier - `a_atom_hash` (dap_hash_fast_t *) - Output atom hash - `a_atom_num` (uint64_t *) - Output atom number **Returns:** - `true` - Successfully retrieved last atom information - `false` - Failed to retrieve information **Description:** Retrieves the hash and number of the last atom in the specified cell. ##### `dap_chain_get_atom_last_hash()` Get last atom hash. ```c bool dap_chain_get_atom_last_hash(dap_chain_t *a_chain, dap_chain_cell_id_t a_cell_id, dap_hash_fast_t *a_atom_hash); ``` **Parameters:** - `a_chain` (dap_chain_t *) - Chain to query - `a_cell_id` (dap_chain_cell_id_t) - Cell identifier - `a_atom_hash` (dap_hash_fast_t *) - Output atom hash **Returns:** - `true` - Successfully retrieved last atom hash - `false` - Failed to retrieve hash **Description:** Retrieves the hash of the last atom in the specified cell. ##### `dap_chain_atom_save()` Save atom to chain cell. ```c ssize_t dap_chain_atom_save(dap_chain_cell_t *a_chain_cell, const uint8_t *a_atom, size_t a_atom_size, dap_hash_fast_t *a_new_atom_hash); ``` **Parameters:** - `a_chain_cell` (dap_chain_cell_t *) - Chain cell to save to - `a_atom` (const uint8_t *) - Atom data to save - `a_atom_size` (size_t) - Size of atom data - `a_new_atom_hash` (dap_hash_fast_t *) - Output new atom hash **Returns:** - `ssize_t` - Number of bytes written - `negative value` - Save failed **Description:** Saves an atom to the specified chain cell and returns the new atom hash. ##### `dap_cert_chain_file_save()` Save certificate chain to file. ```c int dap_cert_chain_file_save(dap_chain_datum_t *datum, char *net_name); ``` **Parameters:** - `datum` (dap_chain_datum_t *) - Certificate datum to save - `net_name` (char *) - Network name **Returns:** - `0` - Save successful - `negative value` - Save failed **Description:** Saves a certificate chain datum to a file in the specified network directory. --- ## Chain Cell *Based on: `dap_chain_cell.h` and `dap_chain_cell.c`* ### Overview Chain cell management and storage providing the fundamental storage units for blockchain data. Cells represent logical storage containers within chains that handle file operations, memory mapping, and thread-safe access to chain data. **Key Responsibilities:** - Cell creation and lifecycle management - File storage operations and memory mapping - Thread-safe cell access with read-write locks - Cell-specific data loading and saving - Storage path management and organization ### Document Structure - [[#Overview|Overview]] - [[#Structures|Structures]] - [[#dap_chain_cell_t|dap_chain_cell_t - Main cell structure]] - [[#dap_chain_cell_decl_req_t|dap_chain_cell_decl_req_t - Cell declaration request]] - [[#dap_chain_cell_decl_t|dap_chain_cell_decl_t - Cell declaration]] - [[#Functions|Functions]] - [[#Cell Management|Cell Management]] - [[#Cell Operations|Cell Operations]] ### Structures #### dap_chain_cell_t Main cell structure for chain data storage management. ```c typedef struct dap_chain_cell { dap_chain_cell_id_t id; // Cell identifier dap_chain_t *chain; // Parent chain reference char file_storage_path[MAX_PATH]; // Storage file path char *map, *map_pos, *map_end; // Memory mapping pointers FILE *file_storage; // File handle for storage uint8_t file_storage_type; // Storage type identifier dap_list_t *map_range_bounds; // Memory map range boundaries #ifdef DAP_OS_DARWIN size_t cur_vol_start; // Current volume start (macOS) #endif pthread_rwlock_t storage_rwlock; // Storage read-write lock UT_hash_handle hh; // Hash table handle } dap_chain_cell_t; ``` **Fields:** - `id` - Unique identifier for the cell - `chain` - Reference to parent chain - `file_storage_path` - Full path to storage file - `map`/`map_pos`/`map_end` - Memory mapping control pointers - `file_storage` - File handle for persistent storage - `file_storage_type` - Type of storage mechanism used - `map_range_bounds` - List of memory mapping boundaries - `storage_rwlock` - Thread-safe access control - `hh` - Hash table handle for efficient lookups #### dap_chain_cell_decl_req_t Cell declaration request structure. ```c typedef struct dap_chain_cell_delc_req { dap_chain_addr_t wallet_address; // Target wallet address uint64_t create_ts; // Creation timestamp union { uint8_t raw[DAP_CHAIN_CELL_DECL_REQ_SIGN_SIZE]; // Raw info data char str[DAP_CHAIN_CELL_DECL_REQ_SIGN_SIZE]; // String info data } info; } DAP_ALIGN_PACKED dap_chain_cell_decl_req_t; ``` **Fields:** - `wallet_address` - Wallet address for cell creation - `create_ts` - Timestamp when request was created - `info` - Additional information (raw bytes or string) #### dap_chain_cell_decl_t Cell declaration structure with approval information. ```c typedef struct dap_chain_cell_decl { dap_chain_cell_decl_req_t request; // Original declaration request dap_chain_cell_id_t cell_id; // Assigned cell identifier uint64_t accept_ts; // Acceptance timestamp union { uint8_t raw[DAP_CHAIN_CELL_DECL_ACCEPT_INFO_SIZE]; // Raw accept info char str[DAP_CHAIN_CELL_DECL_ACCEPT_INFO_SIZE]; // String accept info } accept_info; } DAP_ALIGN_PACKED dap_chain_cell_decl_t; ``` **Fields:** - `request` - Original cell declaration request - `cell_id` - Cell identifier assigned upon acceptance - `accept_ts` - Timestamp when declaration was accepted - `accept_info` - Additional acceptance information ### Functions #### Cell Management ##### `dap_chain_cell_init()` Initialize cell subsystem. ```c int dap_chain_cell_init(void); ``` **Returns:** - `0` - Initialization successful - `non-zero` - Initialization failed ##### `dap_chain_cell_create_fill()` Create and fill cell structure. ```c dap_chain_cell_t *dap_chain_cell_create_fill(dap_chain_t *a_chain, dap_chain_cell_id_t a_cell_id); ``` **Parameters:** - `a_chain` (`dap_chain_t *`) - Parent chain - `a_cell_id` (`dap_chain_cell_id_t`) - Cell identifier **Returns:** - `dap_chain_cell_t *` - Created cell structure - `NULL` - Creation failed ##### `dap_chain_cell_find_by_id()` Find cell by identifier in chain. ```c dap_chain_cell_t *dap_chain_cell_find_by_id(dap_chain_t *a_chain, dap_chain_cell_id_t a_cell_id); ``` **Parameters:** - `a_chain` (`dap_chain_t *`) - Chain to search - `a_cell_id` (`dap_chain_cell_id_t`) - Cell identifier **Returns:** - `dap_chain_cell_t *` - Found cell - `NULL` - Cell not found ##### `dap_chain_cell_close()` Close cell and release resources. ```c void dap_chain_cell_close(dap_chain_cell_t *a_cell); ``` **Parameters:** - `a_cell` (`dap_chain_cell_t *`) - Cell to close **Description:** Closes file handles and releases memory mappings without deleting the cell structure. ##### `dap_chain_cell_delete()` Delete cell and free all resources. ```c void dap_chain_cell_delete(dap_chain_cell_t *a_cell); ``` **Parameters:** - `a_cell` (`dap_chain_cell_t *`) - Cell to delete **Description:** Completely removes cell including file closure and memory deallocation. ##### `dap_chain_cell_delete_all()` Delete all cells in chain. ```c void dap_chain_cell_delete_all(dap_chain_t *a_chain); ``` **Parameters:** - `a_chain` (`dap_chain_t *`) - Chain containing cells to delete #### Cell Operations ##### `dap_chain_cell_load()` Load cell data from storage. ```c int dap_chain_cell_load(dap_chain_t *a_chain, dap_chain_cell_t *a_cell); ``` **Parameters:** - `a_chain` (`dap_chain_t *`) - Parent chain - `a_cell` (`dap_chain_cell_t *`) - Cell to load **Returns:** - `0` - Load successful - `non-zero` - Load failed ##### `dap_chain_cell_file_append()` Append data to cell file. ```c ssize_t dap_chain_cell_file_append(dap_chain_cell_t *a_cell, const void *a_atom, size_t a_atom_size); ``` **Parameters:** - `a_cell` (`dap_chain_cell_t *`) - Target cell - `a_atom` (`const void *`) - Data to append - `a_atom_size` (`size_t`) - Size of data **Returns:** - `ssize_t` - Number of bytes written - `-1` - Write failed --- ## Chain Consensus *Based on: `dap_chain_cs.h` and `dap_chain_cs.c`* ### Overview Chain consensus interface providing the abstraction layer for different consensus mechanisms. This division provides the common interface that consensus implementations must follow to integrate with the chain system. ### Document Structure - [[#Overview|Overview]] - [[#Functions|Functions]] - [[#Consensus Management|Consensus Management]] - [[#Consensus Operations|Consensus Operations]] ### Functions #### Consensus Management ##### `dap_chain_cs_init()` Initialize consensus subsystem. ```c int dap_chain_cs_init(void); ``` **Returns:** - `0` - Initialization successful - `non-zero` - Initialization failed **Description:** Initializes the consensus subsystem and sets up global consensus data structures. ##### `dap_chain_cs_deinit()` Deinitialize consensus subsystem. ```c void dap_chain_cs_deinit(void); ``` **Description:** Cleans up the consensus subsystem and frees all consensus resources. ##### `dap_chain_cs_add()` Add consensus mechanism. ```c void dap_chain_cs_add(const char *a_cs_str, dap_chain_callback_new_cfg_t a_callback_init); ``` **Parameters:** - `a_cs_str` (`const char *`) - Consensus mechanism name - `a_callback_init` (`dap_chain_callback_new_cfg_t`) - Initialization callback **Description:** Registers a consensus mechanism with the chain system. #### Consensus Operations ##### `dap_chain_cs_create()` Create consensus for chain. ```c int dap_chain_cs_create(dap_chain_t *a_chain, dap_config_t *a_chain_cfg); ``` **Parameters:** - `a_chain` (`dap_chain_t *`) - Chain to create consensus for - `a_chain_cfg` (`dap_config_t *`) - Chain configuration **Returns:** - `0` - Consensus created successfully - `non-zero` - Consensus creation failed **Description:** Creates and initializes consensus mechanism for the specified chain. ##### `dap_chain_cs_type_add()` Add consensus type. ```c void dap_chain_cs_type_add(const char *a_cs_str, dap_chain_callback_new_cfg_t a_callback_init, dap_chain_callback_t a_callback_start); ``` **Parameters:** - `a_cs_str` (`const char *`) - Consensus type name - `a_callback_init` (`dap_chain_callback_new_cfg_t`) - Initialization callback - `a_callback_start` (`dap_chain_callback_t`) - Start callback **Description:** Registers a consensus type with initialization and start callbacks. ##### `dap_chain_cs_type_create()` Create consensus type for chain. ```c int dap_chain_cs_type_create(const char *a_type, dap_chain_t *a_chain, dap_config_t *a_chain_cfg); ``` **Parameters:** - `a_type` (`const char *`) - Consensus type name - `a_chain` (`dap_chain_t *`) - Chain to create consensus for - `a_chain_cfg` (`dap_config_t *`) - Chain configuration **Returns:** - `0` - Consensus type created successfully - `non-zero` - Consensus type creation failed **Description:** Creates consensus mechanism of specified type for the chain. ##### `dap_chain_cs_type_start()` Start consensus type for chain. ```c void dap_chain_cs_type_start(const char *a_type, dap_chain_t *a_chain); ``` **Parameters:** - `a_type` (`const char *`) - Consensus type name - `a_chain` (`dap_chain_t *`) - Chain to start consensus for **Description:** Starts the consensus mechanism of specified type for the chain. --- ## Chain Channels *Based on: `dap_chain_ch.h` and `dap_chain_ch.c`* ### Overview Chain channel operations providing communication infrastructure for blockchain networks. This division handles channel initialization, error handling, and communication protocols between chain components. ### Document Structure - [[#Overview|Overview]] - [[#Functions|Functions]] - [[#Channel Management|Channel Management]] - [[#Channel Operations|Channel Operations]] ### Functions #### Channel Management ##### `dap_chain_ch_init()` Initialize chain channels. ```c int dap_chain_ch_init(void); ``` **Returns:** - `0` - Initialization successful - `non-zero` - Initialization failed **Description:** Initializes the chain channel subsystem and sets up communication infrastructure. ##### `dap_chain_ch_deinit()` Deinitialize chain channels. ```c void dap_chain_ch_deinit(void); ``` **Description:** Cleans up the chain channel subsystem and frees all channel resources. #### Channel Operations ##### `dap_stream_ch_write_error_unsafe()` Write error to stream channel (unsafe). ```c void dap_stream_ch_write_error_unsafe(dap_stream_ch_t *a_ch, dap_chain_net_id_t a_net_id, dap_chain_id_t a_chain_id, dap_chain_cell_id_t a_cell_id, dap_chain_ch_error_type_t a_error); ``` **Parameters:** - `a_ch` (`dap_stream_ch_t *`) - Stream channel - `a_net_id` (`dap_chain_net_id_t`) - Network identifier - `a_chain_id` (`dap_chain_id_t`) - Chain identifier - `a_cell_id` (`dap_chain_cell_id_t`) - Cell identifier - `a_error` (`dap_chain_ch_error_type_t`) - Error type **Description:** Writes an error message to the stream channel without thread safety. ##### `dap_chain_ch_pkt_new()` Create new channel packet. ```c dap_chain_ch_pkt_t *dap_chain_ch_pkt_new(dap_chain_net_id_t a_net_id, dap_chain_id_t a_chain_id, dap_chain_cell_id_t a_cell_id, const void *a_data, size_t a_data_size, uint8_t a_version); ``` **Parameters:** - `a_net_id` (`dap_chain_net_id_t`) - Network identifier - `a_chain_id` (`dap_chain_id_t`) - Chain identifier - `a_cell_id` (`dap_chain_cell_id_t`) - Cell identifier - `a_data` (`const void *`) - Packet data - `a_data_size` (`size_t`) - Size of packet data - `a_version` (`uint8_t`) - Packet version **Returns:** - `dap_chain_ch_pkt_t *` - Created packet - `NULL` - Creation failed **Description:** Creates a new channel packet with the specified data and metadata. ##### `dap_chain_ch_pkt_write_unsafe()` Write packet to channel (unsafe). ```c size_t dap_chain_ch_pkt_write_unsafe(dap_stream_ch_t *a_ch, uint8_t a_type, dap_chain_net_id_t a_net_id, dap_chain_id_t a_chain_id, dap_chain_cell_id_t a_cell_id, const void *a_data, size_t a_data_size, uint8_t a_version); ``` **Parameters:** - `a_ch` (`dap_stream_ch_t *`) - Stream channel - `a_type` (`uint8_t`) - Packet type - `a_net_id` (`dap_chain_net_id_t`) - Network identifier - `a_chain_id` (`dap_chain_id_t`) - Chain identifier - `a_cell_id` (`dap_chain_cell_id_t`) - Cell identifier - `a_data` (`const void *`) - Packet data - `a_data_size` (`size_t`) - Size of packet data - `a_version` (`uint8_t`) - Packet version **Returns:** - `size_t` - Number of bytes written - `0` - Write failed **Description:** Writes a packet to the channel without thread safety. ##### `dap_chain_ch_pkt_write_mt()` Write packet to channel (multi-threaded). ```c size_t dap_chain_ch_pkt_write_mt(dap_stream_worker_t *a_worker, dap_stream_ch_uuid_t a_ch_uuid, uint8_t a_type, dap_chain_net_id_t a_net_id, dap_chain_id_t a_chain_id, dap_chain_cell_id_t a_cell_id, const void *a_data, size_t a_data_size, uint8_t a_version); ``` **Parameters:** - `a_worker` (`dap_stream_worker_t *`) - Stream worker - `a_ch_uuid` (`dap_stream_ch_uuid_t`) - Channel UUID - `a_type` (`uint8_t`) - Packet type - `a_net_id` (`dap_chain_net_id_t`) - Network identifier - `a_chain_id` (`dap_chain_id_t`) - Chain identifier - `a_cell_id` (`dap_chain_cell_id_t`) - Cell identifier - `a_data` (`const void *`) - Packet data - `a_data_size` (`size_t`) - Size of packet data - `a_version` (`uint8_t`) - Packet version **Returns:** - `size_t` - Number of bytes written - `0` - Write failed **Description:** Writes a packet to the channel using multi-threaded worker. ##### `dap_chain_ch_pkt_write_inter()` Write packet to channel (inter-thread). ```c size_t dap_chain_ch_pkt_write_inter(dap_events_socket_t *a_es_input, dap_stream_ch_uuid_t a_ch_uuid, uint8_t a_type, dap_chain_net_id_t a_net_id, dap_chain_id_t a_chain_id, dap_chain_cell_id_t a_cell_id, const void *a_data, size_t a_data_size, uint8_t a_version); ``` **Parameters:** - `a_es_input` (`dap_events_socket_t *`) - Event socket - `a_ch_uuid` (`dap_stream_ch_uuid_t`) - Channel UUID - `a_type` (`uint8_t`) - Packet type - `a_net_id` (`dap_chain_net_id_t`) - Network identifier - `a_chain_id` (`dap_chain_id_t`) - Chain identifier - `a_cell_id` (`dap_chain_cell_id_t`) - Cell identifier - `a_data` (`const void *`) - Packet data - `a_data_size` (`size_t`) - Size of packet data - `a_version` (`uint8_t`) - Packet version **Returns:** - `size_t` - Number of bytes written - `0` - Write failed **Description:** Writes a packet to the channel using inter-thread communication. ##### `dap_chain_ch_pkt_get_size()` Get packet size. ```c size_t dap_chain_ch_pkt_get_size(dap_chain_ch_pkt_t *a_pkt); ``` **Parameters:** - `a_pkt` (`dap_chain_ch_pkt_t *`) - Packet to get size for **Returns:** - `size_t` - Total packet size including header and data **Description:** Returns the total size of a channel packet including header and data. ##### `dap_chain_ch_pkt_type_to_str()` Convert packet type to string. ```c const char *dap_chain_ch_pkt_type_to_str(uint8_t a_pkt_type); ``` **Parameters:** - `a_pkt_type` (`uint8_t`) - Packet type to convert **Returns:** - `const char *` - String representation of packet type - `"DAP_CHAIN_CH_PKT_TYPE_UNKNOWN"` - For unknown types **Description:** Converts a packet type enum value to its string representation. --- ## Chain Transactions *Based on: `dap_chain_tx.h` and `dap_chain_tx.c`* ### Overview Chain transaction management providing transaction processing and validation for blockchain operations. This division handles transaction creation, verification, and lifecycle management. ### Document Structure - [[#Overview|Overview]] - [[#Functions|Functions]] - [[#Transaction Management|Transaction Management]] ### Functions #### Transaction Management ##### `dap_chain_tx_hh_add()` Add transaction to hash table. ```c void dap_chain_tx_hh_add(dap_chain_tx_t **a_tx_hh, dap_chain_tx_t *a_tx); ``` **Parameters:** - `a_tx_hh` (`dap_chain_tx_t **`) - Hash table pointer - `a_tx` (`dap_chain_tx_t *`) - Transaction to add **Description:** Adds a transaction to the hash table for efficient lookup. ##### `dap_chain_tx_hh_free()` Free transaction hash table. ```c void dap_chain_tx_hh_free(dap_chain_tx_t *a_tx_hh); ``` **Parameters:** - `a_tx_hh` (`dap_chain_tx_t *`) - Hash table to free **Description:** Frees all transactions in the hash table and the table itself. ##### `dap_chain_tx_delete()` Delete transaction. ```c void dap_chain_tx_delete(dap_chain_tx_t *a_tx); ``` **Parameters:** - `a_tx` (`dap_chain_tx_t *`) - Transaction to delete **Description:** Deletes a transaction and frees all associated resources. --- ## Chain Policy *Based on: `dap_chain_policy.h` and `dap_chain_policy.c`* ### Overview Chain policy management providing governance and rule enforcement for blockchain networks. This division handles policy creation, application, validation, and exception management for network-wide rules and regulations. ### Document Structure - [[#Overview|Overview]] - [[#Structures|Structures]] - [[#dap_chain_policy_t|dap_chain_policy_t - Policy structure]] - [[#Functions|Functions]] - [[#Policy Management|Policy Management]] - [[#Policy Operations|Policy Operations]] ### Structures #### dap_chain_policy_t Chain policy structure for network governance and rule enforcement. ```c typedef struct dap_chain_policy { uint16_t version; // Policy version number uint64_t flags; // Policy flags and options uint64_t data_size; // Size of policy data uint8_t data[]; // Variable-length policy data } DAP_ALIGN_PACKED dap_chain_policy_t; ``` **Fields:** - `version` - Policy version number for compatibility tracking - `flags` - Policy flags including activation status and options - `data_size` - Size of the variable-length policy data - `data[]` - Variable-length array containing policy-specific data ### Functions #### Policy Management ##### `dap_chain_policy_init()` Initialize policy subsystem. ```c int dap_chain_policy_init(); ``` **Returns:** - `0` - Initialization successful - `non-zero` - Initialization failed **Description:** Initializes the policy management subsystem and sets up global policy data structures. ##### `dap_chain_policy_deinit()` Deinitialize policy subsystem. ```c void dap_chain_policy_deinit(); ``` **Description:** Cleans up the policy management subsystem and frees all policy resources. ##### `dap_chain_policy_create_activate()` Create activation policy. ```c dap_chain_policy_t *dap_chain_policy_create_activate(uint32_t a_num, int64_t ts_start, uint64_t a_block_start, dap_chain_id_t a_chain_id, uint16_t a_generation); ``` **Parameters:** - `a_num` (`uint32_t`) - Policy number - `ts_start` (`int64_t`) - Start timestamp - `a_block_start` (`uint64_t`) - Starting block number - `a_chain_id` (`dap_chain_id_t`) - Target chain identifier - `a_generation` (`uint16_t`) - Policy generation number **Returns:** - `dap_chain_policy_t *` - Created activation policy - `NULL` - Creation failed **Description:** Creates a new activation policy for enabling features or rules. ##### `dap_chain_policy_create_deactivate()` Create deactivation policy. ```c dap_chain_policy_t *dap_chain_policy_create_deactivate(char **a_nums, uint32_t a_count); ``` **Parameters:** - `a_nums` (`char **`) - Array of policy numbers to deactivate - `a_count` (`uint32_t`) - Number of policies in array **Returns:** - `dap_chain_policy_t *` - Created deactivation policy - `NULL` - Creation failed **Description:** Creates a deactivation policy for disabling specific policies. #### Policy Operations ##### `dap_chain_policy_net_add()` Add policy to network. ```c int dap_chain_policy_net_add(dap_chain_net_id_t a_net_id, dap_config_t *a_net_cfg); ``` **Parameters:** - `a_net_id` (`dap_chain_net_id_t`) - Network identifier - `a_net_cfg` (`dap_config_t *`) - Network configuration **Returns:** - `0` - Policy added successfully - `non-zero` - Add failed **Description:** Adds policy management to a specific network. ##### `dap_chain_policy_net_purge()` Purge all policies from network. ```c void dap_chain_policy_net_purge(dap_chain_net_id_t a_net_id); ``` **Parameters:** - `a_net_id` (`dap_chain_net_id_t`) - Network identifier **Description:** Removes all policies from the specified network. ##### `dap_chain_policy_net_remove()` Remove policy from network. ```c void dap_chain_policy_net_remove(dap_chain_net_id_t a_net_id); ``` **Parameters:** - `a_net_id` (`dap_chain_net_id_t`) - Network identifier **Description:** Removes policy management from the specified network. ##### `dap_chain_policy_apply()` Apply policy to network. ```c int dap_chain_policy_apply(dap_chain_policy_t *a_policy, dap_chain_net_id_t a_net_id); ``` **Parameters:** - `a_policy` (`dap_chain_policy_t *`) - Policy to apply - `a_net_id` (`dap_chain_net_id_t`) - Target network identifier **Returns:** - `0` - Policy applied successfully - `non-zero` - Application failed **Description:** Applies a policy to the specified network. ##### `dap_chain_policy_add_exceptions()` Add policy exceptions. ```c void dap_chain_policy_add_exceptions(dap_chain_net_id_t a_net_id, const char **a_nums, uint32_t a_count); ``` **Parameters:** - `a_net_id` (`dap_chain_net_id_t`) - Network identifier - `a_nums` (`const char **`) - Array of exception numbers - `a_count` (`uint32_t`) - Number of exceptions **Description:** Adds exceptions to policy enforcement for the network. ##### `dap_chain_policy_update_last_num()` Update last policy number. ```c void dap_chain_policy_update_last_num(dap_chain_net_id_t a_net_id, uint32_t a_num); ``` **Parameters:** - `a_net_id` (`dap_chain_net_id_t`) - Network identifier - `a_num` (`uint32_t`) - New last policy number **Description:** Updates the last processed policy number for the network. ##### `dap_chain_policy_get_last_num()` Get last policy number. ```c uint32_t dap_chain_policy_get_last_num(dap_chain_net_id_t a_net_id); ``` **Parameters:** - `a_net_id` (`dap_chain_net_id_t`) - Network identifier **Returns:** - `uint32_t` - Last policy number **Description:** Returns the last processed policy number for the network. ##### `dap_chain_policy_activate_json_collect()` Collect activation policy JSON. ```c json_object *dap_chain_policy_activate_json_collect(dap_chain_net_id_t a_net_id, uint32_t a_num); ``` **Parameters:** - `a_net_id` (`dap_chain_net_id_t`) - Network identifier - `a_num` (`uint32_t`) - Policy number **Returns:** - `json_object *` - JSON object containing activation policy data - `NULL` - Collection failed **Description:** Collects activation policy data in JSON format. ##### `dap_chain_policy_json_collect()` Collect policy JSON data. ```c json_object *dap_chain_policy_json_collect(dap_chain_policy_t *a_policy); ``` **Parameters:** - `a_policy` (`dap_chain_policy_t *`) - Policy to collect data from **Returns:** - `json_object *` - JSON object containing policy data - `NULL` - Collection failed **Description:** Converts policy data to JSON format. ##### `dap_chain_policy_list()` List all policies for network. ```c json_object *dap_chain_policy_list(dap_chain_net_id_t a_net_id); ``` **Parameters:** - `a_net_id` (`dap_chain_net_id_t`) - Network identifier **Returns:** - `json_object *` - JSON object containing policy list - `NULL` - List operation failed **Description:** Returns a list of all policies for the specified network. ##### `dap_chain_policy_is_exist()` Check if policy exists. ```c bool dap_chain_policy_is_exist(dap_chain_net_id_t a_net_id, uint32_t a_num); ``` **Parameters:** - `a_net_id` (`dap_chain_net_id_t`) - Network identifier - `a_num` (`uint32_t`) - Policy number to check **Returns:** - `true` - Policy exists - `false` - Policy does not exist **Description:** Checks if a specific policy exists for the network. ##### `dap_chain_policy_is_activated()` Check if policy is activated. ```c bool dap_chain_policy_is_activated(dap_chain_net_id_t a_net_id, uint32_t a_policy_num); ``` **Parameters:** - `a_net_id` (`dap_chain_net_id_t`) - Network identifier - `a_policy_num` (`uint32_t`) - Policy number to check **Returns:** - `true` - Policy is activated - `false` - Policy is not activated **Description:** Checks if a specific policy is currently activated for the network. ##### `dap_chain_policy_get_size()` Get policy size. ```c size_t dap_chain_policy_get_size(dap_chain_policy_t *a_policy); ``` **Parameters:** - `a_policy` (`dap_chain_policy_t *`) - Policy to get size for **Returns:** - `size_t` - Total size of policy including data - `0` - If policy is NULL **Description:** Returns the total size of a policy including its variable-length data. ##### `dap_chain_policy_to_str()` Convert policy to string. ```c const char *dap_chain_policy_to_str(dap_chain_policy_t *a_policy); ``` **Parameters:** - `a_policy` (`dap_chain_policy_t *`) - Policy to convert **Returns:** - `const char *` - String representation of policy type - `"<null>"` - If policy is NULL **Description:** Converts a policy to its string representation for debugging and logging. --- ## Typical Examples //... existing code...