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

# Architecture at a glance

Ethosis pairs a compact set of non-upgradeable contracts on Robinhood Chain with open-source services that anyone is free to operate. State and rule enforcement sit entirely in the contracts. The services exist so that the state is easy to reach and act on; they add convenience, not authority.

```mermaid
flowchart LR
  subgraph Users
    B[Borrower wallet<br/>Robinhood Wallet or any EVM wallet<br/>4337 or 7702]
    L[Lender wallet]
    K[Keepers and liquidators]
  end

  subgraph OffChain[Services off-chain]
    FE[Front-end, Next.js]
    REL[Relayer API<br/>EIP-712 order book]
    IDX[Indexer<br/>Ponder or Envio]
    KYC[KYC provider<br/>issues EAS attestations]
    NOTIF[Keeper bots and alerts]
  end

  subgraph Chain[Robinhood Chain, chain 4663]
    CORE[LoanDesk<br/>immutable core]
    ELIG[AccessRegistry]
    ORA[PriceGate<br/>Chainlink Feeds and Streams<br/>Sequencer Uptime]
    AUC[CollateralAuction]
    REFI[RolloverAuction]
    POS[SliceToken, ERC-721]
    PARK[IdleVaultAdapter<br/>Morpho Blue USDG vault]
    PARAM[PolicyController<br/>multisig behind a timelock]
    ST[(Stock Tokens<br/>ERC-20 and ERC-8056)]
    USDG[(USDG)]
    CL[(Chainlink)]
    MB[(Morpho Blue)]
  end

  B --> FE --> REL
  L --> FE
  FE --> IDX
  KYC --> ELIG
  REL --> CORE
  B --> CORE
  K --> AUC
  CORE --> ELIG
  CORE --> ORA --> CL
  CORE --> POS
  CORE --> ST
  CORE --> USDG
  CORE --> PARK --> MB
  CORE --> AUC
  CORE --> REFI
  PARAM --> CORE
  IDX --> CORE
  NOTIF --> IDX
```

## The two layers

### Contracts

| Contract            | What it is responsible for                                                                                     |
| ------------------- | -------------------------------------------------------------------------------------------------------------- |
| `LoanDesk`          | Checks offers, holds collateral in escrow, pays out principal, keeps loan and slice records, handles repayment |
| `IntentBook`        | EIP-712 hashing, signature recovery (ECDSA and EIP-1271), nonce bitmaps, partial-fill bookkeeping              |
| `AccessRegistry`    | Looks up attestations, answers role queries, applies jurisdiction rules and expiry                             |
| `PriceGate`         | Session-aware pricing with guards for staleness, pauses, multipliers and sequencer uptime                      |
| `CollateralAuction` | Dutch auction of seized collateral, optional in-kind settlement, division of the penalty                       |
| `RolloverAuction`   | Rising-rate auction that rolls a loan over at maturity                                                         |
| `SliceToken`        | One ERC-721 per lender slice; transfers gated on recipient eligibility                                         |
| `IdleVaultAdapter`  | Moves lender balances into and out of a whitelisted Morpho vault                                               |
| `PolicyController`  | Every tunable parameter, held behind a timelocked multisig, with an event on each change                       |
| `Treasury`          | Collects origination, interest-share, penalty and refinance fees                                               |

The [contract reference](/architecture/smart-contracts.md) covers each of these in depth, including the interfaces integrators call.

### Services

| Service     | What it is responsible for                                                                      |
| ----------- | ----------------------------------------------------------------------------------------------- |
| Relayer     | Public book of signed offers and requests, validation, suggested matches                        |
| Indexer     | Event-sourced record of every loan, slice, auction and parameter, feeding the explorer and bots |
| Keepers     | Alerts, starting auctions, submitting refinance acceptances, rebalancing idle capital           |
| KYC service | Identity, sanctions and residency screening; issues attestations; keeps PII off-chain           |
| Front-end   | Dashboards for borrowers and lenders, loan explorer, risk page, governance log                  |

See [Off-chain services](/architecture/off-chain-services.md) for the specifics of each.

## Who trusts whom

* **Prices come from Chainlink.** The contracts accept them, subject to the guards built into `PriceGate`.
* **Eligibility comes from the attestation issuers** registered in `PolicyController`. That is the only thing the contracts take on trust about a user.
* **Parameter changes come from the timelocked multisig.** That is the extent of its power: it cannot touch funds, replace code or halt repayment.
* **The relayer is not trusted by anyone.** Each offer it hands over is verified again on-chain when the loan is originated. A hostile relayer could hide offers, but it cannot forge one or change one.
* **The front-end is not trusted by anyone either.** It is a convenience layer over public data and public contracts.

## How it is operated

* The core contracts cannot be upgraded. A new version means a fresh deployment, and loans already open finish their term on the deployment that created them.
* Apart from loan data, parameters are the only state that can change, and each change goes through the timelock and is recorded on-chain.
* The emergency pause reaches new loans and liquidations, and nothing else. Repaying a loan and withdrawing collateral after repayment can never be paused.


---

# 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.ethosis.org/architecture/overview.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.