@usesigil/kit 0.15.0 → 0.16.0

package/dist/post-assertions/cross-field-lte.d.ts

@@ -0,0 +1,134 @@
+/**
+ * @usesigil/kit/post-assertions — CrossFieldLte builder.
+ *
+ * Constructs a PostAssertionEntry that performs a ratio check on two byte
+ * offsets inside the same target account AFTER the DeFi call completes.
+ *
+ * The on-chain check: `field_A × 10000 ≤ multiplier_bps × field_B`
+ * (u128 safe math, cross-multiplication to avoid division).
+ *
+ * Typical use: leverage caps. field_A = sizeUsd, field_B = collateralUsd,
+ * multiplier_bps = maxLeverage × 10000. If the cap is violated, the program
+ * raises `PostAssertionFailed` (6068) and the entire transaction reverts.
+ *
+ * ## Jupiter Perpetuals UX rail — NOT a security boundary
+ *
+ * `leverageCapLteBps()` throws `JupiterPerpsPostAssertionUnsupportedError`
+ * when the caller supplies a target account owned by the Jupiter Perpetuals
+ * program. This is a **UX-level misuse-prevention guardrail**, NOT a
+ * security guarantee — the on-chain program does **not** reject Jupiter
+ * Perps target accounts. A caller who constructs a plain `PostAssertionEntry`
+ * object literal (skipping this builder) and passes it to
+ * `createPostAssertions(...)` WILL land an entry that targets a Jupiter
+ * Perps Position account. That entry will always pass trivially, because:
+ *
+ * Jupiter Perps uses a 2-transaction keeper-fulfillment model — the user's
+ * tx writes a PositionRequest, and a Jupiter-hosted keeper executes the
+ * actual position change up to 45 seconds later. Sigil's
+ * `finalize_session` reads account state in the USER's tx, not the keeper's,
+ * so the Jupiter Position account still reflects pre-trade state at check
+ * time. CrossFieldLte post-execution over that account therefore is a
+ * **silent constraint bypass** — the user thinks their leverage cap is
+ * active when it isn't.
+ *
+ * For REAL security on Jupiter Perps, combine with pre-execution
+ * `InstructionConstraints` (the `@sigil-trade/constraints` package compiles
+ * byte-level checks on Jupiter instruction args that the on-chain program
+ * enforces BEFORE the request hits the keeper — covers the same attack
+ * surface from the opposite direction).
+ *
+ * Follow-up work (tracked in the Phase 2 PRD as deferred): add an on-chain
+ * `target_account.owner` deny-list check in `finalize_session.rs` that
+ * rejects CrossFieldLte entries whose target account is owned by Jupiter
+ * Perpetuals. Until that lands, this builder's rail is defense-against-
+ * typos, nothing more.
+ *
+ * @see programs/sigil/src/state/post_assertions.rs — on-chain source of truth
+ * @see docs/LEVERAGE-ENFORCEMENT.md — full Jupiter Perps gap writeup
+ */
+import type { Address } from "@solana/kit";
+import type { PostAssertionEntry } from "../generated/types/postAssertionEntry.js";
+/**
+ * Jupiter Perpetuals program. Owner of Position + PositionRequest accounts.
+ *
+ * This is the ONLY Jupiter program the `leverageCapLteBps` builder refuses
+ * at authoring time (see the docblock above for why — UX rail, not on-chain
+ * security). Other Jupiter programs (V6 Aggregator, Lend, Earn, Borrow)
+ * execute synchronously in the user's transaction and work fine with
+ * post-execution assertions.
+ */
+export declare const JUPITER_PERPS_PROGRAM_ADDRESS: Address;
+/**
+ * Thrown by {@link leverageCapLteBps} when the target account is owned by
+ * the Jupiter Perpetuals program. Carries a long, copy-paste-friendly
+ * explanation so the error bubbling to the dashboard is actionable.
+ */
+export declare class JupiterPerpsPostAssertionUnsupportedError extends Error {
+    constructor(message: string);
+}
+/**
+ * Options for `leverageCapLteBps`.
+ *
+ * `targetAccountOwnerProgram` is REQUIRED (not optional) so that callers
+ * cannot accidentally bypass the Jupiter Perpetuals safety check by
+ * omitting the ownership hint. If the caller doesn't know the owner
+ * program, they shouldn't be building a post-execution leverage cap.
+ */
+export interface LeverageCapLteOpts {
+    /**
+     * Address of the account whose bytes will be inspected post-execution.
+     * Typically the Position PDA for the protocol being constrained
+     * (e.g. Flash Trade Position account).
+     */
+    targetAccount: Address;
+    /**
+     * Address of the program that OWNS `targetAccount`. Required for the
+     * Jupiter Perpetuals safety rail. When this matches
+     * {@link JUPITER_PERPS_PROGRAM_ADDRESS}, the helper throws
+     * {@link JupiterPerpsPostAssertionUnsupportedError} — see file header.
+     */
+    targetAccountOwnerProgram: Address;
+    /**
+     * Byte offset of field_A (the "numerator" field) inside `targetAccount`.
+     * Read as `u64` LE (8 bytes from this offset). Must be in `0..=65535`.
+     * Typical: `sizeUsd` offset = 140 on Flash Trade Position.
+     */
+    fieldAOffset: number;
+    /**
+     * Byte offset of field_B (the "denominator" field). Read as `u64` LE.
+     * Must be in `0..=65535` and MUST differ from `fieldAOffset` — comparing
+     * a field against itself is either a no-op or a trap.
+     * Typical: `collateralUsd` offset = 172 on Flash Trade Position.
+     */
+    fieldBOffset: number;
+    /**
+     * Leverage cap expressed in basis points: `maxBps = leverage × 10_000`.
+     *
+     * The on-chain check is `field_A × 10_000 ≤ maxBps × field_B`.
+     * Examples:
+     *   - 10×     → `maxBps = 100_000`
+     *   - 50×     → `maxBps = 500_000`
+     *   - 100×    → `maxBps = 1_000_000`
+     *
+     * Must be a positive integer in `1..=u32::MAX`. Prefer conservative caps;
+     * never set to the protocol's maximum.
+     */
+    maxBps: number;
+}
+/**
+ * Build a PostAssertionEntry that enforces a leverage cap via the
+ * CrossFieldLte ratio check.
+ *
+ * Validates inputs, rejects Jupiter Perpetuals Position accounts at the
+ * call site, and returns an entry ready to pass to
+ * `createPostAssertions(rpc, vault, owner, network, [entry])`.
+ *
+ * @throws {JupiterPerpsPostAssertionUnsupportedError}
+ *   When `targetAccountOwnerProgram` matches
+ *   {@link JUPITER_PERPS_PROGRAM_ADDRESS}. See file header for why.
+ * @throws {RangeError}
+ *   When offsets are not integers in `0..=65535`, are equal to each other,
+ *   or when `maxBps` is not a positive integer in `1..=u32::MAX`.
+ */
+export declare function leverageCapLteBps(opts: LeverageCapLteOpts): PostAssertionEntry;
+//# sourceMappingURL=cross-field-lte.d.ts.map

