Back to Details

vechain-dev

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

VeChain Development Skill

VeChain开发技能

CRITICAL RULES

核心规则

  1. Read reference files FIRST. When the user's request involves any topic in the reference table below, read those files before doing anything else — before writing code, before making decisions. Briefly mention which files you are reading so the user can confirm the skill is active (e.g., "Reading VeChain Kit reference...").
  2. Information priority for VeChain topics: (a) Reference files in this skill — always the primary source. (b) VeChain MCP tools — use 
    @vechain/mcp-server
    for on-chain data, transaction building, and live network queries; use Kapa AI MCP for VeChain documentation lookups. (c) Web search — only as a last resort, and only for topics NOT covered in the reference files.
  3. Prefer working directly in the main conversation for VeChain tasks. Plan mode and subagents do not inherit skill context and may fall back to web search instead of using reference files.
  4. After compaction or context loss, re-read this SKILL.md to restore awareness of the reference table and operating procedure before continuing work.
  1. 优先阅读参考文件。当用户的请求涉及下方参考列表中的任意主题时，在执行任何操作前（编写代码、做决策前）先阅读对应文件。简单说明你正在阅读的文件，让用户确认技能已激活（例如："正在阅读VeChain Kit参考文档..."）。
  2. VeChain相关内容的信息优先级：(a) 本技能内置的参考文件——始终作为首要信息源。(b) VeChain MCP工具——使用
    @vechain/mcp-server
    获取链上数据、构建交易、查询实时网络状态；使用Kapa AI MCP查找VeChain文档。(c) 网页搜索——仅作为最后手段，且仅用于参考文件未覆盖的主题。
  3. VeChain相关任务优先直接在主会话中处理。计划模式和子Agent不会继承该技能上下文，可能会 fallback 到网页搜索而不使用参考文件。
  4. 上下文压缩或丢失后，继续工作前请重新阅读本SKILL.md，恢复对参考表和操作流程的认知。

Scope

适用范围

Use this Skill for any VeChain development task:
  • Frontend dApps (React/Next.js), wallet connection, social login
  • Transaction building, sending, confirmation UX
  • Solidity smart contracts on VeChainThor
  • Multi-clause transactions, fee delegation (VIP-191)
  • Testing with Hardhat + Thor Solo
  • Security reviews
  • VeBetterDAO / X2Earn apps, StarGate staking, governance
所有VeChain开发任务均可使用本技能：
  • 前端dApps（React/Next.js）、钱包连接、社交登录
  • 交易构建、发送、确认交互体验
  • VeChainThor上的Solidity智能合约
  • 多条款交易、费用委托（VIP-191）
  • 使用Hardhat + Thor Solo测试
  • 安全审计
  • VeBetterDAO / X2Earn应用、StarGate质押、治理

Default stack (opinionated)

推荐技术栈（约定式）

LayerDefaultAlternative
Frontend
@vechain/vechain-kit
@vechain/dapp-kit-react
(lightweight/non-React)
SDK
@vechain/sdk-core
+ 
@vechain/sdk-network
@vechain/sdk-ethers-adapter
ContractsSolidity + Hardhat + 
@vechain/sdk-hardhat-plugin
--
EVM target
paris
(mandatory)		--
TestingHardhat + Thor Solo (
--on-demand
)		--
TypesTypeChain (
@typechain/ethers-v6
)
@vechain/vechain-contract-types
(pre-built)
NodeNode 20 LTS (managed via 
nvm
)		--
层级默认选择替代方案
前端
@vechain/vechain-kit
@vechain/dapp-kit-react
（轻量/非React场景）
SDK
@vechain/sdk-core
+ 
@vechain/sdk-network
@vechain/sdk-ethers-adapter
合约Solidity + Hardhat + 
@vechain/sdk-hardhat-plugin
--
EVM目标版本
paris
（强制要求）		--
测试Hardhat + Thor Solo (
--on-demand
)		--
类型定义TypeChain (
@typechain/ethers-v6
)
@vechain/vechain-contract-types
（预构建）
Node版本Node 20 LTS（通过
nvm
管理）		--

Operating procedure

操作流程

1. Check Node version

1. 检查Node版本

Before installing dependencies or running any command:
  • Check if 
    .nvmrc
    exists in the project root. If yes, run 
    nvm use
    to switch to the required version.
  • If 
    .nvmrc
    does not exist, create one with 
    20
    (Node 20 LTS) and run 
    nvm use
    .
  • When adding dependencies that require a specific Node version, update 
    .nvmrc
    accordingly.
