@parallel-protocol/cli 0.1.1 → 0.2.0

package/README.md

@@ -111,6 +111,7 @@ All optional — they override the config file when set.
 | `PARALLEL_PRIVATE_KEY` | Raw private key (hex, `0x` prefix) — alternative to keystore, useful for scripts and CI |
 | `PARALLEL_DEFAULT_CHAIN` | Default chain — overrides `network.default_chain` in config |
 | `PARALLEL_JSON` | Set to `true` to force JSON output on all commands |
+| `PARALLEL_API_URL` | Parallel API base URL for `--history` commands (default: `https://api.parallel.best`) |
 
 
 ---
@@ -157,6 +158,12 @@ parallel protocol exchange-rate  [--chain <chain>]                     # sUSDp /
 parallel protocol solvency       [--chain <chain>]                     # Backing ratio per chain
 parallel protocol surplus        [--chain <chain>]                     # Pending surplus (USDp)
 parallel protocol flashloan      [--chain <chain>]                     # Flash loan capacity + fee rate
+
+# Historical data (daily series) — flags: [--from <YYYY-MM-DD>] [--to <YYYY-MM-DD>] [--chain <chain>]
+parallel protocol backing      --history       # reserves over time, per chain (source: Parallel API)
+parallel protocol tvl          --history       # TVL over time (source: DeFiLlama)
+parallel protocol savings-rate --history       # sUSDp APY over time (source: DeFiLlama)
+parallel protocol supply       --history usdp  # USDp circulating supply over time (source: DeFiLlama)
 ```
 
 ---

package/dist/index.js

@@ -4751,6 +4751,7 @@ async function buildBridgeTx(fromChain, toChain, amount, sender, recipient) {
 var CONFIG_DIR = join(homedir(), ".parallel");
 var CONFIG_PATH = join(CONFIG_DIR, "config.toml");
 var PROD_FACILITATOR_URL = "https://agents.parallel.best";
+var PROD_API_URL = "https://api.parallel.best";
 var _cache = null;
 function loadConfig() {
   if (_cache) return _cache;
@@ -4778,6 +4779,9 @@ function getDefaultChain() {
 function getFacilitatorUrl() {
   return process.env.FACILITATOR_URL ?? loadConfig().facilitator?.url ?? PROD_FACILITATOR_URL;
 }
+function getApiUrl() {
+  return process.env.PARALLEL_API_URL ?? process.env.SUPPLY_API_URL ?? loadConfig().api?.url ?? PROD_API_URL;
+}
 function getKeystorePath() {
   return loadConfig().wallet?.keystore_path;
 }
@@ -10119,7 +10123,183 @@ async function getSupply(token, chain) {
   });
 }
 
+// src/providers/api.ts
+async function get2(path) {
+  const base3 = getApiUrl();
+  let res;
+  try {
+    res = await fetch(`${base3}${path}`);
+  } catch (_err) {
+    throw new CliError(
+      ErrorCode.RPC_ERROR,
+      `Cannot reach Parallel API at ${base3}`,
+      "Check PARALLEL_API_URL or your network connection"
+    );
+  }
+  if (!res.ok) {
+    const text = await res.text().catch(() => res.statusText);
+    throw new CliError(
+      ErrorCode.UNKNOWN,
+      `Parallel API error (${res.status}): ${text}`
+    );
+  }
+  const body = await res.json();
+  return body?.json ?? body;
+}
+function getHistoricalProtocols(from, to) {
+  const q = new URLSearchParams();
+  if (from) q.set("startDate", from);
+  if (to) q.set("endDate", to);
+  const query = q.toString();
+  return get2(
+    `/public/transparency/historical-protocols${query ? `?${query}` : ""}`
+  );
+}
+function reservesByDate(points, chainId) {
+  return points.map((point) => {
+    const perChain = {};
+    for (const protocol of Object.values(point.protocols)) {
+      for (const [id, chainData] of Object.entries(protocol.chains)) {
+        const numericId = Number(id);
+        if (chainId !== void 0 && numericId !== chainId) continue;
+        perChain[numericId] = (perChain[numericId] ?? 0) + Number(chainData.value);
+      }
+    }
+    const total = Object.values(perChain).reduce((sum, v) => sum + v, 0);
+    return { date: point.date, perChain, total };
+  });
+}
+
+// src/providers/defillama.ts
+var TVL_URL = "https://api.llama.fi";
+var YIELDS_URL = "https://yields.llama.fi";
+var STABLECOINS_URL = "https://stablecoins.llama.fi";
+var PARALLEL_SLUG = "parallel-protocol-v3";
+var USDP_STABLECOIN_ID = "291";
+var DEFILLAMA_CHAIN = {
+  ethereum: "Ethereum",
+  base: "Base",
+  avalanche: "Avalanche",
+  hyperevm: "Hyperliquid L1",
+  sonic: "Sonic"
+};
+var STABLECOIN_CHAIN = {
+  ethereum: "Ethereum",
+  base: "Base",
+  arbitrum: "Arbitrum",
+  optimism: "OP Mainnet",
+  polygon: "Polygon",
+  avalanche: "Avalanche",
+  bsc: "BSC",
+  scroll: "Scroll",
+  gnosis: "Gnosis",
+  sei: "Sei",
+  berachain: "Berachain",
+  hyperevm: "Hyperliquid L1",
+  unichain: "Unichain",
+  ink: "Ink",
+  tac: "TAC",
+  linea: "Linea",
+  xlayer: "X Layer",
+  fraxtal: "Fraxtal",
+  worldchain: "World Chain",
+  hemi: "Hemi",
+  plume: "Plume Mainnet",
+  plasma: "Plasma",
+  katana: "Katana"
+};
+var SAVINGS_POOL_ID = {
+  ethereum: "f65159b4-7bec-40c8-8f31-1fa2f5408738",
+  base: "f65159b4-7bec-40c8-8f31-1fa2f5408738",
+  avalanche: "f65159b4-7bec-40c8-8f31-1fa2f5408738",
+  hyperevm: "086da6ff-2302-4a9e-8cd8-1599e67c655d"
+};
+var DEFAULT_SAVINGS_POOL_ID = SAVINGS_POOL_ID.ethereum;
+async function get3(url) {
+  let res;
+  try {
+    res = await fetch(url);
+  } catch (_err) {
+    throw new CliError(
+      ErrorCode.RPC_ERROR,
+      "Cannot reach DeFiLlama",
+      "Check your network connection"
+    );
+  }
+  if (!res.ok) {
+    throw new CliError(ErrorCode.UNKNOWN, `DeFiLlama error (${res.status})`);
+  }
+  return res.json();
+}
+function collapseByDay(points) {
+  const byDay = /* @__PURE__ */ new Map();
+  for (const p of points) byDay.set(p.date, p.value);
+  return [...byDay].map(([date, value]) => ({ date, value }));
+}
+function unknownChain(chain, supported) {
+  return new CliError(
+    ErrorCode.UNKNOWN_CHAIN,
+    `No DeFiLlama history for chain "${chain}"`,
+    `Supported chains: ${supported.join(", ")}`
+  );
+}
+async function getTvlHistory(chain) {
+  let chainName;
+  if (chain) {
+    chainName = DEFILLAMA_CHAIN[chain];
+    if (!chainName) throw unknownChain(chain, Object.keys(DEFILLAMA_CHAIN));
+  }
+  const data = await get3(
+    `${TVL_URL}/protocol/${PARALLEL_SLUG}`
+  );
+  const raw = (chainName ? data.chainTvls?.[chainName]?.tvl : data.tvl) ?? [];
+  return collapseByDay(
+    raw.map((p) => ({
+      date: new Date(p.date * 1e3).toISOString().slice(0, 10),
+      value: p.totalLiquidityUSD
+    }))
+  ).map(({ date, value }) => ({ date, tvl: value }));
+}
+async function getSavingsApyHistory(chain) {
+  let poolId = DEFAULT_SAVINGS_POOL_ID;
+  if (chain) {
+    const id = SAVINGS_POOL_ID[chain];
+    if (!id) throw unknownChain(chain, Object.keys(SAVINGS_POOL_ID));
+    poolId = id;
+  }
+  const data = await get3(`${YIELDS_URL}/chart/${poolId}`);
+  return collapseByDay(
+    (data.data ?? []).map((p) => ({
+      date: p.timestamp.slice(0, 10),
+      value: p.apy
+    }))
+  ).map(({ date, value }) => ({ date, apy: value }));
+}
+async function getUsdpSupplyHistory(chain) {
+  let chainName;
+  if (chain) {
+    chainName = STABLECOIN_CHAIN[chain];
+    if (!chainName) throw unknownChain(chain, Object.keys(STABLECOIN_CHAIN));
+  }
+  const data = await get3(
+    `${STABLECOINS_URL}/stablecoin/${USDP_STABLECOIN_ID}`
+  );
+  const raw = (chainName ? data.chainBalances?.[chainName]?.tokens : data.tokens) ?? [];
+  return collapseByDay(
+    raw.map((p) => ({
+      date: new Date(p.date * 1e3).toISOString().slice(0, 10),
+      value: p.circulating?.peggedUSD ?? 0
+    }))
+  ).map(({ date, value }) => ({ date, supply: value }));
+}
+
 // src/utils/chains.ts
+var CHAIN_NAME_BY_ID = new Map(
+  Object.values(CHAINS).map((cfg) => [cfg.id, cfg.name])
+);
+function chainNameById(id) {
+  return CHAIN_NAME_BY_ID.get(id) ?? `chain:${id}`;
+}
 function assertParallelizerChain(chain) {
   const cfg = CHAINS[chain];
   if (cfg?.status === "sunset")
@@ -10260,8 +10440,13 @@ function overviewCmd() {
   });
 }
 function supplyCmd() {
-  return new Command("supply").description("Token supply: usdp | susdp | prl | sprl1 | sprl2").argument("<token>", "token symbol").option("-c, --chain <chain>", "filter to a single chain").action(async function(token) {
-    const { chain } = resolveOpts(this);
+  return new Command("supply").description("Token supply: usdp | susdp | prl | sprl1 | sprl2").argument("<token>", "token symbol").option("-c, --chain <chain>", "filter to a single chain").option("--history", "supply over time \u2014 usdp only (source: DeFiLlama)").option("--from <date>", "history start date (YYYY-MM-DD)").option("--to <date>", "history end date (YYYY-MM-DD)").action(async function(token) {
+    const opts = resolveOpts(this);
+    if (opts.history) {
+      await renderSupplyHistory(token, opts);
+      return;
+    }
+    const { chain } = opts;
     try {
       const result = await getSupply(
         token,
@@ -10284,11 +10469,85 @@ function supplyCmd() {
     }
   });
 }
+function fmtDelta(delta, fmt2) {
+  if (delta === void 0) return chalk5.dim("\u2014");
+  return delta >= 0 ? chalk5.green(`+${fmt2(delta)}`) : chalk5.red(`\u2212${fmt2(-delta)}`);
+}
+function fmtApy(value) {
+  return `${value.toFixed(2)}%`;
+}
+function renderHistory(series, opts, cfg) {
+  const { from, to } = opts;
+  let rows = series;
+  if (from) rows = rows.filter((p) => p.date >= from);
+  if (to) rows = rows.filter((p) => p.date <= to);
+  rows = rows.slice().sort((a, b) => b.date.localeCompare(a.date));
+  output({ interval: "day", source: cfg.source, series: rows }, () => {
+    const table = rows.map((row, i) => {
+      const prev = rows[i + 1];
+      const delta = prev ? cfg.valueOf(row) - cfg.valueOf(prev) : void 0;
+      return [row.date, cfg.fmt(cfg.valueOf(row)), fmtDelta(delta, cfg.fmt)];
+    });
+    printTable(cfg.title, ["Date", cfg.valueHeader, "\u0394 vs prev"], table);
+  });
+}
+async function renderTvlHistory(opts) {
+  try {
+    const series = await getTvlHistory(opts.chain);
+    renderHistory(series, opts, {
+      valueOf: (r) => r.tvl,
+      fmt: fmtUsd,
+      title: "TVL Over Time \u2014 Daily (source: DeFiLlama)",
+      valueHeader: "TVL",
+      source: "defillama"
+    });
+  } catch (err) {
+    formatCliError(err);
+  }
+}
+async function renderSavingsRateHistory(opts) {
+  try {
+    const series = await getSavingsApyHistory(opts.chain);
+    renderHistory(series, opts, {
+      valueOf: (r) => r.apy,
+      fmt: fmtApy,
+      title: "sUSDp APY Over Time \u2014 Daily (source: DeFiLlama)",
+      valueHeader: "APY",
+      source: "defillama"
+    });
+  } catch (err) {
+    formatCliError(err);
+  }
+}
+async function renderSupplyHistory(token, opts) {
+  try {
+    if (token.toLowerCase() !== "usdp")
+      throw new CliError(
+        ErrorCode.UNKNOWN,
+        `supply --history is only available for usdp (got "${token}")`,
+        "Only USDp has a public historical supply source"
+      );
+    const series = await getUsdpSupplyHistory(opts.chain);
+    renderHistory(series, opts, {
+      valueOf: (r) => r.supply,
+      fmt: fmtNum,
+      title: "USDp Supply Over Time \u2014 Daily (source: DeFiLlama)",
+      valueHeader: "Supply (USDp)",
+      source: "defillama"
+    });
+  } catch (err) {
+    formatCliError(err);
+  }
+}
 function tvlCmd() {
-  return new Command("tvl").description("Total Value Locked across all Parallelizer chains").option("-c, --chain <chain>", "filter to a single chain").action(async function() {
-    const { chain } = resolveOpts(this);
+  return new Command("tvl").description("Total Value Locked across all Parallelizer chains").option("-c, --chain <chain>", "filter to a single chain").option("--history", "TVL over time (source: DeFiLlama)").option("--from <date>", "history start date (YYYY-MM-DD)").option("--to <date>", "history end date (YYYY-MM-DD)").action(async function() {
+    const opts = resolveOpts(this);
+    if (opts.history) {
+      await renderTvlHistory(opts);
+      return;
+    }
     try {
-      const result = await getTvl(chain);
+      const result = await getTvl(opts.chain);
       output(result, () => {
         printKeyValue("TVL", [["Total TVL", fmtUsd(result.totalTVL)]]);
         const rows = result.breakdown.map((b) => [b.chain, fmtUsd(b.tvl)]);
@@ -10299,9 +10558,56 @@ function tvlCmd() {
     }
   });
 }
+function orderedChainIds(series, latest) {
+  const ids = /* @__PURE__ */ new Set();
+  for (const row of series) {
+    for (const id of Object.keys(row.perChain)) ids.add(Number(id));
+  }
+  return [...ids].sort((a, b) => (latest[b] ?? 0) - (latest[a] ?? 0));
+}
+async function renderBackingHistory(opts) {
+  try {
+    let chainId;
+    if (opts.chain) {
+      const cfg = CHAINS[opts.chain];
+      if (!cfg)
+        throw new CliError(
+          ErrorCode.UNKNOWN_CHAIN,
+          `Unknown chain "${opts.chain}"`,
+          "Run: parallel protocol chains to see supported chains"
+        );
+      chainId = cfg.id;
+    }
+    const points = await getHistoricalProtocols(opts.from, opts.to);
+    const series = reservesByDate(points, chainId).sort((a, b) => b.date.localeCompare(a.date));
+    const chainIds = orderedChainIds(series, series[0]?.perChain ?? {});
+    output({ interval: "day", series }, () => {
+      const headers = [
+        "Date",
+        ...chainIds.map((id) => chainNameById(id)),
+        "Total"
+      ];
+      const rows = series.map((row) => [
+        row.date.slice(0, 10),
+        ...chainIds.map(
+          (id) => row.perChain[id] ? fmtUsd(row.perChain[id]) : chalk5.dim("\u2212")
+        ),
+        fmtUsd(row.total)
+      ]);
+      printTable("Backing History (reserves over time) \u2014 Daily", headers, rows);
+    });
+  } catch (err) {
+    formatCliError(err);
+  }
+}
 function backingCmd() {
-  return new Command("backing").description("Collateral backing composition per chain").option("-c, --chain <chain>", "filter to a single chain").action(async function() {
-    const { chain } = resolveOpts(this);
+  return new Command("backing").description("Collateral backing composition per chain").option("-c, --chain <chain>", "filter to a single chain").option("--history", "reserves (backing) over time, per chain").option("--from <date>", "history start date (YYYY-MM-DD)").option("--to <date>", "history end date (YYYY-MM-DD)").action(async function() {
+    const opts = resolveOpts(this);
+    if (opts.history) {
+      await renderBackingHistory(opts);
+      return;
+    }
+    const { chain } = opts;
     try {
       const [result, usdpSupply, solvency] = await Promise.all([
         getTvl(chain),
@@ -10614,8 +10920,13 @@ function feesCmd2() {
   });
 }
 function savingsRateCmd() {
-  return new Command("savings-rate").description("sUSDp savings rate (APY) across all chains").option("-c, --chain <chain>", "filter to a single chain").action(async function() {
-    const { chain } = resolveOpts(this);
+  return new Command("savings-rate").description("sUSDp savings rate (APY) across all chains").option("-c, --chain <chain>", "filter to a single chain").option("--history", "APY over time (source: DeFiLlama)").option("--from <date>", "history start date (YYYY-MM-DD)").option("--to <date>", "history end date (YYYY-MM-DD)").action(async function() {
+    const opts = resolveOpts(this);
+    if (opts.history) {
+      await renderSavingsRateHistory(opts);
+      return;
+    }
+    const { chain } = opts;
     try {
       if (chain) assertParallelizerChain(chain);
       const result = await getSavingsRate();
@@ -14230,7 +14541,7 @@ var package_default = {
 
 // package.json
 var package_default2 = {
-  version: "0.1.1"};
+  version: "0.2.0"};
 
 // src/commands/version.ts
 function versionCommand() {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@parallel-protocol/cli",
-	"version": "0.1.1",
+	"version": "0.2.0",
 	"private": false,
 	"type": "module",
 	"files": [