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

# Token Contracts & Tokenomics

# Ramses Token Contracts and Emissions

## Token Stack

| Layer              | Contract                   | Purpose                                                |
| ------------------ | -------------------------- | ------------------------------------------------------ |
| **RAM**            | `Token.sol` + `Minter.sol` | Base emissions asset                                   |
| **xRAM**           | `XRam.sol`                 | Transfer-restricted governance token                   |
| **Voting power**   | `VoteModule.sol`           | Holds staked xRAM and exposes balances used by `Voter` |
| **Liquid wrapper** | `R33.sol`                  | ERC4626 vault that mints `hyperRAM` shares             |

## RAM and Minter

The supply schedule is enforced by `Minter.sol`.

### Contract-level constants

* `INITIAL_SUPPLY = 350_000_000e18`
* `MAX_SUPPLY = 1_000_000_000e18`
* `BASIS = 10_000`
* `MAX_DEVIATION = 2_500`

### Lifecycle

1. `kickoff()` sets the RAM, voter, and xRAM addresses and mints the initial supply to the operator.
2. `initEpoch0()` starts weekly period tracking and mints the configured epoch-0 emissions to the operator.
3. `updatePeriod()` advances weekly emissions when a new period starts.
4. `updatePeriodAndRebase()` advances the period and then calls xRAM's `rebase()`.

### Emissions multiplier

`updateEmissionsMultiplier()` is governance-controlled and cannot move by more than 25% in a single update. `calculateWeeklyEmissions()` also respects the global `MAX_SUPPLY`.

## xRAM

`XRam.sol` is the governance token contract.

### Conversion

```solidity theme={null}
function convertEmissionsToken(uint256 amount) external
```

This function:

1. Pulls `amount` RAM from the caller
2. Burns the configured slashing penalty
3. Mints `amount` xRAM to the caller

The current slashing penalty is set so that at least 50% of the incoming RAM is burned.

### Exit

```solidity theme={null}
function exit(uint256 amount) external returns (uint256 exitedAmount)
```

This burns xRAM and returns the post-penalty RAM amount to the caller, capped by the RAM currently held by the xRAM contract.

### Transfer restrictions

xRAM is not freely transferable. Transfers only succeed when the sender or receiver is exempt, or when the transfer is part of recognized gauge and fee-distributor flows.

### Governance controls

`AccessHub` can:

* Pause or unpause xRAM
* Manage exemption lists
* Move the xRAM operator
* Rescue non-RAM tokens from xRAM

## VoteModule

`VoteModule.sol` is where voting power actually lives.

### Core behavior

* Users deposit xRAM into `VoteModule`
* `VoteModule.balanceOf(user)` is the user's voting power
* `VoteModule.totalSupply()` is the total voting power in the system

### Delegation and admin permissions

* `delegate(address)` is used for voting-related permissions
* `setAdmin(address)` is used for broader owner-authorized operations such as fee claims

### Cooldown

`VoteModule` exposes:

* `cooldown()`
* `unlockTime()`
* `setCooldownExemption()`
* `setNewCooldown()`

Unless exempt, deposits and withdrawals require `block.timestamp >= unlockTime`.

## Voter and Weekly Periods

`Voter.sol` is the contract that ties voting, gauges, and emissions together.

### Weekly period model

The contracts use:

```solidity theme={null}
period = block.timestamp / 1 weeks
```

### Important consequence

Votes are written into the **next** period, not the current one.

That same next-period behavior also applies to:

* `FeeDistributor.notifyRewardAmount()`
* `FeeDistributor.incentivize()`

### Voting flow

```solidity theme={null}
function vote(address owner, address[] calldata pools, uint256[] calldata weights) external
```

`Voter` normalizes the supplied weights against the owner's current `VoteModule.balanceOf(owner)` and records the resulting allocations for the next weekly period.

### Maintenance flow

`Voter.distribute()`:

* Ensures emissions are up to date through `Minter`
* Routes emissions into gauges
* Collects CL protocol fees through `FeeCollector`
* Preserves or updates fee-split behavior depending on gauge status

## Fee Routing and Incentives

Two contracts matter most here: `FeeCollector.sol` and `FeeDistributor.sol`.

### FeeCollector

For CL pools, `FeeCollector`:

1. Reads accrued protocol fees from the pool
2. Sends a treasury portion according to `treasuryFees`
3. Routes the remainder into the pool's `FeeDistributor`

If a pool has no active gauge, the fees go directly to the treasury.

### FeeDistributor

Each fee distributor tracks:

* Vote balances per owner address
* Reward supply per token and per period
* Claimed amounts per owner, token, and period

Rewards can enter a fee distributor in two ways:

* `notifyRewardAmount()` for routed protocol fees
* `incentivize()` for vote incentives and bribes

Claims are keyed by **owner address**, not by NFT token ID.

## R33 / hyperRAM

`R33.sol` is an ERC4626 vault that wraps xRAM exposure.

### Naming

* Source contract name: `R33`
* Token name: `xRAM Liquid Staking Token`
* Token symbol: `hyperRAM`

### Core behavior

* Deposits pull xRAM from the user
* The vault immediately deposits that xRAM into `VoteModule`
* Vault shares are freely transferable
* `totalAssets()` reflects the vault's staked xRAM balance in `VoteModule`

### Operator actions

The vault operator can:

* `submitVotes()`
* `claimIncentives()`
* `swapIncentiveViaAggregator()`
* `compound()`
* `unlock()`

### Locking

Deposits require `isUnlocked()`, which means:

* The current period has been unlocked
* The system is not within one hour of the next weekly period

Withdrawals and redeems do not use that same vault lock, but they still depend on `VoteModule.withdraw()` succeeding.

## Additional Resources

* [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)
* [Ramses V3 Contracts Repository](https://github.com/RamsesExchange/ramses-v3-contracts)