Stargate

StarGate 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 StarGate staking 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

Use this Skill for StarGate staking development:

• NFT-based staking platform integration
• Tiered staking and rewards
• Validator system and delegation
• Node Manager features
• Boosting mechanics
• Phase 2 breaking changes

Operating procedure

1. Clarify before implementing

When the user's request is ambiguous, ask before building. Key questions:

• Which staking tier or node level?
• Mainnet or testnet?
• Phase 1 or Phase 2 contract interfaces?

2. Implement with VeChain-specific correctness

• Network: always explicit (mainnet/testnet/solo)
• Tokens: VET for staking, VTHO for rewards
• Use correct contract addresses for the target network

3. Verify and deliver

A task is not complete until all applicable gates pass:

1. Code compiles — no build errors 2. Tests pass — existing tests still pass; new logic has test coverage 3. Risk notes documented — any staking or delegation implications are called out

Reference files

Read the matching files BEFORE doing anything else. See Critical Rules above.

StarGate Smart Contracts

When to use

Use when the user asks about:

• Stargate contract functions, roles, or architecture
• StargateNFT minting, burning, boosting, maturity, token managers
• ProtocolStaker delegation and validator interactions
• Delegation status, rewards claiming, effective stake
• Contract integration for staking flows

Contract Map

User
 │
 ▼
Stargate (main entry point)
 ├──► StargateNFT (ERC721 — mint/burn NFTs, maturity, boost, managers)
 └──► ProtocolStaker (protocol-level — validator/delegation VET deposits)

• Stargate orchestrates all user actions: stake, unstake, delegate, claim rewards
• StargateNFT is the ERC721 contract representing staking positions; mint/burn only callable by Stargate
• ProtocolStaker is the on-chain protocol contract managing validator stakes and delegation deposits

Stargate

Main entry point for staking, delegation, and reward distribution. Upgradeable, pausable, access-controlled.

Key Types

enum DelegationStatus { NONE, PENDING, ACTIVE, EXITED }

struct Delegation {
    uint256 delegationId;
    address validator;
    uint256 stake;
    uint8   probabilityMultiplier;
    uint32  startPeriod;
    uint32  endPeriod;
    bool    isLocked;
    DelegationStatus status;
}

• NONE: no delegation exists
• PENDING: delegated but waiting for validator's next period to activate
• ACTIVE: earning rewards; stays ACTIVE even after requesting exit (until period ends)
• EXITED: delegation ended (user exited, validator exited, or pending delegation cancelled)

Key Functions

Staking

Delegation

Rewards

Rewards edge cases: claimRewards loops over periods and can run out of gas if >832 periods are unclaimed. Use maxClaimablePeriods (default 832) and call multiple times or use multi-clause transactions to claim before unstaking/re-delegating.

Query

Admin

Roles

Important Details

• Delegation activates at the next validator period, not immediately
• While PENDING, users can re-delegate to a different validator or cancel
• Once ACTIVE, requestDelegationExit is the only way out (irreversible, waits for period end)
• unstake and delegate auto-claim pending rewards
• VET flows: on delegate, VET moves from StargateNFT → ProtocolStaker; on exit, back through Stargate
• Probability multipliers: PROB_MULTIPLIER_NODE (Eco tiers) and PROB_MULTIPLIER_X_NODE (X tiers)
• Periods are validator-specific and numbered incrementally (not fixed duration)

Key Events

Key Errors

---

StargateNFT

ERC721 upgradeable contract representing staking positions. Mint/burn only callable by Stargate. Handles maturity periods, boosting, token managers, and level management.

Key Functions

Minting / Burning (Stargate-only)

Maturity & Boosting

Token Manager (Node Manager)

Managers can vote on VeVote and use the token in governance, but cannot claim rewards, transfer, delegate, or unstake. Manager is removed on transfer.

Token & Level Queries

Level Management

X Token Queries

Roles

Important Details

• NFTs are always transferable, even when delegated (changed in V3)
• Transfer removes the token manager automatically
• VET amount tracked in StargateNFT contract (legacy from pre-Hayabusa, kept to avoid migration complexity)
• Migrated legacy nodes have no maturity period
• No upgrade/downgrade: once minted at a level, it stays at that level
• Users must deposit exact VET amount for the tier (no more, no less)
• V3 removed all VTHO generation logic (Hayabusa changed VTHO to require active delegation)
• REWARD_MULTIPLIER_SCALING_FACTOR: scaling factor for reward multiplier calculations

---

ProtocolStaker (IProtocolStaker)

Protocol-level interface for validator staking and delegation. The Stargate contract interacts with this to manage VET deposits.

Validator Functions

Delegation Functions

Query Functions

StarGate (NFT-Based Staking & Delegation)

When to use

Use when the user asks about:

• Staking VET on VeChain
• StarGate NFTs and node tiers
• Validator delegation
• VTHO rewards from staking
• Boosting NFT maturity
• VeChain node management
• Legacy X Node or Economic Node migration

