erpc_sdk/tron.rs
1use std::sync::Arc;
2
3use serde::Serialize;
4use serde_json::Value;
5use url::Url;
6
7use crate::{
8 PendingRpcRequest, Result, RpcNamespace,
9 rpc::{BatchPolicy, HttpJsonRpcTransport},
10};
11
12/// TRON Mainnet read-only JSON-RPC methods represented by this release.
13pub const TRON_RPC_METHODS: &[&str] = &["eth_call", "eth_chainId", "eth_getBalance"];
14
15/// TRON Mainnet read-only JSON-RPC service client.
16///
17/// TRON Mainnet uses chain ID `728126428` (`0x2b6653dc`). The native balance
18/// returned by `eth_getBalance` is a raw JSON-RPC quantity in lowercase `sun`
19/// units (`1 TRX = 1,000,000 sun`); this client does not parse or convert it.
20#[derive(Clone)]
21pub struct TronClient {
22 /// TRON Mainnet read-only JSON-RPC namespace.
23 pub rpc: TronRpcClient,
24}
25
26impl TronClient {
27 pub(crate) const fn new(transport: Arc<HttpJsonRpcTransport>) -> Self {
28 Self {
29 rpc: TronRpcClient::new(transport),
30 }
31 }
32}
33
34/// TRON Mainnet read-only JSON-RPC namespace.
35///
36/// The namespace deliberately exposes only the three read methods represented
37/// by [`TRON_RPC_METHODS`]. JSON-RPC quantities and results remain raw strings;
38/// in particular, no `41` prefix or `Base58Check` address conversion is applied.
39/// Callers should use the documented interoperable 20-byte `0x` hexadecimal
40/// address form and the `latest` state selector.
41///
42/// A hosted root target is posted to `/`; the provider owns its upstream
43/// `/jsonrpc` route. A caller-owned direct endpoint is the complete request
44/// target, so a direct `/jsonrpc` suffix, encoded path, and query are retained
45/// unchanged. The client is HTTP-only and has no REST, generic raw/request,
46/// batch, subscription, transaction, signing, broadcast, swap, or bridge API.
47///
48/// The intentionally narrow surface has compile-fail coverage for forbidden
49/// escape hatches and state-changing operations:
50///
51/// ```compile_fail
52/// # use erpc_sdk::{ErpcClient, ErpcClientConfig};
53/// # async fn forbidden() -> erpc_sdk::Result<()> {
54/// let rpc = ErpcClient::new(ErpcClientConfig::new("key"))?.tron.rpc;
55/// let _ = rpc.raw::<String>("eth_chainId", None);
56/// # Ok(())
57/// # }
58/// ```
59///
60/// ```compile_fail
61/// # use erpc_sdk::{ErpcClient, ErpcClientConfig};
62/// # async fn forbidden() -> erpc_sdk::Result<()> {
63/// let rpc = ErpcClient::new(ErpcClientConfig::new("key"))?.tron.rpc;
64/// let _ = rpc.request::<String>("eth_chainId", Vec::<serde_json::Value>::new());
65/// # Ok(())
66/// # }
67/// ```
68///
69/// ```compile_fail
70/// # use erpc_sdk::{ErpcClient, ErpcClientConfig};
71/// # async fn forbidden() -> erpc_sdk::Result<()> {
72/// let rpc = ErpcClient::new(ErpcClientConfig::new("key"))?.tron.rpc;
73/// let _ = rpc.batch(Vec::new());
74/// # Ok(())
75/// # }
76/// ```
77///
78/// ```compile_fail
79/// # use erpc_sdk::{ErpcClient, ErpcClientConfig};
80/// # async fn forbidden() -> erpc_sdk::Result<()> {
81/// let rpc = ErpcClient::new(ErpcClientConfig::new("key"))?.tron.rpc;
82/// let _ = rpc.subscribe("newHeads", Vec::new());
83/// # Ok(())
84/// # }
85/// ```
86///
87/// ```compile_fail
88/// # use erpc_sdk::{ErpcClient, ErpcClientConfig};
89/// # async fn forbidden() -> erpc_sdk::Result<()> {
90/// let rpc = ErpcClient::new(ErpcClientConfig::new("key"))?.tron.rpc;
91/// let _ = rpc.eth_send_raw_transaction(["0xdeadbeef"]);
92/// # Ok(())
93/// # }
94/// ```
95#[derive(Clone)]
96pub struct TronRpcClient {
97 namespace: RpcNamespace,
98}
99
100impl TronRpcClient {
101 pub(crate) const fn new(transport: Arc<HttpJsonRpcTransport>) -> Self {
102 Self {
103 namespace: RpcNamespace::new(transport, BatchPolicy::Unsupported),
104 }
105 }
106
107 /// Returns the credential-free TRON Mainnet JSON-RPC origin and root.
108 #[must_use]
109 pub fn endpoint(&self) -> String {
110 let endpoint = self.namespace.endpoint();
111 if endpoint.is_empty() {
112 return endpoint;
113 }
114 let Ok(mut url) = Url::parse(&endpoint) else {
115 return String::new();
116 };
117 url.set_path("/");
118 url.set_query(None);
119 url.set_fragment(None);
120 let _ = url.set_username("");
121 let _ = url.set_password(None);
122 url.to_string()
123 }
124
125 /// Creates a pending TRON Mainnet `eth_chainId` read.
126 ///
127 /// # Panics
128 ///
129 /// The empty parameter array is infallible to serialize.
130 #[must_use]
131 pub fn eth_chain_id(&self) -> PendingRpcRequest<String> {
132 self.namespace
133 .request("eth_chainId", Vec::<Value>::new())
134 .expect("empty parameters serialize")
135 }
136
137 /// Creates a pending positional TRON native balance read.
138 ///
139 /// The raw JSON-RPC quantity is returned unchanged. TRON uses lowercase
140 /// `sun` as the native base unit; no TRX/sun scaling or conversion occurs.
141 pub fn eth_get_balance<P: Serialize>(&self, params: P) -> Result<PendingRpcRequest<String>> {
142 self.namespace.request("eth_getBalance", params)
143 }
144
145 /// Creates a pending read-only TRON `eth_call` simulation.
146 ///
147 /// The caller's 20-byte `0x` hexadecimal address and `latest` selector are
148 /// serialized unchanged. This helper does not construct, sign, or submit
149 /// a transaction and does not promise archive-state support.
150 pub fn eth_call<P: Serialize>(&self, params: P) -> Result<PendingRpcRequest<String>> {
151 self.namespace.request("eth_call", params)
152 }
153}