Website | Whitepaper | PIP-001 | PIP-002
When AI does everything for you, who proves you still exist?
PunkGo is a local sovereignty compute kernel: giving individuals the inalienable right to write history on their own hardware.
PunkGo implements the Right to History — the principle that every actor (human or agent) can spend energy to perform actions, commit results to verifiable world state, and leave an indelible trace.
The kernel is a single-writer, append-only event system built on three primitives:
punkgo-kernel/
bins/
punkgo-cli/ # CLI client (IPC over Unix socket / Windows named pipe)
crates/
punkgo-core/ # Core types: Actor, Energy, Action, Boundary, Consent
punkgo-kernel/ # Kernel engine + daemon binary (cargo install punkgo-kernel)
src/
audit.rs # Merkle tree, inclusion/consistency proofs, C2SP checkpoints
state/ # Persistence: ActorStore, EnergyLedger, EventLog, EnvelopeStore, BlobStore
runtime/ # 7-step submit pipeline, lifecycle, energy producer
daemon/ # punkgo-kerneld binary (IPC server + energy producer)
testkit.rs # Test utilities: temp state dirs, request builders
Every action goes through a 7-step pipeline:
- Validate — check actor status, boundary permissions, action well-formedness
- Quote — compute energy cost for the action
- Reserve — lock energy from actor's balance
- Validate Payload — for
executeactions, validate the actor-submitted result (PIP-002 §2) - Settle — finalize energy accounting
- Append — write the committed event to the append-only log with cryptographic hash
- Receipt — return a verifiable receipt (event ID, log index, event hash)
Energy is produced continuously, anchored to the machine's hardware compute power (INT8 TOPS). Each tick, energy is distributed proportionally among active actors based on their shares. The kernel itself holds no energy (energy neutrality).
- Human — unconditional existence, cannot be deleted or downgraded
- Agent — conditional existence, created by humans with declared purpose and bounded permissions
- Only humans can create agents (PIP-001 §5/§6)
- Agents require authorization envelopes with budget, checkpoint levels, and expiry
- Agents can be supervised via hold rules (
hold_on) at envelope creation — matching actions are intercepted for Human judgment before execution (PIP-001 §11)
Every actor declares writable_targets (glob pattern + action types) at creation time. Access is default-deny. Privileged targets (system/*, ledger/*) are restricted to root. Child actor boundaries must be a subset of their parent's boundary.
The kernel is a committer, not an executor. For execute actions, the actor performs the execution externally and submits the result. The kernel validates the payload format and records the event.
The execute payload must contain:
| Field | Format | Description |
|---|---|---|
input_oid |
sha256:<64 hex> |
Reference to serialized input |
output_oid |
sha256:<64 hex> |
Reference to serialized output |
exit_code |
integer | Process exit code |
artifact_hash |
sha256:<64 hex> |
SHA-256 of raw output bytes |
output_bytes |
integer (optional) | Output size for IO cost calculation |
Energy cost: 25 + output_bytes / 256. The kernel does not verify whether OID references point to actual content — it records what the actor claims, consistent with mutate behavior.
Every committed event is added to a Merkle tree (Google tlog algorithm). The proof is logarithmic: 3 hashes verify 1 event in 8; 20 hashes verify 1 event in a million.
- Inclusion proof — prove a specific event exists in the tree (RFC 6962)
- Consistency proof — prove the tree is append-only between two sizes (RFC 6962)
- C2SP checkpoints — signed tree heads compatible with Go's
sum.golang.organd Sigstore Rekor
These proofs enable whitepaper invariants §3.5 (append-only provable) and §3.7 (independently verifiable). Any RFC 6962 verifier can audit PunkGo's log — no PunkGo software required.
Trust model: The current Merkle proofs guarantee append-only integrity — no silent deletion or modification. However, a root operator with database access could theoretically rebuild the tree from scratch. This is the "trust the operator" boundary: sufficient for local sovereignty (you trust your own hardware), but not for trustless third-party audit. Future work will introduce cryptographic mechanisms to make history unforgeable even by root.
cargo install punkgo-kernelThis installs the punkgo-kerneld daemon binary.
Requires Rust 2024 edition (1.85+).
cargo build --workspace
cargo test --workspacepunkgo-kerneld
# or from source:
cargo run --bin punkgo-kerneld# Check kernel health
cargo run --bin punkgo-cli -- read health
# Create a new actor
cargo run --bin punkgo-cli -- seed-actor alice --energy 5000
# Check actor energy
cargo run --bin punkgo-cli -- read actor_energy --actor-id root
# Submit an action (JSON payload)
cargo run --bin punkgo-cli -- submit '{"actor_id":"root","action_type":"mutate","target":"workspace/hello","payload":{"msg":"world"}}'
# View recent events
cargo run --bin punkgo-cli -- read events --limit 5
# Query the audit trail
cargo run --bin punkgo-cli -- audit checkpoint
cargo run --bin punkgo-cli -- audit proof 0specs/kernel-tools.json — MCP-compatible tool definitions for all kernel operations. Machine-readable, no running kernel required. Covers Quote, Submit (all action types), and Read (all query kinds) with full input/output JSON schemas.
- punkgo-jack — AI tool hook adapter: every tool call gets a cryptographic receipt
- punkgo-watchdog — real-time kernel monitor with terminal dashboard
PunkGo is governed by two documents:
- PunkGo Whitepaper (EN | ZH) — foundational axioms, world model, and 7 invariants
- PIP-001: Action (EN | ZH) — energy source, actor types, writability boundaries, and hold mechanism (§11)
- PIP-002: Execute Submission (EN | ZH) — actor executes, kernel records (supersedes PIP-001 §12)
All governance changes enter the event history (whitepaper §3, invariant 6).
New rules are introduced exclusively through PIPs (PunkGo Improvement Proposals) — they fill gaps in the whitepaper without overriding it.
- The kernel is a committer, not a judge — it provides a single linearization point for actions, not moral authority
- No a-priori restrictions — design is opt-in, not pre-emptive
- Append-only history — errors are corrected by appending compensating events, never by rewriting
- Hardware-anchored economics — energy production is tied to physical compute, not arbitrary tokens
- Right to History — every individual can write to the world state through their own hardware
See CONTRIBUTING.md for build instructions, code style, and how to propose PIPs.