feat(policy): add NOT/invert policy semantics to reference by rayyan224 · Pull Request #222 · base/base-std

rayyan224 · 2026-09-10T14:11:56Z

What

Adds an invert (NOT) flag on the high bit of the uint64 policy ID so one membership set can be evaluated as include or exclude without maintaining a mirror list. When the bit (B20Constants.POLICY_INVERT_BIT, bit 63) is set, isAuthorized resolves the base policy (id & ~POLICY_INVERT_BIT) and returns the opposite of its decision. The base's members are shared, never copied — updating the base updates the inverse.

This is Option 2a (invert bit on the ID) with a base-existence check. No new functions or selectors are added; the invert bit reinterprets the existing ID argument.

Why fail-closed matters

An inverted ID over an unknown or malformed base returns false, never allow-everyone. Without this guard, a garbage/typo'd ID with the bit set would authorize every account — a mint/transfer/seize bypass. The flip is only applied after the base resolves against a real policy.

Changes

src/lib/B20Constants.sol — POLICY_INVERT_BIT (single source of truth) + a pure invertPolicy() helper. Negation is pure bit math, so no registry selector is added (kept off the frozen ABI surface).
src/interfaces/IPolicyRegistry.sol — NatSpec only (no signature changes): the ID layout + invert flag, isAuthorized's fail-closed rule, strip-to-base semantics on the read getters (policyExists(~id) == policyExists(id), etc.), and the composite create/update contract (a child may carry the flag for "A AND NOT X"; an inverted composite child is rejected to preserve the flat-tree invariant).
test/lib/mocks/MockPolicyRegistry.sol — invert handling in _isAuthorized (fail-closed flip), strip-to-base in the getters, composite-child validation on the base. Non-inverted paths are byte-identical.
test/unit/PolicyRegistry/isAuthorizedInvert.t.sol — new suite, fail-closed invariants first, then simple/built-in truth tables, INTERSECT[A, ~X], child validation, getter strip semantics, and the helper.

Scope

base-std reference mock only; the Rust precompile is unchanged. Per AGENTS.md the mock must mirror the Rust impl slot-for-slot — the Rust side does not implement NOT yet, so live-precompile (base-forge test) will diverge for the new inverted-ID cases until the precompile lands. Existing behavior stays in parity.

Testing

forge build clean; forge fmt --check clean.
forge test — 751 passed, 0 failed, 4 skipped (adds 16 invert cases).
python3 script/check-coverage.py — all interface functions covered.

Introduce an invert (NOT) flag on the high bit of the uint64 policy ID so one membership set can be evaluated as include or exclude without maintaining a mirror list. When the bit is set, isAuthorized resolves the base policy (id & ~POLICY_INVERT_BIT) and returns the opposite of its decision. Fail-closed by construction: an inverted ID over an unknown or malformed base returns false rather than authorizing everyone -- the guard that keeps the flag safe on gated mint / transfer / seize paths. The base's members are shared, never copied, so updating the base updates the inverse. - B20Constants: add POLICY_INVERT_BIT (single source of truth) and a pure invertPolicy() helper (no new registry selector; negation is pure bit math). - IPolicyRegistry: document the invert contract on isAuthorized, the read getters (strip-to-base), and composite create/update (inverted simple child allowed for "A AND NOT X"; inverted composite child rejected). No signature changes. - MockPolicyRegistry: invert handling in _isAuthorized (fail-closed flip), strip-to-base in the getters, and composite-child validation on the base. - Tests: isAuthorizedInvert.t.sol -- fail-closed invariants first, then the simple/built-in truth tables, INTERSECT[A, ~X], child validation, getter strip semantics, and the helper. Scope is the base-std reference mock; the Rust precompile is unchanged. Co-Authored-By: Claude <noreply@anthropic.com>

github-actions · 2026-09-10T14:13:01Z

Interface Coverage

✅ All interface functions have test coverage.

github-actions · 2026-09-10T14:13:31Z

📊 Forge Coverage (`src/lib/`)

🟡 ≥95% across all metrics — some metrics below 99%.

File	Lines	Stmts	Branches	Funcs
🟡 B20FactoryLib.sol	97.70%	98.00%	100.00%	95.00%
🔴 test/lib/ForceFeeder.sol	0.00%	0.00%	100.00%	0.00%
🔴 test/lib/PrecompileProbe.sol	0.00%	0.00%	0.00%	0.00%
🟢 MockActivationRegistry.sol	100.00%	100.00%	100.00%	100.00%
🟢 MockActivationRegistryStorage.sol	100.00%	100.00%	100.00%	100.00%
🟢 MockB20.sol	100.00%	100.00%	100.00%	100.00%
🟢 MockB20Asset.sol	100.00%	100.00%	100.00%	100.00%
🟡 MockB20Factory.sol	98.96%	99.10%	100.00%	100.00%
🟢 MockB20Stablecoin.sol	100.00%	100.00%	100.00%	100.00%
🟢 MockB20Storage.sol	100.00%	100.00%	100.00%	100.00%
🟡 MockPolicyRegistry.sol	100.00%	99.58%	97.78%	100.00%
🟢 MockPolicyRegistryStorage.sol	100.00%	100.00%	100.00%	100.00%
Total	97.12%	97.57%	98.18%	97.03%

