Skip to main content

kal_sc/types/
txn.rs

1use serde::{Deserialize, Serialize};
2
3#[derive(Serialize, Deserialize, Debug, Clone)]
4pub enum TxnSender {
5    Delegate {
6        sc_name: String,
7        sc_instance: String,
8    },
9    Current,
10    ContractBefore,
11    OriginalContract,
12    User,
13}
14
15#[derive(Serialize, Deserialize, Debug, Clone)]
16pub(crate) struct NetworkTXN {
17    pub(crate) txn_type: TransactionType,
18    pub(crate) payload: String,
19    pub(crate) sender: TxnSender,
20}
21
22// Numeric wire values are protocol identifiers. Retired values stay invalid;
23// deriving ordinary enum serialization after removing variants would renumber
24// all later Postcard transactions.
25#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
26#[repr(u32)]
27pub enum TransactionType {
28    #[default]
29    UnknownType = 0,
30    CoinType = 1,
31    MintType = 2,
32    ItemMintType = 3,
33    ContractTxnType = 4,
34    VoteType = 5,
35    ProposalType = 6,
36    SmartContractType = 7,
37    SmartContractExecuteType = 8,
38    ExpenseRatioType = 9,
39    NftType = 10,
40    UpdateContractType = 11,
41    ValidatorRegistrationType = 12,
42    ValidatorHeartbeatType = 13,
43    ProposalResultType = 14,
44    DelegatedVotingType = 15,
45    RevokeType = 16,
46    ComplianceType = 19,
47    SbtBurnType = 20,
48    RequiredVersion = 21,
49    SmartContractInstantiateType = 22,
50    AllowanceType = 23,
51    ProposalCancelType = 24,
52}
53
54// Keep Serde's named unit variants for human-readable formats. Empty slots are
55// retired wire values and are never accepted by deserialization.
56const TRANSACTION_TYPE_NAMES: &[&str] = &[
57    "UnknownType", "CoinType", "MintType", "ItemMintType", "ContractTxnType",
58    "VoteType", "ProposalType", "SmartContractType", "SmartContractExecuteType",
59    "ExpenseRatioType", "NftType", "UpdateContractType", "ValidatorRegistrationType",
60    "ValidatorHeartbeatType", "ProposalResultType", "DelegatedVotingType", "RevokeType",
61    "", "", "ComplianceType", "SbtBurnType", "RequiredVersion",
62    "SmartContractInstantiateType", "AllowanceType", "ProposalCancelType",
63];
64
65impl Serialize for TransactionType {
66    fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
67        serializer.serialize_unit_variant("TransactionType", *self as u32,
68                                          TRANSACTION_TYPE_NAMES[*self as usize])
69    }
70}
71
72impl<'de> Deserialize<'de> for TransactionType {
73    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
74        if !deserializer.is_human_readable() {
75            return Self::try_from(u32::deserialize(deserializer)?).map_err(serde::de::Error::custom);
76        }
77
78        struct Variant(TransactionType);
79        struct VariantVisitor;
80        impl<'de> serde::de::Visitor<'de> for VariantVisitor {
81            type Value = Variant;
82
83            fn expecting(&self, formatter: &mut std::fmt::Formatter) -> std::fmt::Result {
84                formatter.write_str("a live transaction variant")
85            }
86
87            fn visit_u64<E: serde::de::Error>(self, value: u64) -> Result<Variant, E> {
88                let number = u32::try_from(value).map_err(E::custom)?;
89                TransactionType::try_from(number).map(Variant).map_err(E::custom)
90            }
91
92            fn visit_str<E: serde::de::Error>(self, value: &str) -> Result<Variant, E> {
93                if !value.is_empty() {
94                    if let Some(number) = TRANSACTION_TYPE_NAMES.iter().position(|name| *name == value) {
95                        return TransactionType::try_from(number as u32).map(Variant).map_err(E::custom);
96                    }
97                }
98                Err(E::custom("unknown or retired transaction type"))
99            }
100        }
101        impl<'de> Deserialize<'de> for Variant {
102            fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
103                deserializer.deserialize_identifier(VariantVisitor)
104            }
105        }
106        struct TypeVisitor;
107        impl<'de> serde::de::Visitor<'de> for TypeVisitor {
108            type Value = TransactionType;
109
110            fn expecting(&self, formatter: &mut std::fmt::Formatter) -> std::fmt::Result {
111                formatter.write_str("a live transaction variant")
112            }
113
114            fn visit_enum<A: serde::de::EnumAccess<'de>>(self, value: A) -> Result<TransactionType, A::Error> {
115                let (variant, access) = value.variant::<Variant>()?;
116                serde::de::VariantAccess::unit_variant(access)?;
117                Ok(variant.0)
118            }
119        }
120        deserializer.deserialize_enum("TransactionType", TRANSACTION_TYPE_NAMES, TypeVisitor)
121    }
122}
123
124impl From<TransactionType> for u32 {
125    fn from(value: TransactionType) -> Self {
126        value as u32
127    }
128}
129
130impl TryFrom<u32> for TransactionType {
131    type Error = &'static str;
132
133    fn try_from(value: u32) -> Result<Self, Self::Error> {
134        match value {
135            0 => Ok(Self::UnknownType),
136            1 => Ok(Self::CoinType),
137            2 => Ok(Self::MintType),
138            3 => Ok(Self::ItemMintType),
139            4 => Ok(Self::ContractTxnType),
140            5 => Ok(Self::VoteType),
141            6 => Ok(Self::ProposalType),
142            7 => Ok(Self::SmartContractType),
143            8 => Ok(Self::SmartContractExecuteType),
144            9 => Ok(Self::ExpenseRatioType),
145            10 => Ok(Self::NftType),
146            11 => Ok(Self::UpdateContractType),
147            12 => Ok(Self::ValidatorRegistrationType),
148            13 => Ok(Self::ValidatorHeartbeatType),
149            14 => Ok(Self::ProposalResultType),
150            15 => Ok(Self::DelegatedVotingType),
151            16 => Ok(Self::RevokeType),
152            19 => Ok(Self::ComplianceType),
153            20 => Ok(Self::SbtBurnType),
154            21 => Ok(Self::RequiredVersion),
155            22 => Ok(Self::SmartContractInstantiateType),
156            23 => Ok(Self::AllowanceType),
157            24 => Ok(Self::ProposalCancelType),
158            _ => Err("unknown or retired transaction type"),
159        }
160    }
161}
162
163#[derive(Serialize, Deserialize, Debug, Clone, Default)]
164pub struct ContractUpdateTXN {
165    pub contract_id: String,
166    pub contract_version: u64,
167    pub name: Option<String>,
168    pub governance: Option<Governance>,
169    pub restricted_keys: Vec<RestrictedKey>,
170    pub contract_fees: Option<ContractFees>,
171    pub custom_parameters: Vec<KeyValuePair>,
172    pub expense_ratio: Vec<ExpenseRatio>,
173    pub token_compliance: Vec<TokenCompliance>,
174    pub kyc_status: Option<bool>,
175    pub immutable_kyc_status: Option<bool>,
176}
177
178#[derive(Serialize, Deserialize, Debug, Clone, Default)]
179pub struct InstrumentContractTXN {
180    pub contract_version: u64,
181    pub symbol: String,
182    pub name: String,
183    pub governance: Option<Governance>,
184    pub restricted_keys: Vec<RestrictedKey>,
185    pub max_supply: Option<String>,
186    pub contract_fees: Option<ContractFees>,
187    pub premint_wallets: Vec<PreMintWallet>,
188    pub coin_denomination: Option<CoinDenomination>,
189    pub custom_parameters: Vec<KeyValuePair>,
190    pub contract_id: String,
191    pub expense_ratio: Vec<ExpenseRatio>,
192    pub contract_type: ContractType,
193    pub update_contract_fees: bool,
194    pub update_expense_ratio: bool,
195    pub token_compliance: Vec<TokenCompliance>,
196    pub kyc_status: bool,
197    pub immutable_kyc_status: bool,
198    pub max_supply_release: Vec<MaxSupplyRelease>,
199}
200
201#[derive(Serialize, Deserialize, Debug, Clone, Default)]
202pub struct PreMintWallet {
203    pub address: String,
204    pub amount: String,
205}
206
207#[derive(Serialize, Deserialize, Debug, Clone, Default)]
208pub struct CoinDenomination {
209    pub denomination_name: String,
210    pub amount: String,
211}
212
213#[derive(Serialize, Deserialize, Debug, Clone, Default)]
214pub struct MaxSupplyRelease {
215    pub release_date: ProtoTimestamp,
216    pub amount: String,
217}
218
219#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq, Default)]
220pub enum ContractType {
221    #[default]
222    Token,
223    Nft,
224    Sbt,
225}
226
227#[derive(Serialize, Deserialize, Debug, Clone, Default)]
228pub struct Governance {
229    pub governance_type: GovernanceType,
230    pub regular_quorum: u32,
231    pub fast_quorum: Option<u32>,
232    pub voting_instrument: Vec<String>,
233    pub threshold: u32,
234    pub chicken_dinner: Option<bool>,
235    pub allow_multi: bool,
236    pub voting_period: Option<u32>,
237    pub allowed_proposal_instrument: Vec<String>,
238    pub proposal_period: Option<ProposalPeriod>,
239    pub stage_length: Vec<Stage>,
240    pub start_timestamp: Option<ProtoTimestamp>,
241    pub max_approved: Option<u32>,
242}
243
244#[derive(Serialize, Deserialize, Debug, Clone, Default)]
245pub struct Stage {
246    pub length: u32,
247    pub period: ProposalPeriod,
248    pub break_stage: bool,
249    pub max_approved: u32,
250}
251
252#[derive(Serialize, Deserialize, Debug, Clone, Default)]
253pub struct RestrictedKey {
254    pub public_key: PublicKey,
255    pub global: bool,
256    pub update_contract: bool,
257    pub transfer: bool,
258    pub mint: bool,
259    pub vote: bool,
260    pub propose: bool,
261    pub compliance: bool,
262    pub expense_ratio: bool,
263    pub revoke: bool,
264    pub key_weight: u32,
265}
266
267#[derive(Serialize, Deserialize, Debug, Clone, Default)]
268pub struct PublicKey {
269    /// Base58-encoded single public key (e.g. `"A_c_7kdro2TE..."`).
270    pub single: String,
271    pub multi: Option<MultiKey>,
272    /// Smart-contract auth identifier in the form `"sc_<contract>_<instance>"`,
273    /// e.g. `"sc_sc_test_proxy_1"`. Used to identify a smart contract as a
274    /// restricted-key holder.
275    pub smart_contract_auth: Option<String>,
276    /// Governance auth identifier.
277    pub governance_auth: Option<String>,
278}
279
280impl PublicKey {
281    /// Build a `PublicKey` that authorizes a smart contract, identified by
282    /// its `name` and optional `instance` (defaults to `"1"`).
283    ///
284    /// Equivalent to populating `smart_contract_auth` with the string
285    /// returned by [`crate::wallet::sc_auth`] and leaving all other fields
286    /// at their defaults.
287    pub fn sc(contract: &str, instance: Option<&str>) -> Self {
288        let inst = instance.unwrap_or("1");
289        PublicKey {
290            smart_contract_auth: Some(format!("sc_{contract}_{inst}")),
291            ..Default::default()
292        }
293    }
294}
295
296#[derive(Serialize, Deserialize, Debug, Clone, Default)]
297pub struct MultiKey {
298    /// Base58-encoded public keys, with class prefix (e.g. `"c1_<key>"`).
299    pub public_keys: Vec<String>,
300    pub signatures: Vec<Vec<u8>>,
301    pub multi_patterns: Vec<MultiPatterns>,
302    pub hash_tokens: Vec<String>,
303}
304
305#[derive(Serialize, Deserialize, Debug, Clone, Default)]
306pub struct MultiPatterns {
307    pub class: Vec<u32>,
308    pub required: Vec<u32>,
309}
310
311#[derive(Serialize, Deserialize, Debug, Clone, Default)]
312pub struct ContractFees {
313    pub fee: String,
314    /// Base58-encoded fee recipient wallet address.
315    pub fee_address: Option<String>,
316    pub burn: String,
317    pub validator: String,
318    pub allowed_fee_instrument: Vec<String>,
319    pub contract_fee_type: ContractFeeType,
320}
321
322#[derive(Serialize, Deserialize, Debug, Clone, Default)]
323pub struct KeyValuePair {
324    pub key: String,
325    pub value: String,
326}
327
328#[derive(Serialize, Deserialize, Debug, Clone, Default)]
329pub struct ExpenseRatio {
330    pub day: u32,
331    pub month: u32,
332    pub percent: u32,
333}
334
335#[derive(Serialize, Deserialize, Debug, Clone, Default)]
336pub struct TokenCompliance {
337    pub compliance: Vec<Compliance>,
338}
339
340#[derive(Serialize, Deserialize, Debug, Clone, Default)]
341pub struct Compliance {
342    pub contract_id: String,
343    pub compliance_level: u32,
344}
345
346#[derive(Serialize, Deserialize, Debug, Clone, Default)]
347pub struct ProtoTimestamp {
348    pub seconds: i64,
349    pub nanos: i32,
350}
351
352#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq, Default)]
353pub enum ContractFeeType {
354    #[default]
355    None,
356    Fixed,
357    CurEquivalent,
358    Percentage,
359}
360
361#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq, Default)]
362pub enum GovernanceType {
363    #[default]
364    Adaptive,
365    Staged,
366    Cycle,
367    Staggered,
368    Remove,
369}
370
371#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq, Default)]
372pub enum ProposalPeriod {
373    #[default]
374    Days,
375    Months,
376}
377
378/// Full coin-transfer transaction, mirroring the network's `CoinTXN` proto
379/// (minus `base`, which the network fills in from the transaction context).
380///
381/// Use this when you need the full expressiveness of a coin transfer: multiple
382/// inputs, multiple outputs, explicit fee routing, etc. For the common
383/// "send X of Y to one recipient" case, prefer [`crate::transfer::send`] from
384/// the `transfer` module, which handles all of this internally.
385///
386/// # Address / key fields
387///
388/// Every wallet address or public key in this transaction — including
389/// `output_transfers[i].wallet_address` and `auth.public_key[i].single` — is
390/// passed as a base58 `String`. The network decodes it on its side. Raw
391/// binary fields (signatures, hashes) stay as `Vec<u8>`.
392#[derive(Serialize, Deserialize, Debug, Clone, Default)]
393pub struct CoinTXN {
394    pub contract_id: String,
395    /// Sender authorization. For smart-contract-originated transfers the
396    /// network populates `public_key`, `signature`, and `nonce` from the
397    /// `TxnSender` context — callers typically leave this at `Default`.
398    pub auth: TransferAuthentication,
399    pub input_transfers: Vec<InputTransfers>,
400    pub output_transfers: Vec<OutputTransfers>,
401    /// Contract used to pay this transfer's contract-level fee, if the
402    /// token being transferred has one configured. Leave as `None` when
403    /// transferring a token without contract fees.
404    pub contract_fee_id: Option<String>,
405    pub contract_fee_amount: Option<String>,
406}
407
408/// Sender authentication for a `CoinTXN`. Mirrors the network's
409/// `TransferAuthentication` proto. Each position in `public_key`,
410/// `signature`, and `nonce` refers to the same signer.
411///
412/// For SC-originated transfers the network populates every field here from
413/// the `TxnSender` context; callers typically leave this at `Default`.
414#[derive(Serialize, Deserialize, Debug, Clone, Default)]
415pub struct TransferAuthentication {
416    pub public_key: Vec<PublicKey>,
417    pub signature: Vec<Vec<u8>>,
418    pub nonce: Vec<u64>,
419    /// Base58-encoded allowance wallet addresses.
420    pub allowance_address: Vec<String>,
421    pub allowance_nonce: Vec<u64>,
422}
423
424/// Describes which signer (by index into `TransferAuthentication.public_key`)
425/// is sending, how much, and how fees are split. Mirrors `InputTransfers`.
426///
427/// `fee_percent` and `contract_fee_percent` use a fixed-point scale where
428/// `100_000_000` = 100%.
429#[derive(Serialize, Deserialize, Debug, Clone, Default)]
430pub struct InputTransfers {
431    pub index: u64,
432    pub amount: String,
433    pub fee_percent: u32,
434    pub contract_fee_percent: Option<u32>,
435}
436
437/// A single coin-transfer output. Mirrors `OutputTransfers`.
438#[derive(Serialize, Deserialize, Debug, Clone, Default)]
439pub struct OutputTransfers {
440    /// Base58-encoded recipient wallet address.
441    pub wallet_address: String,
442    pub amount: String,
443    pub memo: Option<String>,
444}
445
446/// Full mint transaction, mirroring the network's `MintTXN` proto (minus
447/// `base`, which the network fills in).
448///
449/// For the common "mint X to Y" case, prefer [`crate::transfer::mint`] from
450/// the `transfer` module.
451#[derive(Serialize, Deserialize, Debug, Clone, Default)]
452pub struct MintTXN {
453    pub contract_id: String,
454    pub amount: String,
455    /// Base58-encoded recipient wallet address.
456    pub recipient_address: String,
457}