Skip to content

extract shared cairo-native-syscalls crate#1611

Open
avi-starkware wants to merge 2 commits into
avi/cairo_native/syscall-trait-alignfrom
avi/cairo_native/syscall-types-crate
Open

extract shared cairo-native-syscalls crate#1611
avi-starkware wants to merge 2 commits into
avi/cairo_native/syscall-trait-alignfrom
avi/cairo_native/syscall-types-crate

Conversation

@avi-starkware
Copy link
Copy Markdown
Collaborator

Summary

Extracts the StarknetSyscallHandler trait and its supporting types into a new workspace-local crate, cairo-native-syscalls. Both cairo-native and sierra-emu re-export from it, so the two crates' types are now nominally identical — a single handler impl can drive both runtimes without an adapter.

Replaces the bridge approach from #1597 / #1607: with this PR landed, the bridge file isn't necessary, and #1608's Emu arm can call the cairo-native handler directly. Those follow-ups land in subsequent PRs in this stack.

Layout

cairo-native-syscalls/
  Cargo.toml      # deps: serde, starknet-types-core
  src/lib.rs      # types + trait

Sibling to test_utils/ at workspace root — fits the repo's existing convention for shared, non-binary, non-debug-tool crates.

What moved

From cairo-native/src/starknet.rs and sierra-emu/src/starknet/* into the new crate:

  • Types: U256, BlockInfo, TxInfo, TxV2Info, TxV3Info, ResourceBounds, ExecutionInfo, ExecutionInfoV2, ExecutionInfoV3, Secp256k1Point, Secp256r1Point.
  • Trait: StarknetSyscallHandler, including its existing default cheatcode impl.
  • Constructors: Secp256k1Point::new / Secp256r1Point::new (pure-data).
  • Alias: SyscallResult<T>.

Repr / serde / derive layouts preserved exactly (#[repr(C, align(16))] on U256, Secp256{k1,r1}Point).

What stayed put

  • cairo-native: ArrayAbi, Felt252Abi, DummySyscallHandler, the runtime/codegen vtables (handler::StarknetSyscallHandlerCallbacks, cairo_native__vtable_cheatcode, etc.) — all cairo-native-specific.
  • sierra-emu: StubSyscallHandler, StubEvent, ContractLogs, and the VM eval logic.

Value-conversion methods

Sierra-emu previously had impl <Type> { fn into_value(self) -> Value, fn from_value(v: Value) -> Self } on each type. Inherent impls can't follow the type into a foreign crate, so these become free functions in a new sierra_emu::starknet::value_conv module:

Before After
U256::from_value(v) u256_from_value(v)
u.into_value() u256_into_value(u)
Secp256k1Point::from_value(v) secp256k1_point_from_value(v)
info.into_value(felt_ty) execution_info_into_value(info, felt_ty)
... (same pattern for each type)

Call sites in sierra-emu/src/vm/starknet.rs and cairo-native/src/metadata/trace_dump.rs updated.

Backwards compatibility

  • cairo-native users: backwards-compatible. cairo_native::starknet::U256, …::StarknetSyscallHandler, etc. still resolve via pub use. Existing impls and callers compile unchanged. No semver-breaking change.
  • sierra-emu users: breaking — the inherent into_value / from_value methods are gone. Sierra-emu is debug-only and not an externally published API surface; callers in this repo are all updated.
  • The 11 per-type files under debug_utils/sierra-emu/src/starknet/* are deleted now that the struct defs live in the shared crate.

Stack

  1. align sierra-emu StarknetSyscallHandler trait/types with cairo-native #1610 — align trait/type surfaces ← prerequisite
  2. this PR — extract the shared crate
  3. (next) ContractExecutor dispatch enum without the bridge (replaces add ContractExecutor dispatch enum (Aot + Emu) #1598 / add ContractExecutor dispatch enum (Aot + Emu) #1608)
  4. (next) run_with_libfunc_profile + AotWithProgram (rebase of add run_with_libfunc_profile + AotWithProgram variant for ContractExecutor #1599 / add run_with_libfunc_profile + AotWithProgram variant for ContractExecutor #1609)

Test plan

  • cargo check --workspace --all-features clean
  • cargo check -p sierra-emu --all-targets clean
  • CI green

@github-actions
Copy link
Copy Markdown

github-actions Bot commented May 14, 2026

✅ Code is now correctly formatted.

avi-starkware and others added 2 commits May 14, 2026 15:30
Both cairo-native and sierra-emu now re-export the StarknetSyscallHandler
trait and supporting types (U256, Block/Tx/Execution Info v{1,2,3},
ResourceBounds, Secp256{k1,r1}Point) from the new
`cairo-native-syscalls` crate. The crate is workspace-local at the top
level (sibling to `test_utils/`).

The two crates' types are now nominally identical, so a single handler
impl can drive both runtimes without an adapter / bridge.

sierra-emu's previous inherent into_value/from_value methods (which
depend on sierra-emu's `Value` enum and can't follow the moved types)
become free functions in the new sub-module
`sierra_emu::starknet::value_conv`. Callers updated.

The per-type files under debug_utils/sierra-emu/src/starknet/* are
deleted now that the struct definitions live in the shared crate.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Default impl previously panicked with unimplemented!(). On the sierra-emu
path, a contract that invokes the `cheatcode` libfunc against a handler
that didn't override the method would unwind through the VM and abort
the host. Production handlers (e.g. the blockifier's NativeSyscallHandler)
don't implement cheatcode at all, so the default impl is what runs.

Soft-fail with a single error felt instead, so misuse manifests as a
normal syscall error rather than an unhandled panic. Test handlers that
implement cheatcode override the default and are unaffected.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@avi-starkware avi-starkware force-pushed the avi/cairo_native/syscall-trait-align branch from 7698d47 to a37920a Compare May 14, 2026 12:33
@avi-starkware avi-starkware force-pushed the avi/cairo_native/syscall-types-crate branch from 319a6be to 92ecf03 Compare May 14, 2026 12:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant