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

# System Architecture

Design of the Axis smart contract system: how components relate, how funds flow, and how access control works.

For design rationale, see [Design Decisions](/technical-and-architecture/design-decisions.md). For step-by-step integration instructions, see [Guides](/usdx-the-synthetic-dollar/mint-and-redeem.md). For function signatures, see [Reference](/reference/core-contracts.md). Every contract symbol on this page traces back to the [Protocol Taxonomy](/reference/core-contracts.md) as the single source of truth.

## Onchain and offchain components

The system splits into two halves. The **onchain** component is the smart contracts described on this page, the `USDx` token, the `USDxMarket` primary market, and the `StakedUSDx` vault, which govern issuance, redemption, and staking. The **offchain** component is everything else: the trading strategy, order execution, custody and settlement operations, and risk management that stand behind the backing. This page covers the onchain contracts; the offchain side is described in [Backing, Custody & Transparency](/backing-reserves-and-transparency/backing-custody-transparency.md) and the Risk section.

Every deployed contract is source-verified onchain, so the source can be read directly from the block explorer using the addresses in [Contract Addresses](/reference/contract-addresses.md).

![Four deployed V2 contracts and the two authorities over them. MarketConfig holds the parameters USDxMarket enforces, USDxMarket is the only holder of MARKET\_ROLE on USDx, and StakedUSDx takes USDx as its underlying asset. A governance Safe is admin over all four, while a separate TimelockController owns the ProxyAdmin so upgrades pass a delay.](/files/xwhRGDfVNgn0KbVS3aZI)

## Three-layer design

The protocol separates into three layers:

**Dollar layer**, `USDx`

* Upgradeable ERC-20 synthetic dollar (with `ERC20Permit`); supply is role-gated so only the primary market may mint.

**Market layer**, `USDxMarket`

* Collateral intake and the mint/redeem lifecycle, settled from signed EIP-712 orders against approved routes, channels, and capacity.

**Rewards layer**, `StakedUSDx` (share symbol `sUSDx`)

* ERC-4626 vault whose underlying asset is USDx, with an asynchronous ERC-7540 redemption lifecycle.
* Rewards are funded directly into the vault via `fundRewards` (held under `REWARD_MANAGER_ROLE`). There is no separate rewards-distributor contract.
* Redemption liabilities live inside the vault as `pendingRedeemAssets` / `claimableRedeemAssets`. There is no separate cooldown-escrow (silo) contract.
* `exchangeRate()` is a read-only view (USDx assets per share) that external integrations can observe directly on the vault.

The contract boundaries limit the direct capabilities of each layer. They do not make the layers economically independent: both the market and the rewards vault depend on USDx, and privileged-role or token failures can affect the system across contract boundaries.

## Contract model and upgradeability

Every V2 contract sits behind a `TransparentUpgradeableProxy` with a `ProxyAdmin`; there is no UUPS self-upgrade path in the implementations. Authority uses OpenZeppelin `AccessControlUpgradeable` (`IGovernedAccessControl`) across `USDx`, `USDxMarket`, and `StakedUSDx`.

| Contract     | Shape                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------------- |
| `USDx`       | Upgradeable ERC-20 (`ERC20Permit`), role-gated mint/burn, bridge, pause, and restriction controls |
| `USDxMarket` | EIP-712 order settlement over approved routes/channels; single supply authority on the token      |
| `StakedUSDx` | ERC-4626 vault + ERC-7540 async redemption; its own ERC-7575 share token (`sUSDx`)                |

`DEFAULT_ADMIN_ROLE` (admin over every other role) is held by a **geographically-distributed governance Safe (multisig)**, never a hot EOA. **Contract upgrades are governed separately by a `TimelockController`**, the owner of each `ProxyAdmin`, so an upgrade must pass a timelock delay before it can execute; the delay is set on the `TimelockController` and is verifiable onchain. The governance Safe is **not** behind the timelock: risk-**down** changes (pause, cap decrease, restrict) execute immediately via the guardian roles; non-upgrade risk-**up** changes (cap increase, add a route/custodian/asset) require a deliberate direct action by the Safe, which acts seldom; upgrading an implementation additionally passes through the timelock. Granting **and** revoking roles are both gated by `DEFAULT_ADMIN_ROLE`, there is no custom revoke path or `_setRoleAdmin` override, so only the governance Safe can add or remove a role.

## Fund flow

![Minting runs through the primary market: a signed order, an operator settlement against routes and caps, then USDx. The collateral does not stay onchain, it moves out to custody and trading venues. Leaving the rewards vault is asynchronous in four steps: requestRedeem burns the position and reserves the USDx, a cooldown elapses during which the reserved amount earns nothing, a servicer marks the request claimable, and only then does the holder claim.](/files/G6HqtP4ehqFTp1AnKz0n)

| Path                   | Trigger                                      | Flow                                                                                                 | Outcome                           |
| ---------------------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------------- | --------------------------------- |
| **Mint**               | Eligible party signs an EIP-712 mint order   | Collateral → custody, USDx → user                                                                    | User receives USDx                |
| **Stake**              | User deposits USDx                           | USDx → vault, sUSDx → user                                                                           | Shares appreciate as rewards vest |
| **Redeem**             | Eligible party signs an EIP-712 redeem order | USDx burned, collateral → user                                                                       | User receives collateral          |
| **Request redemption** | Staker calls `requestRedeem`                 | Shares burned, assets reserved as `pendingRedeemAssets`; after cooldown + servicing, claimed as USDx | Asynchronous exit from the vault  |