package/dist/post-assertions/cross-field-lte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cross-field-lte.d.ts","sourceRoot":"","sources":["../../src/post-assertions/cross-field-lte.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,OAAO,KAAK,EAAE,OAAO,EAAsB,MAAM,aAAa,CAAC;AAC/D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0CAA0C,CAAC;AAInF;;;;;;;;GAQG;AACH,eAAO,MAAM,6BAA6B,EACS,OAAO,CAAC;AA2C3D;;;;GAIG;AACH,qBAAa,yCAA0C,SAAQ,KAAK;gBACtD,OAAO,EAAE,MAAM;CAQ5B;AAID;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,aAAa,EAAE,OAAO,CAAC;IACvB;;;;;OAKG;IACH,yBAAyB,EAAE,OAAO,CAAC;IACnC;;;;OAIG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB;;;;;;;;;;;OAWG;IACH,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,kBAAkB,GACvB,kBAAkB,CAmDpB"}

package/dist/post-assertions/cross-field-lte.js

@@ -0,0 +1,129 @@
+// ─── Constants ────────────────────────────────────────────────────────────
+/**
+ * Jupiter Perpetuals program. Owner of Position + PositionRequest accounts.
+ *
+ * This is the ONLY Jupiter program the `leverageCapLteBps` builder refuses
+ * at authoring time (see the docblock above for why — UX rail, not on-chain
+ * security). Other Jupiter programs (V6 Aggregator, Lend, Earn, Borrow)
+ * execute synchronously in the user's transaction and work fine with
+ * post-execution assertions.
+ */
+export const JUPITER_PERPS_PROGRAM_ADDRESS = "PERPHjGBqRHArX4DySjwM6UJHiR3sWAatqfdBS2qQJu";
+/**
+ * CrossFieldLte enable bit — bit 0 of `cross_field_flags`.
+ * Every other bit is reserved; the on-chain validator rejects unknown flags.
+ */
+const CROSS_FIELD_LTE_FLAG = 0x01;
+/**
+ * Both field_A and field_B are parsed as `u64::from_le_bytes(bytes[0..8])`
+ * on-chain when CrossFieldLte is enabled. Entry's `value_len` MUST be 8.
+ */
+const CROSS_FIELD_VALUE_LEN = 8;
+/**
+ * CrossFieldLte only composes with Absolute assertion_mode. Delta modes
+ * (1/2/3) would re-interpret the snapshot bytes as field_A, which is
+ * semantically nonsensical — on-chain hard-rejects.
+ */
+const ABSOLUTE_ASSERTION_MODE = 0;
+/**
+ * Lte operator (3). Not actually consulted at runtime when the CrossField
+ * flag is set — the on-chain code branches to the ratio check and ignores
+ * operator/expected_value. Set to 3 here as a semantic hint for anyone
+ * inspecting the raw entry: "this is a less-than-or-equal check."
+ */
+const LTE_OPERATOR = 3;
+/**
+ * u16 range guard for byte offsets. Account data is at most ~10MB but
+ * PostAssertionEntry.offset is a u16 on-chain, capping at 65535.
+ */
+const MAX_U16 = 0xffff;
+/**
+ * u32 range guard for `cross_field_multiplier_bps`. The on-chain type is
+ * u32. Values above this would overflow deserialization.
+ */
+const MAX_U32 = 0xffffffff;
+// ─── Errors ───────────────────────────────────────────────────────────────
+/**
+ * Thrown by {@link leverageCapLteBps} when the target account is owned by
+ * the Jupiter Perpetuals program. Carries a long, copy-paste-friendly
+ * explanation so the error bubbling to the dashboard is actionable.
+ */
+export class JupiterPerpsPostAssertionUnsupportedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "JupiterPerpsPostAssertionUnsupportedError";
+        Object.setPrototypeOf(this, JupiterPerpsPostAssertionUnsupportedError.prototype);
+    }
+}
+/**
+ * Build a PostAssertionEntry that enforces a leverage cap via the
+ * CrossFieldLte ratio check.
+ *
+ * Validates inputs, rejects Jupiter Perpetuals Position accounts at the
+ * call site, and returns an entry ready to pass to
+ * `createPostAssertions(rpc, vault, owner, network, [entry])`.
+ *
+ * @throws {JupiterPerpsPostAssertionUnsupportedError}
+ *   When `targetAccountOwnerProgram` matches
+ *   {@link JUPITER_PERPS_PROGRAM_ADDRESS}. See file header for why.
+ * @throws {RangeError}
+ *   When offsets are not integers in `0..=65535`, are equal to each other,
+ *   or when `maxBps` is not a positive integer in `1..=u32::MAX`.
+ */
+export function leverageCapLteBps(opts) {
+    // Runtime Jupiter Perps reject (Phase 2 ISC-37, anti-criterion ISC-A1).
+    // Fails before any further validation so the error surface points at
+    // the real problem rather than incidental validation failures.
+    if (opts.targetAccountOwnerProgram === JUPITER_PERPS_PROGRAM_ADDRESS) {
+        throw new JupiterPerpsPostAssertionUnsupportedError(`Post-execution CrossFieldLte is NOT viable on Jupiter Perpetuals Position accounts.\n\n` +
+            `Reason: Jupiter Perps uses a 2-transaction keeper-fulfillment model. The user's tx writes ` +
+            `to a PositionRequest account; a Jupiter-hosted keeper executes the actual position change ` +
+            `up to 45 seconds later in a separate tx. Sigil's finalize_session reads account state in ` +
+            `the user's tx — at that point the Jupiter Position account still reflects pre-trade state. ` +
+            `The leverage check would always pass trivially, creating a silent constraint bypass.\n\n` +
+            `Jupiter Perps remains a fully supported protocol for agent use. Configure constraints ` +
+            `via pre-execution InstructionConstraints instead — @sigil-trade/constraints compiles ` +
+            `byte-level checks on Jupiter instruction args (sizeUsd, collateralUsd in the request) ` +
+            `that are enforced BEFORE the request hits the keeper.\n\n` +
+            `See docs/LEVERAGE-ENFORCEMENT.md — "Jupiter Perps — use pre-execution constraints".`);
+    }
+    // Offset range / integrality checks (u16 on-chain).
+    requireIntegerInRange(opts.fieldAOffset, "fieldAOffset", 0, MAX_U16);
+    requireIntegerInRange(opts.fieldBOffset, "fieldBOffset", 0, MAX_U16);
+    if (opts.fieldAOffset === opts.fieldBOffset) {
+        throw new RangeError(`leverageCapLteBps: fieldAOffset and fieldBOffset must differ — ratio of a field against itself is nonsensical (got ${opts.fieldAOffset})`);
+    }
+    // Multiplier range / integrality check (u32 on-chain, must be > 0).
+    requireIntegerInRange(opts.maxBps, "maxBps", 1, MAX_U32);
+    // All-zero expected_value — the on-chain CrossField path ignores this
+    // field, but validate_entries still requires `expected_value.len() >=
+    // value_len`. We ship exactly `CROSS_FIELD_VALUE_LEN` (8) bytes to
+    // satisfy the size invariant without wasting space.
+    const expectedValue = new Uint8Array(CROSS_FIELD_VALUE_LEN);
+    return {
+        targetAccount: opts.targetAccount,
+        offset: opts.fieldAOffset,
+        valueLen: CROSS_FIELD_VALUE_LEN,
+        operator: LTE_OPERATOR,
+        expectedValue,
+        assertionMode: ABSOLUTE_ASSERTION_MODE,
+        crossFieldOffsetB: opts.fieldBOffset,
+        crossFieldMultiplierBps: opts.maxBps,
+        crossFieldFlags: CROSS_FIELD_LTE_FLAG,
+    };
+}
+// ─── Internal ─────────────────────────────────────────────────────────────
+/**
+ * Guard that rejects non-integer, out-of-range, or non-finite values.
+ * Matches JS's pre-coercion discipline: a string `"8"` should NOT silently
+ * pass an integer check, and `NaN` / `Infinity` must not sneak through.
+ */
+function requireIntegerInRange(value, field, min, max) {
+    if (typeof value !== "number" || !Number.isInteger(value)) {
+        throw new RangeError(`leverageCapLteBps: ${field} must be an integer, got ${JSON.stringify(value)} (${typeof value})`);
+    }
+    if (value < min || value > max) {
+        throw new RangeError(`leverageCapLteBps: ${field} must be in ${min}..=${max}, got ${value}`);
+    }
+}
+//# sourceMappingURL=cross-field-lte.js.map

