sol-parser-sdk-python 0.5.8__py3-none-any.whl → 0.5.9__py3-none-any.whl

sol_parser/grpc_types.py

@@ -37,6 +37,8 @@ class EventType(str, Enum):
     """事件类型"""
     # Block
     BLOCK_META = "BlockMeta"
+    ACCOUNT_RAW_SNAPSHOT = "AccountRawSnapshot"
+    ACCOUNT_LIQUIDITY_SNAPSHOT = "AccountLiquiditySnapshot"
     # RaydiumLaunchlab
     RAYDIUM_LAUNCHLAB_TRADE = "RaydiumLaunchlabTrade"
     RAYDIUM_LAUNCHLAB_POOL_CREATE = "RaydiumLaunchlabPoolCreate"
@@ -435,6 +437,18 @@ class EventMetadata:
     recent_blockhash: str = ""
     is_created_buy: bool = False
 
+    def __post_init__(self):
+        for name,signed in (("slot",False),("tx_index",False),("block_time_us",True),("grpc_recv_us",True)):
+            value=getattr(self,name)
+            if isinstance(value,str):
+                import re
+                if not re.fullmatch(r"-?\d+",value):raise ValueError(f"Invalid {name} integer")
+                value=int(value)
+            minimum=-(1<<63) if signed else 0
+            maximum=(1<<63)-1 if signed else (1<<64)-1
+            if type(value) is not int or not minimum<=value<=maximum:raise ValueError(f"{name} outside {'i64' if signed else 'u64'}")
+            setattr(self,name,value)
+
 
 @dataclass
 class ClientConfig:
@@ -747,6 +761,8 @@ class Protocol(str, Enum):
     PUMP_SWAP = "PumpSwap"
     PUMP_FEES = "PumpFees"
     RAYDIUM_LAUNCHLAB = "RaydiumLaunchlab"
+    LAUNCH_LAB = "LaunchLab"
+    STONK_FUN = "StonkFun"
     RAYDIUM_CPMM = "RaydiumCpmm"
     RAYDIUM_CLMM = "RaydiumClmm"
     RAYDIUM_AMM_V4 = "RaydiumAmmV4"
