Specifications - Base Documentation

1. Abstract

B20 is the Base ecosystem’s native token standard — an ERC-20 superset implemented as Rust precompiles rather than EVM smart contracts. It ships with a built-in compliance toolkit: transfer policies, freeze-and-seize, role-based access control, memos, and supply caps. All tokens are deployed via the singleton B20Factory precompile. The full interface definitions are available in the Base Standard Library repository. To deploy your first token, see the Launch a B20 token quickstart.

Verify the Activation Registry is enabled before attempting to deploy.

2. ERC-20 Compatibility

B20 is a strict superset of ERC-20. Every ERC-20 call (transfer, transferFrom, approve, balanceOf, allowance, and the standard events) behaves exactly as the standard specifies, so existing ERC-20 tooling and integrations work against B20 with no changes. B20 adds methods that ERC-20 does not include: memos, mint/burn, policy gating, granular pause, and ERC-2612 permit. These extend ERC-20 without altering it — every ERC-20 method exists on B20, but the reverse does not hold. Because B20 runs as a native precompile, tokens are cheaper and higher-throughput than contract-based tokens while maintaining full ERC-20 wire compatibility.

3. Variants

B20 supports two token variants. Each shares the full base surface (ERC-20, roles, policies, pause, memos, permit) and adds capabilities specific to its use case.

Variant	Address byte	Decimals	Unique features
Asset	`0x00`	6–18 (configurable, immutable)	Rebase multiplier, onchain announcements, batch mint, extra metadata, `OPERATOR_ROLE`
Stablecoin	`0x01`	6 (fixed)	Self-declared fiat currency code

The variant byte is encoded directly in the token address at byte 10, making it identifiable without state queries. A single token standard cannot serve all use cases equally. Equities need stock splits (multiplier), SEC-style disclosure brackets (announcements), and CUSIP/ISIN storage (extra metadata). Stablecoins need a fixed decimal convention matching fiat (6 decimals) and an on-chain currency code for automated classification. Two concrete variants let each type carry only what it needs. See Asset variant and Stablecoin variant for each variant’s unique surface.

4. Policy Registry

The Policy Registry is a singleton precompile that manages allowlists and blocklists. B20 tokens reference policies by uint64 ID — they do not store membership data themselves. Any caller can create a policy and nominate its admin, decoupling policy management from token issuance. Centralizing list management in a shared precompile means one policy can gate multiple tokens, and one compliance team can manage one blocklist that applies across their entire portfolio.

State-changing functions on the Policy Registry are gated by the Activation Registry, which tracks which Base features are live. Read functions (isAuthorized, policyExists, policyAdmin, pendingPolicyAdmin) are always callable.

4.1. Policy Types

Type	Enum value	Default authorization	Behavior
`BLOCKLIST`	`0`	Authorized	All accounts authorized by default; explicitly listed accounts are denied
`ALLOWLIST`	`1`	Denied	All accounts denied by default; explicitly listed accounts are authorized

4.2. Policy IDs

Policy IDs are uint64 values. The top byte encodes the PolicyType; the low 56 bits are a global counter starting at 2.

[top 8 bits: PolicyType][low 56 bits: counter]

Two built-in IDs require no creation:

Constant	ID	Behavior
`ALWAYS_ALLOW`	`0`	Authorizes every account unconditionally. Default scope value on new B20 tokens.
`ALWAYS_BLOCK`	`(uint64(ALLOWLIST) << 56) \| 1`	Denies every account unconditionally.

4.3. `isAuthorized` Semantics

isAuthorized(policyId, account) never reverts, even on a non-existent policy ID. Non-existent policies collapse to empty-member-set semantics:

Policy state	Type	Result
Exists, account listed	`BLOCKLIST`	`false` (denied)
Exists, account not listed	`BLOCKLIST`	`true` (authorized)
Exists, account listed	`ALLOWLIST`	`true` (authorized)
Exists, account not listed	`ALLOWLIST`	`false` (denied)
Does not exist	`BLOCKLIST` (by ID prefix)	`true` (authorizes everyone — no members to block)
Does not exist	`ALLOWLIST` (by ID prefix)	`false` (denies everyone — no members to allow)

Consumers that write a policy ID (e.g. updatePolicy) MUST validate policyExists(policyId) at write time to avoid silently binding to an unintended empty-set policy.

4.4. Creating and Managing Policies

// Create a blocklist policy with an admin
uint64 policyId = policyRegistry.createPolicy(adminAddress, PolicyType.BLOCKLIST);

// Or seed the initial member set in one call
uint64 policyId = policyRegistry.createPolicyWithAccounts(
    adminAddress, PolicyType.BLOCKLIST, accounts
);

Membership is updated via type-specific methods. The bool parameter sets the membership state.

// Blocklist operations (batched)
policyRegistry.updateBlocklist(policyId, true, accounts);   // block these accounts
policyRegistry.updateBlocklist(policyId, false, accounts);  // unblock these accounts