Full report: download artifact. To browse locally: make coverage (runs forge coverage + genhtml + opens the HTML report).

github-actions · 2026-09-10T14:29:10Z

⚠️ Fork tests: 26 failed, 731 passed

These failures indicate divergences where base/base needs to catch up to the base-std spec. This check is advisory and does not block merging.

Failing tests

test_invertedPolicyId_success_negatesAuthorization(address): custom error 0x6b468933; counterexample: calldata=0x4268079e000000000000000000000000efcc15b3f966ecfd1ca1463c9b784cad29203561 args=[0xeFcc15b3F966eCFD1ca1463C9b784caD29203561]
test_invertedPolicyId_success_togglesAndRoundTrips(uint64): custom error 0x6b468933; counterexample: calldata=0x123f60c00000000000000000000000000000000000000000000000000000000000000000 args=[0]
test_isAuthorized_success_intersectAllowAndNotX(address): PolicyNotFound(); counterexample: calldata=0x55848b8e00000000000000000000000046fe08e88deef6f5cd756aba96c53c171659f6d3 args=[0x46fE08E88Deef6F5cd756aba96c53C171659F6d3]
test_isAuthorized_success_invertAllowlistNonMemberAuthorized(address): assertion failed; counterexample: calldata=0xb07c21cd0000000000000000000000003b25ef30456738b7198ef42c25e7a8226a1fd2f0 args=[0x3b25EF30456738b7198EF42C25E7A8226A1fd2F0]
test_isAuthorized_success_invertAlwaysBlockAuthorizes(address): assertion failed; counterexample: calldata=0xca9d71610000000000000000000000008278c8835a5b02a099ecacac52cf324d1dae1ab7 args=[0x8278C8835A5b02A099eCaCAC52Cf324D1dAe1ab7]
test_isAuthorized_success_invertBlocklistMemberAuthorized(address): assertion failed; counterexample: calldata=0x0726177900000000000000000000000048118a9a4c414a0a7bfa1943007b7db5f4d4605a args=[0x48118A9a4c414a0A7bFA1943007B7DB5F4d4605A]
test_policyAdmin_success_invertResolvesBaseAdmin(address): assertion failed: 0x0000000000000000000000000000000000000000 != 0x091038295246766bbf9C0Ccb1cEFcce6dD3566a4; counterexample: calldata=0xee7ff5a6000000000000000000000000091038295246766bbf9c0ccb1cefcce6dd3566a4 args=[0x091038295246766bbf9C0Ccb1cEFcce6dD3566a4]
test_policyExists_success_invertMirrorsBase(uint56): assertion failed; counterexample: calldata=0xf4aec5dc00000000000000000000000000000000000000000000000000000000000001ca args=[458]
[FAIL: Error != expected error: PolicyNotFound() != InvalidChildPolicy(9367487224930631684 [9.367e18])] test_createCompositePolicy_revert_invertedCompositeChild() (gas: 234691)
[FAIL: PolicyNotFound()] test_compositePolicyChildIds_success_invertedCompositeIdReturnsSameSet() (gas: 130069)
[FAIL: PolicyNotFound()] test_compositePolicyChildIds_success_returnsChildrenVerbatim() (gas: 130113)
[FAIL: PolicyNotFound()] test_compositePolicyChildIds_success_returnsInvertedChildVerbatimAfterUpdate() (gas: 234463)
[FAIL: PolicyNotFound()] test_createCompositePolicy_success_invertedSimpleChild() (gas: 130123)

Expose the invert (NOT) negation as an ABI-discoverable registry view so indexers, explorers, EOAs, and cross-codebase contracts can obtain the inverted form of a policy ID without knowing the bit layout or compiling against base-std. `invertedPolicyId(uint64)` is a pure toggle of the invert flag (`policyId ^ POLICY_INVERT_BIT`): never reverts, reads no state, and is involutive. It delegates to the on-chain `B20Constants.invertPolicy` helper so the view and the library can never disagree. Existence stays enforced where it matters -- isAuthorized is fail-closed on an inverted, non-existent base. - IPolicyRegistry: declare invertedPolicyId in POLICY QUERIES. - MockPolicyRegistry: implement it via B20Constants.invertPolicy. - Tests: toggle/involution, agreement with the library helper, and end-to-end negation of the authorization decision. Note: on the real precompile this is a new selector -- a follow-up must add it to the frozen ABI surface, the dispatch view-bypass list, and gate it at a hardfork. Scope here is the base-std interface + reference mock. Co-Authored-By: Claude <noreply@anthropic.com>

