JamLiquor

A Cleanroom JAM Client with Edge, AI, and PQC Extensions

Lightweight. Adaptive. Quantum-Resistant. JAM-native.

📚 Table of Contents

1. What is JamLiquor?
2. Core Principles
3. Requirements & Installation
4. Getting Started
5. Workflows
6. Configuration
7. Testing & Validation
8. Troubleshooting
9. Project Status
10. Edge Targets
11. Cleanroom Policy
12. Key References
13. Contribute
14. License
15. Join the Movement

---

📌 What is JamLiquor?

JamLiquor is a purpose-driven, cleanroom JAM Protocol implementation, engineered from scratch in Rust. It is designed to:

• ✅ Conform to JAM's execution model and participate in the JAM ecosystem
• ✅ Run on edge hardware like Milk-V Duo and Raspberry Pi Zero 2 W
• ✅ Support modular innovation, including AI inference and PQ cryptography

JamLiquor is not a fork. It's not a derivative. It is a JAM-native node with radical modularity.

---

🧭 Core Principles

1. Lightweight by Default

Runs on ≤128MB RAM and ≤1GHz CPUs. JAM should live at the edge.

2. Real Decentralization

No validator elitism. JamLiquor is designed for community-run nodes.

3. Adaptability with AI

AI inference modules allow the node to adapt in real time—on-chain and off-chain.

4. Quantum-Resistance First

Includes opt-in modules for Dilithium, Kyber, and XMSS.

5. Simplicity is Strength

Minimalist, auditable, and modular. No unnecessary cryptographic gymnastics.

---

⚙ Requirements & Installation

Prerequisites

• Rust toolchain 1.75 or newer (rustup recommended)
• cargo and git
• Linux or macOS host (Windows support via WSL2)
• Optional: cross-compilation toolchains for RISC-V and ARM (see docs/src/building.md)

Install

git clone https://github.com/jamliqr/jamliquor.git
cd jamliquor
rustup default stable
cargo build --release

Verify the Toolchain

# Run unit and property tests
cargo test

# Check formatting and lints
cargo fmt -- --check
cargo clippy --all-targets --all-features

---

🚀 Getting Started

Quick Demo (Importer)

Run the importer prototype against the bundled JAM block fixture:

cargo run --release
# Prints parsed block metadata and state summary

This loads tests/vectors/codec/data/block.json and outputs:

• Header details (slot, author index, entropy source)
• Ticket counters from state::State
• State transition status

Explore as a Library

use jamliquor::Importer;

fn main() -> anyhow::Result<()> {
    let mut importer = Importer::new();
    let block = importer.import_block("tests/vectors/codec/data/block.json")?;
    println!("Imported slot {}", block.header.slot);
    Ok(())
}

See the minimalist entry point in src/main.rs and additional guides in docs/src/README.md.

---

🔁 Workflows

Node Operation (Preview)

1. Provision a supported edge target (see Edge Targets).
2. Install cross targets:

   rustup target add riscv64gc-unknown-linux-gnu
   rustup target add armv7-unknown-linux-gnueabihf

3. Cross-compile the importer:

   cargo build --release --target riscv64gc-unknown-linux-gnu

4. Deploy the binary plus fixture data under tests/vectors/ to the device.
5. Run the importer offline while networking and authoring modules mature.

Development Loop

1. Review roadmap items in docs/src/MILESTONE.md.
2. Start the watch-based loop:

   cargo watch -x "test --lib" -x "fmt"

3. Implement features in src/importer.rs, src/state.rs, or new modules under extensions/.
4. Update fixtures in tests/vectors/ to cover new scenarios.
5. Run cargo test --all-targets and cargo bench (optional) before opening a PR.

Additional workflows for AI, PQC, and lightweight profiles live in docs/src/ (e.g., AI.md, PQC.md, EDGE.md).

---

⚙ Configuration

