tooloracle.io · Deal Protocol · Draft v1.1 · Revised 2026-04-23 · Markdown source
Draft status. This specification is published for public review. It is currently implemented by a single reference deployment and MAY change before it leaves Draft. v1.1 is a sharpening pass over v1.0 — no scope changes, normative language tightened.

OracleNet Deal Discovery Protocol — v1

Field Value
Document Number ORACLENET-RFC-0001
Status Draft
Category Informational / Experimental
Authors OracleNet (did:web:tooloracle.io, did:web:feedoracle.io)
Created 2026-04-23
Revised 2026-04-23 (v1.1-draft — sharpened per public review)
Canonical URL https://tooloracle.io/docs/deal-protocol/rfc-0001
Protocol Identifier oraclenet-deal-v1
License CC BY 4.0 (specification). Reference code: see implementation repositories.

Abstract

This document specifies the OracleNet Deal Discovery Protocol, a permissioned commercial matching layer for autonomous software agents. It defines a set of signed, machine-readable artefacts and a strict client-side gate chain that together let two agents (1) declare what they offer and seek as commercial intent, (2) discover one another without spamming, and (3) exchange cryptographically verifiable proposals under auditable governance. It is explicitly not a general agent-to-agent messaging protocol and not a cold-outreach channel; see §1.5.

The protocol is designed for the Model Context Protocol (MCP) / Agent-to-Agent (A2A) ecosystem and assumes HTTPS, JSON, and a public DID-style identity for each participating agent.

The protocol deliberately separates six concerns into six artefacts: (1) curated intent, (2) anti-spam governance, (3) discovery broadcast, (4) commercial message format, (5) observed demand, and (6) counterparty assessment rules. Each artefact is independently versioned and independently verifiable.

Status of This Memo

This is a Draft submitted for public review. It describes a protocol which is currently running in a single reference deployment (OracleNet, April 2026). It is published to invite review, adoption, and revision. This memo is not an IETF RFC and does not represent the work of any standards body.

Changes will be tracked in the repository of record and signalled by incrementing the $id of each JSON-Schema. Backward-incompatible changes will increment the major-version suffix of the protocol identifier (oraclenet-deal-v2, etc.).

1. Introduction

1.1. Problem

Autonomous AI agents and MCP servers have proliferated. They make one-off bespoke connections by email, by human intermediaries, or by ad-hoc JSON POSTs. There is no common machine-readable way for two agents to find out:

1.2. Goals

This protocol has five goals, in priority order:

  1. Opt-in first. No agent receives deal proposals unless it has published a policy that says it is willing to.
  2. Verifiable. Every proposal, every policy, and every broadcast is signed; tampering is detectable without trusting the server that hosts the artefact.
  3. Auditable. A participating agent can produce a full, append-only, time-ordered record of every attempt, decision, and response — including negative ones.
  4. Anti-spam. The sender is expected to run a pre-flight check (readiness, fit, rate limit, governance) and refuse to send when any gate fails. Receivers are not expected to carry the filtering load alone.
  5. Minimal coupling. No shared database. No central registry. Each agent publishes its artefacts under its own origin. Discovery can be pointer-based (manifest / Link header) or crawl-based (Atom feed).

1.3. Non-Goals

This protocol does not specify:

1.4. Relationship to Other Work

This protocol sits above the transport layer (HTTPS) and above the identity layer (DID / .well-known/agent.json). It is intended to be compatible with:

1.5. Scope: What This Protocol Is Not

To prevent category confusion, the following are out of scope — and a conformant implementation MUST NOT rely on this protocol for any of them:

In short: this is the commercial discovery and permissioned proposal layer. Everything else — chat, settlement, identity, licensing — is a neighbour, not a feature.

2. Conformance

The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" in this document are to be interpreted as described in RFC 2119 and RFC 8174 when, and only when, they appear in all capitals.

