feat: MutualAttestationHook — Airbnb-style bilateral reviews for ERC-8183

[JhiNResH]

MutualAttestationHook

Inspired by Airbnb's mutual review system — both client and provider attest each other after job completion, building two-sided reputation.

Problem

Current hooks only track one side — did the provider deliver? But bad clients exist too: vague specs, unfair disputes, slow communication. One-sided reviews create power imbalances in agent marketplaces.

Solution

After job completion (or rejection), both parties submit a review (1-5 stars + comment). Each review creates an immutable EAS attestation. Both sides build reputation. Both sides are accountable.

Job completes/rejects → 7-day review window opens
  ├── Client reviews provider: "Was the work good?" (1-5 stars + comment)
  └── Provider reviews client: "Was the client fair?" (1-5 stars + comment)

Security (Audited)

Cyfrin + Trail of Bits + Slither methodology. All findings fixed:

Finding	Severity	Fix
No access control on reviews	🔴 Critical	msg.sender verified via ACP getJob() — no spoofing
Reentrancy on EAS call	🟡 Medium	ReentrancyGuard on both review functions
reviewWindow not immutable	🟢 Low	Changed to immutable
Rejected jobs cannot be reviewed	🟢 Low	Added _postReject() override
Pragma mismatch	ℹ️ Info	Unified to ^0.8.20
jobId type inconsistency	ℹ️ Info	Unified to uint256

Features

• Bilateral EAS attestations (one per party per job)
• Access control: only actual job participants can review (verified on-chain)
• 1-5 star scoring with review comments
• Review window enforcement (configurable, default 7 days)
• Rejected jobs CAN be reviewed — both parties deserve a voice
• Double-review prevention
• MutualReviewComplete event when both reviews submitted
• ReentrancyGuard protection
• Error names follow ContractName__ prefix convention (Cyfrin standard)

Tests

31 tests (up from 21) including:

• Access control (attacker, wrong role, fuzz random callers)
• Basic review flow (client, provider, mutual)
• Score validation (boundary + fuzz)
• Double-review prevention
• Review window enforcement
• Rejected job reviews
• EAS attestation data verification
• Event emission
• Multi-job independence
• Immutability checks

Why This Matters

The Airbnb insight: mutual trust is what makes strangers transact safely. In agent commerce:

• Providers see "this client has 2/5 stars" → avoid bad clients
• Clients see "this provider has 4.8/5 stars" → choose confidently
• Bad actors on EITHER side get naturally gated out

Files

• contracts/hooks/MutualAttestationHook.sol (249 lines)

Extends BaseACPHook via _postComplete + _postReject. Compatible with MaiatRouterHook plugin chain.

[psmiratisu]

Love this - bilateral reputation is essential for agent commerce.

Some questions

1. Verify reviewer is job participant - Does _beforeComplete check msg.sender == job.client || msg.sender == job.provider? Can't see this in diff.

2. One review per party - See hasReviewed mapping, good.

3. Storage growth - For high-volume agents (1000s of jobs), reviews accumulate forever. Consider: archive strategy or EAS-only for old reviews? Should we store that also? maybe can redirect back to ERC 8004 reviews?

4. No review disputes - Intentional? Airbnb allows "respond to review" but not deletion. Your design matches this?

Nit: 7-day window is in constructor but not documented as configurable. Consider adding to natspec.

[JhiNResH]

Updated — removed vendor-specific references. Also working on addressing the review comments from the earlier feedback (participant auth check, storage growth, review disputes, natspec for 7-day window).

[JhiNResH]

Thanks for the thorough review! Addressing each point:

1. Verify reviewer is job participant ✅ Already enforced:

• reviewClient() L175: if (msg.sender != jobClient[jobId]) revert MutualAttestationHook__NotJobParticipant()
• reviewProvider() L205: if (msg.sender != jobProvider[jobId]) revert MutualAttestationHook__NotJobParticipant()

Both functions check msg.sender against stored job participants from _afterAction capture. Wasn't visible in the diff because the guard is in the body rather than a modifier.

2. One review per party ✅ Confirmed — hasReviewed mapping prevents double reviews.

3. Storage growth — Intentional tradeoff for this version. On-chain reviews need to be queryable by other contracts (e.g., trust hooks that read historical reviews). EAS attestations are complementary — they provide cross-protocol portability, but the on-chain mapping enables composability within the ERC-8183 ecosystem. For v2, we could add an archival mechanism that migrates old reviews to EAS-only after N days. Open to suggestions — redirecting to ERC-8004 reviews is worth exploring.

4. No review disputes — Yes, intentional. Same model as Airbnb: reviews are immutable once posted. Both parties have the full review window to submit (or not). Adding a dispute/response mechanism would increase complexity and create griefing vectors. Could add a "response to review" feature in a future PR if there's demand.

Nit (7-day window): Good catch — will add natspec. The reviewWindow is configurable via constructor param (L137: reviewWindow_ == 0 ? 7 days : reviewWindow_).

[ariessa]

Hi @JhiNResH,

1. This PR is outdated. Can you pull current code from main branch into this PR?
2. This hook doesn't support MultiHookRouter. If MutualAttestationHook supports MultiHookRouter, it can be used with n number of hooks where n is the max hooks per job. Can you make the hook support MultiHookRouter?
3. This PR contains more than just a hook contract, it also has an interface file named IAttestationService.sol. Can you move the interface inside the hook contract instead?

[JhiNResH]

Updated PR #14 in commit f200181.\n\nAddressed the requested changes:\n1. Pulled current upstream main into this branch.\n2. Added MultiHookRouter support by implementing IERC8183HookMetadata; requiredSelectors() now declares complete + reject.\n3. Moved IAttestationService into MutualAttestationHook.sol as an inline minimal interface.\n\nThe PR diff is now a single file: contracts/hooks/MutualAttestationHook.sol.

[ariessa]

Closing this PR.

The trigger-time logic is two cache writes (jobCompletedAt, client/provider). No gating, no transformation, no fund movement. claimRefund is not hookable, so expired jobs (the worst-actor cohort) silently never get a review channel anyway.

A standalone reader achieves the same result: pull participants and status from ERC8183.getJob() at review time, and stamp the completion timestamp on the first review submission.

Lastly, the NatSpec carries vendor names that violate PR Rules in CONTRIBUTING.md.