// Allowlist operations (batched)
policyRegistry.updateAllowlist(policyId, true, accounts);   // allow these accounts
policyRegistry.updateAllowlist(policyId, false, accounts);  // deny these accounts

4.5. Admin Model

Each policy has exactly one admin. Admin transfers use a two-step pattern to prevent accidental transfers to wrong addresses:

Current admin calls stageUpdateAdmin(policyId, newAdmin)
Pending admin calls finalizeUpdateAdmin(policyId)

renounceAdmin(policyId) permanently freezes the policy — membership can never be changed again. This is irreversible. There is no grantAdmin or path to restore an admin after renouncement.

4.6. Read Interface

Method	Returns	Reverts?
`isAuthorized(policyId, account)`	Whether `account` is authorized under `policyId`	Never
`policyExists(policyId)`	Whether a policy with this ID has been created	Never
`policyAdmin(policyId)`	Current admin address	Never
`pendingPolicyAdmin(policyId)`	Pending admin during a two-step transfer	Never

5. Roles and Access Control

B20 uses a fixed set of roles to gate privileged operations. The model extends OpenZeppelin AccessControl with one behavioral override: the last admin cannot be removed through standard revocation. Token issuers need fine-grained control over who can mint, burn, pause, and configure a token. A single “owner” pattern is too coarse — an issuer may want their treasury to mint while a separate compliance team manages pauses, without either party having the other’s privileges. The fixed role set ensures every B20 token has the same permission surface, making tooling, audits, and integrations predictable across the ecosystem.

5.1. Base Roles

Role	Constant	Gates
Default admin	`DEFAULT_ADMIN_ROLE`	All admin operations: role grants/revocations, policy updates, supply-cap changes
Minter	`MINT_ROLE`	`mint`, `mintWithMemo`
Burner	`BURN_ROLE`	Caller-side burns: `burn`, `burnWithMemo`
Blocked burner	`BURN_BLOCKED_ROLE`	Third-party burns against policy-blocked accounts: `burnBlocked`
Pauser	`PAUSE_ROLE`	`pause`
Unpauser	`UNPAUSE_ROLE`	`unpause`
Metadata	`METADATA_ROLE`	`updateName`, `updateSymbol`, `updateContractURI`
Operator	`OPERATOR_ROLE`	Asset variant only: `updateMultiplier`, `announce`

The first seven roles exist on all B20 tokens. OPERATOR_ROLE is exclusive to the Asset variant.

5.2. Custom Roles

User-defined roles are supported via setRoleAdmin and grantRole. They carry no built-in effect — B20 only enforces gates against the eight base-surface roles listed above. Custom roles can be used by external contracts that call hasRole to implement additional access patterns.

5.3. Admin Renunciation

The last DEFAULT_ADMIN_ROLE holder cannot be removed via renounceRole or revokeRole (both revert with LastAdminCannotRenounce). The dedicated renounceLastAdmin() is the only path to permanently transition a token to admin-less operation.

// Remove the last admin — irreversible
token.renounceLastAdmin();

Tokens that launch admin-less from the start pass initialAdmin == address(0) at creation, which never grants the role and skips the renounceLastAdmin step entirely. After renounceLastAdmin() (or for tokens deployed with initialAdmin == address(0)):

Operations gated by DEFAULT_ADMIN_ROLE become permanently uncallable
Roles already granted to other addresses (MINT_ROLE, BURN_ROLE, etc.) continue to function independently
Admin resurrection is blocked: grantRole, revokeRole, and setRoleAdmin all revert with AccessControlUnauthorizedAccount
The token’s policies, supply cap, and metadata become immutable

OpenZeppelin’s standard AccessControl allows the last admin to renounceRole themselves, which is a footgun. B20 blocks this path and requires renounceLastAdmin() — a function that does nothing else and whose name makes the consequence unmistakable.

5.4. Pause and Unpause Role Separation

PAUSE_ROLE and UNPAUSE_ROLE are intentionally separate. This enables security architectures where a monitoring bot can emergency-pause on anomaly detection without having the power to unpause. Only governance (a multisig, timelock, or higher-authority key) can restore operations — preventing a compromised pauser from toggling pause to mask an attack.

6. Transfer Policies

B20 declares a fixed set of policy scopes that reference the Policy Registry. Each scope stores a uint64 policy ID. On every gated operation, B20 calls isAuthorized against the relevant scope and reverts if the account is not authorized. A bare ERC-20 transfer moves tokens between any two addresses with no concept of authorized parties. Regulated issuers need to enforce KYC/AML, sanctions compliance, and jurisdiction restrictions at the transfer level. B20 externalizes these rules to the Policy Registry and connects token operations to policies via scopes — compliance rules can be updated without modifying the token, multiple tokens can share the same policy, and different aspects of a transfer can be gated by different policies.

