feat: add engine failure monitoring

[bmuddha]

What changed

Operators can now watch live Engine loading and execution failures with magicblock monitor, without submitting a probe or receiving successful transactions. Aperture exposes a dedicated failure-only WebSocket subscription backed by Engine 0.15.0. Both Cargo workspaces use that release, and existing log and Geyser consumers now handle its shared transaction payloads.

The operator CLI uses concise tracing output, with complete failure diagnostics at debug level. Healthcheck and domain operations are simplified while retaining signing and execution-result checks. Repository docs are shorter, and the PR template no longer requires a closing issue reference.

Closes #1709.

Impact

Monitoring is live-only, bounded, and best effort. Slow receivers can disconnect silently; there is no replay, gap reporting, or automatic reconnection. Connection and subscription setup has a fixed 10-second deadline.

CLI outcomes, including healthcheck success, now go to stderr through tracing rather than stdout.

[coderabbitai]

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 40 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

• Configuration used: Repository: magicblock-labs/magicblock-validator/.coderabbit.yaml
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: 33d05ac6-a041-46a5-8c9a-6c5cfbe367c3

📥 Commits

Reviewing files that changed from the base of the PR and between e1af7b4 and 18d2369.

⛔ Files ignored due to path filters: 2

• Cargo.lock is excluded by !**/*.lock
• test-integration/Cargo.lock is excluded by !**/*.lock

📒 Files selected for processing: 25

• .github/PULL_REQUEST_TEMPLATE.md
• AGENTS.md
• Cargo.toml
• aperture/src/geyser.rs
• aperture/src/requests/mod.rs
• aperture/src/requests/websocket/log_subscribe.rs
• aperture/src/requests/websocket/mod.rs
• aperture/src/requests/websocket/transaction_failure_subscribe.rs
• aperture/src/server/websocket/dispatch.rs
• aperture/src/transaction.rs
• bins/magicblock/Cargo.toml
• bins/magicblock/README.md
• bins/magicblock/src/claim_fees.rs
• bins/magicblock/src/domain/client.rs
• bins/magicblock/src/domain/mod.rs
• bins/magicblock/src/healthcheck/deadline.rs
• bins/magicblock/src/healthcheck/expression.rs
• bins/magicblock/src/healthcheck/mod.rs
• bins/magicblock/src/main.rs
• bins/magicblock/src/monitor.rs
• docs/CONTRIBUTING.md
• docs/GOVERNANCE.md
• docs/RELEASE_PROCESS.md
• docs/SECURITY.md
• test-integration/Cargo.toml

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: magicblock-labs/magicblock-validator/.coderabbit.yaml
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: 71e64216-2d0f-4d5e-af8b-174ab0e9c9f9

📥 Commits

Reviewing files that changed from the base of the PR and between ca21b2e and e1af7b4.

⛔ Files ignored due to path filters: 2

• Cargo.lock is excluded by !**/*.lock
• test-integration/Cargo.lock is excluded by !**/*.lock

📒 Files selected for processing: 24

• .github/PULL_REQUEST_TEMPLATE.md
• Cargo.toml
• aperture/src/geyser.rs
• aperture/src/requests/mod.rs
• aperture/src/requests/websocket/log_subscribe.rs
• aperture/src/requests/websocket/mod.rs
• aperture/src/requests/websocket/transaction_failure_subscribe.rs
• aperture/src/server/websocket/dispatch.rs
• aperture/src/transaction.rs
• bins/magicblock/Cargo.toml
• bins/magicblock/README.md
• bins/magicblock/src/claim_fees.rs
• bins/magicblock/src/domain/client.rs
• bins/magicblock/src/domain/mod.rs
• bins/magicblock/src/healthcheck/deadline.rs
• bins/magicblock/src/healthcheck/expression.rs
• bins/magicblock/src/healthcheck/mod.rs
• bins/magicblock/src/main.rs
• bins/magicblock/src/monitor.rs
• docs/CONTRIBUTING.md
• docs/GOVERNANCE.md
• docs/RELEASE_PROCESS.md
• docs/SECURITY.md
• test-integration/Cargo.toml

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

