How does Shadow work?

How does Shadow work?

Shadow unlocks custom onchain data that you can pull into your subgraph or database for enhanced indexing and analytics, with just a few lines of code.

This post explains:

  • How you can generate custom onchain data with Shadow
  • Key concepts of shadow forks, shadow contracts, and shadow event logs
  • Fetching custom data from your shadow fork with your Shadow RPC, and connecting it to your subgraph provider or database

How do I generate custom data?

Shadow enables you to add custom event logs and view functions to any deployed contract, and provides you with familiar hosted RPC endpoints to get your data.

Here are the steps:

  1. Log into your Shadow account
  2. Search for a contract address
  3. Edit contract code to add your own event logs and view functions
  4. Deploy the edited contract on your shadow fork
  5. Make Shadow RPC requests to get your custom data
The original CryptoPunks contract emits the PunkBought event in the wrong place, resulting in inaccurate data. We can fix this using Shadow.
Your shadow fork has its own Shadow RPC URL, which you can request your custom data from.

What is a shadow fork?

Shadow provides your team its own hosted shadow fork – an offchain environment that mirrors mainnet chain state in realtime, highly optimized for data access.

  • You have full control within your shadow fork. You can add custom event logs and view functions to any contract to get the exact data you need.
  • Any edits you make to contracts pertain only to your own shadow fork. Nothing on mainnet is affected, and shadow forks don't talk to each other.
  • Your shadow fork re-executes mainnet transactions in realtime and generates custom data, reflecting all the contract changes you made.

What is a shadow contract?

When you modify a contract in Shadow, its bytecode is updated and replaced at the same contract address on your shadow fork.

  • Shadow contracts have the same exact write (e.g. state-changing) functions as their counterparts deployed on the public chain, but can also include additional custom events and view functions that you add.
  • This means that as your shadow fork re-executes transactions that occur on the public chain, its state stays in sync, but it also has your additional custom data.
  • Unlike their publicly deployed counterparts, shadow contracts don't have any contract size limitations and can be easily updated at any time.

What is a shadow event?

A shadow event is an event log that only lives in a shadow contract, and not on the version of the contract that is deployed on a public chain.

  • Shadow events are fully customizable for any contract, don't cost any gas to emit, and can access any internal contract state.
  • They are a powerful way to access enriched smart contract data for analysis, indexing, and observability purposes.
  • You can significantly reduce downstream data pipelines by writing the indexing logic you need directly in the contract itself.

How do I get data from my shadow fork?

Your shadow fork has its own hosted Shadow RPC, which basically behaves like a mainnet RPC, but also has the extra data you've defined.

  • To access data on your shadow fork, you make requests to your Shadow RPC with standard read methods, e.g. eth_getLogs and eth_call.
  • Simply swap your mainnet RPC URL with your Shadow RPC URL.
  • You can connect your Shadow RPC to subgraph providers and indexing pipelines, or pull data from it into your database.

What does Shadow provide?

Shadow provides you hosted tools and infrastructure to:

  • Spin up a new shadow fork in one click
  • Edit any contract to add custom event logs and view functions
  • Instantly access your data via standard RPC methods
  • Quickly backfill shadow events for past transactions
  • Connect your Shadow RPC to your subgraph or database

We manage lots of boring things for you, including:

  • Nodes for both the shadow fork and public chain
  • Keeping state in sync in realtime, including re-orgs
  • Compiling and deploying contracts on your shadow fork
  • Proxy patterns and applying changes to all factory created contracts
  • Shadow RPC endpoints, which you can use with subgraphs
  • Decoded and indexed event data exports to your database

How do I get started?

Head to to create a free trial account, and get custom data in minutes by following our step-by-step Getting Started guide at

For more resources:

  • Follow us on Twitter for tips and important updates
  • Get help and join the conversation on Telegram
  • Subscribe to our blog for case studies and more announcements

Want to build the future of crypto data infra?

Check out our open roles if what we're building resonates – we're hiring talented engineers to join Shadow's founding team.