# Yellow DeFi Lending/Borrowing Protocol Roadmap

## Week 1 — Skeleton + Funding Flows

**Goal:** End‑to‑end channel open → deposit → withdraw → settle.

* **Reuse:**

* ClearNode connect/auth boilerplate (JWT reuse).
* CzechOut‑style gasless payments UX for deposits/withdrawals.
* Existing `createAppSession` + signed‑JSON `app_update` helper.

* **Build:**

* State types: `Reserve`, `User`, `MarketConfig`.
* Transitions: `deposit`, `withdraw`.
* Settlement path: close & withdraw balances from escrow.
* CLI/devtools for deposits/withdrawals.

* **Deliverables:**

* Working demo repo: deposit/withdraw/settle.
* Unit tests for serialization + balance invariants.

---

## Week 2 — Interest, Borrows, Repayments

**Goal:** Implement live interest accrual and borrow/repay.

* **Reuse:**

* Reloop recurring logic for lazy interest accrual on state changes.
* Signed update flow from AMM demo.

* **Build:**

* Accrual math: `accrue()` updating borrow index & reserves.
* Shares math: `amountToShares`, `sharesToAmount`.
* Transitions: `borrow`, `repay`.
* Oracle pack stub.

* **Deliverables:**

* Scenario tests for accrual, borrow→repay round‑trip.
* Gasless repay UX.

---

## Week 3 — Risk, Liquidation, Auctions

**Goal:** Add risk controls and liquidation mechanism.

* **Reuse:**

* FlashBid auction boilerplate for collateral liquidation.
* Reloop scheduling if using periodic repayments.

* **Build:**

* Health Factor (HF) computation.
* Enforce HF on `borrow`/`withdraw`.
* Liquidation transition with `closeFactorBps` cap + `liqBonusBps` seize.
* Auction adapter: open lot → settle proceeds into reserve.
* Oracle verification (sig + freshness).

* **Deliverables:**

* HF & liquidation tests.
* Auction round‑trip (mock integration).

---

## Week 4 — Multi‑Asset + Hardening

**Goal:** Production‑ready MVP with two assets.

* **Reuse:**

* YellowConnect UI shell.
* ChainFlash Pro style routing UX patterns.

* **Build:**

* Multi‑asset support in state.
* Session keys for security.
* Settlement proofs (Merkle map optional).
* Observability: logs + metrics.

* **Deliverables:**

* Two‑asset demo (e.g. USDC collateral, WETH borrow).
* Load test script (1000 ops).
* Security checklist & runbook.

---

## Tickets

* [ ] Types: `MarketConfig`, `Reserve`, `User`, `LendingState`.
* [ ] Serialization & versioning.
* [ ] Accrual & shares math.
* [ ] Transitions: deposit, withdraw, borrow, repay, liquidate.
* [ ] Signed JSON envelopes.
* [ ] ClearNode connect/auth integration.
* [ ] Oracle verification.
* [ ] FlashBid auction adapter.
* [ ] CzechOut‑style gasless repay.
* [ ] Escrow/settlement logic.
* [ ] Unit + integration tests.
* [ ] Security review checklist.

---

## Example Message Payloads

**Borrow:**

{
  "app_session_id": "<id>",
  "payload": {
    "kind": "borrow",
    "user": "0x…",
    "asset": "USDC",
    "amount": "100000000",
    "oracle": {"priceRay": "1000000000000000000000000000", "ts": 1690000000, "signer": "0x…", "sig": "0x…"},
    "now": 1723900000
  },
  "prevNonce": 41,
  "nextNonce": 42
}

**Liquidate:**

{
  "kind": "liquidate",
  "liquidator": "0x…",
  "victim": "0x…",
  "asset": "USDC",
  "repayAmount": "50000000",
  "oracle": {"priceRay": "…", "ts": 1723900100, "signer": "0x…", "sig": "0x…"},
  "now": 1723900100
}

**Auction Result:**

{
  "kind": "auction_settle",
  "lotId": "fb-123",
  "proceedsAsset": "USDC",
  "proceeds": "51250000",
  "now": 1723900700
}