Vechain Foundation

We express our gratitude to the Vechain Foundation team for the collaborative engagement that enabled the execution of this Smart Contract Security Assessment.

The VeChain StarGate is a pivotal component of the Hayabusa phase within the broader VeChain Renaissance initiative. It is VeChain’s next-generation staking platform, designed to transform how users participate in the VeChainThor network. It introduces a novel approach by using NFTs as staking collateral, creating a dynamic and transparent framework for delegation, reward distribution, and governance.

The system users should acknowledge all the risks summed up in the risks section of the report

{Finding_Table?columns=title,severity,status&setting.filter.type=Vulnerability}

Documentation quality

• Public documentation clearly specify the functional requirements.

• Technical description is provided, the project runs well out-of-box.

Code quality

• The code considers best architectural practices, functionality is split in separate libraries.

• The role based access control is clear.

• The development environment is configured.

Test coverage

Code coverage of the project is 87.7% (branch coverage).

• Unit tests cover deployment and basic contract operations in mocked environment.

• Certain getters and permissioned functionality of StargateNFT contract is not covered with unit tests.

• Integration tests cover high-level operations such as staking and delegation in connection with Thor Solo node.

Stargate is a decentralized VET staking and delegation system on the VeChain blockchain that enables users to stake their VET tokens through NFTs and delegate them to validators to earn VTHO rewards. The system utilizes an NFT-based approach where each staking position is represented as a transferable ERC721 token, allowing users to participate in the VeChain PoA consensus mechanism while maintaining liquidity and flexibility of their staked assets.

The protocol implements a sophisticated delegation model with validator periods, reward distribution based on effective stake calculations, and comprehensive maturity and migration mechanisms for legacy node holders. The system is composed of several modular smart contracts working together to provide a complete staking infrastructure with upgradeability, access control, and pausability features.

Stargate.sol (Main Entry Point): The primary contract that orchestrates all staking, unstaking, delegation, and reward distribution operations. It serves as the main entry point for users and manages interactions with the VeChain Protocol Staker contract.

• Handles VET deposits and withdrawals

• Manages delegation lifecycle (initiate, exit, withdraw)

• Calculates and distributes VTHO rewards based on effective stake

• Tracks delegation periods and validator states

• Implements checkpointed effective stake tracking per validator

• Provides automatic reward claiming during unstake/redelegate operations

• Enforces maximum claimable period limits to prevent gas exhaustion

StargateProxy.sol (Proxy Pattern): A standard ERC1967 UUPS proxy contract that delegates all calls to the Stargate implementation. It follows OpenZeppelin's upgradeable proxy pattern and stores the implementation address using the EIP-1967 standard storage slot to avoid collision with the implementation's storage layout.

• Delegate calls to current Stargate implementation

• Store implementation address in EIP-1967 standard slot

• Support upgrades via UUPS pattern

StargateNFT.sol (NFT & Position Management): An ERC721 upgradeable contract that represents staking positions as NFTs. Each NFT corresponds to a specific level (tier) with associated VET requirements and reward multipliers.

• Mints NFTs when users stake (callable only by Stargate)

• Burns NFTs when users unstake (callable only by Stargate)

• Manages NFT levels, caps, and metadata

• Handles maturity periods for newly minted NFTs

• Supports migration from legacy VeChain X-Nodes and Eco Nodes

• Implements boost functionality to skip maturity periods

• Tracks token managers for delegation management

The system also uses a modular library approach to manage different aspects of the NFT functionality:

MintingLogic.sol: Implements the core minting logic for both regular staking and legacy node migration. Handles:

• VET amount validation for each level

• Circulating supply and cap checks

• Maturity period assignment

• Whitelist-based migration (V2 feature)

• Integration with legacy TokenAuction contract

Token.sol:  Manages individual token operations, including:

• Token data structure access

• Token state queries (maturity status, level, VET amount)

• Token validation and existence checks

TokenManager.sol: Handles the manager functionality where NFT owners can assign managers to their tokens:

• Manager assignment and removal

• Manager validation

• Automatic manager removal on token transfer

Levels.sol:  Manages NFT level configurations, including:

• Level metadata (VET requirements, reward multipliers, maturity periods, caps)

• Circulating supply tracking per level

• Historical supply checkpoints for analytics

• Level addition and updates

Settings.sol:  Provides administrative functions for contract configuration:

• Legacy nodes contract reference

• Stargate contract address management

• Whitelist entry management (V2)

• Base URI configuration for metadata

Clock.sol: Provides block-based timing functionality:

• Returns current block number as clock time

• Implements EIP-6372 clock mode for compatibility

• Used for maturity period calculations

DataTypes.sol: Defines all shared data structures used across the system:

• Token: Stores token-specific data (level, VET amount, mint time)

• Level: Defines level parameters (VET requirement, reward multiplier, maturity, cap)

• StargateNFTStorage: Main storage structure using EIP-7201 namespaced storage

• Whitelist entry structure for migration edge cases

Errors.sol:  Centralizes all custom error definitions for gas-efficient error handling, including:

• Staking-related errors

• Migration-related errors

• Access control errors

• State validation errors

Privileged Roles

The contracts use OpenZeppelin's AccessControlUpgradeable for role-based access control management. The following roles are defined:

Stargate Contract Roles

DEFAULT_ADMIN_ROLE can call:

• pause() - Pauses all staking, delegation, and reward operations

• unpause() - Resumes contract operations after pause

• setMaxClaimablePeriods() - Updates the maximum claimable periods limit (currently 832)

• Manage roles via grantRole() and revokeRole()

UPGRADER_ROLE can call:

• upgradeTo() / upgradeToAndCall() - Upgrades the contract implementation

onlyTokenOwner modifier for user-specific operations:

• unstake() - Only NFT owner can unstake

• delegate() - Only NFT owner can delegate

• requestDelegationExit() - Only NFT owner can request exit

StargateNFT Contract Roles

DEFAULT_ADMIN_ROLE can:

• Manage all other roles via grantRole() and revokeRole()

• Perform emergency administrative functions

• Migrate manager storage (V3 migration only)

UPGRADER_ROLE can:

• upgradeTo() / upgradeToAndCall() - Upgrades the contract implementation

PAUSER_ROLE can:

• pause() - Pauses NFT minting and transfers

• unpause() - Resumes NFT operations

LEVEL_OPERATOR_ROLE can:

• updateLevel() - Updates existing level parameters (VET requirement, rewards, maturity)

• updateLevelCap() - Updates the maximum supply cap for a level

• addLevel() - Adds new NFT levels to the system

MANAGER_ROLE can:

• Designated by the Stargate contract for specific delegation operations

• Managed per-token through the TokenManager library

Stargate Contract (special role):

• mint() - Mints new NFTs when users stake

• burn() - Burns NFTs when users unstake

• boostOnBehalfOf() - Skips maturity period for stakeAndDelegate()

The scope of the project includes the following smart contracts from the provided repository:

Assets in Scope