@parchment-trade/sdk 0.0.0-stage → 1.0.1

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

@@ -0,0 +1,68 @@
+import type { Transaction, TransactionArgument, TransactionObjectArgument } from "@mysten/sui/transactions";
+/** Max position ids per `trade::force_close_session` call (`trade::EBatchTooLarge` 34 above it). */
+export declare const FORCE_CLOSE_SESSION_MAX_IDS = 128;
+type ObjectInput = string | TransactionObjectArgument;
+export interface ArmSessionCloseCall {
+    /** Latest `parchment_trade` package id (call target). */
+    tradePackageId: string;
+    /** Collateral coin type `C`. */
+    coinType: string;
+    market: ObjectInput;
+    exchange: ObjectInput;
+    config: ObjectInput;
+    /** `oracle::PriceReceipt` from an earlier command in the same PTB; must be a closed receipt for this market. */
+    receipt: TransactionArgument;
+}
+/**
+ * Keeper-only `oracle::arm_session_close<C>(market, exchange, config, receipt, clock)`: the tx sender must be an
+ * order keeper (`oracle::ENotKeeper` 16 otherwise). Arms from a receipt whose signed Lazer market session is
+ * closed (the storage may still be fresh: the crank keeps writing through a closed session), snapshots the
+ * storage price at the signed last-trade time and starts the drain. The gap is measured from the signed last
+ * trade (`oracle::EGapTooShort` 13 until it is older than the force-close minimum gap). Consumes the receipt.
+ * Aborts oracle 10-16 (see `ORACLE_ABORT_NAMES`); runs during every pause and the oracle kill switch.
+ */
+export declare function addArmSessionCloseCall(tx: Transaction, input: ArmSessionCloseCall): void;
+export interface ArmSessionCloseAdminCall extends ArmSessionCloseCall {
+    /** `parchment::authority::AuthorityCap<PACKAGE, ADMIN>`. */
+    adminCap: ObjectInput;
+}
+/** Admin `oracle::arm_session_close_admin<C>(market, exchange, config, cap, receipt, clock)`: same as {@link addArmSessionCloseCall}, authorized by the admin cap. */
+export declare function addArmSessionCloseAdminCall(tx: Transaction, input: ArmSessionCloseAdminCall): void;
+export interface SessionRefundCall {
+    tradePackageId: string;
+    coinType: string;
+    exchange: ObjectInput;
+    market: ObjectInput;
+    account: ObjectInput;
+    config: ObjectInput;
+    /** The pending `order::OrderRequest<C>` object. */
+    order: ObjectInput;
+    /** Closed `oracle::PriceReceipt` frozen at the market's session snapshot tick. */
+    receipt: TransactionArgument;
+}
+/**
+ * Keeper-only `order::session_refund<C>(exchange, market, account, config, order, receipt, clock)`: refunds an order
+ * left pending across an equity session close with outcome 13, without the fill window. Aborts order 0, 2, 3, 21, 22.
+ */
+export declare function addSessionRefundCall(tx: Transaction, input: SessionRefundCall): void;
+export interface ForceCloseSessionCall {
+    tradePackageId: string;
+    coinType: string;
+    exchange: ObjectInput;
+    market: ObjectInput;
+    account: ObjectInput;
+    config: ObjectInput;
+    /** Position ids on `account` (at most {@link FORCE_CLOSE_SESSION_MAX_IDS}); ids not eligible are skipped. */
+    positionIds: ReadonlyArray<string | number | bigint>;
+}
+/**
+ * Permissionless `trade::force_close_session<C>(exchange, market, account, config, position_ids, clock)`: settles the
+ * listed positions at the armed snapshot price. Returns `[lossTicket, coin]`: settle the `LossTicket` with
+ * `fee_mint::mint_on_loss` or `fees::discard_zero_loss` as for a close; `coin` carries any liquidation bounty
+ * (zero otherwise) and must be transferred or merged. Runs during every pause and the oracle kill switch.
+ */
+export declare function addForceCloseSessionCall(tx: Transaction, input: ForceCloseSessionCall): {
+    lossTicket: TransactionArgument;
+    coin: TransactionArgument;
+};
+export {};

package/dist/packages/parchment/sessionClose.js

@@ -0,0 +1,50 @@
+export const FORCE_CLOSE_SESSION_MAX_IDS = 128;
+function obj(tx, o) {
+    return typeof o === "string" ? tx.object(o) : o;
+}
+export function addArmSessionCloseCall(tx, input) {
+    tx.moveCall({
+        target: `${input.tradePackageId}::oracle::arm_session_close`,
+        typeArguments: [input.coinType],
+        arguments: [obj(tx, input.market), obj(tx, input.exchange), obj(tx, input.config), input.receipt, tx.object.clock()],
+    });
+}
+export function addArmSessionCloseAdminCall(tx, input) {
+    tx.moveCall({
+        target: `${input.tradePackageId}::oracle::arm_session_close_admin`,
+        typeArguments: [input.coinType],
+        arguments: [
+            obj(tx, input.market), obj(tx, input.exchange), obj(tx, input.config), obj(tx, input.adminCap), input.receipt, tx.object.clock(),
+        ],
+    });
+}
+export function addSessionRefundCall(tx, input) {
+    tx.moveCall({
+        target: `${input.tradePackageId}::order::session_refund`,
+        typeArguments: [input.coinType],
+        arguments: [
+            obj(tx, input.exchange), obj(tx, input.market), obj(tx, input.account), obj(tx, input.config), obj(tx, input.order),
+            input.receipt, tx.object.clock(),
+        ],
+    });
+}
+export function addForceCloseSessionCall(tx, input) {
+    if (input.positionIds.length === 0)
+        throw new Error("force_close_session: no position ids");
+    if (input.positionIds.length > FORCE_CLOSE_SESSION_MAX_IDS) {
+        throw new Error(`force_close_session: at most ${FORCE_CLOSE_SESSION_MAX_IDS} position ids`);
+    }
+    const [lossTicket, coin] = tx.moveCall({
+        target: `${input.tradePackageId}::trade::force_close_session`,
+        typeArguments: [input.coinType],
+        arguments: [
+            obj(tx, input.exchange),
+            obj(tx, input.market),
+            obj(tx, input.account),
+            obj(tx, input.config),
+            tx.pure.vector("u64", input.positionIds.map((id) => BigInt(id))),
+            tx.object.clock(),
+        ],
+    });
+    return { lossTicket: lossTicket, coin: coin };
+}

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

