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#[derive(Clone, Debug, Eq, PartialEq)]
16pub enum EmbeddedRequest {
17 SendTransaction(TransactionPayload),
19 SignMessage(TransactionPayload),
21 SignData(SignDataPayload),
23}
24
25#[derive(Clone, Debug, Eq, PartialEq, Deserialize, Serialize)]
30#[serde(untagged)]
31pub enum EmbeddedResponse {
32 Success(EmbeddedResponseSuccess),
34 Error(EmbeddedResponseError),
36}
37
38impl EmbeddedResponse {
39 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#[derive(Clone, Debug, Eq, PartialEq, Deserialize, Serialize)]
83#[serde(deny_unknown_fields)]
84pub struct EmbeddedResponseSuccess {
85 pub result: WalletResult,
87}
88
89#[derive(Clone, Debug, Eq, PartialEq, Deserialize, Serialize)]
91#[serde(deny_unknown_fields)]
92pub struct EmbeddedResponseError {
93 pub error: WalletResponseError,
95}
96
97#[derive(Debug, Error)]
99pub enum EmbeddedRequestError {
100 #[error("embedded request must be unpadded URL-safe base64")]
102 InvalidBase64,
103 #[error("invalid embedded TON Connect request: {0}")]
105 InvalidJson(#[from] serde_json::Error),
106}
107
108pub 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
122pub 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(¶meter),
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(¶meter).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(¶meter)
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}