feat: add reputation extension specification

[tenequm]

Summary

Adds the reputation extension specification for x402, enabling cryptographic proof of agent interactions linked to payment transactions.

Implements the proposal from #931 with additions:

• Agent signatures on every response (proof of service delivery)
• Multi-chain support (ERC-8004 compliant registries on EVM and Solana)
• Registration file format with authorized signers
• Prevents fake feedback spam (requires cryptographic proof of actual service delivery)

Key Design

Agents sign responses with their registered identity keys as part of the normal response flow. This provides:

• Zero-overhead proof of service: Signing happens naturally as part of returning the response
• Non-selective participation: Agents cannot avoid creating proofs (sign WITH every response, before knowing feedback outcome)
• Trustworthy feedback: Each review cryptographically tied to actual service delivery

Without agent signatures, clients could send 1000 payment transactions without ever requesting service and submit 1000 fake reviews. Agent signatures ensure feedback represents real interactions.

Implementation Status

Extension implementations in progress, coordinating with @ruhil6789 for EVM and Solana sides.

Backend registries ready:

• EVM: ERC-8004 contracts on Base, Ethereum
• Solana: SATI (ERC-8004 compliant)

References

• Ref: [extension] Support ERC-8004 for payment-based reputation #931
• ERC-8004 Specification: https://eips.ethereum.org/EIPS/eip-8004
• SATI Implementation: https://github.com/cascade-protocol/sati

CC: @notorious-d-e-v @ruhil6789

[cb-heimdall]

🟡 Heimdall Review Status

Requirement	Status	More Info
Reviews	🟡 0/1	Denominator calculation Show calculation 1 if user is bot 0 1 if user is external 0 2 if repo is sensitive 0 From .codeflow.yml 1 Additional review requirements Show calculation Max 0 0 From CODEOWNERS 0 Global minimum 0 Max 1 1 1 if commit is unverified 0 Sum 1

[vercel]

@tenequm is attempting to deploy a commit to the Coinbase Team on Vercel.

A member of the Team first needs to authorize it.

[tenequm]

Updated spec with:

• Added "Pre-Payment Verification" section - clients should verify payTo matches on-chain agentWallet BEFORE sending payment
• Converted TypeScript to pseudocode (matches other x402 extension style)
• Uses unified ERC-8004 interface (getAgentWallet, tokenURI) for both EVM and SATI backends

[notorious-d-e-v]

Nice work @tenequm!

My three main pieces of feedback would be:

1. What is backend used for? Imo there is no need to abstract "reputation" -- instead I would just build the extension as 8004-reputation and keep it specific to 8004.
2. The signing is a great idea and agree that it is useful, however I don't think it should be required. I think the server can optionally require signing by including a flag in the PAYMENT-REQUIRED step, and the client should be able to upgrade to signing if they want by including a field in the PAYMENT-SIGNATURE step.
3. I think this is true, but I just want to confirm -- a server or client can choose which 8004 smart contracts they want to use by setting the desired contract addresses in the agentRegistry and reputationRegistry fields. Even though EVM seems to have a canonical 8004 implementation, solana seems to have multiple (SATI and 8004-solana).

[tenequm]

@notorious-d-e-v thanks for the feedback. Will make changes based on it.

[tenequm]

@notorious-d-e-v Following up before I make the changes - want to make sure I implement what you intended:

1. Backend abstraction → 8004-reputation

Clear - will rename extension to 8004-reputation and remove the backend field. The registry addresses already identify the implementation.

2. Optional signing

Want to confirm scope here. The spec has agent signatures in two places:

a) Agent signs response (PAYMENT-RESPONSE) - proof-of-service-delivery
b) Client signs feedback (feedbackURI) - ties feedback to specific interaction

Are you asking to make (a) optional? So:

• Server declares "signatures": true in PaymentRequired extension to opt-in
• Client can request "requestSignature": true in payment payload
• If neither opts in, no agent signature in response

3. Multi-registry support

Confirmed - agentRegistry and reputationRegistry fields let implementations point to SATI, 8008-solana, or any ERC-8004 compliant registry.

---

Let me know on point 2 and I'll push the updates.

[phdargen]

What about request/responses with binary data?

[phdargen]

Thanks a lot for putting this together @tenequm @notorious-d-e-v, overall looks great to me!

@notorious-d-e-v proposal stated "Payments and reputation feedback occur on the same chain", this seems implicit in this PR too. It would be great if we could decouple payments from identity, otherwise servers need registrations on every chain they want to accept payments and feedback is fragmented.

I'd suggest to allow agents to have identity on one chain (or a select few, ordered by preference) while accepting payments on any chain. The registration file could include a paymentAddresses array listing accepted chains/addresses (must be same as in 402 response). Clients could then submit feedback on any of the agent's identity chains, referencing the cross-chain payment via taskRef. For example agent has identity on Base, accepts payments on Base and Solana, client pays on Solana but submits feedback on Base or vice-versa.

[phdargen]

The 8004 evm contracts have been audited, did the svm implementations went through the same scrutiny?

[phdargen]

In general, preferred to finalize specs before discussing implementation details but since you've already started exploring, a few thoughts:

• extensions should not modify core packages
• the enrichSettlementResponse hook should be good for the payment response
• for the client feedback, I think we will also need sth like a onResourceDelievered hook. I will add this in a seperate PR as it should be general-purpose, not narrowly scoped to a specific use-case
• If you anticipate the need for any additional hooks, please tag me and I will look into it

[notorious-d-e-v]

@notorious-d-e-v Following up before I make the changes - want to make sure I implement what you intended:

1. Backend abstraction → 8004-reputation

Clear - will rename extension to 8004-reputation and remove the backend field. The registry addresses already identify the implementation.

2. Optional signing

Want to confirm scope here. The spec has agent signatures in two places:

a) Agent signs response (PAYMENT-RESPONSE) - proof-of-service-delivery b) Client signs feedback (feedbackURI) - ties feedback to specific interaction

Are you asking to make (a) optional? So:

* Server declares `"signatures": true` in PaymentRequired extension to opt-in

* Client can request `"requestSignature": true` in payment payload

* If neither opts in, no agent signature in response

3. Multi-registry support

Confirmed - agentRegistry and reputationRegistry fields let implementations point to SATI, 8008-solana, or any ERC-8004 compliant registry.

Let me know on point 2 and I'll push the updates.

Regarding the optional signing preferences.

The way I imagined it was

step	effect
PAYMENT-REQUIRED	Server can request signing. If the client doesn't echo it back in PAYMENT-SIGNATURE, then no feedback is given by the server
PAYMENT-SIGNATURE	Client can request signing. If the server doesn't provide a signature in PAYMENT-RESPONSE, then no feedback is given by the client
PAYMENT-RESPONSE	The client will see whether the server signed or not, and can leave feedback, or not.

If both parties don't request signatures, then both parties are free to leave feedback if they want to, or not.

It seems like the client can trick the server though and not leave signed feedback, even if it promised to.

[tenequm]

Just pushed several commits addressing the review:

Changes

• Removed backend field - registry addresses (CAIP-10) already identify the implementation
• Renamed extension to 8004-reputation per @notorious-d-e-v suggestion
• Renamed maxAmountRequired → amount in examples
• Added missing resource field to Multi-Chain example
• Added x402Support and supportedTrust fields to registration file per ERC-8004 spec
• Fixed PAYMENT-RESPONSE structure to match PR New hooks for extensions to enrich payment-required and payment-response #1003 convention (removed settlementResponse wrapper, txHash → transaction, networkId → network)

---

On SVM audit status

@phdargen Not formally audited yet - formal audit is on the roadmap. The spec itself is registry-agnostic and works with any ERC-8004 compliant implementation.

---

Remaining questions

Will think through and respond tomorrow on:

• Binary data in request/responses
• Aligning proofOfPayment with ERC-8004 spec structure
• feedbackAggregator specification scope
• Bidirectional ratings vs server-only focus
• agentWallet fallback when no signers specified
• Cross-chain feedback model (paymentAddresses array proposal)
• Optional signing mechanics and client commitment

Noted on implementation guidance - will keep extension isolated from core packages and use the hooks you mentioned.

Appreciate the detailed feedback @phdargen @notorious-d-e-v - want to get these right.

[tenequm]

@phdargen @notorious-d-e-v

Apologies for the delay - this took longer than expected as I dug deeper into all the involved mechanisms to make sure the approach is consistent.

Here's my proposed direction for each remaining question. Want to confirm alignment before pushing changes.

---

Q1: Binary data in request/responses

Proposed: Signature computed over raw bytes:

• dataHash = keccak256(requestBodyBytes || responseBodyBytes)
• interactionHash = keccak256(taskRefBytes || dataHash)
• Agent signs interactionHash

Binary bodies (images, files) used as-is. Text bodies UTF-8 encoded. No special handling needed - keccak256 operates on bytes directly.

---

Q2: Align proofOfPayment with ERC-8004 structure

Proposed: Rename to proofOfParticipation with these fields:

