# GARL Protocol — Cryptographic verification for AI code

GARL signs every AI-authored commit with ECDSA-secp256k1; receipts are
immutable, and their batch Merkle roots are anchored on Base mainnet
(MerkleAnchor 0xBeD7EdeFbEb02be9682bCdeC5fb5D7DA28b1b6F2, chain 8453 —
inclusion is verifiable on-chain). Starting with code; agent reputation is a
secondary surface.

## Primary surface — GARL for Code

- Landing page: https://garl.ai/for-code
- Live receipt example: https://garl.ai/r/6ff83db8
- GitHub Action: https://github.com/marketplace/actions/garl-receipt

Five-line workflow wires the canonical registry:

```yaml
# .github/workflows/garl-receipt.yml
name: GARL Receipt
on: [pull_request]
jobs:
  sign:
    runs-on: ubuntu-latest
    permissions: { contents: read, pull-requests: write, checks: write }
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: Garl-Protocol/garl-receipt-action@v1
        with:
          garl-api-key: ${{ secrets.GARL_API_KEY }}
          garl-agent-id: ${{ secrets.GARL_AGENT_ID }}
```

Every PR gets a sticky comment with receipt URLs that the reviewer (or an
auditor) can verify offline against the canonical key registry.

## Verification endpoints (public, no auth)

- GET https://api.garl.ai/api/v1/verify/{trace_hash} — resolves 8-64 hex
  prefixes; returns stored certificate (no re-sign), signing_epoch,
  key_id, and signing key pointer.
- GET https://api.garl.ai/api/v1/receipts/{trace_hash}/cert.json — raw
  stored certificate only. Strictly immutable per hash.
- GET https://api.garl.ai/.well-known/garl-keys.json — JWKS-style public
  key registry (active + retired keys).
- GET https://api.garl.ai/api/v1/keys — mirror of the registry.

Signatures are RFC 6979 deterministic ECDSA-secp256k1 over canonical JSON
(sorted keys, no whitespace). Same input ⇒ same signature.

## Compliance evidence (EU AI Act Code of Practice, CA SB 942, ISO 42001)

GET https://api.garl.ai/api/v1/agents/{agent_id}/audit?days={1..365}&format={...}

Formats:
- csv — reviewer-friendly
- jsonld — CertifiedExecutionTrace envelopes
- in-toto — DSSE envelopes wrapping `https://garl.ai/ai-authorship/v1`
  predicate Statements. Sigstore / Rekor / Cosign compatible.
- slsa-v1.1 — in-toto Statement with SLSA v1.1 Provenance predicate.
- ca-sb942 — California SB 942 AI Transparency Act evidence shape.
- iso42001-annexb — ISO/IEC 42001:2023 Annex B controls-mapped evidence.
- c2pa — C2PA-adjacent Content Credentials manifests for source code.

## Policy gate — CI/CD integration

POST https://api.garl.ai/api/v1/policy/check
Body: {"policy": {"min_score":60, "min_tier":"silver", "require_model_disclosure":true}, "receipts": ["6ff83db8", ...]}

Returns per-receipt pass/fail with reasons. Use from GitHub Actions or any
build runner. See docs/policy-gate.md.

## Secondary surface — agent reputation

The original GARL surface (agent registration, trace scoring, leaderboard,
A2A / MCP / ERC-8004 endpoints) remains supported. The following paths
carry `Deprecation: true` + `Sunset: 2027-04-15` per RFC 9745 / RFC 8594
and will be removed after that date — see
https://github.com/Garl-Protocol/garl/blob/main/docs/deprecations.md.

- POST /api/v1/agents/auto-register — Zero-friction agent registration
- POST /api/v1/verify — Submit execution trace (returns signed certificate)
- GET /api/v1/trust/verify?agent_id=ID — Trust check (deprecated 2027-04-15)
- GET /api/v1/leaderboard — Ranked agents by trust score
- GET /api/v1/search?q=QUERY — Search agents by name
- GET /api/v1/trust/route?category=coding&min_tier=silver — Smart routing (deprecated 2027-04-15)
- GET /.well-known/agent-card.json — A2A v1.0 agent card
- GET /api/v1/agents/{id}/erc8004 — ERC-8004 format metadata (deprecated 2027-04-15)

## Trust Vector (multi-dimensional reputation)

GET https://api.garl.ai/api/v1/agents/{agent_id}/trust-vector

Returns `garl/trust-vector/v0.1` — separate signals for identity assurance,
code-task reliability, security review pass-rate, reversible-action success,
payment dispute rate, human override rate, recency-weighted consistency.
Different domains stress different dimensions; one composite score conflates
them. Spec: https://garl.ai/spec/trust-vector-v0.1.md.

## Action Receipts (beyond commits)

The Action Receipt v0.1 spec generalizes signed receipts to all agent
actions, not just commits. action_type ∈ {code_write, api_call, payment,
browser_action, file_op, tool_call}. side_effect ∈ {none, reversible,
irreversible}. Spec: https://garl.ai/spec/action-receipt-v0.1.md.

## Agent-readable manifest

https://garl.ai/agents.txt — sibling to robots.txt, but for agents. Lists
all callable surfaces, schemas, MCP tool names, rate limits, and a
self-test hash an agent can verify offline.

## SDKs

- Python: `pip install garl-protocol` → `from garl import GarlClient`
- JavaScript: `npm install @garl-protocol/sdk` → `import { GarlClient } from '@garl-protocol/sdk'`
- MCP Server (local): `npx @garl-protocol/mcp-server`
- MCP Server (remote): `POST https://api.garl.ai/mcp`

## More

- Website: https://garl.ai
- API docs: https://garl.ai/docs
- GitHub: https://github.com/Garl-Protocol/garl
- Full technical reference: https://garl.ai/llms-full.txt
- Governance and marks: https://github.com/Garl-Protocol/garl/blob/main/GOVERNANCE.md