B20 Invariants and Test Cases

These invariants and conformance test cases are the normative behavioral guarantees of the B20 precompiles. They complement the B20 specification and the errors & events index.

Invariants

Policy Registry

isAuthorized never reverts for any combination of policyId and account.
A non-existent BLOCKLIST policy authorizes everyone. A non-existent ALLOWLIST policy denies everyone.
After renounceAdmin(policyId), all membership-mutating calls on that policy revert permanently.
ALWAYS_ALLOW (ID 0) authorizes every account. ALWAYS_BLOCK denies every account. Neither can be created, modified, or renounced.
Policy IDs are globally unique and monotonically increasing within each PolicyType prefix.
An inverted policy ID (bit 63 set) is an extension of its base — policyExists, policyAdmin, and pendingPolicyAdmin resolve to the base’s values.
isAuthorized on an inverted ID returns the negated result of the base. If the base does not exist, it returns false (fail-closed).
invertedPolicyId(invertedPolicyId(id)) == id — inversion is involutive.
An inverted composite child id evaluates the base’s members and returns the opposite result; an inverted composite child is rejected.

Roles

The last DEFAULT_ADMIN_ROLE holder cannot be removed via renounceRole or revokeRole — only renounceLastAdmin().
After renounceLastAdmin(), no address can ever hold DEFAULT_ADMIN_ROLE again.
Roles granted before admin renunciation continue to function.
Custom roles have no built-in effect on any B20 operation.

Transfer Policies

approve is never policy-gated.
TRANSFER_EXECUTOR_POLICY is checked only on transferFrom, never on transfer.
MINT_RECEIVER_POLICY is always enforced, even during factory initCalls.
All three transfer-side scopes are bypassed during initCalls.
Every scope defaults to ALWAYS_ALLOW at token creation.

Supply

totalSupply can never exceed the supply cap.
The supply cap can never be set below the current totalSupply.
Burns reduce totalSupply and create headroom under the cap.

Pause

Each PausableFeature is independent — pausing one does not affect the others.
approve and permit are never affected by any pause state.
Pause state is never bypassed during factory initCalls.

Memos

The Memo event is always emitted at exactly logIndex + 1 relative to its parent Transfer event.
Memo methods are functionally identical to their non-memo counterparts in all respects except event emission.

Permit

permit only accepts ECDSA signatures. ERC-1271 contract signatures always fail.
Each successful permit increments the owner’s nonce by exactly 1.
Permits signed before updateName fail after the name change.

Variants

Asset decimals are set at creation and immutable. Valid range is 6–18.
Stablecoin decimals are always 6.
OPERATOR_ROLE exists only on Asset tokens.
Announcement IDs are unique across a token’s lifetime.
The currency code on a Stablecoin is immutable and contains only A–Z characters.
Multiplier updates affect all holders simultaneously.
batchMint enforces MINT_RECEIVER_POLICY for each recipient individually.

Factory

B20 addresses are deterministic: same inputs always produce the same address.
The variant byte at address position 10 always matches the deployed variant.
Each (deployer, variant, salt) tuple produces exactly one address.
initCalls execute in array order. A revert in any initCall reverts the entire deployment.

Test Cases

Policy Registry

#	Scenario	Expected
1	Create `BLOCKLIST` policy, check unblocked account	`isAuthorized` returns `true`
2	Add account to blocklist, check	`isAuthorized` returns `false`
3	Remove account from blocklist, check	`isAuthorized` returns `true`
4	Create `ALLOWLIST` policy, check unlisted account	`isAuthorized` returns `false`
5	`isAuthorized` with non-existent blocklist-prefixed ID	Returns `true`
6	`isAuthorized` with non-existent allowlist-prefixed ID	Returns `false`
7	`renounceAdmin`, then `updateBlocklist`	Reverts
8	`finalizeUpdateAdmin` from non-pending address	Reverts
9	`isAuthorized(invertedPolicyId(id), account)` where base authorizes account	Returns `false`
10	`isAuthorized(invertedPolicyId(id), account)` where base denies account	Returns `true`
11	`isAuthorized(invertedPolicyId(id), account)` where base does not exist	Returns `false` (fail-closed)
12	`policyExists(invertedPolicyId(id))` where base exists	Returns `true`
13	`policyExists(invertedPolicyId(id))` where base does not exist	Returns `false`
14	`policyAdmin(invertedPolicyId(id))`	Returns same address as `policyAdmin(id)`
15	`pendingPolicyAdmin(invertedPolicyId(id))`	Returns same address as `pendingPolicyAdmin(id)`
16	`compositePolicyChildIds(invertedPolicyId(id))` where base is composite	Returns same children as base, preserving per-child invert flags
17	`invertedPolicyId(invertedPolicyId(id))`	Returns `id`
18	`createCompositePolicy` with an inverted simple-policy child	Succeeds
19	`createCompositePolicy` with an inverted composite child	Reverts with `InvalidChildPolicy`
20	`INTERSECT` composite of policy A and `invertedPolicyId(policyB)` — account in A but in B	`isAuthorized` returns `false`
21	`INTERSECT` composite of policy A and `invertedPolicyId(policyB)` — account in A but not in B	`isAuthorized` returns `true`

