> For the complete documentation index, see [llms.txt](https://docs.vevote.vechain.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.vevote.vechain.org/for-developers/editor.md).

# Smart Contracts

## VeVote Smart Contracts Documentation

This document provides a technical summary of the smart contracts that make up the VeVote governance system. It explains the architecture, roles, upgrade mechanics, use of libraries, and how contracts interact with external components.

***

### Contract Architecture

VeVote is designed as a modular system using the **UUPS proxy pattern**, which separates contract logic from storage. This allows logic to be upgraded while preserving state.

#### Core Contracts

| Contract     | Purpose                                                                                            |
| ------------ | -------------------------------------------------------------------------------------------------- |
| `VeVote.sol` | VeVote system smart contract, routes proposal and voting calls, handles access control and storage |

> This contract define the high-level behavior and state management of the system. All logic is offloaded to libraries.

***

### Libraries in VeVote

VeVote.sol uses a set of specialized **library contracts** to keep the logic modular, testable, and upgradable without increasing the size of the main contract. These libraries are stateless and rely on a shared storage layout defined in `VeVoteStorage.sol`.

#### Why Libraries?

* **Modularity** – Each library focuses on a single area of functionality (e.g. voting, timing)
* **Gas Efficiency** – Smaller contract size reduces deployment and interaction costs
* **Upgrade Flexibility** – Allows logic updates without touching unrelated modules
* **Reusability** – Logic can be reused across governance versions

#### Core Logic Libraries

| Library Contract          | Responsibility                                                                       |
| ------------------------- | ------------------------------------------------------------------------------------ |
| `VeVoteVoteLogic.sol`     | **Voting logic**: casting, tallying, validation                                      |
| `VeVoteProposalLogic.sol` | **Proposal creation**: input validation, role checks, setup                          |
| `VeVoteQuorumLogic.sol`   | Quorum calculation and pass/fail logic                                               |
| `VeVoteClockLogic.sol`    | Time-related logic                                                                   |
| `VeVoteConfigurator.sol`  | **Admin-only config updates**: vote durations, multipliers, external contracts, etc. |

> 📌 These libraries are called via delegatecall from `VeVote.sol`, and all read/write operations interact with `VeVoteStorage.sol`.

***

### Roles & Access Control

VeVote uses OpenZeppelin's `AccessControlUpgradeable` to manage permissions.

| Role                       | Capability                                                     |
| -------------------------- | -------------------------------------------------------------- |
| `DEFAULT_ADMIN_ROLE`       | Full control: manage roles and governance parameters           |
| `UPGRADER_ROLE`            | Grants ability to upgrade logic contracts via proxy            |
| `WHITELISTED_ROLE`         | Can submit proposals to the VeVote system                      |
| `SETTINGS_MANAGER_ROLE`    | Manages contract configurations                                |
| `EXECUTOR_ROLE`            | Can mark proposals as executed, as execution happens off-chain |
| `NODE_WEIGHT_MANAGER_ROLE` | Can update parameters of the vote weighting formula            |

***

### Upgradeability

VeVote supports upgradeability through the **UUPS Proxy Pattern**:

* The **proxy contract** holds all persistent data
* **Logic contracts (libraries)** are called via delegatecall
* **`VeVoteStorage.sol`** defines a stable layout to prevent storage collisions

> 🔄 Logic can be upgraded module-by-module without resetting or migrating data.

***

### External Integrations

| External Contract | Purpose                                                                                                                            |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `StargateNFT.sol` | Core Stargate NFT staking contract. Stores level info, VET stake, and token management information used to calculate voting power. |
| `Staker.sol`      | VeChain’s Proof of Stake registry. Used to check if a voter is an endorser of an VeChainThor Validator.                            |

***

### Deployed Addresses

This section will list the deployed VeVote contract addresses by network.

<table><thead><tr><th width="250.953125">Contract</th><th>Address</th></tr></thead><tbody><tr><td><code>VeVote.sol</code></td><td><code>0x7d812e8e544bb0c7898ea656b70173e7ef426b4c</code></td></tr></tbody></table>

<table><thead><tr><th width="251.78125">Library</th><th>Address</th></tr></thead><tbody><tr><td><code>VeVoteVoteLogic.sol</code></td><td><code>0xc1e1c32d98e1e63983dea48b0b4ca4375b5cb582</code></td></tr><tr><td><code>VeVoteQuorumLogic.sol</code></td><td><code>0xefadb7b6ba6cccf0ae15b54bb3d05e748dee611a</code></td></tr><tr><td><code>VeVoteProposalLogic.sol</code></td><td><code>0x6fdc53583570a3ef6f8ff647ef4785883998a2e9</code></td></tr><tr><td><code>VeVoteConfigurator.sol</code></td><td><code>0xb47de033fec4e3ef1f5f5b79a42be469173b6357</code></td></tr><tr><td><code>VeVoteStateLogic.sol</code></td><td><code>0x716c552490c3e4ddb68fab8b5dd1f1e9d115916f</code></td></tr></tbody></table>