A conformant implementation MUST:

  1. Publish a signed deal-policy.json at /.well-known/deal-policy.json of its canonical origin.
  2. Treat any policy whose inbox.accepts list is empty — or missing — as an explicit do not send me proposals signal.
  3. Verify the cryptographic signature on every inbound proposal; reject on mismatch, expiry, or unknown signer.
  4. Honour the opt-out / do-not-contact registry that its own policy references, both for incoming attempts it publishes to reject and for its own outgoing attempts.
  5. Refuse to emit an outbound proposal unless every gate in §10.3 has passed; a conformant implementation MUST log every gate decision (pass or fail) in an append-only audit store.

Required vs Recommended at a glance:

Layer Artefact Status
1 deal-policy.json REQUIRED
2 do-not-contact.json (or equivalent) REQUIRED
6 Gate chain enforcement + audit logging REQUIRED
3 deal-feed.atom RECOMMENDED
4 deal-proposal-card.v1 (W3C VC wire format) RECOMMENDED
5 deal-emergence.json RECOMMENDED
HTTP Link headers for discovery RECOMMENDED

An implementation MAY publish Layers 3, 4, and 5. An implementation that publishes any of them MUST conform to its schema.

3. Terminology

Term Meaning
Agent An autonomous software process with a stable DID and one or more public endpoints.
Deal A proposed arrangement between two agents involving exchange of capability, data, or value.
Proposal A message of type capability_declaration, partnership_inquiry, or counter_offer.
Inbox The HTTP endpoint to which an agent accepts proposals.
Readiness Tier A coarse classification of how ready an agent is to receive a deal proposal.
Fit Score A numeric estimate of how promising a match between two agents is.
Gate A single check in the outbound pipeline. A send MUST NOT proceed unless every gate is satisfied.
Origin The scheme+host+port under which an agent publishes its canonical artefacts.

4. Architecture Overview

The protocol defines six layers, each implemented by one or more artefacts.

┌─────────────────────────────────────────────────────────────┐
│ Layer 6 — Counterparty Assessment                           │
│   readiness tiers, fit score, guard hooks, rate limits      │  (client-side)
├─────────────────────────────────────────────────────────────┤
│ Layer 5 — Observed Demand       /.well-known/deal-emergence │
│   behavioural emergence → demand hypotheses                 │
├─────────────────────────────────────────────────────────────┤
│ Layer 4 — Commercial Message    deal-proposal-card.v1 (VC)  │
│   W3C Verifiable Credential, EcdsaSecp256k1Signature2019    │
├─────────────────────────────────────────────────────────────┤
│ Layer 3 — Discovery Broadcast   /.well-known/deal-feed.atom │
│   subscribable Atom feed of capabilities sought             │
├─────────────────────────────────────────────────────────────┤
│ Layer 2 — Anti-Spam Governance  /.well-known/do-not-contact │
│   signed opt-out registry                                   │
├─────────────────────────────────────────────────────────────┤
│ Layer 1 — Curated Intent        /.well-known/deal-policy    │
│   what I offer, what I seek, how to reach me, who may       │
└─────────────────────────────────────────────────────────────┘

Each layer is independently fetchable, independently signed, independently versioned. Layers 1 and 2 are the only REQUIRED layers for conformance. Layers 3–6 are RECOMMENDED.

Discovery is pointer-based: a well-behaved agent publishes an HTTP Link header of the form:

Link: </.well-known/deal-policy.json>; rel="deal-policy",
      </.well-known/do-not-contact.json>; rel="do-not-contact",
      </.well-known/deal-feed.atom>; rel="deal-feed"

5. Layer 1 — Curated Intent (deal-policy.json v1)

5.1. Location

The file MUST be published at /.well-known/deal-policy.json of the agent's canonical origin. It MUST be served with Content-Type: application/json and SHOULD include Cache-Control: max-age=3600 or similar.

5.2. Required fields

An implementation MUST publish at minimum:

If inbox.accepts is empty, the agent is signalling that it does not accept proposals. Senders MUST treat this as a refusal.

An implementation SHOULD publish each of the following. The Status column is normative per-field:

Field Status Notes
schema_url SHOULD Pointer to the JSON Schema of this document.
specification_url SHOULD Pointer to this specification (enables self-describing artefacts).
capabilities_offered SHOULD Machine-readable list with at least skill; description, pricing, endpoint, evidence are OPTIONAL per entry.
capabilities_sought SHOULD Machine-readable list with at least type; freshness_max_hours, max_price_usd_per_call, notes are OPTIONAL per entry.
policy SHOULD At minimum min_trust_level and rate_limit_per_sender.
policy.rate_limit_per_sender SHOULD Conformant senders MUST honour it; missing = fall back to 1 thread per counterparty per 30 days.
opt_out_registry SHOULD URL of the Layer 2 do-not-contact registry. If absent, the default /.well-known/do-not-contact.json of the origin is assumed.
escrow MAY On-chain settlement contract reference, if any.
ttl_seconds SHOULD Fetcher-side cache control.

5.4. Signature

Signature MUST be produced over the canonical serialisation (JSON with keys sorted lexicographically, no trailing whitespace) of the policy document with the signature field removed. The signature block MUST include:

Verifiers MUST recompute the canonical hash independently and compare against content_hash. They MUST NOT trust the content_hash field alone.

5.5. Caching

Verifiers SHOULD honour Cache-Control of the response, up to a maximum of 24 hours. They SHOULD re-fetch on any verification failure.

6. Layer 2 — Anti-Spam Governance (do-not-contact.json v1)

6.1. Purpose

Every publisher of a deal-policy.json MAY maintain a companion opt-out registry. Any other agent that has explicitly told this publisher to stop contacting them SHOULD appear in that registry. Senders MUST consult the registry before every outbound proposal.

6.2. Location and structure

Published at /.well-known/do-not-contact.json. MUST contain:

6.3. Semantics

A match of either did (case-insensitive exact) or domain (case-insensitive exact or wildcard suffix) against the target URL's host or DID MUST cause the sender to abort the proposal. The abort MUST be logged in the sender's audit trail (Layer 6).

6.4. Self-enforcement

A sender MUST consult its own do-not-contact.json as well when its policy is to honour its own published opt-out registry. In other words, opt-out is symmetric: what you declare publicly as your opt-out registry is what you yourself enforce.

6.5. Forbidden Practices

The following sender behaviours are explicit violations of this specification. A conformant implementation MUST NOT engage in any of them:

  1. Sending to an agent below deal_ready tier. A target without a signed deal-policy.json declaring non-empty inbox.accepts is, by definition, not opted in.
  2. Bulk parallel POSTs. A sender MUST serialise outbound proposals per counterparty and MUST NOT broadcast the same VC to multiple inboxes in a single burst.
  3. Re-contacting within the rate window. A sender MUST NOT open a second thread with the same counterparty within the window declared by the target policy (or the 30-day default, whichever is stricter) unless the counterparty explicitly invites follow-up.
  4. Fabricated fit claims. The fit_claim block in a proposal MUST reflect the sender's actual computed score. Systematic inflation is a violation and is grounds for the recipient to add the sender's DID to a DNC registry.
  5. Signing under another DID. A sender MUST only sign under DIDs it controls. Impersonation is a severe violation.
  6. Ignoring expiry. A sender MUST NOT re-send an expired Verifiable Credential; it MUST mint a fresh one.
  7. Stripping audit entries. Audit rows are append-only. A conformant implementation MUST NOT modify or delete them for at least 12 months after creation.
  8. Probing without identification. A sender's probe of a target's readiness MUST use a self-identifying User-Agent string; anonymous or spoofed probes are a violation.

A recipient that detects any of these violations SHOULD add the offending DID or domain to its do-not-contact.json and MAY publicly disclose the violation in its deal-emergence.json under a violations section (future work).

7. Layer 3 — Discovery Broadcast (deal-feed.atom v1)

7.1. Purpose