安装依赖或运行任何命令前：
  • 检查项目根目录是否存在
    .nvmrc
    ，如果有，运行
    nvm use
    切换到要求的版本。
  • 如果不存在
    .nvmrc
    ，创建一个内容为
    20
    的该文件（对应Node 20 LTS）并运行
    nvm use
    。
  • 添加需要特定Node版本的依赖时，对应更新
    .nvmrc
    。

2. Detect project structure

2. 识别项目结构

  • turbo.json
    present → follow Turborepo conventions (
    apps/frontend
    , 
    packages/contracts
    , 
    packages/*
    )
  • Use 
    useThor
    for Thor client access (both VeChain Kit and dapp-kit v2). 
    useConnex
    is deprecated everywhere.
  • Apply conditional patterns (Chakra UI, i18n, Zustand) only when the project uses them
  • 存在
    turbo.json
    →遵循Turborepo规范（
    apps/frontend
    、
    packages/contracts
    、
    packages/*
    ）
  • 访问Thor客户端使用
    useThor
    （VeChain Kit和dapp-kit v2均支持）。全场景下
    useConnex
    已废弃。
  • 仅当项目本身使用对应技术栈时，才应用条件模式（Chakra UI、i18n、Zustand）

3. Clarify before implementing

3. 实现前先明确需求

When the user's request is ambiguous or could be solved multiple ways, ask before building. Do not silently research alternatives and pick one. Separate research from implementation:
  • If the scope is unclear, ask the user to narrow it
  • If multiple architectures are viable, present trade-offs and let the user choose
  • Only proceed to implementation once the approach is agreed upon
当用户请求模糊或有多种实现方案时，开发前先询问确认。不要自行调研备选方案并选择其中一个，将调研和实现分离：
  • 如果范围不清晰，请求用户缩小范围
  • 如果有多个可行架构，展示优劣让用户选择
  • 仅在方案达成一致后再开始实现

4. Classify the task layer

4. 划分任务层级

UI/hooks → SDK/scripts → Smart contracts → Testing/CI → Infra
UI/钩子 → SDK/脚本 → 智能合约 → 测试/CI → 基础设施

5. Pick building blocks

5. 选择构建模块

  • UI (full-featured): VeChain Kit hooks + components
  • UI (lightweight/non-React): dapp-kit
  • Backend/scripts: 
    @vechain/sdk-core
    + 
    sdk-network
    directly
  • Legacy Connex present: migrate or isolate behind adapter boundary
When to ask the user: If the project doesn't already use VeChain Kit or dapp-kit and the user hasn't specified which to use, ask before choosing. Key questions:
  • Do you need social login (email, Google, passkey)? → VeChain Kit
  • Do you want pre-built UI modals and hooks (WalletButton, TransactionModal, token hooks)? → VeChain Kit
  • Do you want a lightweight wallet-only integration with minimal dependencies? → dapp-kit
  • Non-React framework? → dapp-kit
  • UI（全功能）：VeChain Kit钩子 + 组件
  • UI（轻量/非React）：dapp-kit
  • 后端/脚本：直接使用
    @vechain/sdk-core
    + 
    sdk-network
  • 存在旧版Connex：迁移或通过适配器层隔离
需要询问用户的场景：如果项目未使用VeChain Kit或dapp-kit，且用户未指定使用哪一个，选择前先询问。核心问题：
  • 是否需要社交登录（邮箱、Google、 passkey）？→ VeChain Kit
  • 是否需要预置UI弹窗和钩子（WalletButton、TransactionModal、通证钩子）？→ VeChain Kit
  • 是否需要最小依赖的轻量钱包集成？→ dapp-kit
  • 非React框架？→ dapp-kit

6. Implement with VeChain-specific correctness

6. 符合VeChain特定规范实现

  • Network: always explicit (
    mainnet
    /
    testnet
    /
    solo
    )
  • Gas: estimate first, use fee delegation where appropriate
  • Transactions: use multi-clause when batching benefits atomicity or UX
  • Tokens: VET for value, VTHO for gas (dual-token model)
  • Social login: Generic Delegator auto-enabled (users pay gas in VET/VTHO/B3TR); app-sponsored delegation optional for better UX; smart accounts; pre-fetch data before 
    sendTransaction
  • 网络：始终显式指定（
    mainnet
    /
    testnet
    /
    solo
    ）
  • Gas：先预估，合适场景下使用费用委托
  • 交易：批量操作需要原子性或优化体验时使用多条款交易
  • 通证：VET用于价值存储，VTHO用于支付Gas（双通证模型）
  • 社交登录：默认启用通用委托器（用户可用VET/VTHO/B3TR支付Gas）；可选应用赞助委托优化体验；支持智能账户；
    sendTransaction
    前预拉取数据

7. Test

7. 测试

  • Unit: Hardhat + Thor Solo
  • Integration: Thor Solo with realistic state
  • Wallet UX: mocked hook/provider tests
  • 单元测试：Hardhat + Thor Solo
  • 集成测试：使用真实状态的Thor Solo实例
  • 钱包交互体验：钩子/Provider mock测试

8. Verify and deliver

8. 验证与交付

A task is not complete until all applicable gates pass:
  1. Code compiles — no build errors (
    npm run build
    or equivalent succeeds)
  2. Tests pass — existing tests still pass; new logic has test coverage
  3. Risk notes documented — any signing, fee, or token-transfer implications are called out to the user
Then provide:
  • Files changed + diffs
  • Install/build/test commands
  • Risk notes for signing, fees, token transfers
所有适用检查项通过前，任务不算完成：
  1. 代码可编译——无构建错误（
    npm run build
    或等价命令执行成功）
  2. 测试通过——现有测试仍可通过；新逻辑有测试覆盖
  3. 风险说明文档齐全——所有签名、费用、通证转账相关影响都向用户明确说明
交付时提供：
  • 变更文件 + 差异内容
  • 安装/构建/测试命令
  • 签名、费用、通证转账相关风险说明

Reference files

参考文件

Read the matching files BEFORE doing anything else. See Critical Rules above.
TopicFileRead when user mentions...
Frontend patterns (shared)references/frontend.mdfrontend, React Query, caching, query keys, loading, skeleton, Turborepo, Chakra, i18n, state management
VeChain Kitreferences/frontend-vechain-kit.mdVeChain Kit, useWallet, useSendTransaction, useCallClause, WalletButton, TransactionModal, social login, Privy, smart accounts, account abstraction, theming
dapp-kitreferences/frontend-dappkit.mddapp-kit, DAppKitProvider, lightweight wallet
Legacy migrationreferences/sdk-migration.mdConnex, thor-devkit, migration, deprecated
Smart contractsreferences/smart-contracts.mdSolidity, Hardhat, ERC-20, ERC-721, deploy, contract interaction, libraries, contract size, upgradeable
Gas optimizationreferences/smart-contracts-optimization.mdgas, optimize, storage packing, assembly, unchecked
Testingreferences/testing.mdtest, Thor Solo, Docker, CI, fixtures
ABI / codegenreferences/abi-codegen.mdTypeChain, ABI, typechain-types, code generation
Fee delegationreferences/fee-delegation.mdgasless, sponsored, VIP-191, delegator, vechain.energy
Multi-clausereferences/multi-clause-transactions.mdbatch, multi-clause, atomic, multiple operations
Securityreferences/security.mdsecurity, audit, vulnerability, reentrancy, access control
VeBetterDAOreferences/vebetterdao.mdX2Earn, B3TR, sustainability, rewards, VeBetterDAO
StarGate stakingreferences/stargate-staking.mdstaking, StarGate, validator, delegation, VTHO rewards, node tier
Governancereferences/governance.mdVeVote, governance, voting, VOT3, proposal, steering committee
Reference linksreferences/resources.mddocs URL, npm link, GitHub repo
做任何操作前先阅读匹配的文件，参见上方核心规则。
主题文件用户提及以下内容时阅读
前端通用模式references/frontend.md前端、React Query、缓存、查询键、加载、骨架屏、Turborepo、Chakra、i18n、状态管理
VeChain Kitreferences/frontend-vechain-kit.mdVeChain Kit、useWallet、useSendTransaction、useCallClause、WalletButton、TransactionModal、社交登录、Privy、智能账户、账户抽象、主题定制
dapp-kitreferences/frontend-dappkit.mddapp-kit、DAppKitProvider、轻量钱包
旧版本迁移references/sdk-migration.mdConnex、thor-devkit、迁移、废弃
智能合约references/smart-contracts.mdSolidity、Hardhat、ERC-20、ERC-721、部署、合约交互、库、合约大小、可升级
Gas优化references/smart-contracts-optimization.mdgas、优化、存储打包、汇编、unchecked
测试references/testing.md测试、Thor Solo、Docker、CI、测试用例数据
ABI / 代码生成references/abi-codegen.mdTypeChain、ABI、typechain-types、代码生成
费用委托references/fee-delegation.mdgasless、赞助、VIP-191、委托器、vechain.energy
多条款交易references/multi-clause-transactions.md批量、多条款、原子性、多操作
安全references/security.md安全、审计、漏洞、重入、权限控制
VeBetterDAOreferences/vebetterdao.mdX2Earn、B3TR、可持续性、奖励、VeBetterDAO
StarGate质押references/stargate-staking.md质押、StarGate、验证节点、委托、VTHO奖励、节点等级
治理references/governance.mdVeVote、治理、投票、VOT3、提案、 steering committee
参考链接references/resources.md文档链接、npm链接、GitHub仓库