Overview
What is logs.xyz?
A decentralized registry of shadow contracts and offchain event logs hosted on IPFS and written by the community — which includes experts, researchers, and protocol teams themselves. Anyone can freely pull down and use contracts from the registry to generate extra smart contract data on the offchain infrastructure of their choice.
Why logs.xyz?
With the rise of open-source and hosted shadow simulation tools and infrastructure, there has been a rapid increase in useful offchain event logs.
We believe it’s important that offchain logs are discoverable and available to the public, if the author wants them to be. This allows other developers, integrators, analysts, and data platforms to find and use pre-written offchain logs for their own purposes, using whatever simulation tools and infrastructure they choose.
What are shadow contracts and offchain event logs?
Shadow contracts are smart contracts that are modified from their mainnet deployed versions for the purpose of extracting additional data. They are run on offchain infrastructure to generate offchain event logs.
Offchain event logs are LOG opcodes added to shadow contracts, which do not exist on mainnet. They generate event data through the process of running offchain infrastructure to simulate mainnet transactions against the shadow contract.
What are the benefits of offchain logs?
Offchain logs allow developers to exercise greater control over how they extract and index data from smart contracts. They make adding the LOG opcode — a widely used and commonly understood standard — accessible to anyone on any smart contract.
This new data primitive unlocks deeper data coverage and allows anyone to flexibly extract the exact data they need — eliminating many challenges of indexing onchain data today that require trace-based or state diff-based indexing approaches.
How to use
How do I use it?
logs.xyz provides a registry of shadow contracts and offchain event logs written by the community, which includes experts, researchers, and protocol teams themselves.
To utilize a pre-written shadow contract:
- Select a shadow contract or search for one by address.
- Click the “Get” button to download a JSON file with the contract address(es) and the shadow contract bytecode(s).
- Run the shadow contract bytecode(s) on offchain infrastructure / tools that have the capability of shadow simulation of mainnet transactions.
You can utilize pre-written shadow contracts and offchain events on any set of infrastructure / tools of your choosing — there are no restrictions whatsoever.
What are some offchain tools that offer shadow simulation?
- Shadow: a hosted platform for shadow-enabled RPCs and realtime database streams.
- shadow-reth: an open-source Execution Extension for Reth nodes.
- Erigon overlays: a custom endpoint for Erigon nodes.
Uploading
How do I upload a shadow contract to the registry? Who can do it?
Anyone can permissionlessly upload their own shadow contracts to the registry, which allows others to freely utilize them however they’d like.
To upload, you can use the open-source Shadow CLI — see step-by-step instructions on how to clone, compile, and upload to the registry on Github.
Why would I upload shadow contracts to the registry?
Protocol teams might upload shadow contracts to the registry to make it easy for integrators and 3rd party developers to access useful extra data from their smart contracts, which were not included in mainnet contract event logs.
Data platforms and researchers might upload shadow contracts to the registry to allow anyone to freely audit how they are generating the onchain data used in their products and services.
Are uploads limited to one shadow contract at a time?
No — you can choose to upload just one shadow contract, or include multiple shadow contracts that are intended to be used together as part of a group.
For example, if you were defining a new offchain event log that is applied across several contracts — perhaps even from different protocols — then you would include all of the different contracts with the new event in one shadow contract group.
