feat: follow proxies and use Sourcify as the only source of reference ABIs

[marcocastignoli]

What

Reference ABIs are fetched from Sourcify only, and proxies are followed. This is the work we discussed for the Sourcify fork of the library; the commits are separate so you can take the proxy following without the Etherscan removal.

• Follow proxies. The client asks Sourcify for proxyResolution and merges the ABI of every implementation into the proxy's ABI, following nested proxies and diamonds (checked on the LI.FI diamond, 40 facets). The "likely to be a proxy, validation skipped" shortcut is removed from both linters, so proxies are validated against the merged ABIs. A proxy resolution error, or an implementation that is not verified on Sourcify, is a failure for that deployment rather than a silent fallback to the proxy's own ABI.
• Sourcify as the only source. The Etherscan fallback for reference ABIs is removed, along with the ETHERSCAN_API_KEY documentation for lint and generate. Supported chains come from Sourcify, and lint messages link to repo.sourcify.dev. The Etherscan transport stays for descriptors whose abi field is an Etherscan URL.
• Distinct failure modes. ContractNotVerifiedError, ProxyImplementationNotVerifiedError and ChainNotSupportedError replace the single "Could not fetch ABI" case, each with its own lint title (documented in docs/pages/lint.md). "Could not fetch ABI" is kept for transient failures, and the classifier now traces the deployments it skips.
• Caching. Sourcify responses carry no caching headers, so the existing hishel cache never stored them and every run refetched everything. Sourcify responses are now force-cached for one hour (other hosts follow their own headers), get_contract_abis is memoized within a run, and ERC7730_NO_CACHE=1 disables the cache.
• Sourcify token. With SOURCIFY_TOKEN set, X-Sourcify-Token is sent on Sourcify requests, for callers exempted from rate limiting.
• Test registries. update = none on the two registry submodules, with an explicit --checkout in CI and the developer docs, so pip install from git works without an SSH key (ledger-asset-dapps has a nested submodule with an SSH URL).

Effect on the registry

erc7730 lint over the clear signing registry, before and after:

	before	after
Skipped as "likely a proxy"	7	0
"Unknown selector" warnings	326	83
"Missing display format" warnings	3669	5223
Fetch failures	8	7

"Missing display format" goes up because the merged ABIs include the proxy admin functions. The 7 remaining fetch failures are contracts verified nowhere, Sei precompiles, an unverified implementation, and a chain Sourcify does not support.

Proxy patterns Sourcify does not resolve will keep failing: Celo core Proxy, Aragon AppProxyUpgradeable (Lido stETH), StarkGate, Kiln VaultBeaconProxy, Polygon ValidatorShareProxy.

Tests

With --run-v1 --run-integration: 2558 passed, 2 skipped, 2 failed. The 2 failures are real descriptor bugs that the proxy shortcut was hiding: lido/calldata-stETH-L2.json and lido/calldata-wstETH-L2.json use paths like #.amount while the implementation ABI names the parameters amount_, recipient_ and so on. They need a fix in clear-signing-erc7730-registry.

🤖 Generated with Claude Code