Introducing the Shadow Registry

Overview

We’re announcing the Shadow Registry – a decentralized registry of public shadow contracts stored on IPFS and registered on Base EAS. 

The Shadow Registry allows anyone to get pre-written shadow logs without needing to write any smart contract code themselves.

Now, all you need to do is decide which shadow logs you want to use, download the code for free, and run it on the Shadow platform or your own self-hosted node.

This makes it easy for data products and other 3rd party integrators to get rich onchain data, written by experts, for a wide range of contracts.

And often, these experts are the protocol teams themselves. At launch, the registry already contains data-rich shadow logs written by top protocol teams including Ambient, Pendle, Frax, Yearn, Uniswap, and Derive (fka Lyra).

Why public shadow contracts?

Shadow, along with open-source solutions like shadow-reth and Erigon overlays, have unlocked a rapid increase in the usage of shadow logs to supercharge data analysis and build better products.

Shadow logs are a powerful new primitive that empower developers with greater flexibility over how they work with smart contract data. They have quickly become an important part of the crypto builder’s toolkit:

• Smart contract developers can maintain a separation of concerns between core execution logic and data instrumentation
• App developers can get the exact indexed data they need with just a few lines of code
• Data teams are no longer stuck with just the event logs that were originally deployed in the contract

However, these benefits have mostly only been realized by the teams who have been early adopters of shadow simulation tools.

We think these benefits should be shared more broadly – and that much like source code verification, shadow contracts should be discoverable and available to the public if the author wants them to be. 

Public shadow contracts allow other 3rd party developers, analysts, and data platforms to evaluate and use pre-written shadow logs to get richer contract data with zero upfront work.

Using the Shadow Registry

The Shadow Registry is a decentralized registry of public shadow contracts stored on IPFS and registered on Base EAS.

The Shadow Registry makes it easy for:

• Protocol teams to share extra contract data with 3rd party integrators
• Data platforms and analysts to get enriched datasets for protocols

And to interface with the decentralized Shadow Registry, we’ve also built:

• logs.xyz – a simple frontend to browse and download contracts
• Shadow CLI – an open-source CLI tool for uploading to the registry

Read on for a quick overview on how to use the Shadow Registry to get and share richer smart contract data.

Viewing shadow contracts

logs.xyz provides a simple frontend to search, preview, and download shadow contracts from the Shadow Registry. It indexes the public EAS schema of IPFS content, so anyone can create their own frontend to access the registry.

You can preview the code diff of the shadow contract against the contract code deployed on the canonical chain if you want to audit its logic.

The uploader can also provide a README to provide context on how the shadow contract is intended to be used.

Downloading shadow contracts

Contracts are downloaded from the Shadow Registry as a simple JSON file that maps a contract address to its shadow contract bytecode.

Using shadow contracts

Anyone can utilize the contracts in the registry to generate shadow event logs.

Once a shadow contract is downloaded, its shadow logs can be generated using whatever offchain infrastructure you'd like – e.g. on your own self-hosted Reth or Erigon node, or through a managed provider like Shadow.

Uploading shadow contracts

Anyone can easily upload shadow contracts to IPFS using the open source Shadow CLI. The CLI guides you through the steps of creating a shadow contract with a README, pinning it to IPFS, and registering it on EAS to be indexed.

• IPFS is used to store all of the contract data (source code, bytecode, ABIs, compiler settings)
• Ethereum Attestation Service (EAS) on Base is used for indexing the IPFS Content IDs, as well as attesting to the creation and endorsement of contract data in the registry

Upload signers

When adding a new contract to the Shadow Registry, uploaders are prompted to sign a message that attests to their upload.

The signing address is stored as structured data, along with all the necessary information about the shadow contracts.

This allows us to attach some onchain identity, credibility, and reputation to uploaded shadow contracts. For example, we can display ENS names and other labels associated with the uploader address – such as matching it to the deployer address of the original mainnet contract.

Contract groups

In some scenarios, you may want to modify multiple contracts in tandem to generate the data that you want, e.g. Contract A emits a shadow log that calls a modified view function on Contract B.

In order to get the intended data results, a user would need to run the shadow versions of both Contract A and Contract B on their node.

To support this usage pattern, the Shadow Registry supports uploads and downloads of “contract groups” – bundles of contracts that are meant to be used together. Contract groups can include any number of contracts.

What’s next?

The Shadow Registry is live! Anyone can now get pre-written shadow logs and get richer data, without writing any smart contract code themselves.

Special thank you to the protocol teams who provided valuable feedback, and were part of this initial launch.

We’re excited to see more protocol teams and smart contract data experts contribute new contracts to the Shadow Registry.

Let's grow the crypto community's collective understanding of onchain activity.

To learn more about the Shadow Registry, visit these FAQs.