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

# Entities & Reads

> The typed model behind every read — loans, positions, venues and bond curves, with contract-exact math that runs offline.

Every read in the SDK returns an **entity**: a typed class defined in [`@iris-credit/core-sdk`](https://www.npmjs.com/package/@iris-credit/core-sdk) whose derived values mirror the Iris contracts exactly. The math is framework-agnostic and runs offline — positions can be projected to arbitrary timestamps without an RPC; `viem` is only needed to hydrate entities from the chain.

| Entity            | Represents                                                                                                               |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `Loan`            | The immutable terms of a loan                                                                                            |
| `Position`        | The stored state of a loan's position, as of its `lastUpdate`                                                            |
| `AccrualPosition` | A position paired with its loan and its venue, for derived and accrued values                                            |
| `Venue`           | A venue's view of a pod — indices, price, LLTV and the pod's assets — implemented by `MorphoBlueVenue` and `AaveV3Venue` |
| `Blm`             | A bond liquidity manager's bond parameters for one debt token                                                            |
| `Config`          | The mutable protocol-level Iris configuration                                                                            |
| `Token`           | An ERC-20 token                                                                                                          |
| `Holding`         | A user's balance and allowance state for one token                                                                       |
| `User`            | A user of Iris                                                                                                           |

## Reading through the entity

The `client.iris.core(chainId)` entity exposes one getter per input a flow takes. Flows are fetch-first, so one fetch can feed several builds and a stale build never hides a fetch:

```typescript theme={null}
const loanData = await iris.getLoanData(pod); // the pod's Loan — parties, tokens, terms.
const positionData = await iris.getPositionData(pod); // AccrualPosition — position + loan + venue.
const claimableData = await iris.getClaimableData(account, token); // claimable balance (bigint).
const newVenue = await iris.getVenueData({ loanData, venueId, data }); // a venue's live view of the pod.
```

Every getter accepts optional `FetchParameters` (`blockNumber`, `blockTag`, `stateOverride`) for historical or state-overridden reads.

<Tip>
  `getPositionData` reads the whole venue state. Prefer `getLoanData` for flows that only need the loan, and hand an `AccrualPosition`'s `.loan` to those flows instead of re-fetching.
</Tip>

Outside the entity, every fetcher is also exported standalone from `@iris-credit/core-sdk` (`fetchLoan`, `fetchAccrualPosition`, `fetchVenue`, `fetchBlm`, …) — or, by importing `@iris-credit/core-sdk/augment` once, attached to each entity class as a `fetch` static:

```typescript theme={null}
import { AccrualPosition } from "@iris-credit/core-sdk/augment";

const position = await AccrualPosition.fetch(pod, client);
```

## Offline math

`AccrualPosition` carries the whole position model. Health, repay pricing and withdraw ceilings are plain property reads, and `accrueLegs(timestamp)` projects the position — venue indices included, using the venue's own rate model — to any timestamp:

```typescript theme={null}
import { Time } from "@iris-credit/iris-ts";

const position = await iris.getPositionData(pod);

position.isHealthy; // Iris's health check — worst-case payoff within the venue LLTV.
position.isHealthyVenue; // the venue's own check.
position.isHealthyBond; // the solver's bond against the loan's bond LLTV.
position.withdrawableCollateral; // the maximum withdrawable, in collateral assets.

const accrued = position.accrueLegs(Time.timestamp());

accrued.fixedLeg; // interest owed at the loan's fixed rate, in debt assets.
accrued.floatingLeg; // interest the venue charged, in debt assets.
accrued.repayAmount; // what a full repay costs, in debt assets.
```

Onchain operations are mirrored as pure transitions returning a new position — `repay`, `liquidate`, `liquidateBond`, `supplyCollateral`, `withdrawCollateral`, `supplyBond`, `withdrawBond` and `refinance` — each accruing and rebasing exactly as Iris does:

```typescript theme={null}
const { position: repaid, repaid: debtAssets } = position.repay(Time.timestamp());

debtAssets; // pulled from the payer, in debt assets.
repaid.bondRequirement; // 0n — the loan is resolved.
```

<Warning>
  Venue fields are live onchain observations and must come from the block being evaluated. Position math composed with stale venue data (old indices, an old price) silently diverges from Iris's onchain results.
</Warning>

## Units & precision

The SDK follows the same conventions as the [Iris API](/api/get-started):

* **Rates, LLTVs and fees are WAD-scaled** (`1e18`). A `fixedRate` of `81000000000000000n` is 8.1% simple annual interest.
* **Amounts are in the token's own decimals** — read `decimals` off a fetched `Token`.
* **Everything is `bigint`.** No floats anywhere; format for display with `@iris-credit/iris-ts`'s `format` helpers.

<Note>
  The contracts store rates and LLTVs BP-compressed (`1e14`) to fit small integer slots. The fetchers rescale them to WAD on the way in — only a raw `Iris.getLoan` call returns the compressed values.
</Note>

## Bond requirements

`Blm` computes the bond a quote requires without a `bondRequirement` contract call:

```typescript theme={null}
import { Blm } from "@iris-credit/core-sdk/augment";
import { Time } from "@iris-credit/iris-ts";

const blm = await Blm.fetch(
  blmAddress, // e.g. quote.blm.
  debtToken, // the quote's debt token.
  client,
);

blm.bondRequirement({ debt: 50_000_000000n, duration: Time.s.from.d(30n) }); // in debt assets.
```

## Addresses & registries

Two static, per-chain sources ship with the SDK, both narrowed to the exact chain by their getter:

* **`getChainAddresses(chainId)`** — what is **deployed**: the Iris core, BLMs, bundler adapters, venue adapters and common tokens.
* **`getChainRegistry(chainId)`** — what is **enabled** on the Iris contract: venue ids, accepted bond LLTVs, and the market data payloads (recorded as preimages, since the contract only stores `keccak256(data)`).

```typescript theme={null}
import { ChainId, getChainAddresses, getChainRegistry } from "@iris-credit/core-sdk";

const { iris, blm, morphoBlueAdapter, tokens } = getChainAddresses(ChainId.EthMainnet);
const { venues, bondLltvs, marketDatas } = getChainRegistry(ChainId.EthMainnet);

venues.morphoBlue; // 1n
bondLltvs; // [900000000000000000n] — 90%.
marketDatas["morphoBlue:cbBTC/USDC"].data; // the enabled abi.encode(MarketParams) payload.
```

Enablement is append-only onchain, so registry entries can only ever be stale-incomplete — never stale-wrong. Solvers can quote from the registry offline, while the fetchers re-verify mutable state (BLM params, whitelist entries, fee) at runtime.

<Note>
  Both sources are compile-time constants — supporting a new chain means a new SDK release. Fetchers that resolve a contract from the registry throw `UnsupportedChainIdError` on an unknown chain.
</Note>

## EIP-712 payloads

The signature builders return typed data ready for viem's `signTypedData` — the same payloads Iris verifies onchain:

* `getQuoteTypedData(chainId, quote)` — a solver's `Quote`, consumed by `take`
* `getAuthorizationTypedData(chainId, authorization)` — granting or revoking a manager on Iris
* `getPermitTypedData(args, chainId)` — an ERC-2612 permit
* `getPermit2PermitTypedData(args, chainId)` — a Permit2 allowance (`PermitSingle`)
* `getPermit2TransferFromTypedData(args, chainId)` — a Permit2 signature transfer

Most integrations never touch these directly: [transaction flows](/sdk/transactions) collect signatures through their requirements, and [`signResponse`](/sdk/solver-signing) wraps the solver side.