Skip to main content

ton_connect_core/
protocol.rs

1//! Top-level TON Connect message and method discriminators.
2
3use std::{fmt, str::FromStr};
4
5use serde::{Deserialize, Serialize};
6use thiserror::Error;
7
8use crate::{AppRequest, ConnectEvent, ConnectRequest, KnownAppRequest, WalletResponse};
9
10/// RPC methods defined by the current TON Connect specification.
11#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq, Serialize, Deserialize)]
12pub enum RpcMethod {
13    /// Sign and broadcast outgoing messages.
14    #[serde(rename = "sendTransaction")]
15    SendTransaction,
16    /// Sign outgoing messages without broadcasting them.
17    #[serde(rename = "signMessage")]
18    SignMessage,
19    /// Sign application data.
20    #[serde(rename = "signData")]
21    SignData,
22    /// End an established session.
23    #[serde(rename = "disconnect")]
24    Disconnect,
25}
26
27impl RpcMethod {
28    /// Returns the exact method name carried on the wire and in bridge topics.
29    #[must_use]
30    pub const fn as_str(self) -> &'static str {
31        match self {
32            Self::SendTransaction => "sendTransaction",
33            Self::SignMessage => "signMessage",
34            Self::SignData => "signData",
35            Self::Disconnect => "disconnect",
36        }
37    }
38}
39
40impl fmt::Display for RpcMethod {
41    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
42        formatter.write_str(self.as_str())
43    }
44}
45
46impl FromStr for RpcMethod {
47    type Err = RpcMethodError;
48
49    fn from_str(value: &str) -> Result<Self, Self::Err> {
50        match value {
51            "sendTransaction" => Ok(Self::SendTransaction),
52            "signMessage" => Ok(Self::SignMessage),
53            "signData" => Ok(Self::SignData),
54            "disconnect" => Ok(Self::Disconnect),
55            _ => Err(RpcMethodError),
56        }
57    }
58}
59
60/// A method name is not part of the current TON Connect RPC catalogue.
61#[derive(Clone, Copy, Debug, Eq, Error, PartialEq)]
62#[error("unsupported TON Connect RPC method")]
63pub struct RpcMethodError;
64
65/// Anything a dApp can send to a wallet through TON Connect.
66///
67/// The initial connect request is transported by a link or the JS bridge.
68/// Subsequent RPC requests are encrypted on the HTTP bridge.
69#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
70#[serde(untagged)]
71pub enum AppMessage {
72    /// Initial connection request.
73    Connect(ConnectRequest),
74    /// Post-connect RPC request.
75    Request(AppRequest),
76}
77
78/// Wallet-initiated event carried by TON Connect.
79pub type WalletEvent = ConnectEvent;
80
81/// Anything a wallet can send to a dApp through TON Connect.
82#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
83#[serde(untagged)]
84pub enum WalletMessage {
85    /// Wallet-initiated event, including connect and disconnect.
86    Event(WalletEvent),
87    /// Response correlated to an RPC request.
88    Response(WalletResponse),
89}
90
91impl From<&KnownAppRequest> for RpcMethod {
92    fn from(request: &KnownAppRequest) -> Self {
93        match request {
94            KnownAppRequest::SendTransaction(_) => Self::SendTransaction,
95            KnownAppRequest::SignMessage(_) => Self::SignMessage,
96            KnownAppRequest::SignData(_) => Self::SignData,
97            KnownAppRequest::Disconnect(_) => Self::Disconnect,
98        }
99    }
100}
101
102#[cfg(test)]
103mod tests {
104    use super::*;
105
106    #[test]
107    fn every_rpc_method_round_trips_with_the_normative_name() {
108        for (method, name) in [
109            (RpcMethod::SendTransaction, "sendTransaction"),
110            (RpcMethod::SignMessage, "signMessage"),
111            (RpcMethod::SignData, "signData"),
112            (RpcMethod::Disconnect, "disconnect"),
113        ] {
114            assert_eq!(method.as_str(), name);
115            assert_eq!(method.to_string(), name);
116            assert_eq!(name.parse::<RpcMethod>(), Ok(method));
117            assert_eq!(
118                serde_json::from_str::<RpcMethod>(&format!("{name:?}")).ok(),
119                Some(method)
120            );
121        }
122        assert!("futureMethod".parse::<RpcMethod>().is_err());
123    }
124
125    #[test]
126    fn top_level_message_types_select_every_protocol_envelope() {
127        let connect = r#"{
128            "manifestUrl":"https://app.example/tonconnect-manifest.json",
129            "items":[{"name":"ton_addr"}]
130        }"#;
131        assert!(matches!(
132            serde_json::from_str::<AppMessage>(connect),
133            Ok(AppMessage::Connect(_))
134        ));
135
136        let request = r#"{"method":"disconnect","params":[],"id":"1"}"#;
137        assert!(matches!(
138            serde_json::from_str::<AppMessage>(request),
139            Ok(AppMessage::Request(_))
140        ));
141
142        let event = r#"{"event":"disconnect","id":1,"payload":{}}"#;
143        assert!(matches!(
144            serde_json::from_str::<WalletMessage>(event),
145            Ok(WalletMessage::Event(_))
146        ));
147
148        let response = r#"{"result":{},"id":"1"}"#;
149        assert!(matches!(
150            serde_json::from_str::<WalletMessage>(response),
151            Ok(WalletMessage::Response(_))
152        ));
153    }
154}