@@ -0,0 +1,78 @@
+import type { Signer } from "@mysten/sui/cryptography";
+import type { ParchmentDelegate, ParchmentSponsoredTx } from "./parchmentTypes.js";
+/**
+ * Trading session keys. An app keeps an Ed25519 key in the browser, the owner grants it as a delegate on
+ * their Parchment account once (`grant-delegate`, wallet-signed, AccountCap), and afterwards the key signs
+ * the `*-as-delegate` trade transactions itself with the gas sponsored. On chain a delegate can only
+ * request opens / closes, cancel and emergency-close on the account (`order::*_as_delegate`,
+ * `trade::close_retired_as_delegate`); withdraw, deposit and delegate changes all need the AccountCap, so a
+ * leaked session key can trade the account but never move funds out of it. The owner removes it with
+ * `revoke-delegate` (runs under every pause).
+ */
+/** Default session length; callers may choose a longer duration. */
+export declare const SESSION_KEY_TTL_MS: number;
+/** A session is treated as ended this long before its on-chain expiry (a trade then still lands while live). */
+export declare const SESSION_KEY_EXPIRY_MARGIN_MS = 600000;
+/**
+ * A session key. `keypair` is an Ed25519 signer: an in-memory `Ed25519Keypair`, or one whose private key
+ * cannot be read out (e.g. a non-extractable WebCrypto key) that only signs.
+ */
+export interface ParchmentSessionKey {
+    readonly address: string;
+    readonly keypair: Signer;
+}
+/** A fresh random Ed25519 session key. */
+export declare function createSessionKey(): ParchmentSessionKey;
+/** The bech32 `suiprivkey…` secret to persist for {@link sessionKeyFromSecret}; `bad_session_key` for a signer that can't export it. */
+export declare function sessionKeySecret(key: ParchmentSessionKey): string;
+/** A stored session key back from its `suiprivkey…` secret; `bad_session_key` when it is not an Ed25519 secret. */
+export declare function sessionKeyFromSecret(secret: string): ParchmentSessionKey;
+/** The `expiryMs` to grant: `now + ttlMs`. */
+export declare function sessionKeyExpiryMs(nowMs?: number, ttlMs?: number): bigint;
+/**
+ * The account's delegate entry for `address` when it is still live at `nowMs` with `marginMs` to spare, else
+ * null (revoked elsewhere, never granted, or about to expire: `assert_delegate` wants `expiry > now`).
+ */
+export declare function liveSessionDelegate(delegates: readonly ParchmentDelegate[] | undefined, address: string, nowMs?: number, marginMs?: number): ParchmentDelegate | null;
+/**
+ * Throws `bad_session_tx` unless the BCS `TransactionKind` is a programmable transaction that calls a
+ * `*_as_delegate` trade entry and nothing that moves funds or delegates: every command is a Move call or a
+ * `TransferObjects` back to `sender` itself (the service hands the zero coin `mint_on_loss` returns to the
+ * sender), so no `Publish` / `Upgrade`, `SplitCoins`, `MergeCoins` or `MakeMoveVec`; every Move call is one
+ * of the delegate trade entries, `adapter::quote`, `oracle::begin_price` or `tokenomics::mint_on_loss` in one
+ * of `packages` (the Parchment package ids: core, trade, oracle and token, any version), or
+ * `price_feed_storage::update_price_feed` on `lazerIntegrationPackage` only (the configured
+ * integration, not a Parchment package). Run it on every kind before the session key signs.
+ */
+export declare function assertSessionTradeKind(kind: Uint8Array | string, sender: string, packages: Iterable<string>, lazerIntegrationPackage?: string | null): void;
+/**
+ * True when the sponsor's `txBytesBase64` is exactly `kind`, sent by `sender`, with another address paying gas
+ * (and that address is `sponsored.sponsor` when served): `TransactionData::V1` = tag 0, the kind bytes, the sender.
+ */
+export declare function isSponsoredCopyOf(sponsored: Pick<ParchmentSponsoredTx, "txBytesBase64" | "sponsor">, kind: Uint8Array, sender: string): boolean;
+/**
+ * The session key's signature over the sponsor's transaction, after checking it is the sponsored copy of
+ * `kind` from the session address and a trade-only kind calling only `packages` ({@link assertSessionTradeKind}).
+ * Execute with `[signature, sponsored.sponsorSignature]`.
+ */
+export declare function signSessionSponsoredTx(key: ParchmentSessionKey, sponsored: Pick<ParchmentSponsoredTx, "txBytesBase64" | "sponsor">, kind: Uint8Array, packages: Iterable<string>, lazerIntegrationPackage?: string | null): Promise<string>;
+/** The sponsor's `MAX_PROOF_LIFETIME_MS`: a session proof's `expiresAtMs` is at most this far ahead of its clock. */
+export declare const MAX_SPONSOR_PROOF_LIFETIME_MS = 120000;
+/** The lifetime {@link signSponsorProof} gives a proof: half the maximum, so a browser clock up to 60 s off still passes. */
+export declare const SPONSOR_PROOF_LIFETIME_MS = 60000;
+/** The session proof a sponsor request carries: the session key's personal-message signature and its expiry. */
+export interface ParchmentSponsorProof {
+    senderSignature: string;
+    expiresAtMs: bigint;
+}
+/**
+ * The personal message the session key signs for one sponsorship (service `sponsor::proof_message`): five
+ * `\n`-joined lines, no trailing newline. Addresses are `0x` + 64 lowercase hex digits, `txKindSha256` the
+ * lowercase hex SHA-256 of the kind bytes, `expiresAtMs` plain decimal.
+ */
+export declare function sponsorProofMessage(sender: string, accountId: string, kind: Uint8Array, expiresAtMs: bigint): Promise<string>;
+/**
+ * The session key's proof for sponsoring `kind` on `accountId` (the account the kind trades on), valid for
+ * {@link SPONSOR_PROOF_LIFETIME_MS} from `nowMs`. Signed by the session key alone, never the wallet.
+ */
+export declare function signSponsorProof(key: ParchmentSessionKey, accountId: string, kind: Uint8Array, nowMs?: number): Promise<ParchmentSponsorProof>;

package/dist/packages/parchment/sessionKey.js

