add EmuContractExecutor (sierra-emu backend, interchangeable with AotContractExecutor)

[avi-starkware]

Summary

Makes the sierra-emu interpreter usable as a drop-in alternative to AotContractExecutor at contract call sites — without a dispatch enum. No consumer selects a backend at runtime (the choice is always made per build by feature flags), so consumers pick an executor type per build instead of wrapping every executor in an enum on the production path.

An earlier revision of this PR introduced a ContractExecutor dispatch enum (Aot + Emu); per review it's gone — no consumer, in-tree or out, ever picked a variant at runtime, so the enum's match was ceremony around a decision the build's feature flags had already made.

Changes

• debug_utils/sierra-emu: new VirtualMachine::run_contract(...) — one-shot convenience over new_starknet + call_contract + run. Returns None when the VM never produced a final state.
• src/executor/emu_contract_executor.rs (new, gated on the new sierra-emu cargo feature): EmuContractExecutor { program, entry_points, sierra_version } with an inherent run() that mirrors AotContractExecutor::run — same parameter shape, same StarknetSyscallHandler trait (shared via cairo-native-syscalls, so the handler flows through unchanged). Converts BuiltinCosts and the emu result into cairo-native's ContractExecutionResult (with default builtin_stats).
• Cargo.toml: new sierra-emu = ["dep:sierra-emu"] feature; with-trace-dump now depends on the feature rather than the optional dep directly.

Stack

1. align sierra-emu StarknetSyscallHandler trait/types with cairo-native #1610 — trait alignment
2. extract shared cairo-native-syscalls crate #1611 — extract shared crate
3. this PR — sierra-emu contract executor
4. add run_with_libfunc_profile + AotWithProgram pairing #1613 — run_with_libfunc_profile + AotWithProgram

Test plan

• cargo check (default features) clean
• cargo check --features sierra-emu clean
• cargo check --workspace --all-features clean (on stack tip)
• CI green

---

This change is

[github-actions]

✅ Code is now correctly formatted.

[orizi]

@orizi made 1 comment.
Reviewable status: 0 of 23 files reviewed, 1 unresolved discussion (waiting on avi-starkware, TomerStarkware, and Yoni-Starkware).

---

-- commits line 1 at r2:
is this missing a rebase?

[github-actions]

Benchmarking results

Benchmark for program dict_insert

Open benchmarks

