Skip to main content

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}