Field	Purpose
taskRef	CAIP-220 payment reference
dataHash	keccak256(request || response)
agentSignerPublicKey	Which key signed (for multi-signer agents)
agentSignature	Signature over keccak256(taskRef || dataHash)
agentSignatureAlgorithm	ed25519 or secp256k1
reviewerAddress	Actual reviewer's address (CAIP-10)
reviewerSignature	Proves reviewer authorized this feedback
reviewerSignatureAlgorithm	ed25519 or secp256k1

Why proofOfParticipation instead of proofOfPayment:

• Payment proof is already in taskRef (CAIP-220 contains chain + txHash)
• What x402 uniquely provides is proof of participation - that the client actually received service, not just that they paid
• The agent signature over dataHash (request + response content) cryptographically binds feedback to actual service delivery
• This is what makes x402 feedback meaningful vs. generic on-chain reviews

Why reviewerAddress + reviewerSignature:
ERC-8004's giveFeedback() hardcodes clientAddress = msg.sender. When aggregator submits on behalf of client, on-chain clientAddress = aggregator address. The real reviewer must be identified and verified in feedbackURI so consumers know who actually left the feedback.

---

Q3: feedbackAggregator specification scope

Proposed: In scope for v1. Essential for practical adoption.

The problem without aggregator:

• Client must have wallet on agent's identity chain
• Client must have native tokens for gas
• Cross-chain friction: paid on Solana, need ETH on Base for feedback
• Most clients won't bother → less feedback → less useful reputation data

How it works:

1. Agent declares feedbackAggregator URL in registration file
2. Client receives PAYMENT-RESPONSE with agent signature
3. Client signs their review off-chain (no on-chain interaction)
4. Client POSTs to aggregator: { paymentResponse, review: { value, reviewerAddress, reviewerSignature } }
5. Aggregator validates signatures, builds feedbackURI JSON, uploads to IPFS
6. Aggregator submits to identity chain's reputation registry, pays gas
7. Client gets confirmation

Economic model:

• Agent funds aggregator (deposit, subscription, or per-feedback fee)
• Aggregator submits ALL feedback regardless of sentiment - this is a trust requirement
• Agent benefits from operational reputation system; aggregator is infrastructure

Why facilitators are natural fit:
Facilitators already validate settlements against their records. They have the infrastructure, the trust relationship with agents, and economic alignment. A facilitator-operated aggregator can verify the payment actually happened before accepting feedback submission.

---

Q4: Bidirectional ratings vs server-only focus

Agreed with @phdargen. Will remove any mention of bidirectional ratings for v1 and focus entirely on server (agent) ratings.

Rationale:

• Server ratings are the primary unlock - clients rating agents builds trust in the autonomous agent ecosystem
• Client ratings are marginal value add at this stage and add protocol complexity
• Client identity in the spec exists for feedback attribution (proving who left the review), not for agents to rate clients back

Bidirectional ratings could be revisited in a future version if agent-to-agent interactions become common and client reputation becomes valuable for prioritization or pricing.

---

Q5: agentWallet fallback when no signers specified

Proposed: Yes, allow fallback to agentWallet when signers array is empty or missing. Follows ERC-8004 pattern where agentWallet defaults to owner address.

Also proposing to remove role field from signers - it's self-declared and unverifiable. Owner/delegate status should be checked on-chain.

---

Q6: Cross-chain feedback model

Proposed: Adopt @phdargen's suggestion to decouple identity from payments. Use existing ERC-8004 services pattern:

"services": [
  { "name": "agentWallet", "endpoint": "eip155:8453:0xBaseWallet..." },
  { "name": "agentWallet", "endpoint": "solana:5eykt4...:SolanaWallet..." }
]

Why cross-chain decoupling matters:

• Without it: agents need registrations on every chain they accept payments → higher costs, fragmented reputation
• With it: register once on preferred identity chain, accept payments anywhere, unified reputation

Why this aligns with ERC-8004 direction:

• ERC-8004 spec (Line 406): "an agent registered and receiving feedback on chain A can still operate and transact on other chains"
• ERC-8004 Best Practices: "You can also advertise wallets on other chains even if your agent is registered on mainnet"
• Davide Crapis (ERC-8004 author) has noted cross-chain is priority for next version

Why services pattern vs new paymentAddresses array:
Reuses existing ERC-8004 primitive without adding x402-specific fields to the registration schema. The agentWallet service entries already support CAIP-10 format for any chain.

Note: Happy to discuss if you prefer a dedicated paymentAddresses array - the functionality is the same, it's a question of schema preference.

---

Q7: Optional signing and client commitment

Re: "client can trick the server and not leave signed feedback, even if it promised to"

