@parqxchange/sdk 0.1.0 → 0.2.0

package/idl/pool_program.json

@@ -57,6 +57,9 @@
       "accounts": [
         {
           "name": "insurance_fund",
+          "docs": [
+            "Insurance fund state (mutated for total_accrued + event)."
+          ],
           "writable": true,
           "pda": {
             "seeds": [
@@ -84,14 +87,24 @@
         },
         {
           "name": "pool_state",
+          "docs": [
+            "Pool state for the market being liquidated. We mutate `total_usdc` to",
+            "reflect that 25 bps was never LP-owned."
+          ],
           "writable": true
         },
         {
           "name": "pool_vault_usdc",
+          "docs": [
+            "Source: pool's USDC vault. Must match `pool_state`'s vault."
+          ],
           "writable": true
         },
         {
           "name": "insurance_vault",
+          "docs": [
+            "Destination: insurance fund's USDC vault."
+          ],
           "writable": true
         },
         {
@@ -99,6 +112,9 @@
         },
         {
           "name": "engine_auth",
+          "docs": [
+            "Key equality with pool_state.engine_auth enforced in handler."
+          ],
           "signer": true
         },
         {
@@ -188,6 +204,9 @@
         },
         {
           "name": "trader",
+          "docs": [
+            "Trader wallet — payer for rent on first init, and owner of the claims account."
+          ],
           "writable": true,
           "signer": true
         },
@@ -216,6 +235,210 @@
         }
       ]
     },
+    {
+      "name": "apply_queue_haircut",
+      "docs": [
+        "ADL Tier B — permissionless queue-IOU haircut. Walks the contiguous aged",
+        "Pending prefix from queue_head_idx and socializes the unbacked tail",
+        "pro-rata, re-deriving the whole trigger live from on-chain bytes. The",
+        "handler is the sole gate. Step 3, 2026-06-05."
+      ],
+      "discriminator": [
+        60,
+        181,
+        236,
+        16,
+        168,
+        31,
+        41,
+        40
+      ],
+      "accounts": [
+        {
+          "name": "pool_state",
+          "writable": true,
+          "pda": {
+            "seeds": [
+              {
+                "kind": "const",
+                "value": [
+                  112,
+                  111,
+                  111,
+                  108
+                ]
+              },
+              {
+                "kind": "account",
+                "path": "pool_state.market_id",
+                "account": "PoolState"
+              }
+            ]
+          }
+        },
+        {
+          "name": "market_state",
+          "docs": [
+            "are validated in-handler before any byte is trusted."
+          ]
+        },
+        {
+          "name": "protocol_config",
+          "docs": [
+            "`[b\"protocol_config\"]` PDA derivation are validated in-handler."
+          ]
+        },
+        {
+          "name": "caller",
+          "docs": [
+            "Permissionless caller — keeps the keeper-down / backup-operator story."
+          ],
+          "signer": true
+        }
+      ],
+      "args": [
+        {
+          "name": "max_entries",
+          "type": "u8"
+        }
+      ]
+    },
+    {
+      "name": "apply_retroactive_funding",
+      "docs": [
+        "Admin-only retroactive funding correction (2026-06-09). Debits one",
+        "Pending queue IOU by the funding it dodged while adaptive funding was",
+        "structurally off (launch → 2026-06-09). Gated on `pool_state.admin`."
+      ],
+      "discriminator": [
+        122,
+        5,
+        179,
+        204,
+        24,
+        119,
+        127,
+        240
+      ],
+      "accounts": [
+        {
+          "name": "pool_state",
+          "writable": true,
+          "pda": {
+            "seeds": [
+              {
+                "kind": "const",
+                "value": [
+                  112,
+                  111,
+                  111,
+                  108
+                ]
+              },
+              {
+                "kind": "account",
+                "path": "pool_state.market_id",
+                "account": "PoolState"
+              }
+            ]
+          }
+        },
+        {
+          "name": "entry",
+          "writable": true,
+          "pda": {
+            "seeds": [
+              {
+                "kind": "const",
+                "value": [
+                  112,
+                  97,
+                  121,
+                  111,
+                  117,
+                  116,
+                  95,
+                  113,
+                  117,
+                  101,
+                  117,
+                  101,
+                  95,
+                  101,
+                  110,
+                  116,
+                  114,
+                  121
+                ]
+              },
+              {
+                "kind": "account",
+                "path": "pool_state.market_id",
+                "account": "PoolState"
+              },
+              {
+                "kind": "account",
+                "path": "entry.idx",
+                "account": "PayoutQueueEntry"
+              }
+            ]
+          }
+        },
+        {
+          "name": "user_claims",
+          "writable": true,
+          "pda": {
+            "seeds": [
+              {
+                "kind": "const",
+                "value": [
+                  117,
+                  115,
+                  101,
+                  114,
+                  95,
+                  113,
+                  117,
+                  101,
+                  117,
+                  101,
+                  95,
+                  99,
+                  108,
+                  97,
+                  105,
+                  109,
+                  115
+                ]
+              },
+              {
+                "kind": "account",
+                "path": "pool_state.market_id",
+                "account": "PoolState"
+              },
+              {
+                "kind": "account",
+                "path": "entry.owner",
+                "account": "PayoutQueueEntry"
+              }
+            ]
+          }
+        },
+        {
+          "name": "admin",
+          "signer": true,
+          "relations": [
+            "pool_state"
+          ]
+        }
+      ],
+      "args": [
+        {
+          "name": "funding_debit",
+          "type": "u64"
+        }
+      ]
+    },
     {
       "name": "credit_collateral",
       "discriminator": [
@@ -281,13 +504,22 @@
           "name": "user_usdc",
           "writable": true
         },
+        {
+          "name": "lp_dead",
+          "writable": true
+        },
         {
           "name": "depositor",
+          "writable": true,
           "signer": true
         },
         {
           "name": "token_program",
           "address": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"
+        },
+        {
+          "name": "system_program",
+          "address": "11111111111111111111111111111111"
         }
       ],
       "args": [
@@ -499,6 +731,9 @@
         },
         {
           "name": "caller",
+          "docs": [
+            "Caller receives rent refunds when entry PDAs are closed."
+          ],
           "writable": true,
           "signer": true
         },
