diff --git a/docs/develop/dapps/ton-connect/sign.mdx b/docs/develop/dapps/ton-connect/sign.mdx index 592d66dba1..e343efe401 100644 --- a/docs/develop/dapps/ton-connect/sign.mdx +++ b/docs/develop/dapps/ton-connect/sign.mdx @@ -1,4 +1,6 @@ -# Sign and Verification +import ThemedImage from '@theme/ThemedImage'; + +# Signing and Verification :::warning @@ -29,10 +31,62 @@ type TonProofItemReplySuccess = { ## How to use TON Proof (High-Level) - Send dApp id to client(nested in the QR code typically) -- Got signed transaction with message from client in the ton proof entity -- Verify TON Proof on the back-end side +- Retrieve signed transaction with ton_proof entity +- Verify ton_proof on the backend side + +

+ +

+ +## Address proof signature (`ton_proof`) + +If `TonProofItem` is requested, wallet proves ownership of the selected account’s key. The signed message is bound to: + +- Unique prefix to separate messages from on-chain messages. (`ton-connect`) +- Wallet address. +- App domain +- Signing timestamp +- App’s custom payload (where server may put its nonce, cookie id, expiration time). + +``` +message = utf8_encode("ton-proof-item-v2/") ++ + Address ++ + AppDomain ++ + Timestamp ++ + Payload +signature = Ed25519Sign(privkey, sha256(0xffff ++ utf8_encode("ton-connect") ++ sha256(message))) +``` + +where: -![](\img\docs\ton-connect\ton_proof_scheme.png?raw=true) +* `Address` is the wallet address encoded as a sequence: + * `workchain`: 32-bit signed integer big endian; + * `hash`: 256-bit unsigned integer big endian; +* `AppDomain` is Length ++ EncodedDomainName +- `Length` is 32-bit value of utf-8 encoded app domain name length in bytes +- `EncodedDomainName` id `Length`-byte utf-8 encoded app domain name +* `Timestamp` 64-bit unix epoch time of the signing operation +* `Payload` is a variable-length binary string. + +Note: payload is variable-length untrusted data. To avoid using unnecessary length prefixes we simply put it last in the message. + +The signature must be verified by public key: + +1. First, try to obtain public key via `get_public_key` get-method on smart contract deployed at `Address`. + +2. If the smart contract is not deployed yet, or the get-method is missing, you need: + +2.1. Parse `TonAddressItemReply.walletStateInit` and get public key from stateInit. You can compare the `walletStateInit.code` with the code of standard wallets contracts and parse the data according to the found wallet version. + +2.2. Check that `TonAddressItemReply.publicKey` equals to obtained public key + +2.3. Check that `TonAddressItemReply.walletStateInit.hash()` equals to `TonAddressItemReply.address`. `.hash()` means BoC hash. ## How to Check TON Proof on Server Side(Low-Level) @@ -51,4 +105,8 @@ Obtain from the frontend the following data: wallet address, domain, timestamp, * [GO demo app](https://github.com/ton-connect/demo-dapp-backend/blob/master/proof.go) * [TS example](https://gist.github.com/TrueCarry/cac00bfae051f7028085aa018c2a05c6) -* [Python example](https://github.com/disintar/ton-connect-python-proof/blob/master/check_proof.ipynb?short_path=8776c84) \ No newline at end of file +* [Python example](https://github.com/disintar/ton-connect-python-proof/blob/master/check_proof.ipynb?short_path=8776c84) + +## See Also + +[[YouTube] TON Connect ton proof [RU](https://www.youtube.com/watch?v=i2HzhM59kfQ) \ No newline at end of file diff --git a/docs/develop/dapps/ton-connect/transactions.md b/docs/develop/dapps/ton-connect/transactions.md index b044389370..c2d9f2e703 100644 --- a/docs/develop/dapps/ton-connect/transactions.md +++ b/docs/develop/dapps/ton-connect/transactions.md @@ -1,10 +1,10 @@ -# Sending messages +# Sending Messages :::info There is no description of connecting a wallet on this page. We suppose you have already connected the wallet to your dApp. If not, you can refer to [integration manual](/develop/dapps/ton-connect/integration). ::: -TON Connect 2 has more powerful options than just authenticating users in the dApp: it's possible to send outgoing messages via connected wallets! +TON Connect 2.0 has more powerful options than just authenticating users in the dApp: it's possible to send outgoing messages via connected wallets! ## Playground page @@ -31,6 +31,7 @@ We'll experiment in the browser console on a page where the wallet is already co ``` + ## Sending multiple messages Let's start with something interesting! We will send two separate messages in one transaction: one to your own address, carrying 0.2 TON, and one to the other wallet address carrying 0.1 TON. @@ -148,6 +149,10 @@ console.log(await connector.sendTransaction({ })); ``` +:::info +Learn more about payload from [Preparing Messages](/develop/dapps/ton-connect/message-builders) page for Transfer NFT and Jettons. +::: + After confirmation, we may see our transaction complete at [tonscan.org](https://tonscan.org/tx/pCA8LzWlCRTBc33E2y-MYC7rhUiXkhODIobrZVVGORg=). ## What happens if the user rejects a transaction request? @@ -158,4 +163,4 @@ When a user clicks "Cancel" in the popup in the wallet application, an exception ## See Also -* [Preparing Messages](/develop/dapps/ton-connect/message-builders) \ No newline at end of file +* [Preparing Messages](/develop/dapps/ton-connect/message-builders) diff --git a/docs/develop/dapps/ton-connect/web.mdx b/docs/develop/dapps/ton-connect/web.mdx index bab86aaa5b..8e50a30298 100644 --- a/docs/develop/dapps/ton-connect/web.mdx +++ b/docs/develop/dapps/ton-connect/web.mdx @@ -3,74 +3,139 @@ import Button from '@site/src/components/button' import ThemedImage from '@theme/ThemedImage'; +# TON Connect for Websites -:::warning -The page is under development. -::: +## Installation React -TODO: add description with TON Connect UI + low-level SDK +1. Install @tonconnect/ui-react in the project of your website: -# TON Connect for the Web with the JavaScript SDK +```bash +npm i @tonconnect/ui-react +``` -Telegram Web Apps (TWA) are web applications that run inside the Telegram messenger. They are built using web technologies — HTML, CSS, and JavaScript. TWA can be used to create bots, games, and other types of apps that can be run inside Telegram. +2. [Define manifest.json](#application-manifest) for you application. +3. Add `TonConnectUIProvider` to the root of the your website: - - +```tsx +import { TonConnectUIProvider } from '@tonconnect/ui-react'; +export function App() { + return ( + + { /* Your app */ } + + ); +} +``` +4. Add TonConnect Button +TonConnect Button is universal UI component for initializing connection. After wallet is connected it transforms to a wallet menu. It is recommended to place it in the top right corner of your app. +```tsx +export const Header = () => { + return ( +
+ My App with React UI + +
+ ); +}; +``` +You can add className and style props to the button as well. Note that you cannot pass child to the TonConnectButton. -### Web Sites SDK list +### Examples +* [Demo dApp](https://github.com/ton-connect/demo-dapp-with-react-ui) - Example of a DApp with `@tonconnect/ui-react`. +* [ton.vote](https://github.com/orbs-network/ton-vote) - Example of React website with TON Connect implementation. -## TON Web Sites -- [Telegram Web Apps documentation](https://docs.twa.dev/docs/introduction/about-platform) — a community-driven documentation for TWA. -- [TWA Documentation by Telegram](https://core.telegram.org/bots/webapps) — full description on Telegram website. +## Installation JavaScript/HTML -### Community +1. Add script in the `` of your website: -Join a Telegram [Community Chat](https://t.me/tondev_eng) for TON developers if you're interested. +```html + +``` -## TON Connect for Web Apps +:::tip +It is recommended to use certain library version for minimize unpredictable behaviour with updates, however last version available with `ui@latest`. +::: +2. [Define manifest.json](#application-manifest) for you application. -Recommended TON Connect SDK for Telegram Web Apps is a UI React SDK. It is a React component that provides a high-level way to interact with TON Connect. +3. Create anchor in top right corner for the connection button +```html +
+``` -```bash -npm i @tonconnect/ui-react +4. Final step, add script for a connector `tonConnectUI` in `` part of application page: + +```html + ``` -- [GitHub](https://github.com/ton-connect/sdk/tree/main/packages/ui-react) -- [NPM](https://www.npmjs.com/package/@tonconnect/ui-react) -- [API Documentation](https://ton-connect.github.io/sdk/modules/_tonconnect_ui_react.html) -### Basic usage +## Application manifest +App needs to have its manifest to pass meta information to the wallet. Manifest is a JSON file named as `tonconnect-manifest.json` following format: -TonConnect UI React is a React UI kit for TonConnect SDK. Use it to connect your app to TON wallets via TonConnect protocol in React apps. +```json +{ + "url": "", // required + "name": "", // required + "iconUrl": "", // required + "termsOfUseUrl": "", // optional + "privacyPolicyUrl": "" // optional +} +``` -```jsx -import { TonConnectUIProvider } from '@tonconnect/ui-react'; +Example: -export function App() { - return ( - - { /* Your app */ } - - ); +```json +{ + "url": "https://ton.vote", + "name": "TON Vote", + "iconUrl": "https://ton.vote/logo.png" } ``` -* Example of a DApp with `@tonconnect/ui-react`: [GitHub](https://github.com/ton-connect/demo-dapp-with-react-ui) -* Example of deployed `demo-dapp-with-react-ui`: [GitHub](https://ton-connect.github.io/demo-dapp-with-react-ui/) +Best practice is to place the manifest in the root of your app, e.g. `https://myapp.com/tonconnect-manifest.json`. It allows the wallet to handle your app better and improve the UX connected to your app. +Make sure that manifest is available to GET by its URL. + +#### Fields description +|Field|Requirement|Description| +|---|---|---| +|`url` |required| app URL. Will be used as the dapp identifier. Will be used to open the dapp after click to its icon in the wallet. It is recommended to pass url without closing slash, e.g. 'https://mydapp.com' instead of 'https://mydapp.com/'.| +| `name`|required| app name. Might be simple, will not be used as identifier.| +| `iconUrl`| required | Url to the app icon. Must be PNG, ICO, ... format. SVG icons are not supported. Perfectly pass url to a 180x180px PNG icon.| +| `termsOfUseUrl` |optional| url to the Terms Of Use document. Optional for usual apps, but required for the apps which is placed in the Tonkeeper recommended apps list.| +| `privacyPolicyUrl` | optional | url to the Privacy Policy document. Optional for usual apps, but required for the apps which is placed in the Tonkeeper recommended apps list.| + +## Learn + + + + ### SDKs for other frameworks - If you don't use React for your app, take a look at TonConnect UI. - If you want to use TonConnect on the server side, you should use the TonConnect SDK. -- Check the [supported SDKs](/develop/dapps/ton-connect/developers) list and choose the one that suits you best. \ No newline at end of file +- Check the [supported SDKs](/develop/dapps/ton-connect/developers) list and choose the one that suits you best. + +## See Also + +* [Preparing Messages](/develop/dapps/ton-connect/message-builders) +* [Sending Messages](/develop/dapps/ton-connect/transactions) +* [Signing and Verification](/develop/dapps/ton-connect/sign) +* [[YouTube] TON Connect UI React [RU]](https://youtu.be/wIMbkJHv0Fs?list=PLyDBPwv9EPsCJ226xS5_dKmXXxWx1CKz_&t=1747) +* [[YouTube] Connect TON Connect UI to Site [RU]](https://www.youtube.com/watch?v=HUQ1DPfFxG4&list=PLyDBPwv9EPsAIWi8vgic9kiV3KF_wvIcz&index=4) diff --git a/static/img/docs/ton-connect/ton_proof_scheme-dark.svg b/static/img/docs/ton-connect/ton_proof_scheme-dark.svg new file mode 100644 index 0000000000..0cce783619 --- /dev/null +++ b/static/img/docs/ton-connect/ton_proof_scheme-dark.svg @@ -0,0 +1,386 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Page-1 + + + + + + + + + + Actor lifeline + dApp frontend + + Sheet.39 + + + + Sheet.41 + + + Sheet.42 + + + + + + + dApp frontend + + + + + + + + + Object lifeline + dApp backend + + Sheet.44 + + + + Sheet.45 + + + + Sheet.46 + + + Sheet.47 + + + + + + + dApp backend + + + + + + + + + Object lifeline.54 + Wallet + + Sheet.55 + + + + Sheet.56 + + + + Sheet.57 + + + Sheet.58 + + + + + + + Wallet + + + Activation + + + + + + + + Activation.60 + + + + + + + + Activation.65 + + + + + + + + Message.21 + + + + + + + + + + + + Dynamic connector.161 + + + + + + + Activation.148 + + + + + + + + Dynamic connector + + + + + + + Dynamic connector.152 + + + + + + + Dynamic connector.153 + + + + + + + + + + + User + + + + + Sheet.155 + + Sheet.156 + + + + + + + Sheet.157 + + + + + + + + + Dynamic connector.160 + + + + + + + + + + + + + Object lifeline.142 + User + + Sheet.164 + + + + Sheet.165 + + + + Sheet.166 + + + Sheet.167 + + + + + + + User + + + Dynamic connector.169 + + + + + + + Sheet.175 + Connect wallet + + + + + + + Connect wallet + + Sheet.179 + generate ton_proof payload + + + + + + + generate ton_proofpayload + + Sheet.181 + Connection request with ton_proof + + + + + + + Connection request with ton_proof + + Sheet.183 + Signed ton_proof + + + + + + + Signed ton_proof + + Sheet.185 + Check ton_proof + + + + + + + Check ton_proof + + Sheet.189 + Auth token/cookie + + + + + + + Auth token/cookie + + diff --git a/static/img/docs/ton-connect/ton_proof_scheme.png b/static/img/docs/ton-connect/ton_proof_scheme.png deleted file mode 100644 index a7c61a26d7..0000000000 Binary files a/static/img/docs/ton-connect/ton_proof_scheme.png and /dev/null differ diff --git a/static/img/docs/ton-connect/ton_proof_scheme.svg b/static/img/docs/ton-connect/ton_proof_scheme.svg new file mode 100644 index 0000000000..25a9723939 --- /dev/null +++ b/static/img/docs/ton-connect/ton_proof_scheme.svg @@ -0,0 +1,403 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Page-1 + + + + + + + + + + Actor lifeline + dApp frontend + + Sheet.39 + + + + + + + Sheet.41 + + + + Sheet.42 + + + + + + + + + + dApp frontend + + + + + + + + + Object lifeline + dApp backend + + Sheet.44 + + + + + + + Sheet.45 + + + + + + + Sheet.46 + + + + Sheet.47 + + + + + + + + + + dApp backend + + + + + + + + + Object lifeline.54 + Wallet + + Sheet.55 + + + + + + + Sheet.56 + + + + + + + Sheet.57 + + + + Sheet.58 + + + + + + + + + + Wallet + + + Activation + + + + + + + + Activation.60 + + + + + + + + Activation.65 + + + + + + + + Message.21 + generate ton_proof payload + + + + + + + + + + + + + generate ton_proofpayload + + Activation.148 + + + + + + + + Dynamic connector + + + + + + + Dynamic connector.152 + Connection request with ton_proof + + + + + + + + Connection request with ton_proof + + Dynamic connector.153 + Signed ton_proof + + + + + + + + Signed ton_proof + + + + + + User + + + + + Sheet.155 + + Sheet.156 + + + + + + + Sheet.157 + + + + + + + + + Dynamic connector.160 + Check ton_proof + + + + + + + + Check ton_proof + + Dynamic connector.161 + Auth token/cookie + + + + + + + + Auth token/cookie + + + + + + + + Object lifeline.142 + User + + Sheet.164 + + + + + + + Sheet.165 + + + + + + + Sheet.166 + + + + Sheet.167 + + + + + + + + + + User + + + Dynamic connector.169 + Connect wallet + + + + + + + + Connect wallet + + diff --git "a/static/schemes-visio/~$$ton-connect \342\200\224 dark.~vsdx" "b/static/schemes-visio/~$$ton-connect \342\200\224 dark.~vsdx" new file mode 100644 index 0000000000..11647a4ab9 Binary files /dev/null and "b/static/schemes-visio/~$$ton-connect \342\200\224 dark.~vsdx" differ diff --git a/static/schemes-visio/~$$ton-connect.~vsdx b/static/schemes-visio/~$$ton-connect.~vsdx new file mode 100644 index 0000000000..02bd7eb4f8 Binary files /dev/null and b/static/schemes-visio/~$$ton-connect.~vsdx differ