@1delta/data-sdk 0.0.46 → 0.0.48

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export * from './chains';
 export * from './lending';
+export * from './remoteCache';
 export * from './tokens';

package/dist/index.js

@@ -95,6 +95,8 @@ var LENDER_DATA_DEFAULTS = () => ({
   llamaLendMarkets: {},
   resupplyConfig: {},
   curvanceConfig: {},
+  twyneConfig: {},
+  twyneMarkets: {},
   fraxlendConfig: {},
   eulerConfigs: {},
   eulerVaults: {},
@@ -745,6 +747,60 @@ var curvancePositionManager = (lender, chainId, marketManager, kind) => {
   return pms.simplePositionManager ?? pms.vaultPositionManager ?? pms.nativeVaultPositionManager ?? pms.pendlePtPositionManager;
 };
 
+// src/lending/twyne.ts
+var twyneConfig = () => getGlobalData2()?.twyneConfig;
+var twyneConfigFor = (lender, chainId) => getGlobalData2()?.twyneConfig?.[twyneBaseKey(lender)]?.[String(chainId)];
+var twyneMarkets = () => getGlobalData2()?.twyneMarkets;
+var twyneChainData = (lender, chainId) => getGlobalData2()?.twyneMarkets?.[twyneBaseKey(lender)]?.[String(chainId)];
+var twyneBaseKey = (lender) => lender?.startsWith("TWYNE") ? "TWYNE" : lender;
+var twyneMarketKey = (chainId, intermediateVault, targetAsset) => `TWYNE_${chainId}_${intermediateVault.replace(/^0x/i, "").toUpperCase()}_${targetAsset.replace(/^0x/i, "").toUpperCase()}`;
+var assertTwyneKeysUnique = (markets, chainId) => {
+  const byKey = /* @__PURE__ */ new Map();
+  for (const m of markets) {
+    const key = twyneMarketKey(chainId, m.intermediateVault, m.targetAsset);
+    const triple = `${m.intermediateVault}|${m.targetVault}|${m.targetAsset}`.toLowerCase();
+    const seen = byKey.get(key);
+    if (seen && seen !== triple) {
+      throw new Error(
+        `assertTwyneKeysUnique: key ${key} maps to two triples (${seen} and ${triple}). The target vault must be added back into the key.`
+      );
+    }
+    byKey.set(key, triple);
+  }
+};
+var twyneMarketByKey = (lender, chainId) => {
+  const upper = lender?.toUpperCase();
+  return twyneChainData(lender, chainId)?.markets?.find((m) => m.key.toUpperCase() === upper);
+};
+var twyneMarketFor = (lender, chainId, intermediateVault, targetAsset) => {
+  const iv = intermediateVault?.toLowerCase();
+  const asset = targetAsset?.toLowerCase();
+  return twyneChainData(lender, chainId)?.markets?.find(
+    (m) => m.intermediateVault.toLowerCase() === iv && m.targetAsset.toLowerCase() === asset
+  );
+};
+var twyneMarketsForIntermediateVault = (lender, chainId, intermediateVault) => {
+  const iv = intermediateVault?.toLowerCase();
+  return (twyneChainData(lender, chainId)?.markets ?? []).filter((m) => m.intermediateVault.toLowerCase() === iv);
+};
+var twyneLendersByChain = (chainId) => {
+  const cfg = getGlobalData2()?.twyneConfig ?? {};
+  const chain = String(chainId);
+  return Object.keys(cfg).filter((lender) => !!cfg[lender]?.[chain]?.collateralVaultFactory);
+};
+var twyneOperator = (lender, chainId, vaultType, kind) => twyneConfigFor(lender, chainId)?.operators?.[vaultType]?.[kind];
+var twyneBeaconFor = (lender, chainId, targetVault) => {
+  const map = twyneConfigFor(lender, chainId)?.beacons;
+  if (!map || !targetVault) return void 0;
+  const direct = map[targetVault];
+  if (direct) return direct;
+  const target = targetVault.toLowerCase();
+  for (const key of Object.keys(map)) {
+    if (key.toLowerCase() === target) return map[key];
+  }
+  return void 0;
+};
+
 // src/lending/fraxlend.ts
 var FRAXLEND_ETHEREUM_CONFIG = {
   deployer: "0xD6E9D27C75Afd88ad24Cd5EdccdC76fd2fc3A751",
@@ -862,12 +918,143 @@ var parseFraxlendPairKey = (lender) => {
   return { chainId: m[1], pair: m[2].toLowerCase() };
 };
 
+// src/remoteCache.ts
+var FRESH_TTL_MS = 5 * 60 * 1e3;
+var REMOTE_CACHE_STORE_TTL_S = 7 * 24 * 60 * 60;
+var STATE_KEY = "__1delta_remote_cache__";
+function getState() {
+  const g = globalThis;
+  if (!g[STATE_KEY]) g[STATE_KEY] = { memo: /* @__PURE__ */ new Map(), inflight: /* @__PURE__ */ new Map() };
+  return g[STATE_KEY];
+}
+function setRemoteCacheStore(next) {
+  getState().store = next;
+}
+function setRemoteCacheGithubToken(token) {
+  getState().githubToken = token;
+}
+function clearRemoteCache() {
+  const state = getState();
+  state.memo.clear();
+  state.inflight.clear();
+}
+var RAW_HOST = "https://raw.githubusercontent.com/";
+function githubApiMirror(url) {
+  if (!url.startsWith(RAW_HOST)) return void 0;
+  const [owner, repo, ref, ...path] = url.slice(RAW_HOST.length).split("/");
+  if (!owner || !repo || !ref || path.length === 0) return void 0;
+  return `https://api.github.com/repos/${owner}/${repo}/contents/${path.join("/")}?ref=${ref}`;
+}
+var RemoteFetchError = class extends Error {
+  constructor(message, status) {
+    super(message);
+    this.status = status;
+    this.name = "RemoteFetchError";
+  }
+  /** 404/410 — re-fetching cannot change the answer. */
+  get isMissing() {
+    return this.status === 404 || this.status === 410;
+  }
+};
+async function fetchRemoteJson(url, label) {
+  const res = await fetch(url);
+  if (res.ok) return await res.json();
+  const mirror = githubApiMirror(url);
+  const worthRetrying = res.status === 429 || res.status >= 500;
+  if (!mirror || !worthRetrying) {
+    throw new RemoteFetchError(`${label} fetch failed: HTTP ${res.status} from ${new URL(url).host}`, res.status);
+  }
+  const headers = {
+    Accept: "application/vnd.github.raw",
+    // The GitHub API rejects a request that sends no User-Agent.
+    "User-Agent": "1delta-data-sdk"
+  };
+  const token = getState().githubToken;
+  if (token) headers.Authorization = `Bearer ${token}`;
+  const viaApi = await fetch(mirror, { headers });
+  if (!viaApi.ok) {
+    throw new RemoteFetchError(
+      `${label} fetch failed: HTTP ${res.status} from raw.githubusercontent.com, HTTP ${viaApi.status} from api.github.com`,
+      res.status
+    );
+  }
+  return await viaApi.json();
+}
+var storeKey = (key) => `remote-cache:v1:${key}`;
+async function readStore(key, isValid) {
+  const { store } = getState();
+  if (!store) return void 0;
+  try {
+    const raw = await store.get(storeKey(key));
+    if (!raw) return void 0;
+    const parsed = JSON.parse(raw);
+    if (typeof parsed?.at !== "number" || !isValid(parsed.value)) return void 0;
+    return parsed;
+  } catch {
+    return void 0;
+  }
+}
+async function writeStore(key, entry) {
+  const { store } = getState();
+  if (!store) return;
+  try {
+    await store.put(storeKey(key), JSON.stringify(entry), REMOTE_CACHE_STORE_TTL_S);
+  } catch {
+  }
+}
+async function loadCached(key, load, isValid) {
+  const { memo, inflight } = getState();
+  const cached = memo.get(key);
+  if (cached && Date.now() - cached.at < FRESH_TTL_MS) return cached.value;
+  const pending = inflight.get(key);
+  if (pending) return pending;
+  const task = (async () => {
+    const stored = await readStore(key, isValid);
+    if (stored && Date.now() - stored.at < FRESH_TTL_MS) {
+      memo.set(key, stored);
+      return stored.value;
+    }
+    try {
+      const value = await load();
+      const entry = { at: Date.now(), value };
+      memo.set(key, entry);
+      await writeStore(key, entry);
+      return value;
+    } catch (error) {
+      const stale = memo.get(key) ?? stored;
+      if (!stale) throw error;
+      memo.set(key, stale);
+      return stale.value;
+    }
+  })().finally(() => {
+    inflight.delete(key);
+  });
+  inflight.set(key, task);
+  return task;
+}
+async function loadCachedJson(key, url, isValid, label = key) {
+  return loadCached(key, () => fetchRemoteJson(url, label), isValid);
+}
+
 // src/tokens.ts
 var getListUrl = (chainId) => `https://raw.githubusercontent.com/1delta-DAO/token-lists/main/${chainId}.json`;
+var MAIN_TOKENS_URL = "https://raw.githubusercontent.com/1delta-DAO/token-lists/main/main-tokens.json";
+var isTokenListFile = (value) => !!value?.list && typeof value.list === "object";
+async function loadTokenListFile(chainId) {
+  return loadCached(
+    `token-list:${chainId}`,
+    async () => {
+      const json = await fetchRemoteJson(getListUrl(chainId), `Token list for chain ${chainId}`);
+      return {
+        list: json.list,
+        mainTokens: json.mainTokens ?? []
+      };
+    },
+    isTokenListFile
+  );
+}
 async function fetchTokenList(chainId) {
-  const data = await fetch(getListUrl(chainId));
-  if (!data.ok) throw new Error(`HTTP error! status: ${data.status}`);
-  return (await data.json()).list;
+  return (await loadTokenListFile(chainId)).list;
 }
 async function fetchTokenLists(chainIds) {
   const promises = chainIds.map(async (chainId) => {
@@ -878,25 +1065,27 @@ async function fetchTokenLists(chainIds) {
   return Object.fromEntries(results);
 }
 async function fetchTokenListFile(chainId) {
-  const data = await fetch(getListUrl(chainId));
-  if (!data.ok) throw new Error(`HTTP error! status: ${data.status}`);
-  const json = await data.json();
-  return {
-    list: json.list,
-    mainTokens: json.mainTokens ?? []
-  };
+  const file = await loadTokenListFile(chainId);
+  return { list: file.list, mainTokens: file.mainTokens };
 }
-var MAIN_TOKENS_URL = "https://raw.githubusercontent.com/1delta-DAO/token-lists/main/main-tokens.json";
 async function fetchMainTokensMap() {
-  const data = await fetch(MAIN_TOKENS_URL);
-  if (!data.ok) return void 0;
-  return await data.json();
+  try {
+    return await loadCached(
+      "main-tokens",
+      () => fetchRemoteJson(MAIN_TOKENS_URL, "main-tokens"),
+      (value) => !!value && typeof value === "object"
+    );
+  } catch {
+    return void 0;
+  }
 }
 
 exports.CURVANCE_MONAD_CONFIG = CURVANCE_MONAD_CONFIG;
 exports.FRAXLEND_ETHEREUM_CONFIG = FRAXLEND_ETHEREUM_CONFIG;
 exports.GEARBOX_ACCOUNT_COMPRESSOR_V310 = GEARBOX_ACCOUNT_COMPRESSOR_V310;
+exports.REMOTE_CACHE_STORE_TTL_S = REMOTE_CACHE_STORE_TTL_S;
 exports.RESUPPLY_ETHEREUM_CONFIG = RESUPPLY_ETHEREUM_CONFIG;
+exports.RemoteFetchError = RemoteFetchError;
 exports.aaveOracles = aaveOracles;
 exports.aaveOraclesConfig = aaveOraclesConfig;
 exports.aavePools = aavePools;
@@ -907,8 +1096,10 @@ exports.aaveV4Peripherals = aaveV4Peripherals;
 exports.aaveV4SpokeLenderKey = aaveV4SpokeLenderKey;
 exports.aaveV4Spokes = aaveV4Spokes;
 exports.aaveWethGateway = aaveWethGateway;
+exports.assertTwyneKeysUnique = assertTwyneKeysUnique;
 exports.chainLogoURI = chainLogoURI;
 exports.chains = chains;
+exports.clearRemoteCache = clearRemoteCache;
 exports.compoundV2Oracles = compoundV2Oracles;
 exports.compoundV2OraclesConfig = compoundV2OraclesConfig;
 exports.compoundV2Pools = compoundV2Pools;
@@ -942,6 +1133,7 @@ exports.exactlyMarketByAsset = exactlyMarketByAsset;
 exports.exactlyMarkets = exactlyMarkets;
 exports.exactlyMarketsByChain = exactlyMarketsByChain;
 exports.fetchMainTokensMap = fetchMainTokensMap;
+exports.fetchRemoteJson = fetchRemoteJson;
 exports.fetchTokenList = fetchTokenList;
 exports.fetchTokenListFile = fetchTokenListFile;
 exports.fetchTokenLists = fetchTokenLists;
@@ -1011,6 +1203,8 @@ exports.llamaLendMarketByVault = llamaLendMarketByVault;
 exports.llamaLendMarkets = llamaLendMarkets;
 exports.llamaLendSupportsDelegation = llamaLendSupportsDelegation;
 exports.llamaLendSupportsLeverage = llamaLendSupportsLeverage;
+exports.loadCached = loadCached;
+exports.loadCachedJson = loadCachedJson;
 exports.midnightApiBaseOverride = midnightApiBaseOverride;
 exports.midnightConfig = midnightConfig;
 exports.midnightMarketById = midnightMarketById;
@@ -1041,6 +1235,8 @@ exports.riverLendersByChain = riverLendersByChain;
 exports.riverMarketByIndex = riverMarketByIndex;
 exports.riverMarkets = riverMarkets;
 exports.setMidnightApiBase = setMidnightApiBase;
+exports.setRemoteCacheGithubToken = setRemoteCacheGithubToken;
+exports.setRemoteCacheStore = setRemoteCacheStore;
 exports.setTermApiBase = setTermApiBase;
 exports.siloMarkets = siloMarkets;
 exports.siloMarketsV3 = siloMarketsV3;
@@ -1068,6 +1264,18 @@ exports.termMaxChainIds = termMaxChainIds;
 exports.termMaxConfig = termMaxConfig;
 exports.termMaxConfigByChain = termMaxConfigByChain;
 exports.termMaxLenderKey = termMaxLenderKey;
+exports.twyneBaseKey = twyneBaseKey;
+exports.twyneBeaconFor = twyneBeaconFor;
+exports.twyneChainData = twyneChainData;
+exports.twyneConfig = twyneConfig;
+exports.twyneConfigFor = twyneConfigFor;
+exports.twyneLendersByChain = twyneLendersByChain;
+exports.twyneMarketByKey = twyneMarketByKey;
+exports.twyneMarketFor = twyneMarketFor;
+exports.twyneMarketKey = twyneMarketKey;
+exports.twyneMarkets = twyneMarkets;
+exports.twyneMarketsForIntermediateVault = twyneMarketsForIntermediateVault;
+exports.twyneOperator = twyneOperator;
 exports.usddChainData = usddChainData;
 exports.usddConfig = usddConfig;
 exports.usddConfigFor = usddConfigFor;

package/dist/index.mjs

@@ -93,6 +93,8 @@ var LENDER_DATA_DEFAULTS = () => ({
   llamaLendMarkets: {},
   resupplyConfig: {},
   curvanceConfig: {},
+  twyneConfig: {},
+  twyneMarkets: {},
   fraxlendConfig: {},
   eulerConfigs: {},
   eulerVaults: {},
@@ -743,6 +745,60 @@ var curvancePositionManager = (lender, chainId, marketManager, kind) => {
   return pms.simplePositionManager ?? pms.vaultPositionManager ?? pms.nativeVaultPositionManager ?? pms.pendlePtPositionManager;
 };
 
+// src/lending/twyne.ts
+var twyneConfig = () => getGlobalData2()?.twyneConfig;
+var twyneConfigFor = (lender, chainId) => getGlobalData2()?.twyneConfig?.[twyneBaseKey(lender)]?.[String(chainId)];
+var twyneMarkets = () => getGlobalData2()?.twyneMarkets;
+var twyneChainData = (lender, chainId) => getGlobalData2()?.twyneMarkets?.[twyneBaseKey(lender)]?.[String(chainId)];
+var twyneBaseKey = (lender) => lender?.startsWith("TWYNE") ? "TWYNE" : lender;
+var twyneMarketKey = (chainId, intermediateVault, targetAsset) => `TWYNE_${chainId}_${intermediateVault.replace(/^0x/i, "").toUpperCase()}_${targetAsset.replace(/^0x/i, "").toUpperCase()}`;
+var assertTwyneKeysUnique = (markets, chainId) => {
+  const byKey = /* @__PURE__ */ new Map();
+  for (const m of markets) {
+    const key = twyneMarketKey(chainId, m.intermediateVault, m.targetAsset);
+    const triple = `${m.intermediateVault}|${m.targetVault}|${m.targetAsset}`.toLowerCase();
+    const seen = byKey.get(key);
+    if (seen && seen !== triple) {
+      throw new Error(
+        `assertTwyneKeysUnique: key ${key} maps to two triples (${seen} and ${triple}). The target vault must be added back into the key.`
+      );
+    }
+    byKey.set(key, triple);
+  }
+};
+var twyneMarketByKey = (lender, chainId) => {
+  const upper = lender?.toUpperCase();
+  return twyneChainData(lender, chainId)?.markets?.find((m) => m.key.toUpperCase() === upper);
+};
+var twyneMarketFor = (lender, chainId, intermediateVault, targetAsset) => {
+  const iv = intermediateVault?.toLowerCase();
+  const asset = targetAsset?.toLowerCase();
+  return twyneChainData(lender, chainId)?.markets?.find(
+    (m) => m.intermediateVault.toLowerCase() === iv && m.targetAsset.toLowerCase() === asset
+  );
+};
+var twyneMarketsForIntermediateVault = (lender, chainId, intermediateVault) => {
+  const iv = intermediateVault?.toLowerCase();
+  return (twyneChainData(lender, chainId)?.markets ?? []).filter((m) => m.intermediateVault.toLowerCase() === iv);
+};
+var twyneLendersByChain = (chainId) => {
+  const cfg = getGlobalData2()?.twyneConfig ?? {};
+  const chain = String(chainId);
+  return Object.keys(cfg).filter((lender) => !!cfg[lender]?.[chain]?.collateralVaultFactory);
+};
+var twyneOperator = (lender, chainId, vaultType, kind) => twyneConfigFor(lender, chainId)?.operators?.[vaultType]?.[kind];
+var twyneBeaconFor = (lender, chainId, targetVault) => {
+  const map = twyneConfigFor(lender, chainId)?.beacons;
+  if (!map || !targetVault) return void 0;
+  const direct = map[targetVault];
+  if (direct) return direct;
+  const target = targetVault.toLowerCase();
+  for (const key of Object.keys(map)) {
+    if (key.toLowerCase() === target) return map[key];
+  }
+  return void 0;
+};
+
 // src/lending/fraxlend.ts
 var FRAXLEND_ETHEREUM_CONFIG = {
   deployer: "0xD6E9D27C75Afd88ad24Cd5EdccdC76fd2fc3A751",
@@ -860,12 +916,143 @@ var parseFraxlendPairKey = (lender) => {
   return { chainId: m[1], pair: m[2].toLowerCase() };
 };
 
+// src/remoteCache.ts
+var FRESH_TTL_MS = 5 * 60 * 1e3;
+var REMOTE_CACHE_STORE_TTL_S = 7 * 24 * 60 * 60;
+var STATE_KEY = "__1delta_remote_cache__";
+function getState() {
+  const g = globalThis;
+  if (!g[STATE_KEY]) g[STATE_KEY] = { memo: /* @__PURE__ */ new Map(), inflight: /* @__PURE__ */ new Map() };
+  return g[STATE_KEY];
+}
+function setRemoteCacheStore(next) {
+  getState().store = next;
+}
+function setRemoteCacheGithubToken(token) {
+  getState().githubToken = token;
+}
+function clearRemoteCache() {
+  const state = getState();
+  state.memo.clear();
+  state.inflight.clear();
+}
+var RAW_HOST = "https://raw.githubusercontent.com/";
+function githubApiMirror(url) {
+  if (!url.startsWith(RAW_HOST)) return void 0;
+  const [owner, repo, ref, ...path] = url.slice(RAW_HOST.length).split("/");
+  if (!owner || !repo || !ref || path.length === 0) return void 0;
+  return `https://api.github.com/repos/${owner}/${repo}/contents/${path.join("/")}?ref=${ref}`;
+}
+var RemoteFetchError = class extends Error {
+  constructor(message, status) {
+    super(message);
+    this.status = status;
+    this.name = "RemoteFetchError";
+  }
+  /** 404/410 — re-fetching cannot change the answer. */
+  get isMissing() {
+    return this.status === 404 || this.status === 410;
+  }
+};
+async function fetchRemoteJson(url, label) {
+  const res = await fetch(url);
+  if (res.ok) return await res.json();
+  const mirror = githubApiMirror(url);
+  const worthRetrying = res.status === 429 || res.status >= 500;
+  if (!mirror || !worthRetrying) {
+    throw new RemoteFetchError(`${label} fetch failed: HTTP ${res.status} from ${new URL(url).host}`, res.status);
+  }
+  const headers = {
+    Accept: "application/vnd.github.raw",
+    // The GitHub API rejects a request that sends no User-Agent.
+    "User-Agent": "1delta-data-sdk"
+  };
+  const token = getState().githubToken;
+  if (token) headers.Authorization = `Bearer ${token}`;
+  const viaApi = await fetch(mirror, { headers });
+  if (!viaApi.ok) {
+    throw new RemoteFetchError(
+      `${label} fetch failed: HTTP ${res.status} from raw.githubusercontent.com, HTTP ${viaApi.status} from api.github.com`,
+      res.status
+    );
+  }
+  return await viaApi.json();
+}
+var storeKey = (key) => `remote-cache:v1:${key}`;
+async function readStore(key, isValid) {
+  const { store } = getState();
+  if (!store) return void 0;
+  try {
+    const raw = await store.get(storeKey(key));
+    if (!raw) return void 0;
+    const parsed = JSON.parse(raw);
+    if (typeof parsed?.at !== "number" || !isValid(parsed.value)) return void 0;
+    return parsed;
+  } catch {
+    return void 0;
+  }
+}
+async function writeStore(key, entry) {
+  const { store } = getState();
+  if (!store) return;
+  try {
+    await store.put(storeKey(key), JSON.stringify(entry), REMOTE_CACHE_STORE_TTL_S);
+  } catch {
+  }
+}
+async function loadCached(key, load, isValid) {
+  const { memo, inflight } = getState();
+  const cached = memo.get(key);
+  if (cached && Date.now() - cached.at < FRESH_TTL_MS) return cached.value;
+  const pending = inflight.get(key);
+  if (pending) return pending;
+  const task = (async () => {
+    const stored = await readStore(key, isValid);
+    if (stored && Date.now() - stored.at < FRESH_TTL_MS) {
+      memo.set(key, stored);
+      return stored.value;
+    }
+    try {
+      const value = await load();
+      const entry = { at: Date.now(), value };
+      memo.set(key, entry);
+      await writeStore(key, entry);
+      return value;
+    } catch (error) {
+      const stale = memo.get(key) ?? stored;
+      if (!stale) throw error;
+      memo.set(key, stale);
+      return stale.value;
+    }
+  })().finally(() => {
+    inflight.delete(key);
+  });
+  inflight.set(key, task);
+  return task;
+}
+async function loadCachedJson(key, url, isValid, label = key) {
+  return loadCached(key, () => fetchRemoteJson(url, label), isValid);
+}
+
 // src/tokens.ts
 var getListUrl = (chainId) => `https://raw.githubusercontent.com/1delta-DAO/token-lists/main/${chainId}.json`;
+var MAIN_TOKENS_URL = "https://raw.githubusercontent.com/1delta-DAO/token-lists/main/main-tokens.json";
+var isTokenListFile = (value) => !!value?.list && typeof value.list === "object";
+async function loadTokenListFile(chainId) {
+  return loadCached(
+    `token-list:${chainId}`,
+    async () => {
+      const json = await fetchRemoteJson(getListUrl(chainId), `Token list for chain ${chainId}`);
+      return {
+        list: json.list,
+        mainTokens: json.mainTokens ?? []
+      };
+    },
+    isTokenListFile
+  );
+}
 async function fetchTokenList(chainId) {
-  const data = await fetch(getListUrl(chainId));
-  if (!data.ok) throw new Error(`HTTP error! status: ${data.status}`);
-  return (await data.json()).list;
+  return (await loadTokenListFile(chainId)).list;
 }
 async function fetchTokenLists(chainIds) {
   const promises = chainIds.map(async (chainId) => {
@@ -876,19 +1063,19 @@ async function fetchTokenLists(chainIds) {
   return Object.fromEntries(results);
 }
 async function fetchTokenListFile(chainId) {
-  const data = await fetch(getListUrl(chainId));
-  if (!data.ok) throw new Error(`HTTP error! status: ${data.status}`);
-  const json = await data.json();
-  return {
-    list: json.list,
-    mainTokens: json.mainTokens ?? []
-  };
+  const file = await loadTokenListFile(chainId);
+  return { list: file.list, mainTokens: file.mainTokens };
 }
-var MAIN_TOKENS_URL = "https://raw.githubusercontent.com/1delta-DAO/token-lists/main/main-tokens.json";
 async function fetchMainTokensMap() {
-  const data = await fetch(MAIN_TOKENS_URL);
-  if (!data.ok) return void 0;
-  return await data.json();
+  try {
+    return await loadCached(
+      "main-tokens",
+      () => fetchRemoteJson(MAIN_TOKENS_URL, "main-tokens"),
+      (value) => !!value && typeof value === "object"
+    );
+  } catch {
+    return void 0;
+  }
 }
 
-export { CURVANCE_MONAD_CONFIG, FRAXLEND_ETHEREUM_CONFIG, GEARBOX_ACCOUNT_COMPRESSOR_V310, RESUPPLY_ETHEREUM_CONFIG, aaveOracles, aaveOraclesConfig, aavePools, aaveReserves, aaveTokens, aaveV4Oracles, aaveV4Peripherals, aaveV4SpokeLenderKey, aaveV4Spokes, aaveWethGateway, chainLogoURI, chains, compoundV2Oracles, compoundV2OraclesConfig, compoundV2Pools, compoundV2Reserves, compoundV2TokenArray, compoundV2Tokens, compoundV3BaseData, compoundV3Bulker, compoundV3OraclesData, compoundV3Pools, compoundV3Reserves, curvanceConfig, curvanceConfigFor, curvanceLendersByChain, curvancePositionManager, curvancePositionManagersFor, dolomiteChains, dolomiteConfigs, dolomiteEmode, dolomiteMarketIdByToken, dssChainData, dssConfigFor, dssDebtJoin, dssDebtToken, dssMarketByIlk, eulerConfigs, eulerVaults, exactlyConfig, exactlyMarketByAddress, exactlyMarketByAsset, exactlyMarkets, exactlyMarketsByChain, fetchMainTokensMap, fetchTokenList, fetchTokenListFile, fetchTokenLists, findAaveV4PositionManager, fluidChains, fluidResolvers, fluidVaultEntries, fluidVaults, frankencoinChainData, frankencoinConfig, frankencoinConfigFor, frankencoinLendersByChain, frankencoinMarketByPosition, frankencoinMarkets, fraxlendConfig, fraxlendConfigFor, fraxlendLendersByChain, fraxlendPairKey, fraxlendPairsFor, gearboxAccountCompressor, gearboxAddressProviderV310, gearboxBotListV3, gearboxChains, gearboxMarketCompressor, gearboxMarketConfigurators, gearboxResolvers, gearboxV3LenderKey, getAaveV4GatewayAddresses, getAaveV4PositionManagers, getAaveV4SpokeAccess, getAaveV4SpokeEntry, getAaveV4SpokePeripherals, getChainEntries, getSiloV2MarketEntry, getSiloV3MarketEntry, initConfig, initializeChainData, initializeLenderData, inverseChainData, inverseConfig, inverseConfigFor, inverseLendersByChain, inverseMarketByAddress, inverseMarkets, isAaveV4OperationRestricted, isListaSmartLpAsset, liquityBranchByIndex, liquityBranchByTroveManager, liquityBranchesByChain, liquityConfig, liquityConfigFor, liquityLendersByChain, liquityMarkets, listaCollateralProvider, listaCollateralProviders, listaNativeProvider, listaSmartLpByCollateral, llamaLendApiBaseUrl, llamaLendChainData, llamaLendConfig, llamaLendConfigFor, llamaLendLenderKey, llamaLendLendersByChain, llamaLendLeverageZap, llamaLendMarketByController, llamaLendMarketByVault, llamaLendMarkets, llamaLendSupportsDelegation, llamaLendSupportsLeverage, midnightApiBaseOverride, midnightConfig, midnightMarketById, midnightMarkets, midnightMarketsByChain, morphoBundler3, morphoOracles, morphoPools, morphoTypeMarkets, morphoTypeOracles, morphoTypeVaults, parseAaveV4SpokeLenderKey, parseFraxlendPairKey, parseGearboxV3LenderKey, parseLlamaLendLenderKey, parseSiloV2LenderKey, parseSiloV3LenderKey, parseTermMaxLenderKey, resolveMidnightApiBase, resolveTermApiBase, resupplyConfig, resupplyConfigFor, resupplyLendersByChain, riverChainData, riverConfig, riverConfigFor, riverLendersByChain, riverMarketByIndex, riverMarkets, setMidnightApiBase, setTermApiBase, siloMarkets, siloMarketsV3, siloPeripherals, siloPeripheralsV3, siloV2LenderKey, siloV3LenderKey, skyChainData, skyConfig, skyConfigFor, skyLendersByChain, skyMarkets, tellerConfig, tellerConfigByChain, tellerPoolByAddress, tellerPools, tellerPoolsByChain, termApiBaseOverride, termConfig, termMarketById, termMarkets, termMarketsByChain, termMaxApiBaseUrl, termMaxChainIds, termMaxConfig, termMaxConfigByChain, termMaxLenderKey, usddChainData, usddConfig, usddConfigFor, usddLendersByChain, usddMarketByIlk, usddMarkets };
+export { CURVANCE_MONAD_CONFIG, FRAXLEND_ETHEREUM_CONFIG, GEARBOX_ACCOUNT_COMPRESSOR_V310, REMOTE_CACHE_STORE_TTL_S, RESUPPLY_ETHEREUM_CONFIG, RemoteFetchError, aaveOracles, aaveOraclesConfig, aavePools, aaveReserves, aaveTokens, aaveV4Oracles, aaveV4Peripherals, aaveV4SpokeLenderKey, aaveV4Spokes, aaveWethGateway, assertTwyneKeysUnique, chainLogoURI, chains, clearRemoteCache, compoundV2Oracles, compoundV2OraclesConfig, compoundV2Pools, compoundV2Reserves, compoundV2TokenArray, compoundV2Tokens, compoundV3BaseData, compoundV3Bulker, compoundV3OraclesData, compoundV3Pools, compoundV3Reserves, curvanceConfig, curvanceConfigFor, curvanceLendersByChain, curvancePositionManager, curvancePositionManagersFor, dolomiteChains, dolomiteConfigs, dolomiteEmode, dolomiteMarketIdByToken, dssChainData, dssConfigFor, dssDebtJoin, dssDebtToken, dssMarketByIlk, eulerConfigs, eulerVaults, exactlyConfig, exactlyMarketByAddress, exactlyMarketByAsset, exactlyMarkets, exactlyMarketsByChain, fetchMainTokensMap, fetchRemoteJson, fetchTokenList, fetchTokenListFile, fetchTokenLists, findAaveV4PositionManager, fluidChains, fluidResolvers, fluidVaultEntries, fluidVaults, frankencoinChainData, frankencoinConfig, frankencoinConfigFor, frankencoinLendersByChain, frankencoinMarketByPosition, frankencoinMarkets, fraxlendConfig, fraxlendConfigFor, fraxlendLendersByChain, fraxlendPairKey, fraxlendPairsFor, gearboxAccountCompressor, gearboxAddressProviderV310, gearboxBotListV3, gearboxChains, gearboxMarketCompressor, gearboxMarketConfigurators, gearboxResolvers, gearboxV3LenderKey, getAaveV4GatewayAddresses, getAaveV4PositionManagers, getAaveV4SpokeAccess, getAaveV4SpokeEntry, getAaveV4SpokePeripherals, getChainEntries, getSiloV2MarketEntry, getSiloV3MarketEntry, initConfig, initializeChainData, initializeLenderData, inverseChainData, inverseConfig, inverseConfigFor, inverseLendersByChain, inverseMarketByAddress, inverseMarkets, isAaveV4OperationRestricted, isListaSmartLpAsset, liquityBranchByIndex, liquityBranchByTroveManager, liquityBranchesByChain, liquityConfig, liquityConfigFor, liquityLendersByChain, liquityMarkets, listaCollateralProvider, listaCollateralProviders, listaNativeProvider, listaSmartLpByCollateral, llamaLendApiBaseUrl, llamaLendChainData, llamaLendConfig, llamaLendConfigFor, llamaLendLenderKey, llamaLendLendersByChain, llamaLendLeverageZap, llamaLendMarketByController, llamaLendMarketByVault, llamaLendMarkets, llamaLendSupportsDelegation, llamaLendSupportsLeverage, loadCached, loadCachedJson, midnightApiBaseOverride, midnightConfig, midnightMarketById, midnightMarkets, midnightMarketsByChain, morphoBundler3, morphoOracles, morphoPools, morphoTypeMarkets, morphoTypeOracles, morphoTypeVaults, parseAaveV4SpokeLenderKey, parseFraxlendPairKey, parseGearboxV3LenderKey, parseLlamaLendLenderKey, parseSiloV2LenderKey, parseSiloV3LenderKey, parseTermMaxLenderKey, resolveMidnightApiBase, resolveTermApiBase, resupplyConfig, resupplyConfigFor, resupplyLendersByChain, riverChainData, riverConfig, riverConfigFor, riverLendersByChain, riverMarketByIndex, riverMarkets, setMidnightApiBase, setRemoteCacheGithubToken, setRemoteCacheStore, setTermApiBase, siloMarkets, siloMarketsV3, siloPeripherals, siloPeripheralsV3, siloV2LenderKey, siloV3LenderKey, skyChainData, skyConfig, skyConfigFor, skyLendersByChain, skyMarkets, tellerConfig, tellerConfigByChain, tellerPoolByAddress, tellerPools, tellerPoolsByChain, termApiBaseOverride, termConfig, termMarketById, termMarkets, termMarketsByChain, termMaxApiBaseUrl, termMaxChainIds, termMaxConfig, termMaxConfigByChain, termMaxLenderKey, twyneBaseKey, twyneBeaconFor, twyneChainData, twyneConfig, twyneConfigFor, twyneLendersByChain, twyneMarketByKey, twyneMarketFor, twyneMarketKey, twyneMarkets, twyneMarketsForIntermediateVault, twyneOperator, usddChainData, usddConfig, usddConfigFor, usddLendersByChain, usddMarketByIlk, usddMarkets };

package/dist/lending/index.d.ts

@@ -37,4 +37,5 @@ export * from './dss';
 export * from './llamalend';
 export * from './resupply';
 export * from './curvance';
+export * from './twyne';
 export * from './fraxlend';

package/dist/lending/morpho.d.ts

@@ -53,6 +53,13 @@ export type MorphoTypeVaultEntry = {
     underlying: string;
     /** Curated display name (e.g. `Lista USD1 Vault`). Optional. */
     name?: string;
+    /** Human curator/brand name (e.g. `Steakhouse Financial`). Filled by
+     *  lender-metadata's `update:vault-curators` job (Morpho curator roster
+     *  joined on the on-chain `curator()`/`owner()` address, with a
+     *  conservative name-derived fallback) — the chains in this registry have
+     *  no Morpho-API coverage, so the on-chain fetcher cannot learn the
+     *  curator any other way. */
+    curatorName?: string;
     /** Vault interface version. `v1` = MetaMorpho (withdraw-queue → markets);
      *  `v2` = Vaults V2 (adapter-based). Drives the on-chain fetcher's
      *  allocation walk. Absent ⇒ the fetcher auto-detects on-chain

package/dist/lending/registry.d.ts

@@ -24,6 +24,7 @@ import type { GeneralReservesMap, OracleMap } from './common';
 import type { CompoundV2OraclesConfigType, CompoundV2PoolsType, CompoundV2TokenArrayType, CompoundV2TokensType } from './compoundV2';
 import type { CompoundV3BaseDataType, CompoundV3BulkerType, CompoundV3OracleDataMap, CompoundV3PoolsType } from './compoundV3';
 import type { CurvanceConfigType } from './curvance';
+import type { TwyneConfigType, TwyneMarketsType } from './twyne';
 import type { DolomiteConfigsType, DolomiteEmodeType } from './dolomite';
 import type { UsddConfigType, UsddMarketsType } from './dss';
 import type { EulerConfigsType, EulerVaultsType } from './euler';
@@ -105,6 +106,8 @@ export interface GlobalLenderDataRegistry {
     llamaLendMarkets: LlamaLendMarketsType;
     resupplyConfig: ResupplyConfigType;
     curvanceConfig: CurvanceConfigType;
+    twyneConfig: TwyneConfigType;
+    twyneMarkets: TwyneMarketsType;
     fraxlendConfig: FraxlendConfigType;
     eulerConfigs: EulerConfigsType;
     eulerVaults: EulerVaultsType;

package/dist/lending/twyne.d.ts

@@ -0,0 +1,210 @@
+/** The two external protocols Twyne integrates. Mirrors the on-chain enum. */
+export type TwyneVaultType = 'EULER_V2' | 'AAVE_V3';
+/**
+ * The 1-click operators for one `VaultType`. Each is EVC-authenticated
+ * (`_msgSender() == collateralVault.borrower()`) and runs a Morpho Blue flash
+ * loan plus, where it swaps, Euler's `Swapper` — whose GENERIC handler executes
+ * arbitrary calldata on an arbitrary target, so any aggregator we support works
+ * without an allowlist.
+ */
+export type TwyneOperators = {
+    /** `executeLeverage(collateralVault, underlyingAmt, collateralAmt, flashAmt, minOut, deadline, swapData)` */
+    leverage?: string;
+    /** `executeDeleverage(collateralVault, flashAmt, maxDebt, withdrawAmt, swapData)` */
+    deleverage?: string;
+    /**
+     * `executeTeleport(collateralVault, aTokenAmount, debtAmount)` — migrate an
+     * existing external position IN.
+     *
+     * AAVE_V3 ONLY, and it carries NO swapper (its constructor takes
+     * `evc, morpho, factory, permit2, aavePool` and nothing else), so it handles
+     * the IDENTITY CASE ONLY: the user's aToken must be this market's aToken and
+     * their VARIABLE debt asset must be this market's `targetAsset`. Anything
+     * cross-asset has to fall back to the generic migrate. There is no
+     * teleport-OUT.
+     */
+    teleport?: string;
+};
+/**
+ * The BeaconProxy beacon for one target vault, and OPTIONALLY a cached
+ * init-code hash for the CREATE2 address predictor.
+ *
+ * `CollateralVaultFactory.createCollateralVault` deploys
+ * `new BeaconProxy{salt: keccak256(abi.encodePacked(borrower, nonce))}(beacon, "")`,
+ * so a position's address IS predictable — but the init-code hash is a property
+ * of the FACTORY IMPLEMENTATION, not of the protocol. That factory is a UUPS
+ * proxy which has already been upgraded four times, and the embedded BeaconProxy
+ * creation code is not identical across those implementations.
+ *
+ * So `evc.batchSimulation` is the source of truth for a new vault's address, and
+ * a cached hash here is a FAST PATH ONLY. It is valid exactly while
+ * `factoryImplementation` still matches the live ERC-1967 implementation slot
+ * (`0x360894…382bbc`) — one `eth_getStorageAt` to check. On a mismatch, fall
+ * back; never guess, because a stale hash yields a plausible EMPTY address and
+ * the leverage batch would then `skim`/`borrow` on nothing.
+ *
+ * See TWYNE_BUILD_PLAN.md D3.
+ */
+export type TwyneBeacon = {
+    beacon: string;
+    /** `keccak256(BeaconProxy.creationCode ++ abi.encode(beacon, "0x"))`. */
+    initCodeHash?: string;
+    /** The factory implementation `initCodeHash` was derived from. A cached hash
+     *  is only usable while this still matches the live implementation slot. */
+    factoryImplementation?: string;
+};
+/** Per-chain, protocol-level (evergreen) Twyne addresses. */
+export type TwyneConfigChain = {
+    /**
+     * Twyne's OWN EVC — `0xef39D649…` on Ethereum, NOT Euler's canonical
+     * `0x0C9a3dd6…`. Every collateral-vault write is authenticated through it
+     * (`EVCUtil._msgSender()`), which is also what lets an EVC account operator
+     * drive a position. Reusing the Euler address here is a silent failure.
+     */
+    evc: string;
+    /** `CollateralVaultFactory` — `createCollateralVault`, `getCollateralVaults`,
+     *  `isCollateralVault`, `nonce`, `collateralVaultBeacon`, `paused`. */
+    collateralVaultFactory: string;
+    /** `VaultManager` — the whitelists and the LTV bounds
+     *  (`maxTwyneLTVs`, `externalLiqBuffers`, `isAllowedTargetAssets`). */
+    vaultManager: string;
+    /** Euler-style oracle router used to price collateral vaults. */
+    oracleRouter?: string;
+    /** Morpho Blue — the (free) flash source every operator uses. */
+    morpho?: string;
+    /** Euler periphery `Swapper` (GENERIC handler = no target allowlist). */
+    swapper?: string;
+    /** Euler periphery `SwapVerifier` — used by the Euler leverage operator. */
+    swapVerifier?: string;
+    /** Permit2, as the operators pull user funds through `SafeERC20Lib`. */
+    permit2?: string;
+    /** 1-click operators per external protocol. */
+    operators?: Partial<Record<TwyneVaultType, TwyneOperators>>;
+    /**
+     * Collateral-vault beacons keyed by TARGET VAULT (the factory keys its
+     * beacon map that way), for the CREATE2 address predictor.
+     */
+    beacons?: {
+        [targetVault: string]: TwyneBeacon;
+    };
+};
+export type TwyneConfigType = {
+    [lender: string]: {
+        [chainId: string]: TwyneConfigChain;
+    };
+};
+/**
+ * One whitelisted Twyne market.
+ *
+ * Numeric risk fields are strings/numbers in the protocol's own scale (1e4 for
+ * LTVs and the buffer) because they are sourced from JSON metadata; live values
+ * are re-read on every refresh, since the external liquidation threshold moves
+ * — Aave's PT eMode thresholds ramp down as a PT ages, and Twyne's LOWER bound
+ * is derived from it.
+ */
+export type TwyneMarketConfig = {
+    /** `TWYNE_<chainId>_<INTERMEDIATE_VAULT>_<TARGET_ASSET>`, upper-cased hex. */
+    key: string;
+    vaultType: TwyneVaultType;
+    /** The EVK credit vault. Also the market's identity for LTV bounds. */
+    intermediateVault: string;
+    /** Euler: the debt eVault. Aave: the Pool. */
+    targetVault: string;
+    /** The borrowed asset (e.g. USDe, WETH). */
+    targetAsset: string;
+    /** The intermediate vault's asset — an `eToken` or a Twyne aToken wrapper.
+     *  This is what the collateral vault actually holds. */
+    collateralAsset: string;
+    /** What the user thinks they deposited (WETH / wstETH / a Pendle PT).
+     *  `depositUnderlying` / `redeemUnderlying` take this. */
+    underlyingAsset: string;
+    /** Aave only: the aToken the wrapper wraps. */
+    aToken?: string;
+    /** Aave only: the eMode category the collateral vault is initialized with.
+     *  The external liquidation threshold must be read from THIS category when
+     *  the reserve is in its collateral bitmap — never the plain reserve LT. */
+    categoryId?: number;
+    /** Governance ceiling on a position's chosen liq LTV, 1e4. */
+    maxTwyneLiqLTV?: number;
+    /** Safety margin below the external threshold, 1e4 — the LOWER bound is
+     *  `extLiqLTV * externalLiqBuffer / 1e4`. */
+    externalLiqBuffer?: number;
+    /** Maturity of the collateral, unix seconds, when the collateral is a
+     *  fixed-term asset (every live PT market). Absent for wstETH/WETH. */
+    collateralMaturity?: number;
+    /** The credit vault's `IRMTwyneCurve` — the join key into the `irm` repo's
+     *  `twyne.json`, where the fitted `gamma` lives. */
+    creditIrm?: string;
+    /** The collateral vault BeaconProxy beacon for this market's target vault.
+     *  Recorded for the CREATE2 predictor's fast path; the init-code hash is
+     *  deliberately NOT pinned (see TWYNE_BUILD_PLAN.md D3). */
+    beacon?: string;
+    /** Display only. */
+    symbol?: string;
+    name?: string;
+};
+export type TwyneChainData = {
+    markets: TwyneMarketConfig[];
+};
+export type TwyneMarketsType = {
+    [lender: string]: {
+        [chainId: string]: TwyneChainData;
+    };
+};
+export declare const twyneConfig: () => TwyneConfigType;
+/** Deployment seed for one Twyne lender on a chain (undefined if unloaded). */
+export declare const twyneConfigFor: (lender: string, chainId: string | number) => TwyneConfigChain | undefined;
+export declare const twyneMarkets: () => TwyneMarketsType;
+/** Generated chain data (curated market roster; undefined if unloaded). */
+export declare const twyneChainData: (lender: string, chainId: string | number) => TwyneChainData | undefined;
+/**
+ * The bare lender key a per-market key belongs to. Per-market keys are
+ * `TWYNE_<chainId>_<iv>_<targetAsset>`, so the base is simply the first
+ * segment — kept as a function because callers pass both forms
+ * interchangeably.
+ */
+export declare const twyneBaseKey: (lender: string) => string;
+/**
+ * Build the per-market lender key for a triple.
+ *
+ * The TARGET VAULT is deliberately NOT in the key: it is redundant on every
+ * live market (implied by the asset on Euler, always the Pool on Aave), and
+ * every other fan-out lender in this registry uses a one-or-two-identifier key.
+ * `assertTwyneKeysUnique` guards the day that assumption breaks.
+ */
+export declare const twyneMarketKey: (chainId: string | number, intermediateVault: string, targetAsset: string) => string;
+/**
+ * Throw if two distinct `(intermediateVault, targetVault, targetAsset)` triples
+ * collapse onto one key.
+ *
+ * This cannot happen with the eight live markets, but it is exactly the failure
+ * that would silently MERGE two markets — the same lender key resolving to two
+ * different debt venues — so the roster is validated at load rather than
+ * trusted. Called by the generator and by the margin-fetcher on ingest.
+ */
+export declare const assertTwyneKeysUnique: (markets: TwyneMarketConfig[], chainId: string | number) => void;
+/** Find one Twyne market by its per-market lender key. */
+export declare const twyneMarketByKey: (lender: string, chainId: string | number) => TwyneMarketConfig | undefined;
+/** Find one Twyne market by its (intermediate vault, target asset) pair. */
+export declare const twyneMarketFor: (lender: string, chainId: string | number, intermediateVault: string, targetAsset: string) => TwyneMarketConfig | undefined;
+/** Every market that reserves credit from one intermediate (credit) vault. */
+export declare const twyneMarketsForIntermediateVault: (lender: string, chainId: string | number, intermediateVault: string) => TwyneMarketConfig[];
+/**
+ * All Twyne lender keys with config on a chain (drives getLendersForChain).
+ * Gated on the collateral vault FACTORY — the one address every flow needs, and
+ * the bootstrap for position discovery.
+ */
+export declare const twyneLendersByChain: (chainId: string | number) => string[];
+/**
+ * The operator to drive for a market's `VaultType`, or `undefined` when Twyne
+ * has not deployed one — a real state, not a gap: there is no Euler-side
+ * teleport at all, and the docs' address table omits deployed operators, so
+ * absence here must be reported rather than defaulted.
+ */
+export declare const twyneOperator: (lender: string, chainId: string | number, vaultType: TwyneVaultType, kind: keyof TwyneOperators) => string | undefined;
+/**
+ * Beacon + init-code hash for a target vault, for the CREATE2 predictor.
+ * Lookup is case-insensitive because target-vault addresses arrive from config
+ * and from chain in mixed checksum forms.
+ */
+export declare const twyneBeaconFor: (lender: string, chainId: string | number, targetVault: string) => TwyneBeacon | undefined;

package/dist/remoteCache.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Cache for the static JSON this SDK reads from GitHub (token lists, the chain
+ * registry).
+ *
+ * raw.githubusercontent.com rate-limits per EGRESS IP, and Cloudflare Workers
+ * share theirs — so an uncached fetch per request 429s in bursts. Before this
+ * existed that surfaced as a hard `INTERNAL_ERROR` 500 on every route needing a
+ * token list, and as a silently EMPTY chain registry (every chain rendered as
+ * "Chain 8453") that a 10-minute init cache then pinned in place.
+ *
+ * These files change on the order of days, so serving a stale copy is strictly
+ * better than failing — hence the stale-on-error fallback, which is the part
+ * that actually survives an outage.
+ */
+/** How long a persisted copy is kept around purely as the stale fallback. */
+export declare const REMOTE_CACHE_STORE_TTL_S: number;
+/**
+ * Durable backing store — a Cloudflare KV namespace in the workers, absent
+ * everywhere else. Without one the cache is per-process, which still collapses
+ * N requests into one upstream fetch but cannot help a cold start; with one, a
+ * fresh isolate never touches GitHub at all.
+ */
+export interface RemoteCacheStore {
+    get(key: string): Promise<string | null>;
+    put(key: string, value: string, ttlSeconds: number): Promise<void>;
+}
+/** Installs (or with `undefined`, removes) the durable store. */
+export declare function setRemoteCacheStore(next: RemoteCacheStore | undefined): void;
+/**
+ * Optional GitHub token for the API mirror below. Unauthenticated it allows 60
+ * requests/hour per IP, which is thin for a shared Worker egress; a token
+ * raises that to 5,000. Only ever used on the fallback path.
+ */
+export declare function setRemoteCacheGithubToken(token: string | undefined): void;
+/** Drops every cached value. Intended for tests. */
+export declare function clearRemoteCache(): void;
+/**
+ * A non-2xx from the remote. Carries the ORIGIN status so a caller can tell a
+ * settled answer (404/410 — the file is not published) from a transient one
+ * (429/5xx — the same URL may work a second later). Callers that collapse the
+ * two re-fetch known-missing files forever, or treat a rate limit as proof that
+ * a lender has no config.
+ */
+export declare class RemoteFetchError extends Error {
+    /** Status from the ORIGIN host, not from the mirror. */
+    readonly status: number;
+    constructor(message: string, 
+    /** Status from the ORIGIN host, not from the mirror. */
+    status: number);
+    /** 404/410 — re-fetching cannot change the answer. */
+    get isMissing(): boolean;
+}
+/** Fetches JSON from `url`, retrying via the GitHub API when raw rate-limits. */
+export declare function fetchRemoteJson<T>(url: string, label: string): Promise<T>;
+/**
+ * Serves `key` from memory, then the durable store, then `load()` — and on a
+ * failed `load()` falls back to whatever stale copy either layer holds, only
+ * rethrowing when there is nothing to fall back to.
+ *
+ * Concurrent callers for the same key share one in-flight load.
+ *
+ * `isValid` guards the durable layer: a truncated or shape-changed entry is
+ * treated as absent rather than served, since a bad token list silently
+ * mis-decimals every balance built from it.
+ */
+export declare function loadCached<T>(key: string, load: () => Promise<T>, isValid: (value: any) => boolean): Promise<T>;
+/** `loadCached` over a JSON URL, failing on any non-2xx so stale can take over. */
+export declare function loadCachedJson<T>(key: string, url: string, isValid: (value: any) => boolean, label?: string): Promise<T>;

package/dist/tokens.d.ts

@@ -13,10 +13,6 @@ export interface TokenListEntry {
 type TokenList = {
     [addr: string]: TokenListEntry;
 };
-export declare function fetchTokenList(chainId: string): Promise<TokenList>;
-export declare function fetchTokenLists(chainIds: string[]): Promise<{
-    [chainId: string]: TokenList;
-}>;
 export interface TokenListFileData {
     list: TokenList;
     /**
@@ -26,7 +22,18 @@ export interface TokenListFileData {
      */
     mainTokens: string[];
 }
-/** Like {@link fetchTokenList} but keeps the `mainTokens` curation. */
+/**
+ * NOTE: cached — the returned `list` is a SHARED object. Treat it as read-only;
+ * mutating it corrupts the copy every other caller sees.
+ */
+export declare function fetchTokenList(chainId: string): Promise<TokenList>;
+export declare function fetchTokenLists(chainIds: string[]): Promise<{
+    [chainId: string]: TokenList;
+}>;
+/**
+ * Like {@link fetchTokenList} but keeps the `mainTokens` curation. Same
+ * read-only caveat on `list`.
+ */
 export declare function fetchTokenListFile(chainId: string): Promise<TokenListFileData>;
 /**
  * Aggregated chainId → mainTokens map (one small file for all chains, so

package/package.json

@@ -4,7 +4,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.0.46",
+  "version": "0.0.48",
   "description": "Hold and initialize lending protocol data across a stack",
   "files": [
     "dist"