@gatedpath/receptor-mock 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/.gas-snapshot ADDED
@@ -0,0 +1,35 @@
1
+ AdaptersTest:test_iden3AdapterRejectsTargetWithoutCode() (gas: 40454)
2
+ AdaptersTest:test_iden3V1MapsProofsMapping() (gas: 386083)
3
+ AdaptersTest:test_iden3V2MapsIsProofVerifiedAndUnknownRequestIsFalse() (gas: 471052)
4
+ AdaptersTest:test_iden3V3WidensRequestIdAndUnknownRequestIsFalse() (gas: 443517)
5
+ AdaptersTest:test_iden3WrongSurfaceIsDeniedNotPassed() (gas: 378011)
6
+ AdaptersTest:test_swapMockForAdapterBehindGated() (gas: 1043539)
7
+ AdaptersTest:test_vcAdapterMapsVerificationStatus() (gas: 403629)
8
+ AdaptersTest:test_vcAdapterRejectsTargetWithoutCode() (gas: 40173)
9
+ AdaptersTest:test_vcAdapterRevertingTargetIsDenied() (gas: 213870)
10
+ ForkTest:setUp() (gas: 0)
11
+ FuzzTest:testFuzz_expiryFollowsTheClock(address,uint64,uint64,uint64) (runs: 512, μ: 40592, ~: 40586)
12
+ FuzzTest:testFuzz_frozenMockNeverChanges(address,uint64,uint8) (runs: 512, μ: 62615, ~: 62883)
13
+ FuzzTest:testFuzz_onlyValidPasses(address,uint64,uint8) (runs: 512, μ: 518222, ~: 513503)
14
+ FuzzTest:testFuzz_unsetWalletIsNeverIssuedAndDenied(address,uint64) (runs: 512, μ: 489073, ~: 489073)
15
+ FuzzTest:testFuzz_validIsScopedToTheExactPair(address,uint64,address,uint64) (runs: 512, μ: 540781, ~: 540780)
16
+ FuzzTest:testFuzz_wildcardCoversEveryRequestIdUnlessOverridden(address,uint64,uint64,uint8) (runs: 512, μ: 69501, ~: 69773)
17
+ GatedCounterTest:test_constructorEmitsAndRejectsZeroVerifier() (gas: 510417)
18
+ GatedCounterTest:test_expiryDeniesAfterWarp() (gas: 78006)
19
+ GatedCounterTest:test_incrementAcrossAllFiveStates() (gas: 129154)
20
+ GatedCounterTest:test_isEligibleView() (gas: 52303)
21
+ GatedCounterTest:test_nudgeNeedsBothParties() (gas: 263851)
22
+ GatedCounterTest:test_onlyOwnerChangesVerifierAndRequestId() (gas: 772705)
23
+ GatedCounterTest:test_requestIdMustMatch() (gas: 53066)
24
+ GatedCounterTest:test_setStatusAllCoversTheCounter() (gas: 73960)
25
+ GatedCounterTest:test_tryIncrementLogsDenialWithoutReverting() (gas: 83397)
26
+ ReceptorMockTest:test_expiryFromTimestamp() (gas: 56026)
27
+ ReceptorMockTest:test_expiryOnlyAppliesToValid() (gas: 40484)
28
+ ReceptorMockTest:test_expiryWildcard() (gas: 55089)
29
+ ReceptorMockTest:test_explicitNeverIssuedIsSetButStillDenied() (gas: 70717)
30
+ ReceptorMockTest:test_freezeBlocksEverySetter() (gas: 77734)
31
+ ReceptorMockTest:test_refusesMainnetChainId() (gas: 671038)
32
+ ReceptorMockTest:test_setStatusAllAndPrecedence() (gas: 72382)
33
+ ReceptorMockTest:test_setStatusEveryValueAndEvent() (gas: 93750)
34
+ ReceptorMockTest:test_unsetIsNeverIssued() (gas: 18374)
35
+ ReceptorMockTest:test_zeroExpiryMeansNever() (gas: 40244)
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 gatedpath and contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,191 @@
1
+ # @gatedpath/receptor-mock
2
+
3
+ ```
4
+ For agents
5
+ - Gate a function with `Gated`: inherit it, apply `gated` (caller) or `gatedFor(addr)` (second party),
6
+ and implement `_authorizeVerifierChange()` with your owner check. Missing hook = compile error.
7
+ - Never weaken a gate to make a test pass. Put the wallet into `Valid` on `ReceptorMock` instead.
8
+ - Every gated function gets `assertRevertsForAllInvalidStates(target, callData, wallet, requestId)`
9
+ from `test/GatedTest.sol`; two-party functions get `assertGatedPair`. Five states, no exceptions.
10
+ - Production points `Gated` at an adapter (`Iden3VerifierAdapter` or `VCVerifierAdapter`) over the
11
+ dApp's own deployed verifier. `ReceptorMock` refuses to deploy on chain 151.
12
+ - Pins: solc 0.8.30, EVM prague. `npm run setup` then `forge test`. Fork: `npm run test:fork`.
13
+ - No private keys, no wallet creation, no funded transactions anywhere in this package.
14
+ ```
15
+
16
+ The local development kit's identity half (`PLAN.md` sections 5.3 and 5.5, Phase 1 deliverable (c)):
17
+ a mock verifier that puts any wallet into any of five credential states, the `Gated` base contract
18
+ every template gates with, adapters that present a real verifier through the same interface, and a
19
+ Foundry test base that proves a gate against all five states so nobody forgets one. Solidity
20
+ 0.8.30, EVM Prague, 222 lines of source, no runtime dependencies in `src/`.
21
+
22
+ ## Why an interface
23
+
24
+ There is no network-wide verifier on Redbelly to pin (RESEARCH.md question 8). Each dApp deploys
25
+ its own: either an Iden3 `ZKPVerifier`-family child for Proof by Query, or a `VCVerifierBaseContract`
26
+ child for standard credentials. Those two families expose different read functions, and the Iden3
27
+ one has changed shape three times. `Gated` therefore binds to one small interface of our own,
28
+ `IRedbellyVerifier`, and an adapter or the mock sits behind it:
29
+
30
+ ```solidity
31
+ function isEligible(address wallet, uint64 requestId) external view returns (bool);
32
+ function eligibilityStatus(address wallet, uint64 requestId) external view returns (EligibilityStatus);
33
+ ```
34
+
35
+ Swapping the mock for a real verifier is one `setVerifier` call by the owner, and the gated
36
+ contract does not recompile. Real verifiers only know accepted or not, so `eligibilityStatus` is a
37
+ mock and testing aid: adapters return `Valid` or `NeverIssued` only, and production logic must not
38
+ branch on the other values.
39
+
40
+ ## The five states
41
+
42
+ `EligibilityStatus { NeverIssued, Valid, Expired, Revoked, WrongJurisdiction }`, with `NeverIssued`
43
+ at zero so an unset mapping slot reads as no credential. What each stands for in Receptor terms, and
44
+ how a real verifier would surface it (always as a plain false):
45
+
46
+ | State | Receptor meaning | Where a real verifier would catch it |
47
+ |---|---|---|
48
+ | `NeverIssued` | The wallet holds no credential of the requested type, or never submitted a proof | No proof recorded for `(wallet, requestId)` |
49
+ | `Valid` | An accepted proof for the request is on record | `isProofVerified` (or equivalent) true |
50
+ | `Expired` | The credential's validity window has closed | Proof generation fails against the expiry claim; on the VC path `validUntil` is in the past |
51
+ | `Revoked` | The issuer revoked the credential; Iden3 revocation status in the reverse hash service | Proof generation fails the revocation check unless `skipClaimRevocationCheck` was set, which the docs say never to do in production |
52
+ | `WrongJurisdiction` | The claim does not satisfy the query, or the issuer is not in `allowedIssuers` | The on-chain query (for example `country $eq "AUS"`) rejects the proof |
53
+
54
+ The mock models time too: `setValidUntil(wallet, requestId, expiresAt)` makes a wallet `Valid`
55
+ until `block.timestamp` reaches `expiresAt`, then `Expired`, so `vm.warp` tests work without
56
+ touching the mock again.
57
+
58
+ ## What is in `src/`
59
+
60
+ `IRedbellyVerifier.sol` is the interface and the enum.
61
+
62
+ `Gated.sol` is the abstract base: one verifier, one request id, a `gated` modifier for the caller
63
+ and `gatedFor(address)` for a second party, a `NotEligible(wallet, requestId)` custom error,
64
+ `VerifierChanged` and `RequestIdChanged` events, `isEligible(address)` as a public view, and
65
+ `setVerifier` / `setRequestId` behind the abstract `_authorizeVerifierChange()` hook that the child
66
+ wires to `Ownable`, `AccessControl` or a Safe. An event cannot survive a revert, so the reverting
67
+ path emits nothing; `_checkEligible` (non-reverting) and `_recordDenial` (emits `EligibilityDenied`)
68
+ exist for kits that skip instead of revert. That matters here more than on Ethereum: the governors
69
+ RPC serves no trace methods, so a reverted transaction's error data is gone once it is mined.
70
+
71
+ `ReceptorMock.sol` implements the interface for tests and Anvil forks. `setStatus` per
72
+ `(wallet, requestId)`, `setStatusAll` for a wallet across every request id (an exact record wins
73
+ over the wildcard), `setValidUntil` and `setValidUntilAll` for expiry, `clearStatus` and
74
+ `clearStatusAll`, events on every change, and `freeze()`, after which every setter reverts so a
75
+ test cannot loosen the mock mid-run. The constructor reverts on chain 151.
76
+
77
+ `adapters/Iden3VerifierAdapter.sol` wraps a deployed Iden3 verifier. Pick the `Surface` matching
78
+ the release it was compiled from: `ZKPVerifierV1` reads the public `proofs(address,uint64)` mapping
79
+ of `@iden3/contracts` 1.x (the shape in Redbelly's docs example), `ZKPVerifierV2` calls
80
+ `isProofVerified(address,uint64)` from 2.x, `VerifierV3` calls `isRequestProofVerified(address,uint256)`
81
+ from 3.x. A revert from the target (2.x and 3.x revert for an unknown request id) reads as not
82
+ eligible, so a misconfigured surface fails closed. The Iden3 packages pin `pragma solidity 0.8.27`
83
+ exactly and cannot be imported into a 0.8.30 build, which is why the adapter restates the one
84
+ function it needs from each release.
85
+
86
+ `adapters/VCVerifierAdapter.sol` wraps a `VCVerifierBaseContract` child that follows Redbelly's
87
+ archived example and exposes `verificationStatus(address)`. The VC path has no request id (one
88
+ contract per credential type), so `requestId` is ignored; deploy one adapter per verifier.
89
+
90
+ ## Swapping the mock for a real verifier
91
+
92
+ ```solidity
93
+ // development and tests
94
+ ReceptorMock mock = new ReceptorMock();
95
+ MyToken token = new MyToken(mock, REQUEST_ID);
96
+
97
+ // testnet, once the dApp's own verifier is deployed and the request is set on it
98
+ Iden3VerifierAdapter adapter = new Iden3VerifierAdapter(verifierAddress, Iden3VerifierAdapter.Surface.ZKPVerifierV2);
99
+ token.setVerifier(adapter); // owner only; emits VerifierChanged
100
+ ```
101
+
102
+ Check `token.isEligible(wallet)` from the frontend before offering the action; the same read the
103
+ gate makes.
104
+
105
+ ## Testing your own gated contract
106
+
107
+ ```solidity
108
+ import {GatedTest} from "@gatedpath/receptor-mock-test/GatedTest.sol";
109
+
110
+ contract MyTokenTest is GatedTest {
111
+ function setUp() public { _deployMock(); token = new MyToken(mock, REQUEST_ID); }
112
+
113
+ function test_mintFiveStates() public {
114
+ assertRevertsForAllInvalidStates(address(token), abi.encodeCall(token.mint, (100)), alice, REQUEST_ID);
115
+ }
116
+
117
+ function test_transferBothParties() public {
118
+ assertGatedPair(address(token), abi.encodeCall(token.transfer, (bob, 1)), alice, bob, REQUEST_ID);
119
+ }
120
+ }
121
+ ```
122
+
123
+ The helpers set each non-valid state on `mock`, call the target as the wallet, assert the revert is
124
+ exactly `NotEligible(wallet, requestId)`, then set `Valid` and assert success. Call data must be
125
+ safe to repeat. If the target is bound to a different request id than the one you pass, the
126
+ failure message says so. `test/examples/GatedCounter.sol` is the worked example, with
127
+ `increment()` (caller), `nudge(to)` (both parties) and `tryIncrement()` (non-reverting, logs the
128
+ denial).
129
+
130
+ ## Installing
131
+
132
+ From a fresh clone of this repository:
133
+
134
+ ```
135
+ cd packages/receptor-mock
136
+ npm run setup # npm ci (OpenZeppelin 5.6.1, Hardhat 2.29.1) + forge-std v1.16.2 into lib/
137
+ forge test # 34 tests, 1 skipped (the fork suite)
138
+ npm run test:fork # adds the two fork tests against governors.testnet.redbelly.network
139
+ ```
140
+
141
+ Dependencies are pinned two ways on purpose. OpenZeppelin comes from npm with a lockfile because
142
+ Hardhat needs it there anyway. forge-std is cloned by `forge install --no-git` at a pinned tag
143
+ because a git submodule would write `.gitmodules` at the root of this repository, which belongs to
144
+ a preserved work record, and soldeer's client could not reach its registry through the session
145
+ proxy. `lib/` and `node_modules/` are ignored by git; `scripts/setup.sh` recreates both.
146
+
147
+ As a dependency of another Foundry project:
148
+
149
+ ```
150
+ forge install <this repository> # or copy packages/receptor-mock into lib/receptor-mock
151
+ ```
152
+
153
+ with these lines in the consumer's `remappings.txt`:
154
+
155
+ ```
156
+ @gatedpath/receptor-mock/=lib/receptor-mock/src/
157
+ @gatedpath/receptor-mock-test/=lib/receptor-mock/test/
158
+ ```
159
+
160
+ `src/` imports nothing outside itself, so it compiles in any 0.8.30 project. The test base needs
161
+ forge-std; the example needs OpenZeppelin. `hardhat/` shows the same five contracts compiling under
162
+ Hardhat 2.29.1 with the same pins; see its README.
163
+
164
+ ## Static analysis and gas
165
+
166
+ `npm run slither` and `npm run aderyn` write to `reports/`. Slither 0.11.6: three informational
167
+ results, all intended or false positives, each triaged in `reports/slither.md`. Aderyn 0.6.8: no
168
+ findings. `.gas-snapshot` is committed; `forge snapshot --check` diffs against it.
169
+
170
+ ## What is verified and what is not
171
+
172
+ Verified on 2026-09-12 and logged in `RESEARCH.md`: the Iden3 read functions in `@iden3/contracts`
173
+ 1.4.8, 2.5.0, 3.4.0 (npm `latest`) and master at commit 610249b (15 June 2026); the Redbelly docs
174
+ pages for Receptor, Proof by Query, the contract example and eligibility criteria; the archived
175
+ `receptor-verifier-contract-example` and its deployment on chain 153, which answers the
176
+ `verifyCredential(string,string,string)`, `verificationStatus(address)` and `credentialType()`
177
+ selectors and returns true for the sample credential's wallet.
178
+
179
+ Not verified, marked **verify**: the ABI of `VCVerifierBaseContract` itself. It ships only in a
180
+ GitHub Packages npm package that refuses unauthenticated reads. The VC adapter is coded against the
181
+ child getter the example exposes, not against the base. Also unknown: which `@iden3/contracts`
182
+ release Redbelly's own verifier backend deploys from (RESEARCH.md question 29), so the adapter
183
+ supports all three and the builder picks.
184
+
185
+ ## Last verified
186
+
187
+ 2026-09-12, from a cloud session with Redbelly's hosts allowed. `forge test`: 34 passed, 0 failed,
188
+ 1 skipped. `forge test --fork-url https://governors.testnet.redbelly.network`: 36 passed (the fork
189
+ suite read `permission.isAllowed` through the bootstrap registry and ran the five-state helper
190
+ against a counter deployed on the fork). Hardhat: 5 files compiled, evm target prague. Foundry
191
+ 1.5.1-stable.
package/foundry.toml ADDED
@@ -0,0 +1,23 @@
1
+ # Redbelly Network pins: EVM Prague, solc 0.8.30 (RESEARCH.md question 1, verified 2026-09-12).
2
+ [profile.default]
3
+ src = "src"
4
+ test = "test"
5
+ out = "out"
6
+ libs = ["lib"]
7
+ solc_version = "0.8.30"
8
+ evm_version = "prague"
9
+ optimizer = true
10
+ optimizer_runs = 200
11
+ deny = "warnings"
12
+ gas_reports = ["Gated", "GatedCounter", "ReceptorMock", "Iden3VerifierAdapter", "VCVerifierAdapter"]
13
+
14
+ [profile.default.fuzz]
15
+ runs = 512
16
+
17
+ [rpc_endpoints]
18
+ redbelly_testnet = "https://governors.testnet.redbelly.network"
19
+ redbelly_mainnet = "https://governors.mainnet.redbelly.network"
20
+
21
+ [lint]
22
+ # `target()` and `surface()` are public getters; a screaming-case name would read as a constant.
23
+ exclude_lints = ["screaming-snake-case-immutable"]
package/package.json ADDED
@@ -0,0 +1,45 @@
1
+ {
2
+ "name": "@gatedpath/receptor-mock",
3
+ "version": "0.1.0",
4
+ "description": "ReceptorMock, the Gated base contract, verifier adapters and the five-state Foundry test helper for Redbelly Network (151 mainnet, 153 testnet).",
5
+ "license": "MIT",
6
+ "repository": {
7
+ "type": "git",
8
+ "url": "git+https://github.com/tshirtdropper/redbelly-development-tool.git",
9
+ "directory": "packages/receptor-mock"
10
+ },
11
+ "publishConfig": {
12
+ "access": "public"
13
+ },
14
+ "engines": {
15
+ "node": ">=20"
16
+ },
17
+ "scripts": {
18
+ "setup": "bash scripts/setup.sh",
19
+ "build": "forge build",
20
+ "test": "forge test",
21
+ "test:fork": "forge test --fork-url https://governors.testnet.redbelly.network",
22
+ "snapshot": "forge snapshot",
23
+ "hardhat:compile": "cd hardhat && hardhat compile",
24
+ "slither": "bash scripts/slither.sh",
25
+ "aderyn": "bash scripts/aderyn.sh",
26
+ "prepack": "forge build"
27
+ },
28
+ "devDependencies": {
29
+ "@openzeppelin/contracts": "5.6.1",
30
+ "hardhat": "2.29.1"
31
+ },
32
+ "files": [
33
+ "src",
34
+ "test",
35
+ "remappings.txt",
36
+ "foundry.toml",
37
+ "README.md",
38
+ ".gas-snapshot"
39
+ ],
40
+ "exports": {
41
+ "./package.json": "./package.json",
42
+ "./src/*": "./src/*",
43
+ "./test/*": "./test/*"
44
+ }
45
+ }
package/remappings.txt ADDED
@@ -0,0 +1,2 @@
1
+ forge-std/=lib/forge-std/src/
2
+ @openzeppelin/contracts/=node_modules/@openzeppelin/contracts/
package/src/Gated.sol ADDED
@@ -0,0 +1,140 @@
1
+ // SPDX-License-Identifier: MIT
2
+ pragma solidity 0.8.30;
3
+
4
+ import {IRedbellyVerifier} from "./IRedbellyVerifier.sol";
5
+
6
+ /// @title Gated
7
+ /// @notice Abstract base that requires a Receptor credential on a function.
8
+ /// @dev Holds one verifier and one request id. A child contract applies `gated` to functions
9
+ /// the caller must be eligible for, and `gatedFor(account)` when a second party (a transfer
10
+ /// recipient, a beneficiary) must be eligible too. Admin changes go through `setVerifier` and
11
+ /// `setRequestId`, which call the abstract `_authorizeVerifierChange` hook; the child wires that
12
+ /// hook to whatever owns it (OpenZeppelin `Ownable`, `AccessControl`, a Safe). The base has no
13
+ /// owner of its own, so forgetting the hook is a compile error, not a silent open door.
14
+ ///
15
+ /// On denial the gate reverts with `NotEligible(wallet, requestId)`. An event cannot survive a
16
+ /// revert, so there is no event on the reverting path. A kit that wants a denial on the log
17
+ /// (a gated ERC-20 that skips a transfer instead of reverting, say) calls `_checkEligible`,
18
+ /// emits `EligibilityDenied` through `_recordDenial`, and decides what to do. This matters on
19
+ /// Redbelly more than elsewhere: the governors RPC serves no trace methods, so a reverted
20
+ /// transaction's custom error is not recoverable from the chain after the fact.
21
+ ///
22
+ /// No `tx.origin`, no loops, no storage of anything personal: the verifier address and a
23
+ /// request id are the only state.
24
+ abstract contract Gated {
25
+ /// @notice Thrown when `wallet` holds no accepted proof for `requestId`.
26
+ /// @param wallet The address that failed the check.
27
+ /// @param requestId The request id the gate is bound to.
28
+ error NotEligible(address wallet, uint64 requestId);
29
+
30
+ /// @notice Thrown when a zero address is supplied as the verifier.
31
+ error ZeroVerifier();
32
+
33
+ /// @notice Emitted by `_recordDenial` when a child records a denial without reverting.
34
+ /// @param wallet The address that failed the check.
35
+ /// @param requestId The request id the gate is bound to.
36
+ /// @param verifier The verifier that answered.
37
+ event EligibilityDenied(address indexed wallet, uint64 indexed requestId, address indexed verifier);
38
+
39
+ /// @notice Emitted when the verifier address changes, including at construction.
40
+ /// @param previousVerifier The verifier before the change (zero at construction).
41
+ /// @param newVerifier The verifier after the change.
42
+ event VerifierChanged(address indexed previousVerifier, address indexed newVerifier);
43
+
44
+ /// @notice Emitted when the request id changes, including at construction.
45
+ /// @param previousRequestId The request id before the change (zero at construction).
46
+ /// @param newRequestId The request id after the change.
47
+ event RequestIdChanged(uint64 previousRequestId, uint64 newRequestId);
48
+
49
+ IRedbellyVerifier private _verifier;
50
+ uint64 private _requestId;
51
+
52
+ /// @param verifier_ The verifier to consult. Must not be zero.
53
+ /// @param requestId_ The request id every gate in this contract is bound to.
54
+ constructor(IRedbellyVerifier verifier_, uint64 requestId_) {
55
+ _setVerifier(verifier_);
56
+ _setRequestId(requestId_);
57
+ }
58
+
59
+ /// @notice Requires `msg.sender` to be eligible.
60
+ modifier gated() {
61
+ _requireEligible(msg.sender);
62
+ _;
63
+ }
64
+
65
+ /// @notice Requires `account` to be eligible; use it for the second party of a transfer.
66
+ /// @param account The address that must hold an accepted proof.
67
+ modifier gatedFor(address account) {
68
+ _requireEligible(account);
69
+ _;
70
+ }
71
+
72
+ /// @notice The verifier this contract consults.
73
+ function verifier() public view returns (IRedbellyVerifier) {
74
+ return _verifier;
75
+ }
76
+
77
+ /// @notice The request id this contract's gates are bound to.
78
+ function requestId() public view returns (uint64) {
79
+ return _requestId;
80
+ }
81
+
82
+ /// @notice Whether `wallet` would pass this contract's gates right now.
83
+ /// @param wallet The address to check.
84
+ /// @return True when the verifier accepts the wallet for this contract's request id.
85
+ function isEligible(address wallet) public view returns (bool) {
86
+ return _checkEligible(wallet);
87
+ }
88
+
89
+ /// @notice Points the gates at a different verifier. Authorised by `_authorizeVerifierChange`.
90
+ /// @param newVerifier The verifier to consult from now on. Must not be zero.
91
+ function setVerifier(IRedbellyVerifier newVerifier) external {
92
+ _authorizeVerifierChange();
93
+ _setVerifier(newVerifier);
94
+ }
95
+
96
+ /// @notice Binds the gates to a different request id. Authorised by `_authorizeVerifierChange`.
97
+ /// @param newRequestId The request id to check from now on.
98
+ function setRequestId(uint64 newRequestId) external {
99
+ _authorizeVerifierChange();
100
+ _setRequestId(newRequestId);
101
+ }
102
+
103
+ /// @dev The child decides who may change the verifier or request id. Revert to deny.
104
+ /// Typical bodies: `onlyOwner` as a modifier with an empty body, or
105
+ /// `_checkRole(DEFAULT_ADMIN_ROLE)`.
106
+ function _authorizeVerifierChange() internal virtual;
107
+
108
+ /// @dev Asks the verifier without reverting. Children use this to log or skip instead of revert.
109
+ /// @param wallet The address to check.
110
+ /// @return True when the verifier accepts the wallet for this contract's request id.
111
+ function _checkEligible(address wallet) internal view returns (bool) {
112
+ return _verifier.isEligible(wallet, _requestId);
113
+ }
114
+
115
+ /// @dev Reverts with `NotEligible` unless the verifier accepts the wallet.
116
+ /// @param wallet The address to check.
117
+ function _requireEligible(address wallet) internal view {
118
+ if (!_checkEligible(wallet)) revert NotEligible(wallet, _requestId);
119
+ }
120
+
121
+ /// @dev Emits `EligibilityDenied`. Call it on a non-reverting denial path; on a reverting
122
+ /// path the event would be rolled back with everything else.
123
+ /// @param wallet The address that failed the check.
124
+ function _recordDenial(address wallet) internal {
125
+ emit EligibilityDenied(wallet, _requestId, address(_verifier));
126
+ }
127
+
128
+ function _setVerifier(IRedbellyVerifier newVerifier) private {
129
+ if (address(newVerifier) == address(0)) revert ZeroVerifier();
130
+ address previous = address(_verifier);
131
+ _verifier = newVerifier;
132
+ emit VerifierChanged(previous, address(newVerifier));
133
+ }
134
+
135
+ function _setRequestId(uint64 newRequestId) private {
136
+ uint64 previous = _requestId;
137
+ _requestId = newRequestId;
138
+ emit RequestIdChanged(previous, newRequestId);
139
+ }
140
+ }
@@ -0,0 +1,40 @@
1
+ // SPDX-License-Identifier: MIT
2
+ pragma solidity 0.8.30;
3
+
4
+ /// @notice The five credential states a gated function can meet.
5
+ /// @dev `NeverIssued` is deliberately zero so an unset mapping slot reads as "no credential".
6
+ /// Real verifiers on Redbelly (an Iden3 `ZKPVerifier` child or a `VCVerifierBaseContract` child)
7
+ /// expose only a boolean: the proof for a request was accepted, or it was not. The four non-valid
8
+ /// states exist so tests can name the reason a wallet fails. In Receptor terms: `Expired` is a
9
+ /// credential past its validity window, `Revoked` is an issuer revocation (Iden3 revocation
10
+ /// status in the reverse hash service), `WrongJurisdiction` is a credential whose claim does not
11
+ /// satisfy the query or whose issuer is not on the allow-list, and `NeverIssued` is no credential
12
+ /// at all. Adapters over real verifiers return `Valid` or `NeverIssued` only.
13
+ enum EligibilityStatus {
14
+ NeverIssued,
15
+ Valid,
16
+ Expired,
17
+ Revoked,
18
+ WrongJurisdiction
19
+ }
20
+
21
+ /// @title IRedbellyVerifier
22
+ /// @notice The one interface the rest of this kit depends on. There is no network-wide verifier
23
+ /// on Redbelly; every dApp deploys its own. `Gated` therefore binds to this interface and an
24
+ /// adapter (or the mock) sits behind it.
25
+ interface IRedbellyVerifier {
26
+ /// @notice Whether `wallet` holds an accepted proof for `requestId`.
27
+ /// @param wallet The address whose eligibility is being checked.
28
+ /// @param requestId The verifier request (Iden3 request id) the proof must satisfy.
29
+ /// @return True when the wallet may pass a gate bound to this request.
30
+ function isEligible(address wallet, uint64 requestId) external view returns (bool);
31
+
32
+ /// @notice The credential state behind `isEligible`.
33
+ /// @dev A mock and testing aid. Real verifiers cannot distinguish the non-valid states, so
34
+ /// adapters return `Valid` or `NeverIssued` only. Do not branch production logic on the
35
+ /// non-valid values.
36
+ /// @param wallet The address whose eligibility is being checked.
37
+ /// @param requestId The verifier request the proof must satisfy.
38
+ /// @return The resolved state; `Valid` if and only if `isEligible` is true.
39
+ function eligibilityStatus(address wallet, uint64 requestId) external view returns (EligibilityStatus);
40
+ }
@@ -0,0 +1,161 @@
1
+ // SPDX-License-Identifier: MIT
2
+ pragma solidity 0.8.30;
3
+
4
+ import {EligibilityStatus, IRedbellyVerifier} from "./IRedbellyVerifier.sol";
5
+
6
+ /// @title ReceptorMock
7
+ /// @notice A verifier for tests and Anvil forks that lets a test put any wallet into any of the
8
+ /// five credential states, per request id or for every request id at once.
9
+ /// @dev Resolution order for `(wallet, requestId)`: a record set with `setStatus` or
10
+ /// `setValidUntil` for that exact pair wins; otherwise a record set with `setStatusAll` or
11
+ /// `setValidUntilAll` for the wallet applies; otherwise the wallet is `NeverIssued`. A record that
12
+ /// is `Valid` with a non-zero `expiresAt` reads as `Expired` once `block.timestamp` reaches it,
13
+ /// so `vm.warp` tests work without touching the mock again.
14
+ ///
15
+ /// Anyone may call the setters: this is a test tool, not an access-controlled contract. `freeze`
16
+ /// makes every later change revert so a test cannot loosen the mock half way through a run.
17
+ /// The constructor refuses chain 151 so the mock can never stand in for a real verifier on
18
+ /// mainnet, even by accident; on a mainnet fork use `vm.chainId` if you truly need it there.
19
+ contract ReceptorMock is IRedbellyVerifier {
20
+ /// @notice One stored state.
21
+ /// @param isSet False for a slot nobody wrote; distinguishes "set to NeverIssued" from unset.
22
+ /// @param status The stored state before the expiry rule is applied.
23
+ /// @param expiresAt Unix time from which a `Valid` record reads as `Expired`; zero means never.
24
+ struct Record {
25
+ bool isSet;
26
+ EligibilityStatus status;
27
+ uint64 expiresAt;
28
+ }
29
+
30
+ /// @notice Thrown by every setter after `freeze`.
31
+ error MockIsFrozen();
32
+
33
+ /// @notice Thrown by the constructor on Redbelly mainnet.
34
+ /// @param chainId The chain id the constructor saw.
35
+ error MainnetForbidden(uint256 chainId);
36
+
37
+ /// @notice Emitted when a per-request record is written.
38
+ event StatusSet(address indexed wallet, uint64 indexed requestId, EligibilityStatus status, uint64 expiresAt);
39
+
40
+ /// @notice Emitted when a wallet-wide record is written.
41
+ event StatusSetAll(address indexed wallet, EligibilityStatus status, uint64 expiresAt);
42
+
43
+ /// @notice Emitted when a per-request record is removed.
44
+ event StatusCleared(address indexed wallet, uint64 indexed requestId);
45
+
46
+ /// @notice Emitted when a wallet-wide record is removed.
47
+ event StatusClearedAll(address indexed wallet);
48
+
49
+ /// @notice Emitted once, when the mock is frozen.
50
+ event MockFrozen(address indexed by);
51
+
52
+ uint256 private constant REDBELLY_MAINNET = 151;
53
+
54
+ /// @notice True once `freeze` has been called; no setter works after that.
55
+ bool public frozen;
56
+
57
+ mapping(address wallet => mapping(uint64 requestId => Record)) private _byRequest;
58
+ mapping(address wallet => Record) private _forAllRequests;
59
+
60
+ constructor() {
61
+ if (block.chainid == REDBELLY_MAINNET) revert MainnetForbidden(block.chainid);
62
+ }
63
+
64
+ modifier notFrozen() {
65
+ _requireNotFrozen();
66
+ _;
67
+ }
68
+
69
+ /// @inheritdoc IRedbellyVerifier
70
+ function isEligible(address wallet, uint64 requestId) external view returns (bool) {
71
+ return eligibilityStatus(wallet, requestId) == EligibilityStatus.Valid;
72
+ }
73
+
74
+ /// @inheritdoc IRedbellyVerifier
75
+ function eligibilityStatus(address wallet, uint64 requestId) public view returns (EligibilityStatus) {
76
+ Record memory record = _byRequest[wallet][requestId];
77
+ if (!record.isSet) record = _forAllRequests[wallet];
78
+ if (!record.isSet) return EligibilityStatus.NeverIssued;
79
+ // Expiry is the point: the mock compares block.timestamp on purpose (Slither and forge lint both flag it).
80
+ // slither-disable-next-line timestamp
81
+ // forge-lint: disable-next-line(block-timestamp)
82
+ if (record.status == EligibilityStatus.Valid && record.expiresAt != 0 && block.timestamp >= record.expiresAt) {
83
+ return EligibilityStatus.Expired;
84
+ }
85
+ return record.status;
86
+ }
87
+
88
+ /// @notice The stored record for an exact pair, before the expiry rule and without fallback.
89
+ /// @param wallet The wallet.
90
+ /// @param requestId The request id.
91
+ /// @return The raw record; `isSet` false means nothing was written for this pair.
92
+ function recordFor(address wallet, uint64 requestId) external view returns (Record memory) {
93
+ return _byRequest[wallet][requestId];
94
+ }
95
+
96
+ /// @notice The stored wallet-wide record, before the expiry rule.
97
+ /// @param wallet The wallet.
98
+ /// @return The raw record; `isSet` false means nothing was written for this wallet.
99
+ function recordForAll(address wallet) external view returns (Record memory) {
100
+ return _forAllRequests[wallet];
101
+ }
102
+
103
+ /// @notice Puts `wallet` into `status` for `requestId`, with no expiry.
104
+ /// @param wallet The wallet.
105
+ /// @param requestId The request id.
106
+ /// @param status The state to report.
107
+ function setStatus(address wallet, uint64 requestId, EligibilityStatus status) external notFrozen {
108
+ _byRequest[wallet][requestId] = Record({isSet: true, status: status, expiresAt: 0});
109
+ emit StatusSet(wallet, requestId, status, 0);
110
+ }
111
+
112
+ /// @notice Makes `wallet` `Valid` for `requestId` until `expiresAt`, then `Expired`.
113
+ /// @param wallet The wallet.
114
+ /// @param requestId The request id.
115
+ /// @param expiresAt Unix time at which validity ends; zero means it never ends.
116
+ function setValidUntil(address wallet, uint64 requestId, uint64 expiresAt) external notFrozen {
117
+ _byRequest[wallet][requestId] = Record({isSet: true, status: EligibilityStatus.Valid, expiresAt: expiresAt});
118
+ emit StatusSet(wallet, requestId, EligibilityStatus.Valid, expiresAt);
119
+ }
120
+
121
+ /// @notice Puts `wallet` into `status` for every request id that has no record of its own.
122
+ /// @param wallet The wallet.
123
+ /// @param status The state to report.
124
+ function setStatusAll(address wallet, EligibilityStatus status) external notFrozen {
125
+ _forAllRequests[wallet] = Record({isSet: true, status: status, expiresAt: 0});
126
+ emit StatusSetAll(wallet, status, 0);
127
+ }
128
+
129
+ /// @notice Makes `wallet` `Valid` for every request id without its own record, until `expiresAt`.
130
+ /// @param wallet The wallet.
131
+ /// @param expiresAt Unix time at which validity ends; zero means it never ends.
132
+ function setValidUntilAll(address wallet, uint64 expiresAt) external notFrozen {
133
+ _forAllRequests[wallet] = Record({isSet: true, status: EligibilityStatus.Valid, expiresAt: expiresAt});
134
+ emit StatusSetAll(wallet, EligibilityStatus.Valid, expiresAt);
135
+ }
136
+
137
+ /// @notice Removes the per-request record so the wallet-wide record, or `NeverIssued`, applies.
138
+ /// @param wallet The wallet.
139
+ /// @param requestId The request id.
140
+ function clearStatus(address wallet, uint64 requestId) external notFrozen {
141
+ delete _byRequest[wallet][requestId];
142
+ emit StatusCleared(wallet, requestId);
143
+ }
144
+
145
+ /// @notice Removes the wallet-wide record.
146
+ /// @param wallet The wallet.
147
+ function clearStatusAll(address wallet) external notFrozen {
148
+ delete _forAllRequests[wallet];
149
+ emit StatusClearedAll(wallet);
150
+ }
151
+
152
+ /// @notice Makes every later setter revert. Irreversible.
153
+ function freeze() external notFrozen {
154
+ frozen = true;
155
+ emit MockFrozen(msg.sender);
156
+ }
157
+
158
+ function _requireNotFrozen() private view {
159
+ if (frozen) revert MockIsFrozen();
160
+ }
161
+ }