chain-diff

Git diff for onchain state.

chain-diff is a CLI for explaining how lending protocol state changed over time — not just what changed, but why.

Currently supports:

• Aave V3 / Ethereum / USDC
• Morpho Blue / Ethereum / USDC / wstETH
• Generic Morpho Blue USDC markets by Market ID

Features

• Compare current and historical onchain state
• Explain liquidity and debt changes
• Attribute changes to supply, withdrawals, borrowing, repayments, and interest
• Compare protocols over the same Ethereum block window
• Normalize changes by protocol size
• Continuously watch markets for new changes
• Filter watch output by liquidity/debt thresholds
• JSON / JSONL output for automation

Requirements

• Node.js 20+
• Ethereum RPC access

chain-diff can use its default RPC transport, or you can provide your own endpoint:

$env:ETH_RPC_URL="https://your-ethereum-rpc.example"

Install

From the project directory:

npm install
npm run build
npm link

Then:

chain-diff --help

Targets

chain-diff targets

Example:

aave:usdc
morpho:wsteth-usdc

A generic Morpho Blue market can also be addressed with:

morpho:<market-id>

Diff

Inspect how a market changed over a time window:

chain-diff diff aave:usdc --since 1h

Why

Explain the causes behind a state change:

chain-diff why aave:usdc --since 24h

JSON output:

chain-diff why aave:usdc --since 24h --json

Compact JSON without the full event list:

chain-diff why aave:usdc --since 24h --json --summary

Compare

Compare two markets using the exact same Ethereum block window:

chain-diff compare aave:usdc morpho:wsteth-usdc --since 24h

The comparison includes:

• Liquidity change
• Debt change
• Relative percentage change
• Utilization
• Supply APR
• Borrow APR
• Gross activity
• Activity relative to starting supply
• Causal attribution
• Interest model
• Confidence

JSON output:

chain-diff compare aave:usdc morpho:wsteth-usdc --since 24h --json

Watch

Continuously monitor new onchain changes:

chain-diff watch aave:usdc --interval 30s

Run one interval only:

chain-diff watch aave:usdc --interval 15s --once

Only show intervals with at least $100,000 of liquidity movement:

chain-diff watch aave:usdc --interval 30s --min-liquidity 100000

Debt threshold:

chain-diff watch aave:usdc --interval 30s --min-debt 100000

JSONL Watch

watch --json emits machine-readable JSON Lines.

chain-diff watch aave:usdc --interval 30s --json

This can be piped into other tools, databases, webhooks, or monitoring systems.

PowerShell example:

chain-diff watch aave:usdc --interval 15s --once --json 2>$null |
  ConvertFrom-Json |
  Select-Object type, status, target

Analysis model

For liquidity, chain-diff attributes observed changes to normalized protocol events such as:

• Supply
• Withdraw
• Borrow
• Repay

For debt, it separates:

• Principal changes from borrow/repay activity
• Accrued interest

Aave V3 currently uses its variable debt index for interest attribution.

Morpho Blue currently uses an average-APR approximation.

Residual unexplained change is used as part of the confidence calculation.

Development

Type check:

npx tsc --noEmit

Tests:

npm test

Build:

npm run build

Current automated tests cover causal analysis, interest models, normalized metrics, and numerical noise handling.

Status

Early MVP.

The current focus is lending-market state semantics and causal explanation. The longer-term direction is a reusable semantic layer for answering:

What changed onchain, and why?