6.1. Scopes

Scope	Checked account	Operations
`TRANSFER_SENDER_POLICY`	The `from` address	`transfer`, `transferFrom`
`TRANSFER_RECEIVER_POLICY`	The `to` address	`transfer`, `transferFrom`
`TRANSFER_EXECUTOR_POLICY`	The `msg.sender`	`transferFrom` only, when `msg.sender` differs from `from`
`MINT_RECEIVER_POLICY`	The `to` address	`mint`, `mintWithMemo`

6.2. Evaluation Order

For a transferFrom(from, to, amount) call where msg.sender != from:

Check TRANSFER_SENDER_POLICY against from
Check TRANSFER_RECEIVER_POLICY against to
Check TRANSFER_EXECUTOR_POLICY against msg.sender

If any check fails, the transaction reverts with PolicyForbids. For a transfer(to, amount) call, only TRANSFER_SENDER_POLICY (against msg.sender) and TRANSFER_RECEIVER_POLICY (against to) are checked. TRANSFER_EXECUTOR_POLICY is not checked because the sender and executor are the same account.

6.3. Approve Exemption

approve is not policy-gated. Only actual balance movement via transfer / transferFrom is checked. An account on a blocklist can approve a spender, but the spender’s transferFrom will revert when the sender policy check fails. Gating approve would add no security value since the transfer itself is the enforcement point.

6.4. Default Values

Every scope defaults to ALWAYS_ALLOW at token creation unless overridden in the bootstrap initCalls. An unattended B20 deployment is fully open — token behavior must be intentionally constrained.

6.5. Reading and Writing Scopes

// Read the current policy ID for a scope
uint64 currentPolicy = token.policyId(TRANSFER_SENDER_POLICY);

// Update a scope to a new policy (requires DEFAULT_ADMIN_ROLE)
token.updatePolicy(TRANSFER_SENDER_POLICY, newPolicyId);

6.6. initCalls Bypass

During token creation via the Factory, initCalls bypass the three transfer-side policy scopes:

Scope	Bypassed during initCalls?
`TRANSFER_SENDER_POLICY`	Yes
`TRANSFER_RECEIVER_POLICY`	Yes
`TRANSFER_EXECUTOR_POLICY`	Yes
`MINT_RECEIVER_POLICY`	No — always enforced

This allows bootstrap transfers (e.g., initial distribution) in the same transaction as deployment, while still ensuring mint recipients pass policy checks from the start. MINT_RECEIVER_POLICY is never bypassed because mint creates new exposure — a compromised minter that bypasses receiver checks during init could distribute tokens to sanctioned addresses before the compliance program is configured.

7. Mint and Supply Cap

New token supply is created via mint and mintWithMemo, gated by MINT_ROLE. Every mint checks the recipient against MINT_RECEIVER_POLICY. An optional supply cap bounds totalSupply. Token issuance is the most consequential supply-side operation. Three controls are necessary: role gating prevents unauthorized inflation, receiver policy ensures newly minted tokens only reach verified recipients (mint is the first moment a token enters an account — there is no prior transfer to gate), and the supply cap provides a hard ceiling that no minter can exceed.

7.1. Mint Methods

// Mint tokens to a recipient (requires MINT_ROLE)
token.mint(to, amount);

// Mint with an attached memo for off-chain reference
token.mintWithMemo(to, amount, memo);

Both methods require the caller to hold MINT_ROLE, check to against MINT_RECEIVER_POLICY, check that totalSupply + amount does not exceed the supply cap, and revert if the MINT pausable feature is paused.

7.2. Supply Cap

The supply cap is a uint128 upper bound on totalSupply.

Value	Meaning
`type(uint128).max`	No practical cap (the default at creation)
Any value `>= totalSupply`	Active cap — mints that would exceed it revert

// Read the current cap
uint128 cap = token.supplyCap();

// Update the cap (requires DEFAULT_ADMIN_ROLE)
token.updateSupplyCap(newCap);

updateSupplyCap constraints:

newCap must be >= totalSupply (cannot set a cap below current supply)
newCap must be <= type(uint128).max (the sentinel is also the maximum)
Emits SupplyCapUpdated(uint128 oldCap, uint128 newCap)

Burns reduce totalSupply, creating headroom under the cap without requiring admin cap adjustment. ERC-20 uses uint256 for balances, but uint128 (max ~340 undecillion) exceeds any realistic token supply. Using uint128 for the cap allows the sentinel value to represent “no cap” without consuming the full uint256 range.

8. Factory and Deployment

All B20 tokens are created through the singleton B20Factory precompile. Token addresses are deterministic and encode the variant directly, allowing off-chain identification without RPC calls. The factory supports initCalls — a bootstrap window where admin-gated configuration and initial transfers can execute in the same transaction as deployment.

8.1. createB20

address token = b20Factory.createB20(variant, salt, params, initCalls);

Parameter	Type	Description
`variant`	`B20Variant`	`ASSET` or `STABLECOIN`
`salt`	`bytes32`	Caller-chosen entropy for deterministic address derivation
`params`	`bytes`	ABI-encoded, variant-specific creation struct (versioned by leading byte)
`initCalls`	`bytes[]`	Optional array of ABI-encoded calls dispatched post-creation

The factory is exposed in base-std as StdPrecompiles.B20_FACTORY. createB20 reverts with IActivationRegistry.FeatureNotActivated if the requested variant’s feature is not yet activated. Asset params:

Field	Type	Description
`name`	`string`	Token name
`symbol`	`string`	Token symbol
`decimals`	`uint8`	6–18 (configurable, immutable after creation)
`initialAdmin`	`address`	Initial `DEFAULT_ADMIN_ROLE` holder. `address(0)` for admin-less
`contractURI`	`string`	ERC-7572 metadata URI

Stablecoin params:

Field	Type	Description
`name`	`string`	Token name
`symbol`	`string`	Token symbol
`currency`	`string`	ISO-style currency code (`A`–`Z` only, self-declared)
`initialAdmin`	`address`	Initial `DEFAULT_ADMIN_ROLE` holder. `address(0)` for admin-less
`contractURI`	`string`	ERC-7572 metadata URI

8.2. Address Derivation

B20 addresses are deterministic and encode the variant directly:

[10-byte B20 prefix][1-byte variant][9-byte keccak256(deployer, salt)]

The variant is recoverable from the address alone — inspect byte 10 (zero-indexed) to identify the token type without an RPC call.

Method	Description
`getB20Address(variant, deployer, salt)`	Compute the deterministic address without deploying
`isB20(addr)`	Whether the address has the B20 prefix (true even if no token is deployed there)
`isB20Initialized(addr)`	Whether a B20 token has been deployed at this address

8.3. initCalls Semantics

initCalls are dispatched after token creation in the same transaction. During this bootstrap window, factory-originated calls receive special bypass privileges:

Gate	Bypassed?
Role gates (`DEFAULT_ADMIN_ROLE`, etc.)	Yes
`TRANSFER_SENDER_POLICY`	Yes
`TRANSFER_RECEIVER_POLICY`	Yes
`TRANSFER_EXECUTOR_POLICY`	Yes
`MINT_RECEIVER_POLICY`	No — always enforced
Pause state	No — always enforced
Token invariants (supply cap, etc.)	No — always enforced

Typical initCalls sequence:

bytes[] memory initCalls = new bytes[](4);

// 1. Set up compliance policies
initCalls[0] = abi.encodeCall(IB20.updatePolicy, (TRANSFER_SENDER_POLICY, senderBlocklistId));
initCalls[1] = abi.encodeCall(IB20.updatePolicy, (TRANSFER_RECEIVER_POLICY, receiverAllowlistId));

// 2. Grant operational roles
initCalls[2] = abi.encodeCall(IAccessControl.grantRole, (MINT_ROLE, treasuryAddress));

// 3. Set supply cap
initCalls[3] = abi.encodeCall(IB20.updateSupplyCap, (1_000_000e6));

A revert in any initCall reverts the entire deployment. Each (deployer, variant, salt) tuple produces exactly one address — deploying the same tuple twice reverts.

9. Burn and Seize

B20 provides two distinct burn paths. Standard burn lets authorized callers destroy tokens from their own balance. burnBlocked lets authorized callers destroy tokens from a third party’s balance — but only if that account is already denied by TRANSFER_SENDER_POLICY. Unrestricted third-party burns would allow anyone with burn capability to destroy anyone’s tokens. B20 mitigates this by requiring that the target account be frozen first. This ensures seizure is a two-step, auditable process: freeze first, seize second.

9.1. Self-Burn

// Burn from own balance (requires BURN_ROLE)
token.burn(amount);

// Burn with an attached memo
token.burnWithMemo(amount, memo);

Requires caller to hold BURN_ROLE. Burns from msg.sender’s balance. Reverts if the BURN pausable feature is paused.

9.2. Seize (burnBlocked)

// Burn from a third party's frozen account (requires BURN_BLOCKED_ROLE)
token.burnBlocked(account, amount);

Requires caller to hold BURN_BLOCKED_ROLE. The target account must be denied by TRANSFER_SENDER_POLICY — if the target is not frozen, the call reverts. BURN_BLOCKED_ROLE is separate from BURN_ROLE — combining both in one role would mean every party authorized to redeem could also seize.

9.3. Freeze-and-Seize Workflow

// Step 1: Freeze the account (add to sender blocklist)
policyRegistry.updateBlocklist(senderPolicyId, true, [targetAccount]);
// Target can no longer send tokens

