VACT-P — Verifiable Agent Coordination and Transaction Protocol

Every agent action, provable. VACT is a decentralized, model-independent protocol for secure coordination, delegation, audit, and economic exchange among autonomous agents.

This repository is the reference implementation of VACT-P-RFC-0001 (Core 0.1). It implements the Phase 1 roadmap: signed envelopes, Agent Passports, Mandates, Delegations, the task state machine, receipts, revocation, and Python + TypeScript SDKs — plus a reference HTTP gateway and a runnable three-agent end-to-end demo (spec §32).

Why VACT-P & Why It Matters

As autonomous agents begin to act independently—hiring other agents, spending money, executing business processes, and reading sensitive files—they transition from tools to autonomous actors. In this environment, raw API keys or standard OAuth tokens are insufficient because they do not verify context or provenance of actions.

VACT-P introduces a standard, cryptographic, fail-closed trust model that solves these key challenges:

1. Accountability & Non-Repudiation:

   • Every action can be mathematically tied back to a human or organizational Principal who authorized it.
   • You can verify the exact chain of authorization (DIDs and signatures) from the principal down through each intermediary agent.

2. Fine-Grained Dynamic Authorization (Delegation):

   • Instead of sharing master API keys, agents delegate restricted authority using Delegations.
   • These constraints (actions, resources, budget limit, time bounds) are evaluated and narrowed at each hop. Any attempt to expand authority fails closed automatically.

3. Tamper-Evident Auditing:

   • The protocol produces a sequence of signed Receipts (Policy, Execution, Evaluation, Settlement) linked via a cryptographic hash-chain.
   • If an agent tampers with a single byte of execution data or violates a policy, the verification chain breaks.

4. Decentralized & Multi-Agent Standard:

   • Built entirely on open standards: DIDs (Decentralized Identifiers), JSON Canonicalization Scheme (RFC 8785), and Ed25519 signatures.
   • No central database or broker required. Works across different model providers, hosting infrastructure, and programming languages.

Mandate → Delegation → Offer/Quote → Task Contract → Policy Decision
        → Execution Receipt → Evaluation Receipt → Settlement Receipt

---

Integrating VACT-P with Your Infrastructure

VACT-P is designed to be overlayed on top of your existing software, identity, and payment systems without requiring a rewrite:

1. Identity Integration (DIDs)

• did:web: Bind agent identities to DNS domains you already control (e.g. did:web:agent.yourcompany.com). The public key is served under /.well-known/did.json.
• did:key / did:ion: Integrate with other decentralized identity standards.
• Service Mesh / SPIFFE: Map your internal Kubernetes SPIFFE IDs to DIDs to bridge internal cluster authentication with VACT-P's agent authorization framework.

2. Network & Routing (Gateways / Proxies)

• API Gateways: Deploy the reference HTTP gateway (or build custom middleware) behind API gateways like Kong, Traefik, or AWS API Gateway.
• Envelope Wrapping: Intercept incoming HTTPS requests, unpack the VACT-P envelope, verify the signature, and map the headers (e.g. X-VACT-P-Task-Id) to downstream trace headers.

3. Agent Frameworks (SDK Integration)

• LangChain / AutoGen / CrewAI: Integrate the Python or TypeScript SDK into the tools and action hooks of your agent frameworks. Before executing an external tool (e.g., database write), wrap the action in a signed VACT-P task request envelope.

4. Legacy Billing & Payments (Settlement)

• Stripe / Payment Rails: Map the Settlement Receipt schema to payment processors. When a task evaluates to PASS, trigger Stripe/ACH charges programmatically using the captured task budget.

---

Repository layout

vact-p/
├── spec/                  # VACT-P-RFC-0001, JSON Schemas, signed test vectors
├── sdk-python/            # vact-p-sdk (Python ≥3.10)
├── sdk-typescript/        # @vact-p-protocol/sdk (Node ≥18, zero runtime deps)
├── gateway/               # Reference HTTP gateway (spec §25) — stdlib only
├── examples/              # Three-agent reference flow (spec §32)
└── Makefile

Quickstart

Python SDK

cd sdk-python && pip install -e ".[dev]" && pytest

from vact_p_sdk import Keypair, sign_object, verify_object, make_envelope

controller = Keypair.generate(kid="did:web:example.com#key-1")

env = make_envelope(
    type="vact_p.task.request",
    mode="async",
    sender="did:web:client.example",
    recipients=["did:web:provider.example"],
    payload={"task": "summarize", "input": "urn:sha256:..."},
    ttl_seconds=300,
)
signed = sign_object(env, controller)          # JCS + Ed25519 (spec §9.2)
assert verify_object(signed, controller.public_key)

TypeScript SDK

cd sdk-typescript && npm install && npm test

import { generateKeypair, signObject, verifyObject, makeEnvelope } from "@vact-p-protocol/sdk";

const kp = generateKeypair("did:web:example.com#key-1");
const env = makeEnvelope({
  type: "vact_p.task.request", mode: "sync",
  sender: "did:web:client.example", recipients: ["did:web:provider.example"],
  payload: { hello: "world" }, ttlSeconds: 300,
});
const signed = signObject(env, kp);
verifyObject(signed, kp.publicKey); // true

Both SDKs produce byte-identical canonical forms — see spec/test-vectors/, which are generated by the Python SDK and verified by the TypeScript test suite.

Run the three-agent demo (spec §32)

make demo

Principal → Requester → Research Agent → Evaluator → Settlement, with a fully reconstructable audit chain printed at the end. Every step is a signed VACT-P object; tampering with any byte breaks the chain.

Run the LangChain sample agent ("Deep Agent")

make demo-langchain

Demonstrates how to wrap standard LangChain tools with cryptographic VACT-P validation. The agent reads data and publishes summaries if allowed by the delegation chain, and is blocked automatically with PERMISSION DENIED if it attempts unauthorized tool execution.

Run the reference gateway (spec §25)

make gateway     # serves http://localhost:8402
curl http://localhost:8402/.well-known/vact-agent.json

Endpoints: /.well-known/vact-agent.json, POST /vact-p/v0.1/messages, GET /vact-p/v0.1/tasks/{id}, POST /vact-p/v0.1/tasks/{id}/cancel, GET /vact-p/v0.1/receipts/{id}, GET /vact-p/v0.1/revocations/{id}.

What the SDKs enforce (spec §31.1 core conformance)

• Signing — RFC 8785 JCS canonicalization + Ed25519, top-level proof (§9.2)
• Envelope — required fields, expiry, nonce, replay defense (§9.5, §10)
• Authority — effective-authority intersection; delegation can never expand actions, resources, time, budget, or depth; fails closed (§11)
• State machine — the 17 task states with transition validation (§15)
• Receipts — execution / policy / evaluation / settlement / revocation builders (§21)
• Revocation — objects + priority semantics; indeterminate ⇒ deny for material actions (§24)

Status

0.1.0-draft — tracks VACT-P-RFC-0001 Public Design Draft. Not production audited. Contributions via VACT-P Enhancement Proposals (VEPs) — see CONTRIBUTING.md.

License

MIT License