Define a processor-independent native event-handler interface aligned with the Wasm ABI
- 主要语言
- Rust
- 星标
- 772
- 派生
- 352
- 平均合并
- 1 天 7 小时
- 30 天内合并 PR
- 84
描述
## 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.
贡献指南
调研方向
The work is in the `miden-event-handler` crate, implementing new traits (`EventHandler`, `TraceHandler`, `EventContext`) to replace deprecated ones in `miden_processor::event`. Start by reviewing PR #3438 for the migration guide and the current code structure. Focus on preserving the Wasm ABI and the `Host`/`SyncHost` callbacks. Testing involves compiling a minimal portable handler and verifying legacy and new semantics through registries and mixed libraries.
由索引模型根据 Issue 内容生成。
评估
- 技术栈
- rust, wasm
- 领域
- backend, compilers
- Issue 类型
- 重构
- 难度
- 5/5
- 预计耗时
- 一周以上
- 活跃度
- 活跃
- 描述清晰度
- 基本清楚
- 新手友好度
- 25/100