📝 Walkthrough

The PR adds a WebSocket transaction-failure subscription and a CLI monitor. It also updates transaction data sharing, domain operations, healthcheck behavior, fee-claim logging, dependency versions, and repository guidance.

Changes: Transaction Failure Monitoring

Layer / File(s)	Summary
Shared transaction data Cargo.toml, test-integration/Cargo.toml, aperture/src/geyser.rs, aperture/src/transaction.rs, aperture/src/requests/websocket/log_subscribe.rs	Engine dependencies move to tag 0.15.0. Geyser delivery and transaction processing use shared transaction data. Log notifications read signatures, errors, and execution logs from processing results.
WebSocket failure subscription aperture/src/requests/mod.rs, aperture/src/requests/websocket/*, aperture/src/server/websocket/dispatch.rs	Aperture adds transaction-failure subscribe and unsubscribe methods. Failure notifications include transaction and execution details when available.
CLI failure monitor Cargo.toml, bins/magicblock/Cargo.toml, bins/magicblock/src/main.rs, bins/magicblock/src/monitor.rs, bins/magicblock/README.md	The CLI adds a monitor command that connects to Aperture, subscribes to failures, and reads notifications until Ctrl-C or a stream error. Documentation describes setup limits and monitor behavior.

Operator Command Updates

Layer / File(s)	Summary
Domain record operations bins/magicblock/src/domain/*, bins/magicblock/README.md	Synchronization consumes the record and submits its mutable fields. Unregister derives the PDA and sends the instruction without first fetching the record.
Healthcheck behavior and diagnostics bins/magicblock/src/healthcheck/*, bins/magicblock/README.md	The healthcheck waits for signature verification and an account notification within one deadline. Stage logs move to debug level; the arithmetic probe gains explanatory comments.
Operator CLI and fee-claim details bins/magicblock/src/claim_fees.rs, bins/magicblock/src/main.rs, bins/magicblock/README.md	Fee-claim logs report less transaction context. CLI documentation describes operator actions, configuration, and tracing output.

Repository Guidance

Layer / File(s)	Summary
Contribution and security guidance .github/PULL_REQUEST_TEMPLATE.md, docs/CONTRIBUTING.md, docs/GOVERNANCE.md, docs/SECURITY.md	The PR template makes issue links optional. Contribution, governance, and security documents replace detailed procedures with concise guidance.
Release process guidance docs/RELEASE_PROCESS.md	The guide updates release preparation, validation, publishing, and manual version-alignment instructions.

Priority: ➖ Normal

Estimated code review effort: 4 (Complex) | ~45 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant Monitor as monitor::Args
  participant WebSocket as Aperture WebSocket
  participant Dispatcher as WsDispatcher
  participant Engine as Engine failure stream
  Monitor->>WebSocket: Send transactionFailureSubscribe request
  WebSocket->>Dispatcher: Dispatch subscription request
  Dispatcher->>Engine: Subscribe to failure stream
  Engine-->>Dispatcher: Provide transaction processing result
  Dispatcher-->>WebSocket: Send serialized failure notification
  WebSocket-->>Monitor: Deliver JSON notification

Loading

Merge Risk: ⚪ Minimal · up to e1af7

This change adds a live-only, best-effort CLI monitor for Engine failures, updates the Engine dependency to 0.15.0, and simplifies operator commands and documentation. No concrete defect was identified, so the change appears ready to merge after normal checks.

Pre-merge checks: 5

Passed checks: 5 passed

Check name	Status	Explanation
Docstring Coverage		Docstring coverage is 86.84% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 38 functions across 15 files. (9 skipped: 9…
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.
Title check		The title clearly and concisely describes the main change: adding Engine failure monitoring.
Description check		The description accurately summarizes the monitoring feature, related Engine and Aperture changes, operational limits, and validation scope.

✨ Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}