Skip to content

Commit 91ed373

Browse files
themicpthemicp
authored
Merge pull request #47 from commonprefix/readme
WIP: Readme
2 parents 1f50441 + 173ddc5 commit 91ed373

File tree

9 files changed

+334
-906
lines changed

9 files changed

+334
-906
lines changed

‎README.md

+43-50
Original file line numberDiff line numberDiff line change
@@ -1,53 +1,46 @@
1-
# Light Client
1+
# Ethereum Light Client
22

3-
An Ethereum on-chain light client built in CosmWasm.
3+
An Ethereum prover/verifier implementation of a light client that employs the
4+
Sync Committee protocol of Ethereum to bridge events from Ethereum to Axelar.
45

5-
This repo is a collection of modules that work together to implement a light client:
6-
- **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.
7-
- **Light Client**: The core source of the light client.
8-
- **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.
9-
- **Types**: Common types used across the different modules.
10-
11-
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).
12-
13-
The light client currently supports only Ethereum Mainnet due to hardcoded fork versions.
14-
15-
More on the light client architecture: [Light Client Architecture](https://www.notion.so/commonprefix/Light-Client-Architecture-Draft-8fe5486c958e479ab41cdfc36a3d59ed)
16-
17-
## Execution Endpoints (WIP)
18-
### `LightClientUpdate { period: u64, update: LightClientUpdate }`
19-
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.
20-
21-
### `UpdateForks { forks: Forks }`
22-
Receives and stores configuration about the chain's forks.
23-
24-
### `VerifyBlock { verification_data: BlockVerificationData }`
25-
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.
6+
More on the [Light Client Architecture](https://commonprefix.notion.site/Light-Client-Architecture-Draft-8fe5486c958e479ab41cdfc36a3d59ed?pvs=4)
267

27-
### `VerifyTopicInclusion { receipt: Bytes[], topic: Bytes[] }`
28-
It RLP-decodes the receipt from the input and verifies that the topic is included in the receipt's events.
29-
30-
## Test
31-
32-
```sh
33-
cargo test
34-
```
35-
36-
## Build
37-
38-
```sh
39-
cargo wasm
40-
cosmwasm-check ./target/wasm32-unknown-unknown/release/light_client.wasm
41-
42-
docker run --rm -v "$(pwd)":/code \
43-
--mount type=volume,source="$(basename "$(pwd)")_cache",target=/code/target \
44-
--mount type=volume,source=registry_cache,target=/usr/local/cargo/registry \
45-
cosmwasm/rust-optimizer:0.12.11
46-
```
47-
48-
## Acknowledgements
49-
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:
50-
- [Helios](https://github.com/a16z/helios/) for a major part of the light client verification/processing.
51-
- [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.
52-
- [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.
53-
- [ssz_rs](https://github.com/polytope-labs/ssz-rs) for SSZ serialization/deserialization.
8+
This repo is a collection of modules that work together to implement a light client.
9+
- **Light Client**: The core source of the verifier.
10+
- **Contracts** The module that packages the light client verifier in an on-chain CosmWasm contract.
11+
- **Feeder**: Off-chain component that will feed the light client with Update
12+
messages to keep up with the latest sync-committee.
13+
- **Types**: Common types used across the different modules.
14+
- **Relayer**: The core off-chain component, responsible for consuming the
15+
events from the queue, generating the the necessary proofs, and providing them
16+
to the verifier along with the event.
17+
- **Eth** An auxiliary package for querying the Ethereum beacon and execution APIs.
18+
19+
More details about the packages are in their corresponding READMEs.
20+
21+
## Setting up the relayer
22+
The relayer module consumes events from a rabbitMQ instance that is implemented
23+
in Axelar and submits them to the on-chain verifier that exists in the
24+
`light-client` package. To set up the relayer the following steps are
25+
required.
26+
- Set up an instance of the [state prover](https://github.com/commonprefix/state-prover).
27+
- Obtain an Ethereum Beacon and Execution API URLs, the gateway address and the
28+
Wasm URL.
29+
- Deploy the light client verifier by following the instructions in the
30+
`contracts` package.
31+
- Go to the `relayer` package and follow the instructions mentioned there for
32+
running both the feeder and the relayer.
33+
34+
35+
## Acknowledgments
36+
This project uses open-source code from the following projects. We are deeply
37+
grateful for all the work they've put into developing this software, their
38+
commitment to open-source software, and for licensing the work using a
39+
permissive license which allowed us to incorporate their work:
40+
- [Helios](https://github.com/a16z/helios/) for a major part of the light client
41+
verification/processing.
42+
- [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.
43+
- [ethers.rs](https://github.com/gakonst/ethers-rs) and
44+
[alloy.rs](https://github.com/alloy-rs/core) for communicating with Ethereum and
45+
for encoding/decoding execution messages.
46+
- [ssz_rs](https://github.com/polytope-labs/ssz-rs) for SSZ serialization/deserialization.

‎eth/README.md

+68
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
# Types
2+
3+
This package exports connectors for both the beacon and the execution API of
4+
Ethereum. It is being used by the prover for interacting with the Ethereum
5+
chain.
6+
7+
## Beacon API implementation
8+
9+
```
10+
pub trait EthBeaconAPI {
11+
/// Get the block root for a given slot.
12+
async fn get_block_root(&self, slot: u64) -> Result<Root, RPCError>;
13+
14+
/// Get the light client bootstrap for a given block root.
15+
async fn get_bootstrap(&self, block_root: &'_ [u8]) -> Result<Bootstrap, RPCError>;
16+
17+
/// Get the light client updates for a given period range.
18+
async fn get_updates(&self, period: u64, count: u8) -> Result<Vec<Update>, RPCError>;
19+
20+
/// Get the latest light client finality update.
21+
async fn get_finality_update(&self) -> Result<FinalityUpdate, RPCError>;
22+
23+
/// Get the latest light client optimistic update.
24+
async fn get_optimistic_update(&self) -> Result<OptimisticUpdate, RPCError>;
25+
26+
/// Get the beacon block header for a given slot.
27+
async fn get_latest_beacon_block_header(&self) -> Result<BeaconBlockHeader, RPCError>;
28+
29+
/// Get the beacon block header for a given slot.
30+
async fn get_beacon_block_header(&self, slot: u64) -> Result<BeaconBlockHeader, RPCError>;
31+
32+
/// Get the beacon block for a given slot.
33+
async fn get_beacon_block(&self, slot: u64) -> Result<BeaconBlockAlias, RPCError>;
34+
35+
/// Get the block roots tree for a given start slot. This will return a vector of length
36+
/// `SLOTS_PER_HISTORICAL_ROOT` with the block roots for the given range. If any of the block
37+
38+
/// roots fail to resolve, the previous root will be used instead.
39+
async fn get_block_roots_tree(
40+
&self,
41+
start_slot: u64,
42+
) -> Result<Vector<Root, SLOTS_PER_HISTORICAL_ROOT>, RPCError>;
43+
}
44+
```
45+
46+
## Execution API implementation
47+
48+
```
49+
pub trait EthExecutionAPI {
50+
/// Get the receipts for a block
51+
async fn get_block_receipts(&self, block_number: u64) -> Result<Vec<TransactionReceipt>, ProviderError>;
52+
53+
/// Get a block by its block number. This method returns the block without the full transactions.
54+
async fn get_block(&self, block_number: u64) -> Result<Option<Block<H256>>, ProviderError>;
55+
56+
/// Get a block by its block number. This method returns the block with the full transactions.
57+
async fn get_block_with_txs(&self, block_number: u64) -> Result<Option<Block<Transaction>>, ProviderError>;
58+
59+
/// Get multiple blocks by their block numbers.
60+
async fn get_blocks(&self, block_numbers: &[u64]) -> Result<Vec<Option<Block<H256>>>, ProviderError>;
61+
62+
/// Get the latest block number.
63+
async fn get_latest_block_number(&self) -> Result<U64, ProviderError>;
64+
65+
/// Get logs for a given filter.
66+
async fn get_logs(&self, filter: &Filter) -> Result<Vec<Log>, ProviderError>;
67+
}
68+
```

0 commit comments

Comments
 (0)