> For the complete documentation index, see [llms.txt](https://docs.bardiel.tech/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bardiel.tech/technical-architecture/core-primitives/delegate-and-validate-v4-spec-receipts-and-external-proofs.md).

# /delegate & /validate v4 Spec - Receipts & External Proofs

Scope: This page describes **Bardiel’s v4 layer** on top of Cortensor’s `/delegate` and `/validate` (and future `factcheck`) endpoints.\
The router’s public endpoints stay at **v3**; Bardiel v4 adds **receipts** and **externally checkable decision objects** on top.

Bardiel v3 already consumes Cortensor v3 endpoints with explicit redundancy and consensus.\
Bardiel v4 answers the next question:

> How can Base apps, ACP markets, ERC-8004-compatible systems, and other agent ecosystems prove later what happened, without re-running everything?

The answer is **receipts**: compact, signed summaries of Bardiel’s decisions that point back to the underlying Cortensor runs.

***

### 1. Goal

v4 adds a **receipt layer** on top of v3 consensus:

* Every `/delegate` or `/validate` call *can* produce a receipt.
* The receipt:
  * captures what was asked, what Bardiel decided, and how consensus was formed,
  * references Cortensor sessions and tasks used for the decision,
  * can be stored, shared, or verified later.

Think of v4 as:

> Agent-ready receipts: stable, externally referenceable summaries of Bardiel’s verdicts, backed by v3 consensus metadata and Cortensor traces.

The core router behavior (v3 redundancy plus consensus) does not change; v4 is a **Bardiel-side contract** layered on top.

***

### 2. v3 vs v4 - Mental Model (Bardiel Perspective)

#### v3 (today - consensus, but inline)

With v3:

* Bardiel calls router `/api/v3/delegate` or `/api/v3/validate` with:
  * v2-style payloads (`objective` / `input` / `execution` / `policy` or `claim` / `policy` / `context`),
  * a `consensus` block (replicas 1/3/5, session pool, aggregation, disagreement policy).
* The router returns:
  * a final answer or verdict,
  * a `consensus` block (replicas, agreement, verdicts, confidence).

Bardiel v3 turns that into:

* `status` (`VALID`, `INVALID`, `RETRY`, `NEEDS_SPEC`, etc.),
* `confidence`,
* `evidence` (summarized trust signals),

but the full story is **inline and ephemeral**: it lives in logs and traces, not in a portable, stable object.

#### v4 (this spec - receipts on top of consensus)

With v4:

* Bardiel still calls router v3 under the hood.
* For any delegation, validation, or arbitration call, the caller can ask Bardiel to **issue a receipt**.
* Bardiel:
  * runs the v3 flow,
  * derives a verdict,
  * builds a **Receipt Object**:
    * stable fields,
    * hashes of inputs and outputs,
    * policy and consensus snapshots,
    * references to Cortensor sessions and tasks,
    * a Bardiel-side identifier and optional signature.

Base-native apps, Virtual agents, ACP markets, ERC-8004-compatible systems, and other agent ecosystems can:

* store `receipt_id`,
* later fetch or verify the receipt,
* use the receipt as the **record of decision** without re-running the workload.

v3 answers “what did we decide and how strong was consensus right now?”\
v4 adds: “give me something I can point to later as evidence of that decision.”

***

### 3. Request Shape - Asking Bardiel for a Receipt

v4 extends Bardiel’s **Agent Surfaces** envelope (`mode`, `task`, `policy`, `context`, `metadata`) with a `receipt` block.

#### 3.1 Bardiel v4 Request (Conceptual)

Example shape for any Bardiel call (delegation, validation, arbitration):

```
{
  "mode": "validation",
  "task": { "...task payload..." },
  "policy": "safe",
  "context": { "...caller context..." },
  "metadata": { "...job or market metadata..." },
  "receipt": {
    "mode": "inline",
    "include": {
      "consensus_snapshot": true,
      "policy_snapshot": true,
      "input_hash": true,
      "output_hash": true,
      "router_trace_refs": true
    },
    "ttl": "30d",
    "visibility": "private"
  }
}
```

**Fields**

* `receipt.mode`
  * `"none"` - do not create a receipt (default for low-stakes flows)
  * `"inline"` - create a receipt and return it embedded in the response
  * `"detached"` - create a receipt, return only `receipt_id` and minimal metadata
* `receipt.include`
  * toggles for what the receipt should contain:
    * `consensus_snapshot` - snapshot of router v3 consensus
    * `policy_snapshot` - snapshot of Bardiel policy tier and key knobs
    * `input_hash` / `output_hash` - hashes of inputs and outputs rather than full content
    * `router_trace_refs` - session IDs, task IDs, and router trace IDs
* `receipt.ttl`
  * requested retention window, for example `"7d"`, `"30d"`, `"90d"`
  * actual retention is subject to Bardiel / Virtual policy by environment
* `receipt.visibility`
  * `"private"` - visible only to the calling integration
  * `"shared"` - intended to be shared with specific counterparties (for example buyer and seller in a market)
  * `"public"` - possible future mode for transparency dashboards or proof registries

Bardiel treats `receipt` as a **hint** and may clamp TTL or visibility based on environment (testnet vs mainnet) and governance rules.

***

### 4. Response Shape - Bardiel Receipt Object

When `receipt.mode` is not `"none"`, Bardiel response values include a **Receipt Object**.

#### 4.1 Bardiel v4 Response (Conceptual)

```
{
  "status": "VALID",
  "result": { "...chosen output..." },
  "confidence": 0.91,
  "evidence": { "...summary..." },
  "retry_instructions": null,
  "trace_id": "bardiel-trace-123",
  "bardiel_version": "v0.4.0",
  "receipt": {
    "receipt_id": "bar-rec-000123",
    "mode": "validation",
    "task_meta": {
      "type": "json_tool_call",
      "input_hash": "0xabc123",
      "output_hash": "0xdef456"
    },
    "decision": {
      "status": "VALID",
      "confidence": 0.91,
      "reasons": ["schema_ok", "matches_spec"],
      "timestamp": "2026-07-15T12:34:56Z"
    },
    "policy_snapshot": {
      "tier": "safe",
      "consensus": {
        "replicas": 3,
        "strategy": "majority"
      }
    },
    "consensus_snapshot": {
      "replicas": 3,
      "agreement": 0.67,
      "verdicts": ["VALID", "VALID", "INVALID"],
      "strategy": "majority",
      "confidence": 0.82
    },
    "cortensor_refs": {
      "sessions": ["201", "202", "203"],
      "tasks": ["sess201-task77", "sess202-task91", "sess203-task05"],
      "router_trace_ids": ["rtr-aaa", "rtr-bbb", "rtr-ccc"]
    },
    "signing": {
      "issuer": "bardiel",
      "signature_scheme": "ed25519-v1",
      "signature": "0x...",
      "chain_anchor": null
    },
    "ttl": "30d",
    "visibility": "private"
  }
}
```

**Key Sections**

* `receipt.receipt_id`\
  Stable identifier for this Bardiel decision. Base apps, Virtual agents, ACP markets, and ERC-8004-compatible systems can store this as the decision handle.
* `task_meta`\
  Minimal description of what was judged:
  * `type` (for example `summary`, `json_tool_call`, `trade_decision`)
  * `input_hash` and `output_hash` rather than raw content
* `decision`\
  Bardiel’s final verdict and timestamp:
  * `status` mirrors the top-level `status`
  * `confidence` mirrors or refines the top-level `confidence`
  * `reasons` provide coarse-grained explanation
* `policy_snapshot`\
  Snapshot of Bardiel-side policy:
  * `tier` (`fast`, `safe`, `oracle`, `adaptive`)
  * mapped consensus ask: `replicas`, `strategy`
* `consensus_snapshot`\
  Derived from router v3’s `consensus` block:
  * `replicas`
  * `agreement`
  * `verdicts`
  * `strategy`
  * `confidence`
* `cortensor_refs`\
  IDs for operator-level audits:
  * `sessions`
  * `tasks`
  * `router_trace_ids`
* `signing`\
  Optional cryptographic signature:
  * `issuer`
  * `signature_scheme`
  * `signature`
  * optional `chain_anchor` if receipts are later anchored onchain
* `ttl` and `visibility`\
  Effective retention and visibility after Bardiel applies its own limits

***

### 5. Bardiel Receipt Lifecycle

v4 defines a simple lifecycle for receipts.

#### 5.1 Steps

1. **Decision**\
   Bardiel receives a v4 call, uses router v3 (`/delegate` or `/validate` with `consensus`) to run the job, and arrives at a `status` (`VALID`, `INVALID`, etc.) and `confidence`.
2. **Receipt Construction**\
   If `receipt.mode` is `"inline"` or `"detached"`:
   * build the Receipt Object (task meta, decision, policy snapshot, consensus snapshot, references)
   * sign it optionally
   * assign `receipt_id`
3. **Return to Caller**\
   Response includes:
   * result and decision (as in Bardiel v3)
   * plus `receipt` (inline) or at least `{ "receipt_id": "..." }` (detached)
4. **Lookup / Verification**\
   Bardiel exposes new v4-style endpoints conceptually:
   * `GET /api/v4/receipt/{receipt_id}` – fetch receipt by ID (subject to visibility and TTL)
   * `POST /api/v4/verify_receipt` – optional endpoint for schema and signature checks

External systems can:

* re-fetch receipts
* compare `input_hash` and `output_hash` to their own stored data
* use `cortensor_refs` and `trace_id` for joint debugging with infra operators

Retention, access control, and verification rules are environment- and governance-dependent.

***

### 6. Ecosystem Usage Patterns

#### 6.1 Base and Other Onchain Agent Apps

For Base-native apps and other onchain agent systems, receipts provide a lightweight proof object for:

* pre-action validation before state changes
* market or escrow decisions
* long-running automation systems that need an auditable record of why a result was trusted

Typical pattern:

* app calls Bardiel
* Bardiel validates or delegates on Cortensor
* app stores `receipt_id` with the resulting transaction, order, or workflow state
* later, the app can show or verify why the system proceeded

#### 6.2 ACP - Market-Level Receipts

For ACP, Bardiel receipts become the **record of decision** for jobs and disputes.

* **Job settlement**
  * ACP stores `receipt_id` with each job
  * buyers and sellers can inspect:
    * Bardiel’s verdict (`VALID`, `INVALID`, `RETRY`, `NEEDS_SPEC`)
    * policy and consensus snapshot (tier, replicas, agreement, confidence)
* **Disputes**
  * dispute tickets include one or more `receipt_id`s
  * escalations may trigger fresh Bardiel runs that generate new receipts
  * ACP dashboards can show a decision timeline built from receipts:
    * when Bardiel was called
    * how strong consensus was at each step
    * final arbitration verdict

#### 6.3 ERC-8004 - Onchain-Friendly Evidence

For ERC-8004-compatible agents and registries, receipts provide a bridge between offchain validation and onchain logic.

* registries and markets can:
  * store `receipt_id` or a hash of the Receipt Object onchain
  * refer to these receipts when resolving disputes or verifying agent behavior
* Bardiel can be configured as a validator/oracle where:
  * a claim is considered accepted only if:
    * `status` is `VALID`, and
    * the receipt meets policy and consensus requirements (for example `tier = "oracle"` and `replicas = 5`)

Future work may align the Receipt Object with:

* EIP-8183 and other validation artifact standards
* ERC-8004-specific offchain evidence formats that agents and contracts can parse

***

### 7. Backward Compatibility

Bardiel v4 is **additive** relative to v3:

* calls that omit the `receipt` block behave exactly like v3:
  * no receipts are created
  * responses remain `status`, `result`, `confidence`, `evidence`, `trace_id`, and `bardiel_version`
* receipts are optional:
  * strongly recommended for higher-stakes ACP and ERC-8004 jobs
  * useful for Base and other app-level workflows that need later auditability
  * not needed for low-risk or high-volume background tasks

Within a given Bardiel major version:

* the presence of `receipt` is non-breaking
* clients that do not know about receipts can safely ignore the field
* `receipt_id` is stable for at least its configured TTL; behavior after TTL expiry is documented per environment

***

### 8. Roadmap - From Consensus to Receipts and Beyond

* **Router v3 plus Bardiel v3**
  * explicit redundancy and consensus at the endpoint layer
  * Bardiel uses consensus metadata internally to decide when to trust, retry, or escalate
* **Bardiel v4 (this spec)**
  * adds **Receipts**