Skip to content

Commit

Permalink
Update staging branch with the latest main state (ton-community#776)
Browse files Browse the repository at this point in the history 
* Fix according requests

* Fix link

* Add aliases

* [TON-350] add(article): Highload wallet v3 transactions

* Fix image links

* sap-list-update

* asset-processing_crush_fix

* Update enable-liteserver-node.md

* Writing the draft version

* Remove subsection

* Remarks corrected

* Added/changed post-review information

* New translations readme.mdx (Korean)

* New translations guidelines.md (Korean)

* New translations schemes-guidelines.mdx (Korean)

* New translations guidelines.md (Korean)

* Fix link in red_stone.mdx for price_manager.fc

* update inline specifier explanation

* Fix mistake with shards

* Remove tonsdk from bot

* Adds functionality description for GitHub branches

* add japanese to default

* New translations guidelines.md (Japanese)

* remove engines

* chore: rollback previous example

* Update code from tonsdk to pytoniq

* New translations principles-of-a-good-tutorial.md (Korean)

* New translations sample-tutorial.md (Korean)

* New translations readme.md (Korean)

* New translations contribution-rules.md (Korean)

* New translations maintainers.md (Korean)

* New translations participate.md (Korean)

* New translations mining.md (Korean)

* fix typos

* fix typo

* fix typo

* fix typos

* fix typo

* fix typos

* fix typos

* fix typo

* fix typo

* fix typo

* fix typo

* fix typos

* fix typo

* update dropdown menu

* fix import

* add translation of sidebar

* New translations overview.md (Chinese Simplified)

* New translations how-it-works.md (Chinese Simplified)

* New translations how-to-contribute.md (Chinese Simplified)

* New translations how-it-works.md (Chinese Simplified)

* New translations how-to-contribute.md (Chinese Simplified)

* remove content

* New translations overview.md (Chinese Simplified)

* New translations translation-style-guide.md (Chinese Simplified)

* Mandarin localization (ton-community#63)

* New translations cell-boc.mdx (Chinese Simplified)

* New translations as-contributor.md (Korean)

* New translations as-maintainer.md (Korean)

* New translations readme.mdx (Korean)

* New translations guidelines.md (Korean)

* New translations schemes-guidelines.mdx (Korean)

* New translations guidelines.md (Korean)

* New translations guidelines.md (Japanese)

* New translations principles-of-a-good-tutorial.md (Korean)

* New translations sample-tutorial.md (Korean)

* New translations readme.md (Korean)

* New translations contribution-rules.md (Korean)

* New translations maintainers.md (Korean)

* New translations participate.md (Korean)

* New translations mining.md (Korean)

* remove engines

* update dropdown menu

* fix import

* add translation of sidebar

---------

Co-authored-by: TonSquare <[email protected]>

* New translations how-it-works.md (Chinese Simplified)

* New translations how-to-contribute.md (Chinese Simplified)

* format fix

* Update to mytonctrl2 links in FullNode

* Add tip on how to use testnet config in Full Node

* Add tip about status fast in testnet

* Refactor

* Add link for testnet dump for archive node

* update default lang array

* New translations pow-givers.md (Korean)

* New translations sharding-lifecycle.mdx (Korean)

* fix header (ton-community#68)

* fix translation header

* Fix number of outgoing messages

* Remove duplicated

* Add tlb-parsers.md & Add tlb-codegen & fix link

* Separate parsers and tl-b generator

* add backend example for ton proof

* New translations send-transactions-from-highload.md (Chinese Simplified)

* New translations shards.mdx (Korean)

* New translations auditors.mdx (Korean)

* New translations outsource.mdx (Korean)

* New translations adnl.md (Korean)

* New translations getblock-ton-api.md (Korean)

* New translations overview.md (Chinese Simplified)

* New translations how-to-contribute.md (Chinese Simplified)

* cut_warining

* Stepik corrections

Added RU and CHN links as well as replaced EN -> CHN in CHN pages

* Update academy-overview.md

* Add AWS instance description

* ecosystem_messages_layout_init

* ecosystem_messages_layuot_2

Correction sidebars,js

* ecosystem-messages-layout_3

Scheme files added

* ecosystem-messages-layout_4

Cookbook update

* chrore: add info about gasless transactions

* Add information about node setup timings

* Revert "ecosystem-messages-layout_4"

This reverts commit c33a788.

* ecosystem_messages_layout_4

Cookbook Update according new schemes

* cookbook_schemes_update

Added dark scheme

* Cookbook_update

Deleting old scheme

* Cookbook_update_3

Deleting old schemes

* Update jetton_transfer_dark.svg

* Fix non latin symbol

* Scheme_Visio_added

* Update archive-node.md

update archive node requirements

* Update enable-liteserver-node.md

update liteserver requirements

* sidebar_fix

* Delete public proxy and C++ compile page

- participate/web3/sites-and-proxy
- public proxy

* Delete public proxy and C++ instruction

- participate/web3/sites-and-proxy
- public proxy
amend

* Revert "Delete public proxy and C++ instruction"

This reverts commit 4adc61a.

* tons_sites_for_apps_page_added

* Updated after review

* cut_jetton_text

Cut the jetton - as Standard operation text from the Cookbook.

* Update how-to-run-ton-site.md

* Update how-to-run-ton-site.md

* Revert wallet.md typo fix

* Add error of wrong user usage for nodes

* docs(cookbook): update Go address parsing example

* feat: ton connect tg bot integration archived

* Update single-nominator.mdx (ton-community#710)

* Update single-nominator.mdx (ton-community#711)

* collectiong_minging_fix

Transfer fixes from PR, which got stuck because of merge conflicts.

https://github.com/ton-community/ton-docs/pull/664/files

* 🐛 Fix link in doc (ton-community#685)

* Add some explanation for effective stake (ton-community#687)

Co-authored-by: Full-Hat <[email protected]>

* feat: Add tonconnect vue sdk link (ton-community#688)

* add tonconnect vue sdk link

* fix typo

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: infinityspectra <[email protected]>

* feat: upd wallets switch testnet info (ton-community#694)

Co-authored-by: igor <[email protected]>

* Add Error parsing dependencies to troubleshooting (ton-community#695)

Co-authored-by: Full-Hat <[email protected]>
Co-authored-by: AlexG <[email protected]>

* Fix typo in mode 0 of send_raw_message (ton-community#699)

This is a non-trivial typo as developer most likely refer to mode 0 to understand how token transfer works

* Update how-to-run-ton-site.md (ton-community#700)

* update ton connect docs, add video (ton-community#701)

Co-authored-by: Aliaksandr Bahdanau <[email protected]>

* Update cookbook.md date->data (ton-community#703)

* Update messages.md (ton-community#706)

Fixed Send a regular message

* fix_node_troubleshooting

added lost snippet related to Version problem

* update troubleshooting (ton-community#712)

* update_ton_connect_button

* remove mytonctrl2 branch mentions (ton-community#714)

* Scheme update 2 (ton-community#707)

* Ecosystem_schemes_layout_5

Try to change font replacement

* Ecosystem_scheme_png_update

* Ecosystem_sheme_png_2

* Update nodes-troubleshooting.md

* SAP list update

SAP list updated according current status of auditors on Ecosystem.

* added contributors wall

* single-nominator-fix

* wallet-guidelines-cut-oudated-link

* Added info run docker (ton-community#611)

* add info run in docker

* change docker repository mytonctrl

* Update docs/participate/run-nodes/run-docker.md

Co-authored-by: Dr. Awesome Doge <[email protected]>

* Update docs/participate/run-nodes/run-docker.md

Co-authored-by: Dr. Awesome Doge <[email protected]>

* Update docs/participate/run-nodes/run-docker.md

Co-authored-by: Dr. Awesome Doge <[email protected]>

* Update docs/participate/run-nodes/run-docker.md

Co-authored-by: Dr. Awesome Doge <[email protected]>

* Update docs/participate/run-nodes/run-docker.md

Co-authored-by: Dr. Awesome Doge <[email protected]>

* Update docs/participate/run-nodes/run-docker.md

Co-authored-by: Dr. Awesome Doge <[email protected]>

* Update docs/participate/run-nodes/run-docker.md

Co-authored-by: Dr. Awesome Doge <[email protected]>

* Update docs/participate/run-nodes/run-docker.md

Co-authored-by: Dr. Awesome Doge <[email protected]>

* Update docs/participate/run-nodes/run-docker.md

Co-authored-by: Dr. Awesome Doge <[email protected]>

---------

Co-authored-by: Sergey Andreev <[email protected]>
Co-authored-by: AlexG <[email protected]>
Co-authored-by: Dr. Awesome Doge <[email protected]>

* Fixed code for selling nft on getgems (ton-community#691)

* fixed code for selling nft on getgems

* fix first mistake with nanoTon

* added suggestions that tokens come in different decimals

---------

Co-authored-by: vityooook <[email protected]>

* feat: add high-load wallet v3 to wallet tutorial (ton-community#715)

* Update difference-of-blockchains.md (ton-community#716)

The previous link is broken, fix with ton.org pdf

* Add transaction and messages hashes examples (ton-community#718)

Co-authored-by: Aliaksandr Bahdanau <[email protected]>

* Added message modes cookbook (ton-community#724)

Co-authored-by: Vladislav Kokosh <[email protected]>

* Update data about archive node sync timings (ton-community#720)

Co-authored-by: Full-Hat <[email protected]>

* add Japanese content document translation (ton-community#743)

* Transaction outcome description (ton-community#708)

* Transaction outcome

Definition of success and some TVM details.

* Upd transaction outcome

* Update message-delivery-guarantees.mdx

* Update tvm-overview.mdx

* Update auditors.mdx

* Additional changes to Msg & Tx page (ton-community#744)

* Transaction outcome

Definition of success and some TVM details.

* Upd transaction outcome

* Update message-delivery-guarantees.mdx

* Update tvm-overview.mdx

* Update message-delivery-guarantees.mdx

* Added an example of how to send a transaction with Wallet V5 (ton-community#721)

Co-authored-by: Vladislav Kokosh <[email protected]>

* Added actual link to wallet v5 (ton-community#725)

Co-authored-by: Vladislav Kokosh <[email protected]>

* feat: upd mytonwallet switch testnet info (ton-community#726)

Co-authored-by: igor <[email protected]>

* fix bridge.ton.org link (ton-community#727)

and open external links in new page

* Add status output explanation (ton-community#728)

Co-authored-by: Full-Hat <[email protected]>
Co-authored-by: Full-Hat <[email protected]>

* Add information about api keys (ton-community#730)

Co-authored-by: Full-Hat <[email protected]>

* supplement Korean translation (ton-community#731)

Co-authored-by: lotteam003 <[email protected]>

* Adding Tatum under RPC Nodes provider (ton-community#745)

Adding Tatum under RPC Nodes provider as Tatum provides TON RPC Nodes and whole infrastructure to run Web3 Apps.

* Fix for buttons at academy page (ton-community#747)

* Transaction outcome

Definition of success and some TVM details.

* Upd transaction outcome

* Update message-delivery-guarantees.mdx

* Update tvm-overview.mdx

* Update message-delivery-guarantees.mdx

* Update academy-overview.md

Button

* add i18n ja translation (ton-community#732)

Co-authored-by: lotteam003 <[email protected]>

* Mytonctrl installer (ton-community#733)

* Add information about disabling storing archive blocks

* Add explanation to mytonctrl installer section

---------

Co-authored-by: Full-Hat <[email protected]>

* Add information about configs (ton-community#734)

Co-authored-by: Full-Hat <[email protected]>

* change link to tonapi rates documentarion (ton-community#735)

* Examples (ton-community#736)

* Update examples & add -t flag explanation

* Complete examples

---------

Co-authored-by: Full-Hat <[email protected]>

* Fix footer & add guideline (ton-community#739)

* fix & udpate footer

* update guides

* complete add footer guide

* update branch doc

* specify function

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

* improve transaction processing (ton-community#741)

Co-authored-by: Aliaksandr Bahdanau <[email protected]>

* Add vue section (ton-community#738)

* add vue section

* cut numbers from header

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

* Add testnet.dton.io (ton-community#750)

* Add tonpy to TLB parsers and codegen (ton-community#749)

* fix jetton sample (ton-community#742)

Co-authored-by: Aliaksandr Bahdanau <[email protected]>

* remove numbers (ton-community#751)

* Update node-types.md (ton-community#748)

* Added tonutils SDK to the Python SDKs section (ton-community#740)

* update_bridge_example_link

* Add -c flag explanation in liteserver test node (ton-community#670)

* Add -c flag explanation in liteserver test node

* Update links to mytonctrl master

* Update examples & add -t flag explanation

* Add -c flag explanation in liteserver test node

* Update links to mytonctrl master

---------

Co-authored-by: Full-Hat <[email protected]>

* Add .NET ton_proof demo (ton-community#723)

* Add information about api keys (ton-community#729)

* Add information about api keys

* Remove info about tariffs

---------

Co-authored-by: Full-Hat <[email protected]>

* added translation (ton-community#752)

* Update analysis link (ton-community#674)

* Update analysis link

* Fix link

* Add eth 2.0 info

* Remove Eth 1.0 & update ton name

---------

Co-authored-by: Full-Hat <[email protected]>

* node-commands_added

* Fixed cases with 16 flag in modes cookbook (ton-community#754)

Co-authored-by: Vladislav Kokosh <[email protected]>

* Docu update on MacOS installation and docker image with MyTonCtrl 2.0 (ton-community#755)

* update ton installation on MacOS

* update docker with MyTonCtrl 2.0 docu

---------

Co-authored-by: neodiX <[email protected]>

* cut-ecosystem-sap

* Update governance.md

* lite-client-naming

* Update sign.mdx (ton-community#760)

added convenient check if proof valid

* nodes_documentation_fine_update (ton-community#762)

* nodes_documentation_fine_update

* added_wallet_deployment_for_each_shard

* added_mintless_jettons

* beauty_fixes

* beauty_fixes_2

* build_fix

* fix_node_reqierements

* node_reqierement_fix.mdx

* fix_node_reqierements_2

* fix_node_reqierements_3

* wallet_v5_caution_cut

* feat: clarified jetton errors information (ton-community#771)

Co-authored-by: Aliaksandr Bahdanau <[email protected]>

* Add Chainstack as node & indexer provider (ton-community#774)

* Update_node_reqierements

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Full-Hat <[email protected]>
Co-authored-by: Aliaksandr Bahdanau <[email protected]>
Co-authored-by: Andrey Semenov <[email protected]>
Co-authored-by: AlexG <[email protected]>
Co-authored-by: Maksim Kurbatov <[email protected]>
Co-authored-by: Vladislav Kokosh <[email protected]>
Co-authored-by: TonSquare <[email protected]>
Co-authored-by: Igor Golodnitsky <[email protected]>
Co-authored-by: Ryan Holanda <[email protected]>
Co-authored-by: Victor S <[email protected]>
Co-authored-by: sansx <[email protected]>
Co-authored-by: sansx <[email protected]>
Co-authored-by: omahs <[email protected]>
Co-authored-by: “mlikhar” <[email protected]>
Co-authored-by: Antonoff <[email protected]>
Co-authored-by: p.nazarychev <[email protected]>
Co-authored-by: Airam G <[email protected]>
Co-authored-by: Oleg Baranov <[email protected]>
Co-authored-by: Anthony Tsivarev <[email protected]>
Co-authored-by: 70sh1 <[email protected]>
Co-authored-by: igor <[email protected]>
Co-authored-by: Ginta <[email protected]>
Co-authored-by: PixelPlex Dev team <[email protected]>
Co-authored-by: infinityspectra <[email protected]>
Co-authored-by: NakeyJakey <[email protected]>
Co-authored-by: Devin <[email protected]>
Co-authored-by: Duginets Nikita <[email protected]>
Co-authored-by: Roman <[email protected]>
Co-authored-by: Sergey Andreev <[email protected]>
Co-authored-by: Dr. Awesome Doge <[email protected]>
Co-authored-by: Victor <[email protected]>
Co-authored-by: vityooook <[email protected]>
Co-authored-by: aSpite <[email protected]>
Co-authored-by: zhangchitc <[email protected]>
Co-authored-by: SilentPine <[email protected]>
Co-authored-by: spookyahell <[email protected]>
Co-authored-by: Full-Hat <[email protected]>
Co-authored-by: lotteam003 <[email protected]>
Co-authored-by: lotteam003 <[email protected]>
Co-authored-by: blockchaingirl1407 <[email protected]>
Co-authored-by: Moiseev Ilya <[email protected]>
Co-authored-by: Andrey Tvorozhkov <[email protected]>
Co-authored-by: Artem <[email protected]>
Co-authored-by: Shon Ness <[email protected]>
Co-authored-by: Alexander <[email protected]>
Co-authored-by: StarryHazex <[email protected]>
Co-authored-by: neodix42 <[email protected]>
Co-authored-by: neodiX <[email protected]>
Co-authored-by: EmelyanenkoK <[email protected]>
Co-authored-by: JeanClaude (JC) <[email protected]>
Co-authored-by: Ake <[email protected]>
  • Loading branch information
@gleb498 @github-actions
@Full-Hat @a-bahdanau @asemenov-pixelplex @reveloper @yungwine @vkokosh @TonSquare @appqui @RyanHolanda @1IxI1 @sansx @omahs @mlikhtar @memearchivarius @fmira21 @AiramGol @xssnick @tsivarev @70sh1 @IVerhusha @mar-heaven @pixelplex @infinityspectra @Jimsparkle @studyzy @glcanvas @SwiftAdviser @awesome-doge @vityooook @aSpite @zhangchitc @SilentPine @spookyahell @lotteam003 @blockchaingirl1407 @mois-ilya @tvorogme @Sovenok-Hacker @nessshon @WinoGarcia @StarryHazex @neodix42 @EmelyanenkoK @Jeanclaudeaoun @akegaviar @gkaravatski
53 people authored and gkaravatski committed Oct 2, 2024
1 parent ddd3b6b commit f8c70df
Show file tree
Hide file tree
Showing 5 changed files with 324 additions and 11 deletions.
55 changes: 55 additions & 0 deletions docs/develop/dapps/ton-connect/protocol/README.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
# Protocol specifications

Understand how TON Connect works under the hood.

## Who is this section for?

- If you implement a wallet
- If you develop an SDK
- If you want to learn how TON Connect works

## Sections overview

* [Protocol workflows](/develop/dapps/ton-connect/protocol/workflow) is an overview of all the protocols involved in TON Connect.
* [Bridge API](/develop/dapps/ton-connect/protocol/bridge) specifies how the data is transmitted between the app and the wallet.
* [Session protocol](/develop/dapps/ton-connect/protocol/session) ensures end-to-end encrypted communication over the bridge.
* [Requests protocol](/develop/dapps/ton-connect/protocol/requests-responses) defines requests and responses for the app and the wallet.
* [Wallet guidelines](/develop/dapps/ton-connect/protocol/wallet-guidelines) defines guidelines for wallet developers.

## FAQ

#### I am building an HTML/JS app, what should I read?

Simply use the [Supported SDKs](/develop/dapps/ton-connect/developers) and do not worry about the underlying protocols.

#### I need an SDK in my favorite language

Please take the [JS SDK](/develop/dapps/ton-connect/developers) as a reference and check out the protocol docs above.

#### How do you detect whether the app is embedded in the wallet?

JS SDK does that for you; just get wallets list `connector.getWallets()` and check `embedded` property of the corresponding list item. If you build your own SDK you should check `window.[targetWalletJsBridgeKey].tonconnect.isWalletBrowser`.

#### How do you detect if the wallet is a browser extension?

Like with embedded apps (see above), JS SDK detects it for you via `injected` property of the corresponding `connector.getWallets()` list item. If you build your own SDK you should check that `window.[targetWalletJsBridgeKey].tonconnect` exists.

#### How to implement backend authorization with tonconnect?

[See an example of dapp-backend](https://github.com/ton-connect/demo-dapp-backend)

#### How do I make my own bridge?

You don’t need to, unless you are building a wallet.

If you build a wallet, you will need to provide a bridge. See our [reference implementation in Go](https://github.com/ton-connect/bridge).

Keep in mind that the wallet’s side of the bridge API is not mandated.

For a quick start you can use the common TON Connect bridge [github.com/ton-connect/bridge2](https://github.com/ton-connect/bridge2).

#### I make a wallet, how do I add it to the list of wallets?

Submit a pull request for the [wallets-list](https://github.com/ton-blockchain/wallets-list) repository and fill our all the necessary metadata.

Apps may also add wallets directly through the SDK.
202 changes: 202 additions & 0 deletions docs/develop/dapps/ton-connect/protocol/bridge.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,202 @@
# Bridge API

Bridge is a transport mechanism to deliver messages from the app to the wallet and vice versa.

* **Bridge is maintained by the wallet provider**. App developers do not have to choose or build a bridge. Each wallet’s bridge is listed in the [wallets-list](https://github.com/ton-blockchain/wallets-list) config.
* **Messages are end-to-end encrypted.** Bridge does not see the contents or long-term identifiers of the app or wallet.
* **Communication is symmetrical.** Bridge does not distinguish between apps and wallets: both are simply clients.
* Bridge keeps separate queues of messages for each recipient’s **Client ID**.

Bridge comes in two flavors:

- [HTTP Bridge](#http-bridge): for the external apps and services.
- [JS Bridge](#js-bridge): for apps opened within the wallet; or when the wallet is a browser extension.

## HTTP Bridge

Client with ID **A** connects to the bridge to listen to incoming requests.

**Client ID is semi-private:** apps and wallets are not supposed to share their IDs with other entities to avoid having their messages removed unexpectedly.

**Client can subscribe on few Client IDs** - in this case it should enumerate IDs separated with commas. For example: `?client_id=<A1>,<A2>,<A3>`

```tsx
request
GET /events?client_id=<to_hex_str(A)>

Accept: text/event-stream
```

**Subscribing to the bridge second (any other) time**

```tsx
request
GET /events?client_id=<to_hex_str(A)>&last_event_id=<lastEventId>
Accept: text/event-stream
```

**lastEventId** – the eventId of the last SSE event wallet got over the bridge. In this case wallet will fetch all the events which happened after the last connection.

Sending message from client A to client B. Bridge returns error if ttl is too high.

```tsx
request
POST /message?client_id=<to_hex_str(A)>?to=<to_hex_str(B)>&ttl=300&topic=<sendTransaction|signData>
body: <base64_encoded_message>
```


The `topic` [optional] query parameter can be used by the bridge to deliver the push notification to the wallet. If the parameter is given, it must correspond to the RPC method called inside the encrypted `message`.

Bridge buffers messages up to TTL (in secs), but removes them as soon as the recipient receives the message.

If the TTL exceeds the hard limit of the bridge server, it should respond with HTTP 400. Bridges should support at least 300 seconds TTL.

When the bridge receives a message `base64_encoded_message` from client `A` addressed to client `B`, it generates a message `BridgeMessage`:

```js
{
"from": <to_hex_str(A)>,
"message": <base64_encoded_message>
}
```

and sends it to the client B via SSE connection
```js
resB.write(BridgeMessage)
```

### Heartbeat

To keep the connection, bridge server should periodically send a "heartbeat" message to the SSE channel. Client should ignore such messages.
So, the bridge heartbeat message is a string with word `heartbeat`.


## Universal link

When the app initiates the connection it sends it directly to the wallet via the QR code or a universal link.

```bash
https://<wallet-universal-url>?
v=2&
id=<to_hex_str(A)>&
r=<urlsafe(json.stringify(ConnectRequest))>&
ret=back
```

Parameter **v** specifies the protocol version. Unsupported versions are not accepted by the wallets.

Parameter **id** specifies app’s Client ID encoded as hex (without '0x' prefix).

Parameter **r** specifies URL-safe json [ConnectRequest](/develop/dapps/ton-connect/protocol/requests-responses#initiating-connection).

Parameter **ret** (optional) specifies return strategy for the deeplink when user signs/declines the request.
- 'back' (default) means return to the app which initialized deeplink jump (e.g. browser, native app, ...),
- 'none' means no jumps after user action;
- a URL: wallet will open this URL after completing the user's action. Note, that you shouldn't pass your app's URL if it is a webpage. This option should be used for native apps to work around possible OS-specific issues with `'back'` option.

`ret` parameter should be supported for empty deeplinks -- it might be used to specify the wallet behavior after other actions confirmation (send transaction, sign raw, ...).
```bash
https://<wallet-universal-url>?ret=back
```


The link may be embedded in a QR code or clicked directly.

The initial request is unencrypted because (1) there is no personal data being communicated yet, (2) app does not even know the identity of the wallet.

### Unified deeplink `tc`
In addition to its own universal link, the wallet must support the unified deeplink.

This allows applications to create a single qr code, which can be used to connect to any wallet.

More specifically, the wallet must support `tc://` deeplink as well as its own `<wallet-universal-url>`.

Therefore, the following `connect request` must be processed by the wallet:

```bash
tc://?
v=2&
id=<to_hex_str(A)>&
r=<urlsafe(json.stringify(ConnectRequest))>&
ret=back
```


## JS bridge

Used by the embedded apps via the injected binding `window.<wallet-js-bridge-key>.tonconnect`.

`wallet-js-bridge-key` can be specified in the [wallets list](https://github.com/ton-blockchain/wallets-list)

JS bridge runs on the same device as the wallet and the app, so communication is not encrypted.

The app works directly with plaintext requests and responses, without session keys and encryption.

```tsx
interface TonConnectBridge {
deviceInfo: DeviceInfo; // see Requests/Responses spec
walletInfo?: WalletInfo;
protocolVersion: number; // max supported Ton Connect version (e.g. 2)
isWalletBrowser: boolean; // if the page is opened into wallet's browser
connect(protocolVersion: number, message: ConnectRequest): Promise<ConnectEvent>;
restoreConnection(): Promise<ConnectEvent>;
send(message: AppRequest): Promise<WalletResponse>;
listen(callback: (event: WalletEvent) => void): () => void;
}
```

Just like with the HTTP bridge, wallet side of the bridge does not receive the app requests except for [ConnectRequest](/develop/dapps/ton-connect/protocol/requests-responses#initiating-connection) until the session is confirmed by the user. Technically, the messages arrive from the webview into the bridge controller, but they are silently ignored.

SDK around the implements **autoconnect()** and **connect()** as silent and non-silent attempts at establishing the connection.

### walletInfo (optional)
Represents wallet metadata. Might be defined to make an injectable wallet works with TonConnect even if the wallet is not listed in the [wallets-list.json](https://github.com/ton-blockchain/wallets-list).

Wallet metadata format:
```ts
interface WalletInfo {
name: string;
image: <png image url>;
tondns?: string;
about_url: <about page url>;
}
```

Detailed properties description: https://github.com/ton-blockchain/wallets-list#entry-format.

If `TonConnectBridge.walletInfo` is defined and the wallet is listed in the [wallets-list.json](https://github.com/ton-blockchain/wallets-list), `TonConnectBridge.walletInfo` properties will override corresponding wallet properties from the wallets-list.json.


### connect()

Initiates connect request, this is analogous to QR/link when using the HTTP bridge.

If the app was previously approved for the current account — connects silently with ConnectEvent. Otherwise shows confirmation dialog to the user.

You shouldn't use the `connect` method without explicit user action (e.g. connect button click). If you want automatically try to restore previous connection, you should use the `restoreConnection` method.

### restoreConnection()

Attempts to restore the previous connection.

If the app was previously approved for the current account — connects silently with the new `ConnectEvent` with only a `ton_addr` data item.


Otherwise returns `ConnectEventError` with error code 100 (Unknown app).


### send()

Sends a [message](/develop/dapps/ton-connect/protocol/requests-responses#messages) to the bridge, excluding the ConnectRequest (that goes into QR code when using HTTP bridge and into connect when using JS Bridge).
Directly returns promise with WalletResponse, so you don't need to wait for responses with `listen`;

### listen()

Registers a listener for events from the wallet.

Returns unsubscribe function.

Currently, only `disconnect` event is available. Later there will be a switch account event and other wallet events.
62 changes: 62 additions & 0 deletions docs/develop/dapps/ton-connect/protocol/wallet-guidelines.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
# Wallet Guidelines

## Networks

### There aren't many networks.

At the moment, there are only two networks - Mainnet and Testnet.
In the foreseeable future, the emergence of new Mainnet TON-like networks is not expected. Note that the current Mainnet has a built-in mechanism for alternative networks - workchains.


### Hide the Testnet from ordinary users.

Testnet is used exclusively by developers. Ordinary users should not see the Testnet.
This means that switching to Testnet should not be readily available and users SHOULD NOT be prompted to switch wallet to Testnet even if DAppis in Testnet.
Users switch to Testnet, don't understand this action, can't switch back to Mainnet.

For these reasons, dapps do not need to switch networks in runtime, on the contrary, it is more preferable to have different instances of DAppon different domains dapp.com, Testnet.dapp.com.
For the same reason there is no `NetworkChanged` or `ChainChanged` event in the Ton Connect protocol.


### Do not send anything if the DAppis in Testnet and the wallet is in Mainnet.

It is necessary to prevent loss of funds when DApptries to send a transaction in Testnet, and the wallet sends it in Mainnet.

Dapps should explicitly indicate `network` field in `SendTransaction` request.

If the `network` parameter is set, but the wallet has a different network set, the wallet should show an alert and DO NOT ALLOW TO SEND this transaction.

The wallet SHOULD NOT offer to switch to another network in this case.

## Multi accounts

Multiple network accounts can be created for one key pair. Implement this functionality in your wallet - users will find it useful.

### In general, there is no current "active" account

At the moment, the TON Connect is not built on the paradigm that there is one selected account in the wallet, and when the user switches to another account, the `AccountChanged` event is sent to dapp.

We think of a wallet as a physical wallet that can contain many "bank cards" (accounts).

In most cases the sender address is not important to dapp, in these cases the user can select the appropriate account at the time of approving the transaction and the transaction will be sent from selected account.

In some cases, it is important for DAppto send the transaction from a specific address, in which case it explicitly specifies the `from` field in `SendTransaction` request. If `from` parameter is set, the wallet should DO NOT ALLOW user to select the sender's address; If sending from the specified address is impossible, the wallet should show an alert and DO NOT ALLOW TO SEND this transaction.

### Login flow

When DAppconnects the wallet, the user selects in the wallet one of their accounts that they want to log into dapp.

Regardless of what accounts the user uses next in the wallet, DAppworks with the account he received on the connection.

Just like if you logged into a web service with one of your email accounts - if you then change the email account in the email service, the web service continues to use the one he got when you logged in.

For this reason, the protocol does not provide the `AccountChanged` event.

To switch account user need to disconnect (Log out) and connect (Login) again in DAppUI.

We recommend wallets provide the ability to disconnect session with a specified DAppbecause the DAppmay have an incomplete UI.

## See Also

* [TON Connect Overview](/dapps/ton-connect/overview)
* [Connect a Wallet](/dapps/ton-connect/wallet)
3 changes: 1 addition & 2 deletions docs/participate/network-maintenance/custom-overlays.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ If you have multiple node under your control it is expedient to unite them into

Mytonctrl uses default custom overlays available at https://ton-blockchain.github.io/fallback_custom_overlays.json. This overlay is not used most of the time and intended for emergency use in case of problems with public overlay connectivity.
To stop participation in default custom overlays run commands
```bash

MyTonCtrl> set useDefaultCustomOverlays false
MyTonCtrl> delete_custom_overlay default
```
Expand All @@ -43,7 +43,6 @@ Create a config file in format:
"adnl_address_hex_2": {
"msg_sender": false
},

"adnl_address_hex_2": {
"block_sender": true
},
Expand Down
13 changes: 4 additions & 9 deletions docs/participate/nodes/node-types.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -80,18 +80,13 @@ Because of a permanent high load on public Liteservers, the majority of them is
This may drive to instability of your your lite client application.
:::

<Button href="/participate/run-nodes/full-node#enable-liteserver-mode"
colorType="primary" sizeType={'sm'}>
Enable Liteserver in your Node
</Button>

To interact with Liteservers, you can use following tools:

- TON [ADNL API](/develop/dapps/apis/adnl) as the most low-level way to communicate with the blockchain;
- TON [SDKs](/develop/dapps/apis/sdk) provided for various programming languages;
- TON [HTTP-based APIs](/develop/dapps/toncenter) providing the REST API middleware between your application and a Liteserver.
- TON [HTTP-based APIs](/develop/dapps/apis/toncenter) providing the REST API middleware between your application and a Liteserver.

<Button href="/develop/dapps/apis/sdk"
<Button href="/participate/run-nodes/enable-liteserver-node"
colorType="primary" sizeType={'sm'}>
Choose a TON SDK
</Button>
Enable Liteserver in your Node
</Button>

0 comments on commit f8c70df

Please sign in to comment.