truthlinked-sdk 0.1.1

TruthLinked smart-contract SDK
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125

//! TruthLinked Smart Contract SDK
//!
//! This SDK provides a complete toolkit for building smart contracts on the TruthLinked blockchain.
//!
//! # Features
//!
//! - **Storage**: Type-safe collections (maps, vectors, blobs) with dual API pattern
//! - **Codec**: Efficient encoding/decoding for 32-byte and variable-length data
//! - **Events**: Structured logging with indexed topics
//! - **Manifests**: Declare storage access patterns for parallel execution
//! - **Oracle**: HTTP requests for external data
//! - **Testing**: In-memory storage harness for unit tests
//!
//! # Quick Start
//!
//! ```ignore
//! use truthlinked_sdk::prelude::*;
//!
//! #[derive(Manifest)]
//! struct Counter {
//!     #[manifest(read, write)]
//!     value: Slot,
//! }
//!
//! fn increment() -> Result<()> {
//!     let counter = Counter {
//!         value: Slot::from_label("count"),
//!     };
//!     let current = counter.value.read_u64()?;
//!     counter.value.write_u64(current + 1)?;
//!     Ok(())
//! }
//!
//! contract_entry!(increment);
//! ```
//!
//! # Module Overview
//!
//! - [`abi`] - Function selectors and calldata parsing
//! - [`backend`] - Storage backend abstraction
//! - [`call`] - Cross-contract calls
//! - [`codec`] - Encoding/decoding traits and builders
//! - [`collections`] - StorageMap, StorageVec, StorageBlob
//! - [`context`] - Execution context (caller, height, timestamp, etc.)
//! - [`env`] - Low-level WASM host bindings
//! - [`error`] - Error types and Result alias
//! - [`hashing`] - Cryptographic utilities
//! - [`log`] - Event system
//! - [`manifest`] - Storage access declarations
//! - [`oracle`] - HTTP oracle interface
//! - [`storage`] - Direct storage slot access
//! - [`testing`] - Unit test utilities

#![no_std]

extern crate alloc;
extern crate self as truthlinked_sdk;

pub mod abi;
pub mod backend;
pub mod call;
pub mod codec;
pub mod collections;
pub mod context;
pub mod env;
pub mod error;
pub mod hashing;
pub mod log;
pub mod manifest;
pub mod oracle;
pub mod storage;
#[cfg(any(test, feature = "testing"))]
pub mod testing;

pub use error::{Error, Result};
pub use truthlinked_sdk_macros::{error_code, require, BytesCodec, Codec32, Event, Manifest};

/// Prelude module with commonly used imports.
///
/// Import everything with `use truthlinked_sdk::prelude::*;`
pub mod prelude {
    pub use crate::abi;
    pub use crate::backend::{HostStorage, MemoryStorage, StorageBackend};
    pub use crate::call;
    pub use crate::codec::{BytesCodec, Codec32, Decoder, Encoder};
    pub use crate::collections::{Namespace, StorageBlob, StorageMap, StorageVec};
    pub use crate::context;
    pub use crate::env;
    pub use crate::hashing;
    pub use crate::log;
    pub use crate::manifest::{ContractManifest, Manifest, ManifestBuilder, StorageKeySpec};
    pub use crate::oracle;
    pub use crate::storage::{self, Slot};
    #[cfg(any(test, feature = "testing"))]
    pub use crate::testing::{StorageHarness, TestBlob, TestMap, TestVec};
    pub use crate::{
        contract_entry, error_code, require, slot, BytesCodec, Codec32, Error, Event, Manifest,
        Result,
    };
}

/// Defines the contract entry point.
///
/// # Example
///
/// ```ignore
/// fn my_handler() -> Result<()> {
///     // Contract logic
///     Ok(())
/// }
///
/// contract_entry!(my_handler);
/// ```
#[macro_export]
macro_rules! contract_entry {
    ($handler:path) => {
        #[no_mangle]
        pub extern "C" fn execute() -> i32 {
            match $handler() {
                Ok(()) => 0,
                Err(err) => err.code(),
            }
        }
    };
}