ACP Quickstart

⚡ Zero-Setup: Run with Docker

No Go installation required. Pull the pre-built image from GHCR and start the ACP reference server in one command.

docker run -p 8080:8080 \
  -e ACP_INSTITUTION_PUBLIC_KEY=cA4s58S2dEJ-qye6EpJaJKKaVfvPT8mAQf97Vo8TInk \
  ghcr.io/chelof100/acp-server:latest

The key above is RFC 8037 Test Key A — for development only. The server starts on http://localhost:8080. Verify with: curl http://localhost:8080/acp/v1/health

Python: Admission Control Demo

Run the Python SDK offline demo — no server needed. Demonstrates the ACPAdmissionGuard pattern: issue a capability token, run an admission check, execute only if APPROVED.

git clone https://github.com/chelof100/acp-framework-en.git
cd acp-framework-en/impl/python
pip install -e .
python examples/admission_control_demo.py

Requires Python 3.10+. The demo runs 4 scenarios: approved payment, denied capability, data read, and audit ledger. No external dependencies beyond the SDK itself.

🏛️ Multi-Org Demo: Federated Validation (GAP-14)

Run two independent organizations (Org-A and Org-B) in Docker. Org-A issues cryptographically signed policy-context and reputation snapshots; Org-B validates both independently using the real ACP packages — no shared state, no trust assumptions.

git clone https://github.com/chelof100/acp-framework-en.git
cd acp-framework-en/examples/multi-org-demo
docker compose up

Org-A: http://localhost:8081 · Org-B: http://localhost:8082. Demonstrates Ed25519 real signatures, JCS canonicalization, temporal validity enforcement, and cross-org divergence reporting (REP-WARN-002). See README for full walkthrough.

Step 1: Clone & Build (Go)

Clone the repository and compile the reference implementation. Requires Go 1.21+.

git clone https://github.com/chelof100/acp-framework-en.git
cd acp-framework-en/impl/go

# Compile all packages
go build ./...

# Run the full compliance test suite (73 signed + 65 RISK-2.0 vectors, L1–L4)
go test ./...

All tests should pass. The suite covers identity, capability tokens, ledger integrity, policy snapshots, risk evaluation, and execution tokens (138 vectors (73 signed + 65 RISK-2.0), L1–L4).

Step 2: Verify an Event Chain (L3 — Ledger)

The ledger package enforces cryptographic hash chaining and Ed25519 signature verification. Here is a minimal example using the Go API directly.

package main

import (
    "crypto/ed25519"
    "crypto/rand"
    "fmt"
    "log"

    "github.com/chelof100/acp-framework/acp-go/pkg/ledger"
)

func main() {
    // Generate an institution key pair
    pubKey, privKey, _ := ed25519.GenerateKey(rand.Reader)

    // Create a new ledger for institution "bank-001"
    l := ledger.NewInMemoryLedger("bank-001", privKey)

    // Append a GENESIS event (mandatory first event)
    if err := l.Append(ledger.Event{
        EventType: ledger.EventGenesis,
        Payload:   map[string]interface{}{"institution_id": "bank-001"},
    }); err != nil {
        log.Fatal(err)
    }

    // Append an AUTHORIZATION event
    if err := l.Append(ledger.Event{
        EventType: ledger.EventAuthorization,
        Payload: map[string]interface{}{
            "agent_id":             "agent-payments-001",
            "capability":           "acp:cap:financial.payment",
            "policy_snapshot_ref":  "psn-2026-001",
        },
    }); err != nil {
        log.Fatal(err)
    }

    // Verify the entire chain against the institution's public key
    result := l.Verify(pubKey)
    if result.Valid {
        fmt.Println("Chain verified ✓ —", len(result.Events), "events")
    } else {
        for _, e := range result.Errors {
            fmt.Println("Error:", e.Code, "-", e.Message)
        }
    }
}

Step 3: Issue a Capability Token (L1 — CT)

Capability tokens grant agents scoped permissions, signed by the issuing institution, with a cryptographic delegation chain back to the institutional root.

import "github.com/chelof100/acp-framework/acp-go/pkg/ct"

token, err := ct.Issue(ct.IssueRequest{
    InstitutionID: "bank-001",
    AgentID:       "agent-payments-001",
    Capability:    "acp:cap:financial.payment",
    Scope:         []string{"transfer", "query"},
    MaxRisk:       0.25,
    TTLSeconds:    86400, // 24 hours
}, privKey)

if err != nil {
    log.Fatal(err)
}

// Verify the token signature
if err := ct.Verify(token, pubKey); err != nil {
    log.Fatal("Invalid token:", err)
}

fmt.Println("Token issued:", token.TokenID)

Step 4: Run Compliance Test Vectors

ACP ships 138 test vectors (73 signed covering L1–L4 protocols + 65 unsigned RISK-2.0 vectors for anomaly scoring) covering positive and negative cases for each conformance level. These can be used to validate any third-party ACP implementation.

# Test vectors are in compliance/test-vectors/
ls acp-framework-en/compliance/test-vectors/

# TS-LEDGER-POS-001.json  — Valid genesis chain
# TS-LEDGER-NEG-003.json  — Tampered hash (LEDGER-003)
# TS-EXEC-POS-001.json    — Valid execution token
# TS-EXEC-NEG-005.json    — Expired token (EXEC-005)
# ... 138 vectors total

# Each vector has the structure:
# {
#   "meta": { "id": "TS-LEDGER-POS-001", "level": "L3" },
#   "input": { "institution_public_key": "...", "events": [...] },
#   "expected": { "decision": "VALID", "error_code": null }
# }

Package Overview (23 packages, L1–L4)