README
¶
ShadowLedger ($SHARD)
Blockchain where no node stores the full chain. Each block's history is split with
Reed–Solomon erasure coding into shards, scattered deterministically across nodes via
rendezvous hashing. Any k of m shards rebuild a block. New nodes sync by holding their
assigned fragments + the live account state — not gigabytes of history.
No Proof-of-Work. Block production is authority/validator-driven (v0), with a consensus interface designed to grow into Proof-of-Storage.
Monetary policy ($SHARD): Bitcoin-style — 21,000,000 cap, 50-SHARD block subsidy halving every 210,000 blocks, paid to the block's validator (no miners, no burned energy). Fees are recycled, not minted.
Self-tuning: the operator does NOT configure shard counts. The network derives the erasure
shape (K data / M parity) and replication from the live node count (internal/netparams); the
producer stamps the chosen shape into each block header.
Decentralized, no central server: nodes find each other via DNS seeds (hostnames whose A/AAAA records list live node IPs, Bitcoin-style) and explicit bootstrap seeds, then transitive peer-exchange gossip. A fresh node fast-syncs a verified header chain + state snapshot, then participates. Built for the open internet — no LAN-only mode.
Proof-of-Storage: holders must answer random shard challenges (H(nonce ‖ shardBytes)); a
per-node scoreboard tracks pass/miss and gates block-production eligibility. See
docs/PROOF-OF-STORAGE.md.
Smart contracts: a small deterministic stack VM with gas + per-contract storage, contract-to-
contract calls, and event logs. Write them in the .shl language (if/while/expressions),
compile with slctl compile, estimate gas with slctl estimate, deploy/call/query. See
docs/SMART-CONTRACTS.md and docs/SHL.md.
Why
- Full Bitcoin node today: ~745 GB and growing. Barrier to running a node.
- ShadowLedger: a node holds
~ (k/m) * chain_size / Nplus the small active state. - Lose up to
m-kshard-holders per block and the block still reconstructs. - Tampered shards fail Merkle inclusion + RS decode → auto-rejected, content-agnostic.
Layout
cmd/slnode node daemon (control :4004, shard transfer :4005)
cmd/slctl wallet + cli (keygen, balance, send, inspect)
internal/
crypto Ed25519 keys, addresses, signatures
merkle Merkle tree + inclusion proofs
types Transaction, Block, Header
erasure Reed-Solomon encode/decode (klauspost) + shard hashing
rendezvous deterministic shard -> node assignment
bloom local "which shard do I hold" filter
economy $SHARD supply cap + halving emission schedule
netparams network-decided adaptive K/M + replication
state account ledger (balances + nonces + minted supply)
store on-disk blocks (headers) + shards
chain validation, append, reconstruction, fast-sync
consensus validator interface + v0 authority impl
mempool pending validated txs
p2p HTTP control + shard channels, discovery, sync
node wiring
docs/ SPEC-CORE-V1.md, ARCHITECTURE.md, GAPS-AND-DESIGN.md
Install
Prebuilt binaries: grab a .tar.gz / .zip for your OS+arch from the
latest release
(linux/macOS/windows, amd64+arm64; each bundles slnode, slctl, docs and example configs).
With Go:
go install github.com/ArubikU/shadowledger/cmd/slnode@latest
go install github.com/ArubikU/shadowledger/cmd/slctl@latest
Or from source: go build ./... (binaries slnode, slctl).
Quick start (zero config)
Mainnet is baked into the binary (genesis + bootstrap seeds), like bitcoind. Just run it:
slnode # joins mainnet: derives shared genesis, syncs from seeds, serves shards
# wallet + queries (slctl auto-targets your local node, else the mainnet seed)
slctl keygen --out wallet.tok --pass "your strong passphrase" # .tok = encrypted; .json = plaintext
slctl balance --addr <addr>
slctl send --wallet wallet.tok --pass "…" --to <addr> --amount 100
slctl supply # $SHARD minted + next reward
slctl peers # known peers
slctl storage # Proof-of-Storage scoreboard
No node.yaml to write. Override only what you need (identity, advertise, ports) for a
public/validator node — see docs/DEPLOY.md.
Running on the public internet
ShadowLedger is built for the cloud/open internet (no LAN-only mode). A node binds all interfaces
(:4004 control, :4005 shard). To be reachable by others:
- Set
advertise:to your public host/IP and forward both ports (or run on a VPS with a public IP). Same requirement as a Bitcoin full node. - Newcomers find the network by either listing a reachable node under
seeds:, or pointingdns_seeds:at a hostname whose A/AAAA records resolve to live node IPs (Bitcoin's DNS-seed model). Peer-exchange gossip spreads the rest.
Honest caveat: no automatic NAT hole-punching yet (libp2p-style) — you forward a port. See docs/GAPS-AND-DESIGN.md.
Docs
SPEC-CORE-V1.md · ARCHITECTURE.md · SMART-CONTRACTS.md · SHL.md · PROOF-OF-STORAGE.md · CONSENSUS.md · DEPLOY.md · SECURITY.md · GAPS-AND-DESIGN.md (PoW decision, discovery, onboarding, roadmap) · CHANGELOG.md
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
slctl
command
Command slctl is the ShadowLedger wallet and chain inspection CLI.
|
Command slctl is the ShadowLedger wallet and chain inspection CLI. |
|
slnode
command
Command slnode runs a ShadowLedger node daemon.
|
Command slnode runs a ShadowLedger node daemon. |
|
internal
|
|
|
bloom
Package bloom is a small Bloom filter for "do I hold this shard?" lookups.
|
Package bloom is a small Bloom filter for "do I hold this shard?" lookups. |
|
chain
Package chain wires together state, storage, erasure coding and shard placement into an append-only ledger.
|
Package chain wires together state, storage, erasure coding and shard placement into an append-only ledger. |
|
chainparams
Package chainparams holds the network parameters BAKED INTO the binary, the way Bitcoin and Ethereum ship their genesis + DNS seeds in source.
|
Package chainparams holds the network parameters BAKED INTO the binary, the way Bitcoin and Ethereum ship their genesis + DNS seeds in source. |
|
consensus
Package consensus defines how blocks are produced and headers authorized.
|
Package consensus defines how blocks are produced and headers authorized. |
|
crypto
Package crypto provides ShadowLedger identity: Ed25519 keys, addresses, signing.
|
Package crypto provides ShadowLedger identity: Ed25519 keys, addresses, signing. |
|
economy
Package economy defines $SHARD monetary policy: a fixed supply cap with a Bitcoin-style halving emission schedule.
|
Package economy defines $SHARD monetary policy: a fixed supply cap with a Bitcoin-style halving emission schedule. |
|
erasure
Package erasure wraps Reed-Solomon coding to fragment block bodies into shards and rebuild them from any K of K+M shards.
|
Package erasure wraps Reed-Solomon coding to fragment block bodies into shards and rebuild them from any K of K+M shards. |
|
forkchoice
Package forkchoice implements ShadowLedger's deterministic chain-selection rule: among competing branches, pick the heaviest (most cumulative weight), breaking ties by lowest block id.
|
Package forkchoice implements ShadowLedger's deterministic chain-selection rule: among competing branches, pick the heaviest (most cumulative weight), breaking ties by lowest block id. |
|
mempool
Package mempool holds pending, validated transactions awaiting inclusion.
|
Package mempool holds pending, validated transactions awaiting inclusion. |
|
merkle
Package merkle implements a binary Merkle tree with inclusion proofs.
|
Package merkle implements a binary Merkle tree with inclusion proofs. |
|
netparams
Package netparams makes ShadowLedger self-tuning: the erasure parameters (K data / M parity shards) and the shard replication factor are derived from the LIVE node count, not pinned in any config file.
|
Package netparams makes ShadowLedger self-tuning: the erasure parameters (K data / M parity shards) and the shard replication factor are derived from the LIVE node count, not pinned in any config file. |
|
node
Package node wires storage, state, consensus, chain, mempool and networking into a runnable ShadowLedger daemon.
|
Package node wires storage, state, consensus, chain, mempool and networking into a runnable ShadowLedger daemon. |
|
p2p
Package p2p provides ShadowLedger's networking: a control/RPC channel and a shard-transfer channel, decentralized peer discovery (DNS seeds + explicit seeds + peer exchange, NO central server), Proof-of-Storage shard challenges, and the client that reconstructs block bodies by pulling K-of-(K+M) shards from rendezvous-ranked holders.
|
Package p2p provides ShadowLedger's networking: a control/RPC channel and a shard-transfer channel, decentralized peer discovery (DNS seeds + explicit seeds + peer exchange, NO central server), Proof-of-Storage shard challenges, and the client that reconstructs block bodies by pulling K-of-(K+M) shards from rendezvous-ranked holders. |
|
pos
Package pos implements ShadowLedger's Proof-of-Storage challenge layer.
|
Package pos implements ShadowLedger's Proof-of-Storage challenge layer. |
|
regpow
Package regpow is ShadowLedger's registration Proof-of-Work: a one-time compute puzzle a node must solve to register as a validator (on TOP of its bond).
|
Package regpow is ShadowLedger's registration Proof-of-Work: a one-time compute puzzle a node must solve to register as a validator (on TOP of its bond). |
|
rendezvous
Package rendezvous implements Highest-Random-Weight (HRW) hashing to assign each block shard to a deterministic, stable set of holder nodes without any global coordination.
|
Package rendezvous implements Highest-Random-Weight (HRW) hashing to assign each block shard to a deterministic, stable set of holder nodes without any global coordination. |
|
shl
Package shl is a tiny high-level language that compiles to ShadowLedger VM bytecode.
|
Package shl is a tiny high-level language that compiles to ShadowLedger VM bytecode. |
|
state
Package state holds the active account ledger: balances and nonces.
|
Package state holds the active account ledger: balances and nonces. |
|
store
Package store persists block headers (with shard sets) and the erasure shards this node is responsible for, under a data directory.
|
Package store persists block headers (with shard sets) and the erasure shards this node is responsible for, under a data directory. |
|
types
Package types defines ShadowLedger's core data structures: transactions, blocks, headers and shard sets, with deterministic canonical encodings.
|
Package types defines ShadowLedger's core data structures: transactions, blocks, headers and shard sets, with deterministic canonical encodings. |
|
version
Package version reports the build version.
|
Package version reports the build version. |
|
vm
Package vm is ShadowLedger's minimal deterministic smart-contract VM.
|
Package vm is ShadowLedger's minimal deterministic smart-contract VM. |