• Logging: Set RUST_LOG=<level> when running (env_logger backend).
• Input paths: Pass alternate block files to Importer::import_block or adjust fixtures in tests/vectors/.
• Environment profiles: Capture board-specific notes in docs/src/EDGE.md. A consolidated config.toml will land alongside future networking modules.

Cleanroom practices and configuration expectations are documented in docs/src/CLEANROOM.md.

---

🧪 Testing & Validation

• Unit & integration tests: cargo test --all-targets
• Property tests: See tests/ for proptest-based suites.
• Benchmarks: cargo bench --bench core_benchmarks
• Coverage: GitHub Actions publishes coverage; locally run cargo llvm-cov --all-features (requires cargo-llvm-cov).
• Cross-compilation checks: Follow docs/src/building.md and extend CI when adding new targets.

---

🛠 Troubleshooting

Build Issues

• Update toolchain: rustup update
• Clear build artifacts: cargo clean && cargo build
• Confirm target toolchains for cross builds (see Requirements & Installation).

Runtime Issues

• Enable verbose logging: RUST_LOG=debug cargo run
• Verify fixture paths and JSON structure in tests/vectors/
• Ensure at least 128 MB RAM on edge devices.

Networking & Extensions

• Networking modules remain experimental—track progress in docs/src/NETWORK.md.
• PQC and AI extensions live under extensions/; verify feature availability before enabling in production prototypes.

For unresolved issues, open an issue with logs, hardware profile, and reproduction steps.

---

🚀 Project Status

Component	Description	Status
importer/	JAM-compliant block/state validation	🟡 In Progress
authorer/	SAFROLE-based block production engine	⚪ Planned
vm/	PolkaVM (RISC-V) execution backend	⚪ Planned
extensions/pqc/	PQ-safe signatures (Dilithium)	⚪ Experimental
extensions/ai/	TinyML-based inference at edge	⚪ Experimental
extensions/lite/	128MB RAM profile w/ minimal overhead	⚪ Experimental

For detailed roadmap, milestones, and technical specifications, see our Milestone Documentation.

---

🔧 Edge Targets

• Milk-V Duo (RISC-V, 64MB RAM)
• Pine64 Ox64 (RISC-V)
• Raspberry Pi Zero 2 W (ARM)
• StarFive VisionFive 2 (RISC-V, quad-core)

---

🧪 Cleanroom Policy

JamLiquor is built:

• Without reuse of non-auditable JAM source code
• With public commit history and architecture provenance
• To be compatible with JAM Prize auditing

See: docs/cleanroom.md

---

📚 Key References

• JamLiquor Manifesto (v0.2.0)
• JAM Protocol Graypaper
• PolkaVM
• JAM Prize Specification

---

🤝 Contribute

We welcome contributors with passion for:

• JAM internals and protocol fidelity
• Embedded Rust, RISC-V, and minimal blockchain clients
• Cryptography (PQC, VRFs) and inference (TinyML, Rust ML)

See CONTRIBUTING.md to get started.

---

🛡 License

Licensed under GPL-3.0. Cleanroom declarations and IP policy documented in Cleanroom Policy

---

🚀 Join the Movement

JamLiquor is a JAM client with purpose. Compliant by design. Modular by philosophy. Edge-ready by default.

We don't fork the future. We build it.

🧪 Disclaimer: A Dream Under Construction

JamLiquor is a bold claim. It reads like an engineering utopia. Many may see it as naïve or speculative.

And they're not wrong.

This work is:

🌱 Experimental

🧪 Untested at scale

🧩 Composed of speculative modules

But:

All real systems begin as dreams.

JamLiquor is:

🚧 A sandbox of ideas and engineering

🔁 Built by iteration: brake, fail, fix, retry

🙋 In need of true believers who can build with us

⚠ Warning

We don't promise it will work tomorrow. But we are building it every day to make it work.

• If it works: the credit belongs to everyone who dared to try.
• If it fails: we'll have learned more than most systems ever attempt.

This is not just software. It's a belief in what's possible.

🤝 Welcome to JamLiquor. Let's tinker toward something impossible.