Virtual Protocol's contracts split one governance lifecycle across thirteen Solidity contracts, five of them upgradeable

The table marks five contracts upgradeable and four role-gated

Everything the project does is summarised in one table with three columns: contract, purpose, access control, and whether it is upgradable. Thirteen contracts are listed. Five are marked upgradable, and they are the ones that hold state about the ecosystem rather than a single token: AgentFactory, AgentNft, ContributionNft, ServiceNft and AgentReward. The remaining eight are fixed, among them veVirtualToken, VirtualProtocolDAO, VirtualGenesisDAO, AgentToken, AgentDAO, TimeLockStaking, Virtual and Airdrop. Access control is split three ways rather than two. Two contracts, veVirtualToken and Virtual, are marked Ownable. Four carry named roles, and the split matters: AgentFactory holds DEFAULT_ADMIN_ROLE and WITHDRAW_ROLE, AgentNft holds DEFAULT_ADMIN_ROLE, VALIDATOR_ADMIN_ROLE and MINTER_ROLE, and both AgentReward and TimeLockStaking hold GOV_ROLE and TOKEN_SAVER_ROLE.

Genesis clones two implementations and mints the registry NFT

The VIRTUAL Genesis flow is the entry point to the whole system and it is five steps with a fixed order. An application is submitted at AgentFactory, and submitting transfers VIRTUAL to AgentFactory. The application is then proposed at VirtualGenesisDAO, with the action named VirtualFactory.executeApplication, voting starts there, and the proposal is executed there. Execution is where the machinery appears: it clones AgentToken, clones AgentDAO, mints AgentNft, stakes VIRTUAL into $PERSONA depending on the symbol sent with the application, and creates the TBA registry entry with AgentNft. The Genesis DAO is described as allowing early execution of a proposal as soon as a quorum of 10k votes is reached, so it is not a proposal body that waits for a fixed timetable. Everything a VIRTUAL needs is created in that one execution.

Two NFTs separate a proposed contribution from an accepted service

Contribution and service are different objects with different permissions, and the table explains why. Each contribution mints its own ContributionNft, and anyone can propose a new contribution at the VIRTUAL DAO and mint the token using the proposal id, with the mint authenticating that the sender is the proposal's proposer. An accepted contribution mints a ServiceNft instead, and that one is restricted: only the VIRTUAL DAO can mint a ServiceNft. Users can query the latest service NFT for a VIRTUAL CORE. So the contribution step is an open intake with a proposer check, and the service step is a closed registry written by governance. Upgrading a core runs through the second of the two: validators vote for a contribution proposal at AgentDAO, and executing that proposal mints a ServiceNft and updates the maturity score and the VIRTUAL core service id.

AgentNft is a registry and a wallet address generator at once

AgentNft carries more responsibility than its name suggests. It is the main registry for Persona, Core and Validator, three kinds of thing that have to be enumerated somewhere on chain, and it is also used to generate ICV wallet addresses. That combination is what makes it upgradeable: a registry whose entries are referenced by other contracts is expensive to redesign, and the maturity score and core service id that the upgrade flow writes are the sort of bookkeeping that tends to need changing. The access control reflects the same weight, since it is the only contract in the table holding three roles at once, DEFAULT_ADMIN_ROLE, VALIDATOR_ADMIN_ROLE and MINTER_ROLE. Persona and Validator records are what the staking and reward flows address when they distribute to validators and contributors, so this is the contract that ties identity in the table to money movement in the flows.

One reward contract splits daily profit five ways

Distribution is described as two steps that bracket a daily cycle. On a daily basis the protocol backend concludes the day's profits into a single amount, then calls AgentReward.distributeRewards. That call transfers VIRTUAL into AgentReward and accounts and updates the claimable amounts for five parties: the Protocol, Stakers, Validators, Dataset Contributors and Model Contributors. Withdrawing is split by role, and the split is not symmetric. The protocol calls AgentReward.withdrawProtocolRewards, while Stakers, Validators, Dataset Contributors and Model Contributors each call AgentReward.claimAllRewards. The distinction suggests the protocol's share is accounted separately from the participants' shares, with the claimAllRewards name covering everything accrued to that caller rather than one line item.

Staking mints $PERSONA and burns it on the way back

Staking is a two-call round trip through the implementation contract AgentToken, which AgentFactory clones during VIRTUAL instantiation. Calling AgentToken.stake passes in the validator you want to delegate your voting power to, and the call takes in sVIRTUAL and mints $PERSONA to you. Calling AgentToken.withdraw reverses it, burning your $PERSONA and returning the sVIRTUAL. So the stake is delegated, not anonymous: the validator is named at stake time and the reward flow later pays validators as a category of their own. The mapping between the two names is set at genesis, where staking VIRTUAL turns into $PERSONA depending on the symbol sent with the application. TimeLockStaking is the separate contract that lets a user stake VIRTUAL in exchange for sVIRTUAL, with GOV_ROLE and TOKEN_SAVER_ROLE and no upgrade path, and AgentToken notes that the staked token is non-transferable.

package.json still points at another organisation and its test script errors out

The manifest has not been caught up with the repository's current home. It is named virtual-contracts at version 1.0.0, its repository URL is git+https://github.com/PathDAO/virtual-contracts.git, and its homepage field points at the same organisation's readme, while the repository itself lives under Virtual-Protocol as protocol-contracts. It declares ISC as the licence, and the repository itself records no licence at all. Two script fields are worth reading closely. postinstall runs patch-package, which is consistent with the patches directory in the tree and means the build applies local patches to dependencies after every install. test is the untouched npm stub, the command that echoes Error: no test specified and exits 1, so there is no test entry point to call even though the tree contains a test directory and solidity-coverage is a dependency.

Hardhat 2.23.0 with OpenZeppelin upgrades and two verification plugins

The toolchain explains what kind of project this is. Hardhat is pinned at 2.23.0 with hardhat-deploy, hardhat-verify and an OKX explorer verification plugin, alongside typechain, ts-node and typescript, plus gas reporting, contract sizing and coverage, so this is a tested and deployed codebase rather than a sketch. The dependency set is more telling: OpenZeppelin contracts at 5.0.0 with the upgradeable variant and the upgrades plugin, which is what makes the five upgradable entries in the table possible, the account abstraction contracts, and the Uniswap v2 core and periphery plus v3 core, the latter with v2-periphery still at a beta version. Both yarn.lock and package-lock.json sit in the tree, so two lockfiles are present for the same project. The last push to main is dated 2026-09-23, the repository is not archived, there are no GitHub releases, and it reports 101 stars, 62 forks and 8 open issues.

Editorial conclusion

Read this repository as a specification rather than as a library to install: the README is a lifecycle in five flows, and the contract table tells you which pieces of that lifecycle can be replaced after deployment and which are fixed. The upgradeable set is the interesting half, since it is the factory, the two NFT registries and the reward distributor, while the token, the DAOs and the staking contract are not. Two cautions before you build against it. The manifest still identifies itself as virtual-contracts with repository and homepage URLs under a different organisation, and its test script is the untouched stub that exits with an error, so there is no published test entry point to lean on even though the tree carries a test directory and a coverage tool. And the repository records no licence, while package.json says ISC, which is a gap to resolve with the authors rather than to interpret.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository