@parchment-trade/sdk 0.0.0-stage → 1.0.1

package/dist/packages/parchment/batchClose.d.ts

@@ -0,0 +1,268 @@
+import { Transaction } from "@mysten/sui/transactions";
+import type { ParchmentTxRequest } from "./parchmentTypes.js";
+import { type ParchmentTxTrustSetting } from "./txIntent.js";
+/**
+ * Sui protocol limits a batch must stay within (protocol config, mainnet v137:
+ * `max_programmable_tx_commands`, `max_tx_size_bytes`, `max_num_event_emit`,
+ * `max_num_new_move_object_ids`, `max_arguments`).
+ */
+export declare const SUI_TX_LIMITS: {
+    readonly commands: 1024;
+    readonly txBytes: number;
+    readonly events: 1024;
+    readonly newObjectIds: 2048;
+    readonly argumentsPerCommand: 512;
+};
+/**
+ * What a batch may use. Commands and arguments are measured exactly on the tx as it resolves
+ * (wallet coin included), so they get the full limit. The kind's bytes get 3/4: the rest covers what
+ * is added after the kind (the gas payment, up to `max_gas_payment_objects` 256 refs ~19 KiB, the
+ * TransactionData envelope, the signatures: zkLogin / multisig, a few KiB), all counted by
+ * `max_tx_size_bytes`. Events and new ids only show at execution: they are upper bounds counted
+ * from the contracts (`LEG_EXECUTION`) and get 3/4, the one safety margin on those counts. The game
+ * progression events ({@link playerProgressionEvents}) are an exact maximum from the contract
+ * constants, so they take their share of Sui's 1,024 directly and the 3/4 applies to the rest:
+ * leg events <= 768 x (1,024 - progression) / 1,024.
+ */
+export declare const CLOSE_BATCH_BUDGET: {
+    readonly commands: 1024;
+    readonly txBytes: number;
+    readonly events: 768;
+    readonly newObjectIds: 1536;
+    readonly argumentsPerCommand: 512;
+};
+/**
+ * What the gas sponsor takes in one session-key transaction (the sponsor service:
+ * the earlier fixed 16 is gone):
+ * - a Close All of `request_close_as_delegate` legs only: one command and at most
+ *   {@link SPONSOR_BATCH_BUDGET.inputsPerTrade} distinct inputs per close (never fewer than
+ *   {@link SPONSOR_BATCH_BUDGET.inputs} allowed), no fixed count. What bounds it is gas: the
+ *   simulated cost must fit `sponsor.max-gas-budget` (50M MIST) per close, at most 1 SUI per tx. One
+ *   close simulates at about 19.5M MIST gross on testnet, so 1 SUI holds about 51; `trades` takes 32
+ *   (~1.6x headroom on that measure). A sponsor that refuses on gas (`gas_budget_exceeded`) is met
+ *   with a smaller `BatchCloseOptions.maxTrades`.
+ * - a retired Close All (sponsor `max-retired-closes-per-tx`, default 24, since
+ *   h/sponsor-retired-batch): up to {@link SPONSOR_BATCH_BUDGET.retiredTrades}
+ *   `close_retired_as_delegate` legs, each with its quote, `begin_price`, mint and transfer, and one
+ *   storage push per market (`update_price_feed` once per storage and feed: {@link batchCloseTx}
+ *   drops a sponsored leg's push its market already had), at most
+ *   {@link SPONSOR_BATCH_BUDGET.retiredCommandsPerTrade} commands and
+ *   max({@link SPONSOR_BATCH_BUDGET.inputs}, {@link SPONSOR_BATCH_BUDGET.retiredInputsPerTrade} per
+ *   close) inputs. Its gas ceiling is 0.2 SUI per close, at most 1 SUI: a refusal on gas
+ *   (`gas_budget_exceeded`) is met with a smaller `BatchCloseOptions.maxTrades`, which bounds these
+ *   too. A sponsor before that change takes one retired close per tx (`too_many_trades`,
+ *   `disallowed_command`): `maxTrades: 1` is that shape.
+ * The two never share a tx (`mixed_trades`). Applied on top of {@link CLOSE_BATCH_BUDGET} when
+ * {@link BatchCloseOptions.sponsored}.
+ */
+export declare const SPONSOR_BATCH_BUDGET: {
+    readonly trades: 32;
+    readonly inputs: 64;
+    readonly inputsPerTrade: 7;
+    readonly oneTradeCommands: 8;
+    readonly retiredTrades: 24;
+    readonly retiredCommandsPerTrade: 6;
+    readonly retiredInputsPerTrade: 16;
+};
+/**
+ * Registry sizes the game's once-per-player events scale with, at the contract maxima
+ * (`parchment_base::constants`: `max_game_defs` 128 achievements / quests / cosmetics,
+ * `max_tier_thresholds` 32). There is no unopened-crate cap since the batch-open contract.
+ */
+export declare const GAME_REGISTRY_MAXIMA: {
+    readonly achievements: 128;
+    readonly quests: 128;
+    readonly cosmetics: 128;
+    readonly tierThresholds: 32;
+};
+/** Live (or maximum) registry sizes for {@link playerProgressionEvents}; see {@link gameEventLimitsFromDefinitions}. */
+export type GameEventLimits = {
+    [K in keyof typeof GAME_REGISTRY_MAXIMA]: number;
+};
+/**
+ * Registry sizes from `getGameDefinitions()`. Tier thresholds are not in that response: they stay
+ * at the contract maximum unless given.
+ */
+export declare function gameEventLimitsFromDefinitions(definitions: {
+    achievements: readonly unknown[];
+    quests: readonly unknown[];
+    cosmetics: readonly unknown[];
+}, config?: Partial<Pick<GameEventLimits, "tierThresholds">>): GameEventLimits;
+/**
+ * Most events one player's progression can emit in one tx, whatever the number of their closes
+ * (`game_book::settle` and `apply_xp`; each definition fires once per player): per achievement
+ * RewardMinted + AchievementUnlocked + XpGranted (3), per quest XpGranted + QuestCompleted (2), one
+ * CosmeticUnlocked per cosmetic (each needs an unlock), one TierUp per threshold crossed, and a
+ * CrateGranted after each achievement / quest XP grant plus one for the crate effects an earlier
+ * `open_crates` deferred (applied once, first). Crates accumulate uncapped, so each XP grant can
+ * cross an `xp_per_crate` multiple. Progress counters are not here: one event per `game_book` call,
+ * two per close, so the leg count holds them. Each size is capped at
+ * {@link GAME_REGISTRY_MAXIMA}. At the maxima: 384 + 256 + 128 + 32 + 257 = 1,057, above Sui's
+ * 1,024 on its own (one close that fires every definition there reverts alone): with an unknown
+ * registry no retired close fits, so pass the live sizes ({@link gameEventLimitsFromDefinitions}).
+ */
+export declare function playerProgressionEvents(limits?: GameEventLimits): number;
+/**
+ * The Sui client `Transaction.build` takes, from the app's own `@mysten/sui` (a 2.x
+ * `ClientWithCoreApi`; a 1.x `SuiClient` / experimental core client). Derived from `Transaction`
+ * so it typechecks on both peer versions.
+ */
+export type BatchCloseClient = NonNullable<NonNullable<Parameters<Transaction["build"]>[0]>["client"]>;
+/** A batch's measured use of each {@link SUI_TX_LIMITS} (see {@link closeBatchUsage}). */
+export interface CloseBatchUsage {
+    commands: number;
+    txBytes: number;
+    /** Every event the batch can emit: the legs' plus {@link progressionEvents}. */
+    events: number;
+    /** The game's once-per-account events, included in `events` ({@link playerProgressionEvents}). */
+    progressionEvents: number;
+    newObjectIds: number;
+    argumentsPerCommand: number;
+    /** Transaction inputs (only the sponsor limits them, {@link SPONSOR_BATCH_BUDGET}). */
+    inputs: number;
+    /** Trade calls: one per leg. */
+    trades: number;
+    /** Of those, `close_retired` legs (a sponsored tx takes one alone, {@link SPONSOR_BATCH_BUDGET}). */
+    retired: number;
+}
+/** One position's close inside a batch. */
+export interface BatchCloseLeg {
+    /**
+     * A service-built `request-close` kind with no wallet top-up (its `top_up` is the service's
+     * `0x2::coin::zero`), or a `close-retired` kind.
+     */
+    tx: Transaction;
+    /**
+     * The route and body the kind was built for: `ParchmentBuiltTx.request`. Required under
+     * `BatchCloseOptions.txTrust`, which checks the leg against it before copying it into the batch.
+     */
+    request?: ParchmentTxRequest;
+    /**
+     * Collateral base units to put into this request's `top_up` from the wallet (see
+     * {@link closeBatchTopUps}). 0 / omitted keeps the service's zero coin. Not valid on `close-retired`.
+     */
+    topUp?: bigint;
+}
+export interface BatchCloseOptions {
+    sender: string;
+    /**
+     * Re-checks each leg before it is copied into the batch, as the client's builders do:
+     * every leg needs its `request`, must be a close route for `sender` and must pass
+     * `txIntentViolation`. A later leg whose request named its own signed update is refused when an
+     * earlier leg already quotes that feed with a different one (the batch shares one update per feed,
+     * see below), since replacing it would price that close at a price its request did not name.
+     * The assembled batch is then checked to push and quote only updates the legs themselves carried.
+     * `"unchecked"`: the legs are held only to the command shapes, for a caller that already checked
+     * each kind against its request, or that trusts the API (the default when omitted).
+     */
+    txTrust?: ParchmentTxTrustSetting;
+    /** Collateral coin type `C` (needed only when a leg has a top-up). */
+    coinType?: string;
+    /**
+     * Sui client the wallet coin resolves with (the sender's coins / address balance), so
+     * {@link fitCloseBatch} measures the tx with its real coin inputs. Needed there when a leg has a top-up.
+     */
+    client?: BatchCloseClient;
+    /**
+     * The session key's batch for the gas sponsor: `request_close_as_delegate` legs with no top-up, or
+     * `close_retired_as_delegate` legs with one storage push per market, fit within
+     * {@link SPONSOR_BATCH_BUDGET} as well.
+     */
+    sponsored?: boolean;
+    /**
+     * Sponsored only: the most closes one tx carries (the sponsor's served cap, or a smaller one after
+     * it refused a batch on gas). Defaults to {@link SPONSOR_BATCH_BUDGET.trades}; retired closes are
+     * held to {@link SPONSOR_BATCH_BUDGET.retiredTrades} below it.
+     */
+    maxTrades?: number;
+    /**
+     * Game registry sizes for the retired closes' once-per-player events
+     * ({@link playerProgressionEvents}, counted per distinct account). Defaults to the contract
+     * maxima ({@link GAME_REGISTRY_MAXIMA}: 1,057 events per account, above Sui's 1,024, so no
+     * retired close fits). Pass the live sizes,
+     * `gameEventLimitsFromDefinitions(await parchment.getGameDefinitions())`, to batch more.
+     * A registry that grows between this measure and execution can still exceed the bound.
+     */
+    gameLimits?: GameEventLimits;
+}
+export declare class BatchCloseError extends Error {
+    constructor(message: string);
+}
+/**
+ * Each request's wallet top-up so `request_close` never aborts `EInsufficientFree`: the running
+ * shortfall `fee - free` at that request, free growing by the top-up and shrinking by the fee.
+ * Exactly what `fund_close_fee` accepts while deposits are paused (at most `exec_fee - free`,
+ * `ETopUpExceedsFee` above it, C2C-001); the sum is `max(0, sum(fees) - free)`. Put the requests
+ * before any `close-retired` leg: a retired close credits its payout to free, which would shrink
+ * the later shortfalls below these top-ups. Throws {@link BatchCloseError} on a negative fee.
+ */
+export declare function closeBatchTopUps(execFees: readonly bigint[], free: bigint): bigint[];
+/**
+ * One PTB with every leg's commands, in leg order. Pure inputs, Move targets and object refs are
+ * copied verbatim; objects shared by legs become one input. A leg with a `topUp` has its
+ * `coin::zero` replaced by a part of one `coinWithBalance(sum of top-ups)` coin, split once.
+ * Legs quoting the same oracle feed share the first such leg's signed update (see `appendLeg`).
+ * Throws {@link BatchCloseError} on an empty batch or a leg it can't rebuild. Does not check the
+ * size: {@link fitCloseBatch} does.
+ */
+export declare function batchCloseTx(legs: readonly BatchCloseLeg[], options: BatchCloseOptions): Transaction;
+/**
+ * The longest prefix of `legs` whose batch tx stays within {@link CLOSE_BATCH_BUDGET}, and that tx.
+ * Measured on the built kind ({@link closeBatchUsage}); with top-ups, then again on the tx with its
+ * wallet coin resolved through `options.client` (`coinWithBalance` can pull in one input per coin
+ * the sender holds), and that resolved tx is the one returned. `count < legs.length` means the rest
+ * needs another tx; send it after this one confirms (its top-ups assume this one's ran). Throws
+ * {@link BatchCloseError} when not even one leg fits, or a top-up has no client.
+ */
+export declare function fitCloseBatch(legs: readonly BatchCloseLeg[], options: BatchCloseOptions): Promise<{
+    tx: Transaction;
+    count: number;
+    usage: CloseBatchUsage;
+}>;
+/**
+ * Every batch of `legs`, in order: {@link fitCloseBatch} on what is left until nothing is. For legs
+ * already built at once (their signed updates age: send each batch soon after it is built, or build
+ * per batch from {@link planCloseBatches}). Throws {@link BatchCloseError} when a leg does not fit in a
+ * tx of its own, and when a batch after the first has a wallet top-up: its coin would resolve against
+ * the wallet as it is now, the same coin version the first batch spends, so it could not execute after
+ * that one. Fit such a list one batch at a time instead: {@link fitCloseBatch} the rest (with top-ups
+ * recomputed from the free balance then) only after the previous tx confirms.
+ */
+export declare function splitCloseBatches(legs: readonly BatchCloseLeg[], options: BatchCloseOptions): Promise<{
+    tx: Transaction;
+    start: number;
+    count: number;
+    usage: CloseBatchUsage;
+}[]>;
+/** One position's close as {@link planCloseBatches} sees it, before anything is built. */
+export interface CloseBatchPlanLeg {
+    /** A `close-retired` leg (else a `request-close`). */
+    retired: boolean;
+    /** The account a retired close settles (its once-per-player events count once per account). Unknown: counted as its own. */
+    account?: string;
+    /** A request with a wallet top-up (one more event). */
+    funded?: boolean;
+}
+/**
+ * Groups `legs` into consecutive batches, each one tx, from their kinds alone (no build, no network):
+ * the execution budget ({@link CLOSE_BATCH_BUDGET} events and new ids, the game's progression per
+ * account), commands, and with `sponsored` the sponsor's shapes ({@link SPONSOR_BATCH_BUDGET}:
+ * requests up to `maxTrades`, retired closes up to `min(maxTrades, retiredTrades)` per tx, never
+ * mixed). Put a market's retired closes next to each other: a sponsored batch pushes each market's
+ * update once. Returns each batch's leg indices, every leg
+ * exactly once, in order. Tx bytes are not modeled (they depend on the built kinds): the build's
+ * {@link fitCloseBatch} may carry fewer than a planned batch, and the rest joins the next one. A leg
+ * that fits in no tx (a retired close at registry sizes whose progression alone passes Sui's limit)
+ * throws {@link BatchCloseError}.
+ */
+export declare function planCloseBatches(legs: readonly CloseBatchPlanLeg[], options?: Pick<BatchCloseOptions, "sponsored" | "gameLimits" | "maxTrades">): number[][];
+/**
+ * What the batch of `legs` uses of each {@link SUI_TX_LIMITS}, without network: commands and the
+ * largest argument list from its commands (the `coinWithBalance` intent as the 2 commands it
+ * resolves to at least), the kind's BCS size with a placeholder owned coin in place of the intent,
+ * and the per-leg execution counts. A lower bound with top-ups: {@link fitCloseBatch} remeasures
+ * those on the resolved tx.
+ */
+export declare function closeBatchUsage(legs: readonly BatchCloseLeg[], options: BatchCloseOptions): Promise<CloseBatchUsage>;
+/** A `request_close` leg, the owner's or the session key's (`request_close_as_delegate`). */
+export declare function legIsRequest(source: Transaction): boolean;