A collection of Solidity interfaces, libraries, and mock implementations for Base precompiles.

• ActivationRegistry — Feature flags controlled by Base team to activate/deactivate features.
• PolicyRegistry — Membership sets controlled by custom admins, initially providing allow and block lists for B20 token operations.
• B20 — Standard ERC-20 implementation with extensions for roles, policies, memos, pausing, ERC-2612 permits, and a variant system.

CHANGELOG.md summarizes behavioral changes by hardfork. For selector-level detail on a given feature (exact selectors, topic0s, error codes, and edge-case Q&A), see changelog/.

These source files are imported by production contracts to interact with Base precompiles.

forge install base/base-std

src
├── StdPrecompiles.sol: Precompile addresses with interface wrapper handles
├── interfaces
│   ├── IB20.sol: Core token standard
│   ├── IB20Asset.sol: Asset variant of B20
│   ├── IB20Stablecoin.sol: Stablecoin variant of B20
│   ├── IB20Factory.sol: B20 factory precompile
│   ├── IPolicyRegistry.sol: Policy registry precompile
│   └── IActivationRegistry.sol: Activation registry precompile
└── lib
    ├── B20Constants.sol: B20 role and policy-type identifier constants
    └── B20FactoryLib.sol: Pure encoders for B20 factory params and initCalls

These mock contracts replace the live precompiles in unit tests, allowing tests to run without a fork.

test/lib/mocks
├── MockActivationRegistry.sol: Mock implementation of the activation registry precompile
├── MockPolicyRegistry.sol: Mock implementation of the policy registry precompile
└── MockB20Factory.sol: Mock implementation of the B20 factory precompile

forge build
forge test

Solidity version: 0.8.30 for reference implementations. Interfaces are written for broader compatibility (>=0.8.20 <0.9.0) so consumers can import them without forcing a specific compiler.

The same unit suite runs against the live Rust precompiles to verify they match the Solidity reference's behavior and storage layout — only the backend changes. The simplest way is base-forge (from base-anvil), which hosts the precompiles in-process; BaseTest auto-detects them, so no flags are needed:

base-forge test

Stock forge test runs the same suite against the Solidity mocks instead (reference mode); setUp logs which mode ran. See LIVE_PRECOMPILE_TESTING.md for the full workflow, including running against a real base-anvil node.

To run against a forked chain that already hosts the precompiles:

LIVE_PRECOMPILES=true FOUNDRY_PROFILE=fork forge test --fork-url vibenet

What each flag does:

• --fork-url vibenet — selects the RPC endpoint defined in foundry.toml under [rpc_endpoints] (currently https://rpc.vibes.base.org/). Foundry forks the chain in a sandboxed copy-on-write state; tests mutate the fork without touching the real chain.
• LIVE_PRECOMPILES=true — tells BaseTest.setUp to skip the mock-etching step. Without it, vm.etch would clobber the live precompile addresses with the mock bytecode, silently routing every call back through the Solidity reference and producing false-pass results.
• FOUNDRY_PROFILE=fork — switches to a reduced-fuzz-runs profile (10 instead of 256). Each fuzz iteration may trigger RPC round-trips against the live precompiles; the goal at this stage is "does the layout / behavior match" rather than fuzz coverage. Drop this flag to use the default fuzz runs.

A test failure under this command means one of three things, in diagnostic order: (1) the feature isn't activated yet in the ActivationRegistry, (2) the precompile isn't deployed at its canonical address on the forked chain, or (3) the Rust impl's storage layout / behavior diverges from the Solidity reference at the asserted slot.

MIT