A subscribable, Atom-conformant feed through which an agent announces what it is seeking. Machine-readable RSS/Atom clients can subscribe; crawlers can index.

7.2. Location and format

Published at /.well-known/deal-feed.atom. MUST be a well-formed Atom 1.0 (RFC 4287) document. MUST include:

7.4. Regeneration cadence

The feed SHOULD be regenerated no more often than every 5 minutes, and at least whenever deal-policy.json changes. A regeneration cadence of 15 minutes is RECOMMENDED as a sensible default.

8. Layer 4 — Commercial Message Format (deal-proposal-card.v1)

8.1. Purpose

The wire format for a proposal. Wraps the semantic payload in a W3C Verifiable Credential so that a downstream party — not only the sender and receiver — can verify provenance and integrity.

8.2. Data model

A Deal Proposal Card is a VC v2 credential with:

8.3. credentialSubject

Fields:

8.4. Proof

The proof block MUST contain:

Verifiers MUST recompute the canonical hash (proof-field stripped) and MUST NOT rely on the embedded contentHash as ground truth.

8.5. Legacy compatibility

An implementation MAY receive a legacy-signed plain JSON message (no VC wrap, a top-level signature block). A conformant implementation SHOULD continue to accept such messages and verify them via the Layer 1 signature rules. Outbound messages SHOULD use the VC form.

8.6. Pragmatic canonicalisation

This protocol deliberately does not require JSON-LD canonicalisation (URDNA2015) in v1. The reasons are practical:

Implementations MAY upgrade to JCS (RFC 8785) or JSON-LD canonicalisation, but such upgrades MUST be signalled by bumping the proof type identifier and MUST remain verifiable by naive canonical-JSON consumers during a transition period.

8.7. Why a Verifiable Credential instead of plain signed JSON

Two practical reasons, no purity test:

  1. Third-party verifiability. A VC carries its own issuer, validFrom, validUntil, and proof block. A third party — not only the sender or recipient — can verify the proposal was actually issued by the claimed party at the claimed time. Plain signed JSON achieves this too, but the VC form has explicit, named fields.
  2. Toolchain re-use. VC libraries and DID-resolution libraries already exist; reusing them costs less than inventing a parallel format.

If neither of these matters to an implementation, legacy plain-signed JSON (§5.4 signature shape) is acceptable. Receivers MUST accept both forms.

9. Layer 5 — Observed Demand (deal-emergence.json v1)

9.1. Purpose

Publishes, in a signed and machine-readable form, what the agent has observed — as opposed to declared. An agent that sees external callers routinely combine two of its tools can derive a "demand hypothesis" about a capability that would complement the pair. Publishing this emergence signal separately from the curated intent is epistemically honest and gives interested counterparties richer grounds to approach.

9.2. Location and structure

Published at /.well-known/deal-emergence.json. MUST contain:

9.3. Distinction from Layer 1 — the epistemic hierarchy

The separation between Layer 1 (curated intent) and Layer 5 (observed demand) is normative, not cosmetic.

Layer 1 — deal-policy.json Layer 5 — deal-emergence.json
What it expresses Declared intent the operator stands behind Observed behaviour mined from actual agent traffic
Trust weight Stronger (the operator signs on behalf of the organisation) Weaker (a statistical signal, may be provisional)
Updated By a human operator, rarely Automatically, frequently
Use in sender decisions Primary driver Supplementary / directional

A conformant implementation MUST NOT merge the two sets into a single capabilities_sought array. They live in separate artefacts because they mean different things.

A sender that POSTs a capability_declaration in response to a Layer 5 emergent signal MUST include a field in credentialSubject.fit_claim that cites the source:

"source_signal": {
  "layer": 5,
  "origin_url": "https://<target>/.well-known/deal-emergence.json",
  "meta_tool_name": "<as appears in the emergence doc>",
  "observed_at": "<timestamp>"
}

This makes the epistemic source of the proposal traceable end-to-end.

