@tonconnect/ui 2.2.0-beta.0 → 2.3.0-beta.0

package/README.md

@@ -344,6 +344,122 @@ tonConnectUI.uiOptions = {
     };
 ```
 
+## Sign data
+
+Sign arbitrary data with the user's wallet. The wallet will display the data to the user for confirmation before signing. Wallet must be connected when you call `signData`, otherwise an error will be thrown.
+
+### Data Types
+
+You can sign three types of data. Choose the right format based on your use case:
+
+- **Text** - Use for human-readable text that users should see and understand
+- **Cell** - Use for TON Blockchain data that should be used in smart contracts (wallet may show unknown content warning)  
+- **Binary** - For other arbitrary data (least preferred due to security warnings)
+
+#### Text Format
+
+Use when you need to sign human-readable text. The wallet displays the text to the user.
+
+**Parameters:**
+- `type` (string, required): Must be `"text"`
+- `text` (string, required): UTF-8 text to sign
+- `network` (string, optional): `"-239"` for mainnet, `"-3"` for testnet
+- `from` (string, optional): Signer address in raw format `"0:<hex>"`
+
+```ts
+const textData = {
+    type: "text",
+    text: "Confirm new 2fa number:\n+1 234 567 8901",
+    network: "-239", // MAINNET = '-239', TESTNET = '-3'
+    from: "0:348bcf827469c5fc38541c77fdd91d4e347eac200f6f2d9fd62dc08885f0415f"
+};
+
+try {
+    const result = await tonConnectUI.signData(textData);
+    console.log('Signed:', result);
+} catch (e) {
+    console.error('Error:', e);
+}
+```
+
+#### Binary Format
+
+Use for arbitrary binary data. The wallet shows a warning about unknown content.
+
+**Parameters:**
+- `type` (string, required): Must be `"binary"`
+- `bytes` (string, required): Base64 encoded binary data (not url-safe)
+- `network` (string, optional): `"-239"` for mainnet, `"-3"` for testnet
+- `from` (string, optional): Signer address in raw format `"0:<hex>"`
+
+```ts
+const binaryData = {
+    type: "binary",
+    bytes: "1Z/SGh+3HFMKlVHSkN91DpcCzT4C5jzHT3sA/24C5A==",
+    network: "-239", // MAINNET = '-239', TESTNET = '-3'
+    from: "0:348bcf827469c5fc38541c77fdd91d4e347eac200f6f2d9fd62dc08885f0415f"
+};
+
+try {
+    const result = await tonConnectUI.signData(binaryData);
+    console.log('Signed:', result);
+} catch (e) {
+    console.error('Error:', e);
+}
+```
+
+#### Cell Format
+
+Use for TON Blockchain data with TL-B schema. The wallet can parse and display the content if the schema is valid.
+
+**Parameters:**
+- `type` (string, required): Must be `"cell"`
+- `schema` (string, required): TL-B schema of the cell payload
+- `cell` (string, required): Base64 encoded BoC (not url-safe) with single-root cell
+- `network` (string, optional): `"-239"` for mainnet, `"-3"` for testnet
+- `from` (string, optional): Signer address in raw format `"0:<hex>"`
+
+```ts
+const cellData = {
+    type: "cell",
+    schema: "transfer#0f8a7ea5 query_id:uint64 amount:(VarUInteger 16) destination:MsgAddress response_destination:MsgAddress custom_payload:(Maybe ^Cell) forward_ton_amount:(VarUInteger 16) forward_payload:(Either Cell ^Cell) = InternalMsgBody;",
+    cell: "te6ccgEBAQEAVwAAqg+KfqVUbeTvKqB4h0AcnDgIAZucsOi6TLrfP6FcuPKEeTI6oB3fF/NBjyqtdov/KtutACCLqvfmyV9kH+Pyo5lcsrJzJDzjBJK6fd+ZnbFQe4+XggI=",
+    network: "-239", // MAINNET = '-239', TESTNET = '-3'
+    from: "0:348bcf827469c5fc38541c77fdd91d4e347eac200f6f2d9fd62dc08885f0415f"
+};
+
+try {
+    const result = await tonConnectUI.signData(cellData);
+    console.log('Signed:', result);
+} catch (e) {
+    console.error('Error:', e);
+}
+```
+
+### Response
+
+All signData calls return the same response structure:
+
+```ts
+interface SignDataResult {
+    signature: string; // Base64 encoded signature
+    address: string;   // Wallet address in raw format
+    timestamp: number; // UNIX timestamp in seconds (UTC)
+    domain: string;    // App domain name 
+    payload: object;   // Original payload from the request
+}
+```
+
+### Signature Verification
+
+After receiving the signed data, you need to verify the signature to ensure it's authentic and was signed by the claimed wallet address.
+
+**For backend verification:** See [TypeScript verification example](https://github.com/ton-connect/demo-dapp-with-react-ui/blob/master/src/server/services/sign-data-service.ts#L32-L109) showing how to verify signatures on your server.
+
+**For smart contract verification:** See [FunC verification example](https://github.com/p0lunin/sign-data-contract-verify-example/blob/master/contracts/sign_data_example.fc) showing how to verify signatures in TON smart contracts.
+
+**For complete technical details:** See the [Sign Data specification](https://github.com/ton-blockchain/ton-connect/blob/main/requests-responses.md#sign-data) for full signature verification requirements.
+
 ## Universal links redirecting issues (IOS)
 Some operating systems, and especially iOS, have restrictions related to universal link usage. 
 For instance, if you try to open a universal link on an iOS device via `window.open`, you can face the following problem:
@@ -925,3 +1041,9 @@ Please note that this is just a warning and should not affect the functionality
 ```shell
 npm install encoding
 ```
+
+## How to find a sent transaction on the blockchain
+
+See the detailed guide: [Transaction-by-external-message](../../guidelines/transaction-by-external-message.md)
+
+This guide explains how to find the corresponding transaction on the TON blockchain by the BOC of an external-in message.