Address escrow scheme spec review feedback

[A1igator]

Summary

Addresses reviewer feedback on the escrow scheme spec and implementation.

Spec changes

• Network-agnostic scheme_escrow.md: Removed EVM-specific references (Commerce Payments, ERC-3009, Solidity function names). EVM details live exclusively in scheme_escrow_evm.md
• Settlement Response: Defined PAYMENT-RESPONSE contents — includes full paymentInfo so clients can track payment state without retaining client-side state
• Charge path clarity: Explains how refunds work (operator initiates, which may be a contract or authorized account) and the tradeoff vs authorize
• Verification updates: Strict amount equality (=== not >=), authorization.to === tokenCollector check, settlement simulation step

Implementation changes

• Settlement simulation: Verify now simulates operator.authorize/charge via eth_call before spending gas — catches balance issues, consumed nonces, domain mismatches, and contract errors
• Diagnostic fallback: On simulation failure, runs balanceOf check for actionable error messages
• Shared helper: Extracted buildPaymentInfo() used by both verify and settle

Test plan

• All 51 tests pass (pnpm test)
• Build succeeds (pnpm build)
• Prettier passes (pnpm format:check)

🤖 Generated with Claude Code

[vraspar]

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

Notes (below the review threshold, but worth considering):

• Simulation failure is a hard reject — The old balance check was non-fatal (skipped on RPC failure, returned isValid: true). The new simulation catch block always returns { isValid: false, invalidReason: 'simulation_failed' }, meaning transient RPC errors will reject valid payments with no retry.

  x402r-scheme/packages/evm/src/escrow/facilitator/scheme.ts

  Lines 220 to 247 in 7a58eeb

  	})
  	} catch {
  	// Simulation failed — check balance for a more actionable error
  	try {
  	const balance = (await this.signer.readContract({
  	address: requirements.asset as `0x${string}`,
  	abi: ERC20_BALANCE_OF_ABI,
  	functionName: 'balanceOf',
  	args: [payer],
  	})) as bigint
  	if (balance < BigInt(requirements.amount)) {
  	return {
  	isValid: false,
  	invalidReason: 'insufficient_balance',
  	payer,
  	}
  	}
  	} catch {
  	// Balance check failed too
  	}
  	return {
  	isValid: false,
  	invalidReason: 'simulation_failed',
  	payer,
  	}
  	}

• Spec step 5 inconsistency — Settlement Logic step 5 says "Return result: Transaction hash, network, and payer address" but the new Settlement Response section defines paymentInfo as part of the response. Step 5 should be updated to match.

  x402r-scheme/specs/schemes/escrow/scheme_escrow_evm.md

  Lines 154 to 156 in 7a58eeb

  	4. **Wait for receipt**: Confirm transaction success with 60s timeout
  	5. **Return result**: Transaction hash, network, and payer address

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[A1igator]

Thanks for the review! Step 5 is fixed in 92d5b88.

Re: simulation hard reject — this is intentional. Both pending simulation PRs for the exact scheme also hard reject on any simulation failure (including transient RPC errors). The reasoning: if the RPC is down for simulation, the facilitator also can't submit the settlement transaction, so accepting the payment would just defer the failure. A false-negative (rejecting a valid payment) is safer than a false-positive (accepting one that reverts on-chain and wastes gas).

[vraspar]

Looks good to me, but make sure wording is what you expecting. The md file might have unnecessary information

[A1igator]

Acknowledged — the escrow abstract spec is longer than exact's, but escrow has more moving parts (two settlement paths, expiry tiers, fee system, post-settlement actions). I think the current content is justified. Happy to trim if you spot anything specific that feels redundant though.