khadhroony-bobobot/docs/RAYDIUM_LAUNCHPAD_EVENT_COVERAGE_REPORT.md

# Raydium Launchpad event coverage report — `0.7.50`

## Scope

`0.7.50` opens the `raydium_launchpad` tranche after the functional closure of `0.7.49 raydium_clmm`.

Local canonical decoder/surface code:

```text
raydium_launchpad
```

Canonical program id:

```text
LanMV9sAd7wArD4vJFi2qDdfnVhFxYSUg6eADduJ3uj
```

The legacy local name `raydium_launchlab` is not kept in the public Rust API. Coverage rows, upstream registry rows, launch origin entries, and support matrix rows use `raydium_launchpad`.

## Sources used

Primary source hints for this tranche:

- Carbon decoder registry/source: `sevenlabs-hq/carbon/decoders/raydium-launchpad-decoder`.
- Solscan Program IDL/account page: `https://solscan.io/account/LanMV9sAd7wArD4vJFi2qDdfnVhFxYSUg6eADduJ3uj#programIdl`.
- fnzero IDL sources: `sol-parser-sdk` / `solana-program-idls` listings, including `raydium_launchpad.json` and separate `raydium_pool_v4.json` as an audit-only source.
- Raydium SDK Launchpad examples for account-shape hints only.

These sources are not treated as final business proof. Promotion still requires local corpus observation and SQL validation.

## Bootstrap implementation delta

Implemented in this delta:

- `RAYDIUM_LAUNCHPAD_PROGRAM_ID` added as the canonical public constant.
- Upstream generated registry rows normalized from `raydium_launchlab` to `raydium_launchpad`.
- Built-in launch surface code normalized to `raydium_launchpad`.
- DEX support/catalog entries normalized to `raydium_launchpad`.
- Raydium instruction audit fallback now recognizes Launchpad program id.
- Launchpad mapped instruction fallback added for locally listed Launchpad discriminators.
- Coverage target override keeps Launchpad rows `decoded_events_only` until corpus promotion.
- SQL validation file added for the `0.7.50` tranche.

## Listed Launchpad entries

The local upstream registry now lists one program entry plus the following 26 discriminator entries.

| Entry kind | Entry name | Discriminator | Initial family | Initial DB target |
|---|---:|---:|---|---|
| instruction | `buy_exact_in` | `faea0d7bd59c13ec` | swap | decoded_events_only |
| instruction | `buy_exact_out` | `18d3742869039938` | swap | decoded_events_only |
| instruction | `claim_creator_fee` | `1a618acb84ab8dfc` | fee | decoded_events_only |
| instruction | `claim_platform_fee` | `9c27d0874ced3d48` | fee | decoded_events_only |
| instruction | `claim_platform_fee_from_vault` | `75f1c6a8f8da501d` | fee | decoded_events_only |
| event | `claim_vested_event` | `15c2725778d3e220` | fee/vesting audit | decoded_events_only |
| instruction | `claim_vested_token` | `3121681ebd9d4f23` | fee/vesting audit | decoded_events_only |
| instruction | `collect_fee` | `3cadf767045d8230` | fee | decoded_events_only |
| instruction | `collect_migrate_fee` | `ffba96dfeb76c9ba` | fee/migration audit | decoded_events_only |
| instruction | `create_config` | `c9cff3724b6f2fbd` | admin_config | decoded_events_only |
| instruction | `create_platform_config` | `b05ac4affd71dc14` | admin_config | decoded_events_only |
| instruction | `create_vesting_account` | `81b2020dd9ace6da` | account_create/vesting audit | decoded_events_only |
| event | `create_vesting_event` | `96980bb334d2bf7d` | account_create/vesting audit | decoded_events_only |
| instruction | `initialize` | `afaf6d1f0d989bed` | pool_create/launch | decoded_events_only |
| instruction | `initialize_v2` | `4399af27da102620` | pool_create/launch | decoded_events_only |
| instruction | `initialize_with_token_2022` | `25be7ede2c9aab11` | pool_create/launch | decoded_events_only |
| instruction | `migrate_to_amm` | `cf52c091fecf91df` | migration | decoded_events_only |
| instruction | `migrate_to_cpswap` | `885cc8671cda908c` | migration | decoded_events_only |
| event | `pool_create_event` | `97d7e20976a173ae` | pool_create | decoded_events_only |
| instruction | `remove_platform_curve_param` | `1b1e3ea95de01891` | admin_config | decoded_events_only |
| instruction | `sell_exact_in` | `9527de9bd37c981a` | swap | decoded_events_only |
| instruction | `sell_exact_out` | `5fc8472208090ba6` | swap | decoded_events_only |
| event | `trade_event` | `bddb7fd34ee661ee` | swap | decoded_events_only |
| instruction | `update_config` | `1d9efcbf0a53db63` | admin_config | decoded_events_only |
| instruction | `update_platform_config` | `c33c4c81922d438f` | admin_config | decoded_events_only |
| instruction | `update_platform_curve_param` | `8a908afadc800439` | admin_config | decoded_events_only |

