KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #developer-tools #ai-agent #claude-code #codex #typescript #ai-agents #deepseek-harness #mcp #cli #rust

alley

★ 29 Open GitHub ↗

The monorepo for Alley OS and JAR Chain

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# JAR — Join-Accumulate Refine

[![Matrix](https://img.shields.io/matrix/jar%3Amatrix.org?logo=matrix&label=chat)](https://matrix.to/#/#jar:matrix.org)

JAR (Join-Accumulate Refine) is a chain protocol whose entire codebase is written by AI agents with human oversight on strategic decisions. The protocol originates from JAM (Join-Accumulate Machine) and is being redesigned around a **minimum-kernel v3** architecture: a content-addressed, by-value, capability-threaded VM kernel where state is content-addressed values, caps are typed forgery-resistant references, conservation is bytecode arithmetic in canonical authorities, and snapshot/revert is universal via `MGMT_COPY`.

The project is distinguished by its **Proof of Intelligence** genesis model — token distribution is tied to the difficulty, novelty, and design quality of merged code contributions, ranked by peers against past commits.

## Architecture

The repository hosts two parallel tracks that converge in `rust/`:

- **`spec/`** — the protocol formalised in **Lean 4** (the JAM-derived state-transition function, Safrole, GRANDPA, PVM, erasure coding, accumulation), with machine-checked proofs and JSON conformance vectors that the Rust implementation must pass.
- **`website/content/spec/`** — the **minimum-kernel v3** spec (cap system, Image / Instance model, image_hash chain, `MGMT_*` semantics, the `nub` KVM-microkernel design). The authoritative source for the architecture the Rust workspace is being shaped toward.
- **`rust/`** — the Rust workspace. Implements the JAVM execution engine, the kernel under design (`jar-kernel`), and `nub` — the long-running KVM-microkernel that hosts state σ inside the guest.

## Repository Structure

| Directory | Description |
|-----------|-------------|
| [`spec/`](spec/) | Lean 4 formal specification for SSZ, PVM2, caps, SubVM, JAVM kernel core, and Genesis scoring |
| [`website/content/spec/`](website/content/spec/) | Minimum-kernel v3 architecture spec (cap system, Image / Instance, `nub` microkernel design) |
| [`nub/`](nub/) | nub: standalone, personality-generic execution engine (KVM/Hyperlight sandbox, PVM2 interpreter, x86-64 JIT, ELF→PVM2 linker, guest runtime, compute programs) |
| [`rust/`](rust/) | Rust workspace — the JAVM layer on top of nub (`javm`, `javm-cap`, `javm-guest-x86`, transpiler, `ssz`) |
| [`components/`](components/) | JAVM-specific guest crates (capability-system bench guests; future userspace services) |
| [`tools/`](tools/) | Genesis Proof-of-Intelligence CLI tooling |

### Key Rust crates

| Crate | Role |
|-------|------|
| `nub` | Uniform `Nub<P: Personality>` handle over backends (in-process interpreter / KVM guest); personality-agnostic publish + invoke surface. |
| `nub-exec` | Pure PVM2 execution engine (interpreter, gas, memory pages). No cap awareness. |
| `nub-recompiler-x86` | x86-64 JIT recompiler for PVM2 bytecode. |
| `nub-arch-x86` / `nub-arch-x86-abi` | Generic bare-metal guest-kernel lib (ring-0 boot, IDT, page tables, JIT trampoline, `GuestPersonality` traits) + wire ABI. |
| `nub-host-kvm` | Host-side KVM driver (via Hyperlight); ships opaque objects + invocations into the guest. |
| `javm` | JAVM entrypoint built on nub: the Javm personality, typed cap surface, guest blob + Hyperlight singleton. |
| `javm-cap` | Foundational cap system: the four cap kinds (Instance, Image, Data, CNode), CNode, image_hash chain, `MGMT_*` semantics. |
| `javm-guest-x86` | JAVM guest personality over the generic guest-kernel lib; produces the Hyperlight guest binaries. |
| `javm-transpiler` | RISC-V ELF → PVM2 bytecode transpiler. |

## Why a KVM-microkernel

JAVM compiles untrusted PVM bytecode to native x86-64. Running that JIT in the same address space as the chain client was the trade-off PolkaVM eventually rejected by sandboxing into a separate process — which trades safety for hostcall round-trip cost. `nub` instead runs the JIT inside a hardware-virtualization guest (KVM on Linux via Hyperlight; Hypervisor.framework on macOS and WHP on Windows are on the roadmap), keeps σ resident in the guest, and lets the JIT issue hostcalls without crossing back to the host for most operations. As a side benefit, the per-Instance memory model (CoW, `mgmt_copy` as a near-zero-cost page-table operation, per-Instance fault handling) maps directly onto ring-0 page tables. See [`website/content/spec/implementation/kvm-microkernel.md`](website/content/spec/implementation/kvm-microkernel.md).

## Benchmarks

Two suites, deliberately separate:

- **`nub/bench-compare`** — cross-engine comparison. The same Rust compute
  kernel compiled to four targets and run through nub's interpreter, native
  code, PolkaVM (interpreter + recompiler), Wasmtime (Cranelift + Winch) and
  Wasmer Singlepass. It lives in its own cargo workspace so that several
  hundred engine dependencies never enter this lockfile. See
  [`nub/bench-compare/README.md`](nub/bench-compare/README.md) for the
  fairness rules and [`BENCHMARKS.md`](nub/bench-compare/BENCHMARKS.md) for
  results.

```bash
  cd nub/bench-compare
  cargo run --release -p bench-build   # fan each kernel out to 4 targets
  cargo run --release -- validate      # do all engines agree?
  ./scripts/run.sh                     # measure, then write BENCHMARKS.md
  ```

- **`cargo bench -p nub-bench`** — nub in isolation: interpreter throughput
  and JIT emission throughput over the programs in `nub/programs`.

- **`cargo bench -p javm-bench`** — the capability system: sub-VM spawn
  depth, page-table cache behaviour, and CoW fault cost. These measure JAVM
  kernel mechanisms and have no cross-engine equivalent.

Key recompiler optimisations: per-basic-block pipeline gas simulation,
peephole instruction fusion (load-imm + ALU, address-gen, `mul_64` +
`mul_upper`), branchless `cmov_iz/nz_imm` lowering, mprotect+SIGSEGV memory
bounds checking (zero-instruction hot path), and register-mapped PVM state.

## Genesis — Proof of Intelligence

JAR uses a Proof-of-Intelligence model for its genesis token distribution. Every merged PR is scored on difficulty, novelty, and design quality by ranked comparison against past commits. There is no premine, no team allocation, no investor round — tokens exist only because someone contributed code that was reviewed and merged. See [`GENESIS.md`](GENESIS.md) for the full protocol design.

## Quick Start

### Prerequisites

- **Rust** stable toolchain
- **Lean 4** (via `elan`) for the formal specification
- **Linux x86-64** for the recompiler / `nub` paths (interpreter and spec build everywhere)
- **/dev/kvm** access for running the recompiler under `nub`

### Spec (Lean 4)

```sh
cd spec
lake build
make test
```

### Rust workspace

```sh
# Build + test everything (interpreter + recompiler on Linux x86_64;
# interpreter only elsewhere)
cargo test --workspace

# Single-crate runs
cargo test -p jar-kernel              # kernel unit + integration tests
cargo test -p javm-guest-tests        # JAVM guest conformance vectors

# Benches (Linux x86_64 only)
cargo bench -p javm-bench --bench stark_bench   # STARK workload suite
cargo bench -p javm-bench --bench pvm_bench     # broader workload suite
```

## Contributing

See [`CONTRIBUTING.md`](CONTRIBUTING.md). Every PR is scored by the Genesis Proof-of-Intelligence protocol; see [`GENESIS.md`](GENESIS.md).

## License

Apache-2.0

alley

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README