@@ -0,0 +1,154 @@
+import { bcs } from "@mysten/sui/bcs";
+import { Ed25519Keypair } from "@mysten/sui/keypairs/ed25519";
+import { fromBase64, normalizeSuiAddress, toHex } from "@mysten/sui/utils";
+import { ParchmentApiError } from "../../general/utils/errors.js";
+export const SESSION_KEY_TTL_MS = 2_592_000_000 - 3_600_000;
+export const SESSION_KEY_EXPIRY_MARGIN_MS = 600_000;
+export function createSessionKey() {
+    const keypair = Ed25519Keypair.generate();
+    return { address: normalizeSuiAddress(keypair.toSuiAddress()), keypair };
+}
+export function sessionKeySecret(key) {
+    if (!(key.keypair instanceof Ed25519Keypair))
+        throw new ParchmentApiError(0, "bad_session_key", "Session key can't be exported");
+    return key.keypair.getSecretKey();
+}
+export function sessionKeyFromSecret(secret) {
+    let keypair;
+    try {
+        keypair = Ed25519Keypair.fromSecretKey(secret);
+    }
+    catch {
+        throw new ParchmentApiError(0, "bad_session_key", "Stored session key is not an Ed25519 secret");
+    }
+    return { address: normalizeSuiAddress(keypair.toSuiAddress()), keypair };
+}
+export function sessionKeyExpiryMs(nowMs = Date.now(), ttlMs = SESSION_KEY_TTL_MS) {
+    const ttl = Math.max(0, Math.floor(ttlMs));
+    if (ttl <= 0)
+        throw new ParchmentApiError(0, "bad_amount", "Session length must be positive");
+    return BigInt(Math.floor(nowMs)) + BigInt(ttl);
+}
+export function liveSessionDelegate(delegates, address, nowMs = Date.now(), marginMs = SESSION_KEY_EXPIRY_MARGIN_MS) {
+    const who = normalizeSuiAddress(address);
+    const entry = delegates?.find((d) => normalizeSuiAddress(d.delegate) === who);
+    if (!entry)
+        return null;
+    return entry.expiryMs > BigInt(Math.floor(nowMs + marginMs)) ? entry : null;
+}
+const SESSION_TRADE_CALLS = new Set([
+    "order::request_open_as_delegate",
+    "order::request_close_as_delegate",
+    "order::cancel_as_delegate",
+    "order::emergency_close_as_delegate",
+    "trade::close_retired_as_delegate",
+]);
+const SESSION_CALLS = new Set([...SESSION_TRADE_CALLS, "adapter::quote", "oracle::begin_price", "tokenomics::mint_on_loss"]);
+const UPDATE_PRICE_FEED = "price_feed_storage::update_price_feed";
+function pureAddress(inputs, arg) {
+    const index = arg?.Input;
+    if (typeof index !== "number")
+        return null;
+    const pure = inputs[index]?.Pure;
+    if (!pure)
+        return null;
+    try {
+        return normalizeSuiAddress(bcs.Address.parse(fromBase64(pure.bytes)));
+    }
+    catch {
+        return null;
+    }
+}
+export function assertSessionTradeKind(kind, sender, packages, lazerIntegrationPackage) {
+    const bytes = typeof kind === "string" ? fromBase64(kind.trim()) : kind;
+    let parsed;
+    try {
+        parsed = bcs.TransactionKind.parse(bytes);
+    }
+    catch {
+        throw new ParchmentApiError(0, "bad_session_tx", "Session transaction is not a transaction kind");
+    }
+    const ptb = parsed.ProgrammableTransaction;
+    if (!ptb)
+        throw new ParchmentApiError(0, "bad_session_tx", "Session transaction is not a programmable transaction");
+    const self = normalizeSuiAddress(sender);
+    const allowed = new Set([...packages].map((id) => normalizeSuiAddress(id)));
+    const lazer = lazerIntegrationPackage ? normalizeSuiAddress(lazerIntegrationPackage) : null;
+    let trades = 0;
+    for (const command of ptb.commands) {
+        if (command.TransferObjects) {
+            if (pureAddress(ptb.inputs, command.TransferObjects.address) !== self) {
+                throw new ParchmentApiError(0, "bad_session_tx", "Session transaction transfers to another address");
+            }
+            continue;
+        }
+        const call = command.MoveCall;
+        if (!call)
+            throw new ParchmentApiError(0, "bad_session_tx", `Session key never signs ${command.$kind}`);
+        const target = `${call.module}::${call.function}`;
+        if (target === UPDATE_PRICE_FEED) {
+            const typeArguments = call.typeArguments ?? [];
+            if (!lazer || normalizeSuiAddress(call.package) !== lazer || typeArguments.length !== 0) {
+                throw new ParchmentApiError(0, "bad_session_tx", `Session key never signs ${target} on package ${call.package}`);
+            }
+            continue;
+        }
+        if (!SESSION_CALLS.has(target)) {
+            throw new ParchmentApiError(0, "bad_session_tx", `Session key never signs ${target}`);
+        }
+        if (!allowed.has(normalizeSuiAddress(call.package))) {
+            throw new ParchmentApiError(0, "bad_session_tx", `Session key never signs a call to package ${call.package}`);
+        }
+        if (SESSION_TRADE_CALLS.has(target))
+            trades++;
+    }
+    if (trades === 0)
+        throw new ParchmentApiError(0, "bad_session_tx", "Session transaction has no delegate trade call");
+}
+function sameBytes(a, b) {
+    return a.length === b.length && a.every((x, i) => x === b[i]);
+}
+export function isSponsoredCopyOf(sponsored, kind, sender) {
+    try {
+        const bytes = fromBase64(sponsored.txBytesBase64);
+        if (bytes[0] !== 0 || !sameBytes(bytes.subarray(1, 1 + kind.length), kind))
+            return false;
+        const v1 = bcs.TransactionData.parse(bytes).V1;
+        if (!v1)
+            return false;
+        const owner = normalizeSuiAddress(v1.gasData.owner);
+        const from = normalizeSuiAddress(sender);
+        if (normalizeSuiAddress(v1.sender) !== from || owner === from)
+            return false;
+        return typeof sponsored.sponsor !== "string" || !sponsored.sponsor || owner === normalizeSuiAddress(sponsored.sponsor);
+    }
+    catch {
+        return false;
+    }
+}
+export async function signSessionSponsoredTx(key, sponsored, kind, packages, lazerIntegrationPackage) {
+    assertSessionTradeKind(kind, key.address, packages, lazerIntegrationPackage);
+    if (!isSponsoredCopyOf(sponsored, kind, key.address)) {
+        throw new ParchmentApiError(0, "bad_tx", "Sponsored transaction is not the session's trade");
+    }
+    const { signature } = await key.keypair.signTransaction(fromBase64(sponsored.txBytesBase64));
+    return signature;
+}
+export const MAX_SPONSOR_PROOF_LIFETIME_MS = 120_000;
+export const SPONSOR_PROOF_LIFETIME_MS = 60_000;
+export async function sponsorProofMessage(sender, accountId, kind, expiresAtMs) {
+    const kindSha256 = toHex(new Uint8Array(await crypto.subtle.digest("SHA-256", new Uint8Array(kind))));
+    return [
+        "Parchment session-key sponsorship v1",
+        `sender: ${normalizeSuiAddress(sender)}`,
+        `accountId: ${normalizeSuiAddress(accountId)}`,
+        `txKindSha256: ${kindSha256}`,
+        `expiresAtMs: ${expiresAtMs}`,
+    ].join("\n");
+}
+export async function signSponsorProof(key, accountId, kind, nowMs = Date.now()) {
+    const expiresAtMs = BigInt(Math.floor(nowMs) + SPONSOR_PROOF_LIFETIME_MS);
+    const message = await sponsorProofMessage(key.address, accountId, kind, expiresAtMs);
+    const { signature } = await key.keypair.signPersonalMessage(new TextEncoder().encode(message));
+    return { senderSignature: signature, expiresAtMs };
+}

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