package/dist/post-assertions/cross-field-lte.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cross-field-lte.js","sourceRoot":"","sources":["../../src/post-assertions/cross-field-lte.ts"],"names":[],"mappings":"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"}

package/dist/post-assertions/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `@usesigil/kit/post-assertions` — builders for post-execution assertion
+ * entries.
+ *
+ * This barrel exposes the typed helpers a dashboard or headless caller
+ * needs to author `PostAssertionEntry` values for the
+ * `createPostAssertions(...)` mutation without reaching into codegen
+ * (covenant D1: no imports from `src/generated/**`).
+ *
+ * Currently exported:
+ * - `leverageCapLteBps({ ... })` — generic CrossFieldLte builder for a
+ *   "field_A ≤ maxBps × field_B" ratio check
+ * - `JupiterPerpsPostAssertionUnsupportedError` — thrown when a caller
+ *   tries to build a leverage cap against a Jupiter Perpetuals Position
+ *   account (keeper-fulfillment model breaks post-execution semantics)
+ * - `JUPITER_PERPS_PROGRAM_ADDRESS` — re-exported so callers can do their
+ *   own pre-check if they prefer reporting over throwing
+ *
+ * Protocol-specific presets (e.g. `flashTradeLeverageCap`) land in a
+ * `./presets/` sub-directory as they ship — one preset per protocol,
+ * each backed by a committed IDL with a CI drift-check.
+ */
+export { JUPITER_PERPS_PROGRAM_ADDRESS, JupiterPerpsPostAssertionUnsupportedError, leverageCapLteBps, } from "./cross-field-lte.js";
+export type { LeverageCapLteOpts } from "./cross-field-lte.js";
+export { FLASH_TRADE_PROGRAM_ADDRESS, FLASH_TRADE_POSITION_SIZE_USD_OFFSET, FLASH_TRADE_POSITION_COLLATERAL_USD_OFFSET, MIN_LEVERAGE_X, MAX_LEVERAGE_X, FlashTradeLeverageOutOfRangeError, flashTradeLeverageCap, } from "./presets/flash-trade.js";
+export type { FlashTradeLeverageCapOpts } from "./presets/flash-trade.js";
+export type { PostAssertionEntry } from "../generated/types/postAssertionEntry.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/post-assertions/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/post-assertions/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EACL,6BAA6B,EAC7B,yCAAyC,EACzC,iBAAiB,GAClB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAK/D,OAAO,EACL,2BAA2B,EAC3B,oCAAoC,EACpC,0CAA0C,EAC1C,cAAc,EACd,cAAc,EACd,iCAAiC,EACjC,qBAAqB,GACtB,MAAM,0BAA0B,CAAC;AAClC,YAAY,EAAE,yBAAyB,EAAE,MAAM,0BAA0B,CAAC;AAK1E,YAAY,EAAE,kBAAkB,EAAE,MAAM,0CAA0C,CAAC"}

package/dist/post-assertions/index.js

@@ -0,0 +1,28 @@
+/**
+ * `@usesigil/kit/post-assertions` — builders for post-execution assertion
+ * entries.
+ *
+ * This barrel exposes the typed helpers a dashboard or headless caller
+ * needs to author `PostAssertionEntry` values for the
+ * `createPostAssertions(...)` mutation without reaching into codegen
+ * (covenant D1: no imports from `src/generated/**`).
+ *
+ * Currently exported:
+ * - `leverageCapLteBps({ ... })` — generic CrossFieldLte builder for a
+ *   "field_A ≤ maxBps × field_B" ratio check
+ * - `JupiterPerpsPostAssertionUnsupportedError` — thrown when a caller
+ *   tries to build a leverage cap against a Jupiter Perpetuals Position
+ *   account (keeper-fulfillment model breaks post-execution semantics)
+ * - `JUPITER_PERPS_PROGRAM_ADDRESS` — re-exported so callers can do their
+ *   own pre-check if they prefer reporting over throwing
+ *
+ * Protocol-specific presets (e.g. `flashTradeLeverageCap`) land in a
+ * `./presets/` sub-directory as they ship — one preset per protocol,
+ * each backed by a committed IDL with a CI drift-check.
+ */
+export { JUPITER_PERPS_PROGRAM_ADDRESS, JupiterPerpsPostAssertionUnsupportedError, leverageCapLteBps, } from "./cross-field-lte.js";
+// Protocol-specific presets — one file per protocol under `./presets/`.
+// Each preset is backed by a committed IDL source with a drift-check test so
+// any future SDK bump that shifts field offsets fails before shipping.
+export { FLASH_TRADE_PROGRAM_ADDRESS, FLASH_TRADE_POSITION_SIZE_USD_OFFSET, FLASH_TRADE_POSITION_COLLATERAL_USD_OFFSET, MIN_LEVERAGE_X, MAX_LEVERAGE_X, FlashTradeLeverageOutOfRangeError, flashTradeLeverageCap, } from "./presets/flash-trade.js";
+//# sourceMappingURL=index.js.map

