@1delta/data-sdk 0.0.41 → 0.0.43

package/README.md

@@ -20,6 +20,57 @@ The SDK is a **read-only data layer** organized into three modules:
 
 All data is stored in a global registry (`globalThis`) so it's shared across module instances. Data is populated once via `initializeLenderData()` / `initializeChainData()` (typically called by `@1delta/initializer-sdk`) and then accessed through getter functions.
 
+### What belongs here — and what does not
+
+This package is the **address book and shape registry** for every lending deployment the stack knows about. It is deliberately tiny and dependency-free.
+
+**Belongs here**
+
+- The TypeScript **shape** of a lender's deployment metadata (config + market roster).
+- **Synchronous getters** over that data, plus cheap pure lookups on it (find market by address/id, "which lender keys exist on this chain", per-market lender-key synthesis and parsing).
+- Rare, justified **built-in seeds** for protocols whose entire roster is discovered on-chain (`RESUPPLY_ETHEREUM_CONFIG`, `CURVANCE_MONAD_CONFIG`) — published metadata always wins over them.
+
+**Does not belong here**
+
+- Network access, RPC calls, viem — fetching lives in `@1delta/margin-fetcher` and `@1delta/initializer-sdk`.
+- Rate math (`@1delta/irm-sdk`), calldata (`@1delta/calldata-sdk`), lender enums (`@1delta/lender-registry` — this package deliberately does **not** depend on it, so key-brand tests like `isSkyKey` are duplicated locally and must be kept in step).
+- Hardcoded deployment rosters. Data comes from `1delta-DAO/lender-metadata` at runtime.
+
+### Source layout
+
+`src/lending/` holds **one module per lender family**, so a change to one protocol touches one file:
+
+| File | Covers |
+|------|--------|
+| `registry.ts` | The global state: slot list, defaults, `getGlobalData()`, `initializeLenderData()`. **No runtime imports** — every other module imports from it. |
+| `common.ts` | Shapes shared by several families (`GeneralReservesMap`, `OracleMap`). |
+| `aave.ts` / `aaveV4.ts` | Aave V2/V3 + 70 forks; Aave V4 (per-spoke keys, gateways, position managers). |
+| `compoundV2.ts` / `compoundV3.ts` | cToken forks; Comet forks + bulkers. |
+| `morpho.ts` | Morpho Blue forks, oracles, MetaMorpho-shaped vault roster, Bundler3. |
+| `euler.ts`, `silo.ts`, `fluid.ts`, `gearbox.ts`, `dolomite.ts` | Euler V2; Silo v2 + v3; Fluid resolvers/vaults; Gearbox V3.1 (per-CreditManager keys); Dolomite (+ e-mode). |
+| `initProtocol.ts`, `lista.ts` | Init Capital; Lista native provider. |
+| `midnight.ts`, `term.ts`, `termMax.ts`, `exactly.ts`, `teller.ts` | Fixed-rate / fixed-term lenders. |
+| `liquity.ts`, `river.ts`, `inverse.ts`, `frankencoin.ts`, `dss.ts`, `llamalend.ts`, `resupply.ts`, `curvance.ts` | CDP-shaped lenders. `dss.ts` serves **both** USDD 2.0 and Sky from one set of types. |
+| `index.ts` | Barrel. Re-exports every module; `getGlobalData` is intentionally kept internal. |
+
+`src/chains.ts` and `src/tokens.ts` are the other two modules, unchanged by lender work.
+
+### How the registry works
+
+- One slot per data file, listed in `GlobalLenderDataRegistry` (`registry.ts`).
+- State lives on `globalThis` under a single key, so several copies of the package still share one registry.
+- Every getter reads through `getGlobalData()?.<slot>` — **never** a captured module constant. Workers re-run `initializeLenderData` per request, so a captured value goes stale. The same reasoning is why API base URLs are resolved through `resolveMidnightApiBase` / `resolveTermApiBase` / `termMaxApiBaseUrl` rather than read once.
+- Every override **replaces** its slot wholesale; omitted overrides leave the slot untouched, so partial re-initialization is safe.
+
+### Adding a lender
+
+1. Create `src/lending/<lender>.ts`: the config/market types, then the getters (`import { getGlobalData } from './registry'`).
+2. Add one line per data file to `GlobalLenderDataRegistry` **and** the matching `{}` line to `LENDER_DATA_DEFAULTS` in `registry.ts`. The `initializeLenderData` argument (`<slot>Override`) and its assignment are derived from those — nothing else to wire.
+3. Export the module from `src/lending/index.ts`.
+4. Publish the metadata files to `lender-metadata` and load them in `@1delta/initializer-sdk`.
+
+Conventions worth following: document *why* a field exists (mutability, traps, units) next to it — most fields here are snapshots of governance-mutable on-chain state; numeric fields sourced from JSON stay `string` and callers convert with `BigInt(...)`; per-market lender keys are `LENDER_<ADDRESS_HEX_UPPER>` with a matching `parse…LenderKey`; and "is this lender live on this chain" helpers gate on the one address the provider bootstraps from.
+
 ---
 
 ## Initialization
