0xMiden / 0xMiden/miden-vm

Define a processor-independent native event-handler interface aligned with the Wasm ABI

Abierto
#3,761 0 comentarios 0 reacciones 0 asignados Ver en GitHub
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

Abrir la guía de contribución

Evaluación

Este issue todavía no se ha evaluado.

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.