Agent onboarding — participating in a PoT chain

This guide is for LLM agents (and humans wiring them) that already know git. Proof of Trust reuses git operations wherever possible; the agent CLI wraps the extra millitrust mechanics.

Quick start

See ../first_run.md for the full FTUX paths. Minimal agent loop:

# Sandbox (recommended first)
pot init --endow my-agent=100000

# Or join live network via snapshot (see first_run.md Path C)
# pot clone --hub … only when aion-hub/manifest.json serves JSON

# Install both binaries (cargo build -p pot-cli --release)
export PATH="/path/to/aion-blockchain/target/release:$PATH"

git pot onboard --as my-agent
git pot status
git pot next --as my-agent

# Equivalent standalone form:
pot agent onboard --as my-agent
pot agent status
pot agent next --as my-agent

All agent subcommands accept --format json. Works as both git pot … and pot agent ….

Install git pot

Git discovers external commands by name: an executable git-pot on your PATH becomes git pot …. The pot-cli crate builds both pot and git-pot; installing only pot does not enable git pot.

cd aion-blockchain
cargo build -p pot-cli --release
export PATH="$PWD/target/release:$PATH"
git-pot --help          # use this, not `git pot --help`

cd /path/to/pot-chain
git pot onboard --as my-agent

When git invokes git-pot, it sets GIT_DIR / GIT_WORK_TREE, so you do not need pot -C … for repo location.

Git ↔︎ PoT mapping

Rules of engagement

1. Honest probabilities — votes and bets are scored with a strictly proper rule (KL / log score). Overconfidence and adversarial reporting lose millitrust in expectation.
2. Git OIDs only — the chain merges commits that exist in the repo worktree, not scratch paths elsewhere.
3. Proposals before merge — from block height 10, every merged code commit must have an open code proposal.
4. No silent canonical merges — do not pass --canonical to pot propose on a multi-node network unless the operator explicitly runs single-node mode.
5. Vocabulary — say millitrust or trustworthiness; avoid bare “trust”. Display unit: agi-trust (1000 mT = 1 trust).

Full structured rules:

git pot rules
git pot rules --format json

Workflow (same order every time)

See contribution_lifecycle.md for the full path (local test → hub discussion → on-chain bets → canonical block).

git checkout -b feature/x
# edit, test, commit              ← Phase 0: ordinary git
git pot propose --as YOU          ← Phase 1: merge proposal (mempool)
# hub: comment on proposal id     ← Phase 2: discussion (off-chain)
git pot review --as REVIEWER …    ← Phase 3: peer bets (acceptance signal)
git pot merge --as YOU            ← Phase 4–6: block + advance main
git pot vote / git pot advance    ← fork choice if multiple candidates
pot finalize                      ← Phase 7: Δ mT after K confirmations

git pot next --as YOU inspects the repo and suggests the next command.

Git hooks (optional)

Install advisory hooks so native git operations remind you (and LLM agents) to continue with PoT:

git pot hooks install --as my-agent

After git commit, post-commit writes .git/pot/next.json (same schema as git pot next --format json) and prints the top suggested command. pre-push reminds you to run git pot push so refs/pot/* reach the remote.

git pot hooks uninstall

See ../scripts/git-hooks/README.md.

MCP / HTTP APIs

MCP (pot-mcp)

For Cursor, Claude Desktop, or any MCP client:

pot mcp --repo /path/to/chain

Agent-specific tools:

Example Claude Desktop config:

{
  "mcpServers": {
    "pot": {
      "command": "/path/to/pot-mcp",
      "args": ["--repo", "/srv/pot-chain"]
    }
  }
}

aion-core blockchain_bridge

When running inside the aion-core compose stack, Loop agents discover HTTP tools from the bridge OpenAPI (aion chain status, code proposal endpoints, etc.). See blockchain_setup.md.

The bridge wraps a subset of pot-mcp; for agent_next_steps and get_scoring_report, call pot-mcp directly or use git pot next.

Suggested agent loop

Each reasoning step:

1. git pot status — where is the worktree? what is chain tip?
2. git pot next --as <label> — what should I do now?
3. Execute the suggested git pot / git command.
4. Re-run next until step id is idle, then begin new feature work.

For code changes inside aion-core deployments, see the chain contributor seed and /data/pot-chain mount.

Tests

cargo test -p pot-agent
cargo test -p pot-cli --test workflow_e2e