> For the complete documentation index, see [llms.txt](https://docs.useicaria.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.useicaria.xyz/architecture/smart-contracts.md).

# Smart contracts

Every contract in the protocol, the single thing it does, and whether it can ever change.

Keeping the contract set small was a decision, not an accident. One job per contract, logic that cannot be altered within a version, and anything adjustable held in `ParamController` behind the timelock.

## The set

| Contract                       | Job                                                                                                              | Mutability                                           |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| `SwapRouter`                   | The trader's only way in: eligibility, venue choice, two-leg assembly, and enforcement of the band and the bound | Immutable                                            |
| `AnchorVault` (one per market) | Carries inventory, quotes around the mid, mints and burns LP shares                                              | Immutable, with parameters in `ParamController`      |
| `VaultFactory`                 | Puts vaults on-chain from listed configurations                                                                  | Immutable                                            |
| `RfqSettlement`                | Checks maker EIP-712 quotes and settles them in one piece                                                        | Immutable                                            |
| `OracleRouter`                 | The one door a price comes through: Chainlink adapters, guards, and session and regime state                     | Immutable, with adapters in `ParamController`        |
| `EligibilityRegistry`          | The one door permission comes through, checking roles against attestations                                       | Immutable, with policy adapters in `ParamController` |
| `ParamController`              | Where every tunable value lives, behind the timelock                                                             | Timelocked writes, public reads                      |
| `FeeCollector`                 | Accumulates protocol fees                                                                                        | Immutable                                            |
| `Guardian`                     | Halts quoting and settlement during an incident                                                                  | Halting only; cannot move funds or stop withdrawals  |

## The interfaces an integrator needs

```solidity
// SwapRouter: the single call a trader makes
function swap(SwapParams calldata p) external returns (uint256 amountOut);
struct SwapParams {
    address tokenIn; address tokenOut;
    uint256 amountIn; uint256 minAmountOut;
    uint256 deadline;
    MakerQuote[] quotes;     // RFQ candidates, optional, verified on-chain
    bytes permit;            // Permit2 pull covering tokenIn
}

// AnchorVault: the LP side
function deposit(uint256 usdgAmount, uint256 tokenAmount, address receiver) external returns (uint256 shares);
function withdraw(uint256 shares, address receiver) external returns (uint256 usdgOut, uint256 tokenOut);
function quote(bool isBuy, uint256 amountIn) external view returns (uint256 amountOut, QuoteBreakdown memory b);

// OracleRouter: state open to everyone
function priceOf(address token) external view returns (uint256 mid, uint8 regime, uint64 updatedAt);
```

Mid, spread, skew and fee are separated out inside `QuoteBreakdown`, which every fill emits, so the chain's record holds precisely the decomposition the ticket put on screen.

## Events

One event per fill carries the pair, the size, which venue filled it, the whole breakdown, and the oracle round behind it. One event per parameter change carries the old value, the new value and the hash of the timelock proposal. Nothing but these events feeds the [trade explorer](/using-icaria/trade-explorer.md); it displays nothing drawn from anywhere else.

## Upgrade philosophy

There are no proxies. A new version of the protocol means deploying fresh contracts and letting markets migrate when LPs choose to withdraw in kind and redeposit. Migration convenience is the price; what it buys is the permanent guarantee that the code holding funds right now is the code that was audited. One exception exists, the adapter pattern inside `OracleRouter` and `EligibilityRegistry`, where the accepted adapter set is a timelocked parameter, because oracle products and attestation schemes evolve faster than settlement logic has any business doing.

## Access control summary

| Role              | Held by                                  | Powers                                                         |
| ----------------- | ---------------------------------------- | -------------------------------------------------------------- |
| Timelock proposer | Foundation multisig                      | Proposing parameter changes, each published with its reasoning |
| Guardian          | Foundation multisig, at a smaller quorum | Pausing; coming back out runs through the timelock             |
| Keeper functions  | Nobody, being permissionless             | Poking regimes and halts                                       |
| Everything else   | Nobody                                   | No other privileged function exists                            |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.useicaria.xyz/architecture/smart-contracts.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.