Important: VeChain StarGate is NOT a cross-chain bridge. It is VeChain's NFT-based staking platform launched as part of the Hayabusa phase (July 2025).

What is StarGate?

StarGate is VeChain's staking protocol that replaces the legacy node structure with an NFT-based staking and delegation framework. Staked VET positions are represented as tradable ERC721 NFTs, enabling secondary market liquidity while preserving staking rewards.

Key Features

• Minimum entry: 10,000 VET (Dawn tier)
• Liquid staking: NFTs are tradable on VeChain-based marketplaces
• Validator delegation: Delegate to validators and earn VTHO proportional to block production
• On-chain governance: NFTs serve as voting instruments for VeVote governance
• Fully on-chain: All staking logic is transparent and verifiable

VTHO Generation Change

Under StarGate, base VTHO rewards (generated passively by holding VET) no longer exist. VTHO can only be generated by actively delegating to a validator.

Staking Lifecycle

1. Stake: Select a node tier and lock the exact required VET. Protocol mints an NFT. 2. Maturity Period: Each NFT has a maturity countdown (2 to 90 days by tier). During maturity, the NFT cannot be delegated. Optionally boost (pay VTHO) to instantly mature. 3. Delegation: Once mature, delegate to a chosen validator. Delegation activates at the validator's next period. 4. Reward Accumulation: Delegated validator mines blocks; VTHO rewards are distributed to delegators weighted by tier multiplier. 5. Claiming: Rewards claimable at end of each validator period. 6. Unstaking: Burns NFT and returns staked VET. Only possible with no active delegation.

NFT Tiers

X Category (Limited Supply -- from legacy X Node migration)

Eco Category (Open to all)

Validator System

• Validators stake minimum 25 million VET
• Choose validation period of 7, 15, or 30 days
• Block selection probability proportional to own stake + delegated VET
• Validators receive block rewards + 100% of transaction priority fees
• Validators offline for 7+ consecutive days are forcibly removed

Smart Contract Architecture

Two primary contracts:

1. Stargate.sol -- Main entry point. Orchestrates staking, unstaking, delegation, and reward distribution. 2. StargateNFT.sol -- ERC721 upgradeable contract representing staking positions as NFTs.

Contract Addresses

Testnet

Mainnet addresses available at docs.stargate.vechain.org/for-developers/contracts.

Key API Functions

Staking

// Stake VET and mint an NFT
// _levelId specifies the tier (e.g., Dawn, Lightning, etc.)
// Requires exact VET amount as transaction value
await stargate.transact.stake(levelId, { value: requiredVET });

// Stake + immediately delegate (requires maturity or boost)
await stargate.transact.stakeAndDelegate(levelId, validatorId, { value: requiredVET });

// Combined: stake + boost (instant maturity, costs VTHO) + delegate
await stargate.transact.stakeAndBoostAndDelegate(levelId, validatorId, { value: requiredVET });

Delegation

// Delegate an NFT to a validator (active at validator's next period)
await stargate.transact.delegate(tokenId, validatorId);

// Remove delegation
await stargate.transact.undelegate(tokenId);

Rewards

// Claim accumulated VTHO rewards
await stargate.transact.claimRewards(tokenId);

// For multiple NFTs, use multi-clause transactions
const clauses = tokenIds.map(id => ({
    to: stargateAddress,
    value: '0x0',
    data: ABIContract.encodeFunctionInput(stargateABI, 'claimRewards', [id]),
}));

// Check accrued rewards (current period, not yet claimable)
const accrued = await stargate.call.getAccruedRewards(tokenId);

Unstaking

// Burns NFT, returns staked VET, auto-claims remaining rewards
// Only possible when no active delegation exists
await stargate.transact.unstake(tokenId);

Boosting

// Instantly mature an NFT by paying VTHO fee
// IMPORTANT: Approve VTHO spending on StargateNFT contract first
await vthoContract.transact.approve(stargateNFTAddress, boostFee);
await stargate.transact.boost(tokenId);

Critical: VTHO approval must be granted to the StargateNFT contract (not the Stargate contract) before boosting.

Phase 2 Breaking Changes

In Phase 2, delegation requires maturity to have elapsed first. The combined stakeAndBoostAndDelegate flow (paying VTHO for instant boost) is the only way to bypass the maturity waiting period.

Node Manager

NFT owners can assign a Node Manager (secondary wallet) with limited operational privileges (e.g., voting on VeVote) without transferring ownership of the NFT.

Developer Resources

• Documentation: docs.stargate.vechain.org
• GitHub: github.com/vechain/stargate-contracts
• StarGate dApp: app.stargate.vechain.org
• API Reference: docs.stargate.vechain.org/for-developers/api

Security

StarGate contracts have undergone:

• Hacken Audit (October 2025) -- strong code quality, role-based access control
• Trail of Bits Audit
• Immunefi Audit Competition (up to $40,000 in rewards)
• HackenProof DualDefense Contests ($36,000 and $50,000)