TG Miniapp 钱包技术实现 ​

本文档介绍如何将 浏览器插件钱包移植到 Telegram Miniapp 环境中，实现跨端钱包能力。

一、项目概述 ​

1.1 核心结论 ​

1.2 设计目标 ​

在不重新开发整个钱包的前提下，通过适配层抹平浏览器插件和 TG Miniapp 之间的运行时差异。

二、插件现有架构 ​

2.1 三个运行环境 ​

浏览器插件依赖三个独立的运行环境：

2.2 在 TG 中的替代方案 ​

graph TB
    subgraph "浏览器插件"
        A1[DAPP环境<br/>代码注入]
        A2[Background环境<br/>Storage + 后台运行]
        A3[UI环境<br/>插件页面]
    end

    subgraph "TG Miniapp"
        B1[TON Connect<br/>/ Wallet Connect]
        B2[TG本地存储<br/>或TG云存储]
        B3[TG Miniapp Webview]
    end

    A1 -.->|替代| B1
    A2 -.->|替代| B2
    A3 -.->|替代| B3

关键差异：TG 中不支持向网页注入代码，DApp 交互需通过标准连接协议实现。

三、整体架构设计 ​

3.1 适配层架构 ​

graph TB
    subgraph "业务层（不变）"
        BIZ[钱包业务逻辑]
    end

    subgraph "适配层（新增）"
        AD[运行时适配器]
    end

    subgraph "运行时环境"
        E1[浏览器插件 API]
        E2[TG Miniapp API]
    end

    BIZ --> AD
    AD --> E1
    AD --> E2

3.2 Polyfill 方案 ​

在非插件环境中，模拟 Chrome 插件 API：

3.3 BG-UI 环境抹平 ​

现有架构：插件由 Background 和 UI 两个独立进程组成，通过 Chrome API 通信。

目标架构：

• UI 通过 backgroundConnect 对象调用 BG 模块暴露的 API
• UI 通过 backgroundConnect 监听 BG 模块的 sendUpdate 数据
• 业务逻辑对通信方式无感知

sequenceDiagram
    participant UI as UI 模块
    participant Adapter as 通信适配层
    participant BG as Background 模块

    UI->>Adapter: 调用钱包方法
    Adapter->>BG: 转发请求（插件用chrome.runtime / Web用直接调用）
    BG->>BG: 执行业务逻辑
    BG->>Adapter: sendUpdate 通知
    Adapter->>UI: 更新 UI 状态

四、DApp 交互方案 ​

4.1 TON Connect ​

sequenceDiagram
    participant DApp as DApp
    participant SDK as TON Connect SDK
    participant Server as TonConnect Server
    participant Wallet as TG Miniapp钱包

    DApp->>SDK: 发起连接请求
    SDK->>Server: 发送连接请求
    Server->>Wallet: 推送连接请求
    Wallet->>Wallet: 用户确认连接
    Wallet->>Server: 返回连接结果
    Server->>SDK: 转发结果
    SDK->>DApp: 连接成功

    DApp->>SDK: 发起交易请求
    SDK->>Server: 转发交易
    Server->>Wallet: 推送签名请求
    Wallet->>Wallet: 用户确认签名
    Wallet->>Server: 返回签名结果
    Server->>DApp: 交易完成

两部分工作：

• 钱包侧：按协议规范支持 TonConnect，对接自有 TonConnect 服务
• DApp 侧：提供 SDK/UI Kit 供 DApp 方使用

4.2 自定义 Connect 协议 ​

与 TonConnect 类似，但支持更多链。可与移动端团队共建该协议。

五、安全方案 ​

5.1 存储方案对比 ​

产品可选择只提供一种，或让用户自选（主要选择是否跨端）。

5.2 加密方案 ​

基础方案（来自插件经验） ​

1. 不直接使用密码加密
2. 将用户密码进行 50万 - 90万次 PBKDF2 密钥衍生
3. 通过多轮耗时计算提升暴力破解难度
4. Mac 上一次暴力尝试约需 230-340 毫秒

TG 特有：生物识别增强 ​

graph LR
    A[用户触发生物识别] --> B[Face ID / 指纹]
    B --> C[TG BiometricManager]
    C --> D[读取随机密钥<br/>上限1024字节]
    D --> E[系统Enclave解密]
    E --> F[数十万次密钥衍生]
    F --> G[解密助记词/私钥]

• 调用 TG 的 BiometricManager 生成超长密码（上限 1024 字节）
• 随机密钥使用系统 Enclave 密钥加密后存储
• 读取需要用户进行生物识别认证
• 同样进行数十万次密钥衍生

5.3 竞品安全性对比 ​

5.4 跨端说明 ​

• 用户密码加密 → 直接跨端，其他端输入相同密码即可
• 生物识别加密 → 不能直接跨端（随机密钥在本地），需先关闭生物识别切换到普通密码

六、部署方案 ​

七、TG Bot 与 WaaS ​

7.1 TG Bot ​

每个 TG Miniapp 需对应一个 TG Bot，需准备：

• Bot 名称、描述、账户名称
• 消息回复模板
• 推送消息模板
• Bot 指令（用于唤起钱包流程）

7.2 WaaS（钱包即服务） ​

TG Miniapp Wallet 本质是 Web 钱包，架构完成后可直接：

• 以 Webview 方式嵌入三方 App/Web
• 对外提供钱包 SDK

类似 Particle WaaS、Phantom 嵌入式钱包、MetaMask 类似方案。

八、目录结构与构建 ​

8.1 关键目录 ​

src/
├── background/        # BG代码（从原插件迁移）
│   ├── controller/
│   ├── entrypoint/
│   └── providers/
├── contentscript/     # 内容脚本（插件专用）
├── inpage/           # 注入DApp的脚本（插件专用）
├── shared/           # BG和UI公共部分
├── ui/               # UI代码
├── platform/
│   ├── extension/    # 插件打包入口
│   │   ├── background.js
│   │   └── ui.js
│   └── web/          # TG Wallet打包入口（新增）
│       ├── background.js
│       └── ui.js
└── locales/          # 多语言

8.2 构建方式 ​

• 使用 esbuild 构建
• Web 项目构建方式，支持多端输出
• 插件和 TG Miniapp 共用业务代码，仅入口和适配层不同

九、上线计划 ​

总结 ​

TG Miniapp 钱包的核心思路是复用现有插件钱包的业务逻辑，通过适配层抹平运行时差异，重点解决 DApp 交互（用标准 Connect 协议替代代码注入）和安全存储（利用 TG 生物识别 + PBKDF2 密钥衍生）两大问题。

架构完成后还可延伸为 WaaS 服务，为三方提供嵌入式钱包能力。