// Step 2: Seize the balance (requires BURN_BLOCKED_ROLE)
uint256 frozenBalance = token.balanceOf(targetAccount);
token.burnBlocked(targetAccount, frozenBalance);
// Tokens destroyed, totalSupply decreases

// Optional Step 3: Re-mint to a recovery address if required
token.mint(recoveryAddress, frozenBalance);

The seize path burns tokens rather than transferring them. If tokens need to be redirected, the issuer mints new tokens to the recovery address in a separate call — keeping each primitive simple and auditable.

10. Asset Variant

The general-purpose variant for tokenized equities, real-world assets, and long-tail tokens. In addition to the full B20 base surface, Asset tokens add several capabilities gated by OPERATOR_ROLE and existing roles.

10.1. Multiplier

A WAD-precision (1e18) rebase multiplier applied to all balance reads. Raw balances are stored unchanged; the multiplier scales the view returned to callers.

// Read the current multiplier (WAD precision, default 1e18)
uint256 m = token.multiplier();

// Update the multiplier (requires OPERATOR_ROLE)
token.updateMultiplier(2e18);  // 2x — doubles all visible balances

Method	Description
`multiplier()`	Current WAD-precision multiplier
`scaledBalanceOf(account)`	Raw balance × multiplier
`toScaledBalance(raw)`	Convert raw amount to scaled
`toRawBalance(scaled)`	Convert scaled amount to raw
`updateMultiplier(newMultiplier)`	Update the multiplier. Gated by `OPERATOR_ROLE`

balanceOf returns the scaled balance (raw × multiplier). transfer and transferFrom operate on scaled amounts. A multiplier update changes every holder’s visible balance simultaneously — this is a stock-split-equivalent operation.

Multiplier updates should be wrapped in an announce() call for transparency.

10.2. Announcements

On-chain disclosure brackets that wrap sensitive operations with a public notice. Announcements create an auditable record that an operation was intentional and pre-disclosed.

// Wrap operations in an announcement (requires OPERATOR_ROLE)
token.announce(
    internalCalls,  // ABI-encoded calls to execute inside the bracket
    id,             // Unique identifier (enforced forever)
    description,    // Human-readable description
    uri             // Link to off-chain disclosure document
);

Event sequence: Announcement(id, description, uri) emitted → internalCalls executed in order → EndAnnouncement(id) emitted. The id must be unique across the token’s lifetime — reuse reverts with DuplicateAnnouncementId. Permanent uniqueness ensures every announcement is independently verifiable and tamper-evident. Inner call reverts are wrapped in InternalCallFailed.

10.3. Batch Mint

// Mint to multiple recipients in one call (requires MINT_ROLE)
token.batchMint(recipients, amounts);

Applies the same gates as individual mint calls: MINT_ROLE required, MINT_RECEIVER_POLICY checked for each recipient, supply cap enforced across the total.

10.4. Extra Metadata

An arbitrary key/value store for issuer-defined on-chain metadata (e.g., CUSIP, ISIN, or custom identifiers).

// Read a metadata value
string memory value = token.extraMetadata("CUSIP");

// Write a metadata value (requires METADATA_ROLE)
token.updateExtraMetadata("CUSIP", "037833100");

// Remove a metadata entry (set empty value)
token.updateExtraMetadata("CUSIP", "");

11. Stablecoin Variant

The fixed-decimals, fiat-backed variant. Decimals are hard-wired to 6 and not configurable. This matches the precision of most fiat currencies and ensures consistency across all B20 stablecoins.

11.1. Currency Code

// Read the self-declared currency code
string memory code = token.currency();  // e.g., "USD", "EUR"

Property	Value
Set at	Creation via `B20StablecoinCreateParams.currency`
Mutability	Immutable after creation
Character set	`A`–`Z` only (uppercase ASCII letters)
Validation	Not verified against any external registry — self-declared

The currency code is a self-declaration by the issuer. It is not verified against ISO 4217 or any other standard. Integrators should treat it as a label, not a guarantee of peg or backing.

12. Pause

B20 pause is granular: three independently controllable features can be paused and unpaused individually. PAUSE_ROLE and UNPAUSE_ROLE are separate roles. If a vulnerability is discovered in the burn path, a global pause would halt all transfers — freezing every holder’s liquidity to address a problem in an unrelated operation. Granular pause lets issuers halt only the affected operation.

12.1. Pausable Features

Feature	Enum value	Operations affected
`TRANSFER`	`0`	`transfer`, `transferFrom`, `transferWithMemo`, `transferFromWithMemo`
`MINT`	`1`	`mint`, `mintWithMemo`, `batchMint` (Asset variant)
`BURN`	`2`	`burn`, `burnWithMemo`, `burnBlocked`

The PausableFeature enum is append-only — new features may be added in future upgrades but existing values are never changed or removed.

// Pause one or more features (requires PAUSE_ROLE)
token.pause([PausableFeature.TRANSFER, PausableFeature.MINT]);

