# Module Service - Bridge ## Overview The Bridge Service provides cross-chain and inter-network transaction capabilities within the Cellframe SDK. This service handles bridged transfers, cross-chain emissions, transaction validation for bridge operations, and maintains compatibility with various token emission types across different blockchain networks. *Based on: `dap_chain_net_srv_bridge.h`, `dap_chain_net_srv_bridge.c`* **Service UID:** `DAP_CHAIN_NET_SRV_BRIDGE_ID` (0x04) ## Document Structure - [[#Overview|Overview]] - [[#Bridge Structures|Bridge Structures]] - [[#Bridge Action Types|Bridge Action Types - Transaction classification]] - [[#TSD Data Types|TSD Data Types - Transaction supplementary data]] - [[#Bridge Functions|Bridge Functions]] - [[#Service Management|Service Management Functions]] - [[#Transaction Validation|Transaction Validation Functions]] - [[#Emission Processing|Emission Processing Functions]] - [[#Typical Examples|Typical Examples]] ## Bridge Structures ### Bridge Action Types Transaction action types for bridge operations. ```c typedef enum dap_chain_tx_tag_action_type { DAP_CHAIN_TX_TAG_ACTION_UNKNOWN = 0, // Unknown action type DAP_CHAIN_TX_TAG_ACTION_TRANSFER_REGULAR, // Regular bridge transfer DAP_CHAIN_TX_TAG_ACTION_TRANSFER_COMISSION, // Commission transfer DAP_CHAIN_TX_TAG_ACTION_TRANSFER_CROSSCHAIN, // Cross-chain transfer DAP_CHAIN_TX_TAG_ACTION_CLOSE // Bridge closure transaction } dap_chain_tx_tag_action_type_t; ``` **Action Types:** - `TRANSFER_REGULAR` - Standard bridge transfers between networks - `TRANSFER_COMISSION` - Commission collection for bridge operations - `TRANSFER_CROSSCHAIN` - Cross-chain bridging operations - `CLOSE` - Transaction to close bridge operations ### TSD Data Types Transaction Supplementary Data types for bridge identification. ```c // Bridge-specific TSD type constants #define DAP_CHAIN_DATUM_TOKEN_EMISSION_SOURCE_BRIDGE "bridge" #define DAP_CHAIN_DATUM_TOKEN_EMISSION_SOURCE_SUBTYPE_BRIDGE_TRANSFER "bridge_transfer" #define DAP_CHAIN_DATUM_TOKEN_EMISSION_SOURCE_SUBTYPE_BRIDGE_COMMISSION "bridge_commission" #define DAP_CHAIN_DATUM_TOKEN_EMISSION_SOURCE_SUBTYPE_BRIDGE_CROSSCHAIN "bridge_crosschain" #define DAP_CHAIN_DATUM_TOKEN_EMISSION_SOURCE_SUBTYPE_BRIDGE_OUT "bridge_out" #define DAP_CHAIN_DATUM_TOKEN_EMISSION_SOURCE_SUBTYPE_BRIDGE_COMMISSION_OLD "bridge_comission" ``` **TSD Categories:** - `SOURCE_BRIDGE` - Identifies bridge-originated transactions - `SUBTYPE_BRIDGE_TRANSFER` - Regular bridge transfer operations - `SUBTYPE_BRIDGE_COMMISSION` - Commission-related bridge operations - `SUBTYPE_BRIDGE_CROSSCHAIN` - Cross-chain bridging operations - `SUBTYPE_BRIDGE_OUT` - Outgoing bridge transactions - `SUBTYPE_BRIDGE_COMMISSION_OLD` - Legacy commission format support ### Bridge Transaction Structure Bridge transactions use standard transaction format with specific TSD sections. ```c typedef struct dap_chain_datum_tx_item_groups { dap_list_t *items_in_ems; // Input emission items dap_list_t *items_tsd; // Transaction supplementary data // ... other transaction group fields } dap_chain_datum_tx_item_groups_t; ``` ## Bridge Functions ### Service Management #### `dap_chain_net_srv_bridge_init()` Initializes the bridge service and registers transaction tagging functions. ```c int dap_chain_net_srv_bridge_init(); ``` **Returns:** - `0` - Initialization successful - Non-zero - Initialization failed **Description:** Registers the bridge service with the ledger system and sets up transaction validation callbacks for bridge operation detection. #### `dap_chain_net_srv_bridge_deinit()` Deinitializes the bridge service and cleans up resources. ```c void dap_chain_net_srv_bridge_deinit(); ``` **Description:** Cleans up bridge service resources and unregisters service callbacks. ### Transaction Validation #### `s_tag_check_bridge()` (Internal) Internal function that validates and tags bridge transactions. ```c static bool s_tag_check_bridge( dap_ledger_t *a_ledger, dap_chain_datum_tx_t *a_tx, dap_chain_datum_tx_item_groups_t *a_items_grp, dap_chain_tx_tag_action_type_t *a_action ); ``` **Parameters:** - `a_ledger` (dap_ledger_t *) - Ledger context for validation - `a_tx` (dap_chain_datum_tx_t *) - Transaction to validate - `a_items_grp` (dap_chain_datum_tx_item_groups_t *) - Transaction item groups - `a_action` (dap_chain_tx_tag_action_type_t *) - Output action type **Returns:** - `true` - Transaction is a valid bridge operation - `false` - Transaction is not a bridge operation **Description:** Analyzes transaction structure and TSD data to determine if the transaction represents a bridge operation and classifies the operation type. ### Emission Processing #### `s_get_ems_bridge_action()` (Internal) Analyzes token emissions to determine bridge action type. ```c bool s_get_ems_bridge_action( dap_chain_datum_token_emission_t *a_ems, dap_chain_tx_tag_action_type_t *a_action ); ``` **Parameters:** - `a_ems` (dap_chain_datum_token_emission_t *) - Token emission to analyze - `a_action` (dap_chain_tx_tag_action_type_t *) - Output action type **Returns:** - `true` - Emission is bridge-related - `false` - Emission is not bridge-related **Description:** Examines token emission TSD data to identify bridge operations and classify the specific type of bridge action. #### `s_tsd_str_cmp()` (Internal) Compares TSD data with string constants for bridge identification. ```c static inline int s_tsd_str_cmp( const byte_t *a_tsdata, size_t a_tsdsize, const char *str ); ``` **Parameters:** - `a_tsdata` (const byte_t *) - TSD data bytes - `a_tsdsize` (size_t) - Size of TSD data - `str` (const char *) - String to compare against **Returns:** - `0` - Data matches string - `-1` - Data does not match string ## Typical Examples ### Bridge Service Initialization Example ```c #include <dap_chain_net_srv_bridge.h> void bridge_service_initialization_example() { log_it_info("=== Bridge Service Initialization ==="); // Step 1: Initialize bridge service int init_result = dap_chain_net_srv_bridge_init(); if (init_result == 0) { log_it_info("✓ Bridge service initialized successfully"); log_it_info(" Service ID: 0x%02X", DAP_CHAIN_NET_SRV_BRIDGE_ID); log_it_info(" Transaction tagging: Enabled"); log_it_info(" Cross-chain support: Active"); } else { log_it_error("✗ Bridge service initialization failed: %d", init_result); return; } // Step 2: Verify service registration dap_chain_net_srv_uid_t bridge_uid = { .uint64 = DAP_CHAIN_NET_SRV_BRIDGE_ID }; log_it_info("Bridge service capabilities:"); log_it_info(" • Cross-chain token transfers"); log_it_info(" • Bridge emission validation"); log_it_info(" • Transaction tagging and classification"); log_it_info(" • Legacy bridge format support"); log_it_info(" • Commission handling"); // Service is now ready for bridge operations log_it_info("Bridge service ready for operations"); // Note: Service cleanup will be handled by dap_chain_net_srv_bridge_deinit() // when the application shuts down log_it_info("Bridge service initialization example completed"); } ``` ### Bridge Transaction Detection Example ```c #include <dap_chain_net_srv_bridge.h> #include <dap_chain_datum_tx.h> void bridge_transaction_detection_example() { log_it_info("=== Bridge Transaction Detection Example ==="); // Step 1: Setup ledger context dap_ledger_t *ledger = dap_ledger_by_net_name("backbone"); if (!ledger) { log_it_error("✗ Failed to get ledger for backbone network"); return; } // Step 2: Create example transaction with bridge TSD data dap_chain_datum_tx_t *bridge_tx = dap_chain_datum_tx_create(); if (!bridge_tx) { log_it_error("✗ Failed to create bridge transaction"); return; } // Step 3: Add bridge-specific TSD data const char *bridge_source = DAP_CHAIN_DATUM_TOKEN_EMISSION_SOURCE_BRIDGE; const char *bridge_subtype = DAP_CHAIN_DATUM_TOKEN_EMISSION_SOURCE_SUBTYPE_BRIDGE_TRANSFER; // Add TSD data to identify this as a bridge transaction dap_chain_datum_tx_add_tsd(bridge_tx, DAP_CHAIN_DATUM_EMISSION_TSD_TYPE_SOURCE, bridge_source, strlen(bridge_source)); dap_chain_datum_tx_add_tsd(bridge_tx, DAP_CHAIN_DATUM_EMISSION_TSD_TYPE_SOURCE_SUBTYPE, bridge_subtype, strlen(bridge_subtype)); log_it_info("Created bridge transaction with TSD data:"); log_it_info(" Source: %s", bridge_source); log_it_info(" Subtype: %s", bridge_subtype); // Step 4: Simulate bridge detection (normally done internally) dap_chain_datum_tx_item_groups_t *item_groups = dap_chain_datum_tx_item_groups_create(bridge_tx); if (!item_groups) { log_it_error("✗ Failed to create transaction item groups"); dap_chain_datum_tx_delete(bridge_tx); return; } // Step 5: Check if transaction is detected as bridge operation dap_chain_tx_tag_action_type_t detected_action = DAP_CHAIN_TX_TAG_ACTION_UNKNOWN; // This would normally be called by the ledger service // bool is_bridge = s_tag_check_bridge(ledger, bridge_tx, item_groups, &detected_action); // For demonstration, we'll simulate the detection result bool is_bridge = true; // Would be actual result from s_tag_check_bridge detected_action = DAP_CHAIN_TX_TAG_ACTION_TRANSFER_REGULAR; if (is_bridge) { log_it_info("✓ Transaction detected as bridge operation"); switch (detected_action) { case DAP_CHAIN_TX_TAG_ACTION_TRANSFER_REGULAR: log_it_info(" Action: Regular bridge transfer"); break; case DAP_CHAIN_TX_TAG_ACTION_TRANSFER_COMISSION: log_it_info(" Action: Bridge commission"); break; case DAP_CHAIN_TX_TAG_ACTION_TRANSFER_CROSSCHAIN: log_it_info(" Action: Cross-chain transfer"); break; case DAP_CHAIN_TX_TAG_ACTION_CLOSE: log_it_info(" Action: Bridge closure"); break; default: log_it_info(" Action: Unknown (%d)", detected_action); break; } } else { log_it_info("Transaction not detected as bridge operation"); } // Step 6: Cleanup dap_chain_datum_tx_item_groups_delete(item_groups); dap_chain_datum_tx_delete(bridge_tx); log_it_info("Bridge transaction detection example completed"); } ``` ### Bridge Emission Analysis Example ```c #include <dap_chain_net_srv_bridge.h> #include <dap_chain_datum_token_emission.h> void bridge_emission_analysis_example() { log_it_info("=== Bridge Emission Analysis Example ==="); // Step 1: Create sample emission with bridge TSD data dap_chain_datum_token_emission_t *emission = dap_chain_datum_emission_create( "TESTTOKEN", // Token ticker 1000000000000ULL, // Amount (with decimals) "mJWQjJA4iXQ7HCZkZHgmPFNv9xAA7GV9eMUTjRdBGNBuKVaZZ3qw2k" // Address ); if (!emission) { log_it_error("✗ Failed to create test emission"); return; } // Step 2: Add bridge-specific TSD sections const char *bridge_source = DAP_CHAIN_DATUM_TOKEN_EMISSION_SOURCE_BRIDGE; const char *bridge_subtype = DAP_CHAIN_DATUM_TOKEN_EMISSION_SOURCE_SUBTYPE_BRIDGE_CROSSCHAIN; // Add TSD data dap_chain_datum_emission_add_tsd(emission, DAP_CHAIN_DATUM_EMISSION_TSD_TYPE_SOURCE, strlen(bridge_source), (byte_t*)bridge_source); dap_chain_datum_emission_add_tsd(emission, DAP_CHAIN_DATUM_EMISSION_TSD_TYPE_SOURCE_SUBTYPE, strlen(bridge_subtype), (byte_t*)bridge_subtype); log_it_info("Created bridge emission:"); log_it_info(" Token: TESTTOKEN"); log_it_info(" Amount: 10,000.00000000"); log_it_info(" Source: %s", bridge_source); log_it_info(" Subtype: %s", bridge_subtype); // Step 3: Analyze emission for bridge action dap_chain_tx_tag_action_type_t action_type = DAP_CHAIN_TX_TAG_ACTION_UNKNOWN; // This would normally be called internally by s_get_ems_bridge_action // bool is_bridge_emission = s_get_ems_bridge_action(emission, &action_type); // For demonstration, simulate the analysis bool is_bridge_emission = true; action_type = DAP_CHAIN_TX_TAG_ACTION_TRANSFER_CROSSCHAIN; if (is_bridge_emission) { log_it_info("✓ Emission identified as bridge operation"); switch (action_type) { case DAP_CHAIN_TX_TAG_ACTION_TRANSFER_REGULAR: log_it_info(" Type: Regular bridge transfer emission"); log_it_info(" Purpose: Standard token bridging between networks"); break; case DAP_CHAIN_TX_TAG_ACTION_TRANSFER_COMISSION: log_it_info(" Type: Bridge commission emission"); log_it_info(" Purpose: Fee collection for bridge operations"); break; case DAP_CHAIN_TX_TAG_ACTION_TRANSFER_CROSSCHAIN: log_it_info(" Type: Cross-chain bridge emission"); log_it_info(" Purpose: Inter-blockchain token transfer"); break; case DAP_CHAIN_TX_TAG_ACTION_CLOSE: log_it_info(" Type: Bridge closure emission"); log_it_info(" Purpose: Bridge operation finalization"); break; default: log_it_info(" Type: Unknown bridge action"); break; } log_it_info("Bridge emission processing:"); log_it_info(" ✓ TSD validation passed"); log_it_info(" ✓ Action type classified"); log_it_info(" ✓ Ready for ledger integration"); } else { log_it_info("Emission not identified as bridge operation"); } // Step 4: Check for legacy bridge format support log_it_info("--- Legacy Format Check ---"); // Check if emission has legacy bridge identifiers size_t tsd_size = 0; byte_t *net_id_tsd = dap_chain_emission_get_tsd(emission, DAP_CHAIN_DATUM_EMISSION_TSD_TYPE_NET_ID, &tsd_size); byte_t *block_num_tsd = dap_chain_emission_get_tsd(emission, DAP_CHAIN_DATUM_EMISSION_TSD_TYPE_BLOCK_NUM, &tsd_size); byte_t *tx_hash_tsd = dap_chain_emission_get_tsd(emission, DAP_CHAIN_DATUM_EMISSION_TSD_TYPE_OUTER_TX_HASH, &tsd_size); if (net_id_tsd && block_num_tsd && tx_hash_tsd) { log_it_info("✓ Legacy bridge format detected"); log_it_info(" Contains: NET_ID, BLOCK_NUM, OUTER_TX_HASH"); log_it_info(" Compatibility: Full legacy support enabled"); } else { log_it_info("Modern bridge format (no legacy TSD sections)"); } // Step 5: Cleanup dap_chain_datum_token_emission_delete(emission); log_it_info("Bridge emission analysis example completed"); } ``` --- *See also: [[Modules/Module Service|Module Service]], [[Modules/Module Chain Network|Module Chain Network]], [[ETC/Services Overview|Services Overview]]*