rootchain-std 1.0.2

Standard library for RootChain smart contracts, providing utilities for state management, events, and entry points.
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

# rootchain-std

[![Crates.io](https://img.shields.io/crates/v/rootchain-std.svg)](https://crates.io/crates/rootchain-std)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](../../LICENSE)

> **The standard library for developing RootChain smart contracts.**

`rootchain-std` is the developer-facing toolkit for authoring on-chain programs that run inside the RootChain WASM virtual machine. It provides safe, ergonomic access to host functions (state storage, events, caller context), token standards (RRC-20, RRC-721), and the `#[rootchain_contract]` macro.

---

## What's Inside

| Module | Description |
| :--- | :--- |
| `traits` | RRC-20 and RRC-721 token standard trait definitions |
| `rrc721` | Base implementation for Non-Fungible Token collections |
| `types` | Contract-local types (e.g., `TokenId`) |
| `error` | `ContractError` type for safe error handling |
| `lib` | Host function bindings: `state_get`, `state_set`, `get_caller`, `log_event`, `set_metadata` |

---

## Installation

```toml
[dependencies]
rootchain-std = { version = "1.0.2", default-features = false }
```

> **Note**: Always use `default-features = false` for production contracts. The `std` feature enables the full standard library, which is not available in WASM.

Enable the `test-utils` feature to use in-memory mock host functions during unit testing:
```toml
[dev-dependencies]
rootchain-std = { version = "1.0.2", features = ["test-utils"] }
```

---

## Writing a Contract

### 1. Define Your Contract

```rust
#![no_std]
extern crate alloc;

use rootchain_std::{rootchain_contract, traits::RRC20, Address};

pub struct MyToken {
    name: alloc::string::String,
}

#[rootchain_contract]
impl MyToken {
    pub fn init(&mut self, _input: &[u8]) { /* ... */ }
    pub fn transfer(&mut self, input: &[u8]) { /* ... */ }
    pub fn balance_of(&self, input: &[u8]) { /* ... */ }
}
```

### 2. Access Host Functions

```rust
use rootchain_std::{read_input, write_output, log, get_caller, log_event};

// Read ABI-encoded input from the VM
let input = read_input();

// Write output back to the VM
write_output(&encoded_response);

// Emit a structured event (indexed by topic hashes)
let topic = Hash([0u8; 32]);
log_event(&[topic], &payload);
```

### 3. State Management

```rust
// State is accessed via raw host function calls
// The rootchain_std::storage module provides typed helpers
unsafe {
    state_set(key.as_ptr(), key.len(), value.as_ptr(), value.len());
}
```

---

## Token Standards

### RRC-20 (Fungible Tokens)
Implement the `RRC20` trait to create a fungible token compatible with the RootChain explorer and wallet.

### RRC-721 (Non-Fungible Tokens)
Implement the `RRC721` trait or extend `BaseRRC721` from `rootchain_std::rrc721` for an NFT collection.

---

## License

MIT — See [LICENSE](../../LICENSE) for details.