Merge pull request #47 from commonprefix/readme

WIP: Readme

README.md

@@ -1,53 +1,46 @@
-# Light Client
+# Ethereum Light Client
 
-An Ethereum on-chain light client built in CosmWasm.
+An Ethereum prover/verifier implementation of a light client that employs the
+Sync Committee protocol of Ethereum to bridge events from Ethereum to Axelar.
 
-This repo is a collection of modules that work together to implement a light client:
-- **Trie Verifier**: It is a CosmWasm module that receives an MPT root, a proof, and a leaf and verifies that the leaf is indeed a part of that root using the provided proof.
-- **Light Client**: The core source of the light client.
-- **Feeder**: Off-chain component that will feed the light client with Update messages from the Beacon API, as well as the necessary verification data to verify a message.
-- **Types**: Common types used across the different modules.
-
-The light client is heavily inspired by a16z's Helios Consensus light client, with a couple of simplifications, changes, and adjustments to become a valid smart contract. Also, the light client uses a fork of the milagro_bls library, which has been simplified to be CosmWasm compatible (see https://github.com/pkakelas/milagro_bls).
-
-The light client currently supports only Ethereum Mainnet due to hardcoded fork versions.
-
-More on the light client architecture: [Light Client Architecture](https://www.notion.so/commonprefix/Light-Client-Architecture-Draft-8fe5486c958e479ab41cdfc36a3d59ed)
-
-## Execution Endpoints (WIP)
-### `LightClientUpdate { period: u64, update: LightClientUpdate }`
-It receives a LightClientUpdate message from the Ethereum Beacon API. After verifying that the update is correct, it applies the changes to the state, essentially updating the current and next sync committees if needed.
-
-### `UpdateForks { forks: Forks }`
-Receives and stores configuration about the chain's forks.
-
-### `VerifyBlock { verification_data: BlockVerificationData }`
-Receives a target block, a chain of blocks, a sync committee aggregated signature, and a signature slot, and verifies that the sync committee of the light client has signed the chain of blocks back to the target block.
+More on the [Light Client Architecture](https://commonprefix.notion.site/Light-Client-Architecture-Draft-8fe5486c958e479ab41cdfc36a3d59ed?pvs=4)
 
-### `VerifyTopicInclusion { receipt: Bytes[], topic: Bytes[] }`
-It RLP-decodes the receipt from the input and verifies that the topic is included in the receipt's events.
-
-## Test
-
-```sh
-cargo test
-```
-
-## Build
-
-```sh
-cargo wasm
-cosmwasm-check ./target/wasm32-unknown-unknown/release/light_client.wasm
-
-docker run --rm -v "$(pwd)":/code \
-  --mount type=volume,source="$(basename "$(pwd)")_cache",target=/code/target \
-  --mount type=volume,source=registry_cache,target=/usr/local/cargo/registry \
-  cosmwasm/rust-optimizer:0.12.11
-```
-
-## Acknowledgements
-This project uses open source code from the following projects. We are deeply grateful to all the work they've put into developing this software, their commitment to open source software, and for licensing the work using a permissive license which allowed us to incorporate their work:
-- [Helios](https://github.com/a16z/helios/) for a major part of the light client verification/processing.
-- [Polytope's sync_committee_primitives](https://github.com/polytope-labs/sync-committee-rs) for the goerli and mainnet constants as well as some primitive beacon types.
-- [ethers.rs](https://github.com/gakonst/ethers-rs) and [alloy.rs](https://github.com/alloy-rs/core) for communicating with Ethereum and for encoding/decoding execution messages.
-- [ssz_rs](https://github.com/polytope-labs/ssz-rs) for SSZ serialization/deserialization.
+This repo is a collection of modules that work together to implement a light client.
+- **Light Client**: The core source of the verifier.
+- **Contracts** The module that packages the light client verifier in an on-chain CosmWasm contract.
+- **Feeder**: Off-chain component that will feed the light client with Update
+messages to keep up with the latest sync-committee.
+- **Types**: Common types used across the different modules.
+- **Relayer**: The core off-chain component, responsible for consuming the
+events from the queue, generating the the necessary proofs, and providing them
+to the verifier along with the event.
+- **Eth** An auxiliary package for querying the Ethereum beacon and execution APIs.
+
+More details about the packages are in their corresponding READMEs.
+
+## Setting up the relayer
+The relayer module consumes events from a rabbitMQ instance that is implemented
+in Axelar and submits them to the on-chain verifier that exists in the
+`light-client` package. To set up the relayer the following steps are
+required.
+- Set up an instance of the [state prover](https://github.com/commonprefix/state-prover).
+- Obtain an Ethereum Beacon and Execution API URLs, the gateway address and the
+Wasm URL.
+- Deploy the light client verifier by following the instructions in the
+`contracts` package.
+- Go to the `relayer` package and follow the instructions mentioned there for
+running both the feeder and the relayer.
+
+
+## Acknowledgments
+This project uses open-source code from the following projects. We are deeply
+grateful for all the work they've put into developing this software, their
+commitment to open-source software, and for licensing the work using a
+permissive license which allowed us to incorporate their work:
+- [Helios](https://github.com/a16z/helios/) for a major part of the light client
+verification/processing.
+- [Polytope's sync_committee_primitives](https://github.com/polytope-labs/sync-committee-rs) for the Goerli and mainnet constants as well as some primitive beacon types.
+- [ethers.rs](https://github.com/gakonst/ethers-rs) and
+[alloy.rs](https://github.com/alloy-rs/core) for communicating with Ethereum and
+for encoding/decoding execution messages.
+- [ssz_rs](https://github.com/polytope-labs/ssz-rs) for SSZ serialization/deserialization.

eth/README.md

@@ -0,0 +1,68 @@
+# Types
+
+This package exports connectors for both the beacon and the execution API of
+Ethereum. It is being used by the prover for interacting with the Ethereum
+chain. 
+
+## Beacon API implementation
+
+```
+pub trait EthBeaconAPI {
+    /// Get the block root for a given slot.
+    async fn get_block_root(&self, slot: u64) -> Result<Root, RPCError>;
+
+    /// Get the light client bootstrap for a given block root.
+    async fn get_bootstrap(&self, block_root: &'_ [u8]) -> Result<Bootstrap, RPCError>;
+
+    /// Get the light client updates for a given period range.
+    async fn get_updates(&self, period: u64, count: u8) -> Result<Vec<Update>, RPCError>;
+
+    /// Get the latest light client finality update.
+    async fn get_finality_update(&self) -> Result<FinalityUpdate, RPCError>;
+
+    /// Get the latest light client optimistic update.
+    async fn get_optimistic_update(&self) -> Result<OptimisticUpdate, RPCError>;
+
+    /// Get the beacon block header for a given slot.
+    async fn get_latest_beacon_block_header(&self) -> Result<BeaconBlockHeader, RPCError>;
+
+    /// Get the beacon block header for a given slot.
+    async fn get_beacon_block_header(&self, slot: u64) -> Result<BeaconBlockHeader, RPCError>;
+ 
+    /// Get the beacon block for a given slot.
+    async fn get_beacon_block(&self, slot: u64) -> Result<BeaconBlockAlias, RPCError>;
+
+    /// Get the block roots tree for a given start slot. This will return a vector of length
+    /// `SLOTS_PER_HISTORICAL_ROOT` with the block roots for the given range. If any of the block
+
+    /// roots fail to resolve, the previous root will be used instead.
+    async fn get_block_roots_tree(
+        &self,
+        start_slot: u64,
+    ) -> Result<Vector<Root, SLOTS_PER_HISTORICAL_ROOT>, RPCError>;
+}
+```
+
+## Execution API implementation  
+
+```
+pub trait EthExecutionAPI {
+    /// Get the receipts for a block
+    async fn get_block_receipts(&self, block_number: u64) -> Result<Vec<TransactionReceipt>, ProviderError>;
+
+    /// Get a block by its block number. This method returns the block without the full transactions.
+    async fn get_block(&self, block_number: u64) -> Result<Option<Block<H256>>, ProviderError>;
+
+    /// Get a block by its block number. This method returns the block with the full transactions.
+    async fn get_block_with_txs(&self, block_number: u64) -> Result<Option<Block<Transaction>>, ProviderError>;
+
+    /// Get multiple blocks by their block numbers.
+    async fn get_blocks(&self, block_numbers: &[u64]) -> Result<Vec<Option<Block<H256>>>, ProviderError>;
+
+    /// Get the latest block number.
+    async fn get_latest_block_number(&self) -> Result<U64, ProviderError>;
+
+    /// Get logs for a given filter.
+    async fn get_logs(&self, filter: &Filter) -> Result<Vec<Log>, ProviderError>;
+}
+```