> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mystockline.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# RiskRegistry

> RiskRegistry holds every governance-writable parameter: tiers, books, per-book overrides, interest-rate curves, caps, fees, liquidation settings, the DEX router

RiskRegistry holds every governance-writable parameter: tiers, books, per-book overrides, interest-rate curves, caps, fees, liquidation settings, the DEX router, and swap routes. Its owner is the Timelock, so every change waits out the delay. Stockline reads it on every action but never writes to it. The guardian has no access here.

`RiskRegistry` lets you:

* Read the effective LTV, liquidation threshold, and max discount of any book
* Look up a book by id or by collateral token
* Read interest-rate parameters, caps, and liquidation settings
* Read the allowlisted swap routes used by Zap and FeeCollector
* Let governance (through the timelock) create books and tune risk

Addresses per network. Every address is also on [Addresses](/resources/addresses).

| Network                 | Address                                                                                                                                       |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| Robinhood Chain testnet | [0xc620F965f49eE0431d1750EFF62e75f4Dbb96799](https://explorer.testnet.chain.robinhood.com/address/0xc620F965f49eE0431d1750EFF62e75f4Dbb96799) |

The source code is [`src/core/RiskRegistry.sol`](https://github.com/stockline-xyz/contracts/blob/main/src/core/RiskRegistry.sol) on GitHub. The ABI is [`/abis/RiskRegistry.json`](/abis/RiskRegistry.json).

## Write methods

### setTier

```solidity theme={"system"}
function setTier(uint16 id, Tier calldata params) external
```

Creates or replaces a risk tier. Books on this tier pick up the new values at once. Owner only. Reverts with ZeroId for id 0, InvalidLtvLt unless ltv \< lt \< 1e18, and InvalidDiscount when maxLiqDiscount is 1e18 or more.

<Warning>
  Owner (timelock) only.
</Warning>

<Note>
  Bounds: ltv \< lt \< 1e18 so a position always has a cushion before liquidation.
</Note>

**Input parameters**

| Name   | Type     | Description                                                                                                                            |
| ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| id     | `uint16` | Tier id. Must be non-zero.                                                                                                             |
| params | `Tier`   | Tier struct: `ltv` (WAD), `lt` (WAD), `maxLiqDiscount` (WAD), `liquidatorAllowlist` (bool). The `exists` field is set by the contract. |

### createBook

```solidity theme={"system"}
function createBook(
    address collateral,
    address oracle,
    uint16 issuerId,
    uint16 tierId,
    uint128 borrowCap
) external returns (uint16 id)
```

Opens a new isolated book against the shared USDG pool. Owner only. One book per collateral token. The book starts with `borrowingEnabled` false. Reverts with BookAlreadyExists, UnknownTier, ZeroId, or ZeroAddress on bad input.

<Note>
  Collateral, oracle, and issuer never change after creation. Governance must call `setBorrowingEnabled` before anyone can borrow.
</Note>

**Input parameters**

| Name       | Type      | Description                                                                           |
| ---------- | --------- | ------------------------------------------------------------------------------------- |
| collateral | `address` | The stock token accepted as collateral.                                               |
| oracle     | `address` | The EquityOracle for this token.                                                      |
| issuerId   | `uint16`  | Groups books that are claims on the same issuer for the issuer cap. Must be non-zero. |
| tierId     | `uint16`  | The risk tier to inherit. Must exist.                                                 |
| borrowCap  | `uint128` | Maximum USDG debt for this book, in USDG native units.                                |

**Return values**

| Type     | Description                                        |
| -------- | -------------------------------------------------- |
| `uint16` | id: The new book id, equal to the new `bookCount`. |

### setBookOverride

```solidity theme={"system"}
function setBookOverride(uint16 bookId, BookOverride calldata ov) external
```

Replaces the full override set for one book. Each `setX` flag chooses the override value or falls back to the tier. Owner only. The effective pair must still satisfy ltv \< lt \< 1e18 and discount \< 1e18.

<Warning>
  Owner (timelock) only.
</Warning>

<Note>
  Emits BookOverrideSet, not TierSet, so indexers can tell a one-off from a bucket change.
</Note>

**Input parameters**

| Name   | Type           | Description                                                                                                                                    |
| ------ | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| bookId | `uint16`       | The book to override. Must exist.                                                                                                              |
| ov     | `BookOverride` | BookOverride struct: `setLtv`/`ltv`, `setLt`/`lt`, `setMaxLiqDiscount`/`maxLiqDiscount`, `setAllowlist`/`liquidatorAllowlist`. Values are WAD. |

### setBookTier

```solidity theme={"system"}
function setBookTier(uint16 bookId, uint16 tierId) external
```

Moves a book to another tier. Existing overrides still apply on top. Owner only. Reverts with UnknownTier or ZeroId, or InvalidLtvLt if the combination is invalid.

<Warning>
  Owner (timelock) only.
</Warning>

**Input parameters**

| Name   | Type     | Description           |
| ------ | -------- | --------------------- |
| bookId | `uint16` | The book to move.     |
| tierId | `uint16` | The destination tier. |

### setBorrowCap

```solidity theme={"system"}
function setBorrowCap(uint16 bookId, uint128 borrowCap) external
```

Sets the per-book USDG debt cap. A cap of 0 closes new borrowing rather than making it unlimited. Owner only.

<Warning>
  Owner (timelock) only.
</Warning>

**Input parameters**

| Name      | Type      | Description                                            |
| --------- | --------- | ------------------------------------------------------ |
| bookId    | `uint16`  | The book to update.                                    |
| borrowCap | `uint128` | Maximum total debt for the book, in USDG native units. |

### setBorrowingEnabled

```solidity theme={"system"}
function setBorrowingEnabled(uint16 bookId, bool enabled) external
```

Turns borrowing on or off for one book. Books start off so the pool can fill before anyone borrows. Owner only.

<Warning>
  Owner (timelock) only. Turning this off does not block repay, supply, or liquidation.
</Warning>

**Input parameters**

| Name    | Type     | Description                |
| ------- | -------- | -------------------------- |
| bookId  | `uint16` | The book to update.        |
| enabled | `bool`   | True to allow new borrows. |

### setIrmParams

```solidity theme={"system"}
function setIrmParams(uint16 bookId, IrmParams calldata params) external
```

Sets the kinked interest-rate curve for one book. Owner only. Reverts with InvalidKink unless 0 \< kink \< 1e18.

<Warning>
  Owner (timelock) only.
</Warning>

**Input parameters**

| Name   | Type        | Description                                                                                                                 |
| ------ | ----------- | --------------------------------------------------------------------------------------------------------------------------- |
| bookId | `uint16`    | The book to update.                                                                                                         |
| params | `IrmParams` | IrmParams struct: `baseRate`, `slopeBelowKink`, `slopeAboveKink` (per-second rates in WAD) and `kink` (utilization in WAD). |

### setIssuerCap

```solidity theme={"system"}
function setIssuerCap(uint16 issuerId, uint128 cap) external
```

Sets the aggregate USDG debt cap across every book that shares an issuer id. Owner only. Reverts with ZeroId for issuer 0.

<Warning>
  Owner (timelock) only.
</Warning>

<Note>
  Launch: one issuer owns all twelve stock tokens, so this is the protocol cap.
</Note>

**Input parameters**

| Name     | Type      | Description                                  |
| -------- | --------- | -------------------------------------------- |
| issuerId | `uint16`  | The issuer group.                            |
| cap      | `uint128` | Maximum combined debt, in USDG native units. |

### setReserveFactor

```solidity theme={"system"}
function setReserveFactor(uint64 reserveFactor_) external
```

Sets the share of borrower interest that goes to the reserve instead of suppliers. Owner only. Reverts with InvalidWad above 1e18.

<Warning>
  Owner (timelock) only.
</Warning>

**Input parameters**

| Name            | Type     | Description                            |
| --------------- | -------- | -------------------------------------- |
| reserveFactor\_ | `uint64` | Share in WAD. Launch value is 0.15e18. |

### setProtocolLiqFeeShare

```solidity theme={"system"}
function setProtocolLiqFeeShare(uint64 share) external
```

Sets the protocol's share of the liquidation discount, routed to FeeCollector as seized collateral. Owner only. Reverts with InvalidWad above 1e18.

<Warning>
  Owner (timelock) only.
</Warning>

**Input parameters**

| Name  | Type     | Description                         |
| ----- | -------- | ----------------------------------- |
| share | `uint64` | Share of the discount bonus in WAD. |

### setLiquidationParams

```solidity theme={"system"}
function setLiquidationParams(
    uint32 auctionWindow_,
    uint64 targetHealth_,
    uint128 dustDebt_
) external
```

Sets the Dutch auction window, the post-liquidation health target, and the dust threshold. Owner only. Reverts with InvalidAuctionWindow outside (0, 7 days], InvalidTargetHealth outside \[1e18, 2e18], and InvalidDust for 0.

<Warning>
  Owner (timelock) only.
</Warning>

<Note>
  SPEC: launch 2h / 1e18 / 10e18. Window 0 would jump the discount to max on first tick.
</Note>

**Input parameters**

| Name            | Type      | Description                                                                      |
| --------------- | --------- | -------------------------------------------------------------------------------- |
| auctionWindow\_ | `uint32`  | Seconds for the discount to ramp from 0 to the book max.                         |
| targetHealth\_  | `uint64`  | Health factor a partial liquidation aims for, in WAD.                            |
| dustDebt\_      | `uint128` | USDG debt below which a liquidation closes the whole book, in USDG native units. |

### setDexRouter

```solidity theme={"system"}
function setDexRouter(address router) external
```

Sets the ISwapRouter used by Zap, PositionRouter, FeeCollector, and CreatorFeeRouter. Core accounting never calls it. Owner only. Reverts with ZeroAddress for the zero address.

<Warning>
  Owner (timelock) only.
</Warning>

**Input parameters**

| Name   | Type      | Description                                             |
| ------ | --------- | ------------------------------------------------------- |
| router | `address` | An ISwapRouter implementation such as UniswapV3Adapter. |

### setBuyAndBurn

```solidity theme={"system"}
function setBuyAndBurn(BuyAndBurnParams calldata params) external
```

Sets the route, slippage cap, per-call size, and TWAP window for treasury USDG to STK burns. Owner only. Reverts with InvalidRoute for fewer than two hops or a zero TWAP window, InvalidBps above 10000, and ZeroAddress for any zero hop.

<Warning>
  Owner (timelock) only.
</Warning>

**Input parameters**

| Name   | Type               | Description                                                                                                                                                     |
| ------ | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| params | `BuyAndBurnParams` | BuyAndBurnParams struct: `route` (token path starting with USDG and ending in STK), `maxSlippageBps`, `maxPerCall` (USDG native units), `twapWindow` (seconds). |

### setZapRoute

```solidity theme={"system"}
function setZapRoute(address token, ZapRoute calldata route) external
```

Allowlists a token that Zap and the fee contracts can convert to or from USDG, or removes it with `allowed` false. Owner only. Reverts with ZeroAddress for a zero token and validates the route when allowed.

<Warning>
  Owner (timelock) only.
</Warning>

**Input parameters**

| Name  | Type       | Description                                                                          |
| ----- | ---------- | ------------------------------------------------------------------------------------ |
| token | `address`  | The asset to allow or remove.                                                        |
| route | `ZapRoute` | ZapRoute struct: `route` (path from the token to USDG), `maxSlippageBps`, `allowed`. |

## Read methods

### book

```solidity theme={"system"}
function book(uint16 id) external view returns (Book memory)
```

Returns the Book struct for an id. Unknown ids return a struct with `exists` false.

**Input parameters**

| Name | Type     | Description |
| ---- | -------- | ----------- |
| id   | `uint16` | Book id.    |

**Return values**

| Type   | Description                                                                                    |
| ------ | ---------------------------------------------------------------------------------------------- |
| `Book` | Book: `collateral`, `oracle`, `issuerId`, `tierId`, `borrowCap`, `borrowingEnabled`, `exists`. |

### bookIdOf

```solidity theme={"system"}
function bookIdOf(address collateral) external view returns (uint16)
```

Returns the book id for a collateral token, or 0 if none.

**Input parameters**

| Name       | Type      | Description        |
| ---------- | --------- | ------------------ |
| collateral | `address` | The token address. |

**Return values**

| Type     | Description   |
| -------- | ------------- |
| `uint16` | Book id or 0. |

### tier

```solidity theme={"system"}
function tier(uint16 id) external view returns (Tier memory)
```

Returns the Tier struct for an id. Unknown ids return `exists` false.

**Input parameters**

| Name | Type     | Description |
| ---- | -------- | ----------- |
| id   | `uint16` | Tier id.    |

**Return values**

| Type   | Description                                                                 |
| ------ | --------------------------------------------------------------------------- |
| `Tier` | Tier: `ltv`, `lt`, `maxLiqDiscount` (WAD), `liquidatorAllowlist`, `exists`. |

### bookOverride

```solidity theme={"system"}
function bookOverride(uint16 bookId) external view returns (BookOverride memory)
```

Returns the raw override struct for a book. Use `ltv`, `lt`, and `maxLiqDiscount` for effective values.

**Input parameters**

| Name   | Type     | Description |
| ------ | -------- | ----------- |
| bookId | `uint16` | Book id.    |

**Return values**

| Type           | Description          |
| -------------- | -------------------- |
| `BookOverride` | BookOverride struct. |

### ltv

```solidity theme={"system"}
function ltv(uint16 bookId) external view returns (uint64)
```

Returns the effective loan-to-value of a book: the override if set, else the tier value. Reverts with UnknownBook for an unknown id.

**Input parameters**

| Name   | Type     | Description |
| ------ | -------- | ----------- |
| bookId | `uint16` | Book id.    |

**Return values**

| Type     | Description |
| -------- | ----------- |
| `uint64` | LTV in WAD. |

### lt

```solidity theme={"system"}
function lt(uint16 bookId) external view returns (uint64)
```

Returns the effective liquidation threshold of a book. Reverts with UnknownBook for an unknown id.

**Input parameters**

| Name   | Type     | Description |
| ------ | -------- | ----------- |
| bookId | `uint16` | Book id.    |

**Return values**

| Type     | Description                   |
| -------- | ----------------------------- |
| `uint64` | Liquidation threshold in WAD. |

### maxLiqDiscount

```solidity theme={"system"}
function maxLiqDiscount(uint16 bookId) external view returns (uint64)
```

Returns the effective maximum Dutch auction discount of a book. Reverts with UnknownBook for an unknown id.

**Input parameters**

| Name   | Type     | Description |
| ------ | -------- | ----------- |
| bookId | `uint16` | Book id.    |

**Return values**

| Type     | Description      |
| -------- | ---------------- |
| `uint64` | Discount in WAD. |

### liquidatorAllowlist

```solidity theme={"system"}
function liquidatorAllowlist(uint16 bookId) external view returns (bool)
```

Returns the effective allowlist flag of a book. Reverts with UnknownBook for an unknown id.

<Note>
  This flag is stored for governance but LiquidationModule does not enforce it. Liquidations are permissionless.
</Note>

**Input parameters**

| Name   | Type     | Description |
| ------ | -------- | ----------- |
| bookId | `uint16` | Book id.    |

**Return values**

| Type   | Description                |
| ------ | -------------------------- |
| `bool` | True when the flag is set. |

### irmParams

```solidity theme={"system"}
function irmParams(uint16 bookId) external view returns (IrmParams memory)
```

Returns the interest-rate curve of a book. Reverts with UnknownBook for an unknown id.

**Input parameters**

| Name   | Type     | Description |
| ------ | -------- | ----------- |
| bookId | `uint16` | Book id.    |

**Return values**

| Type        | Description                                                                                           |
| ----------- | ----------------------------------------------------------------------------------------------------- |
| `IrmParams` | IrmParams: `baseRate`, `slopeBelowKink`, `slopeAboveKink` (per-second WAD), `kink` (utilization WAD). |

### issuerCap

```solidity theme={"system"}
function issuerCap(uint16 issuerId) external view returns (uint128)
```

Returns the aggregate debt cap for an issuer group.

**Input parameters**

| Name     | Type     | Description |
| -------- | -------- | ----------- |
| issuerId | `uint16` | Issuer id.  |

**Return values**

| Type      | Description               |
| --------- | ------------------------- |
| `uint128` | Cap in USDG native units. |

### buyAndBurn

```solidity theme={"system"}
function buyAndBurn() external view returns (BuyAndBurnParams memory)
```

Returns the current BuyAndBurnParams.

**Return values**

| Type               | Description              |
| ------------------ | ------------------------ |
| `BuyAndBurnParams` | BuyAndBurnParams struct. |

### zapRoute

```solidity theme={"system"}
function zapRoute(address token) external view returns (ZapRoute memory)
```

Returns the ZapRoute for a token. Tokens that were never set return `allowed` false.

**Input parameters**

| Name  | Type      | Description    |
| ----- | --------- | -------------- |
| token | `address` | Token address. |

**Return values**

| Type       | Description                                     |
| ---------- | ----------------------------------------------- |
| `ZapRoute` | ZapRoute: `route`, `maxSlippageBps`, `allowed`. |

## Events

### TierSet

```solidity theme={"system"}
event TierSet(
    uint16 indexed id,
    uint64 ltv,
    uint64 lt,
    uint64 maxLiqDiscount,
    bool liquidatorAllowlist
)
```

Fires when a tier is created or replaced.

### BookCreated

```solidity theme={"system"}
event BookCreated(
    uint16 indexed id,
    address collateral,
    address oracle,
    uint16 issuerId,
    uint16 tierId,
    uint128 borrowCap
)
```

Fires when a book is opened, with its immutable identity and initial cap.

### BookOverrideSet

```solidity theme={"system"}
event BookOverrideSet(
    uint16 indexed bookId,
    bool setLtv,
    uint64 ltv,
    bool setLt,
    uint64 lt,
    bool setMaxLiqDiscount,
    uint64 maxLiqDiscount,
    bool setAllowlist,
    bool liquidatorAllowlist
)
```

Fires when a book's override set is replaced, with every flag and value.

### BookTierSet

```solidity theme={"system"}
event BookTierSet(uint16 indexed id, uint16 tierId)
```

Fires when a book moves to another tier.

### BookCapSet

```solidity theme={"system"}
event BookCapSet(uint16 indexed id, uint128 borrowCap)
```

Fires when a book's borrow cap changes.

### BookBorrowingEnabled

```solidity theme={"system"}
event BookBorrowingEnabled(uint16 indexed id, bool enabled)
```

Fires when a book's borrowing flag changes.

### IrmParamsSet

```solidity theme={"system"}
event IrmParamsSet(
    uint16 indexed bookId,
    uint64 baseRate,
    uint64 slopeBelowKink,
    uint64 slopeAboveKink,
    uint64 kink
)
```

Fires when a book's interest curve changes.

### IssuerCapSet

```solidity theme={"system"}
event IssuerCapSet(uint16 indexed issuerId, uint128 cap)
```

Fires when an issuer cap changes.

### ReserveFactorSet

```solidity theme={"system"}
event ReserveFactorSet(uint64 reserveFactor)
```

Fires when the reserve factor changes.

### ProtocolLiqFeeShareSet

```solidity theme={"system"}
event ProtocolLiqFeeShareSet(uint64 share)
```

Fires when the protocol liquidation fee share changes.

### LiquidationParamsSet

```solidity theme={"system"}
event LiquidationParamsSet(
    uint32 auctionWindow,
    uint64 targetHealth,
    uint128 dustDebt
)
```

Fires when the auction window, target health, or dust debt change.

### DexRouterSet

```solidity theme={"system"}
event DexRouterSet(address router)
```

Fires when the DEX router changes.

### BuyAndBurnSet

```solidity theme={"system"}
event BuyAndBurnSet(
    address[] route,
    uint16 maxSlippageBps,
    uint128 maxPerCall,
    uint32 twapWindow
)
```

Fires when the buy-and-burn route or limits change.

### ZapRouteSet

```solidity theme={"system"}
event ZapRouteSet(
    address indexed token,
    address[] route,
    uint16 maxSlippageBps,
    bool allowed
)
```

Fires when a zap route is allowed, updated, or removed.

## Errors

### NotOwner

```solidity theme={"system"}
error NotOwner()
```

The caller is not the timelock.

### ZeroAddress

```solidity theme={"system"}
error ZeroAddress()
```

A required address was zero.

### ZeroId

```solidity theme={"system"}
error ZeroId()
```

A tier, issuer, or book id was zero.

### UnknownTier

```solidity theme={"system"}
error UnknownTier(uint16 id)
```

The tier id does not exist.

### UnknownBook

```solidity theme={"system"}
error UnknownBook(uint16 id)
```

The book id does not exist.

### BookAlreadyExists

```solidity theme={"system"}
error BookAlreadyExists(address collateral)
```

A book already lists this collateral token.

### InvalidLtvLt

```solidity theme={"system"}
error InvalidLtvLt(uint64 ltv, uint64 lt)
```

The effective LTV and LT do not satisfy ltv \< lt \< 1e18.

### InvalidDiscount

```solidity theme={"system"}
error InvalidDiscount(uint64 discount)
```

The max discount is 1e18 or more.

### InvalidWad

```solidity theme={"system"}
error InvalidWad(uint64 value)
```

A WAD share was above 1e18.

### InvalidKink

```solidity theme={"system"}
error InvalidKink(uint64 kink)
```

The kink is 0 or 1e18 or more.

### InvalidBps

```solidity theme={"system"}
error InvalidBps(uint16 bps)
```

A slippage value is above 10000 bps.

### InvalidRoute

```solidity theme={"system"}
error InvalidRoute()
```

A route has fewer than two hops or the TWAP window is 0.

### InvalidAuctionWindow

```solidity theme={"system"}
error InvalidAuctionWindow()
```

The auction window is 0 or longer than 7 days.

### InvalidTargetHealth

```solidity theme={"system"}
error InvalidTargetHealth()
```

The target health is below 1e18 or above 2e18.

### InvalidDust

```solidity theme={"system"}
error InvalidDust()
```

The dust threshold is 0.