Skip to content

Latest commit

 

History

History
144 lines (93 loc) · 11.7 KB

devfeatures.md

File metadata and controls

144 lines (93 loc) · 11.7 KB

DevFeatures System

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. What it is

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.

B. Inputs — where operators supply the bitmap

The bitmap has two operator-facing input surfaces, both in op-deployer:

  1. CLI flag on op-deployer bootstrap implementations

    • --dev-feature-bitmap (env: DEPLOYER_DEV_FEATURE_BITMAP), defined in op-deployer/pkg/deployer/bootstrap/flags.go
    • Raw 32-byte hex; default empty
    • Flows into ImplementationsConfig.DevFeatureBitmap and on into DeployImplementationsInput for L1 implementation deployment.
  2. 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.

There is no other production operator-facing surface. op-node, kona, and rollup config do not take a bitmap at runtime.

Developer-only: op-node/rollup/toggles.go

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

Test-only: per-feature controls

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_HOOK
  • DEV_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 into devFeatureBitmap
  • test/setup/ForkL1Live.s.sol — branches on individual Config.devFeature* returns
  • test/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.

C. Composition — how those inputs become a single bitmap

All composition happens in op-deployer at deploy / genesis time. The central function is:

  • devFeatureBitmapOverride() in op-deployer/pkg/deployer/pipeline/l2genesis.go
    • Reads intent.GlobalDeployOverrides["devFeatureBitmap"]
    • Returns the bitmap to the genesis builder.

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.

D. Propagation — where the bitmap travels

From op-deployer the bitmap fans out two ways:

  1. Into L2 genesis state — scripts/L2Genesis.s.sol (Foundry script) writes the bitmap into the L2DevFeatureFlags predeploy at 0x42...2D via setDevFeatureBitmap(). Only DEPOSITOR_ACCOUNT can write; effectively write-once at genesis.
  2. Into L1 implementation deployment — scripts/deploy/DeployImplementations.s.sol passes 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).

E. Activation — who reads it and what they gate

On L2 (Solidity), readers consult the in-memory bitmap during deploy scripts:

  • Predeploys.isSupportedPredeploy(...) in src/libraries/Predeploys.sol takes the bitmap as a parameter. A predeploy record with a non-zero devFeatureGate is installed only when the bitmap has that bit.
  • scripts/L2Genesis.s.sol — gates which predeploys get installed at genesis.
  • L2ContractsManager does not read the bitmap. Its upgrade gates the interop predeploys on the INTEROP system feature in L1Block, 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 genesis
  • devFeatureBitmap() — read full bitmap
  • isDevFeatureEnabled(bytes32 feature) — per-flag query

F. Hardfork interaction

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.

G. Lifecycle direction

  • SuperRootGamesMigration is default-on: IsDevFeatureEnabled / isDevFeatureEnabled return true for it regardless of the bitmap.
  • #21662 tracks removing the SuperRootGamesMigration flag and its remaining scaffolding.

SP1 verifier selection (not dev-feature gated)

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 (opcmAddress set), ValidateInputs rejects sp1Verifier.
  • An explicit --sp1-verifier-address (bootstrap) or globalDeployOverrides.sp1Verifier (apply) always wins. Otherwise live deploys on Ethereum mainnet and Sepolia use standard.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; DeployImplementations itself reverts without a verifier contract.
  • A generated genesis contains no release verifier, so a genesis apply needs sp1Verifier unless the caller sets ApplyPipelineOpts.DeployMockSP1Verifier (CLI: apply --deploy-mock-sp1-verifier): op-deployer then puts the accept-all MockSP1Verifier test 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, and bootstrap implementations takes 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 with testutil.DeployMockSP1Verifier.
  • op-deployer/pkg/deployer/standard/sp1-verifier.json records, per chain, the VERIFIER_HASH() of that verifier, the PLONK circuit it accepts proofs for; standard.SP1VerifierHashFor reads it. TestApplyDefaultsSP1VerifierOnSepolia holds it to the chain, VerifyOPCM re-checks it at release, and op-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.

File index

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