@parchment-trade/sdk 0.0.0-stage → 1.0.1

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

@@ -0,0 +1,99 @@
+import type { Transaction } from "@mysten/sui/transactions";
+/**
+ * Every approved version of each package lineage the service's transactions call, original id
+ * first. Take these from your own build (e.g. `docs/PUBLISHED-mainnet.md`) and add an upgrade's id
+ * only once you approve it. Never fill them from `GET /config`: that is the response being checked.
+ */
+export interface ParchmentTrustedPackages {
+    /** Core `parchment` (`exchange`, `config`, ...). */
+    core: readonly string[];
+    /** `parchment_trade` (`order`, `trade`, `oracle`, the game / mint facades, ...). */
+    trade: readonly string[];
+    /** `parchment_base` (`builder_book`, `safety`, ...). Checked against `/config` `basePackageId(s)`. */
+    base: readonly string[];
+    /** `parchment_game`. Checked against `/config` `gamePackageId(s)`; calls go through the trade facades. */
+    game: readonly string[];
+    /** `parchment_mint` (`MintCapKey` types). Checked against `/config` `mintPackageId(s)`; calls go through the trade facades. */
+    mint: readonly string[];
+    /** `parchment_oracle` (`adapter::quote`). Needed for one-step closes, liquidations and sweeps. */
+    oracle?: readonly string[];
+    /** `parchment_token` (`tokenomics::mint_on_loss`, `staking`, `parchment::install_treasury`). */
+    token?: readonly string[];
+    /** the Lazer integration (`price_feed_storage::update_price_feed`). */
+    lazerIntegration?: readonly string[];
+}
+/**
+ * `ParchmentOptions.txTrust: "unchecked"`: build without intent checks, trusting the builder API
+ * for packages and arguments (only the command shapes are checked). For tests and tooling, not wallets.
+ */
+export declare const UNCHECKED_TX: "unchecked";
+/** `ParchmentOptions.txTrust` / `BatchCloseOptions.txTrust`: the trust, or the explicit opt-out. */
+export type ParchmentTxTrustSetting = ParchmentTxTrust | typeof UNCHECKED_TX;
+/** `ParchmentOptions.txTrust`: what builder responses are checked against. */
+export interface ParchmentTxTrust {
+    packages: ParchmentTrustedPackages;
+    /**
+     * The service's close-only trigger delegate. `grant-close-delegate` and `grant-session-and-trigger`
+     * name none in the request (the service adds its own), so without this pin those routes are refused.
+     */
+    triggerDelegate?: string;
+    /**
+     * Which of `delegates` hold a trade or close-only grant on `accountId`, read from chain (the
+     * account's `delegates` and the core package's close-delegate fields), never from the Parchment
+     * API. `revoke-session-and-trigger` revokes only the grants the account holds, so with this
+     * reader a response must revoke exactly the held ones. Without it, the response must revoke
+     * every distinct named delegate, and a one-grant revoke has to use `revoke-delegate` instead.
+     */
+    heldDelegates?: (accountId: string, delegates: readonly string[]) => Promise<readonly string[]>;
+    /**
+     * Emergency and retired closes whose request carries no `update` take the signed update the
+     * service attaches. The chain still verifies it as a fresh Lazer signature, but which
+     * price inside that freshness window is the builder's choice. Off by default: such a request is
+     * refused under `txTrust`, so pass the `update` you fetched (bound exactly), or set this to accept
+     * the service's choice.
+     */
+    acceptServiceOracleUpdate?: boolean;
+}
+/** The pure argument (base64 of BCS `vector<u8>`) a kind built for `updateBase64` passes to `quote`, or null. */
+export declare function updateArgBase64(updateBase64: unknown): string | null;
+/**
+ * Why `tx` (the kind a builder returned for `route` and request `body`, with `sender`) is not the
+ * transaction built for that request, or null. Checks: every Move call targets a trusted package id
+ * and a module of that package; the route's action calls appear exactly as often as tx.rs builds
+ * them, with the request's objects, amounts, side, bounds and delegates; nothing else is called
+ * but the route's prelude. Routes with no intent here are refused.
+ *
+ * `held`: for `revoke-session-and-trigger`, the named delegates that hold a grant, read from chain
+ * ({@link ParchmentTxTrust.heldDelegates}). Without it every distinct named delegate must be revoked.
+ */
+export declare function txIntentViolation(route: string, tx: Transaction, body: Record<string, unknown>, sender: string, trust: ParchmentTxTrust, held?: readonly string[]): string | null;
+/**
+ * Package ids a `/config` response names that are not in the trusted set: a config substituted
+ * with another package. Core, trade, base, game and mint ids (singular and lists) are always
+ * compared, and a lineage with no trusted ids rejects any id. `oracle`, `token` and
+ * `lazerIntegration` are compared only when trusted ids are given for them.
+ */
+export declare function untrustedConfigPackages(config: {
+    packageId?: string | null;
+    packageIds?: readonly string[];
+    tradePackageId?: string | null;
+    tradePackageIds?: readonly string[];
+    basePackageId?: string | null;
+    basePackageIds?: readonly string[];
+    gamePackageId?: string | null;
+    gamePackageIds?: readonly string[];
+    mintPackageId?: string | null;
+    mintPackageIds?: readonly string[];
+    oraclePackageId?: string | null;
+    tokenPackageId?: string | null;
+    lazerIntegrationPackageId?: string | null;
+}, trusted: ParchmentTrustedPackages): string[];
+/** `transactions/<route>` → `<route>`. */
+export declare function txRoute(url: string): string;
+/**
+ * With `txTrust`, a builder response must be the transaction built for its request:
+ * throws `ParchmentApiError` `intent_mismatch` otherwise. `url` is the builder path
+ * (`transactions/<route>`). Run for every client's builder responses (`Caller.fetchApiTxObject`).
+ * For `revoke-session-and-trigger` it first reads which grants are live from `trust.heldDelegates`, when set.
+ */
+export declare function assertTxIntent(url: string, body: Record<string, unknown>, tx: Transaction, sender: string, trust: ParchmentTxTrust): Promise<void>;