0xMiden / 0xMiden/miden-vm

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

未关闭
#3,761 0 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看
主要语言
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

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。