📚Concepts
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, permissionless to write on any contract, don't cost any gas to emit, and can access any internal contract state.
Shadow events are a powerful way to access realtime data for analysis, indexing, and testing purposes, and can significantly reduce the number of data pipelines that you need to maintain.
You can access shadow events via standard methods (e.g. eth_getLogs) using a Shadow RPC, or you can have Shadow automatically decode and index the data for you to export. We currently offer hourly data exports in Parquet to GCP/S3, and are actively working on other export formats.
What is a shadow contract?
When you modify a contract in Shadow to include new shadow events, 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 executes transactions that occur on the public chain, its state stays in sync, but it also has additional custom data accessible to you.
Unlike their publicly deployed counterparts, shadow contracts don't have any contract size limitations, can be easily updated at any time, and anyone can write their own version of one.
You can compile and deploy shadow contracts in one-click, and Shadow also handles factory created contracts (e.g. only need to deploy once) and proxy contracts for you.
What is a shadow fork?
Shadow forks are powerful private execution environments that can be spun up instantly in one click. They're designed to mirror the state of a public blockchain in realtime, but differ in a few important ways that improve data accessibility.
On public blockchains:
Smart contracts are rigid by design and are hard to change once deployed which is great for security, but bad for data accessibility. This presents a lot of data and indexing problems downstream.
Contracts have a 24,576 byte size limit, which often forces developers to choose between functionality and data accessibility.
Generating semantic data (e.g. event logs) costs gas, which are paid by end users. These fees are several orders of magnitude greater than the cost of equivalent operations in a traditional software stack.
On shadow forks:
Smart contracts are flexible and augmenting them is permissionless. Anyone can write a shadow implementation for any contract, at any time.
People who need onchain data can get it precisely for their specific needs on-demand, and everyone else has nothing to worry about.
Gas fees and contract size limits are removed. Projects can optimize their mainnet contracts and reduce gas fees for users by moving event logs and view functions to a shadow contract implementation, and make room for new functionality while significantly improving data accessibility.
What is a shadow node?
A shadow node is a client that makes data on a shadow fork accessible. You can make all of the standard RPC calls to shadow nodes in the same way you do normal nodes – all you need to do is swap out the RPC URL. Shadow hosts and manages shadow nodes for you.
We plan to open source shadow nodes in the future so anyone can run them locally, and have them work with node clients like Reth, Erigon, and Geth.
