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

# System map

The contracts on Robinhood Chain, the services that surround them, and the precise limits of what each party is trusted with.

Farlight is built in two parts. On Robinhood Chain sits a small group of contracts that cannot be upgraded; around them runs a set of open-source services that anyone may operate. Every rule is enforced in the contracts and every balance is held there. The services shorten the distance between a user and that state, in the way a ground station observes and relays without ever steering the craft. They add reach, never 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[Off-chain services]
    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
```

## What runs where

### On the chain

| Contract            | Role                                                                                                                   |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `LoanDesk`          | Verifies offers, escrows collateral, disburses principal, records loans and slices, processes repayment                |
| `IntentBook`        | EIP-712 hashing, ECDSA and EIP-1271 signature recovery, nonce bitmaps, partial-fill accounting                         |
| `AccessRegistry`    | Resolves attestations into role answers, applying jurisdiction rules and expiry                                        |
| `PriceGate`         | Prices that know which trading session they belong to, guarded for staleness, pauses, multipliers and sequencer uptime |
| `CollateralAuction` | Dutch auction of seized collateral, optional settlement in kind, split of the penalty                                  |
| `RolloverAuction`   | Rising-rate auction that refinances a loan when its term ends                                                          |
| `SliceToken`        | An ERC-721 for each lender slice; a transfer goes through only if the recipient is eligible                            |
| `IdleVaultAdapter`  | Routes lender balances into a whitelisted Morpho vault and back out again                                              |
| `PolicyController`  | Every tunable value, behind a timelocked multisig, with an event emitted for each change                               |
| `Treasury`          | Receives origination, interest-share, penalty and refinance fees                                                       |

Each of these is documented function by function, including the interfaces integrators call, in the [contract reference](/architecture/smart-contracts.md).

### Off the chain

| Service     | Role                                                                                                    |
| ----------- | ------------------------------------------------------------------------------------------------------- |
| Relayer     | Publishes the book of signed offers and requests, validates them, and proposes matches                  |
| Indexer     | Replays events into a record of every loan, slice, auction and parameter, for the explorer and the bots |
| Keepers     | Send alerts, start auctions, submit refinance acceptances, rebalance parked capital                     |
| KYC service | Screens identity, sanctions and residency, issues attestations, and keeps personal data off the chain   |
| Front-end   | Borrower and lender dashboards, the loan explorer, the risk page, the governance log                    |

[Off-chain services](/architecture/off-chain-services.md) describes each one in detail.

## Trust boundaries

* **Chainlink supplies prices.** The contracts accept a price only after it clears the guards inside `PriceGate`.
* **Registered attestation issuers supply eligibility.** The issuer set is held in `PolicyController`, and an issuer's word about a user is the single thing the contracts take on faith.
* **The timelocked multisig supplies parameter changes.** Nothing more. It cannot move funds, swap code or block repayment.
* **Nobody trusts the relayer.** Every offer it delivers is verified a second time on-chain at origination. A malicious relayer could withhold offers; it could not forge or alter one.
* **Nobody trusts the front-end.** It is a viewing layer over public data and public contracts.

## Operating model

* Core contracts are never upgraded in place. A new version is a new deployment, and any loan already open runs to maturity on the deployment where it began.
* Outside loan data itself, parameters are the only mutable state. Every change passes through the timelock and lands on-chain as an event.
* The emergency pause covers new loans and liquidations, and stops there. Repayment, and the return of collateral once a loan is repaid, cannot be paused under any circumstances.


---

# 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.usefarlight.com/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.