@@ -509,6 +744,81 @@
         {
           "name": "system_program",
           "address": "11111111111111111111111111111111"
+        },
+        {
+          "name": "insurance_fund",
+          "writable": true,
+          "optional": true,
+          "pda": {
+            "seeds": [
+              {
+                "kind": "const",
+                "value": [
+                  105,
+                  110,
+                  115,
+                  117,
+                  114,
+                  97,
+                  110,
+                  99,
+                  101,
+                  95,
+                  102,
+                  117,
+                  110,
+                  100
+                ]
+              }
+            ]
+          }
+        },
+        {
+          "name": "insurance_vault",
+          "docs": [
+            "insurance_vault.key() == insurance_fund.usdc_vault is verified in the handler",
+            "(Anchor `address =` against an Option account is brittle)."
+          ],
+          "writable": true,
+          "optional": true
+        },
+        {
+          "name": "insurance_vault_authority",
+          "optional": true,
+          "pda": {
+            "seeds": [
+              {
+                "kind": "const",
+                "value": [
+                  105,
+                  110,
+                  115,
+                  117,
+                  114,
+                  97,
+                  110,
+                  99,
+                  101,
+                  95,
+                  118,
+                  97,
+                  117,
+                  108,
+                  116,
+                  95,
+                  97,
+                  117,
+                  116,
+                  104,
+                  111,
+                  114,
+                  105,
+                  116,
+                  121
+                ]
+              }
+            ]
+          }
         }
       ],
       "args": [
@@ -658,6 +968,9 @@
         },
         {
           "name": "vault_authority",
+          "docs": [
+            "Never holds data; only signs SPL transfers for the vault via PDA seeds."
+          ],
           "pda": {
             "seeds": [
               {
@@ -864,8 +1177,76 @@
         }
       ]
     },
+    {
+      "name": "migrate_pool_state_v2",
+      "docs": [
+        "PoolState V1 (240) → V2 (252): appends the ADL idempotency state",
+        "(current_adl_epoch, last_adl_cut_idx). The FIRST-EVER pool realloc.",
+        "Step 3, 2026-06-05."
+      ],
+      "discriminator": [
+        254,
+        70,
+        145,
+        57,
+        158,
+        248,
+        76,
+        50
+      ],
+      "accounts": [
+        {
+          "name": "pool_state",
+          "docs": [
+            "admin is validated from the raw buffer in the handler."
+          ],
+          "writable": true,
+          "pda": {
+            "seeds": [
+              {
+                "kind": "const",
+                "value": [
+                  112,
+                  111,
+                  111,
+                  108
+                ]
+              },
+              {
+                "kind": "arg",
+                "path": "market_id"
+              }
+            ]
+          }
+        },
+        {
+          "name": "admin",
+          "writable": true,
+          "signer": true
+        },
+        {
+          "name": "system_program",
+          "address": "11111111111111111111111111111111"
+        }
+      ],
+      "args": [
+        {
+          "name": "market_id",
+          "type": {
+            "array": [
+              "u8",
+              32
+            ]
+          }
+        }
+      ]
+    },
     {
       "name": "reimburse_liquidator",
+      "docs": [
+        "Followup #44 — liquidator-reward fallback. CPI-only; signer is",
+        "perp-engine `engine_auth`. See `reimburse_liquidator.rs`."
+      ],
       "discriminator": [
         253,
         77,
@@ -879,6 +1260,9 @@
       "accounts": [
         {
           "name": "insurance_fund",
+          "docs": [
+            "Insurance fund state (mutated for counter + event)."
+          ],
           "writable": true,
           "pda": {
             "seeds": [
@@ -906,10 +1290,16 @@
         },
         {
           "name": "insurance_vault",
+          "docs": [
+            "Source: insurance fund's USDC vault."
+          ],
           "writable": true
         },
         {
           "name": "insurance_vault_authority",
+          "docs": [
+            "Validated via seed-bind; mirrors `reimburse_pool_from_fund`."
+          ],
           "pda": {
             "seeds": [
               {
@@ -947,13 +1337,24 @@
         },
         {
           "name": "liquidator_ata",
+          "docs": [
+            "Destination: liquidator's USDC ATA."
+          ],
           "writable": true
         },
         {
-          "name": "pool_state"
+          "name": "pool_state",
+          "docs": [
+            "Read-only — anchors `engine_auth.key() == pool_state.engine_auth`.",
+            "Perp-engine's liquidate handler already passes `pool_state` (it's",
+            "the market's pool), so threading it here is free."
+          ]
         },
         {
           "name": "engine_auth",
+          "docs": [
+            "Key equality with `pool_state.engine_auth` enforced in handler."
+          ],
           "signer": true
         },
         {
@@ -1010,6 +1411,11 @@
         },
         {
           "name": "pool_state",
+          "docs": [
+            "Pool to reimburse. No seed constraint — admin can pick any pool to",
+            "restore after a bad-debt event. `address = pool_state.usdc_vault` on",
+            "`pool_vault_usdc` below pins source-of-truth wiring."
+          ],
           "writable": true
         },
         {
@@ -1076,6 +1482,60 @@
         }
       ]
     },
+    {
+      "name": "sweep_stranded_to_insurance",
+      "discriminator": [
+        222,
+        173,
+        220,
+        245,
+        212,
+        29,
+        17,
+        226
+      ],
+      "accounts": [
+        {
+          "name": "pool_state",
+          "writable": true
+        },
+        {
+          "name": "pool_vault_usdc",
+          "writable": true
+        },
+        {
+          "name": "vault_authority"
+        },
+        {
+          "name": "lp_mint"
+        },
+        {
+          "name": "insurance_fund",
+          "writable": true
+        },
+        {
+          "name": "insurance_vault",
+          "writable": true
+        },
+        {
+          "name": "admin",
+          "signer": true,
+          "relations": [
+            "pool_state"
+          ]
+        },
+        {
+          "name": "token_program",
+          "address": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"
+        }
+      ],
+      "args": [
+        {
+          "name": "amount",
+          "type": "u64"
+        }
+      ]
+    },
     {
       "name": "release_and_enqueue",
       "discriminator": [
@@ -1094,10 +1554,20 @@
           "writable": true
         },
         {
-          "name": "trader"
+          "name": "trader",
+          "docs": [
+            "The user/trader being settled. Used as a seed for user_claims and stored",
+            "in queue_entry.owner / user_claims.owner. Does NOT need to sign — the",
+            "rent_payer signs and pays. Verified by perp-engine to be the position owner."
+          ]
         },
         {
           "name": "rent_payer",
+          "docs": [
+            "The lamports source for the new PDAs. For user-driven closes (close_position),",
+            "callers pass the trader's account here. For keeper-driven decreases",
+            "(execute_decrease), callers pass the keeper's account here."
+          ],
           "writable": true,
           "signer": true
         },
@@ -1107,6 +1577,9 @@
         },
         {
           "name": "queue_entry",
+          "docs": [
+            "New queue entry PDA. Index = pool_state.queue_tail_idx at time of call."
+          ],
           "writable": true,
           "pda": {
             "seeds": [
@@ -1148,6 +1621,10 @@
         },
         {
           "name": "user_claims",
+          "docs": [
+            "User's queue claims tracking account. init_if_needed: first enqueue for",
+            "this user creates the account; subsequent enqueues just update unpaid_owed."
+          ],
           "writable": true,
           "pda": {
             "seeds": [
@@ -1192,6 +1669,17 @@
         {
           "name": "system_program",
           "address": "11111111111111111111111111111111"
+        },
+        {
+          "name": "usdc_vault",
+          "writable": true
+        },
+        {
+          "name": "vault_authority"
+        },
+        {
+          "name": "user_usdc",
+          "writable": true
         }
       ],
       "args": [
@@ -1200,7 +1688,11 @@
           "type": "u64"
         },
         {
-          "name": "net_return",
+          "name": "direct_payout",
+          "type": "u64"
+        },
+        {
+          "name": "enqueue_amount",
           "type": "u64"
         }
       ]
@@ -1346,12 +1838,74 @@
       ],
       "args": [
         {
-          "name": "collateral_release",
-          "type": "u64"
-        },
-        {
-          "name": "phantom_credit",
-          "type": "u64"
+          "name": "collateral_release",
+          "type": "u64"
+        },
+        {
+          "name": "phantom_credit",
+          "type": "u64"
+        }
+      ]
+    },
+    {
+      "name": "set_insurance_auto_payouts",
+      "docs": [
+        "Admin kill switch: when `frozen`, disables the two AUTOMATIC insurance",
+        "debits — `reimburse_liquidator` (#44) no-ops and `harvest`'s #129",
+        "queued-winner fallback declines to draw from the fund. The MANUAL levers",
+        "(`reimburse_pool_from_fund`, `withdraw_insurance`) are unaffected, so the",
+        "fund becomes an emergency-only reserve. Reversible in one tx."
+      ],
+      "discriminator": [
+        117,
+        181,
+        125,
+        174,
+        207,
+        84,
+        119,
+        133
+      ],
+      "accounts": [
+        {
+          "name": "insurance_fund",
+          "writable": true,
+          "pda": {
+            "seeds": [
+              {
+                "kind": "const",
+                "value": [
+                  105,
+                  110,
+                  115,
+                  117,
+                  114,
+                  97,
+                  110,
+                  99,
+                  101,
+                  95,
+                  102,
+                  117,
+                  110,
+                  100
+                ]
+              }
+            ]
+          }
+        },
+        {
+          "name": "admin",
+          "signer": true,
+          "relations": [
+            "insurance_fund"
+          ]
+        }
+      ],
+      "args": [
+        {
+          "name": "frozen",
+          "type": "bool"
         }
       ]
     },
@@ -1885,6 +2439,32 @@
     }
   ],
   "events": [
+    {
+      "name": "AdlHaircutApplied",
+      "discriminator": [
+        45,
+        183,
+        107,
+        249,
+        160,
+        213,
+        154,
+        255
+      ]
+    },
+    {
+      "name": "AdlTailUnclearable",
+      "discriminator": [
+        192,
+        236,
+        249,
+        237,
+        3,
+        27,
+        201,
+        205
+      ]
+    },
     {
       "name": "CollateralCredited",
       "discriminator": [
@@ -1976,6 +2556,19 @@
         215
       ]
     },
+    {
+      "name": "InsuranceAutoPayoutsSet",
+      "discriminator": [
+        48,
+        182,
+        26,
+        194,
+        149,
+        152,
+        81,
+        62
+      ]
+    },
     {
       "name": "InsuranceReimbursed",
       "discriminator": [
@@ -2015,6 +2608,19 @@
         156
       ]
     },
+    {
+      "name": "MarginReturned",
+      "discriminator": [
+        133,
+        233,
+        166,
+        9,
+        235,
+        18,
+        193,
+        184
+      ]
+    },
     {
       "name": "PhantomCreditDrained",
       "discriminator": [
@@ -2054,6 +2660,19 @@
         232
       ]
     },
+    {
+      "name": "RetroactiveFundingApplied",
+      "discriminator": [
+        29,
+        154,
+        201,
+        249,
+        129,
+        10,
+        17,
+        25
+      ]
+    },
     {
       "name": "Settled",
       "discriminator": [
@@ -2080,6 +2699,19 @@
         164
       ]
     },
+    {
+      "name": "StrandedLpGainSweptToInsurance",
+      "discriminator": [
+        66,
+        145,
+        181,
+        189,
+        9,
+        212,
+        139,
+        165
+      ]
+    },
     {
       "name": "Withdrawn",
       "discriminator": [
@@ -2224,9 +2856,131 @@
       "code": 6025,
       "name": "WrongMint",
       "msg": "Destination mint does not match source mint"
+    },
+    {
+      "code": 6026,
+      "name": "AdlDisarmed",
+      "msg": "ADL is disarmed for this market (adl_frozen set)"
+    },
+    {
+      "code": 6027,
+      "name": "AdlNotArmed",
+      "msg": "ADL trigger not armed: deficit below floor, head fundable, or head not aged"
+    },
+    {
+      "code": 6028,
+      "name": "WrongMarketState",
+      "msg": "MarketState account does not match this pool's market/engine"
+    },
+    {
+      "code": 6029,
+      "name": "WrongProtocolConfig",
+      "msg": "ProtocolConfig account does not match this pool's engine"
+    },
+    {
+      "code": 6030,
+      "name": "NothingToDebit",
+      "msg": "Retroactive funding debit resolves to zero (entry already at/below target)"
+    },
+    {
+      "code": 6031,
+      "name": "StrandedPoolBalance",
+      "msg": "Pool holds a stranded balance with zero LP supply; sweep to insurance before the first deposit"
+    },
+    {
+      "code": 6032,
+      "name": "PoolHasLpSupply",
+      "msg": "Sweep refused: pool has outstanding LP shares (total_usdc is LP-owned)"
     }
   ],
   "types": [
+    {
+      "name": "AdlHaircutApplied",
+      "docs": [
+        "Emitted by `apply_queue_haircut` (Tier B) when a queue-IOU haircut is applied.",
+        "`total_cut` is removed from `queue_total_owed` (and the corresponding entries'",
+        "`amount` + owners' `unpaid_owed`), socializing the unbacked tail pro-rata."
+      ],
+      "type": {
+        "kind": "struct",
+        "fields": [
+          {
+            "name": "market_id",
+            "type": {
+              "array": [
+                "u8",
+                32
+              ]
+            }
+          },
+          {
+            "name": "epoch",
+            "type": "u32"
+          },
+          {
+            "name": "entries_cut",
+            "type": "u32"
+          },
+          {
+            "name": "total_cut",
+            "type": "u64"
+          },
+          {
+            "name": "deficit_before",
+            "type": "u64"
+          },
+          {
+            "name": "deficit_after",
+            "type": "u64"
+          },
+          {
+            "name": "queue_total_owed_after",
+            "type": "u64"
+          }
+        ]
+      }
+    },
+    {
+      "name": "AdlTailUnclearable",
+      "docs": [
+        "Emitted by `apply_queue_haircut` when ADL was armed but could clear nothing",
+        "(the worst queue: every claim already drew its collateral, so `cut ≈ 0`) and",
+        "the deficit still exceeds the trigger floor. The terminal signal: the keeper",
+        "safety path alerts and the operator escalates by reusing PR #122",
+        "`set_trading_halt(ReduceOnly)` (or per-market `set_market_paused`). ADL never",
+        "auto-halts. See spec §4.8."
+      ],
+      "type": {
+        "kind": "struct",
+        "fields": [
+          {
+            "name": "market_id",
+            "type": {
+              "array": [
+                "u8",
+                32
+              ]
+            }
+          },
+          {
+            "name": "epoch",
+            "type": "u32"
+          },
+          {
+            "name": "deficit",
+            "type": "u64"
+          },
+          {
+            "name": "queue_total_owed",
+            "type": "u64"
+          },
+          {
+            "name": "side_bucket",
+            "type": "u64"
+          }
+        ]
+      }
+    },
     {
       "name": "CollateralCredited",
       "type": {
@@ -2450,6 +3204,10 @@
           },
           {
             "name": "engine_auth",
+            "docs": [
+              "The engine_auth PDA from perp-engine: PDA([b\"engine_auth\", market_id], perp_engine_id).",
+              "perp-engine computes this PDA, passes it here; pool stores it as the authorized caller."
+            ],
             "type": "pubkey"
           },
           {
@@ -2496,45 +3254,125 @@
         ]
       }
     },
+    {
+      "name": "InsuranceAutoPayoutsSet",
+      "docs": [
+        "Emitted by `set_insurance_auto_payouts` when the admin toggles the automatic",
+        "insurance-debit kill switch (`InsuranceFund.auto_payouts_frozen`).",
+        "`frozen = true` disables #44 (liquidator reimburse) + #129 (queued-winner",
+        "harvest fallback); the manual admin levers are unaffected."
+      ],
+      "type": {
+        "kind": "struct",
+        "fields": [
+          {
+            "name": "frozen",
+            "type": "bool"
+          }
+        ]
+      }
+    },
     {
       "name": "InsuranceFund",
+      "docs": [
+        "Cross-market USDC liquidation insurance fund.",
+        "",
+        "Singleton PDA at seeds `[b\"insurance_fund\"]`. Holds a separate USDC vault",
+        "(`usdc_vault`, a PDA-owned token account at seeds `[b\"insurance_vault\"]`)",
+        "authorized by a third PDA (`[b\"insurance_vault_authority\"]`).",
+        "",
+        "Accrues 25 bps of every liquidation (re-splits the existing 50 bps liq fee:",
+        "25 bps liquidator + 25 bps insurance). Operator-triggered reimbursement via",
+        "`reimburse_pool_from_fund` (WP-4) restores `pool.total_usdc` after bad-debt",
+        "events. See docs/superpowers/specs/2026-05-20-liquidation-insurance-fund-design.md."
+      ],
       "type": {
         "kind": "struct",
         "fields": [
           {
             "name": "usdc_vault",
+            "docs": [
+              "USDC token account owned by the vault authority PDA."
+            ],
             "type": "pubkey"
           },
           {
             "name": "vault_bump",
+            "docs": [
+              "Bump for the usdc_vault PDA (`[b\"insurance_vault\"]`)."
+            ],
             "type": "u8"
           },
           {
             "name": "admin",
+            "docs": [
+              "Admin authority for reimburse + withdraw operations."
+            ],
             "type": "pubkey"
           },
           {
             "name": "total_accrued",
+            "docs": [
+              "Lifetime monotonic accrual sum (observability only — does NOT cap accrual)."
+            ],
             "type": "u64"
           },
           {
             "name": "total_reimbursed",
+            "docs": [
+              "Lifetime monotonic reimbursement sum (operator pool-reimburse via",
+              "`reimburse_pool_from_fund`) — observability only."
+            ],
             "type": "u64"
           },
           {
             "name": "bump",
+            "docs": [
+              "Bump for this InsuranceFund PDA (`[b\"insurance_fund\"]`)."
+            ],
             "type": "u8"
           },
           {
             "name": "total_reimbursed_liquidator",
+            "docs": [
+              "Lifetime monotonic counter for liquidator-reward fallbacks (#44).",
+              "Incremented by `reimburse_liquidator` when perp-engine's liquidate",
+              "detects that `release_and_settle`'s PayDirect under-paid the",
+              "liquidator and the gap is sourced from the insurance fund.",
+              "Carved from the prior 32-byte `_reserved` slot — existing V1 PDAs",
+              "already have 8 zero bytes at this offset, so they decode as 0",
+              "the moment the program is redeployed (no realloc, no migration)."
+            ],
             "type": "u64"
           },
+          {
+            "name": "auto_payouts_frozen",
+            "docs": [
+              "Kill switch for the two AUTOMATIC insurance debits. When non-zero:",
+              "`reimburse_liquidator` (#44 liquidator-reward fallback) no-ops, and",
+              "`harvest`'s #129 queued-winner fallback declines to draw from the fund",
+              "(the winner stays queued until side_bucket / LP can cover it). The",
+              "MANUAL admin levers (`reimburse_pool_from_fund`, `withdraw_insurance`)",
+              "are intentionally NOT gated, so the fund stays usable as an emergency /",
+              "discretionary reserve that pays no one automatically. Toggled by the",
+              "admin via `set_insurance_auto_payouts` — reversible in one tx, no",
+              "realloc. Carved from `_reserved`, so existing on-chain PDAs decode it as",
+              "0 (= auto-payouts ENABLED, the pre-change behavior) on redeploy; turning",
+              "it off is one admin tx after the upgrade."
+            ],
+            "type": "u8"
+          },
           {
             "name": "_reserved",
+            "docs": [
+              "Forward-compat slot for v1.2 cap + cooldown fields. Do not remove.",
+              "Carved 32 → 24 → 23 bytes (the missing byte is `auto_payouts_frozen`",
+              "above). `InsuranceFund::LEN` stays at 122 — wire-compatible with V1."
+            ],
             "type": {
               "array": [
                 "u8",
-                24
+                23
               ]
             }
           }
@@ -2563,6 +3401,16 @@
     },
     {
       "name": "InsuranceReimbursedLiquidator",
+      "docs": [
+        "Followup #44 — liquidator-reward fallback path. Emitted by",
+        "`reimburse_liquidator` when perp-engine's liquidate handler detects",
+        "that `release_and_settle`'s saturating PayDirect under-paid the",
+        "liquidator and sources the gap from the insurance fund.",
+        "",
+        "`amount` is the shortfall covered by the fund (NOT the spec'd full",
+        "50-bps reward — that figure equals the prior `release_and_settle`",
+        "PayDirect transfer + `amount`)."
+      ],
       "type": {
         "kind": "struct",
         "fields": [
@@ -2597,6 +3445,37 @@
         ]
       }
     },
+    {
+      "name": "MarginReturned",
+      "docs": [
+        "Margin/profit split (2026-06-09). Emitted by `release_and_enqueue` when the",
+        "trader's own wallet-funded margin is returned directly in the close tx while",
+        "only the profit slice is enqueued. `amount` is the directly-paid margin (the",
+        "enqueued profit is reported separately by the paired `Enqueued` event)."
+      ],
+      "type": {
+        "kind": "struct",
+        "fields": [
+          {
+            "name": "market_id",
+            "type": {
+              "array": [
+                "u8",
+                32
+              ]
+            }
+          },
+          {
+            "name": "owner",
+            "type": "pubkey"
+          },
+          {
+            "name": "amount",
+            "type": "u64"
+          }
+        ]
+      }
+    },
     {
       "name": "PayoutQueueEntry",
       "type": {
@@ -2703,6 +3582,10 @@
           },
           {
             "name": "engine_auth",
+            "docs": [
+              "PDA from perp-engine authorized to call update_reserve and release_and_settle.",
+              "Derived: PDA([b\"engine_auth\", market_id], perp_engine_program_id)"
+            ],
             "type": "pubkey"
           },
           {
@@ -2748,6 +3631,14 @@
           {
             "name": "bump",
             "type": "u8"
+          },
+          {
+            "name": "current_adl_epoch",
+            "type": "u32"
+          },
+          {
+            "name": "last_adl_cut_idx",
+            "type": "u64"
           }
         ]
       }
@@ -2794,6 +3685,50 @@
         ]
       }
     },
+    {
+      "name": "RetroactiveFundingApplied",
+      "docs": [
+        "Retroactive funding correction (2026-06-09). Emitted by",
+        "`apply_retroactive_funding` when the admin debits a Pending queue IOU by the",
+        "funding it dodged while adaptive funding was structurally off (launch →",
+        "2026-06-09). `debit` is removed from the entry `amount`, the owner's",
+        "`unpaid_owed`, and `queue_total_owed`. Audit-trail event for the correction."
+      ],
+      "type": {
+        "kind": "struct",
+        "fields": [
+          {
+            "name": "idx",
+            "type": "u64"
+          },
+          {
+            "name": "owner",
+            "type": "pubkey"
+          },
+          {
+            "name": "market_id",
+            "type": {
+              "array": [
+                "u8",
+                32
+              ]
+            }
+          },
+          {
+            "name": "debit",
+            "type": "u64"
+          },
+          {
+            "name": "entry_amount_after",
+            "type": "u64"
+          },
+          {
+            "name": "queue_total_owed_after",
+            "type": "u64"
+          }
+        ]
+      }
+    },
     {
       "name": "Settled",
       "type": {
@@ -2844,6 +3779,42 @@
         ]
       }
     },
+    {
+      "name": "StrandedLpGainSweptToInsurance",
+      "docs": [
+        "Followup #123 — emitted when `release_and_settle` detects `lp_mint.supply == 0`",
+        "for the Treasury LP-route and sweeps the lp_gain to the insurance vault instead",
+        "of letting it strand in `pool.total_usdc` (where it would be claimable by the",
+        "first depositor as the deposit-withdraw recovery cycle exploits).",
+        "",
+        "Fires only when the caller passed the optional insurance accounts via",
+        "`remaining_accounts`. Old callers (perp-engine pre-#123) won't trigger this",
+        "event and the stranding will still occur — until perp-engine is upgraded",
+        "to forward the accounts."
+      ],
+      "type": {
+        "kind": "struct",
+        "fields": [
+          {
+            "name": "market_id",
+            "type": {
+              "array": [
+                "u8",
+                32
+              ]
+            }
+          },
+          {
+            "name": "amount",
+            "type": "u64"
+          },
+          {
+            "name": "total_accrued",
+            "type": "u64"
+          }
+        ]
+      }
+    },
     {
       "name": "UpdateFeeSettingsArgs",
       "type": {
@@ -2953,4 +3924,4 @@
       }
     }
   ]
-}
+}