package/dist/post-assertions/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/post-assertions/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EACL,6BAA6B,EAC7B,yCAAyC,EACzC,iBAAiB,GAClB,MAAM,sBAAsB,CAAC;AAG9B,wEAAwE;AACxE,6EAA6E;AAC7E,uEAAuE;AACvE,OAAO,EACL,2BAA2B,EAC3B,oCAAoC,EACpC,0CAA0C,EAC1C,cAAc,EACd,cAAc,EACd,iCAAiC,EACjC,qBAAqB,GACtB,MAAM,0BAA0B,CAAC"}

package/dist/post-assertions/presets/flash-trade.d.ts

@@ -0,0 +1,139 @@
+/**
+ * `@usesigil/kit/post-assertions/presets/flash-trade` — Flash Trade leverage cap preset.
+ *
+ * Convenience wrapper around `leverageCapLteBps` that fills in the byte offsets
+ * of a Flash Trade Position account's `size_usd` and `collateral_usd` fields.
+ *
+ * Callers provide a position account address + a leverage cap expressed in
+ * "x" (multiples), and the preset returns a `PostAssertionEntry` that the
+ * on-chain program enforces as:
+ *
+ *     size_usd × 10000 ≤ maxLeverage × 10000 × collateral_usd
+ *     ⇔ leverage (= size_usd / collateral_usd) ≤ maxLeverage
+ *
+ * ## Field offsets (pinned to flash-sdk@15.x Perpetuals IDL)
+ *
+ * Derived from the Anchor IDL shipped with `flash-sdk@^15.14.1`
+ * (`node_modules/flash-sdk/dist/idl/perpetuals.json`). Position account
+ * Borsh layout, starting after the 8-byte Anchor discriminator:
+ *
+ *     offset  field                  type   size
+ *         8   owner                  pubkey 32
+ *        40   market                 pubkey 32
+ *        72   delegate               pubkey 32
+ *       104   open_time              i64    8
+ *       112   update_time            i64    8
+ *       120   entry_price            OraclePrice { price: u64, exponent: i32 } 12
+ *       132   size_amount            u64    8
+ *    → 140   size_usd                u64    8
+ *       148   locked_amount          u64    8
+ *       156   locked_usd             u64    8
+ *       164   price_impact_usd       u64    8
+ *    → 172   collateral_usd          u64    8
+ *       ...
+ *
+ * A drift-check unit test (`presets/flash-trade.test.ts`) reloads the Anchor
+ * IDL from `flash-sdk` at test time and recomputes offsets — any future
+ * flash-sdk bump that shifts these fields fails the test before a broken
+ * preset can ship.
+ *
+ * ## Jupiter Perps is NOT supported here
+ *
+ * Flash Trade executes position changes synchronously in the user's tx, so
+ * post-execution assertions are meaningful. Jupiter Perpetuals uses a 2-tx
+ * keeper-fulfillment model that silently bypasses post-assertions — that gate
+ * is enforced upstream in `leverageCapLteBps` via
+ * `JupiterPerpsPostAssertionUnsupportedError`, so a caller who mistakenly
+ * plugs a Jupiter Perps Position address here gets an explicit error.
+ *
+ * ## Bounds on `maxLeverage`
+ *
+ * `maxLeverage` is an integer multiplier (e.g., 5 = 5x cap). We reject
+ * values outside [1, 100]:
+ *   - 0 would encode `size_usd ≤ 0` — any non-zero position fails, effectively
+ *     a kill-switch. Safer to reject and let callers use `closePostAssertions`
+ *     if they want to disable the cap entirely.
+ *   - Values > 100 exceed any practical Flash Trade leverage (current mainnet
+ *     caps sit around 25-50x) and are almost certainly caller bugs.
+ *
+ * @see programs/sigil/src/state/post_assertions.rs — on-chain CrossFieldLte enforcer
+ * @see `@usesigil/kit/post-assertions/cross-field-lte.ts` — underlying builder
+ */
+import type { Address } from "@solana/kit";
+import type { PostAssertionEntry } from "../../generated/types/postAssertionEntry.js";
+/**
+ * Flash Trade Perpetuals program address (mainnet-beta). Owner of Position
+ * accounts that this preset targets.
+ *
+ * Source: `constants` module in `flash-sdk@^15.14.1`. Hard-coded here so the
+ * preset is importable without loading the full flash-sdk runtime.
+ */
+export declare const FLASH_TRADE_PROGRAM_ADDRESS: Address;
+/**
+ * Byte offset of `size_usd` (u64, little-endian) inside Flash Trade Position
+ * account data, starting from byte 0 of the account (NOT after discriminator).
+ *
+ * Pinned to flash-sdk@^15.14.1 Perpetuals IDL. A drift-check unit test
+ * reloads the IDL and asserts this value matches.
+ */
+export declare const FLASH_TRADE_POSITION_SIZE_USD_OFFSET = 140;
+/**
+ * Byte offset of `collateral_usd` (u64, little-endian) inside Flash Trade
+ * Position account data.
+ *
+ * Pinned to flash-sdk@^15.14.1 Perpetuals IDL. Drift-check test guards this.
+ */
+export declare const FLASH_TRADE_POSITION_COLLATERAL_USD_OFFSET = 172;
+/**
+ * Lowest permitted `maxLeverage` input — 1x. Zero would encode a kill-switch.
+ */
+export declare const MIN_LEVERAGE_X = 1;
+/**
+ * Highest permitted `maxLeverage` input. 100x is a generous upper bound above
+ * any practical Flash Trade cap.
+ */
+export declare const MAX_LEVERAGE_X = 100;
+/**
+ * Thrown when `maxLeverage` is outside [MIN_LEVERAGE_X, MAX_LEVERAGE_X] or
+ * not an integer. Carries a DxError-compatible shape so FE can branch on
+ * `.code` without `instanceof` checks that break across module realms.
+ */
+export declare class FlashTradeLeverageOutOfRangeError extends Error {
+    /** DxError-compatible numeric code. 7009 reserved for preset validation. */
+    readonly code: number;
+    readonly recovery: readonly string[];
+    /**
+     * Always `false` — thrown at CLIENT validation time, before any RPC
+     * round-trip. Present to satisfy DxError's structural contract (every
+     * DxError carries `onChainReverted`; see v2.2 contract C2).
+     */
+    readonly onChainReverted: boolean;
+    readonly received: unknown;
+    constructor(received: unknown);
+}
+export interface FlashTradeLeverageCapOpts {
+    /** Base-58 pubkey of the Flash Trade Position account to monitor. */
+    readonly positionAccount: Address;
+    /**
+     * Maximum leverage in "x" units (e.g. 5 = 5x). Integer in [1, 100].
+     * The preset throws `FlashTradeLeverageOutOfRangeError` on anything else.
+     */
+    readonly maxLeverage: number;
+}
+/**
+ * Build a post-assertion entry that caps Flash Trade leverage at `maxLeverage` × .
+ *
+ * Equivalent to calling {@link leverageCapLteBps} with Flash Trade's Position
+ * `size_usd` / `collateral_usd` offsets filled in, `targetAccountOwnerProgram`
+ * set to {@link FLASH_TRADE_PROGRAM_ADDRESS}, and `maxBps = maxLeverage * 10000`.
+ *
+ * @throws {FlashTradeLeverageOutOfRangeError} if `maxLeverage` is not an
+ * integer in [1, 100].
+ * @throws {import("../cross-field-lte.js").JupiterPerpsPostAssertionUnsupportedError}
+ * re-thrown by the underlying builder if `targetAccountOwnerProgram` ever
+ * drifts to Jupiter Perps (defense-in-depth — Flash Trade's program address
+ * is hard-coded here, so this throw indicates either a preset bug or a
+ * caller who hand-mutated the returned entry before submitting).
+ */
+export declare function flashTradeLeverageCap(opts: FlashTradeLeverageCapOpts): PostAssertionEntry;
+//# sourceMappingURL=flash-trade.d.ts.map