A recipient that receives a proposal targeting a capability that exists ONLY in Layer 5 (not yet in Layer 1) SHOULD treat the proposal as exploratory and MUST NOT assume the sender has accepted the same terms as for a curated capability.

9.4. Filter rules

An implementation SHOULD NOT emit emergence signals with distinct_agents < 3. This prevents one looping agent from creating phantom demand.

10. Layer 6 — Counterparty Assessment

Layer 6 is not an artefact but a set of client-side rules every sender MUST run before an outbound proposal.

10.1. Readiness tiers

Given a target URL, a sender computes a readiness tier in the set:

Tier Meaning
scanner Target is at most reachable, no machine-readable signals.
probe_responsive Target responds on root but exposes no .well-known/ artefacts.
machine_readable At least one of agent-card, llms.txt, or MCP server-card is parseable.
handshake_capable Agent card + inbox URL present, OR a deal-policy.json exists.
deal_ready deal-policy.json with non-empty inbox.accepts is present AND signed AND paired with either a DID document or a signed deal-policy.

A sender MUST NOT send a proposal to a target whose tier is lower than deal_ready.

10.2. Fit score

A sender SHOULD compute a fit score with at least four components:

A sender SHOULD NOT send a proposal unless the fit score is at least 0.5. Implementations MAY set a higher threshold.

10.3. Gates

Before every outbound proposal, a sender MUST run these gates in order and abort on the first failure:

  1. Readiness check (must be deal_ready).
  2. Do-not-contact check (target MUST NOT match any entry in the sender's DNC registry or the target's own).
  3. Rate limit check (no active thread with the same counterparty within the policy-defined window).
  4. Fit score check (overall ≥ threshold).
  5. Governance pre-flight (e.g. AgentGuard policy_preflight) — decision MUST be allowed.
  6. Dry-run flag MUST be explicitly off.

Every gate — pass or fail — MUST be logged in an append-only audit table with at minimum: timestamp, target URL, state transition, decision, reason, dry-run flag, and a request ID linking to the governance pre-flight trace. Audit rows MUST be retained for at least 12 months.

Default rate-limit window: if the target policy does not declare policy.rate_limit_per_sender, the sender MUST assume the default of one thread per counterparty per 30 calendar days.

Default fit-score threshold: if the sender has no local policy override, the threshold is 0.5 overall. Senders MAY set a higher bar but MUST NOT set it lower than 0.3.

Default dry-run: implementations SHOULD ship with dry_run = true as the factory default. Flipping to live send is an explicit operator action.

10.4. Governance hooks

A governance service (e.g. AgentGuard) SHOULD be consulted as gate 5. The service MUST return at minimum {decision, risk_score, request_id}. The sender MUST log the request_id for audit reconstruction. A decision other than allowed / allow MUST abort the send.

11. Trust & Signing Model

11.1. Keys

Each agent MUST have a stable long-lived signing key. ES256K (secp256k1) is RECOMMENDED for compatibility with Ethereum-based tooling; EdDSA is acceptable.

11.2. DIDs

Each agent MUST have a stable DID resolvable to its signing key. did:web:<domain> is RECOMMENDED for operational simplicity; other DID methods are acceptable.

11.3. Key rotation

Rotation is out of scope for v1. Implementations SHOULD publish key-rotation metadata in the DID Document itself; readers SHOULD honour it.

11.4. Signature canonicalisation

Canonical JSON is produced by serialising with keys sorted lexicographically, UTF-8 encoding, no superfluous whitespace, and the signature / proof field removed. Future work MAY switch to JCS (RFC 8785) or an equivalent.

12. Security Considerations

12.1. Spoofing

Because every artefact is signed and every verifier is expected to recompute the canonical hash, a malicious origin cannot impersonate a legitimate agent without obtaining their private key.

12.2. Replay

Deal Proposal Cards (Layer 4) carry validFrom / validUntil. Receivers MUST reject expired VCs. Nonces are not mandated in v1; implementations that require replay protection beyond expiry SHOULD add application-level deduplication based on the VC id.

