## Overview The Module Common serves as the foundational layer of the Cellframe SDK, providing essential data structures and types used throughout the entire blockchain framework. This module defines core blockchain concepts including datums (atomic data units), transactions, tokens, and other fundamental structures that enable the creation and management of blockchain networks. ## Common Core *Based on: `dap_chain_common.h`, `dap_chain_common.c`, `dap_chain_datum.h`, `dap_chain_datum.c`, `dap_chain_datum_token.h`, `dap_chain_datum_token.c`, `dap_chain_datum_tx.h`, `dap_chain_datum_tx.c`, `dap_chain_datum_decree.h`, `dap_chain_datum_decree.c`, `dap_chain_datum_hashtree_roots.h`, `dap_chain_datum_hashtree_roots.c`, `dap_chain_datum_anchor.h`, `dap_chain_datum_tx_items.h`, `dap_chain_datum_tx_items.c`, `dap_chain_datum_tx_in.h`, `dap_chain_datum_tx_in_cond.h`, `dap_chain_datum_tx_in_ems.h`, `dap_chain_datum_tx_in_reward.h`, `dap_chain_datum_tx_out.h`, `dap_chain_datum_tx_out_cond.h`, `dap_chain_datum_tx_pkey.h`, `dap_chain_datum_tx_receipt.h`, `dap_chain_datum_tx_sig.h`, `dap_chain_datum_tx_tsd.h`, `dap_chain_datum_tx_voting.h`* ## Document Structure - [[#Overview|Overview]] - [[#Common Core|Common Core]] - Basic blockchain types and address management - [[#Datum|Datum]] - Basic datum structures and operations - [[#Token|Token]] - Token definition and management structures - [[#Transaction Core|Transaction Core]] - Basic transaction structures - [[#Transaction Items|Transaction Items]] - Transaction components and items - [[#Transaction Components|Transaction Components]] - Emission inputs, signatures, voting, receipts, rewards - [[#Anchor|Anchor]] - Anchor structures for cross-chain operations - [[#Decree|Decree]] - Governance and decree structures - [[#Other Components|Other Components]] - Additional datum types --- ## Common Core *Based on: `dap_chain_common.h` and `dap_chain_common.c`* ### Overview Core blockchain identifiers, address structures, and fundamental operations providing the foundation for all blockchain functionality. ### Document Structure - [[#Overview|Overview]] - [[#Enumerations|Enumerations]] - [[#Node Role Enumeration|Node Role Enumeration - Node capability definitions]] - [[#dap_chain_hash_slow_kind_t|dap_chain_hash_slow_kind_t - Hash quality classification]] - [[#dap_chain_srv_unit_enum|dap_chain_srv_unit_enum - Service unit types]] - [[#dap_chain_tx_item_type|dap_chain_tx_item_type - Transaction item types]] - [[#Structures|Structures]] - [[#dap_chain_id_t|dap_chain_id_t - Chain identifier]] - [[#dap_chain_cell_id_t|dap_chain_cell_id_t - Cell identifier]] - [[#dap_chain_net_id_t|dap_chain_net_id_t - Network identifier]] - [[#dap_chain_node_role_t|dap_chain_node_role_t - Node role definition]] - [[#dap_chain_addr_t|dap_chain_addr_t - Blockchain address]] - [[#dap_chain_net_srv_uid_t|dap_chain_net_srv_uid_t - Service identifier]] - [[#dap_chain_hash_slow_t|dap_chain_hash_slow_t - Slow hash for mining]] - [[#dap_chain_addr_str_t|dap_chain_addr_str_t - Address string representation]] - [[#dap_chain_token_ticker_str_t|dap_chain_token_ticker_str_t - Token ticker string]] - [[#dap_chain_net_srv_price_unit_uid_t|dap_chain_net_srv_price_unit_uid_t - Price unit identifier]] - [[#Functions|Functions]] - [[#Hash Operations|Hash Operations]] - [[#Address Operations|Address Operations]] - [[#Utility Functions|Utility Functions]] ### Enumerations #### Node Role Enumeration ```c enum { NODE_ROLE_ROOT_MASTER = 0x00, // Root master node NODE_ROLE_ROOT = 0x01, // Root node NODE_ROLE_ARCHIVE = 0x02, // Archive node NODE_ROLE_CELL_MASTER = 0x10, // Cell master node NODE_ROLE_MASTER = 0x20, // Master node NODE_ROLE_FULL = 0xf0, // Full node NODE_ROLE_LIGHT = 0xff // Light node }; ``` #### dap_chain_hash_slow_kind_t Hash quality classification for slow hash operations. ```c typedef enum dap_chain_hash_slow_kind { HASH_GOLD = 0, // High-quality hash HASH_SILVER, // Medium-quality hash HASH_COPPER, // Low-quality hash HASH_USELESS = -1 // Unusable hash } dap_chain_hash_slow_kind_t; ``` #### dap_chain_srv_unit_enum Service unit enumeration for pricing and measurements. ```c enum dap_chain_srv_unit_enum { SERV_UNIT_UNDEFINED = 0, // Undefined unit SERV_UNIT_SEC = 0x00000002, // Seconds SERV_UNIT_B = 0x00000011, // Bytes SERV_UNIT_PCS = 0x00000022 // Pieces }; ``` #### dap_chain_tx_item_type Transaction item type definitions. ```c enum dap_chain_tx_item_type { // Transaction inputs TX_ITEM_TYPE_IN = 0x00, // Basic input TX_ITEM_TYPE_IN_COND = 0x50, // Conditional input TX_ITEM_TYPE_IN_REWARD = 0x07, // Reward input TX_ITEM_TYPE_IN_EMS = 0x40, // Emission input // Transaction outputs TX_ITEM_TYPE_OUT_OLD = 0x10, // Deprecated output TX_ITEM_TYPE_OUT_EXT = 0x11, // Extended output TX_ITEM_TYPE_OUT = 0x12, // Standard output TX_ITEM_TYPE_OUT_STD = 0x13, // Standard output v2 TX_ITEM_TYPE_OUT_COND = 0x61, // Conditional output // Transaction misc TX_ITEM_TYPE_PKEY = 0x20, // Public key TX_ITEM_TYPE_SIG = 0x30, // Signature TX_ITEM_TYPE_RECEIPT = 0x70, // Receipt TX_ITEM_TYPE_TSD = 0x80, // Type-specific data // Transaction voting TX_ITEM_TYPE_VOTING = 0x90, // Voting item TX_ITEM_TYPE_VOTE = 0x91, // Vote item // Virtual types TX_ITEM_TYPE_IN_EMS_LOCK = 0xf1, // Locked emission input TX_ITEM_TYPE_IN_ALL = 0xfd, // All input types TX_ITEM_TYPE_OUT_ALL = 0xfe, // All output types TX_ITEM_TYPE_ANY = 0xff // Any type }; ``` ### Structures #### dap_chain_id_t Chain identifier union for unique chain identification. ```c typedef union dap_chain_id { uint8_t raw[DAP_CHAIN_ID_SIZE]; // Raw bytes representation uint64_t uint64; // 64-bit integer representation } DAP_ALIGN_PACKED dap_chain_id_t; ``` **Fields:** - `raw` - Raw 8-byte array representation of chain ID - `uint64` - 64-bit unsigned integer representation for easier comparison #### dap_chain_cell_id_t Cell (shard) identifier union for chain subdivision. ```c typedef union dap_chain_cell_id { uint8_t raw[DAP_CHAIN_SHARD_ID_SIZE]; // Raw bytes representation uint64_t uint64; // 64-bit integer representation } DAP_ALIGN_PACKED dap_chain_cell_id_t; ``` **Fields:** - `raw` - Raw 8-byte array representation of cell ID - `uint64` - 64-bit unsigned integer representation #### dap_chain_net_id_t Network identifier union for different network types. ```c typedef union dap_chain_net_id { uint64_t uint64; // 64-bit integer representation uint8_t raw[DAP_CHAIN_NET_ID_SIZE]; // Raw bytes representation } DAP_ALIGN_PACKED dap_chain_net_id_t; ``` **Fields:** - `uint64` - 64-bit unsigned integer representation - `raw` - Raw 8-byte array representation of network ID #### dap_chain_node_role_t Node role union defining the capabilities and responsibilities of a node. ```c typedef union dap_chain_node_role { uint32_t enums; // Enumeration value uint8_t raw[DAP_CHAIN_NODE_ROLE_SIZE]; // Raw bytes representation } DAP_ALIGN_PACKED dap_chain_node_role_t; ``` **Fields:** - `enums` - 32-bit enumeration value representing node role - `raw` - Raw 4-byte array representation #### dap_chain_addr_t Blockchain address structure supporting multiple address types and signature schemes. ```c typedef struct dap_chain_addr { uint8_t addr_ver; // Address version (0 for default) dap_chain_net_id_t net_id; // Network ID (testnet, mainnet, etc.) dap_sign_type_t sig_type; // Signature type used union { struct { uint8_t key_spend[sizeof(dap_chain_hash_fast_t)/2]; // Spend key uint8_t key_view[sizeof(dap_chain_hash_fast_t)/2]; // View key } DAP_ALIGN_PACKED key_sv; uint8_t key[sizeof(dap_chain_hash_fast_t)]; // Key data uint8_t hash[sizeof(dap_chain_hash_fast_t)]; // Hash data dap_chain_hash_fast_t hash_fast; // Fast hash } DAP_ALIGN_PACKED data; dap_chain_hash_fast_t checksum; // Address checksum for validation } DAP_ALIGN_PACKED dap_chain_addr_t; ``` **Fields:** - `addr_ver` - Address format version identifier - `net_id` - Network this address belongs to - `sig_type` - Cryptographic signature type used for this address - `data` - Union containing address data (keys or hash) - `checksum` - Validation checksum for address integrity #### dap_chain_net_srv_uid_t Network service unique identifier for service identification. ```c typedef union { uint8_t raw[DAP_CHAIN_NET_SRV_UID_SIZE]; // Raw bytes representation uint64_t raw_ui64; // Alternative 64-bit access uint64_t uint64; // 64-bit integer representation } dap_chain_net_srv_uid_t; ``` **Fields:** - `raw` - Raw 8-byte array representation - `uint64` - 64-bit unsigned integer representation for service UID #### dap_chain_hash_slow_t Slow hash union for mining and proof-of-work operations. ```c typedef union dap_chain_hash_slow { uint8_t raw[DAP_CHAIN_HASH_SLOW_SIZE]; // Raw 32-byte hash data } dap_chain_hash_slow_t; ``` **Fields:** - `raw` - Raw 32-byte array containing the slow hash data #### dap_chain_addr_str_t String representation union for blockchain addresses. ```c typedef union dap_chain_addr_str { const char s[DAP_ENC_BASE58_ENCODE_SIZE(sizeof(dap_chain_addr_t))]; // Base58-encoded address string } dap_chain_addr_str_t; ``` **Fields:** - `s` - Base58-encoded address string with maximum encoded size #### dap_chain_token_ticker_str_t String representation union for token ticker symbols. ```c typedef union dap_chain_token_ticker_str { const char s[DAP_CHAIN_TICKER_SIZE_MAX]; // Token ticker string } dap_chain_token_ticker_str_t; ``` **Fields:** - `s` - Token ticker string with maximum 10 characters #### dap_chain_net_srv_price_unit_uid_t Service price unit identifier union for pricing mechanisms. ```c typedef union { uint8_t raw[4]; // Raw bytes representation uint32_t uint32; // 32-bit integer representation dap_chain_srv_unit_enum_t enm; // Enumeration value } DAP_ALIGN_PACKED dap_chain_net_srv_price_unit_uid_t; ``` **Fields:** - `raw` - Raw 4-byte array representation - `uint32` - 32-bit unsigned integer representation - `enm` - Service unit enumeration value (SEC, B, PCS, etc.) ### Functions #### `dap_chain_hash_slow_to_str()` Convert slow hash to hexadecimal string representation. ```c size_t dap_chain_hash_slow_to_str(dap_chain_hash_slow_t *a_hash, char *a_str, size_t a_str_max); ``` **Parameters:** - `a_hash` (`dap_chain_hash_slow_t *`) - Hash to convert - `a_str` (`char *`) - Output string buffer - `a_str_max` (`size_t`) - Maximum string buffer size **Returns:** - `size_t` - Length of resulting string - `0` - Conversion failed (buffer too small) **Error Conditions:** - Returns `0` if output buffer is too small for hash string #### `dap_chain_addr_to_str_static()` Convert address to Base58-encoded string representation (static buffer). ```c dap_chain_addr_str_t dap_chain_addr_to_str_static_(const dap_chain_addr_t *a_addr); ``` **Parameters:** - `a_addr` (`const dap_chain_addr_t *`) - Address to convert **Returns:** - `dap_chain_addr_str_t` - Static string structure with Base58-encoded address - `"null"` - If address is NULL or blank **Error Conditions:** - Returns "null" if address is NULL or blank #### `dap_chain_addr_from_str()` Parse address from Base58-encoded string. ```c dap_chain_addr_t *dap_chain_addr_from_str(const char *str); ``` **Parameters:** - `str` (`const char *`) - Base58-encoded address string **Returns:** - `dap_chain_addr_t *` - Pointer to parsed address structure - `NULL` - Parsing failed or invalid address **Error Conditions:** - Returns `NULL` if string is invalid or checksum verification fails #### `dap_chain_addr_from_str_array()` Parse multiple addresses from comma-separated string. ```c size_t dap_chain_addr_from_str_array(const char *a_addr_str, dap_chain_addr_t **a_addr); ``` **Parameters:** - `a_addr_str` (`const char *`) - Comma-separated address strings - `a_addr` (`dap_chain_addr_t **`) - Output array of parsed addresses **Returns:** - `size_t` - Number of successfully parsed addresses - `0` - Parsing failed **Error Conditions:** - Returns `0` if any address in the array fails to parse #### `dap_chain_addr_is_blank()` Check if address is blank/empty. ```c bool dap_chain_addr_is_blank(const dap_chain_addr_t *a_addr); ``` **Parameters:** - `a_addr` (`const dap_chain_addr_t *`) - Address to check **Returns:** - `true` - Address is blank - `false` - Address contains data #### `dap_chain_addr_fill()` Fill address structure with signature type and public key hash. ```c void dap_chain_addr_fill(dap_chain_addr_t *a_addr, dap_sign_type_t a_type, dap_chain_hash_fast_t *a_pkey_hash, dap_chain_net_id_t a_net_id); ``` **Parameters:** - `a_addr` (`dap_chain_addr_t *`) - Address structure to fill - `a_type` (`dap_sign_type_t`) - Signature type to use - `a_pkey_hash` (`dap_chain_hash_fast_t *`) - Public key hash - `a_net_id` (`dap_chain_net_id_t`) - Network identifier **Description:** Fills address structure with provided signature type, key hash, and network ID, automatically calculating checksum. #### `dap_chain_addr_fill_from_key()` Fill address structure from encryption key. ```c int dap_chain_addr_fill_from_key(dap_chain_addr_t *a_addr, dap_enc_key_t *a_key, dap_chain_net_id_t a_net_id); ``` **Parameters:** - `a_addr` (`dap_chain_addr_t *`) - Address structure to fill - `a_key` (`dap_enc_key_t *`) - Encryption key to derive address from - `a_net_id` (`dap_chain_net_id_t`) - Network identifier **Returns:** - `0` - Address filled successfully - `non-zero` - Operation failed **Error Conditions:** - Returns non-zero if key type is unsupported or key is invalid #### `dap_chain_addr_check_sum()` Verify address checksum integrity. ```c int dap_chain_addr_check_sum(const dap_chain_addr_t *a_addr); ``` **Parameters:** - `a_addr` (`const dap_chain_addr_t *`) - Address to verify **Returns:** - `0` - Checksum is valid - `non-zero` - Checksum is invalid **Error Conditions:** - Returns non-zero if checksum verification fails #### `dap_chain_net_srv_uid_from_str()` Parse network service UID from hexadecimal string. ```c dap_chain_net_srv_uid_t dap_chain_net_srv_uid_from_str(const char *a_str); ``` **Parameters:** - `a_str` (`const char *`) - Hexadecimal string (with "0x" prefix) **Returns:** - `dap_chain_net_srv_uid_t` - Parsed service UID - Zero UID if parsing fails **Error Conditions:** - Returns zero UID if string format is invalid --- ## Datum *Based on: `dap_chain_datum.h` and `dap_chain_datum.c`* ### Overview Basic datum structures and operations providing the fundamental data storage format for all blockchain elements. Datums are the basic building blocks that contain typed data with headers and metadata. **Key Responsibilities:** - Datum creation with proper headers and timestamps - Type identification and version management - Data serialization and size calculation - JSON conversion and dumping utilities - Hash calculation for datum content ### Document Structure - [[#Overview|Overview]] - [[#Enumerations|Enumerations]] - [[#Datum Type Constants|Datum Type Constants - Type identifier definitions]] - [[#Structures|Structures]] - [[#dap_chain_datum_typeid_t|dap_chain_datum_typeid_t - Type identifier union]] - [[#dap_chain_datum_t|dap_chain_datum_t - Main datum structure]] - [[#Functions|Functions]] - [[#Datum Creation|Datum Creation]] - [[#Datum Utilities|Datum Utilities]] - [[#JSON Operations|JSON Operations]] ### Enumerations #### Datum Type Constants Constant definitions for various datum types used throughout the blockchain. ```c // Block sections #define DAP_CHAIN_DATUM_BLOCK_END 0x0000 // End of block marker #define DAP_CHAIN_DATUM_BLOCK_ROOTS 0x0001 // Additional roots section // Transaction types #define DAP_CHAIN_DATUM_TX 0x0100 // Transaction data #define DAP_CHAIN_DATUM_TX_REQUEST 0x0300 // Transaction request // Governance #define DAP_CHAIN_DATUM_DECREE 0x0200 // Network decree // Smart contracts #define DAP_CHAIN_DATUM_WASM_CODE 0x0900 // WebAssembly code #define DAP_CHAIN_DATUM_WASM_DATA 0x0901 // WebAssembly data #define DAP_CHAIN_DATUM_EVM_CODE 0x0910 // Ethereum VM code #define DAP_CHAIN_DATUM_EVM_DATA 0x0911 // Ethereum VM data // Certificate authority #define DAP_CHAIN_DATUM_CA 0x0c00 // Certificate authority #define DAP_CHAIN_DATUM_SIGNER 0x0c01 // Signer certificate // Token operations #define DAP_CHAIN_DATUM_TOKEN 0xf000 // Token declaration #define DAP_CHAIN_DATUM_TOKEN_EMISSION 0xf100 // Token emission #define DAP_CHAIN_DATUM_TOKEN_DISMISSAL 0xf200 // Token dismissal // Other types #define DAP_CHAIN_DATUM_ANCHOR 0x0a00 // Cross-chain anchor #define DAP_CHAIN_DATUM_CUSTOM 0xffff // Custom datum type ``` **Type Categories:** - **Block Control** - Block structure and control information - **Transactions** - Transaction data and requests - **Governance** - Network governance and decree data - **Smart Contracts** - WASM and EVM contract code and data - **Certificates** - Certificate authority and signer data - **Tokens** - Token operations (declaration, emission, dismissal) - **Cross-chain** - Anchor data for inter-chain operations - **Custom** - User-defined datum types ### Structures #### dap_chain_datum_typeid_t Union structure for datum type identifier with multiple access methods. ```c typedef union dap_chain_datum_typeid { uint8_t data[DAP_CHAIN_DATUM_ID_SIZE]; // Raw byte array access uint16_t uint16; // 16-bit integer access } DAP_ALIGN_PACKED dap_chain_datum_typeid_t; ``` **Fields:** - `data` - Raw byte array representation (2 bytes) - `uint16` - 16-bit unsigned integer representation for easier comparison #### dap_chain_datum_t Main datum structure containing header and variable-length data payload. ```c typedef struct dap_chain_datum { struct { uint8_t version_id; // Datum version identifier uint16_t type_id; // Datum type identifier uint32_t data_size; // Size of data payload uint64_t ts_create; // Creation timestamp (GMT) } DAP_ALIGN_PACKED header; byte_t data[]; // Variable-length data payload } DAP_ALIGN_PACKED dap_chain_datum_t; ``` **Fields:** - `version_id` - Version of datum format (currently DAP_CHAIN_DATUM_VERSION = 0x00) - `type_id` - Type identifier using datum type constants - `data_size` - Size in bytes of the data payload - `ts_create` - Unix timestamp of datum creation in GMT - `data` - Flexible array member containing the actual datum payload ### Functions #### Datum Creation ##### `dap_chain_datum_create()` Create a new datum with specified type and data payload. ```c dap_chain_datum_t *dap_chain_datum_create(uint16_t a_type_id, const void *a_data, size_t a_data_size); ``` **Parameters:** - `a_type_id` (`uint16_t`) - Datum type identifier (see datum type constants) - `a_data` (`const void *`) - Pointer to data payload - `a_data_size` (`size_t`) - Size of data payload in bytes **Returns:** - `dap_chain_datum_t *` - Pointer to newly created datum - `NULL` - Creation failed (memory allocation error) **Error Conditions:** - Returns `NULL` if memory allocation fails **Description:** Creates a new datum with current timestamp, specified type, and copies the provided data into the datum payload. #### Datum Utilities ##### `dap_chain_datum_size()` Calculate total size of a datum including header and data. ```c uint64_t dap_chain_datum_size(const dap_chain_datum_t *a_datum); ``` **Parameters:** - `a_datum` (`const dap_chain_datum_t *`) - Datum to measure **Returns:** - `uint64_t` - Total size in bytes (header + data) - `0` - If datum pointer is NULL **Error Conditions:** - Returns `0` if datum pointer is NULL ##### `dap_chain_datum_calc_hash()` Calculate hash of datum data payload. ```c void dap_chain_datum_calc_hash(const dap_chain_datum_t *a_datum, dap_hash_fast_t *a_out_hash); ``` **Parameters:** - `a_datum` (`const dap_chain_datum_t *`) - Datum to hash - `a_out_hash` (`dap_hash_fast_t *`) - Output buffer for calculated hash **Description:** Calculates fast hash of the datum's data payload (not including header) and stores result in output buffer. ##### `dap_chain_datum_type_id_to_str()` Convert datum type ID to human-readable string. ```c const char *dap_chain_datum_type_id_to_str(uint16_t a_type_id); ``` **Parameters:** - `a_type_id` (`uint16_t`) - Datum type identifier **Returns:** - `const char *` - String representation of type - `"DATUM_UNKNOWN"` - For unrecognized types **Description:** Converts numeric type ID to descriptive string using DAP_DATUM_TYPE_STR macro. #### JSON Operations ##### `dap_chain_datum_to_json()` Convert datum to JSON object representation. ```c json_object *dap_chain_datum_to_json(dap_chain_datum_t *a_datum); ``` **Parameters:** - `a_datum` (`dap_chain_datum_t *`) - Datum to convert **Returns:** - `json_object *` - JSON object representation - `NULL` - Conversion failed **Error Conditions:** - Returns `NULL` if datum is invalid or JSON creation fails ##### `dap_chain_datum_dump_json()` Dump datum information to JSON with detailed formatting. ```c void dap_chain_datum_dump_json(json_object *a_json_arr_reply, json_object *a_obj_out, dap_chain_datum_t *a_datum, const char *a_hash_out_type, dap_chain_net_id_t a_net_id, bool a_verbose); ``` **Parameters:** - `a_json_arr_reply` (`json_object *`) - JSON array for responses - `a_obj_out` (`json_object *`) - Output JSON object - `a_datum` (`dap_chain_datum_t *`) - Datum to dump - `a_hash_out_type` (`const char *`) - Hash output format ("hex" or "base58") - `a_net_id` (`dap_chain_net_id_t`) - Network identifier - `a_verbose` (`bool`) - Enable verbose output **Description:** Performs detailed JSON dump of datum with type-specific formatting based on datum type. --- ## Token *Based on: `dap_chain_datum_token.h` and `dap_chain_datum_token.c`* ### Overview Token definition and management structures providing comprehensive cryptocurrency token functionality. Handles token declarations, emissions, updates, and complex token features like permissions, flags, and delegation. **Key Responsibilities:** - Token declaration with various subtypes (simple, private, native, public) - Token emission and value management - Token flags and permission system - Token signing and certification - Token TSD (Type-Size-Data) sections for metadata - Token update and modification operations ### Document Structure - [[#Overview|Overview]] - [[#Enumerations|Enumerations]] - [[#Token Type Constants|Token Type Constants - Legacy and new type definitions]] - [[#Token Subtype Constants|Token Subtype Constants - Token subtypes]] - [[#Token Flag Constants|Token Flag Constants - Permission and control flags]] - [[#Structures|Structures]] - [[#dap_chain_datum_token_t|dap_chain_datum_token_t - Main token structure]] - [[#dap_chain_datum_token_emission_t|dap_chain_datum_token_emission_t - Token emission structure]] - [[#dap_chain_datum_token_tsd_delegate_from_stake_lock_t|dap_chain_datum_token_tsd_delegate_from_stake_lock_t - Delegation structure]] - [[#Functions|Functions]] - [[#Token Management|Token Management]] - [[#Token Emission|Token Emission]] - [[#Token Utilities|Token Utilities]] ### Enumerations #### Token Type Constants Legacy and current token type definitions for backward compatibility. ```c // Legacy token types (OLD) #define DAP_CHAIN_DATUM_TOKEN_TYPE_OLD_SIMPLE 0x0005 // Simple token #define DAP_CHAIN_DATUM_TOKEN_TYPE_OLD_PRIVATE_DECL 0x0006 // Private token declaration #define DAP_CHAIN_DATUM_TOKEN_TYPE_OLD_PRIVATE_UPDATE 0x0007 // Private token update #define DAP_CHAIN_DATUM_TOKEN_TYPE_OLD_PUBLIC 0x0008 // Public token #define DAP_CHAIN_DATUM_TOKEN_TYPE_OLD_NATIVE_DECL 0x0009 // Native token declaration #define DAP_CHAIN_DATUM_TOKEN_TYPE_OLD_NATIVE_UPDATE 0x000A // Native token update // Current token types (NEW) #define DAP_CHAIN_DATUM_TOKEN_TYPE_DECL 0x0010 // Token declaration #define DAP_CHAIN_DATUM_TOKEN_TYPE_UPDATE 0x0011 // Token update ``` #### Token Subtype Constants Token subtypes defining specific token behaviors and features. ```c // Token subtypes #define DAP_CHAIN_DATUM_TOKEN_SUBTYPE_SIMPLE 0x0001 // Simple token #define DAP_CHAIN_DATUM_TOKEN_SUBTYPE_PRIVATE 0x0002 // Private controlled token #define DAP_CHAIN_DATUM_TOKEN_SUBTYPE_NATIVE 0x0003 // Native network token #define DAP_CHAIN_DATUM_TOKEN_SUBTYPE_PUBLIC 0x0004 // Public open token ``` #### Token Flag Constants Comprehensive flag system for token permissions and behaviors. ```c // Global control flags #define DAP_CHAIN_DATUM_TOKEN_FLAG_NONE 0x0000 // No flags #define DAP_CHAIN_DATUM_TOKEN_FLAG_ALL_SENDER_BLOCKED BIT(1) // Block all senders #define DAP_CHAIN_DATUM_TOKEN_FLAG_ALL_SENDER_ALLOWED BIT(2) // Allow all senders #define DAP_CHAIN_DATUM_TOKEN_FLAG_ALL_SENDER_FROZEN BIT(3) // Freeze sender permissions #define DAP_CHAIN_DATUM_TOKEN_FLAG_ALL_SENDER_UNFROZEN BIT(4) // Unfreeze sender permissions #define DAP_CHAIN_DATUM_TOKEN_FLAG_ALL_RECEIVER_BLOCKED BIT(5) // Block all receivers #define DAP_CHAIN_DATUM_TOKEN_FLAG_ALL_RECEIVER_ALLOWED BIT(6) // Allow all receivers #define DAP_CHAIN_DATUM_TOKEN_FLAG_ALL_RECEIVER_FROZEN BIT(7) // Freeze receiver permissions #define DAP_CHAIN_DATUM_TOKEN_FLAG_ALL_RECEIVER_UNFROZEN BIT(8) // Unfreeze receiver permissions // Static configuration flags #define DAP_CHAIN_DATUM_TOKEN_FLAG_STATIC_ALL BIT(9) // Immutable after declaration #define DAP_CHAIN_DATUM_TOKEN_FLAG_STATIC_FLAGS BIT(10) // Immutable flags ``` ### Structures #### dap_chain_datum_token_t Main token structure supporting multiple token types and configurations. ```c typedef struct dap_chain_datum_token { uint16_t type; // Token type identifier uint16_t version; // Token format version uint16_t subtype; // Token subtype char ticker[DAP_CHAIN_TICKER_SIZE_MAX]; // Token symbol/ticker uint16_t signs_valid; // Valid signatures required uint16_t signs_total; // Total signatures provided uint256_t total_supply; // Maximum token supply union { // Simple token header struct { uint16_t decimals; // Decimal places } DAP_ALIGN_PACKED header_simple; // Private token declaration header struct { uint16_t flags; // Token flags uint64_t tsd_total_size; // TSD section size uint16_t decimals; // Decimal places } DAP_ALIGN_PACKED header_private_decl; // Native token declaration header struct { uint16_t flags; // Token flags uint64_t tsd_total_size; // TSD section size uint16_t decimals; // Decimal places } DAP_ALIGN_PACKED header_native_decl; // Public token declaration header struct { uint32_t flags; // Extended flags uint256_t premine_supply; // Pre-mined supply dap_chain_addr_t premine_address; // Pre-mine recipient } DAP_ALIGN_PACKED header_public; byte_t header[192]; // Future expansion space }; uint8_t nonce[DAP_CHAIN_DATUM_NONCE_SIZE]; // Cryptographic nonce byte_t tsd_n_signs[]; // TSD sections and signatures } DAP_ALIGN_PACKED dap_chain_datum_token_t; ``` **Fields:** - `type` - Token type using type constants - `version` - Token format version for compatibility - `subtype` - Token subtype defining behavior - `ticker` - Token symbol (up to 10 characters) - `signs_valid`/`signs_total` - Signature requirements and counts - `total_supply` - Maximum possible token supply - Union headers for different token types with specific configurations - `nonce` - 64-byte cryptographic nonce for security - `tsd_n_signs` - Variable-length TSD sections and signature data #### dap_chain_datum_token_emission_t Token emission structure for creating new tokens in circulation. ```c typedef struct dap_chain_datum_token_emission { struct { uint8_t version; // Emission format version uint8_t type; // Emission type char ticker[DAP_CHAIN_TICKER_SIZE_MAX]; // Token ticker dap_chain_addr_t address; // Emission recipient address union { uint64_t value64; // Legacy value (deprecated) uint256_t value; // Emission value } DAP_ALIGN_PACKED; uint8_t nonce[DAP_CHAIN_DATUM_NONCE_SIZE]; // Cryptographic nonce } DAP_ALIGN_PACKED hdr; union { // Presale emission data struct { dap_chain_addr_t addr; // Presale address int flags; // Presale flags uint64_t lock_time; // Lock duration } DAP_ALIGN_PACKED type_presale; // Atom owner emission data struct { uint64_t value_start; // Starting value char value_change_algo_codename[32]; // Algorithm name } DAP_ALIGN_PACKED type_atom_owner; // Algorithm-based emission struct { char codename[32]; // Algorithm codename } DAP_ALIGN_PACKED type_algo; // Authority-based emission struct { uint64_t tsd_n_signs_size; // TSD and signs size uint64_t tsd_total_size; // Total TSD size uint16_t signs_count; // Number of signatures } DAP_ALIGN_PACKED type_auth; byte_t free_space[128]; // Future expansion } DAP_ALIGN_PACKED data; byte_t tsd_n_signs[]; // TSD sections and signatures } DAP_ALIGN_PACKED dap_chain_datum_token_emission_t; ``` **Fields:** - `hdr` - Emission header with version, type, ticker, and recipient - `data` - Union containing type-specific emission data - `tsd_n_signs` - Variable TSD sections and signature data #### dap_chain_datum_token_tsd_delegate_from_stake_lock_t Delegation structure for stake-based token emission. ```c typedef struct dap_chain_datum_token_tsd_delegate_from_stake_lock { char ticker_token_from[DAP_CHAIN_TICKER_SIZE_MAX]; // Source token ticker uint256_t emission_rate; // Emission rate in coins byte_t padding[4]; // Future expansion } DAP_ALIGN_PACKED dap_chain_datum_token_tsd_delegate_from_stake_lock_t; ``` **Fields:** - `ticker_token_from` - Source token for delegation - `emission_rate` - Rate of emission (1^18 == 1.0) - `padding` - Reserved space for future features ### Functions #### Token Management ##### `dap_chain_datum_token_flag_to_str()` Convert token flag to string representation. ```c const char *dap_chain_datum_token_flag_to_str(uint32_t a_flag); ``` **Parameters:** - `a_flag` (`uint32_t`) - Token flag value **Returns:** - `const char *` - String representation of flag - `"UNKNOWN"` - For unrecognized flags ##### `dap_chain_datum_token_flag_from_str()` Parse token flag from string representation. ```c uint32_t dap_chain_datum_token_flag_from_str(const char *a_str); ``` **Parameters:** - `a_str` (`const char *`) - Flag string to parse **Returns:** - `uint32_t` - Parsed flag value - `0` - If string is not recognized ##### `dap_chain_datum_token_tsd_get()` Get TSD section from token structure. ```c dap_tsd_t *dap_chain_datum_token_tsd_get(dap_chain_datum_token_t *a_token, size_t a_token_size); ``` **Parameters:** - `a_token` (`dap_chain_datum_token_t *`) - Token structure - `a_token_size` (`size_t`) - Total token size **Returns:** - `dap_tsd_t *` - Pointer to TSD section - `NULL` - If TSD section is corrupted or not found #### Token Emission ##### `dap_chain_datum_emission_create()` Create new token emission structure. ```c dap_chain_datum_token_emission_t *dap_chain_datum_emission_create(uint256_t a_value, const char *a_ticker, dap_chain_addr_t *a_addr); ``` **Parameters:** - `a_value` (`uint256_t`) - Emission amount - `a_ticker` (`const char *`) - Token ticker - `a_addr` (`dap_chain_addr_t *`) - Recipient address **Returns:** - `dap_chain_datum_token_emission_t *` - Created emission structure - `NULL` - Creation failed **Error Conditions:** - Returns `NULL` if memory allocation fails or parameters are invalid ##### `dap_chain_datum_emission_add_tsd()` Add TSD section to emission structure. ```c dap_chain_datum_token_emission_t *dap_chain_datum_emission_add_tsd(dap_chain_datum_token_emission_t *a_emission, int a_type, size_t a_size, void *a_data); ``` **Parameters:** - `a_emission` (`dap_chain_datum_token_emission_t *`) - Emission structure to modify - `a_type` (`int`) - TSD type identifier - `a_size` (`size_t`) - TSD data size - `a_data` (`void *`) - TSD data payload **Returns:** - `dap_chain_datum_token_emission_t *` - Modified emission structure - `NULL` - Addition failed ##### `dap_chain_emission_get_tsd()` Extract TSD section from emission structure. ```c byte_t *dap_chain_emission_get_tsd(dap_chain_datum_token_emission_t *a_emission, int a_type, size_t *a_size); ``` **Parameters:** - `a_emission` (`dap_chain_datum_token_emission_t *`) - Emission structure - `a_type` (`int`) - TSD type to find - `a_size` (`size_t *`) - Output parameter for TSD size **Returns:** - `byte_t *` - Pointer to TSD data - `NULL` - TSD type not found #### Token Utilities ##### `dap_chain_datum_emission_get_size()` Calculate total size of emission structure. ```c size_t dap_chain_datum_emission_get_size(uint8_t *a_emission_serial); ``` **Parameters:** - `a_emission_serial` (`uint8_t *`) - Serialized emission data **Returns:** - `size_t` - Total emission size in bytes - `0` - If emission data is invalid ##### `dap_chain_datum_token_is_old()` Check if token uses legacy format. ```c bool dap_chain_datum_token_is_old(uint8_t a_type); ``` **Parameters:** - `a_type` (`uint8_t`) - Token type to check **Returns:** - `true` - Token uses legacy format - `false` - Token uses current format **Description:** Determines whether a token type uses the legacy format (pre-versioning) or the current format. ##### `dap_chain_datum_token_flags_dump_to_json()` Dump token flags to JSON object. ```c void dap_chain_datum_token_flags_dump_to_json(json_object *json_obj_out, const char *a_key, uint16_t a_flags); ``` **Parameters:** - `json_obj_out` (`json_object *`) - Output JSON object - `a_key` (`const char *`) - Key for the flags in JSON - `a_flags` (`uint16_t`) - Token flags to dump **Description:** Converts token flags to human-readable format and adds them to a JSON object. ##### `dap_chain_datum_token_certs_dump()` Dump token certificates to string. ```c void dap_chain_datum_token_certs_dump(dap_string_t *a_str_out, byte_t *a_tsd_n_signs, size_t a_certs_size, const char *a_hash_out_type); ``` **Parameters:** - `a_str_out` (`dap_string_t *`) - Output string buffer - `a_tsd_n_signs` (`byte_t *`) - Certificate data - `a_certs_size` (`size_t`) - Size of certificate data - `a_hash_out_type` (`const char *`) - Hash output format **Description:** Converts token certificates to human-readable format and appends to string buffer. ##### `dap_chain_datum_token_certs_dump_to_json()` Dump token certificates to JSON object. ```c void dap_chain_datum_token_certs_dump_to_json(json_object *a_json_obj_out, byte_t *a_tsd_n_signs, size_t a_certs_size, const char *a_hash_out_type); ``` **Parameters:** - `a_json_obj_out` (`json_object *`) - Output JSON object - `a_tsd_n_signs` (`byte_t *`) - Certificate data - `a_certs_size` (`size_t`) - Size of certificate data - `a_hash_out_type` (`const char *`) - Hash output format **Description:** Converts token certificates to JSON format and adds them to a JSON object. ##### `dap_chain_datum_emission_get_size()` Get size of emission data. ```c size_t dap_chain_datum_emission_get_size(uint8_t *a_emission_serial); ``` **Parameters:** - `a_emission_serial` (`uint8_t *`) - Serialized emission data **Returns:** - `size_t` - Size of emission data in bytes - `0` - If emission data is invalid **Description:** Calculates the size of serialized emission data by parsing the TSD structure. --- ## Transaction Core *Based on: `dap_chain_datum_tx.h` and `dap_chain_datum_tx.c`* ### Overview Basic transaction structures and operations providing the fundamental transaction processing capabilities. Handles transaction creation, item management, signing, and verification. **Key Responsibilities:** - Transaction creation and lifecycle management - Transaction item addition and manipulation - Transaction signing and signature verification - Transaction size calculation and validation - Transaction hash computation - Fee calculation and management ### Document Structure - [[#Overview|Overview]] - [[#Enumerations|Enumerations]] - [[#Structures|Structures]] - [[#dap_chain_datum_tx_t|dap_chain_datum_tx_t - Main transaction structure]] - [[#dap_chain_tx_used_out_item_t|dap_chain_tx_used_out_item_t - Used output tracking]] - [[#dap_chain_tx_tsd_t|dap_chain_tx_tsd_t - Transaction TSD metadata]] - [[#Functions|Functions]] - [[#Transaction Management|Transaction Management]] - [[#Transaction Items|Transaction Items]] - [[#Transaction Signing|Transaction Signing]] - [[#Transaction Utilities|Transaction Utilities]] ### Structures #### dap_chain_datum_tx_t Main transaction structure containing header and variable-length transaction items. ```c typedef struct dap_chain_datum_tx { struct { dap_time_t ts_created; // Transaction creation timestamp uint32_t tx_items_size; // Total size of transaction items } DAP_ALIGN_PACKED header; uint8_t tx_items[]; // Variable-length transaction items } DAP_ALIGN_PACKED dap_chain_datum_tx_t; ``` **Fields:** - `ts_created` - Unix timestamp when transaction was created - `tx_items_size` - Total size in bytes of all transaction items - `tx_items` - Flexible array containing sequential transaction items #### dap_chain_tx_used_out_item_t Structure for tracking used transaction outputs in spending operations. ```c typedef struct dap_chain_tx_used_out_item { dap_chain_hash_fast_t tx_hash_fast; // Hash of transaction containing output uint32_t num_idx_out; // Output index in transaction uint256_t value; // Value of the output } dap_chain_tx_used_out_item_t; ``` **Fields:** - `tx_hash_fast` - Fast hash of the transaction containing the output - `num_idx_out` - Index of the output within the transaction - `value` - Value of the output in datoshi (smallest token unit) #### dap_chain_tx_tsd_t Transaction TSD (Type-Size-Data) structure for custom transaction metadata. ```c typedef struct dap_chain_tx_tsd { struct { dap_chain_tx_item_type_t type; // Transaction item type uint64_t size DAP_ALIGNED(8); // Size of TSD data } DAP_PACKED header; byte_t tsd[]; // Variable-length TSD data } DAP_PACKED dap_chain_tx_tsd_t; ``` **Fields:** - `type` - Transaction item type (TX_ITEM_TYPE_TSD) - `size` - Size of the TSD data section in bytes - `tsd` - Variable-length TSD data containing type-size-value triplets ### Functions #### Transaction Management ##### `dap_chain_datum_tx_create()` Create empty transaction with initialized header. ```c dap_chain_datum_tx_t *dap_chain_datum_tx_create(void); ``` **Returns:** - `dap_chain_datum_tx_t *` - Pointer to created transaction - `NULL` - Creation failed **Error Conditions:** - Returns `NULL` if memory allocation fails ##### `dap_chain_datum_tx_delete()` Delete transaction and free associated memory. ```c void dap_chain_datum_tx_delete(dap_chain_datum_tx_t *a_tx); ``` **Parameters:** - `a_tx` (`dap_chain_datum_tx_t *`) - Transaction to delete **Description:** Frees all memory associated with the transaction structure. ##### `dap_chain_datum_tx_get_size()` Calculate total size of transaction including all items. ```c size_t dap_chain_datum_tx_get_size(dap_chain_datum_tx_t *a_tx); ``` **Parameters:** - `a_tx` (`dap_chain_datum_tx_t *`) - Transaction to measure **Returns:** - `size_t` - Total transaction size in bytes - `0` - If transaction is invalid #### Transaction Items ##### `dap_chain_datum_tx_add_item()` Add transaction item to existing transaction. ```c int dap_chain_datum_tx_add_item(dap_chain_datum_tx_t **a_tx, const void *a_item); ``` **Parameters:** - `a_tx` (`dap_chain_datum_tx_t **`) - Pointer to transaction (may be reallocated) - `a_item` (`const void *`) - Transaction item to add **Returns:** - `1` - Item added successfully - `-1` - Addition failed **Error Conditions:** - Returns `-1` if memory reallocation fails or item is invalid ##### `dap_chain_datum_tx_add_in_item()` Add input item referencing previous transaction output. ```c int dap_chain_datum_tx_add_in_item(dap_chain_datum_tx_t **a_tx, dap_chain_hash_fast_t *a_tx_prev_hash, uint32_t a_tx_out_prev_idx); ``` **Parameters:** - `a_tx` (`dap_chain_datum_tx_t **`) - Transaction to modify - `a_tx_prev_hash` (`dap_chain_hash_fast_t *`) - Hash of previous transaction - `a_tx_out_prev_idx` (`uint32_t`) - Index of output in previous transaction **Returns:** - `1` - Input item added successfully - `-1` - Addition failed ##### `dap_chain_datum_tx_add_out_item()` Add output item to transaction. ```c int dap_chain_datum_tx_add_out_item(dap_chain_datum_tx_t **a_tx, const dap_chain_addr_t *a_addr, uint256_t a_value); ``` **Parameters:** - `a_tx` (`dap_chain_datum_tx_t **`) - Transaction to modify - `a_addr` (`const dap_chain_addr_t *`) - Recipient address - `a_value` (`uint256_t`) - Output value **Returns:** - `1` - Output item added successfully - `-1` - Addition failed ##### `dap_chain_datum_tx_add_fee_item()` Add fee item to transaction. ```c int dap_chain_datum_tx_add_fee_item(dap_chain_datum_tx_t **a_tx, uint256_t a_value); ``` **Parameters:** - `a_tx` (`dap_chain_datum_tx_t **`) - Transaction to modify - `a_value` (`uint256_t`) - Fee amount **Returns:** - `1` - Fee item added successfully - `-1` - Addition failed #### Transaction Signing ##### `dap_chain_datum_tx_add_sign_item()` Sign transaction and add signature item. ```c int dap_chain_datum_tx_add_sign_item(dap_chain_datum_tx_t **a_tx, dap_enc_key_t *a_key); ``` **Parameters:** - `a_tx` (`dap_chain_datum_tx_t **`) - Transaction to sign - `a_key` (`dap_enc_key_t *`) - Private key for signing **Returns:** - `1` - Signature added successfully - `-1` - Signing failed **Error Conditions:** - Returns `-1` if key is invalid or signing operation fails ##### `dap_chain_datum_tx_get_sign()` Get signature from transaction by index. ```c dap_sign_t *dap_chain_datum_tx_get_sign(dap_chain_datum_tx_t *a_tx, int a_sign_num); ``` **Parameters:** - `a_tx` (`dap_chain_datum_tx_t *`) - Transaction to examine - `a_sign_num` (`int`) - Signature index **Returns:** - `dap_sign_t *` - Pointer to signature structure - `NULL` - Signature not found ##### `dap_chain_datum_tx_verify_sign()` Verify signature in transaction. ```c int dap_chain_datum_tx_verify_sign(dap_chain_datum_tx_t *a_tx, int a_sign_num); ``` **Parameters:** - `a_tx` (`dap_chain_datum_tx_t *`) - Transaction to verify - `a_sign_num` (`int`) - Signature index to verify **Returns:** - `1` - Signature is valid - `0` - Signature is invalid - `-1` - Signature not found or other error #### Transaction Utilities ##### `dap_chain_datum_tx_get_fee_value()` Extract fee value from transaction. ```c int dap_chain_datum_tx_get_fee_value(dap_chain_datum_tx_t *a_tx, uint256_t *a_value); ``` **Parameters:** - `a_tx` (`dap_chain_datum_tx_t *`) - Transaction to examine - `a_value` (`uint256_t *`) - Output parameter for fee value **Returns:** - `0` - Fee value extracted successfully - `non-zero` - Fee extraction failed ##### `dap_chain_node_datum_tx_calc_hash()` Calculate hash of entire transaction. ```c dap_hash_fast_t dap_chain_node_datum_tx_calc_hash(dap_chain_datum_tx_t *a_tx); ``` **Parameters:** - `a_tx` (`dap_chain_datum_tx_t *`) - Transaction to hash **Returns:** - `dap_hash_fast_t` - Calculated transaction hash **Description:** Calculates fast hash of the entire transaction including header and all items. --- ## Transaction Items *Based on: `dap_chain_datum_tx_items.h` and `dap_chain_datum_tx_items.c`* ### Overview Transaction items and components providing detailed transaction input/output structures and specialized transaction elements. This division handles the individual components that make up transactions. **Key Responsibilities:** - Transaction input item structures and management - Transaction output item structures and management - Specialized transaction items (signatures, receipts, voting) - Transaction item validation and processing - Transaction item serialization and parsing *[This section would be completed based on examination of the actual tx_items files]* --- ## Transaction Components *Based on: `dap_chain_datum_tx_in_ems.h`, `dap_chain_datum_tx_sig.h`, `dap_chain_datum_tx_voting.h`, `dap_chain_datum_tx_receipt.h`, `dap_chain_datum_tx_in_reward.h`* ### Overview Specialized transaction components including emission inputs, signatures, voting mechanisms, receipts, and reward inputs with detailed structures and validation. ### Document Structure - [[#Overview|Overview]] - [[#Emission Input Structures|Emission Input Structures]] - [[#dap_chain_tx_in_ems_t|dap_chain_tx_in_ems_t - Token emission input]] - [[#dap_chain_tx_in_ems_ext_t|dap_chain_tx_in_ems_ext_t - External emission input]] - [[#Signature Structures|Signature Structures]] - [[#dap_chain_tx_sig_t|dap_chain_tx_sig_t - Transaction signature]] - [[#Voting Structures|Voting Structures]] - [[#dap_chain_datum_voting_tsd_type_t|dap_chain_datum_voting_tsd_type_t - Voting TSD types]] - [[#dap_chain_tx_voting_t|dap_chain_tx_voting_t - Voting transaction]] - [[#dap_chain_tx_voting_tx_cond_t|dap_chain_tx_voting_tx_cond_t - Voting condition]] - [[#dap_chain_tx_vote_t|dap_chain_tx_vote_t - Vote transaction]] - [[#dap_chain_datum_tx_voting_params_t|dap_chain_datum_tx_voting_params_t - Voting parameters]] - [[#Receipt Structures|Receipt Structures]] - [[#dap_chain_receipt_info_t|dap_chain_receipt_info_t - Receipt information]] - [[#dap_chain_datum_tx_receipt_t|dap_chain_datum_tx_receipt_t - Transaction receipt]] - [[#Reward Input Structures|Reward Input Structures]] - [[#dap_chain_tx_in_reward_t|dap_chain_tx_in_reward_t - Reward input]] ### Emission Input Structures #### dap_chain_tx_in_ems_t Token emission input structure for referencing token emission transactions. ```c typedef struct dap_chain_tx_in_ems { struct { dap_chain_tx_item_type_t type; // Transaction item type char ticker[DAP_CHAIN_TICKER_SIZE_MAX]; // Token ticker symbol dap_chain_id_t token_emission_chain_id DAP_ALIGNED(4); // Chain containing emission dap_hash_fast_t token_emission_hash; // Hash of emission transaction } DAP_PACKED header; // Header for verification } DAP_PACKED dap_chain_tx_in_ems_t; ``` **Fields:** - `type` - Transaction item type (TX_ITEM_TYPE_IN_EMS) - `ticker` - Token ticker symbol (max 10 characters) - `token_emission_chain_id` - Chain ID where emission transaction exists - `token_emission_hash` - Hash of the emission transaction being referenced #### dap_chain_tx_in_ems_ext_t External emission input structure for cross-chain token swaps. ```c typedef struct dap_chain_tx_in_ems_ext { struct { dap_chain_tx_item_type_t type; // Transaction item type uint8_t version; // Structure version char ticker[DAP_CHAIN_TICKER_SIZE_MAX]; // Token ticker symbol uint8_t padding1; // Alignment padding dap_chain_net_id_t ext_net_id; // External network ID dap_chain_id_t ext_chain_id; // External chain ID dap_chain_hash_fast_t ext_tx_hash; // External transaction hash uint16_t padding2; // Alignment padding uint16_t ext_tx_out_idx; // External output index } header; // Header for verification } DAP_ALIGN_PACKED dap_chain_tx_in_ems_ext_t; ``` **Fields:** - `type` - Transaction item type - `version` - Structure version for compatibility - `ticker` - Token ticker being swapped - `ext_net_id` - External network identifier - `ext_chain_id` - External chain identifier - `ext_tx_hash` - Hash of external transaction - `ext_tx_out_idx` - Output index in external transaction ### Signature Structures #### dap_chain_tx_sig_t Transaction signature structure containing cryptographic signatures. ```c typedef struct dap_chain_tx_sig { struct { dap_chain_tx_item_type_t type; // Transaction item type uint8_t version DAP_ALIGNED(1); // Signature version uint32_t sig_size DAP_ALIGNED(4); // Signature data size } DAP_PACKED header; // Header for verification uint8_t sig[]; // Variable-length signature data } DAP_PACKED dap_chain_tx_sig_t; ``` **Fields:** - `type` - Transaction item type (TX_ITEM_TYPE_SIG) - `version` - Signature format version - `sig_size` - Size of signature data in bytes - `sig` - Variable-length signature data ### Voting Structures #### dap_chain_datum_voting_tsd_type_t Enumeration of voting TSD (Type-Size-Data) section types. ```c typedef enum dap_chain_datum_voting_tsd_type { VOTING_TSD_TYPE_QUESTION = 0x01, // Voting question text VOTING_TSD_TYPE_ANSWER, // Answer option text VOTING_TSD_TYPE_EXPIRE, // Voting expiration time VOTING_TSD_TYPE_MAX_VOTES_COUNT, // Maximum vote count VOTING_TSD_TYPE_DELEGATED_KEY_REQUIRED, // Delegation requirement VOTING_TSD_TYPE_VOTE_CHANGING_ALLOWED, // Vote change permission VOTING_TSD_TYPE_VOTE_TX_COND, // Voting transaction condition VOTING_TSD_TYPE_TOKEN // Token requirement } dap_chain_datum_voting_tsd_type_t; ``` **Values:** - `VOTING_TSD_TYPE_QUESTION` - Contains voting question text - `VOTING_TSD_TYPE_ANSWER` - Contains answer option text - `VOTING_TSD_TYPE_EXPIRE` - Contains voting expiration timestamp - `VOTING_TSD_TYPE_MAX_VOTES_COUNT` - Contains maximum allowed votes - `VOTING_TSD_TYPE_DELEGATED_KEY_REQUIRED` - Indicates delegation requirement - `VOTING_TSD_TYPE_VOTE_CHANGING_ALLOWED` - Indicates if vote changes allowed - `VOTING_TSD_TYPE_VOTE_TX_COND` - Contains voting transaction conditions - `VOTING_TSD_TYPE_TOKEN` - Contains required token information #### dap_chain_tx_voting_t Basic voting transaction structure. ```c typedef struct dap_chain_tx_voting { dap_chain_tx_item_type_t type; // Transaction item type } DAP_ALIGN_PACKED dap_chain_tx_voting_t; ``` **Fields:** - `type` - Transaction item type (TX_ITEM_TYPE_VOTING) #### dap_chain_tx_voting_tx_cond_t Voting transaction condition structure referencing required transactions. ```c typedef struct dap_chain_tx_voting_tx_cond { dap_chain_hash_fast_t tx_hash; // Required transaction hash int out_idx; // Required output index } DAP_ALIGN_PACKED dap_chain_tx_voting_tx_cond_t; ``` **Fields:** - `tx_hash` - Hash of transaction that must exist for voting eligibility - `out_idx` - Output index in the required transaction #### dap_chain_tx_vote_t Individual vote transaction structure. ```c typedef struct dap_chain_tx_vote { dap_chain_tx_item_type_t type; // Transaction item type dap_chain_hash_fast_t voting_hash; // Hash of voting transaction uint64_t answer_idx; // Selected answer index } DAP_ALIGN_PACKED dap_chain_tx_vote_t; ``` **Fields:** - `type` - Transaction item type (TX_ITEM_TYPE_VOTE) - `voting_hash` - Hash of the voting transaction being voted on - `answer_idx` - Index of the selected answer option #### dap_chain_datum_tx_voting_params_t Complete voting parameters structure for voting creation. ```c typedef struct dap_chain_datum_tx_voting_params { char *voting_question; // Voting question text dap_list_t *answers_list; // List of answer options uint8_t answers_count; // Number of answers dap_time_t voting_expire; // Expiration timestamp uint64_t votes_max_count; // Maximum votes allowed bool delegate_key_required; // Delegation requirement bool vote_changing_allowed; // Vote change permission char token_ticker[DAP_CHAIN_TICKER_SIZE_MAX]; // Required token ticker } dap_chain_datum_tx_voting_params_t; ``` **Fields:** - `voting_question` - Pointer to voting question string - `answers_list` - Linked list of answer option strings - `answers_count` - Number of available answer options - `voting_expire` - Unix timestamp when voting expires - `votes_max_count` - Maximum number of votes allowed - `delegate_key_required` - Whether delegation is required for voting - `vote_changing_allowed` - Whether voters can change their votes - `token_ticker` - Required token ticker for voting eligibility ### Receipt Structures #### dap_chain_receipt_info_t Receipt information structure containing service payment details. ```c typedef struct dap_chain_receipt_info { dap_chain_net_srv_uid_t srv_uid; // Service unique identifier #if DAP_CHAIN_NET_SRV_UID_SIZE == 8 uint64_t addition; // Additional data #endif dap_chain_net_srv_price_unit_uid_t units_type; // Unit type for pricing byte_t version; // Receipt version byte_t padding[3]; // Alignment padding uint64_t units; // Service units consumed uint256_t value_datoshi; // Payment value in datoshi } DAP_ALIGN_PACKED dap_chain_receipt_info_t; ``` **Fields:** - `srv_uid` - Unique identifier of the service being paid for - `addition` - Additional data field (platform-dependent) - `units_type` - Type of service units (seconds, bytes, pieces) - `version` - Receipt format version - `units` - Number of service units consumed - `value_datoshi` - Payment amount in datoshi (smallest token unit) #### dap_chain_datum_tx_receipt_t Complete transaction receipt structure with signatures. ```c typedef struct dap_chain_datum_tx_receipt { dap_chain_tx_item_type_t type; // Transaction item type dap_chain_receipt_info_t receipt_info; // Receipt information uint64_t size; // Total receipt size uint64_t exts_size; // Extensions size byte_t exts_n_signs[]; // Extensions and signatures } DAP_ALIGN_PACKED dap_chain_datum_tx_receipt_t; ``` **Fields:** - `type` - Transaction item type (TX_ITEM_TYPE_RECEIPT) - `receipt_info` - Complete receipt information structure - `size` - Total size of receipt structure - `exts_size` - Size of extensions and signatures section - `exts_n_signs` - Variable-length extensions and signature data ### Transaction Receipt Functions ##### `dap_chain_datum_tx_receipt_utype_get()` Get receipt user type. ```c uint32_t dap_chain_datum_tx_receipt_utype_get(dap_chain_datum_tx_receipt_t *a_receipt); ``` **Parameters:** - `a_receipt` (`dap_chain_datum_tx_receipt_t *`) - Receipt to query **Returns:** - `uint32_t` - User type value **Description:** Extracts the user type from the transaction receipt. ##### `dap_chain_datum_tx_receipt_srv_uid_get()` Get receipt service UID. ```c uint64_t dap_chain_datum_tx_receipt_srv_uid_get(dap_chain_datum_tx_receipt_t *a_receipt); ``` **Parameters:** - `a_receipt` (`dap_chain_datum_tx_receipt_t *`) - Receipt to query **Returns:** - `uint64_t` - Service UID value **Description:** Extracts the service UID from the transaction receipt. ##### `dap_chain_datum_tx_receipt_units_get()` Get receipt units count. ```c uint64_t dap_chain_datum_tx_receipt_units_get(dap_chain_datum_tx_receipt_t *a_receipt); ``` **Parameters:** - `a_receipt` (`dap_chain_datum_tx_receipt_t *`) - Receipt to query **Returns:** - `uint64_t` - Units count value **Description:** Extracts the units count from the transaction receipt. ##### `dap_chain_datum_tx_receipt_value_get()` Get receipt value. ```c uint256_t dap_chain_datum_tx_receipt_value_get(dap_chain_datum_tx_receipt_t *a_receipt); ``` **Parameters:** - `a_receipt` (`dap_chain_datum_tx_receipt_t *`) - Receipt to query **Returns:** - `uint256_t` - Receipt value **Description:** Extracts the value from the transaction receipt. ##### `dap_chain_datum_tx_receipt_signs_count()` Get receipt signatures count. ```c uint16_t dap_chain_datum_tx_receipt_signs_count(dap_chain_datum_tx_receipt_t *a_receipt); ``` **Parameters:** - `a_receipt` (`dap_chain_datum_tx_receipt_t *`) - Receipt to query **Returns:** - `uint16_t` - Number of signatures **Description:** Returns the number of signatures in the transaction receipt. ##### `dap_chain_datum_tx_receipt_check_size()` Check receipt size validity. ```c int dap_chain_datum_tx_receipt_check_size(dap_chain_datum_tx_receipt_t *a_receipt, size_t a_control_size); ``` **Parameters:** - `a_receipt` (`dap_chain_datum_tx_receipt_t *`) - Receipt to check - `a_control_size` (`size_t`) - Expected control size **Returns:** - `0` - Size is valid - `non-zero` - Size validation failed **Description:** Validates that the receipt size matches the expected control size. --- ## Anchor *Based on: `dap_chain_datum_anchor.h` and `dap_chain_datum_anchor.c`* ### Overview Cross-chain anchor structures for inter-blockchain communication and validation. Provides mechanisms for creating anchors that reference data or state across different blockchain networks. **Key Responsibilities:** - Cross-chain data anchoring and referencing - Anchor creation with timestamps and signatures - TSD sections for anchor metadata - Certificate and signature validation for anchors - Hash calculation and verification ### Document Structure - [[#Overview|Overview]] - [[#Enumerations|Enumerations]] - [[#Anchor TSD Types|Anchor TSD Types - TSD type constants]] - [[#Structures|Structures]] - [[#dap_chain_datum_anchor_t|dap_chain_datum_anchor_t - Main anchor structure]] - [[#Functions|Functions]] - [[#Anchor Utilities|Anchor Utilities]] - [[#Anchor Validation|Anchor Validation]] ### Enumerations #### Anchor TSD Types TSD type constants for anchor metadata sections. ```c // Anchor TSD types #define DAP_CHAIN_DATUM_ANCHOR_TSD_TYPE_DECREE_HASH 0x0001 // Decree hash reference ``` ### Structures #### dap_chain_datum_anchor_t Main anchor structure for cross-chain references. ```c typedef struct dap_chain_datum_anchor { uint16_t anchor_version; // Anchor format version struct { dap_time_t ts_created; // Creation timestamp uint32_t data_size; // Size of data section uint32_t signs_size; // Size of signatures section } DAP_ALIGN_PACKED header; byte_t data_n_sign[]; // Variable data and signatures } DAP_ALIGN_PACKED dap_chain_datum_anchor_t; ``` **Fields:** - `anchor_version` - Version of anchor format for compatibility - `ts_created` - Unix timestamp when anchor was created - `data_size` - Size in bytes of anchor data section - `signs_size` - Size in bytes of signature section - `data_n_sign` - Variable-length section containing data and signatures ### Functions #### Anchor Utilities ##### `dap_chain_datum_anchor_get_size()` Calculate total size of anchor structure. ```c size_t dap_chain_datum_anchor_get_size(dap_chain_datum_anchor_t *a_datum_anchor); ``` **Parameters:** - `a_datum_anchor` (`dap_chain_datum_anchor_t *`) - Anchor to measure **Returns:** - `size_t` - Total anchor size including header, data, and signatures **Description:** Calculates complete anchor size including all variable-length sections. ##### `dap_chain_datum_anchor_certs_dump()` Dump anchor certificates to string format. ```c void dap_chain_datum_anchor_certs_dump(dap_string_t *a_str_out, byte_t *a_signs, size_t a_certs_size, const char *a_hash_out_type); ``` **Parameters:** - `a_str_out` (`dap_string_t *`) - Output string buffer - `a_signs` (`byte_t *`) - Signature data to dump - `a_certs_size` (`size_t`) - Size of certificate data - `a_hash_out_type` (`const char *`) - Hash output format ##### `dap_chain_datum_anchor_certs_dump_json()` Dump anchor certificates to JSON format. ```c void dap_chain_datum_anchor_certs_dump_json(json_object *a_json_out, byte_t *a_signs, size_t a_certs_size, const char *a_hash_out_type); ``` **Parameters:** - `a_json_out` (`json_object *`) - JSON object for output - `a_signs` (`byte_t *`) - Signature data to dump - `a_certs_size` (`size_t`) - Size of certificate data - `a_hash_out_type` (`const char *`) - Hash output format #### Anchor Validation ##### `dap_chain_datum_anchor_get_hash_from_data()` Calculate hash from anchor data section. ```c int dap_chain_datum_anchor_get_hash_from_data(dap_chain_datum_anchor_t *a_anchor, dap_hash_fast_t *a_out_hash); ``` **Parameters:** - `a_anchor` (`dap_chain_datum_anchor_t *`) - Anchor to hash - `a_out_hash` (`dap_hash_fast_t *`) - Output buffer for calculated hash **Returns:** - `0` - Hash calculation successful - `non-zero` - Hash calculation failed **Error Conditions:** - Returns non-zero if anchor data is corrupted or invalid --- ## Decree *Based on: `dap_chain_datum_decree.h` and `dap_chain_datum_decree.c`* ### Overview Governance and decree structures for network management and protocol updates. Provides mechanisms for creating, validating, and processing governance decisions and network parameter changes. **Key Responsibilities:** - Network governance decree creation and validation - Protocol parameter updates and changes - Multi-signature decree authorization - Decree TSD sections for metadata - Certificate and authority validation *[This section would be completed based on examination of the actual decree files]* --- ## Other Components *Based on: Various specialized headers (voting, receipt, poll, hashtree, etc.)* ### Overview Additional specialized datum components including voting mechanisms, transaction receipts, polling systems, and hash tree structures for various blockchain operations. **Key Responsibilities:** - Voting system support and vote processing - Transaction receipt handling and validation - Polling mechanism implementation - Hash tree roots and Merkle tree operations - Specialized TSD sections and metadata handling *[Individual components would be documented based on examination of their respective source files]* ## Typical Examples ### Address Creation and Validation Example ```c #include <dap_chain_common.h> void address_example() { log_it_info("=== Address Creation Example ==="); // Step 1: Create address from string const char *addr_str = "mJUUqS9W..."; // Example Base58 address dap_chain_addr_t *addr = dap_chain_addr_from_str(addr_str); if (!addr) { log_it_error("✗ Failed to parse address from string"); return; } log_it_info("✓ Address parsed successfully"); // Step 2: Verify address checksum int checksum_result = dap_chain_addr_check_sum(addr); if (checksum_result == 0) { log_it_info("✓ Address checksum is valid"); } else { log_it_error("✗ Address checksum verification failed: %d", checksum_result); } // Step 3: Check if address is blank bool is_blank = dap_chain_addr_is_blank(addr); if (!is_blank) { log_it_info("✓ Address contains valid data"); // Step 4: Convert back to string const char *converted_str = dap_chain_addr_to_str_static(addr); log_it_info("Address string: %s", converted_str); } else { log_it_info("ℹ Address is blank"); } // Step 5: Cleanup DAP_DELETE(addr); log_it_info("Address example completed"); } ``` ### Hash Conversion Example ```c #include <dap_chain_common.h> void hash_conversion_example() { log_it_info("=== Hash Conversion Example ==="); // Step 1: Create example hash dap_chain_hash_slow_t example_hash; memset(&example_hash, 0xAB, sizeof(example_hash)); // Fill with example data // Step 2: Convert hash to string char hash_str[256]; size_t str_len = dap_chain_hash_slow_to_str(&example_hash, hash_str, sizeof(hash_str)); if (str_len > 0) { log_it_info("✓ Hash converted to string: %s", hash_str); log_it_info("String length: %zu characters", str_len); // Step 3: Check hash quality dap_chain_hash_slow_kind_t hash_kind = dap_chain_hash_slow_kind_check(&example_hash, 0x00); switch (hash_kind) { case HASH_GOLD: log_it_info("✓ Hash quality: GOLD"); break; case HASH_SILVER: log_it_info("✓ Hash quality: SILVER"); break; case HASH_COPPER: log_it_info("✓ Hash quality: COPPER"); break; case HASH_USELESS: log_it_info("ℹ Hash quality: USELESS"); break; } } else { log_it_error("✗ Hash conversion failed"); } log_it_info("Hash conversion example completed"); } ``` --- *See also: [[Modules/Module Chain|Module Chain]], [[Modules/Module Wallet|Module Wallet]], [[ETC/Development Guide|Development Guide]]*