0.7.57

docs/reports/METEORA_DLMM_EVENT_COVERAGE_REPORT.md

@@ -0,0 +1,182 @@
+# Meteora DLMM event coverage report — 0.7.57 final
+
+## Scope
+
+Version `0.7.57` closes `meteora_dlmm` from the local IDL and the dedicated local corpus.
+
+Target program:
+
+```text
+LBUZKhRxPF3XUpBCjp4YzTKgLccjZhTSDM9YuVaPwxo
+```
+
+Local IDL:
+
+```text
+idls/meteora_dlmm.LBUZKhRxPF3XUpBCjp4YzTKgLccjZhTSDM9YuVaPwxo.json
+```
+
+Final inventoried surface:
+
+```text
+76 IDL instructions
+30 Anchor events
+12 accounts
+```
+
+The local corpus additionally identified discriminator `75c73e67068e1fcb` as `initialize_preset_parameter_v2`. This discriminator was not present in the local IDL under that spelling, but the transaction logs contain `Instruction: InitializePresetParameterV2`, the account layout is stable, and the instruction creates a 36-byte DLMM-owned preset parameter account through the system program.
+
+## Final validation summary
+
+```text
+cargo test -p kb_lib -> 460 passed / 0 failed
+cargo clippy -p kb_lib --all-targets -- -D warnings -> OK
+769 replayed
+0 decode skipped
+769 ledger upserts
+646 unsafe ledger rows
+106 trades
+664 liquidity
+1107 lifecycle
+0 tokenAccount
+424 candle upserts
+instructionObservations = 8062
+resetDeleted = 9898
+catalog = 169 tokens / 218 pools / 218 pairs
+```
+
+## Closure checks
+
+All blocking checks are clean:
+
+```text
+upstream_git fallback for locally covered meteora_dlmm entries -> empty
+local instruction_audit observed -> 0
+DLMM decoded events without coverage -> empty
+successful non-materialized DLMM without explicit skip/policy -> empty
+failed transaction business materialization -> empty
+multi-target materialization -> empty
+non-swap trade/candle safety -> empty
+fee parent scalar without fee amount leg -> empty
+orphan fee amount legs -> empty
+limit/orderbook trade/candle double-count -> empty
+logical duplicate coverage rows -> empty
+```
+
+The only coverage difference left is explained and non-blocking:
+
+```text
+close_bin_array observed 16 / materialized 14
+14 successful transactions -> lifecycle materialized
+2 failed transactions Custom 6015 -> decoded/audit only, no business materialization
+```
+
+## Materialization policy
+
+### Trades and candles
+
+Only instruction-level DLMM swaps can produce trades/candles:
+
+```text
+meteora_dlmm.swap
+meteora_dlmm.swap2
+meteora_dlmm.swap_exact_out
+meteora_dlmm.swap_exact_out2
+meteora_dlmm.swap_with_price_impact
+meteora_dlmm.swap_with_price_impact2
+```
+
+Anchor `swap_event` and `swap2_evt` are materialized as lifecycle `swap_log` rows and never as trades/candles. This prevents double-counting when an instruction swap and an Anchor log describe the same user-visible swap.
+
+### Liquidity and lifecycle
+
+The following families are materialized when transactions are successful and context is reliable:
+
+```text
+add_liquidity*
+remove_liquidity*
+remove_all_liquidity
+rebalance_liquidity
+initialize_bin_array*
+close_bin_array
+go_to_a_bin*
+initialize_position*
+close_position*
+increase_position_length*
+decrease_position_length*
+update_position_operator*
+lb_pair_create_event
+position_create_event
+position_close_event
+```
+
+Position and bin lifecycle events are routed to `k_sol_pool_lifecycle_events` when the operation is structural rather than a direct liquidity amount delta.
+
+### Fees
+
+Fee parents are written to `k_sol_fee_events`. Amount legs are written to `k_sol_fee_event_amounts`.
+
+Final observed amount-leg summary:
+
+```text
+claim_fee                  64 parents /  64 legs
+claim_fee2                 63 parents /  88 legs
+claim_fee_event           127 parents / 187 legs
+claim_fee2_event           78 parents / 118 legs
+composition_fee_event      51 parents /  63 legs
+withdraw_protocol_fee      14 parents /  20 legs
+zap_protocol_fee           13 parents /  13 legs
+```
+
+The inner SPL transfer recovery is explicitly allowlisted for DLMM fee event kinds. It is not inherited globally by future decoders.
+
+### Rewards
+
+Reward parents are written to `k_sol_reward_events`. Amounts are recovered only when a reliable inner SPL transfer or decoded amount is present.
+
+Final observed scalar amount summary:
+
+```text
+claim_reward               15 parents /  1 scalar amount
+claim_reward2              19 parents / 10 scalar amounts
+claim_reward_event         34 parents / 25 scalar amounts
+claim_reward2_event        19 parents / 10 scalar amounts
+fund_reward                10 parents / 10 scalar amounts
+fund_reward_event          10 parents / 10 scalar amounts
+initialize_reward           9 parents /  0 amount
+initialize_reward_event     9 parents /  0 amount
+```
+
+`initialize_reward` and `initialize_reward_event` remain without amount because they are configuration/initialization events, not executed reward transfers. No amount is fabricated from limits, bounds or configuration fields.
+
+### Admin/config and orderbook
+
+Admin/config events materialize to `k_sol_pool_admin_events`. Limit-order operations materialize to `k_sol_orderbook_events` and never to trade/candle tables.
+
+Important promoted local corpus entry:
+
+```text
+75c73e67068e1fcb -> meteora_dlmm.initialize_preset_parameter_v2 -> k_sol_pool_admin_events
+```
+
+## Remaining non-observed surfaces
+
+Non-observed IDL/account rows remain in coverage with `observed_count = 0` and `materialized_count = 0`. They are not blockers.
+
+Examples:
+
+```text
+update_reward_duration
+update_reward_funder
+withdraw_ineligible_reward
+migrate_position
+account metadata rows
+for_idl_type_generation_do_not_call
+anchor_self_cpi_log registry row
+```
+
+## Decision
+
+`0.7.57 meteora_dlmm` is closed. Do not add further DLMM Rust patches unless a new corpus proves a successful transaction that is decoded but not materialized and lacks an explicit skip/policy reason.
+
+Next recommended work is not another DLMM patch: implement `0.7.58 demo4_program_surface_discovery` to display unknown or unsupported program surfaces without automatic materialization or automatic decoder promotion.