kal_sc/lib.rs
1//! Smart contract SDK for the Kalvora Network.
2//!
3//! Write contracts in Rust, compile to `wasm32-unknown-unknown`, and deploy
4//! to Kalvora validators. `kal-sc` wraps the native host ABI exposed by
5//! validators in a safe, idiomatic Rust API, handling serialization, memory
6//! management, and the different execution contexts (direct calls,
7//! `delegatecall`, derived wallets, etc.).
8//!
9//! # Quick start
10//!
11//! ```ignore
12//! use kal_sc::{emit, wasmedge_bindgen};
13//!
14//! #[wasmedge_bindgen]
15//! pub fn hello(name: String) {
16//! emit(&format!("hello, {}", name));
17//! }
18//! ```
19//!
20//! # Modules
21//!
22//! - [`transfer`] — move tokens: `send`, `send_multi`, `send_all`, `deposit`, `burn`, `mint`
23//! - [`state`] — persist data: `save`, `load`, `clear`, `exists`
24//! - [`query`] — read network state: balances, token metadata, contract existence
25//! - [`call`] — invoke other contracts: `execute` or `delegate`
26//! - [`txn`] — submit raw network transactions
27//! - [`wallet`] — derive wallets owned by this contract
28//! - [`context`] — read the current frame: sender, block time, contract identity
29//! - [`crypto`] — hashing primitives: `sha256`, `sha512`, `blake3`, `shake`
30//!
31//! # Non-WASM targets
32//!
33//! On targets other than `wasm32`, every host function is stubbed to panic,
34//! so the crate compiles (and docs build) everywhere, but contract logic can
35//! only be exercised inside a validator.
36
37#![allow(clippy::result_unit_err)]
38
39mod base64;
40mod ffi;
41mod output;
42mod call_codec;
43mod types;
44
45pub mod call;
46pub mod context;
47pub mod crypto;
48pub mod query;
49pub mod state;
50pub mod transfer;
51pub mod txn;
52pub mod wallet;
53
54pub use types::*;
55
56#[allow(unused_imports)]
57use wasmedge_bindgen::*;
58pub use wasmedge_bindgen_macro::wasmedge_bindgen;
59
60use serde::{de::DeserializeOwned, Serialize};
61
62/// The canonical Kalvora Network contract identifier.
63pub const KALVORA_NETWORK_CONTRACT_ID: &str = "KALXvxhUMJERCse4e6b2jeXFkcqqpiUByQQckvPZm4szmF3Ao";
64
65/// The PreGov contract identifier.
66pub const PREGOV_CONTRACT_ID: &str = "PREDNmAbR9Juj233WUQ6kqFGf28oe5kVAK5Y3mhGfE6cVBF95";
67
68/// The Kip contract identifier.
69pub const KIP_CONTRACT_ID: &str = "K1PoaARovFYFLAqWRoXubXBkJ2dSynjzUyRzsBc3ycbGEn9pK";
70
71/// The Legal contract identifier.
72pub const LEGAL_CONTRACT_ID: &str = "LEGWZ2q8Dw1B8Z9r61STBkaFLPMfDYQPQXFEzJzmQEdyw9tg5";
73
74/// The Mint contract identifier.
75pub const MINT_CONTRACT_ID: &str = "M1NTxB3N3GeM5CZLHj3bDLtuye15VQxTTJ3omn9g9Ti87o9b3";
76
77/// The Treasury contract identifier.
78pub const TREASURY_CONTRACT_ID: &str = "TREF2UL7Ut6JDTcAaGfY32UrQv9aC5MVyyDjNbFKjhAq51cet";
79
80/// The Tech contract identifier.
81pub const TECH_CONTRACT_ID: &str = "TECfnGgEykEs1G57P43ABBb6i73LgwAbHLPf46z1kGyY9A7PY";
82
83/// The Marketing contract identifier.
84pub const MARKETING_CONTRACT_ID: &str = "MARYCY87a7ZdeYERoCJbwFv8r6Sm69zjKEspEEo91kcDGH3ce";
85
86/// The BridgeTokens contract identifier.
87pub const BRIDGE_TOKENS_CONTRACT_ID: &str = "BRT3zKHfF8RgqbaYGTrv58j3LpNUr5EAJBVn63sBfpTE7AfFk";
88
89/// The BridgeGuardians contract identifier.
90pub const BRIDGE_GUARDIANS_CONTRACT_ID: &str =
91 "BRGhGqDbqLMqYNRdCSbBVujfQurhW5x3AkQQPnUUCe5Ctb5ua";
92
93/// The Smart Contract Maintenance contract identifier.
94pub const SMART_CONTRACT_MAINTENANCE_CONTRACT_ID: &str =
95 "SCMgkjeFFnHPR7rr6AGqBp1FTm7YK67GiJrLcU159QeZxGk6d";
96
97/// The Treasury wallet address.
98pub const TREASURY_WALLET: &str = "4Yg2ZeYrzMjVBXvU2YWtuZ7CzWR9atnQCD35TQj1kKcH";
99
100/// Emit a log message from the contract. Visible in transaction results.
101pub fn emit(message: &str) {
102 let ptr = message.as_bytes().as_ptr();
103 let len = message.len() as i32;
104 unsafe { ffi::emit(ptr, len) };
105}
106
107/// Emit a block-level log message from the contract.
108pub fn emit_block(message: &str) {
109 let ptr = message.as_bytes().as_ptr();
110 let len = message.len() as i32;
111 unsafe { ffi::emit_block(ptr, len) };
112}
113
114/// Encode `value` as a postcard-serialized, base64-encoded string.
115///
116/// Useful for passing structured data out of a contract via `emit`, or for
117/// preparing payloads to be consumed later by [`decode`].
118pub fn encode<T: Serialize>(value: &T) -> Result<String, ()> {
119 let bytes = postcard::to_allocvec(value).map_err(|_| ())?;
120 Ok(base64::encode(&bytes))
121}
122
123/// Decode a postcard-serialized, base64-encoded string back into `T`.
124///
125/// Useful for decoding structured parameters passed into a contract function
126/// as a single encoded string.
127pub fn decode<T: DeserializeOwned>(encoded: &str) -> Result<T, ()> {
128 let bytes = base64::decode(encoded)?;
129 postcard::from_bytes(&bytes).map_err(|_| ())
130}