blockifier: replace flags in cairo native run config with enum

[ArniStarkware]

Note

Medium Risk
Touches core contract class compilation/execution configuration and changes defaults/serialization, which can alter native compilation behavior at runtime if configs aren’t migrated correctly.

Overview
Refactors Cairo native execution configuration from two booleans (run_cairo_native, wait_on_native_compilation) into a single CairoNativeMode enum (off, wait_on_compilation, lazy_compilation) and wires this through CairoNativeRunConfig/ContractClassManagerConfig.

Updates the class manager startup and compilation flow to branch on the new mode (no worker in Off or WaitOnCompilation; async worker only in LazyCompilation), adjusts invariants/assertions, and migrates all tests and helper constructors to the new API.

Migrates node/deployment JSON configs and the config schema to the new cairo_native_run_mode field (defaulting to off in schema; lazy_compilation in provided app configs), and adds a compatibility mapping in native_blockifier’s Python config conversion from the old flags to the new enum.

^{Written by Cursor Bugbot for commit 82616a7. This will update automatically on new commits. Configure here.}

[reviewable-StarkWare]

This change is 

[github-actions]

Artifacts upload workflows:

• Started at 2026-02-18T19:12:15Z
• Started at 2026-02-18T20:10:41Z
• Started at 2026-02-19T13:09:44Z
• Started at 2026-02-19T13:16:24Z
• Started at 2026-02-19T13:54:29Z
• Started at 2026-02-22T12:50:37Z
• Started at 2026-02-23T15:24:08Z
• Started at 2026-02-25T09:44:17Z

[ArniStarkware]

• blockifier: replace flags in cairo native run config with enum #12717 👈 (View in Graphite)
• blockifier: refactor native class manager get runnable to be more readable #12536 : 1 other dependent PR (#12695 )
• blockifier: implement contains for native classes whitelist #12544 : 1 other dependent PR (#12475 )
• main-v0.14.2

This stack of pull requests is managed by Graphite. Learn more about stacking.

[ArniStarkware]

@ArniStarkware made 2 comments and resolved 2 discussions.
Reviewable status: 0 of 16 files reviewed, all discussions resolved.

[ArniStarkware]

@ArniStarkware made 1 comment.
Reviewable status: 0 of 17 files reviewed, all discussions resolved.

---

a discussion (no related file):
Collides with #12696.

[ArniStarkware]

@ArniStarkware reviewed 1 file.
Reviewable status: 1 of 17 files reviewed, all discussions resolved.

[ArniStarkware]

crates/blockifier/src/blockifier/config.rs line 299 at r4 (raw file):

    WaitOnCompilation,
    DontWaitOnCompilation,
}

Points of discussion:

1. The name of the struct.
2. The name of the variants.
3. How should the variants serialize?

Code quote:

#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "lowercase")]
pub enum RunCairoNativeOptions {
    Off,
    WaitOnCompilation,
    DontWaitOnCompilation,
}

[avi-starkware]

@avi-starkware reviewed 17 files and all commit messages, and made 3 comments.
Reviewable status: all files reviewed, 2 unresolved discussions (waiting on ArniStarkware).

---

crates/blockifier/src/blockifier/config.rs line 299 at r4 (raw file):

Previously, ArniStarkware (Arnon Hod) wrote…

Points of discussion:

1. The name of the struct.
2. The name of the variants.
3. How should the variants serialize?

1. Can be CairoNativeMode
2. The last variant can be CompilationWorkerThread instead, and I like WaitOnCompilation.
3. Use "snake_case" for readability.

---

crates/blockifier/src/state/native_class_manager.rs line 165 at r5 (raw file):

            CompiledClasses::V0(_) => self.class_cache.set(class_hash, compiled_class),
            CompiledClasses::V1(compiled_class_v1, sierra_contract_class) => {
                if let CairoNativeRunMode::SynchronousCompilation = self.cairo_native_run_mode() {

Suggestion:

                if self.cairo_native_run_mode() == CairoNativeRunMode::SynchronousCompilation {

---

crates/blockifier/src/state/native_class_manager.rs line 186 at r5 (raw file):

                );

                if let CairoNativeRunMode::AsynchronousCompilation = self.cairo_native_run_mode() {

Suggestion:

                if self.cairo_native_run_mode() == CairoNativeRunMode::AsynchronousCompilation {

[ArniStarkware]

@ArniStarkware made 3 comments and resolved 2 discussions.
Reviewable status: complete! all files reviewed, all discussions resolved (waiting on ArniStarkware).

---

crates/blockifier/src/blockifier/config.rs line 299 at r4 (raw file):

Previously, avi-starkware (Avi Cohen) wrote…

1. Can be CairoNativeMode
2. The last variant can be CompilationWorkerThread instead, and I like WaitOnCompilation.
3. Use "snake_case" for readability.

Done, except for 2.a. I don't like CompilationWorkerThread. That is not a "mode"...

---

crates/blockifier/src/state/native_class_manager.rs line 165 at r5 (raw file):

            CompiledClasses::V0(_) => self.class_cache.set(class_hash, compiled_class),
            CompiledClasses::V1(compiled_class_v1, sierra_contract_class) => {
                if let CairoNativeRunMode::SynchronousCompilation = self.cairo_native_run_mode() {

Done.

---

crates/blockifier/src/state/native_class_manager.rs line 186 at r5 (raw file):

                );

                if let CairoNativeRunMode::AsynchronousCompilation = self.cairo_native_run_mode() {

Done.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

[avi-starkware]

@avi-starkware made 1 comment.
Reviewable status: 1 of 17 files reviewed, 1 unresolved discussion (waiting on ArniStarkware).

---

crates/blockifier/src/blockifier/config.rs line 299 at r4 (raw file):

Previously, ArniStarkware (Arnon Hod) wrote…

Done, except for 2.a. I don't like CompilationWorkerThread. That is not a "mode"...

It is just the terminology used in the native class manager. We call the thread responsible for compilation the "compilation worker".

The execution worker thread running the class either compiles the class itself and then runs it (in mode WaitOnCompilation), or sends a compilation request to the compilation worker thread and runs the casm in the VM instead of waiting.

We could call it DeferCompilation, DelegateCompilation, LazyCompilation, or something like that...

[ArniStarkware]

crates/blockifier/src/blockifier/config.rs line 299 at r4 (raw file):

Previously, avi-starkware (Avi Cohen) wrote…

It is just the terminology used in the native class manager. We call the thread responsible for compilation the "compilation worker".

The execution worker thread running the class either compiles the class itself and then runs it (in mode WaitOnCompilation), or sends a compilation request to the compilation worker thread and runs the casm in the VM instead of waiting.

We could call it DeferCompilation, DelegateCompilation, LazyCompilation, or something like that...

Done.

[avi-starkware]

@avi-starkware reviewed 16 files and all commit messages.
Reviewable status: complete! all files reviewed, all discussions resolved (waiting on ArniStarkware).

[avi-starkware]

Reviewable status: complete! all files reviewed, all discussions resolved (waiting on ArniStarkware).

[avi-starkware]

@avi-starkware made 1 comment.
Reviewable status: complete! all files reviewed, all discussions resolved (waiting on ArniStarkware).