> ## 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.

# Overview

# 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](https://github.com/RamsesExchange/ramses-v3-contracts). 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](./reference/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:

```solidity theme={null}
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](https://diligence.security/audits/2024/08/ramses-v3/)
* **Cantina / Spearbit**: Independent security review
  * [View on Cantina](https://cantina.xyz/portfolio/ramses-exchange)
* **Code4rena** (October 2024): \$120,000 audit competition
  * 2 medium severity findings, all resolved
  * [View Report](https://code4rena.com/reports/2024-10-ramses-exchange)

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](../../concepts/ramses-protocol).

Then set up your [local environment](./guides/local-environment) and walk through a [first swap](./guides/swaps/single-swaps).

# Reference

For a deeper dive, read the [technical reference](./reference/overview).

# Resources

* [**Ramses V3 Contracts**](https://github.com/RamsesExchange/ramses-v3-contracts) - Main repository
* [**ConsenSys Diligence Audit**](https://diligence.security/audits/2024/08/ramses-v3/)
* [**Cantina / Spearbit Audit**](https://cantina.xyz/portfolio/ramses-exchange)
* [**Code4rena Audit Report**](https://code4rena.com/reports/2024-10-ramses-exchange)
* [**Uniswap V3 Core**](https://github.com/Uniswap/v3-core) - Reference implementation for concentrated-liquidity mechanics