Skip to content

CONCEPTS.md

Latest commit

 

History

History
92 lines (62 loc) · 5.17 KB

CONCEPTS.md

File metadata and controls

92 lines (62 loc) · 5.17 KB

FairAd concepts

A short reference for every important term, header, and flow in the FairAd protocol.
For protocol standards (RFCs, HTTPS, Ed25519, etc.), see PROTOCOL_STANDARDS.md.

Roles

Role Who Responsibility
Merchant E-commerce store Publishes manifest, runs Merchant MCP, signs Payment Commitments, settles on valid PoI.
AI Agent Conversational AI / assistant Discovers merchants, requests context and bids, shows sponsored recommendations, proves human + disclosure, submits PoI.
User End human Sees “Sponsored Recommendation from [Merchant]” when the reply is paid.

Discovery

  • Manifest — fairad.json at https://domain.com/.well-known/fairad.json. Tells agents where your MCP is and how to bid.
  • Discovery Crawler — Python tool that fetches /.well-known/fairad.json for given domains and maintains a local merchant directory so agents can find merchants without a central registry.

Signed bidding

  • Merchant MCP — The “Ad-Server.” Exposes tools:
    • get_sponsored_context(category, amount?, human_token?) → product metadata + Payment Commitment
    • get_manifest() → same data as fairad.json
  • Payment Commitment — Signed message from the merchant: “I will pay $X upon proof of a human-verified impression.” Contains: commitment_id, merchant_domain, amount, currency, category, timestamp, signature, public_key. Becomes binding only when the request includes a valid Proof of Human token.

Fraud prevention (Proof of Human)

  • Proof of Human (PoH) — Attestation that a real human started the session. Reduces fake or bot-driven “impressions” that would wrongly claim merchant bids.
  • X-FairAd-Human-Token — HTTP header (or equivalent in MCP context) carrying the PoH attestation. Supported providers: Worldcoin, Privy, OIDC. If this token is valid, the Payment Commitment is treated as legally binding for settlement.
  • Strict PoH — Set FAIRAD_POH_STRICT=true to enforce provider-specific checks: OIDC JWTs can be verified against the issuer’s JWKS via verify_poh_with_token(raw_token); Worldcoin/Privy require non-empty subject and signature.
  • Binding commitment — A Payment Commitment plus a valid PoH for the same session. Only binding commitments can be used in a valid Proof of Impression.

Transparency

  • Disclosure text — The exact string that must appear in the UI when showing a FairAd-sponsored reply:
    Sponsored Recommendation from [Merchant Name]
  • Transparency header — When the agent serves sponsored content, it should send:
    • X-FairAd-Disclosure: the disclosure text
    • X-FairAd-Sponsor: merchant name
  • Disclosure hash — SHA-256 of (disclosure text + snippet). The Proof of Impression must include this hash; otherwise the receipt is invalid for payment. So the agent cannot get paid without having shown the disclosure.

Proof of Impression (PoI)

  • Proof of Impression — The “Ad-Receipt”: the invoice the agent sends to the FairAd network (or merchant) for settlement. It combines:
    1. Merchant bid signature (the Payment Commitment)
    2. Human attestation token id (reference to the PoH that made the commitment binding)
    3. Agent disclosure hash (proof the disclosure was included in what was shown)
  • Receipt hash — Unique hash of the PoI payload; used as the settlement identifier.

HTTP API and settlement

  • HTTP API — REST wrapper at /manifest, /sponsored-context (POST), /settlement/submit (POST). Same semantics as the Merchant MCP; use when the agent cannot use MCP. Send X-FairAd-Human-Token for binding commitments.
  • Settlement ledger — Accepts PoI at POST /settlement/submit. Validates commitment signature, disclosure hash format, and unique poi_id. Optional file persistence via FAIRAD_LEDGER_PATH.

Headers quick reference

Header Direction Meaning
X-FairAd-Human-Token Agent → Merchant (or handshake) Proof of Human attestation; valid token makes Payment Commitment binding.
X-FairAd-Disclosure Agent → User / response The required disclosure text when serving sponsored content.
X-FairAd-Sponsor Agent → User / response Merchant name for the sponsored snippet.

Flow summary

  1. Agent discovers merchant via /.well-known/fairad.json (or local directory from crawler).
  2. Agent calls Merchant MCP get_sponsored_context(category, amount?, human_token?).
  3. Merchant returns product metadata + Payment Commitment; if human_token is valid PoH, commitment is binding.
  4. Agent shows recommendation to user and must include “Sponsored Recommendation from [Merchant]” in the UI.
  5. Agent builds Proof of Impression (commitment + PoH token id + disclosure hash) and submits for settlement.
  6. Merchant (or network) verifies PoI and settles.

Summary: Merchants pay only for human-verified, disclosed impressions. Users always see when a recommendation is sponsored.

For protocol standards (RFCs, HTTPS, Ed25519, etc.), see PROTOCOL_STANDARDS.md.