12.3. Denial-of-service via proposals

Receivers MAY rate-limit their inbox. Senders MUST rate-limit themselves at the source (gate 3). The combination SHOULD keep inbox load bounded.

12.4. Trojan capabilities

An agent that publishes a capability_offered is declaring, not proving. Consumers of declared capabilities SHOULD independently verify (e.g. via evidence URLs or sandboxed probes) before acting on them.

13. Privacy Considerations

13.1. Public artefacts

All artefacts defined by this protocol are public. An agent publishes its intent, its demand signals, and its opt-out list openly. Agents that require confidentiality SHOULD NOT implement Layer 3 (broadcast) for the relevant capabilities, and MAY set min_trust_level higher in their Layer 1 policy.

13.2. Target identification

When a sender probes a target for readiness, it transmits request headers (User-Agent, etc.). A sender SHOULD use a descriptive, self-identifying User-Agent so that the target can identify the probe in its logs and either welcome or block it.

13.3. Operator fingerprinting

Layer 5 (emergence) exposes what the publisher has observed about its own external callers in aggregate. Publishers SHOULD publish aggregate metrics only; per-agent traces SHOULD NOT appear in the source.corpus_stats.

14. IANA / Namespace Considerations

This protocol defines the following URNs:

No IANA registration is requested for Draft status. If the protocol leaves Draft, a proper registration of the namespace is recommended.

15. Examples

Full worked examples (minimal conformant deal-policy.json, a signed VC, an Atom feed, a DNC registry, an emergence document) are provided in the companion file:

16. Reference Implementation

A running reference implementation is available at:

Public inspection endpoints:

Source code location: see the oraclenet-deal-protocol reference repository (to be linked when published).

17. Acknowledgments

The protocol draws on — and is gratefully indebted to — prior work in W3C Verifiable Credentials, Atom Syndication (RFC 4287), well-known URIs (RFC 8615), and the emerging practice of did:web: identity documents.

18. References

18.1. Normative

18.2. Informative

Appendix A — Conformance Checklist

A conformant implementation:

# Requirement Level
1 Publishes signed deal-policy.json at /.well-known/deal-policy.json MUST
2 Signs deal-policy.json with ES256K or EdDSA MUST
3 Publishes do-not-contact.json (or points to one) and honours it, incoming + outgoing MUST
4 Verifies cryptographic signature on every inbound proposal MUST
5 Recomputes canonical hash independently; does not trust embedded hash MUST
6 Rejects outbound proposals to targets whose tier is below deal_ready MUST
7 Logs every gate decision in append-only audit, retained ≥ 12 months MUST
8 Serialises outbound proposals per counterparty (no bulk parallel POSTs) MUST
9 Honours the 30-day rate-limit window per counterparty (or stricter if the target declares it) MUST
10 Ships with dry_run = true as factory default SHOULD
11 Publishes Atom feed of capabilities_sought SHOULD
12 Publishes deal-emergence.json separately from curated intent SHOULD
13 Uses Verifiable Credential format for outbound proposals SHOULD
14 Publishes Link: headers advertising deal-policy, do-not-contact, deal-feed SHOULD
15 Consults a governance pre-flight service before every send SHOULD
16 Uses a self-identifying User-Agent string for probes SHOULD
17 Cites source_signal when responding to a Layer 5 emergent signal SHOULD
18 Accepts both VC and legacy signed-JSON inbound forms SHOULD

Appendix B — Change Log

Version Date Change
1.0-draft 2026-04-23 Initial draft.
1.1-draft 2026-04-23 Sharpening pass: added §1.5 "What This Protocol Is Not"; per-field SHOULD/MAY markers in §5.3; new §6.5 "Forbidden Practices"; new §8.6 pragmatic canonicalisation + §8.7 rationale for VC choice; reinforced §9.3 epistemic hierarchy with required source_signal for Layer-5-driven proposals; added explicit defaults and 12-month audit retention in §10.3; expanded conformance checklist to 18 items.