tony/MESH2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial workspace: scaffold + constitution + spec documents

Browse Source 
Rust workspace with 5 crates (mesh-types, mesh-crypto, mesh-network,
mesh-validator, mesh-wallet), PROJECT_CONSTITUTION.md for CHORUS
automated ingestion, and the full MESH protocol specification suite.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
anthonyrawlins
2026-03-23 20:49:44 +11:00
commit f2d62fa03d
21 changed files with 5272 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

622
docs/specs/MESH-MVP-Roadmap-Solo-Bootstrap.md Normal file
View File

@@ -0,0 +1,622 @@
**MESH PROTOCOL**
*MVP Roadmap*
From Specification to Working Tier 1 Testnet
Solo Bootstrap Edition
Budget: \$0 \| Team: 1 person \| Timeline: 6--9 months evenings/weekends
March 2026
**1. The Uncomfortable Truth About Solo Bootstrapping**
The specification suite describes a complete protocol with 10
specifications, three consensus tiers, a privacy layer, multi-hop
routing, and formal verification. Building all of that is a multi-year,
multi-million-dollar engineering effort. You are one person in Ballarat
working evenings and weekends.
The entire strategy for the next 6--9 months is therefore about one
thing: proving the core thesis works with the minimum possible code, so
that the project becomes credible enough to attract contributors and
funding. Everything else is deferred.
**The core thesis:** Byzantine Consistent Broadcast can settle everyday
retail payments in under 300ms, without a blockchain, without a native
token, and with confidential amounts. If you can demonstrate this ---
two wallets transacting through validators with Pedersen-committed
amounts and Bulletproofs+ range proofs --- you have something no one
else has built.
**1.1 What the MVP IS**
- **Tier 1 only.** No Tier 2 DAG-BFT, no Tier 3 aBFT. Those are
complex and not needed to prove the thesis.
- **Single asset type.** No multi-currency routing, no connectors, no
exchange. Transfers in a single test token.
- **Confidential amounts.** Pedersen commitments and Bulletproofs+
from day one. This is the privacy differentiator --- without it,
you're just another FastPay clone.
- **4 validators on a local testnet.** Running on your own machines or
cheap VPS instances. No public network.
- **A command-line wallet.** No mobile app, no GUI. A CLI tool that
can create accounts, send payments, and verify receipts.
- **Honest crash-only fault tolerance.** The MVP validators can crash
and recover. Full Byzantine fault tolerance is implemented in the
protocol logic, but adversarial testing comes later.
**1.2 What the MVP is NOT**
- Not a mobile app. Not a web wallet. Not a consumer product.
- Not multi-currency. Not connected to real money. Not connected to
anything external.
- Not formally verified. The TLA+ and Tamarin work comes after the MVP
proves the architecture.
- Not audited. No security firm review. This is a testnet with test
tokens.
- Not horizontally scaled. Single-shard validators. Scaling comes when
there's something worth scaling.
- Not post-quantum. Suite 0 (Ed25519) only. PQ cipher suites are
specified but not implemented.
**2. Technology Stack Decisions**
Every choice here optimises for solo-developer velocity and correctness,
not for theoretical perfection.
----------------- ------------------ ------------------------------------
**Component** **Choice** **Rationale**
Language Rust Memory safety without GC. The entire
crypto ecosystem (dalek, curve25519,
bulletproofs) is Rust-native. The
spec mandates constant-time crypto,
and Rust's type system helps enforce
this. You'll need to learn it if you
haven't, but it's the right
long-term bet.
Async runtime Tokio De facto standard for async Rust.
All networking, timers, and I/O
through Tokio. Single dependency for
the entire async layer.
Networking quinn (QUIC) Rust QUIC implementation built on
Tokio. The spec mandates QUIC
(SPEC-009). Quinn is mature,
well-maintained, and handles TLS 1.3
via rustls.
Crypto: ed25519-dalek Mature, audited, constant-time
signatures Ed25519. Used by Signal, Solana, and
dozens of other projects.
Crypto: curve25519-dalek Ristretto group operations for
commitments Pedersen commitments. Same library
family as ed25519-dalek.
Well-tested.
Crypto: range bulletproofs The dalek-cryptography Bulletproofs
proofs (dalek) implementation. Uses Merlin
transcripts for Fiat-Shamir.
MIT-licensed. This is the same
codebase Monero evaluated.
Crypto: hashing sha3 crate NIST SHA3-256 and SHAKE256. Pure
Rust, no C dependencies.
Crypto: symmetric chacha20poly1305 ChaCha20-Poly1305 AEAD. RustCrypto
crate project. For memo encryption.
Serialisation Custom binary (no The spec mandates deterministic
serde) byte-level encoding. Serde's binary
formats (bincode, etc.) do not
guarantee this across versions.
Write encode/decode by hand for all
protocol structures. It's tedious
but essential for interoperability.
Storage sled (embedded DB) Embedded key-value store. No
external database dependency. Stores
account states, certificates, and
equivocation records. Can be
replaced later with RocksDB if
performance demands it.
Build/CI cargo + GitHub Standard Rust toolchain. CI runs
Actions tests, clippy, and cargo-audit on
every push.
----------------- ------------------ ------------------------------------
> **DELIBERATE OMISSIONS:** No web framework. No REST API. No gRPC. No
> GraphQL. The MVP wallet talks directly to validators over QUIC. Adding
> an HTTP API is a week of work later if needed. Don't build it now.
**3. Milestone Plan**
Each milestone is a shippable unit: it compiles, it passes tests, and it
does something demonstrable. Milestones are sequential --- each depends
on the previous one. Estimated hours assume 10--15 hours/week of focused
coding time.
**Milestone 0: Project Skeleton (Week 1--2, \~20 hours)**
*Deliverable:* A Rust workspace with crate structure, CI pipeline, and
all dependencies pinned.
Set up the mono-repo workspace with these crates:
- mesh-types --- All data structures from SPEC-002. Transition,
AccountState, SettlementCertificate, etc. Pure data, no logic. 100%
test coverage of serialisation round-trips.
- mesh-crypto --- Thin wrapper around dalek crates. Key generation,
signing, verification, Pedersen commit, Bulletproofs+ prove/verify.
Domain-separated hashing per SPEC-006.
- mesh-validator --- Validator node binary. Empty for now.
- mesh-wallet --- CLI wallet binary. Empty for now.
- mesh-network --- QUIC transport layer. Empty for now.
This milestone is pure scaffolding. Write no protocol logic. Get the
types compiling, get serialisation working, get CI green. This is the
foundation everything else builds on. Do not skip it.
> **DEFINITION OF DONE:** cargo build succeeds. cargo test passes.
> GitHub Actions CI is green. All SPEC-002 data structures are defined
> with encode/decode functions. Round-trip property tests (encode then
> decode) pass for every type.
**Milestone 1: Cryptographic Core (Week 3--5, \~40 hours)**
*Deliverable:* A standalone library that can create Pedersen-committed
transactions with Bulletproofs+ range proofs, and verify them.
Implement in mesh-crypto:
1. **Key generation:** Generate Ed25519 key pair + derive view key per
SPEC-006 §6.4.1.
2. **Pedersen commitment:** Commit(value, blinding) = value·G +
blinding·H. Generate H from the nothing-up-my-sleeve construction
per SPEC-007 §7.2.
3. **Range proof:** Generate and verify Bulletproofs+ proofs for values
in \[0, 2⁶⁴). Use dalek Bulletproofs with Merlin transcripts. Bind
to transaction hash per SPEC-007 §7.3.2.
4. **Balance verification:** Given input commitments and output
commitments, verify that the sum of inputs equals the sum of outputs
(homomorphic check).
5. **Transaction construction:** Build a complete Transition struct per
SPEC-002 §2.4.1 with committed amounts and range proofs. Sign with
sender's key.
6. **Transaction validation:** Implement all 9 validation rules from
SPEC-002 §2.4.3. Every rule, in order, with the specified error
codes.
Write test vectors for each operation. These become the reference test
suite that any future implementation must pass.
> **DEFINITION OF DONE:** Can programmatically: create an account,
> construct a 500-unit confidential transfer with range proof, verify
> the transfer, confirm the balance check passes. Can also construct and
> detect an invalid transfer (negative value, insufficient balance,
> wrong signature) for each of the 9 validation rules.
>
> **THIS IS THE HARDEST MILESTONE:** Getting Bulletproofs+ integrated
> correctly with custom Pedersen generators and domain-separated
> transcripts is the single most technically demanding part of the MVP.
> Budget extra time. Read the dalek documentation twice. Write a
> throwaway prototype first if needed.
**Milestone 2: Network Layer (Week 6--8, \~35 hours)**
*Deliverable:* Two nodes can establish a QUIC connection, perform the
MESH handshake, and exchange protocol messages.
Implement in mesh-network:
7. QUIC server and client using quinn. TLS 1.3 with self-signed
certificates for testnet.
8. Message framing: \[length: u32\]\[type: u8\]\[payload\] per SPEC-009
§9.4.
9. HandshakeMessage exchange per SPEC-009 §9.3. Verify identity key
signature.
10. Stream multiplexing: separate QUIC streams for Tier 1 messages vs.
control messages.
11. PING/PONG keepalive per SPEC-009 §9.9.
12. Message dispatch: receive a framed message, deserialise, route to
handler by type.
For the MVP, skip peer discovery (SPEC-009 §9.6). Validators are
configured with a static list of peer addresses. This is fine for a
4-node testnet.
> **DEFINITION OF DONE:** Start two nodes. They connect over QUIC,
> exchange handshakes, verify identities. One sends a PING, the other
> responds with PONG. Message framing is correct (test with malformed
> frames to verify rejection). Logs show the full handshake sequence.
**Milestone 3: Validator Core (Week 9--13, \~50 hours)**
*Deliverable:* A validator node that can receive Tier 1 vote requests,
validate transitions, and return signed votes.
Implement in mesh-validator:
13. **Account state store:** sled database holding AccountState per
public key. CRUD operations.
14. **Validator key management:** Load signing key from file. For MVP,
generate during first run and save.
15. **VOTE_REQUEST handler:** Receive a Transition from a client. Run
all 9 validation rules. If valid, sign a vote (SPEC-003 §3.3.1 step
2). Return VOTE_RESPONSE. If invalid, return VOTE_REJECT with error
code.
16. **Equivocation detection:** Maintain a map of (sender, sequence) →
transition_hash. On any conflict, produce EquivocationProof and
reject.
17. **SETTLEMENT_CERTIFICATE handler:** Receive a certificate. Verify ≥
2f+1 valid votes. Apply state transition: debit sender, credit
recipients. Store certificate.
18. **Account query handler:** Respond to QUERY_ACCOUNT with current
account state (balance commitment, sequence number).
This is the heart of the system. Take your time. Write exhaustive tests.
Every edge case in the validation rules needs a test.
> **DEFINITION OF DONE:** Start a validator. Submit a valid transition
> via the network layer. Receive a signed vote. Submit an invalid
> transition (bad signature). Receive a rejection with the correct error
> code. Submit two conflicting transitions. Receive an equivocation
> proof.
**Milestone 4: CLI Wallet (Week 14--17, \~40 hours)**
*Deliverable:* A command-line wallet that can create accounts, send
confidential payments, and verify receipts.
Implement in mesh-wallet:
19. **Key management:** mesh-wallet keygen → generates key pair, saves
to file. mesh-wallet show-address → prints public key.
20. **Send payment:** mesh-wallet send \--to \<pubkey\> \--amount
\<value\> \--asset \<id\>. Constructs a Transition with
Pedersen-committed amount and Bulletproofs+ range proof. Broadcasts
to all configured validators. Collects 2f+1 votes. Assembles
certificate. Broadcasts certificate. Prints certificate hash.
21. **Check balance:** mesh-wallet balance. Queries a validator for
current account state. Locally decrypts the committed balance using
stored blinding factors.
22. **Receive:** mesh-wallet receive \--cert \<hash\>. Submits a receive
transition referencing the certificate as a causal dependency.
23. **Transaction history:** mesh-wallet history. Lists all sent and
received settlements with their certificate hashes.
The wallet stores blinding factors locally (in a sled database keyed by
transaction hash). Without the blinding factors, the committed balance
is meaningless. This is the wallet's most sensitive data.
> **DEFINITION OF DONE:** Alice creates an account. The genesis
> validator credits Alice's account with 10,000 test tokens (on-ramp via
> a hardcoded genesis transition). Alice sends 500 tokens to Bob. Bob
> receives them. Alice checks her balance: 9,500 (minus fee). Bob checks
> his balance: 500. Both balances are Pedersen-committed --- the
> validators never saw the plaintext amounts.
**Milestone 5: Multi-Validator Testnet (Week 18--21, \~35 hours)**
*Deliverable:* A 4-validator testnet where any validator can crash and
the system continues operating.
This milestone takes the single-validator demo and makes it a real
distributed system:
24. **Config file:** TOML configuration for validator: listen address,
peer addresses, validator set (public keys), epoch number.
25. **Multi-validator vote collection:** Wallet connects to all 4
validators, sends VOTE_REQUEST to all, collects 3 votes (2f+1 with
n=4, f=1), assembles certificate.
26. **Certificate propagation:** Wallet broadcasts certificate to all
validators. All validators apply the state transition. State is
consistent across all 4.
27. **Crash recovery:** Kill one validator. Verify the system still
works (wallet can collect 3/3 remaining votes). Restart the killed
validator. It catches up by requesting missed certificates from
peers.
28. **Docker Compose:** A docker-compose.yml that starts 4 validators
and an initial wallet. One command to launch the entire testnet.
> **DEFINITION OF DONE:** docker compose up starts 4 validators. Run the
> end-to-end send/receive flow. Kill one validator. Repeat the flow ---
> still works. Restart the killed validator. It syncs up. All 4
> validators have identical account state.
**Milestone 6: Benchmarks and Documentation (Week 22--24, \~25 hours)**
*Deliverable:* Performance numbers, a README that explains what this is,
and a grant application package.
29. **Latency benchmark:** Measure end-to-end time from wallet send to
certificate receipt. Run on 4 VPS instances (Sydney + Melbourne +
Perth + Brisbane or similar). Target: \<300ms. Document results.
30. **Throughput benchmark:** Flood a single validator with vote
requests. Measure transactions per second. This establishes a
baseline.
31. **Range proof benchmark:** Measure Bulletproofs+ prove and verify
time on a mid-range Android phone (or equivalent ARM device).
Target: prove \< 500ms, verify \< 10ms.
32. **README.md:** What MESH is, what the MVP does, how to run it,
what's next. Clear, honest, no hype.
33. **Grant application:** Prepare materials for NLnet Foundation,
Sovereign Tech Fund, and OTF FOSS Sustainability Fund. Include:
problem statement, demo video, benchmark results, specification
suite, budget request for next phase.
> **DEFINITION OF DONE:** Published GitHub repo with working code,
> passing CI, benchmark results in the README, a 3-minute demo video of
> Alice paying Bob through 4 validators, and at least one grant
> application submitted.
**4. Crate Dependency Map**
The dependency structure ensures that each crate can be developed and
tested independently:
mesh-wallet (binary)
└─ mesh-network (QUIC transport)
└─ mesh-crypto (signatures, commitments, proofs)
└─ mesh-types (data structures, serialisation)
mesh-validator (binary)
└─ mesh-network
└─ mesh-crypto
└─ mesh-types
└─ sled (embedded storage)
mesh-network
└─ quinn (QUIC)
└─ rustls (TLS 1.3)
└─ mesh-types
mesh-crypto
└─ ed25519-dalek
└─ curve25519-dalek (Ristretto)
└─ bulletproofs (dalek)
└─ merlin (Fiat-Shamir transcripts)
└─ sha3
└─ chacha20poly1305
└─ mesh-types
mesh-types (zero external dependencies)
**5. Risk Register**
Honest accounting of what could go wrong and what to do about it.
------------------- --------------------------- -----------------------
**Risk** **Impact** **Mitigation**
Bulletproofs+ Delays Milestone 1 by 2--4 Start with the dalek
integration is weeks. This is the most bulletproofs example
harder than technically demanding part. code. Build a minimal
expected standalone test
(commit, prove, verify)
before integrating with
the full transaction
structure. If you're
stuck after 2 weeks,
pivot to plaintext
amounts for the MVP and
add confidentiality in
the next phase.
Rust learning curve You know Python and JS. Spend week 0 (before
Rust's ownership model will Milestone 0) doing the
slow you down initially. first 12 chapters of
The Rust Programming
Language book. Write a
toy project. Don't try
to learn Rust while
building MESH.
QUIC/quinn Quinn is powerful but has a Wrap quinn in a thin
complexity steep API. Connection abstraction layer early
management and error (mesh-network). All
handling are non-trivial. MESH code talks to your
abstraction, not to
quinn directly. If
quinn becomes painful,
you can swap it for
s2n-quic or fall back
to TCP+TLS for the
testnet.
Motivation loss / Solo project, no external Set a public milestone.
burnout accountability, no revenue. Announce what you're
The most common cause of building on a relevant
open-source project death. forum (r/rust, a crypto
research mailing list,
or similar). External
accountability helps.
Ship Milestone 0 within
2 weeks of starting ---
early momentum matters.
Scope creep The spec has 10 documents. The milestones above
The temptation to "just add are the scope. If it's
Tier 2" or "just add not in a milestone, it
stealth addresses" is real. doesn't exist yet.
Write ideas down in a
FUTURE.md file and
close the mental loop.
Someone builds this The uncertified DAG + Publish the
first confidential transaction specification suite
space is active. Another now. Establishing prior
project could announce art and an open
something similar. standard is more
valuable than a head
start in code. If
someone else builds a
compatible
implementation, that's
a success, not a
threat.
------------------- --------------------------- -----------------------
**6. What Comes After the MVP**
Once the Tier 1 testnet is working and grant applications are out, the
project enters Phase 1 (funded development). This is the Phase 1 roadmap
at headline level --- detailed specs already exist.
**6.1 With Funding (\$50--100K AUD, 1--2 developers)**
- **Tier 2 DAG-BFT consensus** (SPEC-004). This unlocks multi-party
settlements and atomic swaps. 3--4 months of work.
- **Stealth addresses** (SPEC-007 §7.4). Recipient privacy. 2--3
weeks.
- **Multi-asset support** (SPEC-002 §2.7 Value Semiring). Multiple
asset types in the same testnet. 3--4 weeks.
- **Basic connector** (SPEC-008). Single-hop value routing between two
asset types. 4--6 weeks.
- **First security audit** (design review). \$200--300K AUD. This is
the single biggest expense and the single most important credibility
milestone.
**6.2 With Serious Funding (\$250K+ AUD, 3--5 developers)**
- **Tier 3 aBFT fallback** (SPEC-005). Complete consensus safety net.
- **TLA+ formal verification** of Tier 1 safety properties.
- **Hybrid post-quantum cipher suite** (Suite 1). Ed25519 + ML-DSA-65
hybrid signatures.
- **Mobile wallet SDK** (iOS/Android). This is what makes it real for
retail.
- **Public testnet** with community-operated validators.
- **Mainnet launch** with conservative parameters and permissioned
validator set.
**6.3 Grant Targets**
------------------- ---------------- -------------------------------------
**Fund** **Amount** **Fit**
NLnet Foundation €5K--€50K Strong fit. NLnet funds open internet
(NGI) infrastructure. MESH's
payment-as-protocol narrative aligns
with their mission. Apply under NGI
Zero Entrust or NGI Zero Core.
Sovereign Tech Fund €50K--€1M Good fit. STF funds open digital
infrastructure. The "replacement for
global payment rails" framing
resonates. Longer application
process.
OTF FOSS Fund \$150K--\$400K Decent fit. OTF funds tools that
USD advance internet freedom. The
privacy-by-default angle is strong.
Requires US fiscal sponsor.
Filecoin Foundation \$10K--\$100K Possible fit via their decentralised
(FFDW) USD web grants. Less obvious than the
above.
GitHub Sponsors Variable Good for ongoing small contributions
once the project has visibility.
------------------- ---------------- -------------------------------------
**7. Your Next 7 Days**
Concrete actions to take this week, in order:
34. **Publish the specification suite.** Create a public GitHub
repository. Upload the three spec documents (main suite + addendum +
this roadmap). Add an Apache 2.0 LICENSE file. Add a README that
says: "MESH is an open protocol specification for decentralised
payments. Reference implementation in progress." This establishes
the open standard and creates public accountability.
35. **Register the domain.** mesh-protocol.org or similar. Park it with
a one-page site linking to the GitHub repo. Cost: \~\$15 AUD/year.
36. **Set up the Rust workspace.** cargo new \--lib mesh-types, cargo
new \--lib mesh-crypto, cargo new \--bin mesh-validator, cargo new
\--bin mesh-wallet, cargo new \--lib mesh-network. Add a root
Cargo.toml workspace. Pin all dependency versions. Get CI green.
37. **Write the first 5 structs.** AccountState, Transition, Recipient,
SettlementCertificate, ValidatorVote. With encode/decode. With
round-trip tests. Push to main.
38. **Tell one person.** Not the internet. One person you trust and
respect. Show them the spec. Ask for honest feedback. External
perspective, this early, is invaluable.
*The spec is the easy part. The code is where it becomes real. Start
this week.*