Proposed: Accept the asymmetry. Following @phdargen's point on removing bidirectional ratings, there's no mechanism for agents to enforce client commitment in v1 anyway - and that's fine.

Why this is acceptable:

• Agent signs every response unconditionally (blind commitment to participation)
• Agent gets paid regardless of whether feedback is submitted
• Missing feedback = neutral outcome for agent, not a loss
• Real-world parallel: customers aren't obligated to leave reviews, businesses can't punish non-reviewers

The asymmetry exists but doesn't harm agents. Positive feedback is a bonus (reputation boost), not an entitlement.

---

Does this direction make sense? Happy to push changes once aligned.

[phdargen]

Thanks for the follow up @tenequm

1. Agreed

2. No strong opinion on proofOfParticipation vs proofOfPayment.
   Ideally would also like to get some feedback on the whole feedback json structure from reputation aggregators like 8004scan, will try to reach out to them

3. OK, agree this would be a big boost for adoption.
   Also agree that facilitators are a natural fit. However, I could image that also reputation aggregators might eventually be interested in running such a service. So I think the feedbackAggregator interface should be sufficiently general and not assume that the feedbackAggregator is a facilitator. As far as I can tell this is the case in your proposal, just mentioning so we are on the same page.
   If no feedbackAggregator is specified, it is my understanding we fall back to direct client submission?
   We should also give clients the option not to use the feedbackAggregator if they prefer direct submission.

4. Agreed. To be clear, I am not opposed to adding it in a future version. Just think its a distraction for now.

5. Agreed

6. Great, I think this works especially well in combination with the feedback aggregator as clients wont need gas on identity chain. Couldn't find any guidance in the 8004 specs how to advertise wallets on other chains. Declaring wallet addresses as a services feels semantically awkward to me. I'd prefer sth like

"services": [
  {
    "name": "api",
    "endpoint": "https://api.com,
    "accepts": [
      { "network": "eip155:8453", "payTo": "0xBaseWallet..." },
      { "network": "solana:5eykt4...", "payTo": "SolanaWallet..." }
    ]
  }
]

or

  "services": [
    { "name": "api", "endpoint": "https://api.com" }
  ],
  
  "paymentAddresses": [
    { "network": "eip155:8453", "address": "0xBaseWallet..." },
    { "network": "solana:5eykt4...", "address": "SolanaWallet..." }
  ],

but open to suggestions

7. Agreed

[phdargen]

Hi @tenequm @notorious-d-e-v @BranchManager69 @ruhil6789 @MonteCrypto999 and everyone interested in the 8004 extension, we are now having one open issue and 3 PRs around this topic, its getting increasingly difficult to follow the discussion.

I'd suggest to please:

• comment on this PR instead of the issue [extension] Support ERC-8004 for payment-based reputation #931
• do not comment on Support 8004 x402 #1070 (unless its a very specific implementation detail)

Had a look at @BranchManager69's PR #1054 and think it mostly aligns with what @tenequm and I discussed above. @tenequm did you have a chance to check that?

While @tenequm PR predominantly covers the server- and client-side extension and @BranchManager69's PR focusses on the facilitator extension, they have significant overlap and imo working on 2 separate extension specs doesn't make sense.

Could we please consolidate into this PR?
If that works for you @BranchManager69, I will close out #1054

A merged spec should clearly separate:

1. server extension: declares identity + aggregator (optional)
2. client extension: submits feedback direct or via aggregator (optional)
3. feedback aggregator API interface suitable for facilitator and other external services
4. facilitator extension: optional settlement attestation and/or operating a feedback aggregator

[ruhil6789]

@phdargen thanks for the update. Aligning on a single issue makes sense.

[tenequm]

@phdargen Thanks for the detailed feedback - great to have alignment on most points.

On your refinements:

Q3 (feedbackAggregator): Agreed - the interface should be general, not assume facilitator. Will update the spec to make fallback to direct submission explicit when no aggregator is specified, and add client opt-out for direct submission preference.

Q6 (cross-chain payments): I like the paymentAddresses array approach - cleaner than overloading services. Will adopt that structure.

On consolidation: Strongly support consolidating into this PR. Happy to incorporate the facilitator extension section (settlement attestation as optional layer).

Re: #1054 - I reviewed it when it was opened. The feedbackAggregator portions align with what we discussed. My main concern with facilitatorAttestation was that taskRef already provides on-chain proof of settlement, so the attestation felt redundant. But I see the value in having it as an optional trust signal for off-chain verification scenarios. Happy to include it as optional in the consolidated spec.

Will push the spec changes by end of tomorrow addressing your Q3/Q6 refinements and adding the facilitator extension section.

[BranchManager69]

