protoscan 0.1.0

package/src/registry/index.ts

@@ -0,0 +1,38 @@
+import type { ProtocolDef } from './schema.js';
+import { aaveV3 } from './aave-v3.js';
+import { compoundV3 } from './compound-v3.js';
+import { uniswapV3 } from './uniswap-v3.js';
+import { maker } from './maker.js';
+import { eigenLayer } from './eigenlayer.js';
+import { pendle } from './pendle.js';
+import { lido } from './lido.js';
+import { morphoBlue } from './morpho-blue.js';
+
+const protocols: Record<string, ProtocolDef> = {
+  'aave-v3': aaveV3,
+  'compound-v3': compoundV3,
+  'uniswap-v3': uniswapV3,
+  'maker': maker,
+  'eigenlayer': eigenLayer,
+  'pendle': pendle,
+  'lido': lido,
+  'morpho-blue': morphoBlue,
+};
+
+export function getProtocol(id: string): ProtocolDef | undefined {
+  return protocols[id];
+}
+
+export function listProtocols(): ProtocolDef[] {
+  return Object.values(protocols);
+}
+
+export function getProtocolForChain(id: string, chain: string): { protocol: ProtocolDef; addresses: Record<string, string> } | undefined {
+  const protocol = protocols[id];
+  if (!protocol) return undefined;
+  const addresses = protocol.deployments[chain];
+  if (!addresses) return undefined;
+  return { protocol, addresses };
+}
+
+export type { ProtocolDef, ParamDef, AccessDef, ContractDef } from './schema.js';

package/src/registry/lido.ts