The value that makes sUSDx positions appreciate comes from Axis's trading engine, whose structural edge is cross-venue and cross-asset fragmentation, a durable, market-neutral yield source that does not rely on any single mechanism. Funding is one component (and can be the larger share in a given period); see the Transparency Dashboard for current attribution. Realized results are delivered to the vault as USDx rewards. See [How Axis Earns Yield](/susdx-the-rewards-vault/how-axis-earns-yield.md).

{% hint style="warning" %}
**Edge case: emergency halt.** An `EMERGENCY_ROLE` holder can pause capacity and disable the mint/redeem paths on the market; token and vault flows can additionally be paused under `PAUSER_ROLE`. These are risk-down authorities only, they cannot grant roles, raise caps, or re-enable expanded operations, which requires a deliberate action by the admin multisig.
{% endhint %}

### Mint path

1. An eligible party signs an EIP-712 order binding `accountId`, `routeId`, `channelId`, side, input/output assets and amounts, `deadline`, `nonce`, and `termsHash`.
2. An operator with `MINT_OPERATOR_ROLE` submits it to `USDxMarket.settle`.
3. The market re-runs every pre-trade check (eligibility, route/channel, capacity, signature, nonce), routes collateral to registered custody, and mints USDx to the beneficiary. Supply authority on the token is `MARKET_ROLE`, held only by `USDxMarket`.

### Redeem path

1. An eligible party signs a redeem order.
2. An operator with `REDEEM_OPERATOR_ROLE` submits it for settlement.
3. The market burns the user's USDx (spending an approval) and transfers collateral to the beneficiary. A failed settlement consumes neither the nonce nor the order, so a rejected order can be safely retried.

### Staking and redemption path

1. A user deposits USDx into `StakedUSDx` and receives `sUSDx` shares immediately, priced at the current exchange rate.
2. The reward manager calls `fundRewards` (`REWARD_MANAGER_ROLE`) to add realized yield to the vault.
3. Rewards vest linearly over a configured window; only the vested portion counts toward vault assets, so `exchangeRate()` rises smoothly rather than jumping on each funding.
4. To exit, the staker calls `requestRedeem`, which burns the shares and opens a request subject to a per-policy cooldown. Once eligible, an account with `REDEMPTION_SERVICER_ROLE` calls `serviceRedemptions` to mark it claimable, after which the staker claims (withdraws) the underlying USDx. A still-pending request can be cancelled, which restores the burned shares.

## Access-control model

All three V2 contracts use OpenZeppelin `AccessControlUpgradeable` (`IGovernedAccessControl`). Authority is organized by risk direction rather than by contract: privileged actions map to documentation paths (`GOVERNANCE`, `EMERGENCY`, `OPERATIONS`, `COMPLIANCE`, `REWARDS`, `PUBLIC_READ`), each of which resolves to one or more concrete `*_ROLE` constants. `DEFAULT_ADMIN_ROLE`, the admin over every other role, is held only by the governance Safe (multisig); contract upgrades are governed separately by a `TimelockController` (upgrades pass a timelock delay), which is distinct from the Safe's day-to-day admin authority.

Axis follows an operator/manager split: `_OPERATOR` roles **execute** approved flows, while `_MANAGER` roles **configure or move** within bounds, so a hot executor never gains configuration power.

The role-by-role breakdown, including which function each role gates, is in [Access Control](/reference/access-control.md). Two behaviours matter at the architecture level.

### Market roles

`EMERGENCY_ROLE` is the one-directional emergency brake on the market: it can only reduce risk, never re-enable expanded operations. It has no role-revocation power, revoking a hot market role is gated by `DEFAULT_ADMIN_ROLE`, so only the admin multisig can remove one.

### Vault roles

Restrictions freeze actions; they never seize funds, `RESTRICTION_ROLE` can restrict but cannot mint, burn, seize, service redemptions, or move collateral.

## Design decisions

Trade-offs and rationale behind EIP-712 order signing, route- and channel-based custody, the configured reward-vesting window, the asynchronous ERC-7540 redemption lifecycle, the restriction model, and the vault solvency invariants.

See [Design Decisions](/technical-and-architecture/design-decisions.md) for the full discussion.

## Contract dependencies

| Contract     | Immutable dependencies  | Mutable dependencies                                          |
| ------------ | ----------------------- | ------------------------------------------------------------- |
| `USDx`       | None                    | Role holders (incl. `MARKET_ROLE` on `USDxMarket`)            |
| `USDxMarket` | `USDx` (mint target)    | Supported assets, custodians, routes, channels, capacity caps |
| `StakedUSDx` | `USDx` (ERC-4626 asset) | Cooldown duration, reward schedule, roles                     |

Governance and upgrade authority sit above all three and are held by distinct authorities, as described under [Contract model and upgradeability](#contract-model-and-upgradeability) above.


---

# 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.axis.to/technical-and-architecture/architecture.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.