@phdargen @tenequm - Agreed. We based #1054 on the open questions here, so folding it back in keeps everything in one place.

On attestation vs taskRef - taskRef proves a payment exists on-chain. Attestation ties the feedback to a specific facilitator who processed that settlement. This creates accountability: if a facilitator's attestations are consistently tied to malicious feedback, that becomes visible and their reputation suffers. It also gives facilitators a chokepoint to add verification before issuing attestations. Doesn't prevent attacks outright, but makes them attributable and raises the cost.

Let me know if anything needs clarification.

[tenequm]

@phdargen @notorious-d-e-v @BranchManager69 @ruhil6789

Just pushed a restructure addressing the open review feedback.

What changed

1. Spec restructured into 4 parts per @phdargen's consolidation request:

1. Server extension (identity, signing, registration file)
2. Client extension (pre-payment verification, signature verification, feedback)
3. Feedback aggregator API (general-purpose interface)
4. Facilitator extension (operating a feedback aggregator)

2. Additional sections added: protocol flow overview, conventions, extension JSON schema, reviewer signature spec, feedbackHash computation (RFC 8785 JCS), pre-payment payTo verification with cross-chain support, security considerations, and key rotation guidance.

Design decisions

3. Cross-chain payment addresses: I previously mentioned adopting a paymentAddresses array, but went with agentWallet service entries in CAIP-10 format instead. This follows the ERC-8004 best practices directly and avoids introducing x402-specific fields into the registration schema. Open to revisiting if you prefer a dedicated array.

4. Facilitator attestation: The feedbackAggregator protocol from #1054 is fully integrated. I left out facilitatorAttestation from v1 because taskRef already contains the blockchain tx hash (publicly verifiable), and the proofOfParticipation trust chain already covers all three dimensions: payment (blockchain), service delivery (agent signature), and authorship (reviewer signature). Adding "this facilitator processed the payment" doesn't introduce a new trust dimension beyond what the chain already proves. The broader facilitator-as-validator concept builds toward ERC-8004's Validation Registry, which is still under active revision - I think it deserves its own focused design rather than being an optional field here. Happy to discuss.

5. Signing model: Agent signs every response unconditionally (blind commitment). Per our Q7 discussion, this accepts the asymmetry that clients may not submit feedback - agents get paid regardless, missing feedback is a neutral outcome.

6. proofOfParticipation naming: Kept this over proofOfPayment intentionally. Payment proof is already in taskRef. What x402 uniquely adds is proof that the client actually participated in the interaction - the agent signature over request+response content binds feedback to real service delivery, not just payment existence. proofOfPayment would undersell what this structure actually proves. Open to thoughts on this.

Next steps

• Ready to start on implementation using the hooks @phdargen outlined earlier (enrichSettlementResponse for server, onResourceDelivered for client when available)

[phdargen]

Thanks for the update @tenequm, will try to read through it soon

Concerning the hooks, I realized the current implementation of the enrichSettlementResponse hook would not be sufficient as it misses transport context for the signed dataHash. In particular capturing the response body is quite tricky but I have a PR with an updated hook ready here: #1101

While the enrichSettlementResponse is strictly needed for this extension to keep the core clean, the onResourceDelivered hook would be convenient and might improve devx but is not necessary. The client can just fetch the response as usual (const response = await fetchWithPayment(url, { method: "GET" })) and then process it further in utility functions imported from the extension

[BranchManager69]

@tenequm - Thanks for the detailed breakdown on the design decisions. I see the reasoning on facilitatorAttestation - you're right that taskRef proves payment and proofOfParticipation covers service delivery.

The gap I was targeting is attribution - not whether something happened, but who can be held responsible when it's abused.

Scenario: An attacker spends $1 making 20 micro-payments to Agent X, then submits 20 negative reviews. Each passes all trust checks - valid taskRef, valid agent signature, valid reviewer signature. Agent X's reputation tanks. The attacker is a pseudonymous wallet. There's no traceable party.

With facilitator attestation: those 20 reviews are tied to Facilitator F who processed the settlements. If F's attestations consistently correlate with malicious feedback patterns, that becomes visible - F's reputation suffers. F now has incentive to rate-limit suspicious patterns, add verification, or refuse attestation for sketchy behavior. The attestation creates a traceable party which raises the cost of attacks.

This is the loop @MonteCrypto999 described - facilitators with 8004 identities whose attestation history is public and auditable. The chain proves payment happened; the attestation proves who vouched for it.

Happy to defer to v2 / Validation Registry if that's the cleaner path. Just wanted to clarify the use case - it's about making the trust chain attributable, not adding redundant verification.