@@ -0,0 +1,23 @@
+export type SlippageSide = "long" | "short";
+export type SlippageAction = "open" | "close";
+/**
+ * Worst acceptable fill price (WAD) for a given side, action, mid/quote price and slippage.
+ *
+ * - long open / short close: upper bound `price * (1 + slip)`, rounded down (fill must be <= bound)
+ * - short open / long close: lower bound `price * (1 - slip)`, rounded up (fill must be >= bound);
+ *   an open's bound is at least 1 (the deployed service still refuses a 0 open bound; 0 means "no bound")
+ *
+ * Both round to the tight side, so a bound never allows more than `slippageBps`.
+ *
+ * Pass the result as `acceptablePriceWad` on order requests. On chain it is stored and emitted only;
+ * two-step fills and emergency close take no price bound, so it is a record of intent, not protection.
+ * Throws `invalid_amount` for a negative `priceWad` or a `slippageBps` that is not a non-negative integer
+ * (a negative slip would give a bound on the wrong side of the price, or a negative bound), and
+ * `bad_request` for a `slippageBps` above 10000 (100%), like the service preview's `slippageBps` (0..=10000).
+ */
+export declare function boundFromSlippage(input: {
+    side: SlippageSide;
+    action: SlippageAction;
+    priceWad: bigint;
+    slippageBps: bigint | number;
+}): bigint;

package/dist/packages/parchment/slippage.js

@@ -0,0 +1,27 @@
+import { ParchmentApiError } from "../../general/utils/errors.js";
+const BPS = 10000n;
+export function boundFromSlippage(input) {
+    const price = input.priceWad;
+    const raw = input.slippageBps;
+    if (typeof price !== "bigint" || price < 0n) {
+        throw new ParchmentApiError(0, "invalid_amount", "priceWad must be a non-negative bigint");
+    }
+    if (!(typeof raw === "bigint" || (typeof raw === "number" && Number.isSafeInteger(raw))) || raw < 0) {
+        throw new ParchmentApiError(0, "invalid_amount", "slippageBps must be a non-negative integer");
+    }
+    if ((input.side !== "long" && input.side !== "short") || (input.action !== "open" && input.action !== "close")) {
+        throw new ParchmentApiError(0, "invalid_amount", "side must be long or short and action must be open or close");
+    }
+    const slip = BigInt(raw);
+    if (slip > BPS) {
+        throw new ParchmentApiError(0, "bad_request", "slippageBps must be at most 10000 (100%)");
+    }
+    const ceiling = (input.side === "long" && input.action === "open")
+        || (input.side === "short" && input.action === "close");
+    if (ceiling) {
+        const upper = (price * (BPS + slip)) / BPS;
+        return input.action === "open" && upper === 0n ? 1n : upper;
+    }
+    const floor = slip === BPS ? 0n : (price * (BPS - slip) + (BPS - 1n)) / BPS;
+    return input.action === "open" && floor === 0n ? 1n : floor;
+}

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

