loans package

Realm loans is an unsecured term loan with a fixed installment schedule and a flat finance charge, holding real ugnot. A LENDER opens a loan to a named BORROWER by attaching the principal, which the realm disburses to the borrower in the same transaction; the borrower REPAYS over a fixed number of installments; each repayment credits the lender's pull-claimable balance, the protocol fee splitting off at the ledger. A loan whose installments go unpaid past a grace window is permissionlessly DEFAULT-able — a recorded state, not a seizure, because v1 is unsecured.

It is the one financial primitive this portfolio never had: CREDIT. The accounting realms RECORD obligations (r/invoices, r/receivables — p/aging's own doc lists "invoices, loans, dues") and the disbursement realms pay a KNOWN TOTAL out on a schedule (r/vesting, r/payroll, r/budgets). A loan is the asymmetric opposite: principal OUT once, a LARGER total back over time, plus the finance charge and the default state a disbursement realm has no use for. See onyx/r/loans/DISCOVERY.md.

Custody — the conservation invariant is the product

This is the first custodial realm the factory has selected since the publishers (r/latefees, r/cashflow), so the monetary invariant governs it exactly as it does r/subscriptions and r/meters:

1Held == Σ lender-claimable + fee pot   (== feeledger.Liabilities())

The principal is NEVER held across a transaction: Open receives it and pays it out to the borrower in the same call, so the only coins this realm ever holds are repayments awaiting the lender's Claim. A stuck or abandoned loan therefore strands no principal — it was disbursed — and the only value at risk is the lender's expected return, which is the real nature of unsecured credit and is disclosed, not engineered away.

The finance charge is FLAT in v1, and that is a scope decision

The total repayable is `principal + floor(principal × rateBps / 10000)` — a flat charge over the whole term, NOT compounding and NOT accruing per block. Per-installment is `ceil(total / installments)` with the rounding remainder on the FINAL installment, so the installments sum to exactly the total (the cross-foot). Compounding interest and a tiered-by-duration rate (which p/tiers could price) are a v2: pricing them in v1 would add an accrual surface whose bugs are the ones lending audits most often find.

Default is a state, not a seizure — there is no collateral in v1

A borrower past the grace window who has not repaid in full is Default-able by anyone (like the sibling realms' valves). It freezes the loan and records the shortfall; no coins move, because there is nothing to seize. Secured lending is a v2.

REALM-CALLER CAVEAT, inherited from the siblings: coinio's receipt guard admits only EOA payers, so the LENDER (who funds Open) and any REPAYER (who funds Repay) are EOAs. The BORROWER is a parameter — coinio.Payout delivers the principal to any valid address, including a realm — but a realm borrower could never Repay (Repay is payable, EOA-only), so naming one is the lender's own footgun (an un-repayable gift), not a realm or third-party hazard. assertNoSend reads the ORIGIN envelope, so every non-payable function refuses any transaction that attached coins anywhere.