Skip to content

README.md

Latest commit

 

History

History
73 lines (50 loc) · 4.49 KB

README.md

File metadata and controls

73 lines (50 loc) · 4.49 KB

shell-chain

A docs-first Rust implementation repository for the Shell blockchain protocol. The focus today is on making the design, interfaces, and implementation boundaries clear before code scaffolding begins.

Current Status

shell-chain is still primarily a documentation-and-specification repository, but it now also includes a minimal Rust workspace bootstrap. The repository has a root Cargo.toml, a working shell-primitives crate, early shell-crypto, shell-state, and shell-mempool crates, and shared fixtures under vectors/. It does not yet provide a runnable node, a full crate tree, or a production-ready implementation of the protocol.

At this stage, the core implementation specs in specs/ are all at draft status and are intended to be detailed enough to drive initial implementation planning, including crate scaffolding, fixture planning, and validation/interface placement.

shell-chain in One Page

The planned implementation centers on a few protocol ideas that shape every crate and API boundary:

  • Post-quantum-first authorization: account and validator signing paths are designed around post-quantum-capable (PQ) signature schemes instead of legacy ECDSA assumptions.
  • Witness separation: executable transaction envelopes stay separate from large cryptographic witness sidecars, meaning the heavier proof bundle travels alongside the core object instead of being folded into it.
  • Dual-lane fee accounting: normal execution pricing and witness-heavy pricing are tracked separately so expensive proof bandwidth does not hide inside one fee number.
  • SSZ-first data model: wire-facing objects are expected to keep canonical SSZ (SimpleSerialize) encoding and merkleization behavior.
  • Stateless-friendly validation: transaction admission, block import, and proof reconstruction are split into stages so light and full validation paths can share the same object model.
  • Unified binary-tree state: the state layer is intended to use a compressed binary-tree accumulator rather than a legacy fixed-depth sparse tree.

Repository Layout

Path Purpose
README.md High-level repository overview and current status
docs/ Reader-friendly guides for onboarding, API expectations, and contribution workflow
specs/ Implementation specifications for data types, validation flow, testing vectors, and planned module boundaries

Planned Workspace Shape

The crate layout below describes the intended full architecture. Today, shell-primitives, shell-crypto, shell-state, and shell-mempool are scaffolded in the workspace, while the remaining crates are still placeholders:

  • shell-primitives: SSZ-facing types, roots, aliases, and canonical codec helpers
  • shell-crypto: signature dispatch, hashing boundaries, and scheme-specific verification adapters
  • shell-state: state-key modeling, witness verification, and accumulator abstractions
  • shell-execution: execution-layer transition logic and post-state output calculation
  • shell-mempool: transaction admission, fee-floor checks, and cheap-first screening
  • shell-consensus: block-level binding, header/body checks, and import orchestration
  • shell-network: peer-facing propagation, fetch policy, and reputation consequences
  • shell-cli: operator entry points, configuration, and RPC surface

Documentation Map

After this overview, continue through the repository in this order:

  1. docs/getting-started.md for the onboarding path and brief terminology orientation.
  2. docs/api-reference.md for the planned public API surface and stability expectations.
  3. specs/README.md for the implementation-spec index.

Recommended Spec Reading Order

From there, continue through the core specs in this order:

  1. specs/crate-structure.md
  2. specs/data-types.md
  3. specs/validation-rules.md
  4. specs/testing-vectors.md

When you are ready to make a repository change, continue with docs/contributing.md.

Build and Test Status

A minimal Rust workspace is now scaffolded with shell-primitives plus early shell-crypto, shell-state, and shell-mempool interfaces. The repository-local bootstrap commands are:

  • cargo fmt --all
  • cargo check --workspace
  • cargo test --workspace

The remaining planned crates under crates/ are still directory placeholders until their crate-specific scaffolding is introduced. The documentation set in specs/ remains the source of truth for open protocol areas and for behavior that the current bootstrap intentionally keeps abstract.