Reference for the DevFeatures bitmap system. The bitmap is transitional infrastructure that lets in-development features ride alongside production code without a full hardfork. It is expected to disappear once each feature it gates either ships as a real hardfork or is abandoned.
A 32-byte bitmap (bytes32 on chain, common.Hash in Go) where each feature occupies its own nibble — 0x...01, 0x...10, 0x...100, etc. — giving 64 concurrent feature slots. Defined identically on both sides:
- Go:
op-core/devfeatures/devfeatures.go— flag constants,IsDevFeatureEnabled(bitmap, flag),EnableDevFeature(bitmap, flag) - Solidity:
packages/contracts-bedrock/src/libraries/DevFeatures.sol— same constants, same predicate
The two sides are independent literals with no compile-time sync check — a mismatch silently diverges Go and Solidity behavior. The constant values are canonical in those two files; don't trust copies elsewhere.
Active flags:
| Flag | Gates |
|---|---|
DeployV2DisputeGames |
Legacy, no longer used; constant kept for historical reasons |
BridgeHook |
Bridge hook configuration on OptimismPortal2, currently planned only for the compliance module |
OPPrivate |
The OP Private ChainConfig predeploy in L2 genesis, holding the chain's settlement chain ID (op-deployer chain override settlementChainId, per chain only). A chain whose settlementChainId names an earlier chain of the same intent is a private chain: op-deployer reuses that chain's L1 contracts for it and skips it in validate and verify |
SuperRootGamesMigration |
Super-root games migration path in OPCM upgrade — enabled by default |
The predicate is a bitwise AND ((bitmap & flag) == flag && flag != 0) — except that IsDevFeatureEnabled short-circuits to true for SuperRootGamesMigration, which is enabled by default on both the Go and Solidity sides. The bitmap no longer acts as a circuit breaker for it; removal is tracked in #21662.
Adding a new dev feature: the full checklist lives in the DevFeatures.sol natspec — both constant files, the env-var reader in scripts/libraries/Config.sol, the test assembler in test/setup/FeatureFlags.sol, and the CI &features_matrix anchor in .circleci/continue/main.yml (plus each new matrix job, by name, in the required-contracts-ci gate's requires) all need updating; there is no compile-time link between them.
The bitmap has two operator-facing input surfaces, both in op-deployer:
-
CLI flag on
op-deployer bootstrap implementations--dev-feature-bitmap(env:DEPLOYER_DEV_FEATURE_BITMAP), defined inop-deployer/pkg/deployer/bootstrap/flags.go- Raw 32-byte hex; default empty
- Flows into
ImplementationsConfig.DevFeatureBitmapand on intoDeployImplementationsInputfor L1 implementation deployment.
-
Intent file (
globalDeployOverrides.devFeatureBitmap)- Schema field on
Intent,op-deployer/pkg/deployer/state/intent.go - Lives in the operator's intent TOML/JSON
- Read by the L2 genesis pipeline.
- Schema field on
There is no other production operator-facing surface. op-node, kona, and rollup config do not take a bitmap at runtime.
A third input mechanism, distinct from the bitmap, lives in op-node/rollup/toggles.go. It is a source-code-edit-only developer toggle — not exposed via config, CLI, or env var. The file holds ephemeral Is<Feature>(time) methods on *Config that map an in-development feature to its eventual hardfork timestamp:
func (c *Config) IsL2CM(time uint64) bool {
return c.IsKarst(time)
}The file's comment instructs developers to "replace with return false to disable NUT bundle execution during development." This is a temporary scaffold for the active fork scope; entries are removed after the fork is locked.
What it gates is runtime activation timing in op-node (when NUT bundle deposit transactions are emitted at the activation block), which is orthogonal to what the bitmap gates (whether the supporting predeploys and contracts exist on a given chain at all).
A separate, test-only assembler exists for Foundry tests and fork scripts. It reads env vars for opt-in features and hardcodes default-on features. It is isolated from the production path — no src/ contract and no production deploy script reads these controls.
DEV_FEATURE__BRIDGE_HOOKDEV_FEATURE__OP_PRIVATE
Bridge hook and OP Private are read via vm.envOr(..., false) in packages/contracts-bedrock/scripts/libraries/Config.sol; devFeatureSuperRootGamesMigration() returns true unconditionally. The only callers are under test/:
test/setup/FeatureFlags.sol—resolveFeaturesFromEnv()OR-s each enabled flag intodevFeatureBitmaptest/setup/ForkL1Live.s.sol— branches on individualConfig.devFeature*returnstest/L1/OPContractsManagerStandardValidator.t.sol—vm.skip()based on flag state
The env vars and default-on helper exist purely to set up local test fixtures and to skip or branch tests. They never reach a deployed chain. To exercise an opt-in feature in production you must set the bitmap via op-deployer.
All composition happens in op-deployer at deploy / genesis time. The central function is:
devFeatureBitmapOverride()inop-deployer/pkg/deployer/pipeline/l2genesis.go- Reads
intent.GlobalDeployOverrides["devFeatureBitmap"] - Returns the bitmap to the genesis builder.
- Reads
What this does not do: it does not OR together a list of named feature toggles. The operator hands in a raw bitmap; op-deployer passes it through verbatim. The CLI flag and the intent override are independent surfaces — they are not merged; whichever subcommand runs uses its own input.
The Foundry test-only assembler in FeatureFlags.sol is a separate composition layer entirely; it is never invoked by op-deployer.
From op-deployer the bitmap fans out two ways:
- Into L2 genesis state —
scripts/L2Genesis.s.sol(Foundry script) writes the bitmap into theL2DevFeatureFlagspredeploy at0x42...2DviasetDevFeatureBitmap(). OnlyDEPOSITOR_ACCOUNTcan write; effectively write-once at genesis. - Into L1 implementation deployment —
scripts/deploy/DeployImplementations.s.solpasses the bitmap on to the OPCM container and the StandardValidator. The deployed implementation set no longer depends on it, because the only remaining branch (SUPER_ROOT_GAMES_MIGRATION) is default-on.
It does not flow to op-node or kona at runtime. They learn about feature activation through other channels (hardfork timestamps in rollup config, primarily).
On L2 (Solidity), readers consult the in-memory bitmap during deploy scripts:
Predeploys.isSupportedPredeploy(...)insrc/libraries/Predeploys.soltakes the bitmap as a parameter. A predeploy record with a non-zerodevFeatureGateis installed only when the bitmap has that bit.scripts/L2Genesis.s.sol— gates which predeploys get installed at genesis.L2ContractsManagerdoes not read the bitmap. Its upgrade gates the interop predeploys on theINTEROPsystem feature inL1Block, so chains that never set the bitmap at genesis can still activate interop at Lagoon.
On Go, the bitmap is essentially deploy-time-only:
- No runtime callers. (op-node uses hardfork timestamps, not the bitmap.)
The L2DevFeatureFlags predeploy API (src/L2/L2DevFeatureFlags.sol):
setDevFeatureBitmap(bytes32)— DEPOSITOR_ACCOUNT only, set at genesisdevFeatureBitmap()— read full bitmapisDevFeatureEnabled(bytes32 feature)— per-flag query
Super-root migration has no parallel hardfork timestamp, and it is default-on in the predicate, so its bitmap bit no longer acts as a circuit breaker. Network-wide activation timing is a separate mechanism: the hardfork timestamps mapped by the developer toggles in op-node/rollup/toggles.go (see section B), e.g. IsL2CM(time) decides when L2ContractsManager upgrade transactions execute across the network.
- SuperRootGamesMigration is default-on:
IsDevFeatureEnabled/isDevFeatureEnabledreturntruefor it regardless of the bitmap. - #21662 tracks removing the SuperRootGamesMigration flag and its remaining scaffolding.
ZK implementations are not behind a dev feature. Every implementations deploy includes ZKDisputeGame and SP1PlonkAdapter, so it always needs a raw SP1 verifier. Deploying them never enables ZK on a chain; that takes an upgrade()/migrate() game config, or op-deployer's dangerousAdditionalDisputeGames on a custom intent.
- Selection applies only when implementations are deployed. With a predeployed OPCM (
opcmAddressset),ValidateInputsrejectssp1Verifier. - An explicit
--sp1-verifier-address(bootstrap) orglobalDeployOverrides.sp1Verifier(apply) always wins. Otherwise live deploys on Ethereum mainnet and Sepolia usestandard.SP1VerifierFor(op-deployer/pkg/deployer/standard/standard.go), so bootstrap and apply cannot drift. On any other L1, op-deployer errors and asks for the verifier;DeployImplementationsitself reverts without a verifier contract. - A generated genesis contains no release verifier, so a genesis apply needs
sp1Verifierunless the caller setsApplyPipelineOpts.DeployMockSP1Verifier(CLI:apply --deploy-mock-sp1-verifier): op-deployer then puts the accept-allMockSP1Verifiertest artifact into the genesis state (sysgo, op-e2e). The flag also works on a live L1 without a release verifier, such as a local Anvil, andbootstrap implementationstakes it too. op-deployer refuses it, for every deployment target, on an L1 chain ID that has one. Tests on a live L1 can also deploy it withtestutil.DeployMockSP1Verifier. op-deployer/pkg/deployer/standard/sp1-verifier.jsonrecords, per chain, theVERIFIER_HASH()of that verifier, the PLONK circuit it accepts proofs for;standard.SP1VerifierHashForreads it.TestApplyDefaultsSP1VerifierOnSepoliaholds it to the chain,VerifyOPCMre-checks it at release, andop-zk-proposer's release-pin test holds the linked sp1-sdk to it, so bumping sp1-sdk to a new circuit fails CI until the address and the file move together. The proposer also derives the hash from its SDK at runtime and pauses creation and skips proving for any adapter whose verifier hash differs.- A verifier op-deployer passed is recorded in deployment state (
State.SP1Verifier) and never written back into intent. A resumed deployment reuses the recorded address rather than re-resolving the default, so upgrading op-deployer mid-deployment cannot swap the verifier under a chain.
| Concern | Path |
|---|---|
| Go constants & predicate | op-core/devfeatures/devfeatures.go |
| Solidity constants & predicate | packages/contracts-bedrock/src/libraries/DevFeatures.sol |
| CLI input | op-deployer/pkg/deployer/bootstrap/flags.go |
| Intent input + composition | op-deployer/pkg/deployer/pipeline/l2genesis.go |
| Genesis writer | packages/contracts-bedrock/scripts/L2Genesis.s.sol |
| L2 storage | packages/contracts-bedrock/src/L2/L2DevFeatureFlags.sol |
| Predeploy gating | packages/contracts-bedrock/src/libraries/Predeploys.sol |
| L2CM hardfork gate | op-node/rollup/toggles.go |
| Test-only feature controls | packages/contracts-bedrock/scripts/libraries/Config.sol |
| Test bitmap assembler | packages/contracts-bedrock/test/setup/FeatureFlags.sol |