tronz 0.5.0

Idiomatic, async-first Rust SDK for the TRON network.
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
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158

# tronz

tronz connects applications to the TRON network.

An idiomatic, async-first Rust SDK for TRON — inspired by [alloy](https://github.com/alloy-rs/alloy).

## Installation

Add the `tronz` crate:

```sh
cargo add tronz
```

Or in your `Cargo.toml`:

```toml
tronz = "0.5"
```

The default features include the TLS-enabled gRPC provider, contract bindings,
and local signing. The `full` feature adds mnemonic, keystore, and TIP-712
signing on top; `signer-aws` stays opt-in because it needs an AWS account. A
full list can be found in the
[`tronz` crate's `Cargo.toml`](https://github.com/throgxyz/tronz/blob/main/crates/tronz/Cargo.toml).

## Examples

### Querying the latest block

```rust,no_run
use tronz::{ProviderBuilder, TronProvider, TRONGRID_MAINNET};

# async fn example() -> Result<(), Box<dyn std::error::Error>> {
let provider = ProviderBuilder::new().connect_grpc(TRONGRID_MAINNET).await?;

let block = provider.get_now_block().await?;
println!("Latest block: {} ({}ms)", block.number, block.timestamp);
# Ok(())
# }
```

### Sending TRX

```rust,no_run
use tronz::{LocalSigner, ProviderBuilder, TronProvider, TRONGRID_NILE, parse_trx};

# async fn example() -> Result<(), Box<dyn std::error::Error>> {
let signer = LocalSigner::from_hex("PRIVATE_KEY_HEX").expect("valid key");
let from = signer.address();

let provider = ProviderBuilder::new()
    .with_signer(signer)
    .connect_grpc(TRONGRID_NILE)
    .await?;

let pending = provider
    .send_trx()
    .to(from)
    .amount(parse_trx("1")?)
    .send()
    .await?;

let receipt = pending.get_receipt().await?;
println!("Status: {:?}", receipt.status);
# Ok(())
# }
```

### Querying solidified (irreversible) state

`SolidityProvider` targets a TRON SolidityNode (`WalletSolidity`), which only
serves state confirmed by 2/3+ of the super representatives. It is read-only by
construction — no signer, no broadcast — and `wait_for_success` blocks until a
transaction has solidified *and* its execution succeeded.

```rust,no_run
use tronz::{SolidityProvider, TRONGRID_MAINNET_SOLIDITY};

# async fn example() -> Result<(), Box<dyn std::error::Error>> {
let solidity = SolidityProvider::connect(TRONGRID_MAINNET_SOLIDITY).await?;

let head = solidity.get_now_block().await?;
println!("solidified head: {}", head.number);

let tx_id = std::env::var("TRON_TX_ID")?.parse()?;
let receipt = solidity.wait_for_success(tx_id).await?;
println!("solidified in block {}", receipt.block_number);
# Ok(())
# }
```

### Type-safe contract bindings

`tron_sol!` turns a Solidity interface into typed call and event builders. The
generated code resolves everything through this crate, so no Alloy dependency
has to be added alongside it.

```rust,no_run
use tronz::{ProviderBuilder, TRONGRID_MAINNET, primitives::Address};

tronz::tron_sol! {
    #[sol(rpc)]
    interface IERC20 {
        function balanceOf(address owner) external view returns (uint256);
    }
}

async fn example() -> Result<(), Box<dyn std::error::Error>> {
    let provider = ProviderBuilder::new().connect_grpc(TRONGRID_MAINNET).await?;
    let usdt: Address = "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t".parse()?;

    let token = IERC20::new(usdt, provider);
    let balance = token.balanceOf(usdt).call().await?;
    println!("balance: {balance}");
    Ok(())
}
# fn main() {}
```

For more examples, see the [throgxyz/examples](https://github.com/throgxyz/examples) repository.

## Crates

| Crate | Description |
|-------|-------------|
| [`tronz`] | SDK facade for the commonly used crates and APIs |
| [`tronz-abi`] | Native TRON ABI metadata and optional Alloy JSON ABI conversion |
| [`tronz-primitives`] | `Address`, `Trx`, `ResourceCode`, signatures |
| [`tronz-rpc-types`] | TRON domain types and protobuf messages, without a network stack |
| [`tronz-signer`] | `TronSigner`, `TronSignerSync`, `TronNetworkWallet`, `TronWallet`, and `LocalSigner` |
| [`tronz-provider`] | FullNode and SolidityNode transports/providers, fillers, and builders |
| [`tronz-contract`] | TRC20 / TRC721 bindings, deployment, calls, and event filters |
| [`tronz-sol-macro`] | `tron_sol!` procedural macro for provider-bound contract bindings |
| [`tronz-signer-aws`] | AWS KMS signer (`signer-aws` feature) |

[`tronz`]: https://github.com/throgxyz/tronz/tree/main/crates/tronz
[`tronz-abi`]: https://github.com/throgxyz/tronz/tree/main/crates/abi
[`tronz-primitives`]: https://github.com/throgxyz/tronz/tree/main/crates/primitives
[`tronz-rpc-types`]: https://github.com/throgxyz/tronz/tree/main/crates/rpc-types
[`tronz-signer`]: https://github.com/throgxyz/tronz/tree/main/crates/signer
[`tronz-provider`]: https://github.com/throgxyz/tronz/tree/main/crates/provider
[`tronz-contract`]: https://github.com/throgxyz/tronz/tree/main/crates/contract
[`tronz-sol-macro`]: https://github.com/throgxyz/tronz/tree/main/crates/sol-macro
[`tronz-signer-aws`]: https://github.com/throgxyz/tronz/tree/main/crates/signer-aws

## Supported Rust Versions (MSRV)

The minimum supported Rust version is **1.91.1**.

## Contributing

See [CONTRIBUTING.md](../../CONTRIBUTING.md).

## License

Licensed under either of [Apache License, Version 2.0](../../LICENSE-APACHE) or
[MIT license](../../LICENSE-MIT) at your option.