@tonconnect/sdk 3.2.0 → 3.3.0-beta.0

package/README.md

@@ -247,6 +247,134 @@ try {
 }
 ```
 
+## Sign data
+
+Sign arbitrary data with the user's wallet. The wallet will display the data to the user for confirmation before signing.
+
+### 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 connector.signData(textData);
+    console.log('Signed:', result);
+} catch (e) {
+    if (e instanceof UserRejectedError) {
+        console.log('User rejected signing');
+    } else {
+        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 connector.signData(binaryData);
+    console.log('Signed:', result);
+} catch (e) {
+    if (e instanceof UserRejectedError) {
+        console.log('User rejected signing');
+    } else {
+        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 connector.signData(cellData);
+    console.log('Signed:', result);
+} catch (e) {
+    if (e instanceof UserRejectedError) {
+        console.log('User rejected signing');
+    } else {
+        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.
+
 ## Disconnect wallet
 Note that if you want to change connected wallet, you should disconnect current one firstly. Also make sure that you've waited for `restoreConnection()` promise resolved before call `disconnect()`;