// Unpause one or more features (requires UNPAUSE_ROLE)
token.unpause([PausableFeature.TRANSFER]);

// Check if a specific feature is paused
bool isPaused = token.isPaused(PausableFeature.TRANSFER);

12.2. Feature Interaction Matrix

Paused feature	`transfer`	`mint`	`burn`	`burnBlocked`	`approve`	`permit`
`TRANSFER`	Reverts	OK	OK	OK	OK	OK
`MINT`	OK	Reverts	OK	OK	OK	OK
`BURN`	OK	OK	Reverts	Reverts	OK	OK
All three	Reverts	Reverts	Reverts	Reverts	OK	OK

approve and permit are never affected by pause state. Pause state is never bypassed during factory initCalls. Pausing an already-paused feature is a no-op (does not revert).

13. Memos

A memo is an optional bytes32 payload attached to a token operation for off-chain reference. On-chain token operations often correspond to off-chain events — invoice payments, redemption references, compliance case IDs. Memos embed the reference directly in the transaction, making the association immutable and auditable.

13.1. Memo Event

event Memo(address indexed caller, bytes32 indexed memo);

The Memo event is emitted immediately after the parent operation’s primary event. Both fields are indexed for efficient log filtering.

13.2. Memo-Emitting Entrypoints

Method	Parent event	Memo position
`transferWithMemo(to, amount, memo)`	`Transfer(from, to, value)`	`logIndex(Transfer) + 1`
`transferFromWithMemo(from, to, amount, memo)`	`Transfer(from, to, value)`	`logIndex(Transfer) + 1`
`mintWithMemo(to, amount, memo)`	`Transfer(address(0), to, value)`	`logIndex(Transfer) + 1`
`burnWithMemo(amount, memo)`	`Transfer(from, address(0), value)`	`logIndex(Transfer) + 1`

Each memo method behaves identically to its non-memo counterpart — same role gates, same policy checks, same pause enforcement.

13.3. Indexer Join Pattern

To associate a Memo event with its parent operation:

Join key: (transactionHash, logIndex - 1)

Given a Memo event at log index N, the parent Transfer event is at log index N - 1 in the same transaction. This relationship is guaranteed by the B20 precompile’s event emission ordering.

indexer-example.js

const memoEvent = logs.find(l => l.topics[0] === MEMO_SIGNATURE);
const parentTransfer = logs.find(
  l => l.logIndex === memoEvent.logIndex - 1
    && l.transactionHash === memoEvent.transactionHash
);

Passing bytes32(0) is valid — the Memo event is still emitted. If no memo is needed, use the non-memo method variant instead to save gas. The bytes32 size is deliberately constrained: large enough for UUIDs, hashes, and encoded identifiers, but small enough to discourage storing data that should live off-chain. Separate *WithMemo methods preserve the standard ERC-20 interface while extending it.

14. Permit (ERC-2612)

B20 implements ERC-2612 signed approvals using an EIP-712 typed-data domain. Token holders can authorize spending via off-chain signatures, enabling gasless approval flows where a relayer submits the permit transaction.

14.1. EIP-712 Domain

EIP712Domain(
    string name,      // token's current name()
    string version,   // fixed at "1"
    uint256 chainId,  // block.chainid
    address verifyingContract  // token address
)

14.2. permit

function permit(
    address owner,
    address spender,
    uint256 value,
    uint256 deadline,
    uint8 v, bytes32 r, bytes32 s
) external;

On success, sets allowance(owner, spender) = value and emits Approval(owner, spender, value). Each account has a monotonically increasing nonce — each successful permit call increments the owner’s nonce, preventing signature replay.

14.3. Domain Separator Rotation

When updateName(newName) is called, the EIP-712 domain separator is recomputed with the new name and EIP712DomainChanged (ERC-5267) is emitted. Permits signed with the old name become invalid. Integrations that cache the domain separator must re-fetch it after observing this event.

14.4. Signature Constraints

ECDSA only — ecrecover is used for verification. ERC-1271 contract signatures (smart wallet signatures) are not accepted. Supporting contract signatures would require calling into arbitrary contracts during permit verification, introducing reentrancy and gas-estimation complexity in the precompile environment.
Deadline enforcement — block.timestamp > deadline causes a revert.
Nonce binding — the signed nonce must match the account’s current nonce.
permit is not affected by pause state (it only sets allowance, it does not transfer tokens) and is not policy-gated (like approve).

15. Metadata

METADATA_ROLE gates name, symbol, and contract URI updates:

Method	Effect	Side effects
`updateName(newName)`	Updates `name()`	Rotates EIP-712 domain separator, emits `NameUpdated` and `EIP712DomainChanged`
`updateSymbol(newSymbol)`	Updates `symbol()`	Emits `SymbolUpdated`
`updateContractURI(newUri)`	Updates `contractURI()`	Per ERC-7572