@@ -762,6 +778,8 @@ _PROTOCOL_PROGRAM_IDS: Dict[Protocol, List[str]] = {
     Protocol.PUMP_FUN: ["6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P"],
     Protocol.PUMP_SWAP: ["pAMMBay6oceH9fJKBRHGP5D4bD4sWpmSwMn52FMfXEA"],
     Protocol.PUMP_FEES: ["pfeeUxB6jkeY1Hxd7CsFCAjcbHA9rWtchMGdZ6VojVZ"],
+    Protocol.LAUNCH_LAB: ["LanMV9sAd7wArD4vJFi2qDdfnVhFxYSUg6eADduJ3uj"],
+    Protocol.STONK_FUN: ["LanMV9sAd7wArD4vJFi2qDdfnVhFxYSUg6eADduJ3uj"],
     Protocol.RAYDIUM_LAUNCHLAB: ["LanMV9sAd7wArD4vJFi2qDdfnVhFxYSUg6eADduJ3uj"],
     Protocol.RAYDIUM_CPMM: ["CPMMoo8L3F4NbTegBCKVNunggL7H1ZpdTHKxQB5qKP1C"],
     Protocol.RAYDIUM_CLMM: ["CAMMCzo5YL8w4VFF8KVHrK22GGUsp5VTaW7grrKgrWqK"],
@@ -981,6 +999,7 @@ class SubscribeUpdateBlockMeta:
     parent_slot: int = 0
     parent_blockhash: str = ""
     executed_transaction_count: int = 0
+    block_time: Optional[int] = None
 
 
 @dataclass

sol_parser/instructions.py

@@ -368,7 +368,7 @@ def normal_instruction_data_may_parse(program_id: str, instruction_data: bytes)
     if not instruction_data:
         return False
     if program_id == RAYDIUM_AMM_V4_PROGRAM_ID:
-        return instruction_data[0] in (1, 3, 4, 7, 9, 11)
+        return instruction_data[0] in (1, 3, 4, 7, 9, 11, 16, 17)
     if program_id == METEORA_DLMM_PROGRAM_ID:
         disc = _disc8(instruction_data)
         return disc in _DLMM_INSTRUCTION_DISCS if disc is not None else False
@@ -1710,21 +1710,27 @@ def parse_raydium_amm_v4_instruction(
     instr_type = data[0]
     meta = _make_meta(signature, slot, tx_index, block_time_us, grpc_recv_us)
 
-    if instr_type in (9, 11):  # SwapBaseIn / SwapBaseOut
+    if instr_type in (9, 11, 16, 17):  # SwapBaseIn / SwapBaseOut
         if len(data) < 17:
             return None
+        modern = instr_type in (16,17)
+        if modern and len(accounts)<8:return None
         first, second = struct.unpack_from("<QQ", data, 1)
         shift = 1 if len(accounts) == 17 else 0
         def g(index: int) -> str:
-            return _get_account_safe(accounts, index - shift if index >= 5 else index)
+            if modern:
+                index = {0:0,1:1,2:2,5:3,6:4,15:5,16:6,17:7}.get(index,-1)
+            else:
+                index = index-shift if index>=5 else index
+            return _get_account_safe(accounts,index)
         return legacy_dict_to_dex_event({"RaydiumAmmV4Swap": {
             "metadata": meta,
             "amm": _get_account_safe(accounts, 1),
             "user_source_owner": g(17),
-            "amount_in": first if instr_type == 9 else 0,
-            "minimum_amount_out": second if instr_type == 9 else 0,
-            "max_amount_in": first if instr_type == 11 else 0,
-            "amount_out": second if instr_type == 11 else 0,
+            "amount_in": first if instr_type in (9,16) else 0,
+            "minimum_amount_out": second if instr_type in (9,16) else 0,
+            "max_amount_in": first if instr_type in (11,17) else 0,
+            "amount_out": second if instr_type in (11,17) else 0,
             "token_program": g(0), "amm_authority": g(2), "amm_open_orders": g(3),
             "pool_coin_token_account": g(5), "pool_pc_token_account": g(6),
             "serum_program": g(7), "serum_market": g(8), "serum_bids": g(9),
@@ -1843,7 +1849,7 @@ def parse_raydium_launchlab_instruction(
     payload = data[8:]
 
     if discriminator == _DISC_RAYDIUM_LAUNCHLAB_TRADE:
-        if len(payload) < 139:
+        if len(payload) != 139 or payload[136] > 1 or payload[137] > 2 or payload[138] > 1:
             return None
         return legacy_dict_to_dex_event({"RaydiumLaunchlabTrade": {
             "metadata": meta,
@@ -1854,6 +1860,19 @@ def parse_raydium_launchlab_instruction(
             "is_buy": payload[136] == 0,
             "trade_direction": "Buy" if payload[136] == 0 else "Sell",
             "exact_in": payload[138] == 1,
+            "pool_status": ("Fund","Migrate","Trade")[payload[137]],
+            "total_base_sell": _u64_payload(payload,32),
+            "virtual_base": _u64_payload(payload,40),
+            "virtual_quote": _u64_payload(payload,48),
+            "real_base_before": _u64_payload(payload,56),
+            "real_quote_before": _u64_payload(payload,64),
+            "real_base_after": _u64_payload(payload,72),
+            "real_quote_after": _u64_payload(payload,80),
+            "protocol_fee": _u64_payload(payload,104),
+            "platform_fee": _u64_payload(payload,112),
+            "creator_fee": _u64_payload(payload,120),
+            "share_fee": _u64_payload(payload,128),
+
         }})
     if discriminator == _DISC_RAYDIUM_LAUNCHLAB_POOL_CREATE:
         if len(payload) < 97:
@@ -1897,6 +1916,20 @@ def parse_raydium_launchlab_instruction(
             "is_buy": is_buy,
             "trade_direction": "Buy" if is_buy else "Sell",
             "exact_in": exact_in,
+            "global_config": _get_account_safe(accounts,2),
+            "platform_config": _get_account_safe(accounts,3),
+            "user_base_token": _get_account_safe(accounts,5),
+            "user_quote_token": _get_account_safe(accounts,6),
+            "base_vault": _get_account_safe(accounts,7),
+            "quote_vault": _get_account_safe(accounts,8),
+            "base_mint": _get_account_safe(accounts,9),
+            "quote_mint": _get_account_safe(accounts,10),
+            "base_token_program": _get_account_safe(accounts,11),
+            "quote_token_program": _get_account_safe(accounts,12),
+            "system_program": _get_account_safe(accounts,15),
+            "platform_associated_account": _get_account_safe(accounts,16),
+            "creator_associated_account": _get_account_safe(accounts,17),
+
         }})
     if discriminator in (
         _IX_RAYDIUM_LAUNCHLAB_INITIALIZE,
@@ -1922,7 +1955,16 @@ def parse_raydium_launchlab_instruction(
         _IX_RAYDIUM_LAUNCHLAB_MIGRATE_TO_AMM,
         _IX_RAYDIUM_LAUNCHLAB_MIGRATE_TO_CPSWAP,
     ):
-        return None
+        cp = discriminator == _IX_RAYDIUM_LAUNCHLAB_MIGRATE_TO_CPSWAP
+        if len(accounts) < (28 if cp else 32) or (not cp and len(payload) < 9): return None
+        return legacy_dict_to_dex_event({"RaydiumLaunchlabMigrateAmm": {
+            "metadata": meta, "old_pool": _get_account_safe(accounts,17 if cp else 23),
+            "new_pool": _get_account_safe(accounts,5 if cp else 13), "user": _get_account_safe(accounts,0),
+            "liquidity_amount": 0, "liquidity_amount_known": False,
+            "base_mint": _get_account_safe(accounts,1), "quote_mint": _get_account_safe(accounts,2),
+            "platform_config": _get_account_safe(accounts,3) if cp else Z,
+            "destination_program": _get_account_safe(accounts,4 if cp else 12),
+        }})
 
     return None
 

sol_parser/json_util.py

@@ -11,7 +11,7 @@ from .grpc_types import EventType
 
 
 def dex_event_json_dumps(obj: Any, **kwargs: Any) -> str:
-    return json.dumps(obj, default=str, **kwargs)
+    return json.dumps(_precise_metadata(dex_event_to_jsonable(obj)), default=str, **kwargs)
 
 
 def dex_event_to_jsonable(ev: Any) -> Any:
@@ -39,3 +39,17 @@ def format_dex_event_json(ev: Any, *, indent: int = 2, ensure_ascii: bool = Fals
         indent=indent,
         ensure_ascii=ensure_ascii,
     )
+
+
+def _precise_metadata(obj):
+    """Match Node exact metadata JSON without changing floating latency metrics."""
+    if isinstance(obj,dict):
+        result={k:_precise_metadata(v) for k,v in obj.items()}
+        if "signature" in obj and all(k in obj for k in ("slot","tx_index","block_time_us","grpc_recv_us")):
+            from .grpc_types import EventMetadata
+            validated=EventMetadata(**{k:obj[k] for k in ("signature","slot","tx_index","block_time_us","grpc_recv_us")})
+            for k in ("slot","tx_index","block_time_us","grpc_recv_us"):result[k]=str(getattr(validated,k))
+        return result
+    if isinstance(obj,(tuple,list)):return [_precise_metadata(v) for v in obj]
+    if is_dataclass(obj):return _precise_metadata(asdict(obj))
+    return obj

sol_parser/liquidity_snapshot.py

@@ -0,0 +1,101 @@
+"""Native liquidity identity decoders and immutable raw subscription snapshots."""
+
+from __future__ import annotations
+from dataclasses import dataclass
+import base58
+from .accounts import AccountData
+from .grpc_types import EventMetadata
+from .transaction_route import PROGRAMS
+
+
+@dataclass
+class RawAccountSnapshotEvent:
+    metadata: EventMetadata
+    account: AccountData
+    write_version: int
+    is_startup: bool
+
+
+@dataclass
+class LiquidityAccountSnapshotEvent:
+    metadata: EventMetadata
+    pubkey: str
+    owner: str
+    kind: dict | str
+    data: bytes
+
+
+def parse_liquidity_account(account: AccountData, metadata: EventMetadata):
+    if account.lamports <= 0 or account.executable:
+        return None
+    d, owner = bytes(account.data), account.owner
+    disc = d[:8]
+
+    def key(o):
+        return base58.b58encode(d[o : o + 32]).decode()
+
+    def number(o, n, signed=False):
+        return int.from_bytes(d[o : o + n], "little", signed=signed)
+
+    kind = None
+    if owner == PROGRAMS["LaunchLab"]:
+        if disc == bytes([247, 237, 227, 245, 215, 195, 222, 70]) and len(d) >= 429:
+            kind = {
+                "LaunchLabPool": dict(
+                    base_mint=key(205),
+                    quote_mint=key(237),
+                    global_config=key(141),
+                    platform_config=key(173),
+                )
+            }
+        elif disc == bytes([149, 8, 156, 202, 160, 252, 176, 217]) and len(d) >= 35:
+            kind = "LaunchLabGlobalConfig"
+        elif disc == bytes([160, 78, 128, 0, 248, 83, 230, 160]) and len(d) >= 728:
+            kind = "LaunchLabPlatformConfig"
+    elif owner == PROGRAMS["MeteoraDlmm"]:
+        if disc == bytes([33, 11, 49, 98, 181, 101, 177, 13]) and len(d) >= 904:
+            kind = {
+                "DlmmPool": dict(
+                    token_x_mint=key(88),
+                    token_y_mint=key(120),
+                    active_id=number(76, 4, True),
+                    bin_step=number(80, 2),
+                )
+            }
+        elif disc == bytes([92, 142, 92, 220, 5, 148, 70, 181]) and len(d) >= 10136:
+            kind = {"DlmmBinArray": dict(pool=key(24), index=number(8, 8, True))}
+        elif disc == bytes([80, 111, 124, 113, 55, 237, 18, 5]) and len(d) >= 1576:
+            kind = {"DlmmBitmap": dict(pool=key(8))}
+    elif owner == PROGRAMS["OrcaWhirlpool"]:
+        if disc == bytes([17, 216, 246, 142, 225, 199, 218, 56]) and len(d) >= 148:
+            bitmap, offset = number(44, 16), 60
+            if bitmap >> 88:
+                return None
+            for i in range(88):
+                if (
+                    offset >= len(d)
+                    or d[offset] not in (0, 1)
+                    or d[offset] != (bitmap >> i) & 1
+                ):
+                    return None
+                offset += 1 + (112 if d[offset] else 0)
+                if offset > len(d):
+                    return None
+            kind = {
+                "OrcaDynamicTickArray": dict(
+                    pool=key(12),
+                    start_tick_index=number(8, 4, True),
+                    tick_bitmap=bitmap,
+                )
+            }
+        elif disc == bytes([139, 194, 131, 179, 140, 179, 229, 244]) and len(d) >= 254:
+            kind = {"OrcaAdaptiveOracle": dict(pool=key(8))}
+    elif (
+        owner == PROGRAMS["RaydiumClmm"]
+        and disc == bytes([60, 150, 36, 219, 97, 128, 139, 153])
+        and len(d) >= 1832
+    ):
+        kind = {"ClmmBitmap": dict(pool=key(8))}
+    if kind is None:
+        return None
+    return LiquidityAccountSnapshotEvent(metadata, account.pubkey, owner, kind, d)

sol_parser/simulation_route.py

@@ -0,0 +1,233 @@
+"""Explicit simulateTransaction evidence adapter; no RPC or wire reserialization."""
+
+from __future__ import annotations
+import re
+import struct
+import base58
+from .wire_transaction import decode_wire_transaction
+from .transaction_route import analyze_rpc_transaction_routes, TOKEN, TOKEN_2022, ZERO
+
+
+def _unsigned(value, bits):
+    if type(value) not in (str, int) or not re.fullmatch(r"[0-9]+", str(value)):
+        raise ValueError("Invalid simulation integer")
+    n = int(value)
+    if not 0 <= n < 1 << bits:
+        raise ValueError("Simulation integer outside range")
+    return n
+
+
+def analyze_simulation_routes(wire, response, graduated_pools=()):
+    """Original wire plus simulateTransaction response. SPL transfers and ATA setup.
+
+    Unsupported parsed CPI fail explicitly. Raw/compiled CPI are preserved.
+    V0 with ALT requires the existing compiled route API and loadedAddresses.
+    """
+    tx, _ = decode_wire_transaction(wire)
+    if tx["message"]["addressTableLookups"]:
+        raise ValueError(
+            "V0 ALT addresses unavailable; use compiled route input with loadedAddresses"
+        )
+    if not isinstance(response, dict) or not isinstance(response.get("result"), dict):
+        raise ValueError("Simulation response missing execution metadata")
+    value = response["result"].get("value")
+    if (
+        response.get("error")
+        or not isinstance(value, dict)
+        or "err" not in value
+        or "innerInstructions" not in value
+    ):
+        raise ValueError("Simulation response missing execution metadata")
+    groups = value["innerInstructions"]
+    if groups is None:
+        groups = []
+    if not isinstance(groups, list):
+        raise ValueError("Invalid simulation inner instructions")
+    keys = tx["message"]["accountKeys"]
+
+    def index(key):
+        if not isinstance(key, str) or key not in keys:
+            raise ValueError("Simulation account absent from transaction")
+        return keys.index(key)
+
+    def valid_index(n):
+        if type(n) is not int or not 0 <= n < len(keys):
+            raise ValueError("Invalid simulation account index")
+        return n
+
+    def instruction(ix):
+        if not isinstance(ix, dict):
+            raise ValueError("Invalid simulation instruction")
+        height = ix.get("stackHeight")
+        if height is not None and (type(height) is not int or height < 2):
+            raise ValueError("Invalid simulation stack height")
+        if "programIdIndex" in ix:
+            if (
+                "parsed" in ix
+                or not isinstance(ix.get("data"), str)
+                or not isinstance(ix.get("accounts"), list)
+            ):
+                raise ValueError("Invalid compiled simulation instruction")
+            base58.b58decode(ix["data"])
+            return dict(
+                programIdIndex=valid_index(ix["programIdIndex"]),
+                accounts=[valid_index(i) for i in ix["accounts"]],
+                data=ix["data"],
+                stackHeight=height,
+            )
+        program = index(ix.get("programId"))
+        if "parsed" not in ix:
+            if not isinstance(ix.get("data"), str) or not isinstance(
+                ix.get("accounts"), list
+            ):
+                raise ValueError("Invalid raw simulation instruction")
+            base58.b58decode(ix["data"])
+            return dict(
+                programIdIndex=program,
+                accounts=[index(k) for k in ix["accounts"]],
+                data=ix["data"],
+                stackHeight=height,
+            )
+        parsed = ix["parsed"]
+        if not isinstance(parsed, dict) or not isinstance(parsed.get("info"), dict):
+            raise ValueError("Unsupported parsed simulation instruction")
+        setup = _account_setup(ix["programId"], parsed.get("type"), parsed["info"])
+        if setup is not None:
+            accounts, data = setup
+            return dict(
+                programIdIndex=program,
+                accounts=[index(k) for k in accounts],
+                data=base58.b58encode(data).decode(),
+                stackHeight=height,
+            )
+        if ix["programId"] not in (TOKEN, TOKEN_2022):
+            raise ValueError("Unsupported parsed simulation program")
+        kind, info = ix["parsed"].get("type"), ix["parsed"].get("info")
+        if not isinstance(info, dict) or kind not in (
+            "transfer",
+            "transferChecked",
+            "transferCheckedWithFee",
+        ):
+            raise ValueError("Unsupported parsed simulation instruction")
+        authority = info.get("authority", info.get("multisigAuthority"))
+        signers = info.get("signers", [])
+        if not isinstance(signers, list):
+            raise ValueError("Invalid simulation signers")
+        if kind == "transfer":
+            accounts = [
+                info.get("source"),
+                info.get("destination"),
+                authority,
+            ] + signers
+            data = struct.pack("<BQ", 3, _unsigned(info.get("amount"), 64))
+        else:
+            with_fee = kind == "transferCheckedWithFee"
+            if with_fee and ix["programId"] != TOKEN_2022:
+                raise ValueError("Transfer fee requires Token-2022")
+            amount = info.get("tokenAmount")
+            if not isinstance(amount, dict):
+                raise ValueError("Invalid simulation token amount")
+            n, decimals = _unsigned(amount.get("amount"), 64), _unsigned(
+                amount.get("decimals"), 8
+            )
+            accounts = [
+                info.get("source"),
+                info.get("mint"),
+                info.get("destination"),
+                authority,
+            ] + signers
+            data = (
+                struct.pack(
+                    "<BBQBQ", 26, 1, n, decimals, _unsigned(info.get("feeAmount"), 64)
+                )
+                if with_fee
+                else struct.pack("<BQB", 12, n, decimals)
+            )
+        return dict(
+            programIdIndex=program,
+            accounts=[index(k) for k in accounts],
+            data=base58.b58encode(data).decode(),
+            stackHeight=height,
+        )
+
+    converted, seen = [], set()
+    for group in groups:
+        if not isinstance(group, dict):
+            raise ValueError("Invalid simulation instruction group")
+        outer = group.get("index")
+        if (
+            type(outer) is not int
+            or not 0 <= outer < len(tx["message"]["instructions"])
+            or outer in seen
+            or not isinstance(group.get("instructions"), list)
+        ):
+            raise ValueError("Invalid simulation instruction group")
+        seen.add(outer)
+        converted.append(
+            dict(
+                index=outer,
+                instructions=[instruction(ix) for ix in group["instructions"]],
+            )
+        )
+    return analyze_rpc_transaction_routes(
+        dict(transaction=tx, meta={**value, "innerInstructions": converted}),
+        graduated_pools,
+    )
+
+
+def _account_setup(program, kind, info):
+    def pubkey(key):
+        if not isinstance(key, str):
+            raise ValueError("Invalid simulation public key")
+        data = base58.b58decode(key)
+        if len(data) != 32:
+            raise ValueError("Invalid simulation public key")
+        return data
+
+    if program == ZERO and kind == "createAccount":
+        return [info.get("source"), info.get("newAccount")], struct.pack(
+            "<IQQ",
+            0,
+            _unsigned(info.get("lamports"), 64),
+            _unsigned(info.get("space"), 64),
+        ) + pubkey(info.get("owner"))
+    if program == ZERO and kind in ("transfer", "allocate"):
+        return ([info.get("source"), info.get("destination")] if kind == "transfer" else [info.get("account")]), struct.pack("<IQ", 2 if kind == "transfer" else 8, _unsigned(info.get("lamports" if kind == "transfer" else "space"), 64))
+    if program == ZERO and kind == "assign":
+        return [info.get("account")], struct.pack("<I", 1) + pubkey(info.get("owner"))
+    if program not in (TOKEN, TOKEN_2022):
+        return None
+    if kind in ("mintTo", "mintToChecked", "burn", "burnChecked"):
+        minting = kind.startswith("mintTo")
+        checked = kind.endswith("Checked")
+        authority_key = "mintAuthority" if minting else "authority"
+        multisig_key = "multisigMintAuthority" if minting else "multisigAuthority"
+        authority = info.get(authority_key)
+        if authority is None:
+            authority = info.get(multisig_key)
+        signers = info.get("signers", [])
+        if not isinstance(signers, list):
+            raise ValueError("Invalid simulation signers")
+        amount = info.get("tokenAmount") if checked else info
+        if not isinstance(amount, dict):
+            raise ValueError("Invalid simulation token amount")
+        data = struct.pack("<BQ", (14 if minting else 15) if checked else (7 if minting else 8),
+                           _unsigned(amount.get("amount"), 64))
+        if checked:
+            data += bytes([_unsigned(amount.get("decimals"), 8)])
+        accounts = [info.get("mint"), info.get("account")] if minting else [info.get("account"), info.get("mint")]
+        return accounts + [authority] + signers, data
+    if kind == "initializeImmutableOwner":
+        return [info.get("account")], bytes([22])
+    if kind == "initializeAccount3":
+        return [info.get("account"), info.get("mint")], bytes([18]) + pubkey(
+            info.get("owner")
+        )
+    if kind == "getAccountDataSize":
+        extensions = info.get("extensionTypes")
+        if not isinstance(extensions, list):
+            raise ValueError("Invalid simulation extension types")
+        if any(ext != "immutableOwner" for ext in extensions):
+            raise ValueError("Unsupported simulation extension type")
+        return [info.get("mint")], bytes([21]) + struct.pack("<H", 7) * len(extensions)
+    return None

sol_parser/stonkfun_registry.py

@@ -0,0 +1,139 @@
+"""Caller-owned, replay-safe provenance for successfully migrated StonkFun pools."""
+
+from __future__ import annotations
+from dataclasses import asdict, dataclass
+import base64
+import base58
+from .transaction_route import (
+    PROGRAMS,
+    ZERO,
+    stonkfun_mode_from_platform_config,
+    analyze_rpc_transaction_routes,
+)
+from .wire_transaction import decode_wire_transaction
+
+
+@dataclass(frozen=True)
+class StonkFunGraduatedPool:
+    curve_pool: str
+    pool: str
+    base_mint: str
+    quote_mint: str
+    platform_config: str
+    migration_signature: str
+    migration_slot: int
+
+    def mode(self):
+        return stonkfun_mode_from_platform_config(self.platform_config)
+
+    def validate(self):
+        if (
+            self.mode() is None
+            or self.curve_pool == self.pool
+            or self.base_mint == self.quote_mint
+        ):
+            raise ValueError("Invalid StonkFun registry identity")
+        for key in (self.curve_pool, self.pool, self.base_mint, self.quote_mint):
+            if key == ZERO or len(base58.b58decode(key)) != 32:
+                raise ValueError("Invalid StonkFun registry key")
+        if (
+            len(base58.b58decode(self.migration_signature)) != 64
+            or type(self.migration_slot) is not int
+            or not 0 <= self.migration_slot < 1 << 64
+        ):
+            raise ValueError("Invalid migration provenance")
+
+
+class StonkFunPoolRegistry:
+    def __init__(self, pools=()):
+        self._pools = {}
+        for entry in pools:
+            entry.validate()
+            if entry.pool in self._pools:
+                raise ValueError("Duplicate StonkFun registry entry")
+            self._pools[entry.pool] = entry
+
+    def get(self, pool):
+        return self._pools.get(pool)
+
+    def pools_for_base_mint(self, mint):
+        return [
+            self._pools[k]
+            for k in sorted(self._pools)
+            if self._pools[k].base_mint == mint
+        ]
+
+    def verified_cpmm_pools(self):
+        return sorted(self._pools)
+
+    def to_dict(self):
+        return {"pools": [asdict(self._pools[k]) for k in sorted(self._pools)]}
+
+    @classmethod
+    def from_dict(cls, data):
+        return cls(StonkFunGraduatedPool(**p) for p in data["pools"])
+
+    def observe_migrations(self, entries, succeeded):
+        if not succeeded:
+            return 0
+        pending = {}
+        for entry in entries:
+            entry.validate()
+            prior = pending.get(entry.pool) or self._pools.get(entry.pool)
+            if prior is not None and prior != entry:
+                raise ValueError("Conflicting migration provenance")
+            pending[entry.pool] = entry
+        count = sum(k not in self._pools for k in pending)
+        self._pools.update(pending)
+        return count
+
+    def observe_rpc_transaction(self, transaction):
+        tx = transaction.get("result", transaction)
+        if not isinstance(tx.get("meta"), dict):
+            raise ValueError("Transaction metadata missing")
+        if "err" not in tx["meta"]:
+            raise ValueError("Transaction execution status missing")
+        if tx["meta"]["err"] is not None:
+            return 0
+        analyze_rpc_transaction_routes(transaction)
+        body = tx["transaction"]
+        if isinstance(body, list):
+            if body[1] != "base64":
+                raise ValueError("Expected base64 encoding")
+            body, _ = decode_wire_transaction(base64.b64decode(body[0], validate=True))
+        message, loaded = body["message"], tx["meta"].get("loadedAddresses") or {}
+        keys = (
+            [k if isinstance(k, str) else k["pubkey"] for k in message["accountKeys"]]
+            + loaded.get("writable", [])
+            + loaded.get("readonly", [])
+        )
+        instructions = list(message["instructions"])
+        for group in tx["meta"].get("innerInstructions") or []:
+            instructions.extend(group["instructions"])
+        entries = []
+        for ix in instructions:
+            data = (
+                base58.b58decode(ix["data"])
+                if isinstance(ix["data"], str)
+                else bytes(ix["data"])
+            )
+            if (
+                keys[ix["programIdIndex"]] != PROGRAMS["LaunchLab"]
+                or data[:8] != bytes([136, 92, 200, 103, 28, 218, 144, 140])
+                or len(ix["accounts"]) < 28
+            ):
+                continue
+            a = [keys[k] if 0 <= k < len(keys) else ZERO for k in ix["accounts"]]
+            if (
+                a[4] != PROGRAMS["RaydiumCpmm"]
+                or stonkfun_mode_from_platform_config(a[3]) is None
+            ):
+                continue
+            if ZERO in (a[17], a[5], a[1], a[2]) or a[17] == a[5] or a[1] == a[2]:
+                continue
+            entries.append(
+                StonkFunGraduatedPool(
+                    a[17], a[5], a[1], a[2], a[3], body["signatures"][0], tx["slot"]
+                )
+            )
+        return self.observe_migrations(entries, True)