package/dist/post-assertions/presets/flash-trade.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flash-trade.d.ts","sourceRoot":"","sources":["../../../src/post-assertions/presets/flash-trade.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,6CAA6C,CAAC;AAKtF;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B,EACY,OAAO,CAAC;AAE5D;;;;;;GAMG;AACH,eAAO,MAAM,oCAAoC,MAAM,CAAC;AAExD;;;;;GAKG;AACH,eAAO,MAAM,0CAA0C,MAAM,CAAC;AAE9D;;GAEG;AACH,eAAO,MAAM,cAAc,IAAI,CAAC;AAEhC;;;GAGG;AACH,eAAO,MAAM,cAAc,MAAM,CAAC;AAIlC;;;;GAIG;AACH,qBAAa,iCAAkC,SAAQ,KAAK;IAC1D,4EAA4E;IAC5E,SAAgB,IAAI,EAAE,MAAM,CAAQ;IACpC,SAAgB,QAAQ,EAAE,SAAS,MAAM,EAAE,CAGzC;IACF;;;;OAIG;IACH,SAAgB,eAAe,EAAE,OAAO,CAAS;IACjD,SAAgB,QAAQ,EAAE,OAAO,CAAC;gBAEtB,QAAQ,EAAE,OAAO;CAQ9B;AAID,MAAM,WAAW,yBAAyB;IACxC,qEAAqE;IACrE,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAID;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,yBAAyB,GAC9B,kBAAkB,CAkBpB"}

package/dist/post-assertions/presets/flash-trade.js

