Warning

This is a legacy repository and production API no longer interacts with those contracts. For latest version check Satellite repository.

Herodotus on Starknet

This repository contains and implements smart contracts deployed on Starknet.

This repository contains the following modules:

• Core - Implements the core logic behind Herodotus.
• Remappers - Implements a util allowing to map arbitrary timestamps to L1 block numbers.
• Turbo - Acts as a frontend to the Core contracts, provides great UX to developers and simplifies the integration.
• L1 - Smart contracts deployed on Ethereum L1 responsible for synchronizing with L1.

Core

This module is responsible for:

• Processing new block headers and growing the MMR.
• Receiving and handling L1 messages containing blockhashes and Poseidon roots of the MMR which generation has been SHARP proven.
• Verifying state proofs and saving the proven values in the FactsRegistry

Error codes

Headers Store

• ONLY_COMMITMENTS_INBOX - Only commitments inbox (address saved in commitments_inbox variable) can send messages to this function.

• SRC_MMR_NOT_FOUND - Source MMR (one from which the branch is created) with provided MMR ID does not exist in the store.

• SRC_MMR_ID_0_NOT_ALLOWED - Source MMR (one from which the branch is created) with ID 0 is not allowed.

• NEW_MMR_ID_0_NOT_ALLOWED - New MMR (one that is created from source branch) with ID 0 is not allowed.

• ROOT_0_NOT_ALLOWED - Creating MMR with root 0 is not allowed.

• NEW_MMR_ALREADY_EXISTS - New MMR (one that is created from source branch) with provided ID already exists in the store.

• MMR_NOT_FOUND - MMR with provided ID does not exist in the store.

• PROOF_AND_REF_BLOCK_NOT_ALLOWED - process_batch can't be called with both proof and reference block. Please select either one.

• INVALID_HEADER_RLP - Provided header RLP is invalid.

• INVALID_MMR_PROOF - Provided MMR proof (proof or peaks or both) is invalid.

• INVALID_START_BLOCK - Cannot read block number from the first header RLP.

• BLOCK_NOT_RECEIVED - Block which was referenced in process_batch was not written to the store with receive_hash function.

• INVALID_INITIAL_HEADER_RLP - First header RLP didn't match the reference block.

• MMR_APPEND_FAILED - Append to MMR function failed, most likely due to invalid peaks.

• INVALID_PARENT_HASH_RLP - Could not read parent hash from the provided header RLP.

Commitments Inbox

• ONLY_OWNER - Only owner can call this function.

• ONLY_L1_MESSAGE_SENDER - Only L1 message sender can call this function.

Timestamps to block numbers mapper

This module implements the logic described in this doc: https://herodotus.notion.site/Blocks-timestamp-to-number-mapper-6d6df20f31e24afdba89fe67c04ec5e2?pvs=4

Turbo

WIP -> EVM implementation https://github.com/HerodotusDev/herodotus-evm

More info: https://www.notion.so/herodotus/Herodotus-on-Starknet-Smart-contracts-flow-bb42da2b3f434c84900682ee8a954531

Dependencies

This repository highly relies on the work implemented in: https://github.com/HerodotusDev/cairo-lib

Herodotus Dev Ltd - 2023.