Notes:

- The buy/sell instruction account hints currently use account index `4` as candidate pool account and indexes `9`/`10` as candidate token mints, based on Carbon/Raydium Launchpad account shape hints. This is an audit helper, not a materialization proof.
- Fee/admin/migration/vesting entries intentionally do not infer pool/token accounts until corpus confirms the account semantics.
- Program-data transport is represented by `cpi_event`; embedded events are decoded by their own discriminators and materialized only when their event family has a validated target.

## Family audit matrix

| Family | Launchpad status in `0.7.50` final | Decision |
|---|---|---|
| swap | `trade_event` materialized as trades/candles; buy/sell instructions materialized as launch breadcrumbs. | No duplicate trades from instruction breadcrumbs. |
| pool_create | `initialize`, `initialize_v2`, `initialize_with_token_2022`, `pool_create_event`. | Pool lifecycle/catalogue materialized when transaction succeeded. |
| add_liquidity | No direct Launchpad entry confirmed. | Non-applicable unless local corpus proves direct Launchpad liquidity instruction. |
| remove_liquidity | No direct Launchpad liquidity remove entry confirmed. | Non-applicable unless local corpus proves direct Launchpad liquidity instruction. |
| position_open | No direct Launchpad position instruction confirmed. | Non-applicable. |
| position_close | No direct Launchpad position instruction confirmed. | Non-applicable. |
| fee | claim/collect fee entries listed. | Fee table materialization enabled for observed successful transactions. |
| reward | No direct reward instruction confirmed. | Non-applicable unless local corpus proves otherwise. |
| admin/config | create/update config and platform curve/config entries listed. | Pool admin materialization enabled for observed successful transactions. |
| mint | Token minting may appear as SPL Token/Token-2022 side effect. | Not `raydium_launchpad.*` without direct program proof. |
| burn | Token burn may appear as SPL Token/Token-2022 side effect. | Not `raydium_launchpad.*` without direct program proof. |
| transfer | Transfers are expected as SPL Token/Token-2022 side effects. | Not `raydium_launchpad.*` without direct program proof. |
| account_create / vesting | `create_vesting_account`, `create_platform_vesting_account`, vesting events. | Launch event materialization enabled for observed successful transactions; unobserved events remain mapped. |
| account_close | No direct Launchpad account close confirmed. | Non-applicable. |
| wrap_sol | No direct Launchpad wrap SOL confirmed. | Side effect only unless corpus proves direct instruction. |
| unwrap_sol | No direct Launchpad unwrap SOL confirmed. | Side effect only unless corpus proves direct instruction. |
| order_place | No orderbook surface confirmed. | Non-applicable. |
| order_cancel | No orderbook surface confirmed. | Non-applicable. |
| order_fill | No orderbook surface confirmed. | Non-applicable. |
| consume_events | No orderbook surface confirmed. | Non-applicable. |
| settle_funds | No orderbook surface confirmed. | Non-applicable. |
| vault_deposit | No direct vault deposit confirmed. | Non-applicable. |
| vault_withdraw | No direct vault withdraw confirmed. | Non-applicable. |
| lock | No direct lock confirmed. | Non-applicable. |
| unlock | No direct unlock confirmed. | Non-applicable. |
| launch | initialize/pool_create path listed. | Decode/audit only. |
| migration | `migrate_to_amm`, `migrate_to_cpswap`, `collect_migrate_fee` listed. | Decode/audit only. Destination DEX materialization must be proven locally. |
| stake | No direct stake confirmed. | Non-applicable. |
| unstake | No direct unstake confirmed. | Non-applicable. |
| unknown/unmapped audit | `raydium_launchpad.instruction_audit` retained for unmatched program instructions. | Must trend toward zero for locally covered discriminators after backfill/replay. |

## SQL validation expectations

After targeted backfill and replay:

1. `k_sol_dex_event_coverage_entries` should contain the Launchpad program entry and discriminator entries.
2. Mapped entries should have `local_event_kind = raydium_launchpad.<entry_name>` and initial `proof_status = upstream_git_mapped_unverified` until observed.
3. Locally observed instructions should increment `k_sol_instruction_observations` for `decoder_code = raydium_launchpad`.
4. `upstream_git.instruction_match` fallback rows for `upstreamDecoderCode = raydium_launchpad` should be zero for locally covered instruction discriminators.
5. `raydium_launchpad.*` rows must not produce trades/candles unless a later corpus-backed patch explicitly promotes a specific event.
6. Failed transactions may be decoded/audited, but must not be materialized in trade/candle tables.

Validation file:

```text
validation_sql/SQL_VALIDATION_RAYDIUM_LAUNCHPAD_0_7_50.sql
```

## Suggested targeted Solscan discovery loop

For each discriminator:

```text
https://solscan.io/account/LanMV9sAd7wArD4vJFi2qDdfnVhFxYSUg6eADduJ3uj?instruction=<DISCRIMINATOR>&hide_spam=true&hide_failed=true&show_related=false&sort=desc
```

Then:

1. copy a small batch of recent non-failed signatures;
2. backfill through Demo2 textarea batch;
3. replay with `forceDexDecode=yes` and `deferInstructionObservations=yes`;
4. run the validation SQL;
5. promote only entries whose local payload and account semantics are proven.

## `raydium_pool_v4.json` audit status

The current workspace archive does not contain a local `raydium_pool_v4.json` copy. External fnzero IDL listings expose a separate `raydium_pool_v4.json` beside `raydium_launchpad.json`, but this delta does not confirm its program id or business role.

Decision for `0.7.50`:

- do not promote `raydium_pool_v4` as a DEX/surface;
- keep `0.7.53 raydium_pool_v4 audit / program-id decision` conditional;
- require program id confirmation and local corpus before any roadmap promotion.

## Current limitations

This delta was prepared from the provided archive only. No live RPC backfill, fresh SQLite replay, `cargo fmt`, `cargo test`, or `cargo clippy` could be executed in the current environment because the Rust toolchain is unavailable here. The SQL and code paths are prepared for local validation in the normal project environment.

## Local corpus snapshot from first 0.7.50 backfill

Observed after targeted Demo2 backfills and pool backfill on a fresh 0.7.50 DB:

- coverage listed entries: `27`;
- decoded/local mapped entries: `26`;
- observed entries: `21`;
- materialized entries: `0`;
- total observed coverage count: `672`;
- total materialized count: `0`;
- trade count: `0`;
- residual `upstream_git.instruction_match` for `raydium_launchpad`: `0`;
- residual `raydium_launchpad.instruction_audit`: `287`;
- residual audit discriminators: `e445a52e51cb9a1d` (`276`), `9247ad4562130f6a` (`10`), `a25b92c75d85eaed` (`1`).

The `e445a52e51cb9a1d` selector is handled as Anchor self-CPI event transport. It is not promoted as a Raydium Launchpad business instruction. The two low-count residual discriminators remain local-corpus audit-only until an IDL/upstream mapping is confirmed.


## pre3 correction — Demo3 preset and Launchpad pool catalog

The first replay after pre2 confirmed that Anchor self-CPI selector `e445a52e51cb9a1d` carries Launchpad `trade_event` (`bddb7fd34ee661ee`) and `pool_create_event` (`97d7e20976a173ae`). pre3 therefore decodes those two self-CPI event rows as direct `raydium_launchpad.*` events instead of leaving them under `raydium_launchpad.instruction_audit`. `trade_event` remains audit/decoded-only and is still not promoted to `k_sol_trade_events` or candles.

pre3 also fixes the Launchpad `initialize`, `initialize_v2` and `initialize_with_token_2022` account mapping using the Carbon account shape: `pool_state` index 5, `base_mint` index 6 and `quote_mint` index 7. These initialize rows are now routed to business-level pool detection as `raydium_launchpad` bonding-curve pools with pending status, which should allow pool `6HLQPoLrzX6LqePRiXQ1GGs2Dd9K3dp9VhTSHBugYzzZ` to appear in the local catalog after a forced replay when its initialize transaction is present locally.

Demo3 now exposes a `Raydium Launchpad` preset with program id `LanMV9sAd7wArD4vJFi2qDdfnVhFxYSUg6eADduJ3uj`.


## Final `0.7.50` closure snapshot

Validated closure state reported by local replay:

- `cargo test -p kb_lib`: 404 passed, 0 failed.
- Local replay: 437 replayed, 437 ledger upserts, 30 unsafe ledger rows, 256 trades, 115 lifecycle rows, 1024 candle upserts, 6205 instruction observations.
- Launchpad catalogue: 58 tokens, 58 pools, 58 pairs after replay.
- Coverage normalization: no ambiguous `unknown` family remains; only the synthetic `program` row may have an empty family.
- `trade_event`: 260 decoded, 250 successful materialized trades; 10 failed transactions intentionally not materialized.
- `buy_exact_*` / `sell_exact_*`: materialized as `k_sol_launch_events` swap-instruction breadcrumbs, not as trades.
- `cpi_event`: kept as `cpi_transport` / decoded-only; embedded events are decoded by direct event discriminator.
- Successful `trade_event` rows without materialized `k_sol_trade_events`: zero.

Post-closure recheck assets added:

- `validation_sql/SQL_VALIDATION_RAYDIUM_CPMM_0_7_50_PRE_R2.sql`
- `validation_sql/SQL_VALIDATION_RAYDIUM_CLMM_0_7_50_PRE_R2.sql`
- `docs/SOLSCAN_ACCOUNT_SOURCE_MATRIX.md`
- `kb_lib::SOLSCAN_ACCOUNT_SOURCES`