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

# System map

Where each piece of Gimbal runs, which contract or service owns which job, and exactly how far anyone outside the chain is trusted.

Two layers make up Gimbal. The first is a compact set of contracts on Robinhood Chain (chain ID 4663) with no upgrade path. The second is a ring of open-source services that anyone can run. All rules live in the first layer, and so does every balance. The second layer only makes that state faster to read and easier to act on. Think of a ground station: it watches and relays, and it never flies the craft.

```mermaid
flowchart LR
  subgraph People
    BW[Borrower<br/>Robinhood Wallet or any EVM wallet<br/>4337 or 7702]
    LW[Lender]
    KP[Keepers, liquidators]
  end

  subgraph Ground[Services off the chain]
    UI[Platform, Next.js]
    RLY[Relayer<br/>signed EIP-712 book]
    IX[Indexer<br/>Ponder or Envio]
    ID[KYC provider<br/>writes EAS attestations]
    BOT[Alerts and keeper bots]
  end

  subgraph RH[Robinhood Chain, 4663]
    DESK[TermDesk<br/>the desk, immutable]
    REG[RoleRegistry]
    PX[PriceSentinel<br/>Chainlink Feeds, Streams<br/>sequencer uptime]
    CA[CollateralAuction]
    RA[RolloverAuction]
    SL[LenderSlice, ERC-721]
    PK[ParkingAdapter<br/>Morpho Blue USDG vault]
    PB[PolicyBoard<br/>timelocked multisig]
    STK[(Stock Tokens<br/>ERC-20, ERC-8056)]
    USD[(USDG)]
    LINK[(Chainlink)]
    MORPHO[(Morpho Blue)]
  end

  BW --> UI --> RLY
  LW --> UI
  UI --> IX
  ID --> REG
  RLY --> DESK
  BW --> DESK
  KP --> CA
  DESK --> REG
  DESK --> PX --> LINK
  DESK --> SL
  DESK --> STK
  DESK --> USD
  DESK --> PK --> MORPHO
  DESK --> CA
  DESK --> RA
  PB --> DESK
  IX --> DESK
  BOT --> IX
```

## Who is trusted, and with what

Five statements cover every trust assumption in the system.

* **Prices come from Chainlink.** A price reaches a contract only once the guards in `PriceSentinel` have let it through.
* **Eligibility comes from registered attestation issuers.** `PolicyBoard` holds the issuer list. What an issuer says about a wallet is the one claim the contracts accept without checking.
* **Parameter changes come from the timelocked multisig.** That is the whole of its power. It cannot touch funds, replace code or stand in the way of a repayment.
* **The relayer is trusted with nothing.** At origination, the desk verifies every offer again on-chain. A hostile relayer could sit on offers; it has no way to forge or edit them.
* **The platform is trusted with nothing.** It is a window onto public data and public contracts.

## Reading the edges

Arrows in the diagram are calls or data flows. A borrower reaches the desk two ways: through the platform and relayer, or straight from a wallet. Lenders only ever sign; the relayer or the borrower carries their offers on-chain. Keepers talk to `CollateralAuction`, never to the desk directly, because the desk accepts liquidation hooks from the auctions alone. The desk reads roles from `RoleRegistry`, prices from `PriceSentinel`, and every tunable from `PolicyBoard`. It mints slices on `LenderSlice`, escrows Stock Tokens, moves USDG, and, when a lender has chosen to park capital, draws from the Morpho vault through `ParkingAdapter`. The indexer only reads events; keeper bots read the indexer.

## The chain layer

| Contract            | What it owns                                                                                       |
| ------------------- | -------------------------------------------------------------------------------------------------- |
| `TermDesk`          | Offer verification, collateral escrow, principal payout, the loan and slice ledger, repayment      |
| `OfferBook`         | EIP-712 hashing, signature recovery for ECDSA and EIP-1271, nonce bitmaps, partial-fill accounting |
| `RoleRegistry`      | Turns attestations into yes-or-no role answers, with jurisdiction rules and expiry applied         |
| `PriceSentinel`     | Session-aware prices, guarded against staleness, pauses, multipliers and sequencer downtime        |
| `CollateralAuction` | Dutch auction of the seized collateral, settlement in kind where chosen, the penalty split         |
| `RolloverAuction`   | The rising-rate auction that carries a loan into a new term at maturity                            |
| `LenderSlice`       | One ERC-721 per lender slice; a transfer completes only if the receiver is eligible                |
| `ParkingAdapter`    | Parks a lender's USDG in one whitelisted Morpho vault and pulls it back when a fill needs it       |
| `PolicyBoard`       | All adjustable parameters, held behind the timelocked multisig; each write emits an event          |
| `Treasury`          | Collects the origination, interest-share, penalty and rollover fees                                |

Function-level detail for each of these, including the interfaces an integrator calls, is in [The contract set](/architecture/contracts.md).

## The ground layer

| Service     | What it does                                                                                                   |
| ----------- | -------------------------------------------------------------------------------------------------------------- |
| Relayer     | Publishes signed offers and requests, checks them, proposes matches                                            |
| Indexer     | Rebuilds loans, slices, auctions and parameters from events; feeds the Explorer and the bots                   |
| Keepers     | Raise alerts, open auctions, rebalance parked capital, submit rollover acceptances                             |
| KYC service | Runs identity, sanctions and residency checks, then writes the attestation; no personal data reaches the chain |
| Platform    | Borrower and lender dashboards, the Explorer, Telemetry, the governance log                                    |

[Services off the chain](/architecture/services.md) covers each in depth.

## Rules of operation

* Contracts are not upgraded in place, ever. A new version is a fresh deployment. A loan already open stays on the deployment that opened it until it closes.
* Apart from loan data, the parameters in `PolicyBoard` are the only state that changes. Each change waits out the timelock, then appears on-chain as an event.
* Two things sit behind the emergency pause: new loans and liquidations. Repaying a loan, and getting collateral back after repaying it, sit outside the pause entirely.


---

# 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.usegimbal.app/architecture/system-map.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.