Skip to main content

Documentation Index

Fetch the complete documentation index at: https://tech.ramses.xyz/llms.txt

Use this file to discover all available pages before exploring further.

​
The Ramses Smart Contracts

Welcome to the Ramses contract documentation. The source of truth for the material in this section is the current Ramses Solidity implementation in the Ramses V3 contracts repository. Ramses builds on Uniswap V3-style concentrated liquidity, then adds weekly accounting, gauge-directed emissions, fee routing, and a separate governance stack built around xRAM, VoteModule, Voter, and AccessHub.

​
What Makes Ramses Different

​
Compiler

Ramses V3 contracts are compiled with Solidity ^0.8.0 using via-ir (the Yul-based intermediate representation pipeline). This is a significant departure from upstream Uniswap V3, which targets Solidity 0.7.6 without via-ir. Key implications:
  • Custom errors replace string revert messages across most of the protocol (see Error Codes)
  • Overflow checks are built into the compiler — explicit SafeMath wrappers are no longer needed
  • via-ir optimization enables cross-function inlining and stack-depth relief, allowing the contracts to compile with deeper call stacks and more complex internal logic than the legacy pipeline permits

​
1. Period-based accounting for CL rewards

Ramses V3 pools track weekly liquidity participation so gauges can reward positions based on time spent in range during each period. This is the main on-chain difference from a plain Uniswap V3 deployment.

​
2. Non-custodial CL gauges

GaugeV3 rewards are tied to CL pool positions without moving the underlying pool liquidity into a separate staking contract. The surrounding periphery and voter contracts coordinate eligibility and claims.

​
3. Address-based governance, not veNFT voting

Governance in the current contracts is address-based:
  • XRam.sol creates transfer-restricted xRAM
  • VoteModule.sol holds staked xRAM and exposes voting power
  • Voter.sol records votes by owner address for the next weekly period
  • FeeDistributor.sol pays rewards to those addresses based on periodized vote weight

​
4. Centralized governance routing through AccessHub

AccessHub.sol is the operational control plane for the protocol. It owns batch fee updates, gauge lifecycle management, xRAM/R33 administration, treasury settings, and other protocol-wide actions through roles, multisig-only functions, and timelock-only functions.

​
5. Liquid governance wrapper

R33.sol is an ERC4626 vault that wraps xRAM exposure. The source contract is named R33, while the token it mints is hyperRAM (xRAM Liquid Staking Token in the constructor). It stakes the underlying xRAM into VoteModule, allows an operator to vote and compound, and exposes a liquid ERC20 share token.

​
Contract Layout

​
Concentrated liquidity

Core contracts:
  • RamsesV3Factory: Pool creation, fee configuration, fee collector wiring, and voter integration
  • RamsesV3Pool: Swaps, liquidity management, oracle state, protocol fee accrual, and weekly accounting
  • RamsesV3PoolDeployer: Factory helper used to deploy pool instances
Periphery contracts:
  • RamsesV3PositionManager: NFT position management and reward-claim integrations
  • SwapRouter: Single-hop and multi-hop swap execution
  • Quoter / QuoterV2 / TickLens: Read-oriented helpers

​
Gauges and fee routing

Gauge contracts:
  • GaugeV3: CL reward distribution
  • ClGaugeFactory: Gauge deployment and implementation management
  • FeeCollector: Collects protocol fees from CL pools and routes them to treasury and fee distributors
Reward distribution contracts:
  • FeeDistributor: Tracks vote weight per period and distributes fee/incentive tokens to voter addresses

​
Governance and token stack

  • AccessHub: Role-based and multisig/timelock governance router
  • Voter: Vote accounting, gauge registry, emissions routing, reward claims
  • VoteModule: xRAM staking, delegation, admin permissions, cooldown management
  • Minter: Weekly emission controller with a capped supply schedule
  • XRam: Transfer-restricted governance token with conversion and exit penalties
  • R33 / hyperRAM: ERC4626 liquid wrapper over xRAM staked in VoteModule
  • AutoVault: Optional xRAM automation layer for reward conversion and delegated voting

​
Weekly Period Model

The contracts use: 
period = block.timestamp / 1 weeks
Key consequences of that model:
  1. Voter.vote() writes allocations into the next period.
  2. FeeDistributor.notifyRewardAmount() and incentivize() also queue rewards into the next period.
  3. Minter.updatePeriod() advances emissions when a new weekly period has started.
  4. Voter.distribute() ties together emissions distribution and protocol-fee routing for gauges.
  5. VoteModule cooldowns and R33 unlock windows are also expressed around this weekly cadence.

​
Code Audit Status

Ramses V3 has undergone multiple professional security audits:
  • ConsenSys Diligence (August 2024): 10 contracts, 2,250 nSLOC
    • Focus on period-based accounting system
    • Critical findings addressed in final implementation
    • View Report
  • Cantina / Spearbit: Independent security review
  • Code4rena (October 2024): $120,000 audit competition
The period-accounting and reward-routing stack requires special attention to:
  • Tick and position boundary edge cases
  • Weekly period transitions
  • Reward accounting across gauges and fee distributors
  • Fee routing across treasury, fee collectors, and active gauges

​
Guides

If you are new to Ramses, start with the protocol concepts. Then set up your local environment and walk through a first swap.

​
Reference

For a deeper dive, read the technical reference.

​
Resources