feat: WalletStateHook — condition-based wallet-state gating for _preFund#33
Open
douglasborthwick-crypto wants to merge 4 commits intoerc-8183:mainfrom
Open
Conversation
Adds a minimal ERC-8183 hook that gates the fund stage on a condition-based wallet-state verifier. Complements existing score-based gating (TrustGateHook, erc-8183#9/erc-8183#32) and content-based verification (ReasoningVerifierHook, erc-8183#31) with a third shape: "does this wallet satisfy a named condition set right now?" - contracts/interfaces/IWalletStateVerifier.sol Minimal (bool verified, uint256 validUntil) interface keyed on (wallet, conditionsHash). Hooks stay stateless views. - contracts/hooks/WalletStateHook.sol Inherits BaseERC8183Hook + IERC8183HookMetadata. Immutable verifier + conditionsHash (deploy one hook per distinct condition set, mirrors the minConfidence immutable pattern in ReasoningVerifierHook). Overrides _preFund only — verifier.checkWalletState(caller, conditionsHash) → pass/fail + freshness, reverts otherwise. - contracts/examples/InsumerWalletStateVerifier.sol Reference IWalletStateVerifier implementation. Relayer-push model with optional RIP-7212 P256VERIFY precompile verification of off-chain ECDSA P-256 (ES256) attestation signatures. Works on Base, Arbitrum, Optimism, Polygon, Scroll, ZKsync, Celo — standard ERC-8183 L2 footprint. - test/WalletStateHook.t.sol 21 tests, all passing. Covers constructor guards, _preFund happy path, not-verified revert, expired-attestation revert, validUntil boundary, selector isolation, ERC-165 interface support, verifier relayer auth, and signature-mode flag. Stacked on top of erc-8183#30 (IACPHook → IERC8183Hook rename). Targets main; will rebase cleanly once erc-8183#30 merges.
…w, credentials Follow-ups per CONTRIBUTING.md on PR erc-8183#33: - WalletStateHook.sol: expand NatSpec to match BiddingHook/FundTransferHook style with USE CASE / FLOW / TRUST MODEL sections + Profile A label. - InsumerWalletStateVerifier.sol: add credentials block covering both paths — developers via POST /v1/keys/create (email-based, free tier) and agents via POST /v1/keys/buy (wallet-based, no email, USDC/BTC payment proves identity). - README.md: add WalletStateHook row to the Hook Examples table, Profile A. No code changes — docs only. forge build clean, forge test 21/21 pass.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a minimal ERC-8183 hook that gates the fund stage on a condition-based wallet-state verifier. Complements existing score-based gating (
TrustGateHook, #9/#32) and content-based verification (ReasoningVerifierHook, #31) with a third shape: does this wallet satisfy a named condition set right now?TrustGateHook) — "reputation ≥ N"ReasoningVerifierHook) — "output verified, confidence ≥ N"WalletStateHook, this PR) — "wallet passes condition set X (e.g. USDC ≥ 1000 on Base, KYC attested, NFT held)"What's added
contracts/interfaces/IWalletStateVerifier.sol(bool verified, uint256 validUntil)interface keyed on(wallet, conditionsHash). Hooks remain stateless views.contracts/hooks/WalletStateHook.solBaseERC8183Hook+IERC8183HookMetadata. Immutableverifier+conditionsHash(deploy one hook per distinct set, mirrors theminConfidencepattern in #31). Overrides_preFundonly.contracts/examples/InsumerWalletStateVerifier.solIWalletStateVerifierimplementation. Relayer-push model with optional RIP-7212 P256VERIFY precompile verification of off-chain ECDSA P-256 (ES256) attestation signatures.test/WalletStateHook.t.solDesign intent
Keep the core hook small, generic, and aligned with the current hook stack:
BaseERC8183Hook-native_preFundonlycontracts/examples/Gate stage
_preFund— gates the client wallet before escrow forms. ParallelsTrustGateHook's_preFundstage (score threshold) andReasoningVerifierHook's_preSubmitstage (deliverable hash), so readers see a clean three-way contrast at distinct lifecycle points.Verification model
The example verifier supports two modes:
r,s,messageHash), which are verified via the RIP-7212 precompile before the attestation is stored. Zero trust in the relayer.pubKeyX = pubKeyY = 0, signature verification is skipped and the relayer is trusted. Useful for testnets or deployments where off-chain signature verification is performed by an independent auditor.RIP-7212 is live on Base, Optimism, Arbitrum, Polygon, Scroll, ZKsync, Celo — the standard ERC-8183 L2 footprint.
Verification
forge build✅ (only pre-existing lint notes matching current codebase style)forge test --match-path test/WalletStateHook.t.sol✅ 21/21 passDependency on #30
This branch is stacked on #30 (IACPHook → IERC8183Hook rename) so the new files compile against the post-rename base. Will rebase cleanly once #30 merges.