Command	Mean [s]	Min [s]	Max [s]	Relative
Cairo-vm (Rust, Cairo 1)	10.644 ± 0.209	10.461	11.181	5.75 ± 0.12
cairo-native (embedded AOT)	1.852 ± 0.015	1.825	1.869	1.00
cairo-native (embedded JIT using LLVM's ORC Engine)	1.870 ± 0.020	1.850	1.910	1.01 ± 0.01

Benchmark for program dict_snapshot

Open benchmarks

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
Cairo-vm (Rust, Cairo 1)	515.1 ± 2.2	512.9	519.3	1.00
cairo-native (embedded AOT)	1601.1 ± 11.6	1584.5	1619.4	3.11 ± 0.03
cairo-native (embedded JIT using LLVM's ORC Engine)	1632.1 ± 13.5	1618.4	1661.9	3.17 ± 0.03

Benchmark for program factorial_2M

Open benchmarks

Command	Mean [s]	Min [s]	Max [s]	Relative
Cairo-vm (Rust, Cairo 1)	4.657 ± 0.013	4.639	4.679	2.77 ± 0.03
cairo-native (embedded AOT)	1.682 ± 0.016	1.660	1.715	1.00
cairo-native (embedded JIT using LLVM's ORC Engine)	1.700 ± 0.023	1.677	1.747	1.01 ± 0.02

Benchmark for program fib_2M

Open benchmarks

Command	Mean [s]	Min [s]	Max [s]	Relative
Cairo-vm (Rust, Cairo 1)	4.579 ± 0.016	4.549	4.603	2.83 ± 0.03
cairo-native (embedded AOT)	1.619 ± 0.017	1.595	1.648	1.00
cairo-native (embedded JIT using LLVM's ORC Engine)	1.645 ± 0.011	1.630	1.667	1.02 ± 0.01

Benchmark for program linear_search

Open benchmarks

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
Cairo-vm (Rust, Cairo 1)	561.3 ± 6.2	552.7	571.8	1.00
cairo-native (embedded AOT)	1637.1 ± 9.4	1626.6	1653.4	2.92 ± 0.04
cairo-native (embedded JIT using LLVM's ORC Engine)	1673.5 ± 14.7	1658.3	1703.4	2.98 ± 0.04

Benchmark for program logistic_map

Open benchmarks

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
Cairo-vm (Rust, Cairo 1)	478.7 ± 7.7	466.7	491.8	1.00
cairo-native (embedded AOT)	1606.7 ± 10.2	1584.7	1621.7	3.36 ± 0.06
cairo-native (embedded JIT using LLVM's ORC Engine)	1625.1 ± 7.5	1615.4	1637.5	3.39 ± 0.06

[github-actions]

Benchmark results Main vs HEAD.

Base

Command	Mean [s]	Min [s]	Max [s]	Relative
base dict_insert.cairo (JIT)	1.788 ± 0.005	1.780	1.794	1.00 ± 0.01
base dict_insert.cairo (AOT)	1.783 ± 0.008	1.772	1.798	1.00

Head

Command	Mean [s]	Min [s]	Max [s]	Relative
head dict_insert.cairo (JIT)	2.010 ± 0.042	1.959	2.080	1.00
head dict_insert.cairo (AOT)	2.018 ± 0.042	1.967	2.097	1.00 ± 0.03

Base

Command	Mean [s]	Min [s]	Max [s]	Relative
base dict_snapshot.cairo (JIT)	1.618 ± 0.011	1.600	1.633	1.02 ± 0.01
base dict_snapshot.cairo (AOT)	1.592 ± 0.012	1.579	1.614	1.00

Head

Command	Mean [s]	Min [s]	Max [s]	Relative
head dict_snapshot.cairo (JIT)	1.793 ± 0.046	1.753	1.889	1.00
head dict_snapshot.cairo (AOT)	1.817 ± 0.044	1.761	1.903	1.01 ± 0.04

Base

Command	Mean [s]	Min [s]	Max [s]	Relative
base factorial_2M.cairo (JIT)	1.676 ± 0.012	1.654	1.690	1.01 ± 0.01
base factorial_2M.cairo (AOT)	1.659 ± 0.017	1.633	1.690	1.00

Head

Command	Mean [s]	Min [s]	Max [s]	Relative
head factorial_2M.cairo (JIT)	1.888 ± 0.033	1.833	1.937	1.03 ± 0.03
head factorial_2M.cairo (AOT)	1.841 ± 0.032	1.792	1.885	1.00

Base

Command	Mean [s]	Min [s]	Max [s]	Relative
base fib_2M.cairo (JIT)	1.615 ± 0.005	1.609	1.622	1.01 ± 0.01
base fib_2M.cairo (AOT)	1.594 ± 0.013	1.580	1.618	1.00

Head

Command	Mean [s]	Min [s]	Max [s]	Relative
head fib_2M.cairo (JIT)	1.761 ± 0.028	1.711	1.811	1.00 ± 0.02
head fib_2M.cairo (AOT)	1.760 ± 0.014	1.737	1.776	1.00

Base

Command	Mean [s]	Min [s]	Max [s]	Relative
base linear_search.cairo (JIT)	1.640 ± 0.011	1.624	1.659	1.02 ± 0.01
base linear_search.cairo (AOT)	1.607 ± 0.011	1.586	1.619	1.00

Head

Command	Mean [s]	Min [s]	Max [s]	Relative
head linear_search.cairo (JIT)	1.874 ± 0.024	1.828	1.901	1.05 ± 0.03
head linear_search.cairo (AOT)	1.791 ± 0.039	1.742	1.876	1.00

Base

Command	Mean [s]	Min [s]	Max [s]	Relative
base logistic_map.cairo (JIT)	1.624 ± 0.007	1.612	1.632	1.02 ± 0.01
base logistic_map.cairo (AOT)	1.592 ± 0.011	1.578	1.608	1.00

Head

Command	Mean [s]	Min [s]	Max [s]	Relative
head logistic_map.cairo (JIT)	1.834 ± 0.032	1.803	1.890	1.04 ± 0.02
head logistic_map.cairo (AOT)	1.767 ± 0.028	1.718	1.806	1.00

[avi-starkware]

-- commits line 1 at r2:

Previously, orizi wrote…

is this missing a rebase?

Done.

[orizi]

@orizi reviewed 22 files and all commit messages, and made 1 comment.
Reviewable status: 22 of 23 files reviewed, 2 unresolved discussions (waiting on avi-starkware, TomerStarkware, and Yoni-Starkware).

---

src/executor/contract_executor.rs line 107 at r3 (raw file):

                    builtin_stats: Default::default(),
                })
            }

any reason to not just add this into sierra-emu and not need this entire new execute file?

Code quote:

                let mut virtual_machine = sierra_emu::VirtualMachine::new_starknet(
                    Arc::clone(program),
                    entry_points,
                    *sierra_version,
                );

                let emu_builtin_costs = builtin_costs.map(convert_builtin_costs);

                virtual_machine.call_contract(selector, gas, args.to_vec(), emu_builtin_costs);

                // `VirtualMachine::run` returns `None` when the VM never produced a
                // final state -- propagate as an error rather than aborting the host.
                let result = virtual_machine.run(&mut syscall_handler).ok_or_else(|| {
                    Error::UnexpectedValue("sierra-emu VM produced no final state".to_string())
                })?;

                Ok(ContractExecutionResult {
                    remaining_gas: result.remaining_gas,
                    failure_flag: result.failure_flag,
                    return_values: result.return_values,
                    error_msg: result.error_msg,
                    builtin_stats: Default::default(),
                })
            }

[avi-starkware]

src/executor/contract_executor.rs line 107 at r3 (raw file):

Previously, orizi wrote…

any reason to not just add this into sierra-emu and not need this entire new execute file?

I removed the ContractExecutor enum and replaced it with a type alias (also removed this file).

I looked at the code and at how lambdaclass used it for replay, and there is no dynamic dispatch of Contract executor types. The type used is determined at compile time. So I think we can safely remove this.

[orizi]

@orizi made 1 comment.
Reviewable status: 21 of 25 files reviewed, 2 unresolved discussions (waiting on avi-starkware, TomerStarkware, and Yoni-Starkware).

---

-- commits line 1 at r2:

Previously, avi-starkware (Avi Cohen) wrote…

Done.

are you sure? this seems to contain 4 commits.

[orizi]

@orizi reviewed 4 files and resolved 1 discussion.
Reviewable status: all files reviewed (commit messages unreviewed), 1 unresolved discussion (waiting on avi-starkware, TomerStarkware, and Yoni-Starkware).

[avi-starkware]

@avi-starkware made 1 comment.
Reviewable status: all files reviewed (commit messages unreviewed), 1 unresolved discussion (waiting on orizi, TomerStarkware, and Yoni-Starkware).

---

-- commits line 1 at r2:

Previously, orizi wrote…

are you sure? this seems to contain 4 commits.

Done.

[orizi]

@orizi reviewed all commit messages, made 1 comment, and resolved 1 discussion.
Reviewable status: complete! all files reviewed, all discussions resolved (waiting on TomerStarkware and Yoni-Starkware).