@parchment-trade/sdk 0.0.0-stage → 1.0.0

package/dist/packages/parchment/parchmentTypes.js

@@ -0,0 +1,65 @@
+export const TX_ACTIONS = [
+    "open-account",
+    "deposit",
+    "withdraw",
+    "request-open",
+    "request-open-as-delegate",
+    "request-close",
+    "request-close-as-delegate",
+    "cancel-order",
+    "cancel-order-as-delegate",
+    "expire-order",
+    "emergency-close",
+    "emergency-close-as-delegate",
+    "close-retired",
+    "close-retired-as-delegate",
+    "liquidate",
+    "liquidate-retired",
+    "sweep",
+    "sweep-surplus",
+    "claim-pending-mint",
+    "harvest",
+    "bind-referrer",
+    "bind-trading-referrer",
+    "transfer-account",
+    "stake",
+    "unstake",
+    "claim",
+    "grant-delegate",
+    "revoke-delegate",
+    "register-builder",
+    "set-builder-payout",
+    "create-builder",
+    "set-builder-fee",
+    "pause-builder",
+    "resume-builder",
+    "transfer-builder",
+    "approve-builder",
+    "revoke-builder-approval",
+    "set-builder-create-fee",
+    "install-treasury",
+    "auth-register",
+    "game-attach",
+    "claim-daily",
+    "open-crate",
+    "open-crates",
+    "claim-quest",
+    "collect-mint",
+    "release-unlocked",
+    "exit-early",
+    "exit-early-bounded",
+    "grant-close-delegate",
+    "grant-session-and-trigger",
+    "revoke-session-and-trigger",
+];
+export const PARCHMENT_CANDLES_BATCH_MAX_MARKETS = 12;
+export const LEADERBOARD_PERIODS = ["daily", "weekly", "all", "season"];
+export const LEADERBOARD_METRICS = ["pnl", "pnlPct", "volume", "winStreak", "xp"];
+export const LOCKED_LEDGER_STATUSES = ["current", "rebuilding", "failed"];
+export const PARCHMENT_SPONSORED_ACTIONS = [
+    "request-open-as-delegate",
+    "request-close-as-delegate",
+    "cancel-order-as-delegate",
+    "emergency-close-as-delegate",
+    "close-retired-as-delegate",
+];

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

@@ -0,0 +1,45 @@
+import type { IntPaths } from "../../general/utils/jsBigInt.js";
+export declare const PUBLIC_INTS: {
+    readonly config: readonly ["pins[].sourceId", "pins[].lazerFeedId", ...string[]];
+    readonly markets: string[];
+    readonly market: string[];
+    readonly marketStats: readonly ["sinceMs", "untilMs", ...string[]];
+    readonly priceHistory: readonly ["points[].timestampMs", "points[].priceWad", "points[].twapWad"];
+    readonly livePrice: readonly ["priceWad", "timestampMs:u64"];
+    readonly trade: readonly ["id:i64", "positionId:u64", "notional:u64", "margin:u64", "pnl:i128", "timestampMs:i64"];
+    readonly candles: string[];
+    readonly candlesBatch: readonly ["serverTimeMs", ...string[]];
+    readonly prices: readonly string[];
+    readonly account: readonly [...string[], "queue.aheadCount", "queue.aheadNet"];
+    readonly positions: string[];
+    readonly position: string[];
+    readonly equityHistory: readonly ["bucketMs", "fromMs:i64", "toMs:i64", ...string[]];
+    readonly history: readonly ["items[].id", "items[].positionId", "items[].timestampMs", "items[].triggerPriceWad", ...string[]];
+    readonly trigger: IntPaths;
+    readonly triggers: string[];
+    readonly orders: string[];
+    readonly order: string[];
+    readonly tradingReferral: readonly ["refereeCount", "totalEarned", "pending"];
+    readonly accountQueue: readonly ["net", "rank", ...string[], "queueLength", "totalOwed", "lpCash"];
+    readonly previewOpen: readonly ["fillWad", "suggestedBoundWad", "margin", "fee", "locked", "notional", "winningExposure", "factorBps", "entryWad", "oneStepWad", "oneStepSpreadBps", "bustWad", "confWad", "takerFeeBps", "minPayoutFactorBps", "suggestedAcceptablePriceWad", "maxFeeBps", "execFee", "fillWindowMs", "signedWindowMs", "cancelDelayMs"];
+    readonly previewClose: readonly ["positionId", ...string[], "exitWad", "fillWad", "suggestedBoundWad", "oneStepWad", "oneStepSpreadBps", "confWad", "suggestedAcceptablePriceWad", "maxFeeBps", "execFee", "fillWindowMs", "signedWindowMs", "cancelDelayMs", "emergencyAfterMs", "feeOwed"];
+    readonly builder: IntPaths;
+    readonly builders: string[];
+    readonly builderApprovals: string[];
+    readonly builderAllowance: readonly ["created", "limit", "remaining"];
+    readonly referrals: readonly ["asReferee.boundAtMs", ...string[]];
+    readonly stakingPool: readonly ["totalStaked", "streamRemaining", "streamLastMs", "streamEndMs", "streamVestedNow", "rewardStreamMs", "minStakeLockMs", "rewards", "referralReserve", "nowMs", "parchDripRemaining", "parchDripNow", "parchDripLastMs", "parchDripEndMs", "totalWeight", "lockedWeight", "lockedWeightBps", "lockedOwedTotal"];
+    readonly staker: readonly ["staked", "stakedAtMs", "unlockAtMs", "pendingReward", "parchPending", "nowMs", "lockedWeight", "lockedSyncedBalance", "lockedPending", "lockedOwed", "totalWeight"];
+    readonly sponsored: readonly ["gasBudget", "gasPrice", "estimatedGas", "validEpoch"];
+    readonly queue: readonly ["length", "totalOwed", "lpCash", "instantlyPayable", "owedToLpCashBps"];
+    readonly lp: readonly string[];
+    readonly lpQueue: readonly ["queueLength", "totalOwed", "lpCash", ...string[]];
+    readonly protocol: readonly ["openPositions", "openNotional", "volumeNotional", "equity", "lpCash", "queueLength"];
+    readonly gameDefinitions: readonly [...string[], "cosmetics[].id", "achievementMintFractionBps"];
+    readonly game: readonly ["xp", "seasonXp", "seasonId", "tier", "streak", "winStreak", "crates", "trades", "achievements[]", "questsDone[]", "cosmetics[]", "minted", "mintedToday", "pendingMint", "lastDailyDay", "feeCredit", "feeCreditUsed", "achievementMintFractionBps", ...string[], "lockedBalance", "lockWindowBalance", "nextUnlockMs", "vestingBalance", "releasableNow", "earlyExitPaidNow", "earlyExitPenaltyNow", "earlyExitUnlocks[]"];
+    readonly leaderboard: readonly [...string[], "nextCursor"];
+    readonly feed: string[];
+    readonly pnlCard: readonly ["positionId", "pnl:i128", "pnlPct:i128"];
+    readonly recentPositions: string[];
+    readonly none: readonly [];
+};

package/dist/packages/parchment/publicInts.js

@@ -0,0 +1,383 @@
+const under = (prefix, paths) => paths.map((p) => `${prefix}.${p}`);
+const PRICE = ["priceWad", "twapWad", "timestampMs", "spreadWad", "ageMs:i64", "maxAgeMs", "confWad"];
+const MARKET = [
+    "kind",
+    "status",
+    "takerFeeBps",
+    "winFeeBps",
+    "oracle.sourceId",
+    "oracle.lazerFeedId",
+    "oracle.maxAgeMs",
+    "oracle.maxConfAgeMs",
+    "oracle.maxFutureMs",
+    "oracle.maxTwapDevBps",
+    "oracle.minSpreadBps",
+    "risk.*",
+    "impact.*",
+    "timing.*",
+    "longOi",
+    "shortOi",
+    "longLockedExposure",
+    "shortLockedExposure",
+    "lastOracleTsMs",
+    "lastOracleSequence",
+    "lastOracleSlot",
+    "maxLongOi",
+    "maxShortOi",
+    "maxLongExposure",
+    "maxShortExposure",
+    "oneStepSpreadBps",
+    "cancelDelayMs",
+    "sessionEndsAtMs",
+    "nextSessionOpenMs",
+    ...under("price", PRICE),
+];
+const POSITION = [
+    "positionId",
+    "midWad",
+    "confWad",
+    "entryWad",
+    "bustWad",
+    "margin",
+    "notional",
+    "leverage",
+    "factorBps",
+    "winningExposure",
+    "winFeeBps",
+    "deadbandPpm",
+    "closeFeePpm",
+    "openedAtMs",
+    "autoCloseAtMs",
+    "takeProfitWad",
+    "stopLossWad",
+    "fillBustWad",
+];
+const CANDLE = ["timeMs", "openWad", "highWad", "lowWad", "closeWad"];
+const TRIGGER = ["positionId", "takeProfitWad", "stopLossWad", "stopLossDropped.ms", "stopLossDropped.wad"];
+const ACCOUNT = [
+    "free",
+    "openNotional",
+    "pendingMintBasis",
+    "pendingMint",
+    "delegates[].expiryMs",
+    "delegatesCount",
+    "pendingOrders",
+    "pendingOpenOrders",
+    "nonce",
+];
+const CLAIM = ["claimId", "positionId", "net", "timestampMs", "remaining", "feeRemaining", "onTopRemaining"];
+const BUILDER = ["id:u32", "feeBps:u16", "pending:u64", "totalEarned:u64"];
+const ORDER = [
+    "margin",
+    "leverage",
+    "positionId",
+    "acceptablePriceWad",
+    "minFactorBps",
+    "maxFeeBps",
+    "execFee",
+    "requestedMs",
+    "fillDeadlineMs",
+    "cancelAfterMs",
+    "emergencyAfterMs",
+    "feeOwed",
+    "fillPriceWad",
+    "fillPriceTsMs",
+    "fillLatencyMs:i64",
+    "refund",
+    "execFeeRefunded",
+    "finalizedMs",
+];
+const HISTORY_PAYLOAD = [
+    "amount",
+    "builderId",
+    "builderAmount",
+    "positionId",
+    "midWad",
+    "confWad",
+    "entryWad",
+    "bustWad",
+    "margin",
+    "notional",
+    "factorBps",
+    "winningExposure",
+    "winFeeBps",
+    "deadbandPpm",
+    "closeFeePpm",
+    "gross",
+    "haircut",
+    "fee",
+    "net",
+    "bounty",
+    "toLp",
+    "exitWad",
+];
+const LEADERBOARD_ROW = [
+    "rank",
+    "value:i128",
+    ...under("stats", ["trades", "closes", "wins", "volume", "pnl:i128", "winRateBps", "xp", "tier", "winStreak"]),
+];
+export const PUBLIC_INTS = {
+    config: [
+        "pins[].sourceId",
+        "pins[].lazerFeedId",
+        ...under("gameRewards", [
+            "decimals",
+            "walletMintCapPerDay",
+            "globalMintCapPerDay",
+            "winMint",
+            "achievementMintFractionBps",
+            "dailyDrop.base",
+            "dailyDrop.step",
+            "dailyDrop.max",
+            "dailyDrop.streakCap",
+        ]),
+        "maxPendingOrders",
+        "pauseMask",
+        "trim.maxShareBps",
+        "trim.cPpm",
+        "refereeDiscountBps",
+        ...under("builders", ["ownerFeeLimitBps:u16", "maxFeeBps:u16", "hardCapBps:u16", "createFee:u64"]),
+    ],
+    markets: under("markets[]", MARKET),
+    market: under("market", MARKET),
+    marketStats: [
+        "sinceMs",
+        "untilMs",
+        ...under("markets[]", [
+            "volume24h",
+            "openedNotional24h",
+            "closedNotional24h",
+            "opens24h",
+            "closes24h",
+            "openInterestLong",
+            "openInterestShort",
+            "price24hAgoWad",
+            "price24hAgoTsMs",
+        ]),
+    ],
+    priceHistory: ["points[].timestampMs", "points[].priceWad", "points[].twapWad"],
+    livePrice: ["priceWad", "timestampMs:u64"],
+    trade: ["id:i64", "positionId:u64", "notional:u64", "margin:u64", "pnl:i128", "timestampMs:i64"],
+    candles: under("candles[]", CANDLE),
+    candlesBatch: ["serverTimeMs", ...under("series[].candles[]", CANDLE)],
+    prices: [
+        ...under("markets[]", PRICE),
+        ...under("pins[]", ["sourceId:u64", "lazerFeedId:u32", "ageMs:i64", "priceWad", "twapWad", "timestampMs"]),
+    ],
+    account: [
+        ...under("accounts[]", ACCOUNT),
+        "nextAccountNonce",
+        ...under("positions[]", POSITION),
+        ...under("queue.claims[]", CLAIM),
+        "queue.aheadCount",
+        "queue.aheadNet",
+    ],
+    positions: under("positions[]", POSITION),
+    position: under("position", POSITION),
+    equityHistory: [
+        "bucketMs",
+        "fromMs:i64",
+        "toMs:i64",
+        ...under("points[]", ["tsMs:i64", "equity", "free", "margin", "unrealizedPnl:i128", "openPositions", "unpricedPositions"]),
+        ...under("current", ["tsMs:i64", "equity", "free", "margin", "unrealizedPnl:i128", "openPositions", "unpricedPositions"]),
+    ],
+    history: ["items[].id", "items[].positionId", "items[].timestampMs", "items[].triggerPriceWad", ...under("items[].payload", HISTORY_PAYLOAD)],
+    trigger: TRIGGER,
+    triggers: under("triggers[]", TRIGGER),
+    orders: under("orders[]", ORDER),
+    order: under("order", ORDER),
+    tradingReferral: ["refereeCount", "totalEarned", "pending"],
+    accountQueue: [
+        "net",
+        "rank",
+        ...under("claims[]", ["claimId", "position", "owed", "owedAhead"]),
+        "queueLength",
+        "totalOwed",
+        "lpCash",
+    ],
+    previewOpen: [
+        "fillWad",
+        "suggestedBoundWad",
+        "margin",
+        "fee",
+        "locked",
+        "notional",
+        "winningExposure",
+        "factorBps",
+        "entryWad",
+        "oneStepWad",
+        "oneStepSpreadBps",
+        "bustWad",
+        "confWad",
+        "takerFeeBps",
+        "minPayoutFactorBps",
+        "suggestedAcceptablePriceWad",
+        "maxFeeBps",
+        "execFee",
+        "fillWindowMs",
+        "signedWindowMs",
+        "cancelDelayMs",
+    ],
+    previewClose: [
+        "positionId",
+        ...under("pnl", [
+            "loss",
+            "raw",
+            "trimmed",
+            "adjusted",
+            "winFee",
+            "closeToll",
+            "net",
+            "closeTollFromProfit",
+            "closeTollFromMargin",
+            "userProfit",
+            "marginReturned",
+            "payout",
+            "payoutBeforeRefund",
+            "refereeRefund",
+            "feesCollectedNow",
+            "builderFee",
+            "builderFeeBps:u16",
+            "trimMaxShareBps",
+            "trimCPpm",
+        ]),
+        "exitWad",
+        "fillWad",
+        "suggestedBoundWad",
+        "oneStepWad",
+        "oneStepSpreadBps",
+        "confWad",
+        "suggestedAcceptablePriceWad",
+        "maxFeeBps",
+        "execFee",
+        "fillWindowMs",
+        "signedWindowMs",
+        "cancelDelayMs",
+        "emergencyAfterMs",
+        "feeOwed",
+    ],
+    builder: BUILDER,
+    builders: under("[]", BUILDER),
+    builderApprovals: under("[]", ["builderId:u32", "maxFeeBps:u16"]),
+    builderAllowance: ["created", "limit", "remaining"],
+    referrals: [
+        "asReferee.boundAtMs",
+        ...under("asReferrer", [
+            "direct[].boundAtMs",
+            "directCount",
+            "secondLevel[].boundAtMs",
+            "secondLevelCount",
+            "refereeClaimVolume",
+            "estimatedDirectBonus",
+            "estimatedSecondBonus",
+        ]),
+    ],
+    stakingPool: [
+        "totalStaked",
+        "streamRemaining",
+        "streamLastMs",
+        "streamEndMs",
+        "streamVestedNow",
+        "rewardStreamMs",
+        "minStakeLockMs",
+        "rewards",
+        "referralReserve",
+        "nowMs",
+        "parchDripRemaining",
+        "parchDripNow",
+        "parchDripLastMs",
+        "parchDripEndMs",
+        "totalWeight",
+        "lockedWeight",
+        "lockedWeightBps",
+        "lockedOwedTotal",
+    ],
+    staker: [
+        "staked",
+        "stakedAtMs",
+        "unlockAtMs",
+        "pendingReward",
+        "parchPending",
+        "nowMs",
+        "lockedWeight",
+        "lockedSyncedBalance",
+        "lockedPending",
+        "lockedOwed",
+        "totalWeight",
+    ],
+    sponsored: ["gasBudget", "gasPrice", "estimatedGas", "validEpoch"],
+    queue: ["length", "totalOwed", "lpCash", "instantlyPayable", "owedToLpCashBps"],
+    lp: [
+        ...under("sweep", [
+            "floorBps:u64", "maxBps:u64", "intervalMs:u64", "capBps:u64",
+            "cashFloor:u64", "stakerBps:u64", "treasuryBps:u64", "growthBps:u64",
+        ]),
+        "lpCash",
+        "trackedLp",
+        "equity",
+        "totalOwed",
+        "queueLength",
+        "feeLp",
+        "feeStaker",
+        "feeDev",
+        "userFree",
+        "lockedMargin",
+        "tailProgress",
+        "feeGrowth",
+        "stakerShareBps",
+        "stakerShareMinBps",
+        "stakerShareMaxBps",
+        "stakerCovLowBps",
+        "stakerCovHighBps",
+        "reserveUpnl",
+        "reserveStress",
+        "reserve",
+        "lastSurplusMs",
+        "reserveEpoch",
+        "oiMarkets",
+        ...under("head", CLAIM),
+        ...under("claims[]", CLAIM),
+    ],
+    lpQueue: ["queueLength", "totalOwed", "lpCash", ...under("head", CLAIM), ...under("claims[]", CLAIM)],
+    protocol: ["openPositions", "openNotional", "volumeNotional", "equity", "lpCash", "queueLength"],
+    gameDefinitions: [
+        ...under("quests[]", ["id", "kind", "param", "xp", "cosmetic", "startMs", "endMs", "seasonId"]),
+        ...under("achievements[]", ["id", "kind", "param", "xp", "mintAmount", "cosmetic"]),
+        "cosmetics[].id",
+        "achievementMintFractionBps",
+    ],
+    game: [
+        "xp",
+        "seasonXp",
+        "seasonId",
+        "tier",
+        "streak",
+        "winStreak",
+        "crates",
+        "trades",
+        "achievements[]",
+        "questsDone[]",
+        "cosmetics[]",
+        "minted",
+        "mintedToday",
+        "pendingMint",
+        "lastDailyDay",
+        "feeCredit",
+        "feeCreditUsed",
+        "achievementMintFractionBps",
+        ...under("feeAchievements[]", ["id", "mintAtUnlock", "feesRequired", "feesNeeded", "xp", "mintAmount", "eligibleMint"]),
+        "lockedBalance",
+        "lockWindowBalance",
+        "nextUnlockMs",
+        "vestingBalance",
+        "releasableNow",
+        "earlyExitPaidNow",
+        "earlyExitPenaltyNow",
+        "earlyExitUnlocks[]",
+    ],
+    leaderboard: [...under("rows[]", LEADERBOARD_ROW), ...under("viewer", LEADERBOARD_ROW), "nextCursor"],
+    feed: under("entries[]", ["positionId", "pnl:i128", "notional", "atMs", "leverage", "exitWad"]),
+    pnlCard: ["positionId", "pnl:i128", "pnlPct:i128"],
+    recentPositions: under("entries[]", ["positionId", "atMs", "notional", "margin", "leverage", "entryWad", "exitWad", "priceWad"]),
+    none: [],
+};

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

@@ -0,0 +1,24 @@
+/**
+ * BCS for `parchment::events::Event<PositionsReconciledEventV1>`: one
+ * reconcile call (`trade::reconcile`, or the one an open, fill, retired close or emergency close
+ * runs first) removed these swept / liquidated positions of `market_id` from `account_id`, at most
+ * `max_reconcile` (32), in removal order. Never emitted with no positions.
+ */
+export declare const POSITIONS_RECONCILED_EVENT_BCS: import("@mysten/sui/bcs").BcsStruct<{
+    account_id: import("@mysten/sui/bcs").BcsType<string, string | Uint8Array<ArrayBufferLike>, "bytes[32]">;
+    market_id: import("@mysten/sui/bcs").BcsType<string, string | Uint8Array<ArrayBufferLike>, "bytes[32]">;
+    position_ids: import("@mysten/sui/bcs").BcsType<string[], Iterable<string | number | bigint> & {
+        length: number;
+    }, string>;
+}, string>;
+/** BCS for the per-position `Event<PositionReconciledEventV1>` (`account_id`, `position_id`). */
+export declare const POSITION_RECONCILED_EVENT_BCS: import("@mysten/sui/bcs").BcsStruct<{
+    account_id: import("@mysten/sui/bcs").BcsType<string, string | Uint8Array<ArrayBufferLike>, "bytes[32]">;
+    position_id: import("@mysten/sui/bcs").BcsType<string, string | number | bigint, "u64">;
+}, string>;
+export type PositionsReconciledEvent = ReturnType<typeof POSITIONS_RECONCILED_EVENT_BCS.parse>;
+export type PositionReconciledEvent = ReturnType<typeof POSITION_RECONCILED_EVENT_BCS.parse>;
+/** Decode event bytes supplied by the API; null when they are not this event (or list no position). */
+export declare function decodePositionsReconciledEvent(bytes: Uint8Array): PositionsReconciledEvent | null;
+/** Decode the pre-2026-10-30 per-position event; null when the bytes are not that event. */
+export declare function decodePositionReconciledEvent(bytes: Uint8Array): PositionReconciledEvent | null;

package/dist/packages/parchment/reconcileEvents.js

@@ -0,0 +1,30 @@
+import { bcs } from "@mysten/sui/bcs";
+export const POSITIONS_RECONCILED_EVENT_BCS = bcs.struct("PositionsReconciledEventV1", {
+    account_id: bcs.Address,
+    market_id: bcs.Address,
+    position_ids: bcs.vector(bcs.u64()),
+});
+export const POSITION_RECONCILED_EVENT_BCS = bcs.struct("PositionReconciledEventV1", {
+    account_id: bcs.Address,
+    position_id: bcs.u64(),
+});
+export function decodePositionsReconciledEvent(bytes) {
+    try {
+        const event = POSITIONS_RECONCILED_EVENT_BCS.parse(bytes);
+        if (event.position_ids.length === 0)
+            return null;
+        return POSITIONS_RECONCILED_EVENT_BCS.serialize(event).toBytes().length === bytes.length ? event : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function decodePositionReconciledEvent(bytes) {
+    try {
+        const event = POSITION_RECONCILED_EVENT_BCS.parse(bytes);
+        return POSITION_RECONCILED_EVENT_BCS.serialize(event).toBytes().length === bytes.length ? event : null;
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -0,0 +1,43 @@
+import type { Transaction, TransactionObjectArgument } from "@mysten/sui/transactions";
+import type { ApiParchmentLpResponse } from "./parchmentTypes.js";
+/**
+ * The retained-fee staker share curve (`config::set_retained_fee_curve`):
+ * stakers get `minShareBps` of each retained fee at pool coverage (pool cash / R) <= `lowCovBps`,
+ * `maxShareBps` at >= `highCovBps`, linear between; the treasury keeps the rest. Always split, never
+ * paused, never to the pool.
+ */
+export interface ParchmentRetainedFeeCurve {
+    minShareBps: bigint;
+    maxShareBps: bigint;
+    lowCovBps: bigint;
+    highCovBps: bigint;
+}
+/** Launch defaults (`constants.move`): stakers 30% at <= 100% coverage, rising to 70% at >= 200%. */
+export declare const RETAINED_FEE_CURVE_DEFAULTS: Readonly<ParchmentRetainedFeeCurve>;
+/** `constants::max_ratio_bps!()`: the highest coverage the curve may reference. */
+export declare const RETAINED_FEE_CURVE_MAX_COV_BPS = 30000n;
+/**
+ * Checks a setter input against the contract's bounds (`EBadEconParam` otherwise):
+ * `min_share_bps <= max_share_bps <= 10_000` and `low_cov_bps < high_cov_bps <= 30_000`.
+ */
+export declare function retainedFeeCurve(curve: ParchmentRetainedFeeCurve): ParchmentRetainedFeeCurve;
+/** Stakers' share (bps) of a retained fee, exactly as `safety::retained_staker_bps` (floored; R = 0 gives the max). */
+export declare function retainedStakerShareBps(pool: {
+    lpCash: bigint;
+    reserve: bigint;
+}, curve?: ParchmentRetainedFeeCurve): bigint;
+/** The served curve from `getLp()`, or null while any of its four fields is unindexed or not served. */
+export declare function lpRetainedFeeCurve(lp: Pick<ApiParchmentLpResponse, "stakerShareMinBps" | "stakerShareMaxBps" | "stakerCovLowBps" | "stakerCovHighBps">): ParchmentRetainedFeeCurve | null;
+export interface SetRetainedFeeCurveCall {
+    /** The core `parchment` package (where `config` lives). */
+    packageId: string;
+    configId: string | TransactionObjectArgument;
+    /** `AuthorityCap<PACKAGE, ADMIN>`. */
+    adminCapId: string | TransactionObjectArgument;
+    curve: ParchmentRetainedFeeCurve;
+}
+/**
+ * Admin: `config::set_retained_fee_curve(config, cap, min_share_bps, max_share_bps, low_cov_bps,
+ * high_cov_bps)` (admin action 83). The curve is checked with `retainedFeeCurve` first.
+ */
+export declare function addSetRetainedFeeCurveCall(tx: Transaction, input: SetRetainedFeeCurveCall): void;

package/dist/packages/parchment/retainedFee.js

@@ -0,0 +1,68 @@
+import { ParchmentApiError } from "../../general/utils/errors.js";
+export const RETAINED_FEE_CURVE_DEFAULTS = Object.freeze({
+    minShareBps: 3000n,
+    maxShareBps: 7000n,
+    lowCovBps: 10000n,
+    highCovBps: 20000n,
+});
+export const RETAINED_FEE_CURVE_MAX_COV_BPS = 30000n;
+const U64_MAX = (1n << 64n) - 1n;
+function u64(value, field) {
+    if (typeof value !== "bigint" || value < 0n || value > U64_MAX) {
+        throw new ParchmentApiError(0, "bad_request", `${field} must be a u64`);
+    }
+    return value;
+}
+export function retainedFeeCurve(curve) {
+    const minShareBps = u64(curve.minShareBps, "min_share_bps");
+    const maxShareBps = u64(curve.maxShareBps, "max_share_bps");
+    const lowCovBps = u64(curve.lowCovBps, "low_cov_bps");
+    const highCovBps = u64(curve.highCovBps, "high_cov_bps");
+    if (minShareBps > maxShareBps)
+        throw new ParchmentApiError(0, "bad_request", "min_share_bps must not exceed max_share_bps");
+    if (maxShareBps > 10000n)
+        throw new ParchmentApiError(0, "bad_request", "max_share_bps must be at most 10000");
+    if (lowCovBps >= highCovBps)
+        throw new ParchmentApiError(0, "bad_request", "low_cov_bps must be below high_cov_bps");
+    if (highCovBps > RETAINED_FEE_CURVE_MAX_COV_BPS) {
+        throw new ParchmentApiError(0, "bad_request", `high_cov_bps must be at most ${RETAINED_FEE_CURVE_MAX_COV_BPS}`);
+    }
+    return { minShareBps, maxShareBps, lowCovBps, highCovBps };
+}
+export function retainedStakerShareBps(pool, curve = RETAINED_FEE_CURVE_DEFAULTS) {
+    if (pool.reserve === 0n)
+        return curve.maxShareBps;
+    const c = pool.lpCash * 10000n;
+    const lo = pool.reserve * curve.lowCovBps;
+    const hi = pool.reserve * curve.highCovBps;
+    if (c <= lo)
+        return curve.minShareBps;
+    if (c >= hi)
+        return curve.maxShareBps;
+    return curve.minShareBps + ((c - lo) * (curve.maxShareBps - curve.minShareBps)) / (hi - lo);
+}
+export function lpRetainedFeeCurve(lp) {
+    const { stakerShareMinBps, stakerShareMaxBps, stakerCovLowBps, stakerCovHighBps } = lp;
+    if (typeof stakerShareMinBps !== "bigint" ||
+        typeof stakerShareMaxBps !== "bigint" ||
+        typeof stakerCovLowBps !== "bigint" ||
+        typeof stakerCovHighBps !== "bigint") {
+        return null;
+    }
+    return { minShareBps: stakerShareMinBps, maxShareBps: stakerShareMaxBps, lowCovBps: stakerCovLowBps, highCovBps: stakerCovHighBps };
+}
+export function addSetRetainedFeeCurveCall(tx, input) {
+    const curve = retainedFeeCurve(input.curve);
+    const obj = (o) => (typeof o === "string" ? tx.object(o) : o);
+    tx.moveCall({
+        target: `${input.packageId}::config::set_retained_fee_curve`,
+        arguments: [
+            obj(input.configId),
+            obj(input.adminCapId),
+            tx.pure.u64(curve.minShareBps),
+            tx.pure.u64(curve.maxShareBps),
+            tx.pure.u64(curve.lowCovBps),
+            tx.pure.u64(curve.highCovBps),
+        ],
+    });
+}