Roles

#	Scenario	Expected
22	Grant `MINT_ROLE`, call `mint`	Succeeds
23	Call `mint` without `MINT_ROLE`	Reverts
24	One admin remains, call `revokeRole(DEFAULT_ADMIN_ROLE)`	Reverts with `LastAdminCannotRenounce`
25	Call `renounceLastAdmin()`	Succeeds — token becomes admin-less
26	After `renounceLastAdmin`, `MINT_ROLE` holder calls `mint`	Succeeds — non-admin roles still work
27	Deploy with `initialAdmin == address(0)`, call `grantRole`	Reverts

Transfer Policies

#	Scenario	Expected
28	Sender on blocklist calls `transfer`	Reverts with `PolicyForbids`
29	Sender on blocklist calls `approve`	Succeeds
30	`transferFrom` where executor is on executor blocklist	Reverts
31	Direct `transfer` by sender on executor blocklist (not sender blocklist)	Succeeds
32	During `initCalls`, transfer from blocklisted sender	Succeeds — bypass
33	During `initCalls`, mint to receiver on mint-receiver blocklist	Reverts — never bypassed

Mint and Supply Cap

#	Scenario	Expected
34	Mint that would push `totalSupply` above cap	Reverts with `SupplyCapExceeded`
35	Mint exactly to cap	Succeeds
36	`updateSupplyCap` below current `totalSupply`	Reverts with `InvalidSupplyCap`
37	Burn tokens, then mint up to cap	Succeeds
38	Mint while `MINT` is paused	Reverts

Burn and Seize

#	Scenario	Expected
39	`burnBlocked` on frozen account	Succeeds
40	`burnBlocked` on non-frozen account	Reverts
41	`burnBlocked` by holder of `BURN_ROLE` (not `BURN_BLOCKED_ROLE`)	Reverts
42	Freeze, seize full balance, re-mint to recovery	Succeeds
43	Burn while `BURN` is paused	Reverts

Pause

#	Scenario	Expected
44	Pause `TRANSFER`, call `transfer`	Reverts
45	Pause `TRANSFER`, call `mint`	Succeeds
46	Pause `TRANSFER`, call `approve`	Succeeds
47	Pauser calls `unpause` without `UNPAUSE_ROLE`	Reverts

Memos

#	Scenario	Expected
48	`transferWithMemo`	Emits `Transfer` then `Memo` at consecutive log indices
49	`transferFromWithMemo`	`Memo.caller` is `msg.sender`, not `from`
50	`transfer` (non-memo variant)	No `Memo` event

Permit

#	Scenario	Expected
51	Valid permit with correct signature, nonce, deadline	Succeeds
52	Permit with expired deadline	Reverts
53	Replay used permit signature	Reverts
54	Permit signed before `updateName`, submitted after	Reverts
55	Contract wallet signature (ERC-1271)	Reverts
56	Permit while `TRANSFER` is paused	Succeeds

Factory

#	Scenario	Expected
57	`getB20Address` then deploy with same params	Addresses match
58	Inspect byte 10 of deployed Asset address	Returns `0x00`
59	Deploy same `(deployer, variant, salt)` twice	Second reverts
60	Deploy when variant feature not activated	Reverts
61	`initCalls` that pause `TRANSFER`, then transfer in next initCall	Transfer reverts

Variants

#	Scenario	Expected
62	Deploy Asset with `decimals = 5`	Reverts
63	Update multiplier to `2e18`, check `balanceOf` for raw balance 100	Returns 200
64	Reuse announcement ID	Reverts with `DuplicateAnnouncementId`
65	`batchMint` where one recipient is not on allowlist	Reverts
66	Deploy Stablecoin with `currency = "usd"`	Reverts — `A`–`Z` only

Specifications

Reference

Node Operators

Security

Invariants

Policy Registry

Roles

Transfer Policies

Supply

Pause

Memos

Permit

Variants

Factory

Test Cases

Policy Registry

Roles

Transfer Policies

Mint and Supply Cap

Burn and Seize

Pause

Memos

Permit

Factory

Variants

​Invariants

​Policy Registry

​Roles

​Transfer Policies

​Supply

​Pause

​Memos

​Permit

​Variants

​Factory

​Test Cases

​Policy Registry

​Roles

​Transfer Policies

​Mint and Supply Cap

​Burn and Seize

​Pause

​Memos

​Permit

​Factory

​Variants

Invariants

Policy Registry

Roles

Transfer Policies

Supply

Pause

Memos

Permit

Variants

Factory

Test Cases

Policy Registry

Roles

Transfer Policies

Mint and Supply Cap

Burn and Seize

Pause

Memos

Permit

Factory

Variants