Define a processor-independent native event-handler interface aligned with the Wasm ABI
- Lenguaje dominante
- Rust
- Estrellas
- 772
- Forks
- 352
- Merge medio
- 1 d 12 h
- PR fusionados (30 d)
- 93
Descripción
## Objective
Provide processor-independent native event and trace implementations in the sibling `miden-event-handler` crate, aligned with the capabilities of the current Wasm ABI. Implement the v0.33 transition in [PR #3438](https://github.com/0xMiden/miden-vm/pull/3438); retire legacy interfaces and migrate custom hosts in v0.34.
The complete migration guide is published in the PR description. That guide covers dependency/import changes, explicit compatibility registration, full migration, functions/closures/shared handles, mixed libraries, replacement, traces, payload offsets, current/root memory, missing-versus-zero behavior, advice/Merkle reads, clock/error conversions, and protocol-shaped custom hosts.
## v0.33 requirements
- New traits/context: `miden_event_handler::{EventHandler, TraceHandler, EventContext}`. A minimal implementation has only `miden-event-handler` as a direct dependency, including `no_std`.
- Original deprecated traits remain at `miden_processor::event::{EventHandler, TraceHandler}`; preserve the real `ProcessorState`, its original read APIs and return types, and `FastProcessor::state()`.
- Preserve `Host`/`SyncHost` event and trace callbacks and registry dispatch accepting `&ProcessorState`, including state borrowed across an await. This is not the release that changes host callback signatures.
- Processor-owned cloneable `event::registration::{EventHandler, TraceHandler}` enums contain `Context(Arc)` and `Legacy(Arc)`. Concrete portable handlers/functions/typed closures use `From`; old handlers require `legacy(handler)`; shared handles use variants with no overlapping automatic Arc conversions.
- Registration/replacement accept `impl Into`, normalize before storage, and use the same values in `HostLibrary`, its setter, and processor-facing core/Wasm handler lists. Preserve the protocol's inferred core-library registration loop.
- Legacy dispatch receives the original state. Portable dispatch derives semantic IDs, payload offsets, clock, and root status from the actual event/trace invocation, independently of any custom registry routing key.
- Preserve name validation, duplicate behavior, replacement/unregistration, atomic library loading, and one advice-mutation validation/application path for both generations.
- Remove the `ProcessorState = EventContext` alias, deprecated portable forwarding methods, and processor re-exports of new portable traits/context/metadata. Preserve compatibility paths that predate the PR, including shared errors and advice mutations.
- Keep Greenhat's Wasm ABI unchanged and keep the independent logical-stack hash fix separate. Do not modify the protocol repository in this PR.
- Add self-contained migration rustdoc on the old event trait, corresponding trace guidance, and a state retirement note, all linking to the published guide. Update changelog and crate summaries. The full local authoring guide stays untracked and must never be a link target in published documentation.
## Acceptance
Compile a minimal portable handler with only the portable crate, including `no_std`. Verify old trait/state deprecation diagnostics and new-only callers with deprecations denied. Exercise genuine legacy stack, numeric-context memory, advice-provider, clock, and error semantics alongside portable handlers through event/trace registries and mixed libraries. Cover synchronous/asynchronous custom hosts, borrowed state across an await, core-library-first dispatch, and unchanged error/advice propagation. Retain metadata, payload-offset, current/root memory, missing-versus-zero, zero-extension, and mutation/library atomicity tests. Validate guide examples, real compiled Wasm guests, relevant features, rustdoc, formatting, and repository lints.
Protocol `next` at `87fefc02ed29d162cf065a42045b37ba87e6308f` supplied the downstream patterns. Local fixtures cover them; downstream protocol compilation remains unverified.
## v0.34 follow-up (documented, not implemented here)
- Migrate legacy registered implementations, then remove the old traits, real `ProcessorState`, `FastProcessor::state()`, legacy registration variants/constructors, and temporary migration rustdoc.
- Change host callbacks and registry dispatch to `&EventContext`, preserving core-library-first dispatch and async delegation. Migrate transaction extraction and LinkMap payload offsets, kernel/memory viewers, attachment advice-map helpers, progress clocks, and application error mappings together.
- Audit compatibility exports, shared-handle factories, and deprecation suppressions. Run downstream protocol compilation and its transaction/executor/prover, memory, advice/Merkle, and async tests before completing the removal.
- Keep the portable capability boundary: no numeric/arbitrary-context selector, concrete advice provider, full execution options, or general processor/deferred-state escape hatch.
Guía de contribución
Evaluación
Este issue todavía no se ha evaluado.