@@ -0,0 +1,39 @@
+import type { ApiParchmentSponsorBody } from "./parchmentTypes.js";
+/**
+ * Gas sponsorship for trading session keys. The sponsor pays only for
+ * `*-as-delegate` trade kinds whose sender is a live delegate of the target account (see `sessionKey.ts`); owner
+ * (`AccountCap`) transactions are never sponsored. Limits are per account, shared by all of its session keys.
+ */
+/** 403: the sender is not a live delegate of the account (never granted, expired or revoked). Drop the session key. */
+export declare const SPONSOR_NOT_DELEGATE = "not_delegate";
+/** 429: the account already holds its unresolved sponsorship(s) until the sponsor sees that tx land (or 120 s). */
+export declare const SPONSOR_IN_FLIGHT_LIMIT = "in_flight_limit";
+/** True when a sponsor refusal means the session key is no longer a delegate: forget it and offer to enable again. */
+export declare function isSessionKeyRevoked(error: unknown): boolean;
+/**
+ * Whether a failed {@link Parchment.sponsorTransaction} should fall back to the wallet path (the owner's
+ * `AccountCap` transaction, user-paid gas): true when nothing is wrong with the kind itself.
+ *
+ * - true: 403 `not_delegate` (the session is gone), 401 `session_proof_expired` and 400 `bad_session_proof_expiry`
+ *   (the browser clock is too far off the service's), every 429 (the account's in-flight, rate or failure limits,
+ *   or an edge rate limit), 400 `gas_budget_exceeded`, 502 / 503 / 504 (`sponsor_unavailable`: disabled, out
+ *   of budget, node or signer down) and the SDK's own `network` / `timeout`.
+ * - false: every other 400 (`paused`, `simulation_failed`: the trade would fail anyway; `disallowed_*`,
+ *   `mixed_*`, `bad_account`, ...: a kind the sponsor never pays for), 413, any other status, the SDK's local
+ *   refusals (`bad_request`, `bad_tx`, `bad_tx_kind`) and anything that is not a `ParchmentApiError`.
+ *
+ * Safe to fall back after any of these: the session key signs only the sponsor's bytes, so a refused sponsorship
+ * left nothing signed, and the wallet path is a different (owner) transaction.
+ */
+export declare function shouldPayOwnGas(error: unknown): boolean;
+/**
+ * the legacy API's check: a missing or non-string kind is `bad_request`; the kind is trimmed (as the service does)
+ * and an empty or non-base64 one is the service's `bad_tx_kind`. The service decodes and validates it.
+ */
+export declare function sponsorKind(value: unknown): string;
+/**
+ * The `POST /api/parchment/sponsor` wire body: `{ sender, txKindBase64, senderSignature, expiresAtMs }`,
+ * `expiresAtMs` as a js_bigint literal. A missing sender, signature or expiry is `bad_request`, a bad kind
+ * `bad_tx_kind` ({@link sponsorKind}).
+ */
+export declare function sponsorBody(input: ApiParchmentSponsorBody): Record<string, string>;

package/dist/packages/parchment/sponsor.js

@@ -0,0 +1,48 @@
+import { normalizeAddress } from "../../general/utils/address.js";
+import { ParchmentApiError } from "../../general/utils/errors.js";
+import { toJsBigInt } from "../../general/utils/jsBigInt.js";
+export const SPONSOR_NOT_DELEGATE = "not_delegate";
+export const SPONSOR_IN_FLIGHT_LIMIT = "in_flight_limit";
+export function isSessionKeyRevoked(error) {
+    return error instanceof ParchmentApiError && error.status === 403 && error.code === SPONSOR_NOT_DELEGATE;
+}
+export function shouldPayOwnGas(error) {
+    if (!(error instanceof ParchmentApiError))
+        return false;
+    if (error.status === 0)
+        return error.code === "network" || error.code === "timeout";
+    if (error.status === 400)
+        return error.code === "gas_budget_exceeded" || error.code === "bad_session_proof_expiry";
+    if (error.status === 401)
+        return error.code === "session_proof_expired";
+    if (error.status === 403)
+        return error.code === SPONSOR_NOT_DELEGATE;
+    return error.status === 429 || error.status === 502 || error.status === 503 || error.status === 504;
+}
+export function sponsorKind(value) {
+    if (typeof value !== "string") {
+        throw new ParchmentApiError(0, "bad_request", "txKindBase64 is required");
+    }
+    const kind = value.trim();
+    if (kind.length === 0 || !/^[A-Za-z0-9+/=]+$/.test(kind)) {
+        throw new ParchmentApiError(0, "bad_tx_kind", "txKindBase64 must be base64 transaction-kind bytes");
+    }
+    return kind;
+}
+export function sponsorBody(input) {
+    if (typeof input?.walletAddress !== "string") {
+        throw new ParchmentApiError(0, "bad_request", "walletAddress is required");
+    }
+    if (typeof input.senderSignature !== "string" || input.senderSignature.length === 0) {
+        throw new ParchmentApiError(0, "bad_request", "senderSignature is required");
+    }
+    if (typeof input.expiresAtMs !== "bigint" || input.expiresAtMs <= 0n) {
+        throw new ParchmentApiError(0, "bad_request", "expiresAtMs is required");
+    }
+    return {
+        sender: normalizeAddress(input.walletAddress),
+        txKindBase64: sponsorKind(input.txKindBase64),
+        senderSignature: input.senderSignature,
+        expiresAtMs: toJsBigInt(input.expiresAtMs),
+    };
+}

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

