feat: introduce EVENT_INDEXED_V3 topic with dual-emit migration path

README.md

@@ -101,6 +101,32 @@ Auth failures (e.g. wrong signer) are signaled by host/panic, not `RevoraError`.
 | `iss_acc` | `(token), (old_issuer, new_issuer)` | When `accept_issuer_transfer` completes the transfer. |
 | `iss_canc` | `(token), (current_issuer, proposed_new_issuer)` | When `cancel_issuer_transfer` revokes a pending transfer. |
 | `test_mode` | `(admin), enabled` | When `set_testnet_mode` is called to toggle testnet mode. |
+| `ev_idx2` (V2) | `(version, event_type, issuer, namespace, token, period_id), (event_data...)` | Indexed V2 event — emitted by all state-changing entries for off-chain indexers. |
+| `ev_idx3` (V3) | `(version, event_type, issuer, namespace, token, period_id, _reserved), (event_data...)` | Indexed V3 event — dual-emitted alongside V2. Additive fields land here in future minor versions. |
+
+#### Indexed Event Versioning
+
+The contract maintains two concurrent indexed event topics: `ev_idx2` (V2) and `ev_idx3` (V3). Both are emitted
+by all state-changing entries via the `emit_v2_and_v3` helper. V2 subscribers continue to receive V2 events
+unchanged at the `ev_idx2` topic. V3 subscribers consume the `ev_idx3` topic which carries version=3 and a
+`_reserved` field for additive schema evolution.
+
+**Migration table: V2 → V3**
+
+| Field | V2 (`EventIndexTopicV2`) | V3 (`EventIndexTopicV3`) | Notes |
+|-------|--------------------------|--------------------------|-------|
+| `version` | `2` | `3` | Schema version discriminator |
+| `event_type` | `Symbol` | `Symbol` | Unchanged |
+| `issuer` | `Address` | `Address` | Unchanged |
+| `namespace` | `Symbol` | `Symbol` | Unchanged |
+| `token` | `Address` | `Address` | Unchanged |
+| `period_id` | `u64` | `u64` | Unchanged; 0 when not period-scoped |
+| `_reserved` | — | `u32` | **New in V3.** Reserved for future additive fields (e.g. `share_class`, `tax_bucket`). Always `0` in current version. |
+
+**Deprecation policy:** `ev_idx2` will continue to be emitted for at least two contract minor versions
+after the introduction of `ev_idx3`. V2-only subscribers are safe during this deprecation window.
+After the deprecation window, V2 emission may be removed. V3 subscribers should validate the `version`
+field and ignore events where `version != 3`.
 
 ### Call patterns and limits
 

docs/core-event-version-field.md

@@ -139,5 +139,41 @@ Tests live in `src/test_indexer_fixtures.rs`.
 **Success Criteria**: 100% core events emit `(2u32, ...v2_data)` with correct topic, verified
 by automated tests in `src/test_indexer_fixtures.rs`.
 
+**Upgrade Path**: v3 bumps EVENT_SCHEMA_VERSION_V2 → 3 when storage schemas change.
+See `INDEXER_EVENT_SCHEMA_VERSION = 3` and the `EventIndexTopicV3` struct for the active schema.
+
+## Indexer Event Versioning (V2 → V3)
+
+### What Changed
+
+- Added `EVENT_INDEXED_V3` topic constant (`ev_idx3`).
+- Added `EventIndexTopicV3` struct — same shape as V2 plus a `_reserved: u32` field for future additive fields.
+- Added `emit_v2_and_v3()` helper that publishes both V2 and V3 events from all state-changing entries.
+- Bumped `INDEXER_EVENT_SCHEMA_VERSION` from 2 to 3.
+
+### Dual-Emission Strategy
+
+All state-changing entries now call `emit_v2_and_v3()` which publishes:
+1. **V2 event** at `EVENT_INDEXED_V2` (`ev_idx2`) with `version=2` — unchanged for existing subscribers.
+2. **V3 event** at `EVENT_INDEXED_V3` (`ev_idx3`) with `version=3` — for forward-compatible indexers.
+
+### Deprecation Policy
+
+- V2 events continue to emit for at least **two contract minor versions** after V3 introduction.
+- V2-only subscribers are safe during this window.
+- After the deprecation window, V2 emission may be removed.
+- V3 subscribers should validate `version == 3` and reject mismatches.
+
+### Migration Table
+
+| Aspect | V2 | V3 |
+|--------|----|----|
+| Topic symbol | `ev_idx2` | `ev_idx3` |
+| Struct | `EventIndexTopicV2` | `EventIndexTopicV3` |
+| `version` field | `2` | `3` |
+| `_reserved` | N/A | `u32` (always `0`) |
+| Emission | `env.events().publish((EVENT_INDEXED_V2, ...), ...)` | dual-emitted via `emit_v2_and_v3` |
+| Subscriber impact | Unchanged | New topic, validate version |
+
 **Upgrade Path**: v3 will bump `EVENT_SCHEMA_VERSION_V2 → 3` when storage schemas change;
 the constant guard test will catch any accidental early bump.