VeChain Development Skill

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.

Scope

• 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

Default stack (opinionated)

@vechain/vechain-kit

@vechain/dapp-kit-react

@vechain/sdk-core

@vechain/sdk-network

@vechain/sdk-ethers-adapter

@vechain/sdk-hardhat-plugin

paris

--on-demand

@typechain/ethers-v6

@vechain/vechain-contract-types

nvm

Operating procedure

1. Check Node version

• 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.

2. Detect project structure

• 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

3. Clarify before implementing

• 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

5. Pick building blocks

• 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

• 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

6. Implement with VeChain-specific correctness

• 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

7. Test

• Unit: Hardhat + Thor Solo
• Integration: Thor Solo with realistic state
• Wallet UX: mocked hook/provider tests

8. Verify and deliver

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

• Files changed + diffs
• Install/build/test commands
• Risk notes for signing, fees, token transfers

Reference files