[alabiopeyemi]

Comprehensive Implementation Summary: Versioned Option Lifecycle Events

📌 Issue Overview

Issue Reference: #1467
Title: Emit versioned lifecycle events for option positions
Area: contracts/options

The options contract previously emitted ad-hoc event pairs without a schema
version, and partial exercises reused the full-exercise topic. This PR replaces
those lifecycle emissions with a single versioned schema that consistently
identifies the position and covers creation, fill, exercise, expiry, and
cancellation.

---

🏗️ Architecture & Core Design Decisions

1. One stable event envelope

Every position transition now publishes one event with:

• Topics: (kind, option_id, schema_version)
• Data: OptionLifecycleEvent

kind is one of create, fill, exercise, expire, or cancel. The
position id is available both as a topic and inside the payload, while
schema_version is 1 for the current layout.

2. Complete, self-describing payload

OptionLifecycleEvent carries enough data for indexers and clients to decode a
transition without additional calls:

• position id, option type
• minter and actor
• underlying, quote, and collateral assets
• strike price and exercise window
• collateral amount
• amount moved by this transition
• cumulative exercised amount
• remaining collateral
• ledger timestamp

3. Consistent lifecycle mapping

• create — emitted by mint after collateral is escrowed.
• fill — emitted when an exercise partially consumes the remaining collateral.
• exercise — emitted when the position is fully exercised.
• expire — emitted when unexercised collateral is returned after expiry.
• cancel — emitted when the minter cancels and receives unexercised collateral.

No storage layout, public method signature, or collateral accounting behavior
changed. deposit and withdraw retain their existing events.

---

📁 File-by-File Detailed Breakdown

1. contracts/options/src/events.rs (New)

• Defines OPTION_EVENT_SCHEMA_VERSION = 1.
• Defines the shared OptionLifecycleEvent contract type.
• Adds emitters for create, fill, exercise, expire, and cancel.
• Centralizes topic construction as (kind, option_id, schema_version).

2. contracts/options/src/lib.rs

• Registers the new events module.
• Replaces the legacy lifecycle publishes in mint, settle, expire, and
  cancel with the versioned emitters.
• Emits fill for partial exercises and exercise once the position is fully
  consumed.

3. contracts/options/src/tests.rs

• Adds versioned_lifecycle_events coverage for:
  • creation fields and schema version
  • create → fill → exercise ordering and cumulative amounts
  • full exercise without a fill event
  • expiry after a partial fill
  • cancellation after a partial fill
• Each test decodes the event payload and asserts the position id, kind,
  schema version, actor, amount, exercised total, and remaining collateral.

4. contracts/options/README.md

• Documents the versioned event envelope, payload fields, and lifecycle kinds.

---

✅ Automated Verification & CI Results

Verification Type	Command	Result
Options test suite	cargo test -p options --lib	72 passed; 0 failed (5 new lifecycle-event tests)
Clippy	cargo clippy -p options --all-targets -- -D warnings ...	Passed
Formatting	cargo fmt -p options -- --check	Passed

Closes #1467

[github-actions]

Good job.

[vercel]

@alabiopeyemi is attempting to deploy a commit to the Edeh Victor's projects Team on Vercel.

A member of the Team first needs to authorize it.