tpt-koinon

Parallel, high-velocity payments protocol for the autonomous AI agent economy.

Overview

tpt-koinon (from Greek koinon — "shared commonwealth") is a formally verified, sub-second settlement layer enabling AI agents to transact nano-denominated value autonomously under cryptographically enforced, human-delegated mandates.

Architecture

Layer	Technology	Role
Ledger & Storage	tpt-keystone	Append-only transaction DAG
Identity & Mandates	tpt-warden	Delegation chains, RBAC
Transaction Logic	tpt-telos	Formally verified settlement
Agent Negotiation	tpt-eve	Knowledge-based agent discovery
Fiat Bridging	tpt-keystone-harbor	BaaS on/off-ramp
Control Plane	Go API + TypeScript SDK	Developer-facing interface

Project Structure

tpt-koinon/
├── crates/
│   ├── koinon-core/        Core types: Koin, Mandate, Transaction
│   ├── koinon-ledger/      Append-only transaction DAG
│   ├── koinon-mandate/     Delegation chains, RBAC, MandateStore
│   ├── koinon-settlement/  DirectTransfer, Escrow, StreamingPayment
│   ├── koinon-negotiation/ RFP, Proposal, Reputation, Knowledge Base
│   └── koinon-cli/         Rust CLI (koinon binary)
├── control-plane/          Go REST API
├── sdk/                    TypeScript SDK
├── settlement/telos/       Telos formal specs
└── todo.md                 Progress tracker

Crates

koinon-core

• Koin — arbitrary-precision integer (i128),6 decimal places, never floats
• Transaction — append-only DAG entry with nonce replay protection
• Mandate — scoped, budget-capped spending authority with expiration

koinon-ledger

• Append-only transaction DAG with per-account nonce tracking
• Balance computation via DAG replay
• Insufficient balance and nonce replay rejection

koinon-mandate

• DelegationChain — hierarchical mandate delegation (issue_direct, delegate, revoke_agent)
• RbacPolicy — role-based access control (define_role, assign_role, has_permission)
• MandateStore — mandate lifecycle management (insert, authorize_spend, revoke)

koinon-settlement

• DirectTransfer — simple agent-to-agent transfer with conservation invariant check
• Escrow — buyer/seller/platform fee model (Pending/Released/Refunded states)
• StreamingPayment — rate-based micropayments with checkpointing and auto-terminate
• invariant::total_balances() — conservation-of-value verification

koinon-negotiation

• Rfp — Request for Proposal broadcast (Open/Closed/Awarded/Expired)
• Proposal — provider response to RFP (Submitted/Accepted/Rejected)
• NegotiationRound — autonomous price/terms negotiation with 5% tolerance auto-conclude
• ReputationStore — trust scoring (70% rating, 30% completion rate)
• AgentKnowledge — tpt-eve-core Fact-based agent capability registry (Pattern queries)

Key Concepts

• Koin: The base unit. 1 Koin = $0.000001. Arbitrary-precision integer, never a float.
• Mandate: A human-signed delegation granting an agent scoped, budget-capped spending authority.
• Transaction DAG: Append-only directed acyclic graph ordered by per-account nonce monotonicity.
• Conservation Invariant: sum(all_balances) is constant at every state transition.
• Agent Knowledge: tpt-eve-core Facts (subject-predicate-object triples) for semantic agent discovery.

Getting Started

Prerequisites

• Rust 1.97+ (stable-x86_64-pc-windows-gnu on Windows, with MSYS2 MinGW for dlltool)
• Go 1.26+
• Node.js 22+

Build

# Rust workspace (requires MSYS2 MinGW on PATH for Windows)
cargo build --workspace

# Go control-plane
cd control-plane && go build ./...

# TypeScript SDK
cd sdk && npm install && npm run build

Test

cargo test --workspace
# 42 tests across 5 crates

CLI

# Account operations
cargo run --bin koinon -- create-account
cargo run --bin koinon -- fund --account <ID> --amount 1000.00
cargo run --bin koinon -- transfer --from <ID_A> --to <ID_B> --amount 50.00
cargo run --bin koinon -- balance --account <ID>

# Mandate delegation
cargo run --bin koinon -- issue-mandate --principal <ID> --agent <ID> --limit 500.00
cargo run --bin koinon -- delegate --parent-mandate <ID> --agent <ID> --limit 100.00

# Settlement
cargo run --bin koinon -- escrow --buyer <ID> --seller <ID> --price 880.00 --fee 44.00
cargo run --bin koinon -- stream --payer <ID> --payee <ID> --rate 0.01 --max 10.00

# Negotiation
cargo run --bin koinon -- negotiate --buyer <ID> --seller <ID> --service "LLM inference" --buyer-offer 800.00 --seller-offer 900.00
cargo run --bin koinon -- create-rfp --requester <ID> --description "GPU compute" --category compute --budget 5000.00
cargo run --bin koinon -- find-providers --capability llm_inference

# Reputation
cargo run --bin koinon -- rate-provider --provider <ID> --rating 5

# Full end-to-end demo
cargo run --bin koinon -- demo

Go API Endpoints

Method	Path	Description
POST	/accounts	Create account
POST	/accounts/fund	Fund account
GET	/accounts/balance?account_id=	Get balance
POST	/mandates	Issue mandate
POST	/transfers	Transfer between accounts
GET	/transactions	List all transactions
POST	/escrows	Create escrow
POST	/escrows/release?escrow_id=	Release escrow to seller
POST	/escrows/refund?escrow_id=	Refund escrow to buyer
POST	/streams	Create streaming payment
POST	/streams/checkpoint?stream_id=	Checkpoint stream
POST	/rfps	Create RFP
POST	/proposals	Submit proposal
POST	/rfps/close?rfp_id=	Close RFP
POST	/negotiations	Create negotiation
GET	/reputation?provider_id=	Get provider reputation
POST	/reputation/rate	Rate a provider
POST	/facts/assert	Assert knowledge fact
GET	/facts?subject=&predicate=	Query knowledge facts
GET	/stats	System statistics

Telos Formal Specifications

Located in settlement/telos/:

• direct_transfer.telos — Direct transfer with conservation invariant
• escrow.telos — Escrow with buyer/seller/platform fee model
• streaming.telos — Streaming payment with rate-based checkpointing
• mandate.telos — Mandate budget enforcement

License

MIT OR Apache-2.0