16. Precompile Addresses

These addresses are identical on every network where B20 is active (Mainnet, Base Sepolia, Vibenet, and local base-anvil).

Precompile	Address
B20Factory	`0xB20f000000000000000000000000000000000000`
Activation Registry	`0x8453000000000000000000000000000000000001`
Policy Registry	`0x8453000000000000000000000000000000000002`

17. 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.

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.

18. 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

Roles

#	Scenario	Expected
9	Grant `MINT_ROLE`, call `mint`	Succeeds
10	Call `mint` without `MINT_ROLE`	Reverts
11	One admin remains, call `revokeRole(DEFAULT_ADMIN_ROLE)`	Reverts with `LastAdminCannotRenounce`
12	Call `renounceLastAdmin()`	Succeeds — token becomes admin-less
13	After `renounceLastAdmin`, `MINT_ROLE` holder calls `mint`	Succeeds — non-admin roles still work
14	Deploy with `initialAdmin == address(0)`, call `grantRole`	Reverts

Transfer Policies

#	Scenario	Expected
15	Sender on blocklist calls `transfer`	Reverts with `PolicyForbids`
16	Sender on blocklist calls `approve`	Succeeds
17	`transferFrom` where executor is on executor blocklist	Reverts
18	Direct `transfer` by sender on executor blocklist (not sender blocklist)	Succeeds
19	During `initCalls`, transfer from blocklisted sender	Succeeds — bypass
20	During `initCalls`, mint to receiver on mint-receiver blocklist	Reverts — never bypassed

Mint and Supply Cap

#	Scenario	Expected
21	Mint that would push `totalSupply` above cap	Reverts with `SupplyCapExceeded`
22	Mint exactly to cap	Succeeds
23	`updateSupplyCap` below current `totalSupply`	Reverts with `InvalidSupplyCap`
24	Burn tokens, then mint up to cap	Succeeds
25	Mint while `MINT` is paused	Reverts

Burn and Seize

#	Scenario	Expected
26	`burnBlocked` on frozen account	Succeeds
27	`burnBlocked` on non-frozen account	Reverts
28	`burnBlocked` by holder of `BURN_ROLE` (not `BURN_BLOCKED_ROLE`)	Reverts
29	Freeze, seize full balance, re-mint to recovery	Succeeds
30	Burn while `BURN` is paused	Reverts

Pause

#	Scenario	Expected
31	Pause `TRANSFER`, call `transfer`	Reverts
32	Pause `TRANSFER`, call `mint`	Succeeds
33	Pause `TRANSFER`, call `approve`	Succeeds
34	Pauser calls `unpause` without `UNPAUSE_ROLE`	Reverts

Memos

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

Permit

#	Scenario	Expected
38	Valid permit with correct signature, nonce, deadline	Succeeds
39	Permit with expired deadline	Reverts
40	Replay used permit signature	Reverts
41	Permit signed before `updateName`, submitted after	Reverts
42	Contract wallet signature (ERC-1271)	Reverts
43	Permit while `TRANSFER` is paused	Succeeds

Factory

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

Variants

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

19. Error Reference

Access Control

Error	Trigger	Recovery
`AccessControlUnauthorizedAccount`	Caller does not hold the required role	Grant the appropriate role
`LastAdminCannotRenounce`	Attempted to remove the last admin via `renounceRole` or `revokeRole`	Use `renounceLastAdmin()` if intentional

Policies

Error	Trigger	Recovery
`PolicyForbids`	Account failed `isAuthorized` check for the relevant scope	Add account to policy’s authorized list, or change the scope’s policy ID
`InvalidScope`	Unrecognized scope passed to `updatePolicy`	Use a defined scope constant
`Unauthorized`	Caller is not the policy admin	Call from the policy admin address
`PolicyFrozen`	`renounceAdmin` was called on this policy	None — permanently frozen
`InvalidPolicyType`	Called the wrong type-specific update method	Use the correct method for the policy type

Supply

Error	Trigger	Recovery
`SupplyCapExceeded`	Mint would exceed the supply cap	Reduce amount, raise cap, or burn first
`InvalidSupplyCap`	New cap below `totalSupply` or above `type(uint128).max`	Set cap between `totalSupply` and `type(uint128).max`
`ERC20InsufficientBalance`	Burn amount exceeds account balance	Reduce amount

Pause

Error	Trigger	Recovery
`FeaturePaused`	Operation’s `PausableFeature` is paused	Unpause with `UNPAUSE_ROLE`

Permit

Error	Trigger	Recovery
`ERC2612InvalidSigner`	Recovered signer doesn’t match `owner`, or contract signature	Verify signing key matches `owner` and is an EOA
`ERC2612ExpiredSignature`	`block.timestamp` exceeds deadline	Sign a new permit

Factory