Reword the compositePolicyChildIds NatSpec (interface + mock) so it is unambiguous that only the queried composite's own invert flag is stripped — the child IDs are returned exactly as stored, so a child recorded with the invert flag comes back with the flag set. No behavior change. Add explicit read-side coverage: children returned verbatim (plain + inverted), the composite's inverse returns the identical child set, and the verbatim contract survives updateComposite. Co-Authored-By: Claude <noreply@anthropic.com>

Consolidate the invert primitive now that negation is a first-class registry operation (invertedPolicyId). Remove POLICY_INVERT_BIT and the invertPolicy() helper from the B20-scoped B20Constants library and define a single INVERTED_POLICY_BIT in PolicyRegistryConstants alongside ALWAYS_ALLOW_ID / ALWAYS_BLOCK_ID, shared by the mock and its tests. - B20Constants: drop POLICY_INVERT_BIT and invertPolicy(). - PolicyRegistryConstants: add INVERTED_POLICY_BIT (single source of truth). - MockPolicyRegistry: source the bit from PolicyRegistryConstants; invertedPolicyId toggles it directly; internal uses renamed INVERT_BIT -> INVERTED_POLICY_BIT. - IPolicyRegistry: NatSpec no longer names a removed constant (invert flag, bit 63). - Tests: reference PolicyRegistryConstants.INVERTED_POLICY_BIT; drop the tests that exercised the removed library helper (registry-view coverage is retained). No behavior change. Co-Authored-By: Claude <noreply@anthropic.com>

Invert is query-time only; storage keys, type decode, and existence always resolve against the issued ID. Centralize the mask so getters and child validation share one strip. Co-authored-by: Cursor <cursoragent@cursor.com>

Drop natspec that restates _basePolicyId and the fail-closed invert path; keep the invert toggle note on invertedPolicyId. Co-authored-by: Cursor <cursoragent@cursor.com>

Give inverted composite children a local so the flag is not inlined at every call site, and drop natspec that restates the tests. Co-authored-by: Cursor <cursoragent@cursor.com>

Keep the invert-bit notice without restating getter and fail-closed behavior already covered by the views. Co-authored-by: Cursor <cursoragent@cursor.com>

@dev

Restore the original simple-child @dev and add that an inverted valid policy ID still counts as a composite child. Co-authored-by: Cursor <cursoragent@cursor.com>

Reflow lines that exceeded the 120-char limit (composite-creation calls after the inverted-child locals were introduced). Formatting only, no logic change. Co-Authored-By: Claude <noreply@anthropic.com>

Register Denim as hardfork ordinal 03 in changelog/README.md and add the full spec for query-time policy inversion (bit 63 of a uint64 policy ID): invertedPolicyId, isAuthorized/getter behavior on inverted IDs, composite-child invert handling, and rejected alternatives. Update docs/concepts/policies.md with the corresponding "Inverting a policy" section (renumbers 2.3+ by one). Co-Authored-By: Claude <noreply@anthropic.com>

Cover the "invert multiple children" case explicitly (NOT A AND NOT B) and trim a redundant blank line / sentinel-ID aside. Co-Authored-By: Claude <noreply@anthropic.com>

rayyan224 · 2026-09-11T16:19:31Z

+    ///      or malformed base is denied later, at `isAuthorized`.
+    ///
+    /// @param policyId Policy to invert.
+    ///


Add Nat spec to give the NAT spec that inversion twice results in the same

rayyan224 · 2026-09-11T16:20:39Z

 /// @notice Singleton registry of simple and composite policies. Policies are referenced by
 ///         `uint64 policyId` and queried via `isAuthorized(policyId, account)`.
+///
+/// @dev Invert (`invertedPolicyId`): all view functions see an inverted policy ID as an


Move those to each view functions.

Motivation: feature level natspec should be as close to the feature code as possible

