> 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/mechanics/tour.md). # A tour of the mechanics Who acts in Gimbal, what the desk records, and the route a loan takes from a signed request to repayment, rollover or auction. Start with what is absent. Gimbal has no lending pool. Lenders never pay USDG into a common balance, and no utilisation curve decides the rate. In its place are three things: a public book made of signed messages, one desk contract that turns those messages into loans, and a short list of roles. Everything a role does lands on the chain, and the [Explorer](/guides/explorer.md), the public loan explorer served at `/platform/explorer`, shows all of it. ## What the desk records The contracts work with five objects. **Borrow request.** A borrower's signed statement of what they want. The relayer keeps it, a targeted offer names it by its hash, and the desk spends that hash when it fills the request. **Lend offer.** A lender's signed `LendOffer`, EIP-712 typed data. [Offers, requests and origination](/mechanics/offers-and-origination.md) walks through every field. **Market.** The combination `(collateralToken, loanToken, oracle, ltvConfig)`. Each market is sealed off from the others. The same Stock Token may appear in more than one market, each with its own loan asset and parameters, and trouble in one cannot travel into another. **Loan.** The record the desk writes at origination: one borrower, one escrow of collateral, one or more slices. **Slice.** A single lender's portion of a loan, held as a slice token. [Syndicates and lender slices](/mechanics/syndicates.md) shows how portions are worked out. ## Four roles | Role | Gate | What the role does | | -------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Borrower | `BORROWER` in the role registry | Owns Stock Tokens. Signs borrow requests, submits origination, repays, adds collateral, opens rollovers. | | Lender | `LENDER_PROFESSIONAL` now; `LENDER_RETAIL` where the jurisdiction allows it | Signs standing or targeted offers, holds slice tokens, is repaid in proportion to principal. Can opt into parked capital and into in-kind liquidation. | | Keeper | `LIQUIDATOR` to buy collateral at auction; opening an auction, and everything else, is permissionless | Opens collateral auctions, accepts rollover offers on behalf of delegating lenders, sends margin alerts, rebalances parked capital. Earns a share of each penalty. | | Relayer | `RELAYER`, needed only to submit a transaction on a user's behalf | Holds and serves signed offers, checks them against chain state, proposes fills. Open to anyone. | ## From request to close ```mermaid flowchart LR Bo[Borrower] -->|1 signs a request| Book[(Relayer book)] Le[Lenders] -->|2 sign offers| Book Book -->|3 proposed syndicate| Bo Bo -->|4 originate: request, offers, signatures| Desk[TermDesk] Desk -->|roles| Reg[RoleRegistry] Desk -->|price, session, staleness| Sen[PriceSentinel] Desk -->|escrow| Esc[(Collateral)] Desk -->|pull USDG| Le Desk -->|net principal| Bo Desk -->|mint| Sl[LenderSlice tokens] Bo -->|5 repay, or openRefinance before maturity| Desk Kp[Keeper] -->|6 startAuction once HF is under 1.0| Auc[CollateralAuction] ``` 1. A borrower signs a request: which collateral token and how much of it, the principal wanted, the ceiling APR, a term (7 days, 14 days, 30 days or 90 days) and, last, a fill deadline. That deadline is the launch window. Once it passes the request cannot be filled. 2. Lenders reply with offers signed off-chain. A targeted offer names one request. A standing offer names a token or a whole tier and waits for whichever request fits its terms. 3. The borrower asks a relayer to assemble offers that add up to the principal. A relayer holding the `RELAYER` role can also submit the origination itself, carrying the borrower's signature over the request. 4. A single `originate` call does the rest. It verifies each signature, checks every role, prices the collateral through the sentinel with the closed-market haircut where the session calls for it, tests the LTV against the tier ceiling, books each offer, pulls USDG from every lender, takes the collateral into escrow and mints a slice token for each fill. 5. Interest accrues from that block, second by second, and each slice earns its own fixed APR. The borrower can repay at any time, though the interest for the minimum interest period is owed however early they pay. Before maturity they may open a rollover auction instead; the contract call is `openRefinance`. 6. Should the health factor drop under 1.0, anyone may call `startAuction` and a Dutch auction of the collateral begins. Proceeds run through a fixed waterfall: the keeper's share of the penalty, lender claims, the lenders' share of the penalty, the protocol's share, and whatever remains back to the borrower. Each step emits an event. The only thing not on the chain is the book of offers still waiting to be filled, and that book is public, made of signed messages anyone can verify, and mirrored by the indexer. ## Four things that cannot happen * The protocol never holds a lender's money ahead of a match. USDG moves from lender to borrower inside the origination transaction. * No loan opens without a usable price. One exception is planned, on the roadmap, negotiated loans on Tier D collateral for professional lenders only, without automatic liquidation. * A loss stays with the loan and the slice that took it. Nothing is socialised across loans. * Repayment, and the return of collateral once the debt is cleared, have no pause switch. No guardian or governance key can block them. ## Where to go next * [Every state a loan can hold](/mechanics/loan-states.md) for the state machine and the flight log. * [Health factor and auctions](/mechanics/health-and-auctions.md) for the health factor and liquidation. * [The contract set](/architecture/contracts.md) for each on-chain component. --- # 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/mechanics/tour.md?ask=&goal= ``` `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.