Essential system components, data structures, and fundamental building blocks of the Cellframe SDK. This comprehensive reference covers all core components that form the foundation for blockchain applications. ## Overview Core components form the foundation of all Cellframe SDK operations, providing standardized data structures and interfaces for blockchain functionality. Understanding these components is essential for developing applications, implementing services, and integrating with the blockchain network. **Core Component Categories:** - Universal data containers (Datums) for all blockchain data - Transaction structures and item types for value transfer - Token systems for digital asset management - Address formats for network identity - Cryptographic primitives for security operations - Serialization mechanisms for data exchange **Design Principles:** - **Type Safety** - Strongly typed structures with validation - **Extensibility** - Modular item-based architecture - **Efficiency** - Optimized memory layout and serialization - **Security** - Built-in cryptographic protection ## Document Structure - [[#Overview|Overview]] - [[#Datum System|Datum System]] - [[#Datum Structure|Datum Structure]] - [[#Datum Types|Datum Types]] - [[#Datum Operations|Datum Operations]] - [[#Transaction Architecture|Transaction Architecture]] - [[#Transaction Structure|Transaction Structure]] - [[#Transaction Items|Transaction Items]] - [[#Transaction Creation|Transaction Creation]] - [[#Transaction Validation|Transaction Validation]] - [[#Token Framework|Token Framework]] - [[#Token Types|Token Types]] - [[#Token Operations|Token Operations]] - [[#Token Emission|Token Emission]] - [[#Address System|Address System]] - [[#Address Structure|Address Structure]] - [[#Address Generation|Address Generation]] - [[#Address Validation|Address Validation]] - [[#Cryptographic Components|Cryptographic Components]] - [[#Hash Functions|Hash Functions]] - [[#Digital Signatures|Digital Signatures]] - [[#Key Management|Key Management]] - [[#Serialization & Storage|Serialization & Storage]] - [[#Advanced Usage Patterns|Advanced Usage Patterns]] ## Datum System ### Datum Structure #### Universal Data Container The `dap_chain_datum_t` serves as the universal container for all blockchain data, providing a standardized header and flexible payload system: ```c typedef struct dap_chain_datum { struct { uint8_t version_id; // Protocol version identifier uint16_t type_id; // Data type classification uint32_t data_size; // Payload size in bytes uint64_t ts_create; // Creation timestamp (Unix epoch) } header; uint8_t data[]; // Variable-length payload } dap_chain_datum_t; ``` **Header Fields:** - `version_id` - Protocol version for backward compatibility - `type_id` - Identifies the data type (transaction, token, etc.) - `data_size` - Size of the payload data in bytes - `ts_create` - Creation timestamp for ordering and validation ### Datum Types #### Standard Datum Classifications ```c // Core datum types with their hexadecimal identifiers typedef enum dap_chain_datum_type { DAP_CHAIN_DATUM_TX = 0x0100, // Standard transaction DAP_CHAIN_DATUM_TOKEN = 0xf000, // Token declaration DAP_CHAIN_DATUM_TOKEN_EMISSION = 0xf100, // Token emission event DAP_CHAIN_DATUM_DECREE = 0x0200, // Governance decree DAP_CHAIN_DATUM_ANCHOR = 0x0a00, // Data anchor/reference DAP_CHAIN_DATUM_CA = 0x0c00, // Certificate authority DAP_CHAIN_DATUM_SIGNER = 0x0c01, // Digital signer DAP_CHAIN_DATUM_CUSTOM = 0xffff // Custom application data } dap_chain_datum_type_t; ``` **Type Categories:** - **0x01xx** - Transaction-related datums - **0x02xx** - Governance and decree datums - **0x0axx** - Data anchoring and reference datums - **0x0cxx** - Certificate and identity datums - **0xf0xx** - Token system datums - **0xffxx** - Custom application datums ### Datum Operations #### Complete Datum Management ```c // Advanced datum creation with validation dap_chain_datum_t* create_datum_safe(dap_chain_datum_type_t type, const void *data, size_t data_size) { // Validate input parameters if (!data || data_size == 0) { log_it(L_ERROR, "Invalid datum parameters: data=%p, size=%zu", data, data_size); return NULL; } if (data_size > DAP_CHAIN_DATUM_MAX_SIZE) { log_it(L_ERROR, "Datum size exceeds maximum: %zu > %u", data_size, DAP_CHAIN_DATUM_MAX_SIZE); return NULL; } // Create datum with proper initialization dap_chain_datum_t *datum = dap_chain_datum_create(type, data, data_size); if (!datum) { log_it(L_ERROR, "Failed to create datum of type 0x%04X", type); return NULL; } // Verify datum integrity if (!validate_datum_integrity(datum)) { log_it(L_ERROR, "Datum integrity validation failed"); dap_chain_datum_delete(datum); return NULL; } log_it(L_INFO, "Created datum: type=0x%04X, size=%zu bytes", type, data_size); return datum; } // Datum hash calculation with error handling int calculate_datum_hash(const dap_chain_datum_t *datum, dap_hash_fast_t *hash) { if (!datum || !hash) { log_it(L_ERROR, "Invalid parameters for hash calculation"); return -1; } // Calculate hash of the entire datum size_t datum_size = dap_chain_datum_size(datum); dap_hash_fast(datum, datum_size, hash); // Log hash for debugging char *hash_str = dap_chain_hash_fast_to_str_new(hash); log_it(L_DEBUG, "Datum hash calculated: %s", hash_str); DAP_DELETE(hash_str); return 0; } // Datum validation and verification bool validate_datum_integrity(const dap_chain_datum_t *datum) { if (!datum) { return false; } // Check header consistency size_t expected_size = sizeof(datum->header) + datum->header.data_size; size_t actual_size = dap_chain_datum_size(datum); if (expected_size != actual_size) { log_it(L_ERROR, "Datum size mismatch: expected=%zu, actual=%zu", expected_size, actual_size); return false; } // Validate timestamp uint64_t current_time = time(NULL); if (datum->header.ts_create > current_time + DATUM_TIME_TOLERANCE) { log_it(L_ERROR, "Datum timestamp in future: %lu > %lu", datum->header.ts_create, current_time); return false; } // Type-specific validation switch (datum->header.type_id) { case DAP_CHAIN_DATUM_TX: return validate_transaction_datum(datum); case DAP_CHAIN_DATUM_TOKEN: return validate_token_datum(datum); case DAP_CHAIN_DATUM_TOKEN_EMISSION: return validate_emission_datum(datum); default: // Basic validation for unknown types return datum->header.data_size > 0; } } ``` ## Transaction Architecture ### Transaction Structure #### Modular Transaction Design ```c typedef struct dap_chain_datum_tx { struct { uint64_t ts_created; // Transaction creation timestamp uint32_t tx_items_size; // Total size of all transaction items uint8_t reserved[4]; // Reserved for future use } header; uint8_t tx_items[]; // Variable-length array of transaction items } dap_chain_datum_tx_t; ``` **Transaction Components:** - **Header** - Metadata including timestamp and size information - **Items Array** - Sequential collection of typed transaction items - **Flexible Structure** - Supports any combination of item types ### Transaction Items #### Comprehensive Item Type System ```c // Transaction item types for complete functionality typedef enum dap_chain_tx_item_type { // Input item types TX_ITEM_TYPE_IN = 0x00, // Standard input TX_ITEM_TYPE_IN_COND = 0x01, // Conditional input TX_ITEM_TYPE_IN_EMS = 0x02, // Token emission input TX_ITEM_TYPE_IN_REWARD = 0x03, // Mining/staking reward // Output item types TX_ITEM_TYPE_OUT = 0x10, // Standard output TX_ITEM_TYPE_OUT_COND = 0x11, // Conditional output TX_ITEM_TYPE_OUT_EXT = 0x12, // Extended output TX_ITEM_TYPE_OUT_OLD = 0x13, // Legacy output format // Metadata item types TX_ITEM_TYPE_PKEY = 0x20, // Public key TX_ITEM_TYPE_SIG = 0x21, // Digital signature TX_ITEM_TYPE_TOKEN = 0x22, // Token information TX_ITEM_TYPE_RECEIPT = 0x23, // Service receipt TX_ITEM_TYPE_TSD = 0x24 // Tagged structured data } dap_chain_tx_item_type_t; ``` #### Advanced Transaction Item Examples ```c // Standard input item - references previous transaction output typedef struct dap_chain_tx_in { dap_chain_hash_fast_t prev_hash; // Previous transaction hash uint32_t out_prev_idx; // Output index in previous tx uint8_t reserved[4]; // Reserved for future use } DAP_ALIGN_PACKED dap_chain_tx_in_t; // Conditional input with smart contract integration typedef struct dap_chain_tx_in_cond { dap_chain_hash_fast_t prev_hash; // Previous transaction hash uint32_t out_prev_idx; // Output index in previous tx uint32_t receipt_idx; // Receipt index for conditions uint8_t reserved[4]; // Reserved for future use } DAP_ALIGN_PACKED dap_chain_tx_in_cond_t; // Standard output with recipient address typedef struct dap_chain_tx_out { dap_chain_addr_t addr; // Recipient address uint64_t value; // Value in atomic units uint8_t reserved[8]; // Reserved for future use } DAP_ALIGN_PACKED dap_chain_tx_out_t; // Extended output with additional data typedef struct dap_chain_tx_out_ext { dap_chain_addr_t addr; // Recipient address uint64_t value; // Value in atomic units char token[DAP_CHAIN_TICKER_SIZE_MAX]; // Token ticker uint32_t subtype; // Output subtype uint8_t reserved[4]; // Reserved for future use } DAP_ALIGN_PACKED dap_chain_tx_out_ext_t; ``` ### Transaction Creation #### Professional Transaction Builder ```c // Advanced transaction creation with comprehensive validation dap_chain_datum_tx_t* create_transaction_advanced( const transaction_spec_t *spec) { log_it(L_INFO, "=== Creating Advanced Transaction ==="); // Validate transaction specification if (!validate_transaction_spec(spec)) { log_it(L_ERROR, "Invalid transaction specification"); return NULL; } // Create base transaction dap_chain_datum_tx_t *tx = dap_chain_datum_tx_create(); if (!tx) { log_it(L_ERROR, "Failed to create base transaction"); return NULL; } // Add inputs with validation for (size_t i = 0; i < spec->input_count; i++) { if (add_transaction_input(tx, &spec->inputs[i]) != 0) { log_it(L_ERROR, "Failed to add input %zu", i); goto cleanup_transaction; } } // Add outputs with validation uint64_t total_output = 0; for (size_t i = 0; i < spec->output_count; i++) { if (add_transaction_output(tx, &spec->outputs[i]) != 0) { log_it(L_ERROR, "Failed to add output %zu", i); goto cleanup_transaction; } total_output += spec->outputs[i].value; } // Validate transaction balance uint64_t total_input = calculate_total_input_value(spec); if (total_input < total_output + spec->fee) { log_it(L_ERROR, "Insufficient input value: %lu < %lu + %lu", total_input, total_output, spec->fee); goto cleanup_transaction; } // Add public key if required if (spec->public_key) { if (add_transaction_public_key(tx, spec->public_key) != 0) { log_it(L_ERROR, "Failed to add public key"); goto cleanup_transaction; } } // Add signature for transaction security if (spec->private_key) { if (sign_transaction(tx, spec->private_key) != 0) { log_it(L_ERROR, "Failed to sign transaction"); goto cleanup_transaction; } } // Perform final validation if (!validate_transaction_complete(tx)) { log_it(L_ERROR, "Transaction validation failed"); goto cleanup_transaction; } log_it(L_INFO, "✓ Transaction created successfully"); return tx; cleanup_transaction: dap_chain_datum_tx_delete(tx); return NULL; } // Add transaction input with comprehensive validation int add_transaction_input(dap_chain_datum_tx_t **tx, const input_spec_t *input_spec) { if (!tx || !*tx || !input_spec) { log_it(L_ERROR, "Invalid parameters for input addition"); return -1; } // Validate previous transaction reference if (dap_hash_fast_is_blank(&input_spec->prev_hash)) { log_it(L_ERROR, "Invalid previous transaction hash"); return -1; } // Create input item based on type switch (input_spec->type) { case INPUT_TYPE_STANDARD: { dap_chain_tx_in_t input = {0}; memcpy(&input.prev_hash, &input_spec->prev_hash, sizeof(dap_chain_hash_fast_t)); input.out_prev_idx = input_spec->out_prev_idx; return dap_chain_datum_tx_add_item(tx, TX_ITEM_TYPE_IN, &input, sizeof(input)); } case INPUT_TYPE_CONDITIONAL: { dap_chain_tx_in_cond_t input_cond = {0}; memcpy(&input_cond.prev_hash, &input_spec->prev_hash, sizeof(dap_chain_hash_fast_t)); input_cond.out_prev_idx = input_spec->out_prev_idx; input_cond.receipt_idx = input_spec->receipt_idx; return dap_chain_datum_tx_add_item(tx, TX_ITEM_TYPE_IN_COND, &input_cond, sizeof(input_cond)); } default: log_it(L_ERROR, "Unsupported input type: %d", input_spec->type); return -1; } } ``` ### Transaction Validation #### Multi-Level Validation System ```c // Comprehensive transaction validation pipeline validation_result_t validate_transaction_comprehensive( const dap_chain_datum_tx_t *tx, const dap_chain_t *chain) { validation_result_t result = {0}; result.is_valid = false; log_it(L_DEBUG, "=== Validating Transaction ==="); // Level 1: Structure validation if (!validate_transaction_structure(tx, &result)) { log_it(L_ERROR, "Transaction structure validation failed"); return result; } // Level 2: Item validation if (!validate_transaction_items(tx, &result)) { log_it(L_ERROR, "Transaction items validation failed"); return result; } // Level 3: Cryptographic validation if (!validate_transaction_signatures(tx, &result)) { log_it(L_ERROR, "Transaction signature validation failed"); return result; } // Level 4: Economic validation if (!validate_transaction_economics(tx, chain, &result)) { log_it(L_ERROR, "Transaction economic validation failed"); return result; } // Level 5: Chain state validation if (!validate_transaction_state(tx, chain, &result)) { log_it(L_ERROR, "Transaction state validation failed"); return result; } result.is_valid = true; log_it(L_INFO, "✓ Transaction validation successful"); return result; } // Transaction structure validation bool validate_transaction_structure(const dap_chain_datum_tx_t *tx, validation_result_t *result) { if (!tx) { result->error_code = VALIDATION_ERROR_NULL_TRANSACTION; return false; } // Check header validity if (tx->header.tx_items_size == 0) { result->error_code = VALIDATION_ERROR_EMPTY_TRANSACTION; return false; } // Check timestamp uint64_t current_time = time(NULL); if (tx->header.ts_created > current_time + TRANSACTION_TIME_TOLERANCE) { result->error_code = VALIDATION_ERROR_FUTURE_TIMESTAMP; return false; } // Check size limits size_t tx_size = dap_chain_datum_tx_get_size(tx); if (tx_size > DAP_CHAIN_TX_MAX_SIZE) { result->error_code = VALIDATION_ERROR_OVERSIZED_TRANSACTION; return false; } return true; } ``` ## Token Framework ### Token Types #### Comprehensive Token System ```c // Token type definitions with capabilities typedef enum dap_chain_datum_token_type { DAP_CHAIN_DATUM_TOKEN_TYPE_SIMPLE = 0x0001, // Fixed supply token DAP_CHAIN_DATUM_TOKEN_TYPE_DELEGATED = 0x0002, // Delegated emission DAP_CHAIN_DATUM_TOKEN_TYPE_PRIVATE = 0x0004, // Private balances DAP_CHAIN_DATUM_TOKEN_TYPE_NATIVE = 0x0008, // Native network token DAP_CHAIN_DATUM_TOKEN_TYPE_CF20 = 0x0010, // CF20 standard token DAP_CHAIN_DATUM_TOKEN_TYPE_NFT = 0x0020 // Non-fungible token } dap_chain_datum_token_type_t; // Complete token structure typedef struct dap_chain_datum_token { uint16_t type; // Token type flags char ticker[DAP_CHAIN_TICKER_SIZE_MAX]; // Token ticker symbol uint64_t total_supply; // Maximum token supply uint16_t signs_valid; // Required valid signatures uint16_t signs_total; // Total signatures needed uint64_t header_private_size; // Private data size uint64_t header_native_size; // Native data size uint8_t reserved[16]; // Reserved for extensions uint8_t data[]; // Variable token data } DAP_ALIGN_PACKED dap_chain_datum_token_t; ``` ### Token Operations #### Advanced Token Management ```c // Create comprehensive token with all features dap_chain_datum_token_t* create_advanced_token(const token_spec_t *spec) { log_it(L_INFO, "=== Creating Advanced Token ==="); // Validate token specification if (!validate_token_spec(spec)) { log_it(L_ERROR, "Invalid token specification"); return NULL; } // Calculate total token size size_t total_size = sizeof(dap_chain_datum_token_t) + spec->private_data_size + spec->native_data_size; // Allocate token structure dap_chain_datum_token_t *token = DAP_NEW_Z_SIZE(dap_chain_datum_token_t, total_size); if (!token) { log_it(L_ERROR, "Failed to allocate token structure"); return NULL; } // Initialize token header token->type = spec->type; strncpy(token->ticker, spec->ticker, DAP_CHAIN_TICKER_SIZE_MAX - 1); token->total_supply = spec->total_supply; token->signs_valid = spec->signs_valid; token->signs_total = spec->signs_total; token->header_private_size = spec->private_data_size; token->header_native_size = spec->native_data_size; // Copy private data if present if (spec->private_data && spec->private_data_size > 0) { memcpy(token->data, spec->private_data, spec->private_data_size); } // Copy native data if present if (spec->native_data && spec->native_data_size > 0) { memcpy(token->data + spec->private_data_size, spec->native_data, spec->native_data_size); } log_it(L_INFO, "✓ Token created: %s (type=0x%04X, supply=%lu)", token->ticker, token->type, token->total_supply); return token; } ``` ### Token Emission #### Controlled Token Emission System ```c // Create token emission with comprehensive validation dap_chain_datum_token_emission_t* create_token_emission( const emission_spec_t *spec) { log_it(L_INFO, "=== Creating Token Emission ==="); // Validate emission specification if (!validate_emission_spec(spec)) { log_it(L_ERROR, "Invalid emission specification"); return NULL; } // Check emission permissions if (!check_emission_permissions(spec)) { log_it(L_ERROR, "Insufficient emission permissions"); return NULL; } // Create emission structure dap_chain_datum_token_emission_t *emission = dap_chain_datum_token_emission_create( spec->token_ticker, spec->emission_value, &spec->emission_addr, spec->emission_hash ); if (!emission) { log_it(L_ERROR, "Failed to create emission structure"); return NULL; } // Add signatures for authorization for (size_t i = 0; i < spec->signature_count; i++) { if (dap_chain_datum_token_emission_add_sign( emission, spec->signatures[i]) != 0) { log_it(L_ERROR, "Failed to add emission signature %zu", i); dap_chain_datum_token_emission_delete(emission); return NULL; } } log_it(L_INFO, "✓ Token emission created: %s, value=%lu", spec->token_ticker, spec->emission_value); return emission; } ``` ## Address System ### Address Structure #### Network-Aware Address Format ```c typedef struct dap_chain_addr { union { struct { uint64_t net_id; // Network identifier dap_chain_hash_fast_t addr; // Address hash }; uint8_t data[sizeof(uint64_t) + sizeof(dap_chain_hash_fast_t)]; }; uint8_t checksum[2]; // Address checksum } DAP_ALIGN_PACKED dap_chain_addr_t; ``` ### Address Generation #### Comprehensive Address Management ```c // Generate address from key with network specification int generate_address_from_key(const dap_enc_key_t *key, uint64_t net_id, dap_chain_addr_t *addr_out) { if (!key || !addr_out) { log_it(L_ERROR, "Invalid parameters for address generation"); return -1; } // Clear output address memset(addr_out, 0, sizeof(dap_chain_addr_t)); // Set network ID addr_out->net_id = net_id; // Generate address hash from public key size_t pub_key_size = 0; uint8_t *pub_key_data = dap_enc_key_serialize_pub_key(key, &pub_key_size); if (!pub_key_data) { log_it(L_ERROR, "Failed to serialize public key"); return -1; } // Calculate address hash dap_hash_fast(pub_key_data, pub_key_size, &addr_out->addr); DAP_DELETE(pub_key_data); // Calculate and set checksum calculate_address_checksum(addr_out); // Validate generated address if (!dap_chain_addr_check_sum(addr_out)) { log_it(L_ERROR, "Generated address checksum validation failed"); return -1; } char *addr_str = dap_chain_addr_to_str(addr_out); log_it(L_INFO, "✓ Address generated: %s", addr_str); DAP_DELETE(addr_str); return 0; } // Calculate address checksum for integrity void calculate_address_checksum(dap_chain_addr_t *addr) { if (!addr) return; // Calculate hash of address data (excluding checksum) dap_hash_fast_t hash; dap_hash_fast(addr->data, sizeof(addr->data), &hash); // Use first 2 bytes of hash as checksum memcpy(addr->checksum, hash.raw, 2); } ``` ### Address Validation #### Multi-Level Address Verification ```c // Comprehensive address validation address_validation_result_t validate_address_comprehensive( const dap_chain_addr_t *addr, uint64_t expected_net_id) { address_validation_result_t result = {0}; if (!addr) { result.error_code = ADDR_ERROR_NULL_ADDRESS; return result; } // Validate network ID if (expected_net_id != 0 && addr->net_id != expected_net_id) { result.error_code = ADDR_ERROR_INVALID_NETWORK; result.expected_net_id = expected_net_id; result.actual_net_id = addr->net_id; return result; } // Validate checksum if (!dap_chain_addr_check_sum(addr)) { result.error_code = ADDR_ERROR_INVALID_CHECKSUM; return result; } // Validate address hash is not blank if (dap_hash_fast_is_blank(&addr->addr)) { result.error_code = ADDR_ERROR_BLANK_HASH; return result; } result.is_valid = true; return result; } ``` ## Cryptographic Components ### Hash Functions #### Multi-Algorithm Hash System ```c // Comprehensive hash function interface typedef struct hash_context { hash_algorithm_t algorithm; void *state; size_t output_size; } hash_context_t; // Initialize hash context for specific algorithm hash_context_t* hash_init(hash_algorithm_t algorithm) { hash_context_t *ctx = DAP_NEW_Z(hash_context_t); if (!ctx) { log_it(L_ERROR, "Failed to allocate hash context"); return NULL; } ctx->algorithm = algorithm; switch (algorithm) { case HASH_ALGORITHM_FAST: ctx->output_size = sizeof(dap_hash_fast_t); ctx->state = dap_hash_fast_new(); break; case HASH_ALGORITHM_SHA256: ctx->output_size = 32; ctx->state = dap_hash_sha256_new(); break; case HASH_ALGORITHM_SHA512: ctx->output_size = 64; ctx->state = dap_hash_sha512_new(); break; default: log_it(L_ERROR, "Unsupported hash algorithm: %d", algorithm); DAP_DELETE(ctx); return NULL; } if (!ctx->state) { log_it(L_ERROR, "Failed to initialize hash state"); DAP_DELETE(ctx); return NULL; } return ctx; } // Update hash with data int hash_update(hash_context_t *ctx, const void *data, size_t size) { if (!ctx || !data || size == 0) { return -1; } switch (ctx->algorithm) { case HASH_ALGORITHM_FAST: return dap_hash_fast_update(ctx->state, data, size); case HASH_ALGORITHM_SHA256: return dap_hash_sha256_update(ctx->state, data, size); case HASH_ALGORITHM_SHA512: return dap_hash_sha512_update(ctx->state, data, size); default: return -1; } } // Finalize hash computation int hash_final(hash_context_t *ctx, void *hash_out) { if (!ctx || !hash_out) { return -1; } int result; switch (ctx->algorithm) { case HASH_ALGORITHM_FAST: result = dap_hash_fast_final(ctx->state, hash_out); break; case HASH_ALGORITHM_SHA256: result = dap_hash_sha256_final(ctx->state, hash_out); break; case HASH_ALGORITHM_SHA512: result = dap_hash_sha512_final(ctx->state, hash_out); break; default: result = -1; } // Cleanup state DAP_DELETE(ctx->state); DAP_DELETE(ctx); return result; } ``` ### Digital Signatures #### Post-Quantum Signature System ```c // Multi-algorithm signature interface signature_result_t create_signature_advanced(const signature_spec_t *spec) { signature_result_t result = {0}; log_it(L_INFO, "=== Creating Digital Signature ==="); // Validate specification if (!validate_signature_spec(spec)) { result.error_code = SIG_ERROR_INVALID_SPEC; return result; } // Create signature based on key type switch (spec->key->type) { case DAP_ENC_KEY_TYPE_SIG_DILITHIUM: result.signature = create_dilithium_signature(spec); result.algorithm = SIG_ALGORITHM_DILITHIUM; break; case DAP_ENC_KEY_TYPE_SIG_FALCON: result.signature = create_falcon_signature(spec); result.algorithm = SIG_ALGORITHM_FALCON; break; case DAP_ENC_KEY_TYPE_SIG_SPHINCS: result.signature = create_sphincs_signature(spec); result.algorithm = SIG_ALGORITHM_SPHINCS; break; default: log_it(L_ERROR, "Unsupported signature key type: %d", spec->key->type); result.error_code = SIG_ERROR_UNSUPPORTED_ALGORITHM; return result; } if (!result.signature) { result.error_code = SIG_ERROR_CREATION_FAILED; return result; } // Verify signature immediately int verify_result = dap_sign_verify(result.signature, spec->key, spec->data, spec->data_size); if (verify_result != 1) { log_it(L_ERROR, "Signature verification failed immediately after creation"); dap_sign_delete(result.signature); result.signature = NULL; result.error_code = SIG_ERROR_VERIFICATION_FAILED; return result; } result.is_valid = true; log_it(L_INFO, "✓ Signature created and verified successfully"); return result; } ``` ## Serialization & Storage ### Data Serialization #### Universal Serialization Framework ```c // Comprehensive serialization interface typedef struct serialization_context { serialization_format_t format; dap_stream_t *stream; size_t bytes_written; bool error_occurred; } serialization_context_t; // Initialize serialization context serialization_context_t* serialization_init(serialization_format_t format) { serialization_context_t *ctx = DAP_NEW_Z(serialization_context_t); if (!ctx) { log_it(L_ERROR, "Failed to allocate serialization context"); return NULL; } ctx->format = format; ctx->stream = dap_stream_new(); if (!ctx->stream) { log_it(L_ERROR, "Failed to create serialization stream"); DAP_DELETE(ctx); return NULL; } return ctx; } // Serialize datum to context int serialize_datum(serialization_context_t *ctx, const dap_chain_datum_t *datum) { if (!ctx || !datum) { return -1; } switch (ctx->format) { case SERIALIZATION_FORMAT_BINARY: return serialize_datum_binary(ctx, datum); case SERIALIZATION_FORMAT_JSON: return serialize_datum_json(ctx, datum); case SERIALIZATION_FORMAT_CBOR: return serialize_datum_cbor(ctx, datum); default: log_it(L_ERROR, "Unsupported serialization format: %d", ctx->format); return -1; } } // Get serialized data int serialization_get_data(serialization_context_t *ctx, uint8_t **data_out, size_t *size_out) { if (!ctx || !data_out || !size_out) { return -1; } if (ctx->error_occurred) { log_it(L_ERROR, "Serialization context has errors"); return -1; } return dap_stream_get_data(ctx->stream, data_out, size_out); } ``` ## Advanced Usage Patterns ### Pattern 1: Transaction Builder ```c // Fluent interface for transaction building transaction_builder_t* tx_builder_new(void) { transaction_builder_t *builder = DAP_NEW_Z(transaction_builder_t); builder->tx = dap_chain_datum_tx_create(); return builder; } transaction_builder_t* tx_builder_add_input(transaction_builder_t *builder, const dap_chain_hash_fast_t *prev_hash, uint32_t out_idx) { // Add input implementation return builder; } transaction_builder_t* tx_builder_add_output(transaction_builder_t *builder, const dap_chain_addr_t *addr, uint64_t value) { // Add output implementation return builder; } dap_chain_datum_tx_t* tx_builder_finalize(transaction_builder_t *builder, const dap_enc_key_t *signing_key) { // Finalize and sign transaction dap_chain_datum_tx_t *result = builder->tx; builder->tx = NULL; DAP_DELETE(builder); return result; } ``` ### Pattern 2: Validation Pipeline ```c // Composable validation pipeline typedef struct validation_pipeline { validation_step_t *steps; size_t step_count; bool fail_fast; } validation_pipeline_t; validation_pipeline_t* validation_pipeline_create(bool fail_fast) { validation_pipeline_t *pipeline = DAP_NEW_Z(validation_pipeline_t); pipeline->fail_fast = fail_fast; return pipeline; } void validation_pipeline_add_step(validation_pipeline_t *pipeline, validation_step_func_t func, void *user_data) { // Add validation step } validation_result_t validation_pipeline_execute(validation_pipeline_t *pipeline, const void *data) { // Execute all validation steps validation_result_t result = {0}; for (size_t i = 0; i < pipeline->step_count; i++) { validation_result_t step_result = pipeline->steps[i].func(data, pipeline->steps[i].user_data); if (!step_result.is_valid) { result = step_result; if (pipeline->fail_fast) { break; } } } return result; } ``` --- **See also:** [[Architecture Overview|Architecture Overview]], [[First Application|First Application]], [[Development Guide|Development Guide]], [[Modules/Module Overview|Module Overview]]