@@ -0,0 +1,557 @@
+import { parseAbi } from 'viem';
+import type { ProtocolDef } from './schema.js';
+
+const lidoAbi = parseAbi([
+  'function totalSupply() view returns (uint256)',
+  'function getTotalPooledEther() view returns (uint256)',
+  'function getTotalShares() view returns (uint256)',
+  'function getBufferedEther() view returns (uint256)',
+  'function isStakingPaused() view returns (bool)',
+  'function getCurrentStakeLimit() view returns (uint256)',
+  'function getStakeLimitFullInfo() view returns (bool isStakingPaused, bool isStakeLimitSet, uint256 currentStakeLimit, uint256 maxStakeLimit, uint256 maxStakeLimitGrowthBlocks, uint256 prevStakeLimit, uint256 prevStakeBlockNumber)',
+  'function getFee() view returns (uint16)',
+  'function getFeeDistribution() view returns (uint16 treasuryFeeBasisPoints, uint16 insuranceFeeBasisPoints, uint16 operatorsFeeBasisPoints)',
+  'function getWithdrawalCredentials() view returns (bytes32)',
+  'function getTreasury() view returns (address)',
+  'function getLidoLocator() view returns (address)',
+  'function getBeaconStat() view returns (uint256 depositedValidators, uint256 beaconValidators, uint256 beaconBalance)',
+]);
+
+const wstEthAbi = parseAbi([
+  'function stEthPerToken() view returns (uint256)',
+  'function tokensPerStEth() view returns (uint256)',
+  'function getStETHByWstETH(uint256 _wstETHAmount) view returns (uint256)',
+  'function getWstETHByStETH(uint256 _stETHAmount) view returns (uint256)',
+  'function stETH() view returns (address)',
+]);
+
+const norAbi = parseAbi([
+  'function getNodeOperatorsCount() view returns (uint256)',
+  'function getActiveNodeOperatorsCount() view returns (uint256)',
+  'function getNodeOperator(uint256 _nodeOperatorId, bool _fullInfo) view returns (bool active, string name, address rewardAddress, uint64 totalVettedValidators, uint64 totalExitedValidators, uint64 totalAddedValidators, uint64 totalDepositedValidators)',
+  'function getNodeOperatorIsActive(uint256 _nodeOperatorId) view returns (bool)',
+  'function getNonce() view returns (uint256)',
+  'function getType() view returns (bytes32)',
+  'function getLocator() view returns (address)',
+]);
+
+const withdrawalQueueAbi = parseAbi([
+  'function isBunkerModeActive() view returns (bool)',
+  'function bunkerModeSinceTimestamp() view returns (uint256)',
+  'function getLastRequestId() view returns (uint256)',
+  'function getLastFinalizedRequestId() view returns (uint256)',
+  'function getLastCheckpointIndex() view returns (uint256)',
+  'function MIN_STETH_WITHDRAWAL_AMOUNT() view returns (uint256)',
+  'function MAX_STETH_WITHDRAWAL_AMOUNT() view returns (uint256)',
+]);
+
+const dsmAbi = parseAbi([
+  'function getOwner() view returns (address)',
+  'function getGuardianQuorum() view returns (uint256)',
+  'function getGuardians() view returns (address[])',
+  'function isGuardian(address addr) view returns (bool)',
+  'function canDeposit(uint256 stakingModuleId) view returns (bool)',
+  'function getPauseIntentValidityPeriodBlocks() view returns (uint256)',
+  'function getMaxOperatorsPerUnvetting() view returns (uint256)',
+  'function getLastDepositBlock() view returns (uint256)',
+]);
+
+const accountingOracleAbi = parseAbi([
+  'function getConsensusContract() view returns (address)',
+  'function getConsensusVersion() view returns (uint256)',
+  'function getLastProcessingRefSlot() view returns (uint256)',
+  'function getConsensusReport() view returns (bytes32 hash, uint256 refSlot, uint256 processingDeadlineTime, bool processingStarted)',
+  'function SECONDS_PER_SLOT() view returns (uint256)',
+  'function GENESIS_TIME() view returns (uint256)',
+]);
+
+const hashConsensusAbi = parseAbi([
+  'function getQuorum() view returns (uint256)',
+  'function getMembers() view returns (address[] addresses, uint256[] lastReportedRefSlots)',
+  'function getFastLaneMembers() view returns (address[] addresses, uint256[] lastReportedRefSlots)',
+  'function getCurrentFrame() view returns (uint256 refSlot, uint256 reportProcessingDeadlineSlot)',
+  'function getChainConfig() view returns (uint256 slotsPerEpoch, uint256 secondsPerSlot, uint256 genesisTime)',
+  'function getFrameConfig() view returns (uint256 initialEpoch, uint256 epochsPerFrame, uint256 fastLaneLengthSlots)',
+  'function getReportProcessor() view returns (address)',
+]);
+
+const locatorAbi = parseAbi([
+  'function lido() view returns (address)',
+  'function accountingOracle() view returns (address)',
+  'function stakingRouter() view returns (address)',
+  'function withdrawalQueue() view returns (address)',
+  'function withdrawalVault() view returns (address)',
+  'function elRewardsVault() view returns (address)',
+  'function treasury() view returns (address)',
+  'function oracleReportSanityChecker() view returns (address)',
+  'function burner() view returns (address)',
+  'function validatorsExitBusOracle() view returns (address)',
+  'function depositSecurityModule() view returns (address)',
+  'function oracleDaemonConfig() view returns (address)',
+  'function postTokenRebaseReceiver() view returns (address)',
+]);
+
+const votingAbi = parseAbi([
+  'function supportRequiredPct() view returns (uint64)',
+  'function minAcceptQuorumPct() view returns (uint64)',
+  'function voteTime() view returns (uint64)',
+  'function objectionPhaseTime() view returns (uint64)',
+  'function votesLength() view returns (uint256)',
+]);
+
+const agentAbi = parseAbi([
+  'function kernel() view returns (address)',
+  'function isForwarder() view returns (bool)',
+]);
+
+export const lido: ProtocolDef = {
+  id: 'lido',
+  name: 'Lido',
+  version: '2.0',
+  website: 'https://lido.fi',
+  description: 'Liquid staking protocol for Ethereum — stake ETH, receive rebasing stETH',
+
+  contracts: {
+    Lido: { name: 'Lido (stETH)', role: 'Core staking pool + rebasing stETH token — accepts ETH deposits, mints stETH, tracks total pooled ether', type: 'proxy' },
+    WstETH: { name: 'wstETH', role: 'Non-rebasing wrapped stETH — fixed balance, accrues value via exchange rate', type: 'raw' },
+    NodeOperatorsRegistry: { name: 'NodeOperatorsRegistry', role: 'Curated staking module — manages node operators and validator signing keys', type: 'proxy' },
+    WithdrawalQueue: { name: 'WithdrawalQueueERC721', role: 'stETH withdrawal request queue — NFT claim tickets, bunker mode tracking', type: 'proxy' },
+    DepositSecurityModule: { name: 'DepositSecurityModule', role: 'Guardian committee gate for validator deposits — prevents deposit front-running/DoS', type: 'raw' },
+    AccountingOracle: { name: 'AccountingOracle', role: 'Reports consensus-layer state (balances, exited validators) each epoch, drives stETH rebase', type: 'proxy' },
+    HashConsensus: { name: 'HashConsensus (Accounting)', role: 'Oracle committee consensus module — quorum + member management for AccountingOracle reports', type: 'raw' },
+    LidoLocator: { name: 'LidoLocator', role: 'DAO-controlled pointer registry for every core protocol component — repointing it repoints the whole protocol', type: 'proxy' },
+    Voting: { name: 'Aragon Voting', role: 'Lido DAO governance — token-weighted voting, approves everything Agent executes', type: 'proxy' },
+    Agent: { name: 'Aragon Agent', role: 'DAO treasury + privileged executor — holds funds, executes DAO-approved calls against any contract', type: 'proxy' },
+  },
+
+  deployments: {
+    ethereum: {
+      Lido: '0xae7ab96520DE3A18E5e111B5EaAb095312D7fE84',
+      WstETH: '0x7f39C581F595B53c5cb19bD0b3f8dA6c935E2Ca0',
+      NodeOperatorsRegistry: '0x55032650b14df07b85bF18A3a3eC8E0Af2e028d5',
+      WithdrawalQueue: '0x889edC2eDab5f40e902b864aD4d7AdE8E412F9B1',
+      DepositSecurityModule: '0xC77F8768774E1c9244BEed705C4354f2113CFc09',
+      AccountingOracle: '0x852deD011285fe67063a08005c71a85690503Cee',
+      HashConsensus: '0xD624B08C83bAECF0807Dd2c6880C3154a5F0B288',
+      LidoLocator: '0xC1d0b3DE6792Bf6b4b37EccdcC24e45978Cfd2Eb',
+      Voting: '0x2e59A20f205bB85a89C53f1936454680651E618e',
+      Agent: '0x3e40D73EB977Dc6a537aF587D48316feE66E9C8c',
+    },
+  },
+
+  params: [
+    // -- core pool state --
+    {
+      name: 'totalPooledEther',
+      description: 'Total ETH controlled by the protocol (buffered + beacon chain + EL rewards)',
+      contract: 'Lido',
+      functionName: 'getTotalPooledEther',
+      abi: lidoAbi,
+      decode: 'uint',
+      category: 'state',
+      severity: 'info',
+    },
+    {
+      name: 'totalShares',
+      description: 'Total stETH shares outstanding — denominator used to compute every account balance via rebase',
+      contract: 'Lido',
+      functionName: 'getTotalShares',
+      abi: lidoAbi,
+      decode: 'uint',
+      category: 'state',
+      severity: 'info',
+    },
+    {
+      name: 'bufferedEther',
+      description: 'Unstaked ETH sitting in the Lido contract awaiting deposit to validators',
+      contract: 'Lido',
+      functionName: 'getBufferedEther',
+      abi: lidoAbi,
+      decode: 'uint',
+      category: 'state',
+      severity: 'info',
+    },
+    {
+      name: 'isStakingPaused',
+      description: 'Whether new ETH deposits into Lido are paused',
+      contract: 'Lido',
+      functionName: 'isStakingPaused',
+      abi: lidoAbi,
+      decode: 'bool',
+      category: 'state',
+      severity: 'critical',
+    },
+    {
+      name: 'currentStakeLimit',
+      description: 'Remaining ETH that can be staked right now before hitting the anti-frontrun stake rate limit',
+      contract: 'Lido',
+      functionName: 'getCurrentStakeLimit',
+      abi: lidoAbi,
+      decode: 'uint',
+      category: 'risk',
+      severity: 'warning',
+    },
+
+    // -- fees --
+    {
+      name: 'protocolFee',
+      description: 'Legacy total protocol fee taken from staking rewards (treasury + node operators), in bps',
+      contract: 'Lido',
+      functionName: 'getFee',
+      abi: lidoAbi,
+      decode: 'bps',
+      category: 'config',
+      severity: 'warning',
+    },
+    {
+      name: 'feeDistribution',
+      description: 'Legacy fee split between treasury, insurance and node operators (bps each) — module-level splits now live on StakingRouter',
+      contract: 'Lido',
+      functionName: 'getFeeDistribution',
+      abi: lidoAbi,
+      category: 'config',
+      severity: 'info',
+    },
+
+    // -- withdrawal credentials / treasury / locator pointer --
+    {
+      name: 'withdrawalCredentials',
+      description: 'Withdrawal credentials validators are deposited with — controls where exited/skimmed ETH lands',
+      contract: 'Lido',
+      functionName: 'getWithdrawalCredentials',
+      abi: lidoAbi,
+      decode: 'string',
+      category: 'config',
+      severity: 'critical',
+    },
+    {
+      name: 'treasury',
+      description: 'Address receiving the treasury share of staking rewards (Aragon Agent)',
+      contract: 'Lido',
+      functionName: 'getTreasury',
+      abi: lidoAbi,
+      decode: 'address',
+      category: 'access',
+      severity: 'critical',
+    },
+    {
+      name: 'lidoLocator',
+      description: 'LidoLocator address the core contract resolves every peer component through',
+      contract: 'Lido',
+      functionName: 'getLidoLocator',
+      abi: lidoAbi,
+      decode: 'address',
+      category: 'config',
+      severity: 'info',
+    },
+
+    // -- wstETH --
+    {
+      name: 'wstEthExchangeRate',
+      description: 'stETH redeemable for 1 wstETH — reflects accumulated staking rewards since wrap',
+      contract: 'WstETH',
+      functionName: 'stEthPerToken',
+      abi: wstEthAbi,
+      decode: 'wad',
+      category: 'rate',
+      severity: 'info',
+    },
+
+    // -- node operators --
+    {
+      name: 'nodeOperatorsCount',
+      description: 'Total registered node operators in the curated staking module',
+      contract: 'NodeOperatorsRegistry',
+      functionName: 'getNodeOperatorsCount',
+      abi: norAbi,
+      decode: 'uint',
+      category: 'state',
+      severity: 'info',
+    },
+    {
+      name: 'activeNodeOperatorsCount',
+      description: 'Node operators currently active and eligible for new deposits',
+      contract: 'NodeOperatorsRegistry',
+      functionName: 'getActiveNodeOperatorsCount',
+      abi: norAbi,
+      decode: 'uint',
+      category: 'state',
+      severity: 'info',
+    },
+    {
+      name: 'norNonce',
+      description: 'Increments on any change to operator keys/limits — used to detect stale/front-run deposit data',
+      contract: 'NodeOperatorsRegistry',
+      functionName: 'getNonce',
+      abi: norAbi,
+      decode: 'uint',
+      category: 'state',
+      severity: 'info',
+    },
+
+    // -- withdrawal queue --
+    {
+      name: 'isBunkerModeActive',
+      description: 'Whether the withdrawal queue is in bunker mode (CL-level slashing/penalty event) — changes stETH:ETH withdrawal accounting',
+      contract: 'WithdrawalQueue',
+      functionName: 'isBunkerModeActive',
+      abi: withdrawalQueueAbi,
+      decode: 'bool',
+      category: 'risk',
+      severity: 'critical',
+    },
+    {
+      name: 'bunkerModeSinceTimestamp',
+      description: 'Timestamp bunker mode was activated',
+      contract: 'WithdrawalQueue',
+      functionName: 'bunkerModeSinceTimestamp',
+      abi: withdrawalQueueAbi,
+      decode: 'uint',
+      category: 'state',
+      severity: 'warning',
+    },
+    {
+      name: 'lastRequestId',
+      description: 'Highest withdrawal request id issued',
+      contract: 'WithdrawalQueue',
+      functionName: 'getLastRequestId',
+      abi: withdrawalQueueAbi,
+      decode: 'uint',
+      category: 'state',
+      severity: 'info',
+    },
+    {
+      name: 'lastFinalizedRequestId',
+      description: 'Highest withdrawal request id finalized and claimable — gap vs lastRequestId is the unfinalized withdrawal backlog',
+      contract: 'WithdrawalQueue',
+      functionName: 'getLastFinalizedRequestId',
+      abi: withdrawalQueueAbi,
+      decode: 'uint',
+      category: 'state',
+      severity: 'warning',
+    },
+    {
+      name: 'minWithdrawalAmount',
+      description: 'Minimum stETH amount per withdrawal request',
+      contract: 'WithdrawalQueue',
+      functionName: 'MIN_STETH_WITHDRAWAL_AMOUNT',
+      abi: withdrawalQueueAbi,
+      decode: 'uint',
+      category: 'config',
+      severity: 'info',
+    },
+    {
+      name: 'maxWithdrawalAmount',
+      description: 'Maximum stETH amount per withdrawal request',
+      contract: 'WithdrawalQueue',
+      functionName: 'MAX_STETH_WITHDRAWAL_AMOUNT',
+      abi: withdrawalQueueAbi,
+      decode: 'uint',
+      category: 'config',
+      severity: 'info',
+    },
+
+    // -- deposit security module (guardian committee) --
+    {
+      name: 'guardianQuorum',
+      description: 'Guardian signatures required for DepositSecurityModule to authorize a deposit or emergency pause',
+      contract: 'DepositSecurityModule',
+      functionName: 'getGuardianQuorum',
+      abi: dsmAbi,
+      decode: 'uint',
+      category: 'access',
+      severity: 'critical',
+    },
+    {
+      name: 'dsmOwner',
+      description: 'Can add/remove guardians and change the quorum — controls who gates validator deposits',
+      contract: 'DepositSecurityModule',
+      functionName: 'getOwner',
+      abi: dsmAbi,
+      decode: 'address',
+      category: 'access',
+      severity: 'critical',
+    },
+    {
+      name: 'pauseIntentValidityPeriodBlocks',
+      description: 'Block window during which a guardian pause signature remains valid',
+      contract: 'DepositSecurityModule',
+      functionName: 'getPauseIntentValidityPeriodBlocks',
+      abi: dsmAbi,
+      decode: 'uint',
+      category: 'config',
+      severity: 'info',
+    },
+    {
+      name: 'maxOperatorsPerUnvetting',
+      description: 'Max node operators guardians can unvet keys for in a single report',
+      contract: 'DepositSecurityModule',
+      functionName: 'getMaxOperatorsPerUnvetting',
+      abi: dsmAbi,
+      decode: 'uint',
+      category: 'config',
+      severity: 'info',
+    },
+
+    // -- accounting oracle / consensus --
+    {
+      name: 'accountingConsensusVersion',
+      description: 'Report schema version AccountingOracle expects from HashConsensus reports — bumping it invalidates old reporter software',
+      contract: 'AccountingOracle',
+      functionName: 'getConsensusVersion',
+      abi: accountingOracleAbi,
+      decode: 'uint',
+      category: 'config',
+      severity: 'info',
+    },
+    {
+      name: 'accountingLastProcessingRefSlot',
+      description: 'Last beacon chain reference slot processed by AccountingOracle — staleness indicator for the whole rebase pipeline',
+      contract: 'AccountingOracle',
+      functionName: 'getLastProcessingRefSlot',
+      abi: accountingOracleAbi,
+      decode: 'uint',
+      category: 'state',
+      severity: 'warning',
+    },
+    {
+      name: 'oracleQuorum',
+      description: 'Oracle committee members required to agree before an AccountingOracle report is considered final — directly controls the reported stETH rebase',
+      contract: 'HashConsensus',
+      functionName: 'getQuorum',
+      abi: hashConsensusAbi,
+      decode: 'uint',
+      category: 'access',
+      severity: 'critical',
+    },
+
+    // -- LidoLocator pointer registry (god-pointer) --
+    {
+      name: 'locatorLido',
+      description: 'Lido core contract the locator resolves to — every module trusts this pointer',
+      contract: 'LidoLocator',
+      functionName: 'lido',
+      abi: locatorAbi,
+      decode: 'address',
+      category: 'access',
+      severity: 'critical',
+    },
+    {
+      name: 'locatorAccountingOracle',
+      description: 'AccountingOracle the locator resolves to — repointing it swaps out the entire rebase reporting pipeline',
+      contract: 'LidoLocator',
+      functionName: 'accountingOracle',
+      abi: locatorAbi,
+      decode: 'address',
+      category: 'access',
+      severity: 'critical',
+    },
+    {
+      name: 'locatorStakingRouter',
+      description: 'StakingRouter the locator resolves to — owns module registration and per-module fee routing',
+      contract: 'LidoLocator',
+      functionName: 'stakingRouter',
+      abi: locatorAbi,
+      decode: 'address',
+      category: 'access',
+      severity: 'critical',
+    },
+    {
+      name: 'locatorDepositSecurityModule',
+      description: 'DepositSecurityModule the locator resolves to — repointing it swaps out the guardian committee gating deposits',
+      contract: 'LidoLocator',
+      functionName: 'depositSecurityModule',
+      abi: locatorAbi,
+      decode: 'address',
+      category: 'access',
+      severity: 'critical',
+    },
+    {
+      name: 'locatorTreasury',
+      description: 'Treasury address the locator resolves to — where protocol fee revenue ultimately flows',
+      contract: 'LidoLocator',
+      functionName: 'treasury',
+      abi: locatorAbi,
+      decode: 'address',
+      category: 'access',
+      severity: 'critical',
+    },
+
+    // -- DAO governance parameters --
+    {
+      name: 'votingSupportRequiredPct',
+      description: 'Percentage of yes-votes required for a DAO vote to pass',
+      contract: 'Voting',
+      functionName: 'supportRequiredPct',
+      abi: votingAbi,
+      decode: 'percent',
+      category: 'access',
+      severity: 'critical',
+    },
+    {
+      name: 'votingMinAcceptQuorumPct',
+      description: 'Minimum participation quorum required for a DAO vote to be valid',
+      contract: 'Voting',
+      functionName: 'minAcceptQuorumPct',
+      abi: votingAbi,
+      decode: 'percent',
+      category: 'access',
+      severity: 'critical',
+    },
+    {
+      name: 'voteTime',
+      description: 'Duration a vote remains open before it can be executed',
+      contract: 'Voting',
+      functionName: 'voteTime',
+      abi: votingAbi,
+      decode: 'uint',
+      category: 'config',
+      severity: 'info',
+    },
+    {
+      name: 'objectionPhaseTime',
+      description: 'Trailing window of a vote during which only "no" votes are accepted — guards against last-block vote flipping',
+      contract: 'Voting',
+      functionName: 'objectionPhaseTime',
+      abi: votingAbi,
+      decode: 'uint',
+      category: 'config',
+      severity: 'warning',
+    },
+  ],
+
+  access: [
+    {
+      role: 'Aragon Voting',
+      description: 'Token-weighted DAO vote — required to trigger any Agent-executed protocol change (fees, oracle members, guardians, LidoLocator updates)',
+      contract: 'Voting',
+      functionName: 'supportRequiredPct',
+      abi: votingAbi,
+      severity: 'critical',
+    },
+    {
+      role: 'Aragon Agent (Treasury/Executor)',
+      description: 'Executes DAO-approved calls against every contract resolved via LidoLocator — holds treasury funds and is the ultimate admin of the protocol',
+      contract: 'Agent',
+      functionName: 'kernel',
+      abi: agentAbi,
+      severity: 'critical',
+    },
+    {
+      role: 'DepositSecurityModule Owner',
+      description: 'Can add/remove guardians and change the guardian quorum — controls who gates validator deposits and emergency pauses',
+      contract: 'DepositSecurityModule',
+      functionName: 'getOwner',
+      abi: dsmAbi,
+      severity: 'critical',
+    },
+    {
+      role: 'Oracle Committee (HashConsensus)',
+      description: 'Guardian-style committee whose quorum determines the accepted consensus-layer report — directly drives the stETH rebase rate every day',
+      contract: 'HashConsensus',
+      functionName: 'getQuorum',
+      abi: hashConsensusAbi,
+      severity: 'critical',
+    },
+  ],
+};