@@ -0,0 +1,33 @@
+import type { Transaction, TransactionObjectArgument } from "@mysten/sui/transactions";
+type ObjectInput = string | TransactionObjectArgument;
+/**
+ * Direct `parchment_token::staking` locked-yield calls. `packageId` is the token package of
+ * that has `sync_locked`. `clock` defaults to `0x6`.
+ */
+export interface SyncLockedCall {
+    packageId: string;
+    coinType: string;
+    pool: ObjectInput;
+    exchange: ObjectInput;
+    owner: string;
+    clock?: ObjectInput;
+}
+/**
+ * `staking::sync_locked(pool, exchange, owner, clock)`: banks the yield `owner`'s locked weight
+ * earned and reweighs it from their mint ledger. Permissionless; pays nobody. Append it after any
+ * call that changes the owner's ledger (release, exit, credit, void).
+ */
+export declare function addSyncLockedCall(tx: Transaction, input: SyncLockedCall): void;
+/** {@link addSyncLockedCall} for each distinct owner, in first-seen order. Returns the owners synced. */
+export declare function addSyncLockedCalls(tx: Transaction, input: Omit<SyncLockedCall, "owner"> & {
+    owners: readonly string[];
+}): string[];
+/**
+ * ADMIN `staking::forfeit_locked_yield(pool, exchange, config, cap, owner, clock)`: syncs `owner`, then
+ * returns all their unpaid locked yield to the reward stream. Append it after `locked_mint::admin_void`.
+ */
+export declare function addForfeitLockedYieldCall(tx: Transaction, input: SyncLockedCall & {
+    config: ObjectInput;
+    cap: ObjectInput;
+}): void;
+export {};

package/dist/packages/parchment/stakingCalls.js

@@ -0,0 +1,21 @@
+import { normalizeSuiAddress } from "@mysten/sui/utils";
+const object = (tx, value) => typeof value === "string" ? tx.object(value) : value;
+export function addSyncLockedCall(tx, input) {
+    tx.moveCall({
+        target: `${input.packageId}::staking::sync_locked`, typeArguments: [input.coinType],
+        arguments: [object(tx, input.pool), object(tx, input.exchange), tx.pure.address(input.owner), object(tx, input.clock ?? "0x6")],
+    });
+}
+export function addSyncLockedCalls(tx, input) {
+    const owners = [...new Set(input.owners.map((o) => normalizeSuiAddress(o)))];
+    for (const owner of owners)
+        addSyncLockedCall(tx, { ...input, owner });
+    return owners;
+}
+export function addForfeitLockedYieldCall(tx, input) {
+    tx.moveCall({
+        target: `${input.packageId}::staking::forfeit_locked_yield`, typeArguments: [input.coinType],
+        arguments: [object(tx, input.pool), object(tx, input.exchange), object(tx, input.config), object(tx, input.cap),
+            tx.pure.address(input.owner), object(tx, input.clock ?? "0x6")],
+    });
+}

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

