tx3_sdk/
core.rs

1//! Core types and data structures for the Tx3 SDK.
2//!
3//! This module provides the fundamental types used throughout the SDK for representing
4//! transaction data, addresses, and various envelope formats.
5
6use serde::{Deserialize, Serialize};
7
8/// Flexible key-value arguments for transaction execution.
9///
10/// This type represents the arguments passed to a transaction invocation.
11/// Keys are parameter names and values are JSON values that can represent
12/// various types (strings, numbers, booleans, arrays, objects).
13///
14/// # Example
15///
16/// ```ignore
17/// use serde_json::json;
18/// use tx3_sdk::core::ArgMap;
19///
20/// let mut args = ArgMap::new();
21/// args.insert("sender".to_string(), json!("addr1abc..."));
22/// args.insert("amount".to_string(), json!(1000000));
23/// args.insert("allow_bypass".to_string(), json!(true));
24/// ```
25pub type ArgMap = serde_json::Map<String, serde_json::Value>;
26
27/// Environment variables for transaction execution context.
28///
29/// Environment variables provide additional context for transaction execution,
30/// such as network parameters, protocol constants, or other configuration values
31/// that affect how transactions are resolved.
32///
33/// # Example
34///
35/// ```ignore
36/// use serde_json::json;
37/// use tx3_sdk::core::EnvMap;
38///
39/// let mut env = EnvMap::new();
40/// env.insert("network_id".to_string(), json!(1)); // mainnet
41/// env.insert("slot".to_string(), json!(50000000));
42/// ```
43pub type EnvMap = serde_json::Map<String, serde_json::Value>;
44
45/// Bech32-encoded blockchain address.
46///
47/// This type alias represents blockchain addresses in their Bech32-encoded form,
48/// which is the human-readable format commonly used in wallets and explorers.
49///
50/// # Example
51///
52/// ```ignore
53/// use tx3_sdk::core::Address;
54///
55/// let address: Address = "addr1q9y8r3q4z3q3q3q3q3q3q3q3q3q3q3q3q3q3q3q3q3q3q3q3q3q3q3".to_string();
56/// ```
57pub type Address = String;
58
59/// UTXO reference in the format `0x[64hex]#[index]`.
60///
61/// This type alias represents a reference to an unspent transaction output (UTXO)
62/// on a UTxO-based blockchain. The format consists of:
63/// - A 64-character hexadecimal transaction hash (prefixed with `0x`)
64/// - A `#` separator
65/// - An output index number
66///
67/// # Example
68///
69/// ```ignore
70/// use tx3_sdk::core::UtxoRef;
71///
72/// let utxo_ref: UtxoRef = "0xabc123...def456#0".to_string();
73/// ```
74pub type UtxoRef = String;
75
76/// A generic envelope for byte-encoded data with content type information.
77///
78/// This structure wraps binary data (typically encoded as hex or base64 strings)
79/// along with metadata about the content type and encoding. It's commonly used
80/// for transaction bytes, signatures, and other cryptographic data.
81///
82/// # Fields
83///
84/// * `content` - The encoded data as a string (typically hex or base64)
85/// * `content_type` - MIME type or encoding identifier (e.g., "application/cbor", "hex")
86///
87/// # Example
88///
89/// ```ignore
90/// use tx3_sdk::core::BytesEnvelope;
91///
92/// let envelope = BytesEnvelope {
93///     content: "a10081825820abc123...".to_string(),
94///     content_type: "application/cbor".to_string(),
95/// };
96/// ```
97#[derive(Debug, Deserialize, Serialize, Clone)]
98pub struct BytesEnvelope {
99    /// The encoded payload content as a string.
100    ///
101    /// This field accepts either the alias "payload" or the primary name "content"
102    /// for backward compatibility with different serialization formats.
103    #[serde(alias = "payload")]
104    pub content: String,
105
106    /// The content type or encoding of the payload.
107    ///
108    /// This field accepts either "contentType" or the alias "encoding" for
109    /// backward compatibility with different serialization formats.
110    #[serde(rename = "contentType", alias = "encoding")]
111    pub content_type: String,
112}
113
114/// Encoding format for Transaction Intermediate Representation (TIR) data.
115///
116/// This enum specifies how TIR data is encoded when serialized.
117#[derive(Debug, Deserialize, Serialize, Clone)]
118#[serde(rename_all = "lowercase")]
119pub enum TirEncoding {
120    /// Hexadecimal encoding (e.g., "abc123...")
121    Hex,
122    /// Base64 encoding (e.g., "q83v...")
123    Base64,
124}
125
126/// An envelope containing Transaction Intermediate Representation (TIR) data.
127///
128/// TIR is the intermediate format used by TX3 to represent transactions in a
129/// protocol-agnostic way before they are resolved to specific blockchain transactions.
130/// This envelope wraps the TIR content with metadata about its encoding and version.
131///
132/// # Fields
133///
134/// * `content` - The encoded TIR data
135/// * `encoding` - The encoding format used (hex or base64)
136/// * `version` - The TIR specification version (e.g., "v1beta0")
137///
138/// # Example
139///
140/// ```ignore
141/// use tx3_sdk::core::{TirEnvelope, TirEncoding};
142///
143/// let envelope = TirEnvelope {
144///     content: "a10081825820...".to_string(),
145///     encoding: TirEncoding::Hex,
146///     version: "v1beta0".to_string(),
147/// };
148/// ```
149#[derive(Debug, Deserialize, Serialize, Clone)]
150pub struct TirEnvelope {
151    /// The encoded TIR content.
152    pub content: String,
153
154    /// The encoding format of the content.
155    pub encoding: TirEncoding,
156
157    /// The TIR specification version.
158    pub version: String,
159}
tx3_sdk/core.rs

tx3_sdk/
core.rs
