## Overview The DAG PoA (Directed Acyclic Graph Proof of Authority) consensus module implements a high-performance consensus mechanism combining DAG structure with Proof of Authority validation. This module provides fast transaction processing, deterministic finality, and scalable consensus for authorized validator networks while maintaining Byzantine fault tolerance and efficient resource utilization. *Based on: `dap_chain_cs_dag_poa.h`, `dap_chain_cs_dag_poa.c`, `dap_chain_cs_dag.h`, `dap_chain_cs_dag.c`* ## Document Structure - [[#Overview|Overview]] - [[#Module Structures|Module Structures]] - [[#dap_chain_cs_dag_poa_t|dap_chain_cs_dag_poa_t - DAG PoA Instance]] - [[#dap_chain_cs_dag_poa_validator_t|dap_chain_cs_dag_poa_validator_t - Authority Validator]] - [[#dap_chain_cs_dag_poa_event_t|dap_chain_cs_dag_poa_event_t - DAG Event]] - [[#dap_chain_cs_dag_poa_round_t|dap_chain_cs_dag_poa_round_t - Consensus Round]] - [[#dap_chain_cs_dag_poa_signature_t|dap_chain_cs_dag_poa_signature_t - Event Signature]] - [[#Module Functions|Module Functions]] - [[#Consensus Management|DAG PoA Control]] - [[#Validator Operations|Authority Management]] - [[#Event Processing|DAG Event Handling]] - [[#Finality Control|Consensus Finalization]] - [[#Error Codes|Error Codes]] - [[#Typical Examples|Typical Examples]] ## Module Structures ### dap_chain_cs_dag_poa_t Core DAG PoA consensus instance managing protocol execution. ```c typedef struct dap_chain_cs_dag_poa { struct { dap_chain_t *chain; // Associated blockchain dap_chain_cs_dag_poa_config_t *config; // DAG PoA configuration uint64_t current_round; // Current consensus round dap_time_t round_start_time; // Round start timestamp bool is_authority; // Node authority status uint32_t confirmations_required; // Required confirmations for finality } pub; struct { dap_list_t *authorities; // Active authority validators dap_htable_t *events_table; // DAG events hash table dap_list_t *pending_events; // Pending DAG events dap_chain_cs_dag_poa_stats_t *stats; // Consensus statistics pthread_rwlock_t dag_lock; // DAG structure lock dap_enc_key_t *authority_key; // Authority signing key } priv; } dap_chain_cs_dag_poa_t; ``` ### dap_chain_cs_dag_poa_validator_t Authority validator participating in DAG PoA consensus. ```c typedef struct dap_chain_cs_dag_poa_validator { struct { dap_chain_addr_t *addr; // Authority address dap_pkey_t *pkey; // Authority public key uint256_t authority_weight; // Authority voting weight dap_time_t authorized_time; // Authorization timestamp bool is_online; // Authority online status uint32_t events_signed; // Number of events signed } pub; struct { dap_enc_key_t *signing_key; // Private signing key uint64_t reputation_score; // Authority reputation dap_time_t last_event_time; // Last event timestamp uint32_t missed_rounds; // Missed consensus rounds dap_list_t *recent_signatures; // Recent signature history } priv; } dap_chain_cs_dag_poa_validator_t; ``` ### dap_chain_cs_dag_poa_event_t DAG event structure representing consensus decisions. ```c typedef struct dap_chain_cs_dag_poa_event { struct { dap_chain_hash_fast_t hash; // Event hash dap_chain_addr_t *creator_addr; // Event creator address uint64_t round_number; // Associated round dap_time_t timestamp; // Event creation time uint32_t parents_count; // Number of parent events dap_chain_hash_fast_t *parents; // Parent event hashes } pub; struct { dap_list_t *signatures; // Authority signatures uint32_t confirmations; // Confirmation count bool is_finalized; // Finalization status dap_time_t finalized_time; // Finalization timestamp void *event_data; // Event-specific data } priv; } dap_chain_cs_dag_poa_event_t; ``` ### dap_chain_cs_dag_poa_round_t Consensus round data for DAG PoA processing. ```c typedef struct dap_chain_cs_dag_poa_round { struct { uint64_t round_number; // Round identifier dap_time_t start_time; // Round start time dap_time_t end_time; // Round end time uint32_t events_count; // Events in round uint32_t authorities_active; // Active authorities } pub; private { dap_list_t *round_events; // Events in this round dap_htable_t *authority_signatures; // Authority signatures bool round_finalized; // Round finalization status uint64_t total_weight_signed; // Total authority weight signed } priv; } dap_chain_cs_dag_poa_round_t; ``` ### dap_chain_cs_dag_poa_signature_t Authority signature for DAG events. ```c typedef struct dap_chain_cs_dag_poa_signature { struct { dap_chain_addr_t *authority_addr; // Signing authority dap_chain_hash_fast_t event_hash; // Signed event hash dap_time_t signature_time; // Signature timestamp uint256_t authority_weight; // Authority weight } pub; struct { dap_sign_t *signature; // Cryptographic signature bool is_verified; // Signature verification status dap_time_t verification_time; // Verification timestamp } priv; } dap_chain_cs_dag_poa_signature_t; ``` ## Module Functions ### Consensus Management #### `dap_chain_cs_dag_poa_new()` Creates new DAG PoA consensus instance. ```c dap_chain_cs_dag_poa_t* dap_chain_cs_dag_poa_new(dap_chain_t *a_chain, dap_chain_cs_dag_poa_config_t *a_config); ``` #### `dap_chain_cs_dag_poa_start()` Starts DAG PoA consensus protocol. ```c int dap_chain_cs_dag_poa_start(dap_chain_cs_dag_poa_t *a_dag_poa); ``` #### `dap_chain_cs_dag_poa_stop()` Stops DAG PoA consensus protocol. ```c int dap_chain_cs_dag_poa_stop(dap_chain_cs_dag_poa_t *a_dag_poa); ``` ### Validator Operations #### `dap_chain_cs_dag_poa_authority_add()` Adds authority validator to consensus. ```c int dap_chain_cs_dag_poa_authority_add(dap_chain_cs_dag_poa_t *a_dag_poa, dap_chain_cs_dag_poa_validator_t *a_authority); ``` #### `dap_chain_cs_dag_poa_authority_remove()` Removes authority from consensus set. ```c int dap_chain_cs_dag_poa_authority_remove(dap_chain_cs_dag_poa_t *a_dag_poa, dap_chain_addr_t *a_authority_addr); ``` ### Event Processing #### `dap_chain_cs_dag_poa_event_create()` Creates new DAG event. ```c dap_chain_cs_dag_poa_event_t* dap_chain_cs_dag_poa_event_create( dap_chain_cs_dag_poa_t *a_dag_poa, dap_chain_hash_fast_t *a_parents, uint32_t a_parents_count); ``` #### `dap_chain_cs_dag_poa_event_sign()` Signs DAG event with authority key. ```c int dap_chain_cs_dag_poa_event_sign(dap_chain_cs_dag_poa_t *a_dag_poa, dap_chain_cs_dag_poa_event_t *a_event); ``` ### Finality Control #### `dap_chain_cs_dag_poa_event_finalize()` Finalizes DAG event after sufficient confirmations. ```c int dap_chain_cs_dag_poa_event_finalize(dap_chain_cs_dag_poa_t *a_dag_poa, dap_chain_cs_dag_poa_event_t *a_event); ``` ## Error Codes ```c typedef enum dap_chain_cs_dag_poa_error { DAP_CHAIN_CS_DAG_POA_ERROR_SUCCESS = 0, // Operation successful DAP_CHAIN_CS_DAG_POA_ERROR_INVALID_PARAM, // Invalid parameter DAP_CHAIN_CS_DAG_POA_ERROR_NO_MEMORY, // Memory allocation failed DAP_CHAIN_CS_DAG_POA_ERROR_NOT_AUTHORITY, // Not authorized validator DAP_CHAIN_CS_DAG_POA_ERROR_INVALID_EVENT, // Invalid DAG event DAP_CHAIN_CS_DAG_POA_ERROR_INSUFFICIENT_SIGS, // Insufficient signatures DAP_CHAIN_CS_DAG_POA_ERROR_ALREADY_FINALIZED // Event already finalized } dap_chain_cs_dag_poa_error_t; ``` ## Typical Examples ### Basic DAG PoA Setup Example ```c #include <dap_chain_cs_dag_poa.h> void dag_poa_setup_example() { log_it_info("=== DAG PoA Consensus Setup Example ==="); // Create chain dap_chain_t *chain = dap_chain_find_by_id("testchain"); if (!chain) { log_it_error("✗ Chain not found"); return; } // Configure DAG PoA dap_chain_cs_dag_poa_config_t config = { .min_authorities = 3, .max_authorities = 21, .confirmations_required = 2, .round_timeout_ms = 5000, .byzantine_threshold = 0.33 }; // Create DAG PoA instance dap_chain_cs_dag_poa_t *dag_poa = dap_chain_cs_dag_poa_new(chain, &config); if (!dag_poa) { log_it_error("✗ Failed to create DAG PoA instance"); return; } log_it_info("✓ DAG PoA consensus created"); log_it_info(" Confirmations required: %d", config.confirmations_required); log_it_info(" Round timeout: %d ms", config.round_timeout_ms); // Add authorities for (int i = 0; i < 5; i++) { dap_chain_addr_t *authority_addr = dap_chain_addr_from_str_static( dap_string_with_format("authority_%d", i + 1)); dap_enc_key_t *authority_key = dap_enc_key_new_generate( DAP_ENC_KEY_TYPE_SIG_PICNIC, NULL, 0, NULL, 0, 0); if (authority_addr && authority_key) { dap_chain_cs_dag_poa_validator_t authority = { .pub.addr = authority_addr, .pub.pkey = dap_pkey_from_enc_key(authority_key), .pub.authority_weight = uint256_from_uint64(1000 + i * 500), .pub.authorized_time = dap_time_now(), .pub.is_online = true, .priv.signing_key = authority_key, .priv.reputation_score = 1000 }; int result = dap_chain_cs_dag_poa_authority_add(dag_poa, &authority); if (result == 0) { log_it_info("✓ Authority %d added successfully", i + 1); } else { log_it_error("✗ Failed to add authority %d: %d", i + 1, result); } } } // Start consensus int result = dap_chain_cs_dag_poa_start(dag_poa); if (result == 0) { log_it_info("✓ DAG PoA consensus started successfully"); log_it_info(" Current round: %lu", dag_poa->pub.current_round); log_it_info(" Is authority: %s", dag_poa->pub.is_authority ? "Yes" : "No"); } else { log_it_error("✗ Failed to start DAG PoA consensus: %d", result); } log_it_info("✓ DAG PoA setup example completed"); // Cleanup dap_chain_cs_dag_poa_stop(dag_poa); dap_chain_cs_dag_poa_delete(dag_poa); } ``` ### DAG Event Processing Example ```c #include <dap_chain_cs_dag_poa.h> void dag_event_processing_example() { log_it_info("=== DAG Event Processing Example ==="); // Assume DAG PoA already initialized dap_chain_t *chain = dap_chain_find_by_id("testchain"); dap_chain_cs_dag_poa_config_t config = {.confirmations_required = 2}; dap_chain_cs_dag_poa_t *dag_poa = dap_chain_cs_dag_poa_new(chain, &config); if (!dag_poa) { log_it_error("✗ Failed to create DAG PoA"); return; } // Create DAG event dap_chain_hash_fast_t parents[2]; dap_hash_fast_t genesis_hash = {0}; // Genesis parent parents[0] = *(dap_chain_hash_fast_t*)&genesis_hash; dap_chain_cs_dag_poa_event_t *event = dap_chain_cs_dag_poa_event_create( dag_poa, parents, 1); if (!event) { log_it_error("✗ Failed to create DAG event"); goto cleanup; } log_it_info("✓ DAG event created"); log_it_info(" Event hash: %s", dap_chain_hash_fast_to_str_new(&event->pub.hash)); log_it_info(" Round: %lu", event->pub.round_number); log_it_info(" Parents: %d", event->pub.parents_count); // Sign event int result = dap_chain_cs_dag_poa_event_sign(dag_poa, event); if (result == 0) { log_it_info("✓ Event signed successfully"); log_it_info(" Signatures: %d", dap_list_length(event->priv.signatures)); } else { log_it_error("✗ Failed to sign event: %d", result); } // Check finalization result = dap_chain_cs_dag_poa_event_finalize(dag_poa, event); if (result == 0) { log_it_info("✓ Event finalized"); log_it_info(" Confirmations: %d", event->priv.confirmations); log_it_info(" Finalized: %s", event->priv.is_finalized ? "Yes" : "No"); } else { log_it_info("○ Event pending finalization (need more signatures)"); } log_it_info("✓ DAG event processing example completed"); cleanup: dap_chain_cs_dag_poa_delete(dag_poa); } ``` --- *See also: [[Module Consensus|Consensus Overview]], [[Module Consensus - ESBOCS|ESBOCS Consensus]], [[Module Consensus - CS None|Simple Consensus]], [[ETC/Architecture Overview|System Architecture]]*