ethexe_common/
lib.rs

1// Copyright (C) Gear Technologies Inc.
2// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0
3
4//! # ethexe-common
5//!
6//! Shared vocabulary crate for the ethexe execution layer: block model, on-chain
7//! events, validator commitments, injected transactions, storage trait abstractions,
8//! and protocol constants. It defines shapes and trait interfaces only — the
9//! concrete storage backends live in `ethexe-db`. Being `no_std`-compatible, it
10//! links into both the WASM runtime
11//! (`ethexe-runtime`) and the native node binary.
12//!
13//! ## Role in the stack
14//!
15//! This crate depends on no other ethexe workspace member (it sits on `gear-core`,
16//! `gprimitives`, and `gsigner`) and nearly every other ethexe crate depends on it,
17//! making it a foundational leaf. For example, `ethexe-consensus` exchanges
18//! [`consensus::BatchCommitmentValidationRequest`] /
19//! [`consensus::BatchCommitmentValidationReply`] messages defined here, and
20//! `ethexe-db` provides backends for the [`db`] storage traits declared here.
21//!
22//! ## Public API
23//!
24//! - [`consensus`] — Validation request/reply messages and timeline helpers for the batch commitment protocol.
25//! - [`db`] — `*StorageRO` / `*StorageRW` trait abstractions and block-metadata types.
26//! - [`events`] — On-chain event model: `BlockEvent` (Mirror/Router variants) and `WVaraEvent`.
27//! - [`gear`] — Protocol commitments ([`gear::BatchCommitment`] and siblings) and [`gear::StateTransition`].
28//! - [`injected`] — Injected transactions, promises, and receipts for inbound cross-chain messaging.
29//! - [`malachite`] — Sequencer block-payload shape ([`malachite::Transactions`], `Transaction`).
30//! - [`network`] — Validator network messages (`ValidatorMessage` and signed/verified variants).
31//! - [`ecdsa`] — secp256k1 re-exports from `gsigner`.
32//! - [`mock`] — Test helpers and proptest fixtures (feature `mock`).
33//!
34//! Flattened crate-root re-exports include [`HashOf`], [`MaybeHashOf`],
35//! [`BlockHeader`], [`SimpleBlockData`], [`BlockData`], [`ValidatorsVec`],
36//! [`EmptyValidatorsError`], and the `gsigner` crypto surface ([`Address`],
37//! [`Digest`], [`PublicKey`], [`Signature`], [`SignedData`], [`ToDigest`],
38//! [`VerifiedData`], …).
39//!
40//! Crate-root constants include the per-MB soft execution limits
41//! ([`OUTGOING_MESSAGES_SOFT_LIMIT`], [`OUTGOING_MESSAGES_BYTES_SOFT_LIMIT`],
42//! [`CALL_REPLY_SOFT_LIMIT`], [`PROGRAM_MODIFICATIONS_SOFT_LIMIT`],
43//! [`MAX_TOUCHED_PROGRAMS_PER_MB`]) and [`DEFAULT_BLOCK_GAS_LIMIT`].
44//!
45//! ## Key types
46//!
47//! - [`HashOf<T>`] — phantom-typed `H256` wrapper preventing mixing of hashes of
48//!   different payload kinds; [`MaybeHashOf<T>`] is its optional sibling.
49//! - [`BlockHeader`] / [`SimpleBlockData`] / [`BlockData`] — the ethexe block model.
50//! - [`gear::BatchCommitment`] and sibling commitment types — the validator-submitted
51//!   commitment hierarchy; each implements [`ToDigest`] for Keccak256 hashing.
52//! - [`gear::StateTransition`] — a single validated program state change.
53//! - [`ValidatorsVec`] — a `NonEmpty<Address>` wrapper guaranteeing the validator set
54//!   is never empty.
55//! - [`injected::InjectedTransaction`] / [`injected::Promise`] — inbound cross-chain
56//!   transaction and its promise/receipt lifecycle.
57//!
58//! ## Invariants
59//!
60//! - [`ValidatorsVec`] cannot be constructed from an empty collection; `try_from`
61//!   returns [`EmptyValidatorsError`] on empty input.
62//! - [`DEFAULT_COMMITMENT_DELAY_LIMIT`] is a coordinator-local knob, not a protocol
63//!   constant — each coordinator selects its own value.
64
65#![cfg_attr(not(feature = "std"), no_std)]
66
67extern crate alloc;
68
69pub mod consensus;
70pub mod db;
71pub mod events;
72pub mod gear;
73mod hash;
74pub mod injected;
75pub mod malachite;
76pub mod network;
77mod primitives;
78mod utils;
79mod validators;
80
81#[cfg(feature = "mock")]
82pub mod mock;
83
84pub use gsigner::{
85    Address, ContractSignature, Digest, FromActorIdError, PrivateKey, PublicKey, Signature,
86    SignedData, SignedMessage, ToDigest, VerifiedData,
87};
88pub use validators::{EmptyValidatorsError, ValidatorsVec};
89pub mod ecdsa {
90    pub use gsigner::secp256k1::{
91        ContractSignature, PrivateKey, PublicKey, Signature, SignedData, SignedMessage,
92        VerifiedData,
93    };
94}
95pub use gear_core;
96pub use gprimitives;
97pub use hash::*;
98pub use k256;
99pub use primitives::*;
100pub use sha3;
101pub use utils::*;
102
103/// Default block gas limit for the node.
104pub const DEFAULT_BLOCK_GAS_LIMIT: u64 = 4_000_000_000_000;
105
106/// Default `commitment_delay_limit` (in Ethereum blocks). Coordinator-local
107/// knob: how many EBs a `BatchCommitment` stays valid past its target block.
108/// Not a protocol constant — every coordinator picks its own value.
109pub const DEFAULT_COMMITMENT_DELAY_LIMIT: core::num::NonZero<u8> =
110    core::num::NonZero::new(16).expect("16 != 0");
111
112/// Maximum number of touched programs per MB.
113pub const MAX_TOUCHED_PROGRAMS_PER_MB: u32 = 128;
114
115// Soft limits for one MB processing. Stops execution if any of them is exceeded.
116pub const OUTGOING_MESSAGES_SOFT_LIMIT: u32 = 128;
117pub const OUTGOING_MESSAGES_BYTES_SOFT_LIMIT: u32 = 32 * 1024;
118pub const CALL_REPLY_SOFT_LIMIT: u32 = 4;
119pub const PROGRAM_MODIFICATIONS_SOFT_LIMIT: u32 = MAX_TOUCHED_PROGRAMS_PER_MB / 2;
ethexe_common/lib.rs

ethexe_common/
lib.rs