@@ -55,6 +106,40 @@ initializeChainData({
 
 All lending getters are synchronous and return data from the global registry.
 
+### Getter index
+
+Every family, with its module and its entry-point getters. The sections below document the older families in detail; for the rest, the module file is the reference — each type and field is commented there.
+
+| Family | Module | Getters |
+|--------|--------|---------|
+| Aave V2/V3 + forks | `aave.ts` | `aavePools` · `aaveTokens` · `aaveReserves` · `aaveOracles` · `aaveOraclesConfig` · `aaveWethGateway` |
+| Aave V4 | `aaveV4.ts` | `aaveV4Spokes` · `aaveV4Oracles` · `aaveV4Peripherals` · `getAaveV4SpokeEntry` · `getAaveV4GatewayAddresses` · `getAaveV4PositionManagers` · `aaveV4SpokeLenderKey` / `parseAaveV4SpokeLenderKey` |
+| Compound V2 + forks | `compoundV2.ts` | `compoundV2Pools` · `compoundV2Tokens` · `compoundV2TokenArray` · `compoundV2Reserves` · `compoundV2Oracles` · `compoundV2OraclesConfig` |
+| Compound V3 (Comet) | `compoundV3.ts` | `compoundV3Pools` · `compoundV3BaseData` · `compoundV3Reserves` · `compoundV3OraclesData` · `compoundV3Bulker` |
+| Morpho Blue + forks | `morpho.ts` | `morphoPools` · `morphoOracles` · `morphoTypeOracles` · `morphoTypeMarkets` · `morphoTypeVaults` · `morphoBundler3` |
+| Euler V2 | `euler.ts` | `eulerConfigs` · `eulerVaults` |
+| Silo v2 / v3 | `silo.ts` | `siloMarkets` · `siloPeripherals` · `siloMarketsV3` · `siloPeripheralsV3` · `getSiloV2MarketEntry` / `getSiloV3MarketEntry` · `siloV2LenderKey` / `siloV3LenderKey` (+ parsers) |
+| Fluid | `fluid.ts` | `fluidResolvers` · `fluidVaults` · `fluidChains` · `fluidVaultEntries` |
+| Gearbox V3.1 | `gearbox.ts` | `gearboxResolvers` · `gearboxChains` · `gearboxMarketCompressor` · `gearboxAddressProviderV310` · `gearboxAccountCompressor` · `gearboxBotListV3` · `gearboxMarketConfigurators` · `gearboxV3LenderKey` (+ parser) |
+| Dolomite | `dolomite.ts` | `dolomiteConfigs` · `dolomiteChains` · `dolomiteEmode` · `dolomiteMarketIdByToken` |
+| Init Capital | `initProtocol.ts` | `initConfig` |
+| Lista DAO | `lista.ts` | `listaNativeProvider` |
+| Morpho Midnight | `midnight.ts` | `midnightConfig` · `midnightMarkets(ByChain)` · `midnightMarketById` · `setMidnightApiBase` / `resolveMidnightApiBase` |
+| Term Finance | `term.ts` | `termConfig` · `termMarkets(ByChain)` · `termMarketById` · `setTermApiBase` / `resolveTermApiBase` |
+| TermMax | `termMax.ts` | `termMaxConfig(ByChain)` · `termMaxChainIds` · `termMaxApiBaseUrl` · `termMaxLenderKey` (+ parser) |
+| Exactly | `exactly.ts` | `exactlyConfig` · `exactlyMarkets(ByChain)` · `exactlyMarketByAddress` / `…ByAsset` |
+| Teller V2 | `teller.ts` | `tellerConfig(ByChain)` · `tellerPools(ByChain)` · `tellerPoolByAddress` |
+| Liquity V2 family | `liquity.ts` | `liquityConfig(For)` · `liquityMarkets` · `liquityBranchesByChain` · `liquityBranchByIndex` / `…ByTroveManager` · `liquityLendersByChain` |
+| River / Satoshi | `river.ts` | `riverConfig(For)` · `riverMarkets` · `riverChainData` · `riverMarketByIndex` · `riverLendersByChain` |
+| Inverse FiRM | `inverse.ts` | `inverseConfig(For)` · `inverseMarkets` · `inverseChainData` · `inverseMarketByAddress` · `inverseLendersByChain` |
+| Frankencoin | `frankencoin.ts` | `frankencoinConfig(For)` · `frankencoinMarkets` · `frankencoinChainData` · `frankencoinMarketByPosition` · `frankencoinLendersByChain` |
+| USDD 2.0 / Sky (dss) | `dss.ts` | `usdd*` and `sky*` getters, plus the brand-agnostic `dssConfigFor` · `dssChainData` · `dssMarketByIlk` · `dssDebtToken` · `dssDebtJoin` |
+| Curve LlamaLend | `llamalend.ts` | `llamaLendConfig(For)` · `llamaLendChainData` · `llamaLendMarketByController` / `…ByVault` · `llamaLendSupportsDelegation` / `…SupportsLeverage` · `llamaLendLeverageZap` · `llamaLendLenderKey` (+ parser) |
+| Resupply | `resupply.ts` | `resupplyConfig(For)` · `resupplyLendersByChain` · `RESUPPLY_ETHEREUM_CONFIG` |
+| Curvance | `curvance.ts` | `curvanceConfig(For)` · `curvanceLendersByChain` · `curvancePositionManager(sFor)` · `CURVANCE_MONAD_CONFIG` |
+
+---
+
 ### Aave (V2 / V3 / all forks)
 
 Covers: AAVE_V3, SPARK, LENDLE, ZEROLEND, AVALON, RADIANT_V2, KINZA, YLDR, and 70+ other forks.
@@ -691,3 +776,34 @@ All deployment data originates from the `1delta-DAO/lender-metadata` GitHub repo
 | `data/euler-vaults.json` | `eulerVaults()` |
 | `config/midnight.json` | `midnightConfig()` |
 | `data/midnight-markets.json` | `midnightMarkets()` |
+| `config/aave-oracles-config.json` | `aaveOraclesConfig()` |
+| `config/compound-v2-oracles-config.json` | `compoundV2OraclesConfig()` |
+| `config/aave-weth-gateway.json` | `aaveWethGateway()` |
+| `data/aave-oracles.json` / `data/compound-v2-oracles.json` | `aaveOracles()` / `compoundV2Oracles()` |
+| `data/compound-v3-oracles-data.json` | `compoundV3OraclesData()` |
+| `data/compound-v3-bulkers.json` | `compoundV3Bulker()` |
+| `config/morpho-type-markets.json` | `morphoTypeMarkets()` |
+| `data/morpho-oracles.json` / `data/morpho-type-oracles.json` | `morphoOracles()` / `morphoTypeOracles()` |
+| `data/morpho-type-vaults.json` | `morphoTypeVaults()` |
+| `data/morpho-bundler3.json` | `morphoBundler3()` |
+| `data/init-config.json` | `initConfig()` |
+| `data/lista-providers.json` | `listaNativeProvider()` |
+| `data/aave-v4-spokes.json` / `data/aave-v4-oracles.json` / `config/aave-v4-peripherals.json` | `aaveV4Spokes()` / `aaveV4Oracles()` / `aaveV4Peripherals()` |
+| `config/silo-v2-peripherals.json` / `data/silo-v2-markets.json` | `siloPeripherals()` / `siloMarkets()` |
+| `config/silo-v3-peripherals.json` / `data/silo-v3-markets.json` | `siloPeripheralsV3()` / `siloMarketsV3()` |
+| `config/fluid-resolvers.json` / `data/fluid-vaults.json` | `fluidResolvers()` / `fluidVaults()` |
+| `config/gearbox-resolvers.json` | `gearboxResolvers()` |
+| `config/dolomite-margin.json` / `config/dolomite-emode.json` | `dolomiteConfigs()` / `dolomiteEmode()` |
+| `config/term-finance.json` / `data/term-finance-markets.json` | `termConfig()` / `termMarkets()` |
+| `config/termmax.json` | `termMaxConfig()` |
+| `config/exactly.json` / `data/exactly-markets.json` | `exactlyConfig()` / `exactlyMarkets()` |
+| `config/teller.json` / `data/teller-pools.json` | `tellerConfig()` / `tellerPools()` |
+| `config/liquity.json` / `data/liquity-markets.json` | `liquityConfig()` / `liquityMarkets()` |
+| `config/river.json` / `data/river-markets.json` | `riverConfig()` / `riverMarkets()` |
+| `config/inverse.json` / `data/inverse-markets.json` | `inverseConfig()` / `inverseMarkets()` |
+| `config/frankencoin.json` / `data/frankencoin-markets.json` | `frankencoinConfig()` / `frankencoinMarkets()` |
+| `config/usdd.json` / `data/usdd-markets.json` | `usddConfig()` / `usddMarkets()` |
+| `config/sky.json` / `data/sky-markets.json` | `skyConfig()` / `skyMarkets()` |
+| `config/llamalend.json` / `data/llamalend-markets.json` | `llamaLendConfig()` / `llamaLendMarkets()` |
+| `config/resupply.json` | `resupplyConfig()` — built-in Ethereum seed if unpublished |
+| `config/curvance.json` | `curvanceConfig()` — built-in Monad seed if unpublished |