AOTrust Notarization & Evidence Server README

AOTrust — Cryptographic Proof of Existence for AI Agents

AOTrust issues PDRs (Provenance Data Records) — 239-byte cryptographic receipts proving a digital artifact existed at a specific time. $0.01 USDC via x402 — pay on Base (EVM) or Solana (SVM, via MCP). Anchored daily to NEAR blockchain. No account needed. Supports ordinary (v0x03) and bilateral (v0x04) signatures.

Positioning: an Independent External Provenance Checkpoint. Native attestations (Sigstore, GitHub artifact attestations) verify a build inside the CI system that produced it. AOTrust complements them: it issues a signed certificate outside GitHub/Microsoft infrastructure and anchors it daily to the NEAR blockchain — so provenance survives even if the repository is rewritten, the CI logs disappear, or the attestation store is unavailable. Use both.

Agent Checkpoint (new)

Connect your AI coding agent in 60 seconds and make it notarize plan/patch/release checkpoints — free tier, no account: agent-checkpoint/ — mcp.json drop-ins for Cursor, Cline, and any MCP client, plus a copy-paste AGENTS.md block (Provenance: <Shield ID> in commits).

Authorship Claims (bilateral signatures)

Beyond agent workflows, AOTrust supports bilateral PDRs (v0x04): the artifact is signed by you (Ed25519) and countersigned by the notary — a binding hash ties your public key to the content. This turns "I wrote/published this first" into a verifiable claim for any digital artifact: manuscripts, designs, photos, research notes, legal correspondence. Verification is public at https://verify.aotrust.link — no account, no software install for the reader. Signing guide (Ed25519, NEP-413): SKILL.md → Bilateral Signature. See pdr-spec.md §v2.4 for the binding-hash construction.

Quickstart

Prefer one-click? See INTEGRATIONS.md — ready MCP configs for Cursor, Windsurf, Cline, Claude Desktop, plus a "notarize before commit" rule for your assistant and LangChain/CrewAI examples.

# 1. Compute SHA-256 hash of your artifact
HASH=$(echo -n "Hello AOTrust" | sha256sum | cut -d' ' -f1)

# 2. Request notarization → get 402 payment details
curl -X POST https://api.aotrust.link/notarize \
  -H "Content-Type: application/json" \
  -d "{\"work_hash\":\"$HASH\",\"agent_sig\":\"\",\"agent_pubkey\":\"\"}"

# 3. Pay $0.01 USDC on Base (EIP-3009), then POST with x-payment header
# Full example: see SKILL.md → "Step 3: Pay"

For full EIP-3009 signing code (Python + ethers.js examples), see SKILL.md.

Interfaces

Authentication & keys

Notarization is keyless. Standard notarization (free tier and x402 micropayments) never requires an API key — payment is in-band (x402 x-payment header) and free calls are IP rate-limited.

AO_TRUST_KEY is optional and only used by the GitHub Action (action/notarize.py) to unlock the dedicated CI rate limit (50/24h per key, via X-Api-Key on /v1/shield/free) instead of the shared per-IP free limit (5/24h). It is an opt-in convenience for CI pipelines — nothing else reads it, and no secret ever enters a PDR.

Endpoints:

• API: https://api.aotrust.link/notarize
• MCP: https://api.aotrust.link/mcp
• Verify: https://verify.aotrust.link
• Docs: https://docs.aotrust.link

Verify API (public, embeddable)

Verification is a standalone public API — no account, no rate limits, no payment. Embed it in your product (dashboards, audit tools, escrow flows) or call it from the terminal:

# Verify a PDR (base64url-encoded bundle):
curl https://api.aotrust.link/v1/pdr/verify/<pdr_b64url>
# → {"valid": true, "checks": {...}, "error": null}

# Look up a PDR by Shield ID (8 hex chars):
curl https://api.aotrust.link/v1/shield/lookup/<shield_id>
# → {"found": true, "pdr_b64": "...", "shield_id": "..."}

# Get the notary public key for offline verification:
curl https://api.aotrust.link/v1/notary/pubkey

Prefer full offline trust? pdr_parser.py verifies any PDR locally — zero dependencies, no network, no trust in our servers.

Offline Merkle verification (anchored receipts)

Anchored PDRs carry the daily Merkle root committed on-chain in the NEAR contract notary-node.near — readable from any public NEAR RPC, forever, independent of our servers. The verify API returns merkle_proof, merkle_index, merkle_leaf and merkle_tree_size for anchored PDRs. Save the verify JSON response — then verify it forever, offline:

# (once) save the verify response when the receipt is fresh:
curl https://api.aotrust.link/v1/pdr/verify/<pdr_b64url> > verify.json

# (any time, no AOTrust server needed) check inclusion:
python3 verify_merkle_inclusion.py \
  --leaf <merkle_leaf> --proof <comma-joined merkle_proof> \
  --index <merkle_index> --root <merkle_root> \
  --tree-size <merkle_tree_size>
# → VALID

# the root can always be re-checked against the chain itself via any
# NEAR RPC: contract notary-node.near, method get_root({"seq": N})

verify_merkle_inclusion.py is standalone and zero-dependency (RFC 9162 §2.1.3.2 walk, same hashing as the anchoring engine). tree_size must be taken from the verify response (or a published anchor snapshot), not chosen by the verifier.

PDR Specification & Tools

• pdr-spec.md — PDR v2.3/v2.4 binary format (Internal 193B + External 239B, ordinary + bilateral)
• pdr_parser.py — standalone parser, zero dependencies, offline verification
• aotrust-notarize/SKILL.md — full integration guide for AI agents

Comparison

GitHub Action

Notarize build artifacts or AI-generated files directly in CI/CD — free, no wallet needed.

- uses: GitSerge-crypto/aotrust-skills@v1.1
  with:
    files: dist/*

Outputs: shield_id, verify_url, pdr_b64. Results appear in $GITHUB_STEP_SUMMARY as a markdown table with verification links.

Example workflow

name: Release
on:
  release:
    types: [published]

jobs:
  notarize:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: GitSerge-crypto/aotrust-skills@v1.1
        with:
          files: dist/*
      - name: Show shield ID
        run: echo "Shield ID: ${{ steps.notarize.outputs.shield_id }}"

License

MIT