签名与验证

使用案例

请注意，并非所有DApps都需要 ton_proof 验证。 这对于后端的授权是必要的，以确保用户确实拥有声明的地址，因此可以推断出用户有权访问其在后端的数据。

如果您想验证用户以便从后端提供其个人信息，这将是有用的。

ton_proof 如何工作？

• 向客户端发送DAppid。通常，DAppid嵌入在二维码中。
• 检索带有 ton_proof 实体的已签名交易
• 在后端验证 ton_proof

ton_proof 的结构

ton_proof 在 TON Connect 中与特殊的 TonProof 实体一起工作，该实体在连接器内部实现。

type TonProofItemReply = TonProofItemReplySuccess | TonProofItemReplyError;

type TonProofItemReplySuccess = {
  name: "ton_proof";
  proof: {
    timestamp: string; // 64位unix时代签名操作的时间（秒）
    domain: {
      lengthBytes: number; // AppDomain 长度
      value: string;  // app 域名（作为url部分，无编码）
    };
    signature: string; // base64编码的签名
    payload: string; // 来自请求的有效载荷
  }
}

在服务器端检查 ton_proof

1. 从用户处检索 TonProofItemReply。
2. 验证接收到的域是否对应于应用程序的域。
3. 检查 TonProofItemReply.payload 是否被原始服务器允许且仍然有效。
4. 检查 timestamp 在当前是否真实。
5. 根据消息方案组装消息。
6. 通过API (a) 或 (b) 在后端实现的逻辑获取 public_key

• 6a:
  • 通过 TON API 方法 POST /v2/tonconnect/stateinit 从 walletStateInit 中检索 {public_key, address}。
  • 验证从 walletStateInit 提取的 address 或对应于用户声明的钱包 address。
• 6b:
  • 通过钱包合约的 get 方法 获得钱包的 public_key。
  • 如果合约未激活，或者缺少在旧钱包版本（v1-v3）中发现的 get_method，则以这种方式获取密钥将是不可能的。相反，您将需要解析前端提供的 walletStateInit。确保 TonAddressItemReply.walletStateInit.hash() 等于 TonAddressItemReply.address.hash()，表示一个BoC哈希。

7. 验证前端的 signature 实际上签署了组装的消息，并且对应于地址的 public_key。

React 示例

1. 将token提供器添加到应用的根部：

function App() {
    const [token, setToken] = useState<string | null>(null);

  return (
      <BackendTokenContext.Provider value={{token, setToken}}>
            { /* Your app */ }
      </BackendTokenContext.Provider>
  )
}

2. 描述后端认证：

示例

import {useContext, useEffect, useRef} from "react";
import {BackendTokenContext} from "./BackendTokenContext";
import {useIsConnectionRestored, useTonConnectUI, useTonWallet} from "@tonconnect/ui-react";
import {backendAuth} from "./backend-auth";

const localStorageKey = 'my-dapp-auth-token';
const payloadTTLMS = 1000 * 60 * 20;

export function useBackendAuth() {
    const { setToken } = useContext(BackendTokenContext);
    const isConnectionRestored = useIsConnectionRestored();
    const wallet = useTonWallet();
    const [tonConnectUI] = useTonConnectUI();
    const interval = useRef<ReturnType<typeof setInterval> | undefined>();

    useEffect(() => {
        if (!isConnectionRestored || !setToken) {
            return;
        }

        clearInterval(interval.current);

        if (!wallet) {
            localStorage.removeItem(localStorageKey);
            setToken(null);

            const refreshPayload = async () => {
                tonConnectUI.setConnectRequestParameters({ state: 'loading' });

                const value = await backendAuth.generatePayload();
                if (!value) {
                    tonConnectUI.setConnectRequestParameters(null);
                } else {
                    tonConnectUI.setConnectRequestParameters({state: 'ready', value});
                }
            }

            refreshPayload();
            setInterval(refreshPayload, payloadTTLMS);
            return;
        }

        const token = localStorage.getItem(localStorageKey);
        if (token) {
            setToken(token);
            return;
        }

        if (wallet.connectItems?.tonProof && !('error' in wallet.connectItems.tonProof)) {
            backendAuth.checkProof(wallet.connectItems.tonProof.proof, wallet.account).then(result => {
                if (result) {
                    setToken(result);
                    localStorage.setItem(localStorageKey, result);
                } else {
                    alert('Please try another wallet');
                    tonConnectUI.disconnect();
                }
            })
        } else {
            alert('Please try another wallet');
            tonConnectUI.disconnect();
        }

    }, [wallet, isConnectionRestored, setToken])
}

概念解释

如果请求了 TonProofItem，钱包证明了账户所选密钥的所有权。签名消息绑定到：

• 独特的前缀，以将消息与链上消息分开。（ton-connect）
• 钱包地址
• App域
• 签名时间戳
• 应用的自定义有效载荷（服务器可能在其中放置其随机数、cookie id、过期时间）

message = utf8_encode("ton-proof-item-v2/") ++
          Address ++
          AppDomain ++
          Timestamp ++
          Payload

signature = Ed25519Sign(privkey, sha256(0xffff ++ utf8_encode("ton-connect") ++ sha256(message)))

其中：

• Address 是钱包地址编码为一系列：
• workchain：32位有符号整数大端；
• hash：256位无符号整数大端；
• AppDomain 是长度 ++ 编码的域名

• 长度 是utf-8编码的应用域名长度的32位值（以字节为单位）
• 编码的域名 是长度字节的utf-8编码的应用域名

• Timestamp 是签名操作的64位unix时代时间
• Payload 是一个可变长度的二进制字符串。

注意：有效载荷是可变长度的不受信任数据。为避免使用不必要的长度前缀，我们将其放在消息的最后。

公钥必须验证签名：

1. 首先，尝试通过在 Address 部署的智能合约上的 get_public_key get-method 获得公钥。

2. 如果智能合约尚未部署，或缺少get-method，您需要：

   1. 解析 TonAddressItemReply.walletStateInit 并从stateInit获取公钥。您可以将 walletStateInit.code 与标准钱包合约的代码进行比较，并根据找到的钱包版本解析数据。

   2. 检查 TonAddressItemReply.publicKey 是否等于获得的公钥。

   3. 检查 TonAddressItemReply.walletStateInit.hash() 是否等于 TonAddressItemReply.address。.hash() 意味着BoC哈希。

TON Proof 验证示例

• GO 演示应用
• TS 示例
• Python 示例

参阅

• [YouTube] 为 @tonconnect/react-ui 检查 ton_proof [RU]
• 准备消息
• 发送消息