Skip to main content

ton_connect_core/
embedded.rs

1use base64::{Engine as _, engine::general_purpose};
2use serde::{Deserialize, Deserializer, Serialize, de};
3use serde_json::Value;
4use thiserror::Error;
5
6use crate::{
7    AccountAddress, Base64Value, CellBoc, DecimalString, ExtraCurrencies, FriendlyAddress,
8    KnownAppRequest, KnownWalletResponse, NetworkId, NonEmptyVec, RawMessage,
9    RawTransactionPayload, ResponseValidationError, SendTransactionRequest, SignDataPayload,
10    SignDataRequest, SignMessageRequest, StructuredItem, StructuredTransactionPayload,
11    TransactionPayload, WalletResponse, WalletResponseError, WalletResponseSuccess, WalletResult,
12};
13
14/// An RPC request embedded in a connect link, before a request ID exists.
15#[derive(Clone, Debug, Eq, PartialEq)]
16pub enum EmbeddedRequest {
17    /// Sign and broadcast a transaction after connection approval.
18    SendTransaction(TransactionPayload),
19    /// Sign a message without broadcasting after connection approval.
20    SignMessage(TransactionPayload),
21    /// Sign application data after connection approval.
22    SignData(SignDataPayload),
23}
24
25/// Method-specific response attached to a successful connect event.
26///
27/// Embedded requests have no dApp-assigned request ID, so this deliberately
28/// differs from the normal [`crate::WalletResponse`] envelope.
29#[derive(Clone, Debug, Eq, PartialEq, Deserialize, Serialize)]
30#[serde(untagged)]
31pub enum EmbeddedResponse {
32    /// Embedded action completed successfully.
33    Success(EmbeddedResponseSuccess),
34    /// Embedded action returned an error while connect still succeeded.
35    Error(EmbeddedResponseError),
36}
37
38impl EmbeddedResponse {
39    /// Validates the result shape and error catalogue against the embedded
40    /// method that produced it.
41    ///
42    /// Embedded responses omit only the ordinary RPC `id`; every other result
43    /// rule is identical, so validation deliberately reuses the normal
44    /// request/response correlator with an internal empty identifier.
45    pub fn validate_for(
46        &self,
47        request: &EmbeddedRequest,
48    ) -> Result<KnownWalletResponse, ResponseValidationError> {
49        let request = match request {
50            EmbeddedRequest::SendTransaction(payload) => {
51                KnownAppRequest::SendTransaction(SendTransactionRequest {
52                    id: String::new(),
53                    payload: payload.clone(),
54                })
55            }
56            EmbeddedRequest::SignMessage(payload) => {
57                KnownAppRequest::SignMessage(SignMessageRequest {
58                    id: String::new(),
59                    payload: payload.clone(),
60                })
61            }
62            EmbeddedRequest::SignData(payload) => KnownAppRequest::SignData(SignDataRequest {
63                id: String::new(),
64                payload: payload.clone(),
65            }),
66        };
67        let response = match self {
68            Self::Success(response) => WalletResponse::Success(WalletResponseSuccess {
69                result: response.result.clone(),
70                id: String::new(),
71            }),
72            Self::Error(response) => WalletResponse::Error {
73                error: response.error.clone(),
74                id: String::new(),
75            },
76        };
77        response.validate_for(&request)
78    }
79}
80
81/// Success body for an embedded action.
82#[derive(Clone, Debug, Eq, PartialEq, Deserialize, Serialize)]
83#[serde(deny_unknown_fields)]
84pub struct EmbeddedResponseSuccess {
85    /// Method-specific result identical to a normal wallet response result.
86    pub result: WalletResult,
87}
88
89/// Error body for an embedded action.
90#[derive(Clone, Debug, Eq, PartialEq, Deserialize, Serialize)]
91#[serde(deny_unknown_fields)]
92pub struct EmbeddedResponseError {
93    /// Method-specific error identical to a normal wallet response error.
94    pub error: WalletResponseError,
95}
96
97/// Failure to decode or encode the compact `e` connect-link parameter.
98#[derive(Debug, Error)]
99pub enum EmbeddedRequestError {
100    /// The parameter is not unpadded URL-safe base64.
101    #[error("embedded request must be unpadded URL-safe base64")]
102    InvalidBase64,
103    /// The decoded JSON violates the compact embedded-request schema.
104    #[error("invalid embedded TON Connect request: {0}")]
105    InvalidJson(#[from] serde_json::Error),
106}
107
108/// Decodes the unpadded base64url `e` connect-link parameter.
109pub fn decode_embedded_request_param(
110    parameter: &str,
111) -> Result<EmbeddedRequest, EmbeddedRequestError> {
112    if parameter.is_empty() || parameter.contains('=') {
113        return Err(EmbeddedRequestError::InvalidBase64);
114    }
115    let json = general_purpose::URL_SAFE_NO_PAD
116        .decode(parameter)
117        .map_err(|_| EmbeddedRequestError::InvalidBase64)?;
118    let wire = serde_json::from_slice::<WireEmbeddedRequest>(&json)?;
119    Ok(wire.into())
120}
121
122/// Encodes a request as the unpadded base64url `e` parameter.
123pub fn encode_embedded_request_param(
124    request: &EmbeddedRequest,
125) -> Result<String, EmbeddedRequestError> {
126    let wire = WireEmbeddedRequest::from(request);
127    let json = serde_json::to_vec(&wire)?;
128    Ok(general_purpose::URL_SAFE_NO_PAD.encode(json))
129}
130
131#[derive(Clone, Copy, Deserialize, Serialize)]
132enum WireTransactionMethod {
133    #[serde(rename = "st")]
134    SendTransaction,
135    #[serde(rename = "sm")]
136    SignMessage,
137}
138
139#[derive(Deserialize, Serialize)]
140struct WireTransactionRequest {
141    m: WireTransactionMethod,
142    #[serde(flatten)]
143    payload: WireTransactionPayload,
144}
145
146#[derive(Serialize)]
147#[serde(untagged)]
148enum WireTransactionPayload {
149    Raw(WireRawTransaction),
150    Structured(WireStructuredTransaction),
151}
152
153impl<'de> Deserialize<'de> for WireTransactionPayload {
154    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
155    where
156        D: Deserializer<'de>,
157    {
158        let value = Value::deserialize(deserializer)?;
159        let Value::Object(object) = &value else {
160            return Err(de::Error::custom(
161                "embedded transaction payload must be an object",
162            ));
163        };
164        match (object.contains_key("ms"), object.contains_key("i")) {
165            (true, false) => serde_json::from_value::<WireRawTransaction>(value)
166                .map(Self::Raw)
167                .map_err(de::Error::custom),
168            (false, true) => serde_json::from_value::<WireStructuredTransaction>(value)
169                .map(Self::Structured)
170                .map_err(de::Error::custom),
171            (true, true) | (false, false) => Err(de::Error::custom(
172                "embedded transaction requires exactly one of ms or i",
173            )),
174        }
175    }
176}
177
178#[derive(Deserialize, Serialize)]
179#[serde(deny_unknown_fields)]
180struct WireRawTransaction {
181    #[serde(
182        default,
183        deserialize_with = "crate::value::deserialize_optional_non_null",
184        skip_serializing_if = "Option::is_none"
185    )]
186    f: Option<AccountAddress>,
187    #[serde(
188        default,
189        deserialize_with = "crate::value::deserialize_optional_non_null",
190        skip_serializing_if = "Option::is_none"
191    )]
192    n: Option<NetworkId>,
193    #[serde(
194        default,
195        deserialize_with = "crate::value::deserialize_optional_non_null",
196        skip_serializing_if = "Option::is_none"
197    )]
198    vu: Option<u64>,
199    ms: NonEmptyVec<WireMessage>,
200}
201
202#[derive(Deserialize, Serialize)]
203#[serde(deny_unknown_fields)]
204struct WireStructuredTransaction {
205    #[serde(
206        default,
207        deserialize_with = "crate::value::deserialize_optional_non_null",
208        skip_serializing_if = "Option::is_none"
209    )]
210    f: Option<AccountAddress>,
211    #[serde(
212        default,
213        deserialize_with = "crate::value::deserialize_optional_non_null",
214        skip_serializing_if = "Option::is_none"
215    )]
216    n: Option<NetworkId>,
217    #[serde(
218        default,
219        deserialize_with = "crate::value::deserialize_optional_non_null",
220        skip_serializing_if = "Option::is_none"
221    )]
222    vu: Option<u64>,
223    i: NonEmptyVec<WireItem>,
224}
225
226#[derive(Deserialize, Serialize)]
227#[serde(deny_unknown_fields)]
228struct WireMessage {
229    a: FriendlyAddress,
230    am: DecimalString,
231    #[serde(
232        default,
233        deserialize_with = "crate::value::deserialize_optional_non_null",
234        skip_serializing_if = "Option::is_none"
235    )]
236    p: Option<CellBoc>,
237    #[serde(
238        default,
239        deserialize_with = "crate::value::deserialize_optional_non_null",
240        skip_serializing_if = "Option::is_none"
241    )]
242    si: Option<CellBoc>,
243    #[serde(
244        default,
245        deserialize_with = "crate::value::deserialize_optional_non_null",
246        skip_serializing_if = "Option::is_none"
247    )]
248    ec: Option<ExtraCurrencies>,
249}
250
251#[derive(Deserialize, Serialize)]
252#[serde(tag = "t", rename_all = "lowercase", deny_unknown_fields)]
253enum WireItem {
254    Ton {
255        a: FriendlyAddress,
256        am: DecimalString,
257        #[serde(
258            default,
259            deserialize_with = "crate::value::deserialize_optional_non_null",
260            skip_serializing_if = "Option::is_none"
261        )]
262        p: Option<CellBoc>,
263        #[serde(
264            default,
265            deserialize_with = "crate::value::deserialize_optional_non_null",
266            skip_serializing_if = "Option::is_none"
267        )]
268        si: Option<CellBoc>,
269        #[serde(
270            default,
271            deserialize_with = "crate::value::deserialize_optional_non_null",
272            skip_serializing_if = "Option::is_none"
273        )]
274        ec: Option<ExtraCurrencies>,
275    },
276    Jetton {
277        ma: AccountAddress,
278        d: AccountAddress,
279        am: DecimalString,
280        #[serde(
281            default,
282            deserialize_with = "crate::value::deserialize_optional_non_null",
283            skip_serializing_if = "Option::is_none"
284        )]
285        aa: Option<DecimalString>,
286        #[serde(
287            default,
288            deserialize_with = "crate::value::deserialize_optional_non_null",
289            skip_serializing_if = "Option::is_none"
290        )]
291        qi: Option<String>,
292        #[serde(
293            default,
294            deserialize_with = "crate::value::deserialize_optional_non_null",
295            skip_serializing_if = "Option::is_none"
296        )]
297        rd: Option<AccountAddress>,
298        #[serde(
299            default,
300            deserialize_with = "crate::value::deserialize_optional_non_null",
301            skip_serializing_if = "Option::is_none"
302        )]
303        cp: Option<CellBoc>,
304        #[serde(
305            default,
306            deserialize_with = "crate::value::deserialize_optional_non_null",
307            skip_serializing_if = "Option::is_none"
308        )]
309        fa: Option<DecimalString>,
310        #[serde(
311            default,
312            deserialize_with = "crate::value::deserialize_optional_non_null",
313            skip_serializing_if = "Option::is_none"
314        )]
315        fp: Option<CellBoc>,
316    },
317    Nft {
318        na: AccountAddress,
319        no: AccountAddress,
320        #[serde(
321            default,
322            deserialize_with = "crate::value::deserialize_optional_non_null",
323            skip_serializing_if = "Option::is_none"
324        )]
325        aa: Option<DecimalString>,
326        #[serde(
327            default,
328            deserialize_with = "crate::value::deserialize_optional_non_null",
329            skip_serializing_if = "Option::is_none"
330        )]
331        qi: Option<String>,
332        #[serde(
333            default,
334            deserialize_with = "crate::value::deserialize_optional_non_null",
335            skip_serializing_if = "Option::is_none"
336        )]
337        rd: Option<AccountAddress>,
338        #[serde(
339            default,
340            deserialize_with = "crate::value::deserialize_optional_non_null",
341            skip_serializing_if = "Option::is_none"
342        )]
343        cp: Option<CellBoc>,
344        #[serde(
345            default,
346            deserialize_with = "crate::value::deserialize_optional_non_null",
347            skip_serializing_if = "Option::is_none"
348        )]
349        fa: Option<DecimalString>,
350        #[serde(
351            default,
352            deserialize_with = "crate::value::deserialize_optional_non_null",
353            skip_serializing_if = "Option::is_none"
354        )]
355        fp: Option<CellBoc>,
356    },
357}
358
359#[derive(Clone, Copy, Deserialize, Serialize)]
360enum WireSignDataMethod {
361    #[serde(rename = "sd")]
362    SignData,
363}
364
365#[derive(Deserialize, Serialize)]
366struct WireSignDataRequest {
367    m: WireSignDataMethod,
368    #[serde(
369        default,
370        deserialize_with = "crate::value::deserialize_optional_non_null",
371        skip_serializing_if = "Option::is_none"
372    )]
373    n: Option<NetworkId>,
374    #[serde(
375        default,
376        deserialize_with = "crate::value::deserialize_optional_non_null",
377        skip_serializing_if = "Option::is_none"
378    )]
379    f: Option<AccountAddress>,
380    #[serde(flatten)]
381    payload: WireSignDataPayload,
382}
383
384#[derive(Deserialize, Serialize)]
385#[serde(tag = "t", rename_all = "lowercase", deny_unknown_fields)]
386enum WireSignDataPayload {
387    Text { tx: String },
388    Binary { b: Base64Value },
389    Cell { s: String, c: CellBoc },
390}
391
392#[derive(Deserialize, Serialize)]
393#[serde(untagged)]
394enum WireEmbeddedRequest {
395    Transaction(WireTransactionRequest),
396    SignData(WireSignDataRequest),
397}
398
399impl From<WireMessage> for RawMessage {
400    fn from(message: WireMessage) -> Self {
401        Self {
402            address: message.a,
403            amount: message.am,
404            payload: message.p,
405            state_init: message.si,
406            extra_currency: message.ec,
407        }
408    }
409}
410
411impl From<&RawMessage> for WireMessage {
412    fn from(message: &RawMessage) -> Self {
413        Self {
414            a: message.address.clone(),
415            am: message.amount.clone(),
416            p: message.payload.clone(),
417            si: message.state_init.clone(),
418            ec: message.extra_currency.clone(),
419        }
420    }
421}
422
423impl From<WireItem> for StructuredItem {
424    fn from(item: WireItem) -> Self {
425        match item {
426            WireItem::Ton { a, am, p, si, ec } => Self::Ton {
427                address: a,
428                amount: am,
429                payload: p,
430                state_init: si,
431                extra_currency: ec,
432            },
433            WireItem::Jetton {
434                ma,
435                d,
436                am,
437                aa,
438                qi,
439                rd,
440                cp,
441                fa,
442                fp,
443            } => Self::Jetton {
444                master: ma,
445                destination: d,
446                amount: am,
447                attach_amount: aa,
448                query_id: qi,
449                response_destination: rd,
450                custom_payload: cp,
451                forward_amount: fa,
452                forward_payload: fp,
453            },
454            WireItem::Nft {
455                na,
456                no,
457                aa,
458                qi,
459                rd,
460                cp,
461                fa,
462                fp,
463            } => Self::Nft {
464                nft_address: na,
465                new_owner: no,
466                attach_amount: aa,
467                query_id: qi,
468                response_destination: rd,
469                custom_payload: cp,
470                forward_amount: fa,
471                forward_payload: fp,
472            },
473        }
474    }
475}
476
477impl From<&StructuredItem> for WireItem {
478    fn from(item: &StructuredItem) -> Self {
479        match item {
480            StructuredItem::Ton {
481                address,
482                amount,
483                payload,
484                state_init,
485                extra_currency,
486            } => Self::Ton {
487                a: address.clone(),
488                am: amount.clone(),
489                p: payload.clone(),
490                si: state_init.clone(),
491                ec: extra_currency.clone(),
492            },
493            StructuredItem::Jetton {
494                master,
495                destination,
496                amount,
497                attach_amount,
498                query_id,
499                response_destination,
500                custom_payload,
501                forward_amount,
502                forward_payload,
503            } => Self::Jetton {
504                ma: master.clone(),
505                d: destination.clone(),
506                am: amount.clone(),
507                aa: attach_amount.clone(),
508                qi: query_id.clone(),
509                rd: response_destination.clone(),
510                cp: custom_payload.clone(),
511                fa: forward_amount.clone(),
512                fp: forward_payload.clone(),
513            },
514            StructuredItem::Nft {
515                nft_address,
516                new_owner,
517                attach_amount,
518                query_id,
519                response_destination,
520                custom_payload,
521                forward_amount,
522                forward_payload,
523            } => Self::Nft {
524                na: nft_address.clone(),
525                no: new_owner.clone(),
526                aa: attach_amount.clone(),
527                qi: query_id.clone(),
528                rd: response_destination.clone(),
529                cp: custom_payload.clone(),
530                fa: forward_amount.clone(),
531                fp: forward_payload.clone(),
532            },
533        }
534    }
535}
536
537impl From<WireTransactionPayload> for TransactionPayload {
538    fn from(payload: WireTransactionPayload) -> Self {
539        match payload {
540            WireTransactionPayload::Raw(payload) => Self::Raw(RawTransactionPayload {
541                valid_until: payload.vu,
542                network: payload.n,
543                from: payload.f,
544                messages: payload.ms.map(Into::into),
545            }),
546            WireTransactionPayload::Structured(payload) => {
547                Self::Structured(StructuredTransactionPayload {
548                    valid_until: payload.vu,
549                    network: payload.n,
550                    from: payload.f,
551                    items: payload.i.map(Into::into),
552                })
553            }
554        }
555    }
556}
557
558impl From<&TransactionPayload> for WireTransactionPayload {
559    fn from(payload: &TransactionPayload) -> Self {
560        match payload {
561            TransactionPayload::Raw(payload) => Self::Raw(WireRawTransaction {
562                f: payload.from.clone(),
563                n: payload.network.clone(),
564                vu: payload.valid_until,
565                ms: payload.messages.map_ref(WireMessage::from),
566            }),
567            TransactionPayload::Structured(payload) => {
568                Self::Structured(WireStructuredTransaction {
569                    f: payload.from.clone(),
570                    n: payload.network.clone(),
571                    vu: payload.valid_until,
572                    i: payload.items.map_ref(WireItem::from),
573                })
574            }
575        }
576    }
577}
578
579impl From<WireEmbeddedRequest> for EmbeddedRequest {
580    fn from(request: WireEmbeddedRequest) -> Self {
581        match request {
582            WireEmbeddedRequest::Transaction(request) => match request.m {
583                WireTransactionMethod::SendTransaction => {
584                    Self::SendTransaction(request.payload.into())
585                }
586                WireTransactionMethod::SignMessage => Self::SignMessage(request.payload.into()),
587            },
588            WireEmbeddedRequest::SignData(request) => {
589                let payload = match request.payload {
590                    WireSignDataPayload::Text { tx } => SignDataPayload::Text {
591                        text: tx,
592                        network: request.n,
593                        from: request.f,
594                    },
595                    WireSignDataPayload::Binary { b } => SignDataPayload::Binary {
596                        bytes: b,
597                        network: request.n,
598                        from: request.f,
599                    },
600                    WireSignDataPayload::Cell { s, c } => SignDataPayload::Cell {
601                        schema: s,
602                        cell: c,
603                        network: request.n,
604                        from: request.f,
605                    },
606                };
607                Self::SignData(payload)
608            }
609        }
610    }
611}
612
613impl From<&EmbeddedRequest> for WireEmbeddedRequest {
614    fn from(request: &EmbeddedRequest) -> Self {
615        match request {
616            EmbeddedRequest::SendTransaction(payload) => {
617                Self::Transaction(WireTransactionRequest {
618                    m: WireTransactionMethod::SendTransaction,
619                    payload: payload.into(),
620                })
621            }
622            EmbeddedRequest::SignMessage(payload) => Self::Transaction(WireTransactionRequest {
623                m: WireTransactionMethod::SignMessage,
624                payload: payload.into(),
625            }),
626            EmbeddedRequest::SignData(payload) => {
627                let (n, f, payload) = match payload {
628                    SignDataPayload::Text {
629                        text,
630                        network,
631                        from,
632                    } => (
633                        network.clone(),
634                        from.clone(),
635                        WireSignDataPayload::Text { tx: text.clone() },
636                    ),
637                    SignDataPayload::Binary {
638                        bytes,
639                        network,
640                        from,
641                    } => (
642                        network.clone(),
643                        from.clone(),
644                        WireSignDataPayload::Binary { b: bytes.clone() },
645                    ),
646                    SignDataPayload::Cell {
647                        schema,
648                        cell,
649                        network,
650                        from,
651                    } => (
652                        network.clone(),
653                        from.clone(),
654                        WireSignDataPayload::Cell {
655                            s: schema.clone(),
656                            c: cell.clone(),
657                        },
658                    ),
659                };
660                Self::SignData(WireSignDataRequest {
661                    m: WireSignDataMethod::SignData,
662                    n,
663                    f,
664                    payload,
665                })
666            }
667        }
668    }
669}
670
671#[cfg(test)]
672mod tests {
673    use super::*;
674
675    #[test]
676    fn decodes_typescript_send_transaction_vector() {
677        let wire = r#"{"m":"st","n":"-239","vu":1761071945,"ms":[{"a":"EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs","am":"1000000000"}]}"#;
678        let parameter = general_purpose::URL_SAFE_NO_PAD.encode(wire);
679        assert!(matches!(
680            decode_embedded_request_param(&parameter),
681            Ok(EmbeddedRequest::SendTransaction(TransactionPayload::Raw(
682                RawTransactionPayload {
683                    valid_until: Some(1_761_071_945),
684                    ..
685                }
686            )))
687        ));
688    }
689
690    #[test]
691    fn rejects_padded_or_ambiguous_transaction_payloads() {
692        let both = r#"{"m":"st","ms":[{"a":"EQ","am":"1"}],"i":[{"t":"ton","a":"EQ","am":"1"}]}"#;
693        let parameter = general_purpose::URL_SAFE_NO_PAD.encode(both);
694        assert!(decode_embedded_request_param(&parameter).is_err());
695        assert!(decode_embedded_request_param("e30=").is_err());
696    }
697
698    #[test]
699    fn every_supported_embedded_shape_round_trips() {
700        let samples = [
701            concat!(
702                "{\"m\":\"sm\",\"ms\":[{\"a\":\"",
703                "Ef8AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAADAU",
704                "\",\"am\":\"0\"}]}"
705            ),
706            r#"{"m":"sd","n":"-239","t":"text","tx":"Hello"}"#,
707            r#"{"m":"sd","t":"binary","b":"AA=="}"#,
708            r#"{"m":"sd","t":"cell","s":"value:uint32 = Value","c":"te6ccgEBAQEAAgAAAA=="}"#,
709        ];
710        for sample in samples {
711            let parameter = general_purpose::URL_SAFE_NO_PAD.encode(sample);
712            let round_trip = decode_embedded_request_param(&parameter)
713                .and_then(|request| encode_embedded_request_param(&request))
714                .and_then(|encoded| decode_embedded_request_param(&encoded));
715            assert!(
716                round_trip.is_ok(),
717                "failed embedded sample {sample}: {round_trip:?}"
718            );
719        }
720    }
721
722    #[test]
723    fn embedded_response_has_no_request_id() -> Result<(), Box<dyn std::error::Error>> {
724        let success = EmbeddedResponse::Success(EmbeddedResponseSuccess {
725            result: WalletResult::Object(serde_json::Map::new()),
726        });
727        assert_eq!(serde_json::to_string(&success)?, r#"{"result":{}}"#);
728        assert!(serde_json::from_str::<EmbeddedResponse>(r#"{"result":{},"id":"1"}"#).is_err());
729
730        let error = EmbeddedResponse::Error(EmbeddedResponseError {
731            error: WalletResponseError {
732                code: crate::RpcErrorCode::UserDeclined,
733                message: "declined".to_owned(),
734                data: None,
735            },
736        });
737        assert_eq!(
738            serde_json::to_string(&error)?,
739            r#"{"error":{"code":300,"message":"declined"}}"#
740        );
741        Ok(())
742    }
743}