Error	Trigger	Recovery
`FeatureNotActivated`	Variant feature not active in Activation Registry	Wait for activation
`TokenAlreadyExists`	Same `(deployer, variant, salt)` already deployed	Use a different salt
`InvalidParams`	Params fail validation (e.g., decimals out of range)	Fix params
`InitCallFailed`	An `initCall` reverted during bootstrap	Check the failing initCall

Variants

Error	Trigger	Recovery
`InvalidDecimals`	Asset decimals outside 6–18	Use 6–18
`DuplicateAnnouncementId`	ID already used on this token	Use a unique ID
`InternalCallFailed`	Call inside `announce()` reverted	Check inner call params
`InvalidCurrency`	Currency code contains non-`A`–`Z` characters	Use uppercase ASCII only
`InvalidMultiplier`	Multiplier value is invalid	Use a valid WAD-precision value

​1. Abstract

​2. ERC-20 Compatibility

​3. Variants

​4. Policy Registry

​4.1. Policy Types

​4.2. Policy IDs

​4.3. isAuthorized Semantics

​4.4. Creating and Managing Policies

​4.5. Admin Model

​4.6. Read Interface

​5. Roles and Access Control

​5.1. Base Roles

​5.2. Custom Roles

​5.3. Admin Renunciation

​5.4. Pause and Unpause Role Separation

​6. Transfer Policies

​6.1. Scopes

​6.2. Evaluation Order

​6.3. Approve Exemption

​6.4. Default Values

​6.5. Reading and Writing Scopes

​6.6. initCalls Bypass

​7. Mint and Supply Cap

​7.1. Mint Methods

​7.2. Supply Cap

​8. Factory and Deployment

​8.1. createB20

​8.2. Address Derivation

​8.3. initCalls Semantics

​9. Burn and Seize

​9.1. Self-Burn

​9.2. Seize (burnBlocked)

​9.3. Freeze-and-Seize Workflow

​10. Asset Variant

​10.1. Multiplier

​10.2. Announcements

​10.3. Batch Mint

​10.4. Extra Metadata

​11. Stablecoin Variant

​11.1. Currency Code

​12. Pause

​12.1. Pausable Features

​12.2. Feature Interaction Matrix

​13. Memos

​13.1. Memo Event

​13.2. Memo-Emitting Entrypoints

​13.3. Indexer Join Pattern

​14. Permit (ERC-2612)

​14.1. EIP-712 Domain

​14.2. permit

​14.3. Domain Separator Rotation

​14.4. Signature Constraints

​15. Metadata

​16. Precompile Addresses

​17. Invariants

​Policy Registry

​Roles

​Transfer Policies

​Supply

​Pause

​Memos

​Permit

​Variants

​Factory

​18. Test Cases

​Policy Registry

​Roles

​Transfer Policies

​Mint and Supply Cap

​Burn and Seize

​Pause

​Memos

​Permit

​Factory

​Variants

​19. Error Reference

​Access Control

​Policies

​Supply

​Pause

1. Abstract

2. ERC-20 Compatibility

3. Variants

4. Policy Registry

4.1. Policy Types

4.2. Policy IDs

4.3. `isAuthorized` Semantics

4.4. Creating and Managing Policies

4.5. Admin Model

4.6. Read Interface

5. Roles and Access Control

5.1. Base Roles

5.2. Custom Roles

5.3. Admin Renunciation

5.4. Pause and Unpause Role Separation

6. Transfer Policies

6.1. Scopes

6.2. Evaluation Order

6.3. Approve Exemption

6.4. Default Values

6.5. Reading and Writing Scopes

6.6. initCalls Bypass

7. Mint and Supply Cap

7.1. Mint Methods

7.2. Supply Cap

8. Factory and Deployment

8.1. createB20

8.2. Address Derivation

8.3. initCalls Semantics

9. Burn and Seize

9.1. Self-Burn

9.2. Seize (burnBlocked)

9.3. Freeze-and-Seize Workflow

10. Asset Variant

10.1. Multiplier

10.2. Announcements

10.3. Batch Mint

10.4. Extra Metadata

11. Stablecoin Variant

11.1. Currency Code

12. Pause

12.1. Pausable Features

12.2. Feature Interaction Matrix

13. Memos

13.1. Memo Event

13.2. Memo-Emitting Entrypoints

13.3. Indexer Join Pattern

14. Permit (ERC-2612)

14.1. EIP-712 Domain

14.2. permit

14.3. Domain Separator Rotation

14.4. Signature Constraints

15. Metadata

16. Precompile Addresses

17. Invariants

Policy Registry

Roles

Transfer Policies

Supply

Pause

Memos

Permit

Variants

Factory

18. Test Cases

Policy Registry

Roles

Transfer Policies

Mint and Supply Cap

Burn and Seize

Pause

Memos

Permit

Factory

Variants

19. Error Reference

Access Control

Policies

Supply

Pause