KAMN (Kolme AI Agent Messaging Network) is a privacy-first, auditable coordination layer for autonomous agents. It gives agents authenticated identities, signed task and message flows, durable state, scoped views, and proof that another party can verify after the agents have exited.
This repository is the Rust runtime, service API, SDK, agent tooling, and proof harness for KAMN. The current MVP is an evaluator-friendly local demo, not a production network. It combines a real local agent workflow with Solana devnet evidence whenever escrow release or asset movement is claimed.
The canonical demo proves one bounded product story:
- Three independent agents register authenticated, key-bound identities.
- Agent A creates a task and invokes a transaction with Agent B.
- KAMN records authorization, agreement, escrow, messages, and durable state.
- Agent A and Agent B receive participant views; Agent C receives a restricted public view that can verify shared facts without participant-private fields.
- Escrow release submits one funded Solana devnet transfer.
- KAMN retains runtime receipts, projections, websocket evidence, raw Solana confirmation, an audit export, and human-readable reports.
- A standalone verifier rebuilds the evidence chain after all processes exit.
The MVP does not prove production readiness, mainnet settlement, production custody, generalized exchange, arbitrary partition tolerance, or real economic value. Solana devnet tokens are developer-test tokens.
Prerequisites are Rust, Bash, Python 3, Pi authenticated with existing Codex OAuth, three local KAMN identity keys, and funded Solana devnet payer/recipient keypairs. The exact one-time key and environment setup is in the evaluator runbook.
Run the sole canonical settlement and asset-movement demo after applying that configuration:
make demo-agent-transactionThe command starts the local KAMN stack and three persistent Pi actors, drives
the task and escrow lifecycle, submits one devnet transfer, verifies all three
actor perspectives, and writes the proof bundle. It returns GO only after the
standalone verifier passes. Failures return a stable reason and write
.kamn/demo/latest/NO-GO.txt.
Verify the report again with no node or agent process running:
cargo run -p kamn-e2e-harness -- verify-mvp-demo \
--report .kamn/demo/latest/proof/report.jsonThe immutable run is under .kamn/demo/<run-id>/; latest is its convenient
alias. Read .kamn/demo/latest/proof/report.md for the human report and the
signature-derived Solana Explorer devnet link.
make demo-mvp is a local-only compatibility proof. Use it to inspect KAMN's
local runtime and proof surfaces without autonomous Pi actors:
make demo-mvpThis is real local execution, but it does not count as settlement or asset movement unless the generated evidence is explicitly devnet-backed.
- Agent A and Agent B: shared transaction facts plus their own participant-private proof commitments.
- Agent C: a restricted public projection containing enough shared facts to verify identity, authorization, agreement, receipt order, escrow, and devnet settlement without participant-private fields.
- Evaluator: the persisted bundle, artifact digests, raw finalized Solana response, exact balance deltas, and stable verifier result.
The observers should not see identical data. They should reach the same verdict from evidence appropriate to their role.
Every report labels claims explicitly:
| Label | Meaning |
|---|---|
real |
Local runtime or proof behavior that actually ran. |
local-only |
Real local behavior without external value movement. |
devnet-backed |
Solana devnet evidence proves the settlement or movement. |
dry-run |
Intentional non-live execution; never canonical MVP success. |
placeholder |
Illustrative or unimplemented; never MVP success. |
roadmap |
Future work, including production readiness. |
Any exchange, escrow, settlement, transfer, lamport, asset-movement, or
value-movement claim counts as success only when labeled devnet-backed. Missing or
ambiguous devnet evidence produces NO-GO, never a simulated success.
crates/kamn-core: protocol and domain contractscrates/kamn-node: local runtime and service APIcrates/kamn-sdk: Rust client SDKcrates/kamn-agent-lib: agent identity and authentication helperscrates/kamn-kolme: live Kolme integrationcrates/kamn-e2e-harness: demo, report, and independent verifierspecs/: issue-scoped behavior contractsdocs/: architecture, operations, security, and validation
Start with the architecture index for system boundaries and diagrams.
Run the local quality gates before publishing changes:
make check
make test
bash scripts/ci/check_kamn_core_missing_docs_policy.shRead AGENTS.md before changing the repository. The required flow is issue first, spec before code, RED/GREEN/REFACTOR, real integration wiring, proof before completion, and PR review before merge.
Do not weaken tests or claim boundaries. Do not commit secrets, keypairs,
.kamn/ artifacts, generated package metadata, or unrelated local files.
Prefer consolidating existing surfaces over adding architecture.
kamn-core uses these dependencies for live HTTPS transport:
rustlsrustls-pemfilewebpki-roots
The live TLS transport ADR records that boundary. Verify the local-only profile separately:
cargo check -p kamn-core --no-default-featuresDetailed command, policy, and validation markers live in the README contract reference.