@@ -0,0 +1,154 @@
+/**
+ * `@usesigil/kit/post-assertions/presets/flash-trade` — Flash Trade leverage cap preset.
+ *
+ * Convenience wrapper around `leverageCapLteBps` that fills in the byte offsets
+ * of a Flash Trade Position account's `size_usd` and `collateral_usd` fields.
+ *
+ * Callers provide a position account address + a leverage cap expressed in
+ * "x" (multiples), and the preset returns a `PostAssertionEntry` that the
+ * on-chain program enforces as:
+ *
+ *     size_usd × 10000 ≤ maxLeverage × 10000 × collateral_usd
+ *     ⇔ leverage (= size_usd / collateral_usd) ≤ maxLeverage
+ *
+ * ## Field offsets (pinned to flash-sdk@15.x Perpetuals IDL)
+ *
+ * Derived from the Anchor IDL shipped with `flash-sdk@^15.14.1`
+ * (`node_modules/flash-sdk/dist/idl/perpetuals.json`). Position account
+ * Borsh layout, starting after the 8-byte Anchor discriminator:
+ *
+ *     offset  field                  type   size
+ *         8   owner                  pubkey 32
+ *        40   market                 pubkey 32
+ *        72   delegate               pubkey 32
+ *       104   open_time              i64    8
+ *       112   update_time            i64    8
+ *       120   entry_price            OraclePrice { price: u64, exponent: i32 } 12
+ *       132   size_amount            u64    8
+ *    → 140   size_usd                u64    8
+ *       148   locked_amount          u64    8
+ *       156   locked_usd             u64    8
+ *       164   price_impact_usd       u64    8
+ *    → 172   collateral_usd          u64    8
+ *       ...
+ *
+ * A drift-check unit test (`presets/flash-trade.test.ts`) reloads the Anchor
+ * IDL from `flash-sdk` at test time and recomputes offsets — any future
+ * flash-sdk bump that shifts these fields fails the test before a broken
+ * preset can ship.
+ *
+ * ## Jupiter Perps is NOT supported here
+ *
+ * Flash Trade executes position changes synchronously in the user's tx, so
+ * post-execution assertions are meaningful. Jupiter Perpetuals uses a 2-tx
+ * keeper-fulfillment model that silently bypasses post-assertions — that gate
+ * is enforced upstream in `leverageCapLteBps` via
+ * `JupiterPerpsPostAssertionUnsupportedError`, so a caller who mistakenly
+ * plugs a Jupiter Perps Position address here gets an explicit error.
+ *
+ * ## Bounds on `maxLeverage`
+ *
+ * `maxLeverage` is an integer multiplier (e.g., 5 = 5x cap). We reject
+ * values outside [1, 100]:
+ *   - 0 would encode `size_usd ≤ 0` — any non-zero position fails, effectively
+ *     a kill-switch. Safer to reject and let callers use `closePostAssertions`
+ *     if they want to disable the cap entirely.
+ *   - Values > 100 exceed any practical Flash Trade leverage (current mainnet
+ *     caps sit around 25-50x) and are almost certainly caller bugs.
+ *
+ * @see programs/sigil/src/state/post_assertions.rs — on-chain CrossFieldLte enforcer
+ * @see `@usesigil/kit/post-assertions/cross-field-lte.ts` — underlying builder
+ */
+import { leverageCapLteBps } from "../cross-field-lte.js";
+// ─── Constants ────────────────────────────────────────────────────────────
+/**
+ * Flash Trade Perpetuals program address (mainnet-beta). Owner of Position
+ * accounts that this preset targets.
+ *
+ * Source: `constants` module in `flash-sdk@^15.14.1`. Hard-coded here so the
+ * preset is importable without loading the full flash-sdk runtime.
+ */
+export const FLASH_TRADE_PROGRAM_ADDRESS = "FLaSh6f6Y5bLsmcfiaxvqRJC3WQLKYh1iCfAsh7uMH8z";
+/**
+ * Byte offset of `size_usd` (u64, little-endian) inside Flash Trade Position
+ * account data, starting from byte 0 of the account (NOT after discriminator).
+ *
+ * Pinned to flash-sdk@^15.14.1 Perpetuals IDL. A drift-check unit test
+ * reloads the IDL and asserts this value matches.
+ */
+export const FLASH_TRADE_POSITION_SIZE_USD_OFFSET = 140;
+/**
+ * Byte offset of `collateral_usd` (u64, little-endian) inside Flash Trade
+ * Position account data.
+ *
+ * Pinned to flash-sdk@^15.14.1 Perpetuals IDL. Drift-check test guards this.
+ */
+export const FLASH_TRADE_POSITION_COLLATERAL_USD_OFFSET = 172;
+/**
+ * Lowest permitted `maxLeverage` input — 1x. Zero would encode a kill-switch.
+ */
+export const MIN_LEVERAGE_X = 1;
+/**
+ * Highest permitted `maxLeverage` input. 100x is a generous upper bound above
+ * any practical Flash Trade cap.
+ */
+export const MAX_LEVERAGE_X = 100;
+// ─── Errors ───────────────────────────────────────────────────────────────
+/**
+ * Thrown when `maxLeverage` is outside [MIN_LEVERAGE_X, MAX_LEVERAGE_X] or
+ * not an integer. Carries a DxError-compatible shape so FE can branch on
+ * `.code` without `instanceof` checks that break across module realms.
+ */
+export class FlashTradeLeverageOutOfRangeError extends Error {
+    /** DxError-compatible numeric code. 7009 reserved for preset validation. */
+    code = 7009;
+    recovery = [
+        `Pass a whole number between ${MIN_LEVERAGE_X} and ${MAX_LEVERAGE_X}.`,
+        "To disable an existing leverage cap, call `closePostAssertions(...)`.",
+    ];
+    /**
+     * Always `false` — thrown at CLIENT validation time, before any RPC
+     * round-trip. Present to satisfy DxError's structural contract (every
+     * DxError carries `onChainReverted`; see v2.2 contract C2).
+     */
+    onChainReverted = false;
+    received;
+    constructor(received) {
+        super(`flashTradeLeverageCap: maxLeverage must be an integer in [${MIN_LEVERAGE_X}, ${MAX_LEVERAGE_X}] (got ${String(received)})`);
+        this.name = "FlashTradeLeverageOutOfRangeError";
+        this.received = received;
+        // TS target=ES2020 preserves .name/.message across supers; no extra handling needed.
+    }
+}
+// ─── Builder ──────────────────────────────────────────────────────────────
+/**
+ * Build a post-assertion entry that caps Flash Trade leverage at `maxLeverage` × .
+ *
+ * Equivalent to calling {@link leverageCapLteBps} with Flash Trade's Position
+ * `size_usd` / `collateral_usd` offsets filled in, `targetAccountOwnerProgram`
+ * set to {@link FLASH_TRADE_PROGRAM_ADDRESS}, and `maxBps = maxLeverage * 10000`.
+ *
+ * @throws {FlashTradeLeverageOutOfRangeError} if `maxLeverage` is not an
+ * integer in [1, 100].
+ * @throws {import("../cross-field-lte.js").JupiterPerpsPostAssertionUnsupportedError}
+ * re-thrown by the underlying builder if `targetAccountOwnerProgram` ever
+ * drifts to Jupiter Perps (defense-in-depth — Flash Trade's program address
+ * is hard-coded here, so this throw indicates either a preset bug or a
+ * caller who hand-mutated the returned entry before submitting).
+ */
+export function flashTradeLeverageCap(opts) {
+    if (!Number.isInteger(opts.maxLeverage) ||
+        opts.maxLeverage < MIN_LEVERAGE_X ||
+        opts.maxLeverage > MAX_LEVERAGE_X) {
+        throw new FlashTradeLeverageOutOfRangeError(opts.maxLeverage);
+    }
+    const maxBps = opts.maxLeverage * 10_000;
+    return leverageCapLteBps({
+        targetAccount: opts.positionAccount,
+        targetAccountOwnerProgram: FLASH_TRADE_PROGRAM_ADDRESS,
+        fieldAOffset: FLASH_TRADE_POSITION_SIZE_USD_OFFSET,
+        fieldBOffset: FLASH_TRADE_POSITION_COLLATERAL_USD_OFFSET,
+        maxBps,
+    });
+}
+//# sourceMappingURL=flash-trade.js.map

