Eld chain

Eld is an L1 for ephemeral, content-addressed storage: data is accessed by content-address key, kept only for a TTL, then expires by protocol.

This repository is the chain implementation — protocol types (eld-common), off-chain client (eld-client), the command-line client (eld-cli), and the Tendermint ABCI node (eld-node). It is not the website, docs site, or explorer.

Want	Go here
Protocol narrative, CLI, capacity providers	docs.eld.network
Marketing / product overview	www.eld.network
Live chain UI	explorer.eld.network
This codebase (node, client, types)	this repo

Testnet is live; crate versions here are unpublished (publish = false) and protocol constants are local-dev values, not mainnet economics.

Quick start

Build and test the workspace:

Configure nodes

To run a local node (Docker Compose).

Set env vars:

cp deploy/.env.example deploy/.env   # set TENDERMINT_DIR and image tags

Next, create local wallets + Tendermint/P2P keys (gitignored). See deploy/README.md.

Run nodes

Using published images, single tendermint + node-app pair, fresh genesis

./deploy/scripts/docker/local/single/single-start-without-history.ghcr.sh

eld-app-1 is then on REST 9001 and Tendermint-1 RPC 26657. Stop with ./deploy/scripts/docker/local/single/single-stop.sh.

To build images locally or run the 4-node cluster, use the scripts mentioned in deploy/README.md.

Talk to a local node

With that node up, talk to it with eld-cli:

cargo run -p eld-cli -- wallet create my-wallet
cargo run -p eld-cli -- tx faucet 0xYourAddress
cargo run -p eld-cli -- account get 0xYourAddress

The first command that needs a node asks for the node address and writes eld-cli-config.json under the user config directory (~/.config/eld on Linux, ~/Library/Application Support/eld on macOS). wallet create writes wallets.json under the user data directory on Linux and under Application Support on macOS.

wallet create prints the address to pass to tx faucet and account get. Flags, aliases, and exit codes are in cli/README.md.

This repository

Protocol types (eld-common), off-chain client helpers (eld-client), the command-line client (eld-cli), and the ABCI node application (eld-node) for the Eld blockchain.

Library crates ship LICENSE, README.md, NOTICE, and (where relevant) CHANGELOG.md and TYPE_DESIGN.md so a future crates.io/docs.rs package is self-contained. Crates here are not published yet (publish = false).

Crates

Directory	Package	Role
common/	eld-common	Protocol types, validation, Wallet identity, CADO, capacity, pinboard
client/	eld-client	Tendermint RPC, app REST, faucet HTTP, ChainClient, CWD config, wallet files
cli/	eld-cli	Command-line client over ChainClient
node_app/	eld-node	ABCI application (Tendermint, RocksDB, libp2p, Axum REST)

Library crate imports use underscores (eld_common, eld_client) because Cargo package names may contain hyphens. eld-cli and eld-node are binary crates, not libraries.

Architecture

eld-common is the protocol library: addresses, coins, nonces, transactions and payloads, CADO paths, capacity-proof types (including on-disk SlotAllocator), pinboard and namespace types, signing Wallet identity, validation, constants, and errors.

eld-client is the off-chain process library:

• api::abci — Tendermint RPC / ABCI (AbciHttpApi, queries, broadcast_tx_commit)
• api::rest — node app REST (AppApi plus pinboard/namespace JSON DTOs) and the dev faucet
• facade — ChainClient and command wrappers that may use both stacks
• config — CWD JSON (ClientConfig, ClientSetup); wallets.json I/O at the crate root

Config loaders return Result; binaries can exit after they see an error.

eld-cli is the command-line binary on top of ChainClient.

eld-node is the ABCI application. Runtime data (data/, tx_responses/), wallets, and P2P key files are not shipped in git. Compose mounts them from deploy/docker/local/.

Supported runtimes: Docker Compose (single or 4-node). Bare-metal binary is not supported.

Hex and ID conventions: common/TYPE_DESIGN.md (canonical; workspace root TYPE_DESIGN.md points there).

Encoding

v0 uses two codecs. This is the current client/node map, not a frozen spec.

Codec	Edges
serde_json	Transaction body and Ed25519 signing (serde_json of the tx with an empty sig, then append chain_id). Mempool and block bytes are UTF-8 hex of that JSON. Same codec for Tendermint / app / faucet HTTP, CLI config, wallets, and on-disk slot maps. Coin amounts are decimal strings on this path.
bincode	CADO payload bytes (Account, staking accounts, EpochRecord, NamespaceRecord, CADO envelope). The node also uses bincode for GossipSub SyncMsg and persisted pinboard metadata.

A later canonical transaction encoding would be a breaking change.

Repository documentation

File	Purpose
CONTRIBUTING.md	PR workflow, layout, CI
CHANGELOG.md	Workspace release notes (git tags / GHCR)
SECURITY.md	Vulnerability reporting, wallet hygiene
CODE_OF_CONDUCT.md	Community standards
deploy/README.md	Local four-node Docker Compose and CI scripts
common/TYPE_DESIGN.md	Hex and typed ID conventions

Setup

Rust 1.88.0 (see rust-toolchain.toml). Install gitleaks, cargo-audit 0.22.2+, and cargo-deny (brew install gitleaks cargo-audit cargo-deny on macOS).

./deploy/scripts/ci.sh

That runs the same checks as GitHub Actions: cargo fmt --check, Clippy, build, test, cargo audit, cargo deny, and gitleaks. Rustc and Clippy warnings are treated as errors.

Configuration

Binaries read endpoint and runtime settings from config/config.json (client fields are used by eld-client; the node also reads P2P, capacity, and indexer fields from the same file). See client/config/config.json.example for client fields.

Wallet files (wallets/wallets.json) hold unencrypted Ed25519 private keys; do not commit them. Sample non-secret configs live under deploy/docker/local/; do not add p2p_keypair.json or wallets.json.

Protocol constants in eld_common::constants::protocol (minimum stake, validators per epoch, blocks per epoch, block reward) are local-dev values, not mainnet economics.

Usage

Path-depend from another crate in your workspace:

eld_common = { path = "../common", package = "eld-common" }
eld_client = { path = "../client", package = "eld-client" }

Or depend on this repository with git:

eld_common = { git = "https://github.com/eldnetwork/eld-chain", package = "eld-common" }
eld_client = { git = "https://github.com/eldnetwork/eld-chain", package = "eld-client" }

use eld_common::Address;

let address = Address::parse_hex_str("0x1234567890abcdef1234567890abcdef12345678")?;

License

MIT. Copyright Eld network.

common/src/coin.rs is adapted from IOHK rust-cardano (MIT) and Crypto.com (Apache-2.0). See NOTICE and the file header.