rayyan224 · 2026-09-11T16:22:31Z

    ///      `_isAuthorized` per child, each of which resolves via the simple path
    ///      (or a built-in short-circuit).
    function _isAuthorized(uint64 policyId, address account) internal view returns (bool) {
+        bool isInverted = policyId & INVERTED_POLICY_BIT != 0;


Move this to 399

rayyan224 · 2026-09-11T16:24:44Z

+    T -->|yes| OK["Accept child ID as stored, invert bit kept"]
+```
+
+#### State / gas


Make heading the same as Interfaces and seperate

rayyan224 requested review from amiecorso, eric-ships, ilikesymmetry and stevieraykatz as code owners September 10, 2026 14:11

rayyan224 and others added 2 commits September 10, 2026 10:35

rayyan224 commented Sep 10, 2026

View reviewed changes

Comment thread src/interfaces/IPolicyRegistry.sol

rayyan224 and others added 6 commits September 10, 2026 11:21

refactor(policy): extract _basePolicyId invert-strip helper

4ad5360

Invert is query-time only; storage keys, type decode, and existence always resolve against the issued ID. Centralize the mask so getters and child validation share one strip. Co-authored-by: Cursor <cursoragent@cursor.com>

docs(policy): trim invert comments in the registry mock

0567759

Drop natspec that restates _basePolicyId and the fail-closed invert path; keep the invert toggle note on invertedPolicyId. Co-authored-by: Cursor <cursoragent@cursor.com>

test(policy): name inverted child IDs and shorten invert comments

44770ce

Give inverted composite children a local so the flag is not inlined at every call site, and drop natspec that restates the tests. Co-authored-by: Cursor <cursoragent@cursor.com>

docs(policy): shorten INVERTED_POLICY_BIT natspec

45818bb

Keep the invert-bit notice without restating getter and fail-closed behavior already covered by the views. Co-authored-by: Cursor <cursoragent@cursor.com>

docs(policy): note inverted IDs are valid composite children

7b0cc31

Restore the original simple-child @dev and add that an inverted valid policy ID still counts as a composite child. Co-authored-by: Cursor <cursoragent@cursor.com>

rayyan224 requested review from stephancill and stevieraykatz and removed request for stevieraykatz September 10, 2026 16:00

rayyan224 changed the title ~~feat(policy): add NOT/invert policy semantics to reference mock~~ feat(policy): add NOT/invert policy semantics to referenc Sep 10, 2026

style(policy): forge fmt the invert mock and tests

533de1b

Reflow lines that exceeded the 120-char limit (composite-creation calls after the inverted-child locals were introduced). Formatting only, no logic change. Co-Authored-By: Claude <noreply@anthropic.com>

rayyan224 changed the title ~~feat(policy): add NOT/invert policy semantics to referenc~~ feat(policy): add NOT/invert policy semantics to reference Sep 10, 2026

stephancill reviewed Sep 10, 2026

View reviewed changes

Comment thread test/lib/mocks/MockPolicyRegistry.sol

rayyan224 mentioned this pull request Sep 11, 2026

changelog(denim): add NOT / invert policy spec #225

Closed

2 tasks

changelog(denim): tighten NOT-policy summary/motivation wording

882ca28

Cover the "invert multiple children" case explicitly (NOT A AND NOT B) and trim a redundant blank line / sentinel-ID aside. Co-Authored-By: Claude <noreply@anthropic.com>

rayyan224 commented Sep 11, 2026

View reviewed changes

Navigation Menu

Uh oh!

feat(policy): add NOT/invert policy semantics to reference - #222

feat(policy): add NOT/invert policy semantics to reference#222
rayyan224 wants to merge 12 commits into
mainfrom
feat/policy-not-invert-mock

rayyan224 commented Sep 10, 2026

Uh oh!

github-actions Bot commented Sep 10, 2026

Uh oh!

github-actions Bot commented Sep 10, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Sep 10, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

rayyan224 Sep 11, 2026

Uh oh!

rayyan224 Sep 11, 2026

Uh oh!

stephancill Sep 11, 2026

Uh oh!

rayyan224 Sep 11, 2026

Uh oh!

rayyan224 Sep 11, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

rayyan224 commented Sep 10, 2026

What

Why fail-closed matters

Changes

Scope

Testing

Uh oh!

github-actions Bot commented Sep 10, 2026

Interface Coverage

Uh oh!

github-actions Bot commented Sep 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📊 Forge Coverage (src/lib/)

Uh oh!

github-actions Bot commented Sep 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ Fork tests: 26 failed, 731 passed

Uh oh!

Uh oh!

Uh oh!

rayyan224 Sep 11, 2026

Choose a reason for hiding this comment

Uh oh!

rayyan224 Sep 11, 2026

Choose a reason for hiding this comment

Uh oh!

stephancill Sep 11, 2026

Choose a reason for hiding this comment

Uh oh!

rayyan224 Sep 11, 2026

Choose a reason for hiding this comment

Uh oh!

rayyan224 Sep 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

github-actions Bot commented Sep 10, 2026 •

edited

Loading

📊 Forge Coverage (`src/lib/`)

github-actions Bot commented Sep 10, 2026 •

edited

Loading

rayyan224 Sep 11, 2026 •

edited

Loading