package/dist/post-assertions/presets/flash-trade.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flash-trade.js","sourceRoot":"","sources":["../../../src/post-assertions/presets/flash-trade.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AAIH,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAE1D,6EAA6E;AAE7E;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,2BAA2B,GACtC,8CAAyD,CAAC;AAE5D;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,oCAAoC,GAAG,GAAG,CAAC;AAExD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,0CAA0C,GAAG,GAAG,CAAC;AAE9D;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC;AAEhC;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,GAAG,CAAC;AAElC,6EAA6E;AAE7E;;;;GAIG;AACH,MAAM,OAAO,iCAAkC,SAAQ,KAAK;IAC1D,4EAA4E;IAC5D,IAAI,GAAW,IAAI,CAAC;IACpB,QAAQ,GAAsB;QAC5C,+BAA+B,cAAc,QAAQ,cAAc,GAAG;QACtE,uEAAuE;KACxE,CAAC;IACF;;;;OAIG;IACa,eAAe,GAAY,KAAK,CAAC;IACjC,QAAQ,CAAU;IAElC,YAAY,QAAiB;QAC3B,KAAK,CACH,6DAA6D,cAAc,KAAK,cAAc,UAAU,MAAM,CAAC,QAAQ,CAAC,GAAG,CAC5H,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,mCAAmC,CAAC;QAChD,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,qFAAqF;IACvF,CAAC;CACF;AAcD,6EAA6E;AAE7E;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,qBAAqB,CACnC,IAA+B;IAE/B,IACE,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,WAAW,CAAC;QACnC,IAAI,CAAC,WAAW,GAAG,cAAc;QACjC,IAAI,CAAC,WAAW,GAAG,cAAc,EACjC,CAAC;QACD,MAAM,IAAI,iCAAiC,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IAChE,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,CAAC,WAAW,GAAG,MAAM,CAAC;IAEzC,OAAO,iBAAiB,CAAC;QACvB,aAAa,EAAE,IAAI,CAAC,eAAe;QACnC,yBAAyB,EAAE,2BAA2B;QACtD,YAAY,EAAE,oCAAoC;QAClD,YAAY,EAAE,0CAA0C;QACxD,MAAM;KACP,CAAC,CAAC;AACL,CAAC"}