paybondpaybond
Sign in

V2 protocol trust

How Paybond verifies external mandates, recognition proofs, and settlement receipts for delegated workflows.

V2 protocol trust

Paybond's protocol-trust layer adds delegated authorization and signed settlement receipts on top of the core Harbor lifecycle. It is designed for workflows where another runtime, agent, or partner system needs portable proof of authorization and outcome.

The core Harbor, Gateway, Signal, and Kit flows remain the primary operating contract. The protocol-trust layer adds an import-and-verification surface for external mandates, recognition proofs, and receipts.

What this layer adds

  • Verification of external mandates before they are bound to a Harbor intent.
  • Replay-safe recognition proofs for delegated or cross-runtime actions.
  • Signed authorization and settlement receipts that can be verified outside the live application.
  • Discovery documents for delegated workflows and task contracts.

Gateway protocol surface

Gateway exposes the following protocol surface:

RouteAuthContract
GET /.well-known/agent-card.jsonPublicPublishes the Paybond A2A discovery card.
GET /protocol/v2/a2a/agent-cardPublicGateway-local alias for the same discovery card.
GET /protocol/v2/a2a/task-contractsPublicPublishes Paybond task-contract catalog for Harbor-backed delegated flows.
GET /protocol/v2/a2a/task-contracts/{contract_id}PublicReturns one published task contract.
POST /protocol/v2/mandates/verifyPublicVerifies a signed AgentMandateV1 envelope and returns the normalized mandate plus digest.
POST /protocol/v2/recognition/verifyPublicVerifies an AgentRecognitionProofV1 against an expected purpose, verifier context, and request envelope; nonce replay is rejected on success.
POST /protocol/v2/mandatesTenant-boundImport a signed mandate, bind it to a Harbor intent, and return a signed authorization receipt.
GET /protocol/v2/receipts/{receipt_id}Tenant-boundReturn a signed settlement receipt for a previously imported mandate once the bound Harbor intent reaches a terminal protocol outcome.
POST /protocol/v2/receipts/verifyPublicVerifies either a ProtocolAuthorizationReceiptV1 or a ProtocolSettlementReceiptV1.

Operating model

  1. A partner or runtime presents a signed AgentMandateV1 plus a replay-safe AgentRecognitionProofV1.
  2. Gateway verifies the recognition proof for the exact request envelope and purpose, verifies the mandate, checks tenant scope, validates Harbor alignment for the referenced intent_id, binds the mandate digest to Harbor, and returns a signed ProtocolAuthorizationReceiptV1.
  3. Later Harbor mutations flow through Gateway recognition-gated /harbor/* routes with purpose-specific proofs.
  4. When the bound Harbor intent reaches a protocol-terminal state, Gateway emits ProtocolSettlementReceiptV1.

This keeps Harbor as the source of truth for money movement while making authorization and settlement artifacts portable. POST /protocol/v2/mandates imports and binds an external mandate; it does not issue a Paybond-native mandate.

Harbor-backed mutations

Protocol-driven flows recognition-gate these Harbor mutations:

  • POST /harbor/intents
  • POST /harbor/intents/{intent_id}/fund
  • POST /harbor/intents/{intent_id}/evidence
  • POST /harbor/intents/{intent_id}/settlement/confirm
  • POST /harbor/operator/v1/intents/{intent_id}/dispute/open
  • POST /harbor/operator/v1/intents/{intent_id}/dispute/resolve

Settlement receipts

Receipt verification accepts both ProtocolAuthorizationReceiptV1 and ProtocolSettlementReceiptV1. In the current contract, settlement receipt lookup keeps receipt_id == Harbor intent_id.

Settlement receipts are emitted only for these protocol-terminal Harbor outcomes:

  • released
  • refunded
  • resolved_split
  • escalated_external

Plain disputed is not terminal enough to export a settlement receipt.

Runtime surfaces

TypeScript and Python Kit expose mandate import, receipt reads, receipt verification, and A2A discovery. The packaged TypeScript and Python MCP servers call the same Gateway protocol routes and recognition-gated Harbor routes under the hood.

Signal scope

Signal remains private and tenant-scoped. Adjacent signed artifacts such as GET /reputation/{operator_did} and GET /signal/v1/portfolio/signed-export remain authenticated rather than becoming a public reputation plane.

Trust-anchor hardening

Gateway now enforces tenant-managed trust anchors for protocol recognition and mandate import:

  • recognition proof key_id must resolve in the authenticated tenant’s trusted agent key registry,
  • if the same key_id exists under another tenant, Gateway rejects it with an explicit tenant-mismatch protocol error instead of treating it as local success,
  • the proof-carried signing_public_key_ed25519_hex must match the registered Ed25519 key for that tenant entry,
  • revoked, unregistered, tenant-mismatched, mandate-mismatched, and bound-intent key-divergence cases all fail closed with explicit protocol errors,
  • imported mandate bindings persist the original signed mandate payload, the original recognition proof payload, and normalized mandate agent metadata for audit and dispute evidence,
  • tenant admins manage the registry through API-first control-plane routes and the admin console machine-access workspace:
    • GET /v1/admin/protocol/agent-keys
    • POST /v1/admin/protocol/agent-keys
    • POST /v1/admin/protocol/agent-keys/{key_id}/revoke

Out of scope

  • Paybond-issued mandates
  • shared-SaaS Signal topology rewrite
  • public reputation surfaces
  • consumer checkout and merchant shopping flows