TonWeb锁仓合约实战：LockupWallet与VestingWallet安全配置教程

TonWeb锁仓合约实战：LockupWallet与VestingWallet安全配置教程

【免费下载链接】tonwebJavaScript SDK for TON (The Open Network)项目地址: https://gitcode.com/gh_mirrors/to/tonweb

TonWeb作为TON区块链的JavaScript SDK，提供了强大的锁仓合约功能，帮助用户安全管理数字资产。本文将详细介绍两种核心锁仓合约——LockupWalletV1和VestingWalletV1的安全配置方法，让您轻松掌握资产锁定与释放的全流程。

一、锁仓合约基础：保护资产的终极选择

锁仓合约是TON区块链生态中保护数字资产的重要工具，通过设置时间限制和访问控制，有效防止资产被误操作或恶意转移。TonWeb提供的锁仓合约主要分为两类：

• LockupWalletV1：支持地址白名单和多重权限控制的基础锁仓合约
• VestingWalletV1：具备时间梯度释放功能的高级 vesting 合约

这两类合约均继承自WalletContract，确保了与TON钱包生态的兼容性和安全性。

二、LockupWalletV1安全配置：三步实现基础锁仓

2.1 合约初始化必备参数

创建LockupWalletV1合约需要以下关键参数：

const wallet = new tonweb.lockupWallet.LockupWalletV1(provider, { publicKey:Uint8Array, // 公钥 wc:number, // 工作链ID config: { config_pubkey: string, // 配置公钥(base64编码) allowed_destinations: string // 允许的目标地址列表 } })

⚠️ 安全提示：确保config_pubkey和allowed_destinations参数正确配置，这是控制资产访问权限的核心

2.2 核心安全功能解析

LockupWalletV1提供三种关键余额查询方法，帮助用户实时掌握资产状态：

• getLiquidBalance()：获取可立即花费的余额
• getNominalRestrictedBalance()：获取受时间锁限制但可向白名单地址花费的余额
• getNominalLockedBalance()：获取完全受时间锁限制的余额

这些方法在LockupWalletV1.js中实现，通过智能合约状态查询确保准确性。

2.3 白名单地址管理

通过配置allowed_destinations参数，您可以限制资产只能转移到指定地址：

// 示例：配置允许的目标地址 const config = { config_pubkey: "base64-encoded-public-key", allowed_destinations: ["address1", "address2"] }

白名单机制是防止资产被盗的重要保障，建议定期审计和更新允许的地址列表。

三、VestingWalletV1高级配置：时间梯度释放的完美实现

3.1 理解Vesting合约的核心参数

VestingWalletV1提供更精细的时间控制功能，初始化时需要设置以下关键参数：

const vestingWallet = new tonweb.lockupWallet.VestingWalletV1(provider, { publicKey: Uint8Array, vestingStartTime: number, // vesting开始时间(UNIX时间戳) vestingTotalDuration: number, // 总vesting时长(秒) unlockPeriod: number, // 解锁周期(秒) cliffDuration: number, // 悬崖期时长(秒) vestingTotalAmount: BN, // 总vesting金额 vestingSenderAddress: Address, // 发送者地址 ownerAddress: Address // 所有者地址 })

这些参数在VestingWalletV1.js的构造函数中进行严格验证，确保参数有效性。

3.2 时间参数设置策略

设置vesting参数时需遵循以下规则：

1. unlockPeriod必须能整除vestingTotalDuration
2. cliffDuration必须小于vestingTotalDuration
3. cliffDuration必须是unlockPeriod的整数倍

示例配置：

• vestingTotalDuration: 31536000 (1年)
• unlockPeriod: 2592000 (30天)
• cliffDuration: 7776000 (90天)

这种配置将在90天悬崖期后，每30天解锁1/9的总金额。

3.3 高级功能：地址白名单管理

VestingWalletV1支持动态添加白名单地址，增强资产安全性：

// 创建添加白名单交易 const body = vestingWallet.createAddWhitelistBody({ addresses: [new Address("address1"), new Address("address2")], queryId: 123456 }) // 发送交易 await vestingWallet.sendTransaction(provider, { secretKey: secretKey, body: body })

通过createAddWhitelistBody方法，您可以灵活管理允许接收资产的地址列表。

四、安全最佳实践：保护您的锁仓资产

4.1 合约部署前的安全检查

1. 验证所有时间参数的合理性，避免设置过短或过长的锁仓周期
2. 双重检查公钥和地址的正确性，错误配置可能导致资产永久丢失
3. 在测试网充分测试合约功能，确认锁仓和释放逻辑符合预期

4.2 日常安全管理建议

• 定期通过getBalances()和getLockedAmount()检查合约状态
• 采用多签机制管理配置公钥，避免单点故障
• 记录并备份所有合约参数，特别是时间相关配置
• 监控合约事件，及时发现异常活动

4.3 紧急情况处理

如果发现可疑活动，应立即：

1. 检查并更新白名单地址
2. 确认合约当前锁定状态
3. 必要时通过紧急控制机制转移资产

五、快速开始：部署您的第一个锁仓合约

5.1 环境准备

首先克隆TonWeb仓库：

git clone https://gitcode.com/gh_mirrors/to/tonweb cd tonweb npm install

5.2 部署LockupWalletV1示例

const TonWeb = require("./src/index"); const tonweb = new TonWeb(); async function deployLockupWallet() { // 生成密钥对 const keyPair = TonWeb.utils.nacl.sign.keyPair(); // 创建合约实例 const lockupWallet = new tonweb.lockupWallet.LockupWalletV1(tonweb.provider, { publicKey: keyPair.publicKey, wc: 0, config: { config_pubkey: TonWeb.utils.bytesToBase64(keyPair.publicKey), allowed_destinations: [] } }); // 获取合约地址 const address = await lockupWallet.getAddress(); console.log("Lockup Wallet Address:", address.toString()); // 部署合约 (需要向该地址转入足够的TON) // ... } deployLockupWallet();

5.3 部署VestingWalletV1示例

类似地，您可以使用test-lockup.js中的测试代码作为参考，部署Vesting类型的锁仓合约。

六、总结：选择适合您的锁仓方案

TonWeb提供的LockupWalletV1和VestingWalletV1合约满足不同场景的资产锁定需求：

• LockupWalletV1：适合需要地址白名单控制的简单锁仓场景
• VestingWalletV1：适合需要时间梯度释放的复杂vesting计划

无论选择哪种合约，都应遵循最小权限原则，严格控制访问权限，并定期审计合约状态。通过TonWeb的锁仓合约，您可以安全、灵活地管理TON区块链上的数字资产，为长期投资策略提供有力保障。

想要了解更多细节，可以查看项目中的lockup目录源代码，或参考测试文件test-lockup.js中的示例实现。

【免费下载链接】tonwebJavaScript SDK for TON (The Open Network)项目地址: https://gitcode.com/gh_mirrors/to/tonweb