atlas-common

Summary

atlas-common is the shared contract crate for the Rust workspace. It provides the cross-cutting types, errors, address model, signing helpers, proposal and vote data, ledger entry primitives, and abstraction traits that the rest of the system reuses.

Even though it lives under crates/domain/, it is not only a pure domain-model crate. Today it also carries transport-facing items such as the shared gRPC proto and async port traits used to decouple other crates from concrete implementations.

Why This Crate Exists

• give the workspace one place for canonical shared types
• avoid circular dependencies between runtime, infra, and domain crates
• centralize serialization and signing shapes for transactions, proposals, votes, and ledger entries
• provide trait boundaries such as LedgerPort and MempoolPort so higher-level logic can depend on capabilities instead of concrete implementations

Current Role In The Workspace

atlas-common currently owns five kinds of shared contracts:

1. transaction and registry schemas
2. address and authentication primitives
3. consensus and proposal data models
4. accounting and ledger entry primitives
5. shared error and port abstractions

That makes it one of the most reused crates in the workspace. It is effectively the dependency floor for most of the Rust system.

Public Surface

Top-Level Modules

• address
• auth
• crypto
• env
• ports
• schemas
• utils
• accounting
• entry
• error
• genesis

Important Types

• schemas::Transaction
• schemas::SignedTransaction
• schemas::types::TransactionType
• env::proposal::Proposal
• env::vote_data::VoteData
• env::consensus::types::{Vote, ConsensusPhase, ConsensusResult}
• entry::{LedgerEntry, Leg, LegKind}
• error::{AtlasError, StructuredError}
• genesis::GenesisState
• address::address::{Address, TypedAddress}

Important Traits

• auth::Authenticator
• ports::LedgerPort
• ports::MempoolPort
• env::Callback

Feature Flags

• default feature: grpc
• grpc enables optional tonic and tokio
• atlas-wallet explicitly disables default features when depending on this crate, which keeps the Wasm-facing wallet boundary lighter

Key Modules

• `lib.rs`: top-level export surface for the crate
• `schemas/mod.rs`: reexports transaction requests and shared transaction types
• `schemas/types.rs`: canonical transaction model, signed transaction shape, and transaction signing bytes
• `address/address.rs`: Bech32m address handling and typed address parsing
• `auth/mod.rs`: authentication trait boundary
• `auth/ed25519.rs`: default Ed25519 authenticator implementation
• `env/proposal.rs`: shared proposal model plus deterministic signing view
• `env/consensus/types.rs`: vote and phase enums used by consensus-facing code
• `entry.rs`: double-entry ledger primitives and final balance validation
• `accounting/mod.rs`: DoubleEntryBuilder, which constructs balanced legs before state application
• `ports/ledger.rs`: minimal ledger capability contract for consensus
• `ports/mempool.rs`: minimal mempool capability contract for runtime and validation flows
• `error.rs`: shared error type, structured error catalog parsing, and workspace Result<T>
• `genesis.rs`: genesis bootstrap data and environment validation for the genesis admin public key
• `proto/atlas.proto`: shared gRPC service definition for proposal submission and node status

Inputs And Outputs

Inputs

• transaction payloads and signed transaction envelopes
• public keys and signatures for address and auth flows
• proposal payloads and consensus vote data
• genesis bootstrap configuration
• ledger and mempool capability implementations supplied by other crates

Outputs

• serialized transaction and proposal signing bytes
• validated typed addresses
• balanced ledger legs and ledger entries
• typed workspace errors with catalog-style codes
• gRPC message and service contracts reused by application crates

Internal Dependencies

Workspace Dependencies

• no direct workspace crate dependencies

atlas-common sits at the bottom of the internal dependency graph.

External Dependencies That Shape The Design

• serde and serde_json for canonical serialization
• bincode for deterministic signing bytes
• ed25519-dalek for signatures and verifying keys
• bech32 for address encoding
• tonic behind the grpc feature for shared gRPC status and proto use
• async-trait for async port abstractions
• rs_merkle and sha2 for cryptographic helpers

Used By

These packages depend directly on atlas-common today:

• atlas-bank
• atlas-mempool
• atlas-keygen
• atlas-p2p
• atlas-airdrop
• atlas-consensus
• atlas-ledger
• atlas-node-admin
• atlas-node
• atlas-wallet
• demo-seed

That reach is the strongest signal that atlas-common is the shared contract layer of the Rust workspace.

Testing

The crate leans heavily on local module tests. Most modules include a focused test block that validates:

• top-level reexports
• transaction accessor behavior
• signing-byte determinism
• address generation and parsing
• trait-object compatibility for Authenticator, LedgerPort, and MempoolPort
• accounting balance enforcement through DoubleEntryBuilder and LedgerEntry::validate_balanced
• error code extraction and source chaining
• genesis admin key parsing

There do not appear to be standalone integration tests for atlas-common itself. The stronger end-to-end validation likely happens indirectly in dependent crates.

Risks Or Design Tension

Mixed Boundary

The crate is named and placed like a domain crate, but it also carries:

• transport contracts in proto/atlas.proto
• runtime-facing async port traits
• crypto helpers
• node and consensus environment types

That makes atlas-common practical, but also broad.

Two Address Layers

There is a typed address model in address/, but entry.rs still aliases Address = String for ledger entries. That keeps shared structs simple, but it also means not every part of the crate benefits from the stronger address type.

Canonicality Pressure

Because so many crates depend on it, changes here are expensive. A small schema change can ripple across runtime, infra, wallet, and tooling code quickly.

Open Questions

• should atlas-common stay broad, or eventually split into smaller crates such as atlas-types, atlas-crypto, and atlas-proto
• should ledger-facing primitives migrate from raw String aliases toward stronger typed wrappers
• should the gRPC proto remain here, or move closer to the application layer that serves it
• should there be first-class integration tests for serialization compatibility across dependent crates

Relevant Files

• `Cargo.toml`
• `lib.rs`
• `schemas/types.rs`
• `address/address.rs`
• `env/proposal.rs`
• `env/consensus/types.rs`
• `entry.rs`
• `accounting/mod.rs`
• `ports/ledger.rs`
• `ports/mempool.rs`
• `error.rs`
• `genesis.rs`
• `atlas.proto`