@@ -0,0 +1,53 @@
+/** BCS for `events::Event<StakingDurationCapsUpdatedEventV1>`. */
+export declare const STAKING_DURATION_CAPS_UPDATED_EVENT_BCS: import("@mysten/sui/bcs").BcsStruct<{
+    pool_id: import("@mysten/sui/bcs").BcsType<string, string | Uint8Array<ArrayBufferLike>, "bytes[32]">;
+    max_reward_stream_ms: import("@mysten/sui/bcs").BcsType<string, string | number | bigint, "u64">;
+    max_min_stake_lock_ms: import("@mysten/sui/bcs").BcsType<string, string | number | bigint, "u64">;
+}, string>;
+export type StakingDurationCapsUpdatedEventV1 = ReturnType<typeof STAKING_DURATION_CAPS_UPDATED_EVENT_BCS.parse>;
+/** Decode event bytes supplied by the API. */
+export declare function decodeStakingDurationCapsUpdatedEvent(bytes: Uint8Array): StakingDurationCapsUpdatedEventV1 | null;
+/**
+ * BCS for `events::Event<LockedWeightSyncedEventV1>`: `staking::sync_locked` set `owner`'s
+ * locked weight from `balance` (finalized locked and vesting PARCHMENT). `moved` is the yield the
+ * old weight earned, banked into `owed`; `total_weight` is stake plus locked weight after it.
+ */
+export declare const LOCKED_WEIGHT_SYNCED_EVENT_BCS: import("@mysten/sui/bcs").BcsStruct<{
+    pool_id: import("@mysten/sui/bcs").BcsType<string, string | Uint8Array<ArrayBufferLike>, "bytes[32]">;
+    owner: import("@mysten/sui/bcs").BcsType<string, string | Uint8Array<ArrayBufferLike>, "bytes[32]">;
+    balance: import("@mysten/sui/bcs").BcsType<string, string | number | bigint, "u64">;
+    weight: import("@mysten/sui/bcs").BcsType<string, string | number | bigint, "u64">;
+    total_weight: import("@mysten/sui/bcs").BcsType<string, string | number | bigint, "u64">;
+    moved: import("@mysten/sui/bcs").BcsType<string, string | number | bigint, "u64">;
+    owed: import("@mysten/sui/bcs").BcsType<string, string | number | bigint, "u64">;
+}, string>;
+/**
+ * `Event<LockedYieldClaimedEventV1>`: on a claim, stake or unstake whenever the owner's owed balance
+ * changed. `amount` paid (0 when the reward balance paid none), `owed` still unpaid after it.
+ */
+export declare const LOCKED_YIELD_CLAIMED_EVENT_BCS: import("@mysten/sui/bcs").BcsStruct<{
+    pool_id: import("@mysten/sui/bcs").BcsType<string, string | Uint8Array<ArrayBufferLike>, "bytes[32]">;
+    owner: import("@mysten/sui/bcs").BcsType<string, string | Uint8Array<ArrayBufferLike>, "bytes[32]">;
+    amount: import("@mysten/sui/bcs").BcsType<string, string | number | bigint, "u64">;
+    owed: import("@mysten/sui/bcs").BcsType<string, string | number | bigint, "u64">;
+}, string>;
+/** `Event<LockedYieldForfeitedEventV1>`: ADMIN returned `owner`'s unpaid locked yield to the stream. */
+export declare const LOCKED_YIELD_FORFEITED_EVENT_BCS: import("@mysten/sui/bcs").BcsStruct<{
+    pool_id: import("@mysten/sui/bcs").BcsType<string, string | Uint8Array<ArrayBufferLike>, "bytes[32]">;
+    owner: import("@mysten/sui/bcs").BcsType<string, string | Uint8Array<ArrayBufferLike>, "bytes[32]">;
+    amount: import("@mysten/sui/bcs").BcsType<string, string | number | bigint, "u64">;
+    stream_end_ms: import("@mysten/sui/bcs").BcsType<string, string | number | bigint, "u64">;
+}, string>;
+/** `Event<LockedWeightBpsUpdatedEventV1>`: the multiplier later syncs use (bps). */
+export declare const LOCKED_WEIGHT_BPS_UPDATED_EVENT_BCS: import("@mysten/sui/bcs").BcsStruct<{
+    pool_id: import("@mysten/sui/bcs").BcsType<string, string | Uint8Array<ArrayBufferLike>, "bytes[32]">;
+    bps: import("@mysten/sui/bcs").BcsType<string, string | number | bigint, "u64">;
+}, string>;
+export type LockedWeightSyncedEventV1 = ReturnType<typeof LOCKED_WEIGHT_SYNCED_EVENT_BCS.parse>;
+export type LockedYieldClaimedEventV1 = ReturnType<typeof LOCKED_YIELD_CLAIMED_EVENT_BCS.parse>;
+export type LockedYieldForfeitedEventV1 = ReturnType<typeof LOCKED_YIELD_FORFEITED_EVENT_BCS.parse>;
+export type LockedWeightBpsUpdatedEventV1 = ReturnType<typeof LOCKED_WEIGHT_BPS_UPDATED_EVENT_BCS.parse>;
+export declare function decodeLockedWeightSyncedEvent(bytes: Uint8Array): LockedWeightSyncedEventV1 | null;
+export declare function decodeLockedYieldClaimedEvent(bytes: Uint8Array): LockedYieldClaimedEventV1 | null;
+export declare function decodeLockedYieldForfeitedEvent(bytes: Uint8Array): LockedYieldForfeitedEventV1 | null;
+export declare function decodeLockedWeightBpsUpdatedEvent(bytes: Uint8Array): LockedWeightBpsUpdatedEventV1 | null;