@parchment-trade/sdk 0.0.0-stage → 1.0.0

package/dist/general/types/index.js

@@ -0,0 +1 @@
+export {};

package/dist/general/utils/address.d.ts

@@ -0,0 +1,49 @@
+/** `0x` plus 64 lowercase hex characters; else `bad_request`, the service's and the legacy API's code. */
+export declare function normalizeAddress(value: string): string;
+/**
+ * A caller's base-unit integer (digits or a bigint) as its decimal text; bodies send it as the API's
+ * `"123n"` literal (`toJsBigInt`). A malformed value throws `code` (transaction bodies pass the service's
+ * `bad_amount` / `bad_price_bound`).
+ */
+export declare function baseUnit(value: string | bigint, field: string, code?: string): string;
+export declare const U64_MAX: bigint;
+/**
+ * {@link baseUnit} that also fits a Move u64, else `overflowCode` with no request; a malformed value
+ * throws the same code. Transaction bodies pass the service's `u64_of` code `bad_amount`;
+ * previews keep `invalid_amount`.
+ */
+export declare function u64Unit(value: string | bigint, field: string, overflowCode?: string): string;
+/** {@link baseUnit} that fits a Move u128 (price bounds); malformed or overflow is the service's `price_bound_of` code `bad_price_bound`. */
+export declare function u128Unit(value: string | bigint, field: string): string;
+export declare function signedUpdateBase64(update: string | Uint8Array): string;
+export declare function coinDigest(value: string): string;
+export declare function compact(body: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Decimal id cursor (positions, claims, leaderboard offset); null or blank is omitted, like the legacy API's `numeric_cursor`.
+ * `max` is the largest value the service parses for this cursor (leaderboard offset: u64); a
+ * larger one is a local error with no request: `code` (default `bad_request`; the leaderboard uses the service's `bad_cursor`).
+ */
+export declare function idCursor(value: string | number | bigint | null | undefined, field: string, max?: bigint, code?: string): string | undefined;
+export declare const I64_MAX: bigint;
+/**
+ * Millisecond query bound the service parses as i64 (price history `fromMs`/`toMs`, the service's `opt_i64`, which is
+ * Rust's `str::parse::<i64>`): an optional `+`/`-` sign and ASCII digits within i64. Anything else
+ * (blank, padded, decimal, hex, out of range) is a local `bad_request`, the service's code (a
+ * non-digit was `invalid_amount`). A negative or `+`-signed value parses at the service, so it is sent unchanged.
+ */
+/**
+ * History `cursor`: the service's `opt_i64` (`str::parse::<i64>`), so a negative or `+`-signed value is sent
+ * unchanged and anything else (padded, decimal, hex, out of i64 range) is a local `bad_request`. Null or
+ * a blank string is omitted (the SDK never sends an empty cursor). Formerly `idCursor` (digits only, trimmed).
+ */
+export declare function historyCursor(value: string | number | bigint | null | undefined): string | undefined;
+export declare function i64Ms(value: string | bigint, field: string): string;
+/**
+ * Page-size query value. The service answers a malformed `limit` (non-numeric, negative, zero,
+ * decimal, hex; a fractional or unsafe number too) with 400 `bad_request`, so that is thrown here with
+ * no request (was `invalid_amount`). Any all-digit value above zero is sent and the service
+ * clamps it to its `max-page-limit` (default 200), u64 overflow included; a blank string is omitted.
+ */
+export declare function limitParam(value: string | number | bigint | undefined): string | undefined;
+/** A `GET accounts/{owner}/equity` range: exactly `24h`, `7d`, `30d` or `all`, else `bad_request`. */
+export declare function equityRange(value: unknown): "24h" | "7d" | "30d" | "all";

package/dist/general/utils/address.js

@@ -0,0 +1,110 @@
+import { toBase64 } from "@mysten/sui/utils";
+import { ParchmentApiError } from "./errors.js";
+export function normalizeAddress(value) {
+    const hex = value.trim().toLowerCase().replace(/^0x/, "");
+    if (!/^[0-9a-f]{1,64}$/.test(hex)) {
+        throw new ParchmentApiError(0, "bad_request", `not an address: ${value}`);
+    }
+    return `0x${hex.padStart(64, "0")}`;
+}
+export function baseUnit(value, field, code = "invalid_amount") {
+    const text = typeof value === "bigint" ? value.toString() : typeof value === "string" ? value.trim() : "";
+    if (text.length === 0 || text.length > 78 || !/^[0-9]+$/.test(text)) {
+        throw new ParchmentApiError(0, code, `${field} must be a base-unit integer`);
+    }
+    return text;
+}
+export const U64_MAX = (1n << 64n) - 1n;
+const U128_MAX = (1n << 128n) - 1n;
+export function u64Unit(value, field, overflowCode = "invalid_amount") {
+    const text = baseUnit(value, field, overflowCode);
+    if (BigInt(text) > U64_MAX) {
+        throw new ParchmentApiError(0, overflowCode, `${field} must fit in a u64`);
+    }
+    return text;
+}
+export function u128Unit(value, field) {
+    const text = baseUnit(value, field, "bad_price_bound");
+    if (BigInt(text) > U128_MAX) {
+        throw new ParchmentApiError(0, "bad_price_bound", `${field} must fit in a u128`);
+    }
+    return text;
+}
+export function signedUpdateBase64(update) {
+    if (typeof update !== "string") {
+        if (update.byteLength === 0) {
+            throw new ParchmentApiError(0, "update_required", "signed Lazer update is empty");
+        }
+        return toBase64(update);
+    }
+    const standard = update.replace(/\s/g, "").replace(/-/g, "+").replace(/_/g, "/");
+    if (standard.length === 0 || !/^[A-Za-z0-9+/]+={0,2}$/.test(standard)) {
+        throw new ParchmentApiError(0, "update_required", "signed Lazer update must be base64");
+    }
+    if (Math.floor((standard.replace(/=+$/, "").length * 6) / 8) === 0) {
+        throw new ParchmentApiError(0, "update_required", "signed Lazer update is empty");
+    }
+    return standard;
+}
+export function coinDigest(value) {
+    if (value.length === 0 || value.length > 128 || !/^[0-9A-Za-z]+$/.test(value)) {
+        throw new ParchmentApiError(0, "bad_request", "coin.digest must be a base58 digest");
+    }
+    return value;
+}
+export function compact(body) {
+    const out = {};
+    for (const [key, value] of Object.entries(body)) {
+        if (value !== undefined)
+            out[key] = value;
+    }
+    return out;
+}
+export function idCursor(value, field, max, code = "bad_request") {
+    if (value === undefined || value === null || (typeof value === "string" && value.trim() === ""))
+        return undefined;
+    const cursor = typeof value === "string" ? value.trim()
+        : typeof value === "bigint" || (typeof value === "number" && Number.isSafeInteger(value)) ? value.toString() : "";
+    if (!/^[0-9]{1,40}$/.test(cursor))
+        throw new ParchmentApiError(0, code, `${field} must be a decimal id`);
+    if (max !== undefined && BigInt(cursor) > max)
+        throw new ParchmentApiError(0, code, `${field} must be <= ${max}`);
+    return cursor;
+}
+export const I64_MAX = (1n << 63n) - 1n;
+export function historyCursor(value) {
+    if (value === undefined || value === null || (typeof value === "string" && value.trim() === ""))
+        return undefined;
+    if (typeof value === "number" && !Number.isSafeInteger(value)) {
+        throw new ParchmentApiError(0, "bad_request", "cursor is not an integer");
+    }
+    return i64Ms(typeof value === "number" ? BigInt(value) : value, "cursor");
+}
+export function i64Ms(value, field) {
+    const bad = () => new ParchmentApiError(0, "bad_request", `${field} is not an integer`);
+    const text = typeof value === "bigint" ? value.toString() : value;
+    if (typeof text !== "string" || !/^[+-]?[0-9]+$/.test(text))
+        throw bad();
+    const n = BigInt(text);
+    if (n > I64_MAX || n < -I64_MAX - 1n)
+        throw bad();
+    return text;
+}
+export function limitParam(value) {
+    if (value === undefined)
+        return undefined;
+    const bad = () => new ParchmentApiError(0, "bad_request", "limit must be a positive integer");
+    if (typeof value === "number" && !Number.isSafeInteger(value))
+        throw bad();
+    const text = (typeof value === "string" ? value : value.toString()).trim();
+    if (text === "")
+        return undefined;
+    if (!/^[0-9]+$/.test(text) || BigInt(text) === 0n)
+        throw bad();
+    return text;
+}
+export function equityRange(value) {
+    if (value === "24h" || value === "7d" || value === "30d" || value === "all")
+        return value;
+    throw new ParchmentApiError(0, "bad_request", "range must be 24h, 7d, 30d, or all");
+}

package/dist/general/utils/caller.d.ts

@@ -0,0 +1,58 @@
+import type { ParchmentBuiltTx } from "../../packages/parchment/parchmentTypes.js";
+import type { CallerConfig } from "../types/configTypes.js";
+import { type IntPaths } from "./jsBigInt.js";
+/**
+ * Shared HTTP transport for Parchment API clients.
+ *
+ * A missing body is a GET. A body is a POST of JSON. Every integer in that JSON,
+ * request and response, is a `"123n"` literal (bigint-serde `js_bigint`); a read names
+ * where its response has integers ({@link IntPaths}) and gets them as bigints.
+ * Successful responses use a `data` field, which this caller returns. Transaction builders return kind bytes in
+ * `txBytesBase64`; {@link fetchApiTxObject} turns those into a `Transaction`
+ * and sets the sender.
+ */
+export declare class Caller {
+    readonly config: CallerConfig;
+    protected readonly apiBaseUrl: string | undefined;
+    protected readonly apiEndpoint: string;
+    private readonly apiUrlPrefix;
+    /**
+     * @param config - API origin and optional path segment.
+     * @param apiUrlPrefix - Package path inserted after the API segment. Parchment uses `"parchment"`.
+     */
+    constructor(config?: CallerConfig, apiUrlPrefix?: string);
+    protected urlForApiCall(url: string): string;
+    /**
+     * Sends a request and returns the `data` payload, its integers decoded to bigints.
+     *
+     * @param url - Path relative to `/api/parchment`, unless `apiEndpoint` was changed.
+     * @param ints - Where `data` has integers; a malformed one is `bad_body`.
+     * @param body - JSON body. Omit it for a GET.
+     * @param signal - Optional cancellation signal.
+     */
+    protected fetchApi<Output, BodyType = undefined>(url: string, ints: IntPaths, body?: BodyType, signal?: AbortSignal): Promise<Output>;
+    /** `fetchApi` for a `{ [key]: value }` payload: a null or missing value is `bad_body`, not a TypeError. */
+    protected fetchApiField<Output, Key extends string>(url: string, key: Key, ints: IntPaths, signal?: AbortSignal): Promise<Output>;
+    /**
+     * Posts a transaction builder and returns the parsed kind with its sender set. The API is trusted
+     * for what it builds; with `config.txTrust` set to pinned packages (opt-in strict mode) the kind is
+     * also checked against the request (`intent_mismatch`). The bytes do not include gas. A kind with a command the service never builds (a framework call
+     * other than `coin::zero`, a transfer to anyone but the sender, a split of the gas coin, a merge,
+     * a vector, a publish or an upgrade) is `bad_tx`.
+     */
+    protected fetchApiTxObject(url: string, body: Record<string, unknown>, signal?: AbortSignal): Promise<ParchmentBuiltTx>;
+    /**
+     * Appends `staking::sync_locked` for `owner` to a built release / exit (the `syncLocked` option).
+     * The API does not build it; the pool, exchange, token package and collateral type come from
+     * `/config`. `txBytesBase64` stays the API's kind, without the appended call. Under strict
+     * `txTrust` the token package must be pinned and `/config` must name a pinned one.
+     */
+    protected appendSyncLocked(built: ParchmentBuiltTx, owner: string, signal?: AbortSignal): Promise<ParchmentBuiltTx>;
+    private fetchImpl;
+    private readData;
+}
+/**
+ * Validates the opt-in request timeout. `undefined` means no timeout (the default). Node fires a
+ * delay above 2^31-1 ms after 1 ms, so a larger value is clamped (about 24.8 days).
+ */
+export declare function requestTimeoutMs(timeoutMs: number | undefined): number | undefined;

package/dist/general/utils/caller.js

@@ -0,0 +1,182 @@
+import { Transaction } from "@mysten/sui/transactions";
+import { normalizeSuiAddress } from "@mysten/sui/utils";
+import { PUBLIC_INTS } from "../../packages/parchment/publicInts.js";
+import { addSyncLockedCall } from "../../packages/parchment/stakingCalls.js";
+import { ParchmentApiError, retryAfterMs } from "./errors.js";
+import { decodeJsBigInts } from "./jsBigInt.js";
+import { serviceTxViolation } from "./txShape.js";
+import { UNCHECKED_TX, assertTxIntent, txRoute, untrustedConfigPackages } from "../../packages/parchment/txIntent.js";
+export class Caller {
+    config;
+    apiBaseUrl;
+    apiEndpoint;
+    apiUrlPrefix;
+    constructor(config = {}, apiUrlPrefix = "") {
+        this.config = config;
+        this.apiUrlPrefix = apiUrlPrefix;
+        this.apiBaseUrl = config.baseUrl?.trim().replace(/\/+$/, "") || undefined;
+        this.apiEndpoint = config.apiEndpoint?.replace(/^\/+|\/+$/g, "") || "api";
+    }
+    urlForApiCall(url) {
+        if (!this.apiBaseUrl) {
+            throw new ParchmentApiError(0, "base_url_required", "baseUrl is required");
+        }
+        const queryAt = url.indexOf("?");
+        const pathPart = queryAt === -1 ? url : url.slice(0, queryAt);
+        const query = queryAt === -1 ? "" : url.slice(queryAt);
+        const path = [this.apiEndpoint, this.apiUrlPrefix, pathPart]
+            .map((segment) => segment.replace(/^\/+|\/+$/g, ""))
+            .filter(Boolean)
+            .join("/");
+        return `${this.apiBaseUrl}/${path}${query}`;
+    }
+    async fetchApi(url, ints, body, signal) {
+        const hasBody = body !== undefined;
+        const fullUrl = this.urlForApiCall(url);
+        const timeoutMs = requestTimeoutMs(this.config.timeoutMs);
+        const callerSignals = [this.config.signal, signal].filter((s) => s != null);
+        for (const s of callerSignals)
+            s.throwIfAborted();
+        const timeout = timeoutMs === undefined ? undefined : new AbortController();
+        const timer = timeout && setTimeout(() => timeout.abort(), timeoutMs);
+        const signals = timeout ? [...callerSignals, timeout.signal] : callerSignals;
+        const stop = signals.length === 0 ? undefined : signals.length === 1 ? signals[0] : AbortSignal.any(signals);
+        const timedOut = () => new ParchmentApiError(0, "timeout", `request timed out after ${timeoutMs} ms`);
+        try {
+            let response;
+            try {
+                response = await this.fetchImpl()(fullUrl, {
+                    method: hasBody ? "POST" : "GET",
+                    headers: hasBody
+                        ? { "content-type": "application/json", accept: "application/json" }
+                        : { accept: "application/json" },
+                    body: hasBody ? JSON.stringify(body) : undefined,
+                    signal: stop,
+                });
+            }
+            catch (error) {
+                if (error instanceof ParchmentApiError)
+                    throw error;
+                for (const s of callerSignals)
+                    s.throwIfAborted();
+                if (timeout?.signal.aborted)
+                    throw timedOut();
+                const message = error instanceof Error ? error.message : "request failed";
+                throw new ParchmentApiError(0, "network", message);
+            }
+            return decodeJsBigInts(await this.readData(response, callerSignals, timeout?.signal, timedOut), ints);
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        }
+    }
+    async fetchApiField(url, key, ints, signal) {
+        const data = await this.fetchApi(url, ints, undefined, signal);
+        const value = data?.[key];
+        if (value === null || value === undefined) {
+            throw new ParchmentApiError(0, "bad_body", `response has no ${key}`);
+        }
+        return value;
+    }
+    async fetchApiTxObject(url, body, signal) {
+        if (typeof body.sender !== "string") {
+            throw new ParchmentApiError(0, "bad_request", "walletAddress is required");
+        }
+        const sender = body.sender;
+        const trust = this.config.txTrust ?? UNCHECKED_TX;
+        if (trust !== UNCHECKED_TX && (typeof trust !== "object" || trust === null || typeof trust.packages !== "object" || trust.packages === null)) {
+            throw new ParchmentApiError(0, "bad_request", 'txTrust is "unchecked" or { packages }');
+        }
+        const data = await this.fetchApi(url, [], body, signal);
+        if (!data || typeof data.txBytesBase64 !== "string" || data.txBytesBase64.length === 0) {
+            throw new ParchmentApiError(0, "bad_tx", "transaction response has no txBytesBase64");
+        }
+        let tx;
+        try {
+            tx = Transaction.fromKind(data.txBytesBase64);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : "could not read transaction kind";
+            throw new ParchmentApiError(0, "bad_tx", message);
+        }
+        const violation = serviceTxViolation(tx, sender);
+        if (violation !== null)
+            throw new ParchmentApiError(0, "bad_tx", `transaction has a ${violation}`);
+        if (trust !== UNCHECKED_TX)
+            await assertTxIntent(url, body, tx, sender, trust);
+        tx.setSender(sender);
+        return {
+            request: { route: txRoute(url), body },
+            tx,
+            commands: data.commands ?? [],
+            note: data.note ?? null,
+            txBytesBase64: data.txBytesBase64,
+        };
+    }
+    async appendSyncLocked(built, owner, signal) {
+        const config = await this.fetchApi("config", PUBLIC_INTS.config, undefined, signal);
+        const trust = this.config.txTrust;
+        if (trust && trust !== UNCHECKED_TX) {
+            if (!trust.packages.token?.length) {
+                throw new ParchmentApiError(0, "untrusted_package", "syncLocked under txTrust needs txTrust.packages.token");
+            }
+            const untrusted = untrustedConfigPackages(config, trust.packages);
+            if (untrusted.length > 0)
+                throw new ParchmentApiError(0, "untrusted_package", `config names package ids outside txTrust: ${untrusted.join(", ")}`);
+        }
+        const { tokenPackageId, stakingPoolId, exchangeId, usdcType } = config;
+        if (!tokenPackageId || !stakingPoolId || !exchangeId || !usdcType) {
+            throw new ParchmentApiError(0, "sync_locked_unavailable", "config has no token package, staking pool or exchange for sync_locked");
+        }
+        addSyncLockedCall(built.tx, { packageId: tokenPackageId, coinType: usdcType, pool: stakingPoolId, exchange: exchangeId, owner: normalizeSuiAddress(owner) });
+        return built;
+    }
+    fetchImpl() {
+        return this.config.fetch ?? globalThis.fetch;
+    }
+    async readData(response, callerSignals, timeoutSignal, timedOut) {
+        let text;
+        try {
+            text = await response.text();
+        }
+        catch (error) {
+            for (const s of callerSignals)
+                s.throwIfAborted();
+            if (timeoutSignal?.aborted)
+                throw timedOut();
+            const message = error instanceof Error ? error.message : "response body could not be read";
+            throw new ParchmentApiError(response.status, "network", message);
+        }
+        const retryAfter = response.ok ? undefined : retryAfterMs(response.headers?.get?.("retry-after"));
+        let parsed;
+        try {
+            parsed = text ? JSON.parse(text) : null;
+        }
+        catch {
+            throw new ParchmentApiError(response.status, "bad_body", "response was not JSON", retryAfter);
+        }
+        if (!parsed || typeof parsed !== "object") {
+            throw new ParchmentApiError(response.status, "bad_body", "response was empty", retryAfter);
+        }
+        const record = parsed;
+        if (record.error) {
+            throw new ParchmentApiError(response.status, record.error.code ?? "bad_request", record.error.message ?? "request failed", retryAfter);
+        }
+        if (!response.ok) {
+            throw new ParchmentApiError(response.status, "bad_request", `HTTP ${response.status}`, retryAfter);
+        }
+        if (!("data" in record)) {
+            throw new ParchmentApiError(response.status, "bad_body", "response has no data");
+        }
+        return record.data;
+    }
+}
+export function requestTimeoutMs(timeoutMs) {
+    if (timeoutMs === undefined)
+        return undefined;
+    if (typeof timeoutMs !== "number" || !(timeoutMs > 0)) {
+        throw new ParchmentApiError(0, "bad_request", "timeoutMs must be a positive number of milliseconds");
+    }
+    return Math.min(timeoutMs, 2_147_483_647);
+}

package/dist/general/utils/errors.d.ts

@@ -0,0 +1,16 @@
+/** Failure from a Parchment API call or from a request the SDK refused locally. */
+export declare class ParchmentApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    /**
+     * The response's `Retry-After` in milliseconds (delta-seconds or an HTTP date, floored at 0), when an
+     * error response carried a valid one: 429 from the limiter, and 503/504 passed through by the legacy API.
+     */
+    readonly retryAfterMs?: number;
+    constructor(status: number, code: string, message: string, retryAfterMs?: number);
+}
+/**
+ * `Retry-After` as milliseconds: delta-seconds or an IMF-fixdate HTTP date (floored at 0); anything else
+ * (e.g. "1.5", "-1", "2026-13", which `Date.parse` would accept leniently) is undefined, per RFC 9110.
+ */
+export declare function retryAfterMs(header: string | null | undefined): number | undefined;

package/dist/general/utils/errors.js

@@ -0,0 +1,26 @@
+export class ParchmentApiError extends Error {
+    status;
+    code;
+    retryAfterMs;
+    constructor(status, code, message, retryAfterMs) {
+        super(message);
+        this.name = "ParchmentApiError";
+        this.status = status;
+        this.code = code;
+        if (retryAfterMs !== undefined)
+            this.retryAfterMs = retryAfterMs;
+    }
+}
+export function retryAfterMs(header) {
+    const value = header?.trim();
+    if (!value)
+        return undefined;
+    if (/^[0-9]+$/.test(value)) {
+        const seconds = Number(value);
+        return Number.isSafeInteger(seconds * 1000) ? seconds * 1000 : undefined;
+    }
+    if (!/^[A-Z][a-z]{2}, [0-9]{2} [A-Z][a-z]{2} [0-9]{4} [0-9]{2}:[0-9]{2}:[0-9]{2} GMT$/.test(value))
+        return undefined;
+    const at = Date.parse(value);
+    return Number.isNaN(at) ? undefined : Math.max(0, at - Date.now());
+}

package/dist/general/utils/index.d.ts

@@ -0,0 +1,4 @@
+export { baseUnit, compact, normalizeAddress, signedUpdateBase64 } from "./address.js";
+export { Caller } from "./caller.js";
+export { ParchmentApiError } from "./errors.js";
+export { type IntPaths, decodeJsBigInts, parseJsBigInt, toJsBigInt } from "./jsBigInt.js";

package/dist/general/utils/index.js

@@ -0,0 +1,4 @@
+export { baseUnit, compact, normalizeAddress, signedUpdateBase64 } from "./address.js";
+export { Caller } from "./caller.js";
+export { ParchmentApiError } from "./errors.js";
+export { decodeJsBigInts, parseJsBigInt, toJsBigInt } from "./jsBigInt.js";

package/dist/general/utils/jsBigInt.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The Rust width of an integer field: `u`/`i` plus bits, or the bare `u` (unsigned, any width) /
+ * `i` (signed, any width). Paths without a tag are unsigned (`u`).
+ */
+export type IntKind = "u" | "i" | "u8" | "u16" | "u32" | "u64" | "u128" | "i64" | "i128";
+/**
+ * A public-API integer literal (`"123n"`) as a bigint; anything else, or a value outside `kind`
+ * (default signed, any width), is `bad_body` naming `field`.
+ */
+export declare function parseJsBigInt(value: unknown, field: string, kind?: IntKind): bigint;
+/** A bigint as the public API's integer literal (`123n` -> `"123n"`). */
+export declare function toJsBigInt(value: bigint): string;
+/**
+ * Where a response carries integers, by JSON path: `a.b` (object field), `a[]` (array items),
+ * `a.*` (map values), `[]` alone for a top-level array, optionally tagged with the field's Rust
+ * width after a colon (`ageMs:i64`, `id:u64`; {@link IntKind}). Untagged paths are unsigned of any
+ * width, so a negative there is `bad_body`. A path whose value is absent or null is left as is
+ * (the type says whether that is allowed).
+ */
+export type IntPaths = readonly string[];
+/**
+ * Decodes, in place, every integer at `paths` from its `"123n"` literal to a bigint; a value
+ * there that is not one, or is out of its tagged range, is `bad_body` naming its path.
+ * Everything else is left untouched.
+ */
+export declare function decodeJsBigInts<T>(value: unknown, paths: IntPaths): T;

package/dist/general/utils/jsBigInt.js

@@ -0,0 +1,74 @@
+import { ParchmentApiError } from "./errors.js";
+const JS_BIGINT = /^(?:0|-?[1-9][0-9]*)n$/;
+const INT_KINDS = new Set(["u", "i", "u8", "u16", "u32", "u64", "u128", "i64", "i128"]);
+function inRange(n, kind) {
+    const signed = kind.startsWith("i");
+    if (!signed && n < 0n)
+        return false;
+    const bits = kind.length > 1 ? BigInt(kind.slice(1)) : null;
+    if (bits === null)
+        return true;
+    return signed ? n >= -(1n << (bits - 1n)) && n < 1n << (bits - 1n) : n < 1n << bits;
+}
+export function parseJsBigInt(value, field, kind = "i") {
+    if (typeof value !== "string" || !JS_BIGINT.test(value)) {
+        throw new ParchmentApiError(0, "bad_body", `${field} must be an integer literal like "123n"`);
+    }
+    const n = BigInt(value.slice(0, -1));
+    if (!inRange(n, kind)) {
+        throw new ParchmentApiError(0, "bad_body", `${field} is out of range for ${kind === "u" ? "an unsigned integer" : kind}`);
+    }
+    return n;
+}
+export function toJsBigInt(value) {
+    return `${value}n`;
+}
+function splitTag(path) {
+    const at = path.lastIndexOf(":");
+    if (at < 0)
+        return [path, "u"];
+    const tag = path.slice(at + 1);
+    if (!INT_KINDS.has(tag))
+        throw new Error(`unknown integer tag ${tag} in ${path}`);
+    return [path.slice(0, at), tag];
+}
+export function decodeJsBigInts(value, paths) {
+    for (const tagged of paths) {
+        const [path, kind] = splitTag(tagged);
+        decodeAt(value, path.split(/\.|(?=\[\])/), path, kind);
+    }
+    return value;
+}
+function decodeAt(node, steps, path, kind) {
+    const [step, ...rest] = steps;
+    if (node === null || node === undefined || step === undefined)
+        return;
+    if (step === "[]") {
+        if (!Array.isArray(node))
+            throw new ParchmentApiError(0, "bad_body", `${path}: expected a list`);
+        if (rest.length === 0) {
+            node.forEach((item, i) => {
+                node[i] = parseJsBigInt(item, path, kind);
+            });
+        }
+        else {
+            for (const item of node)
+                decodeAt(item, rest, path, kind);
+        }
+        return;
+    }
+    if (typeof node !== "object" || Array.isArray(node)) {
+        throw new ParchmentApiError(0, "bad_body", `${path}: expected an object`);
+    }
+    const record = node;
+    const keys = step === "*" ? Object.keys(record) : [step];
+    for (const key of keys) {
+        const child = record[key];
+        if (child === null || child === undefined)
+            continue;
+        if (rest.length === 0)
+            record[key] = parseJsBigInt(child, path, kind);
+        else
+            decodeAt(child, rest, path, kind);
+    }
+}

package/dist/general/utils/txShape.d.ts

@@ -0,0 +1,8 @@
+import type { Transaction } from "@mysten/sui/transactions";
+/**
+ * Why a service-built transaction kind is not one the service builds, or null. The service only makes
+ * Move calls (outside the framework, except `0x2::coin::zero`), `TransferObjects` to the sender and a
+ * `SplitCoins` of an owned coin input (the builder creation fee); never a split of the gas coin, a merge, a
+ * vector, a publish or an upgrade.
+ */
+export declare function serviceTxViolation(tx: Transaction, sender: string): string | null;

package/dist/general/utils/txShape.js

@@ -0,0 +1,39 @@
+import { fromBase64, normalizeSuiAddress, toHex } from "@mysten/sui/utils";
+const FRAMEWORK_PACKAGES = new Set(["0x1", "0x2", "0x3"].map((id) => normalizeSuiAddress(id)));
+const FRAMEWORK_CALLS = new Set(["coin::zero"]);
+function pureAddress(data, arg) {
+    if (arg?.$kind !== "Input" || typeof arg.Input !== "number")
+        return null;
+    const input = data.inputs[arg.Input];
+    if (input?.$kind !== "Pure" || !input.Pure)
+        return null;
+    const bytes = fromBase64(input.Pure.bytes);
+    return bytes.length === 32 ? normalizeSuiAddress(toHex(bytes)) : null;
+}
+export function serviceTxViolation(tx, sender) {
+    const data = tx.getData();
+    const me = normalizeSuiAddress(sender);
+    for (const command of data.commands) {
+        switch (command.$kind) {
+            case "MoveCall": {
+                const { package: pkg, module, function: fn } = command.MoveCall;
+                if (FRAMEWORK_PACKAGES.has(normalizeSuiAddress(pkg)) && !FRAMEWORK_CALLS.has(`${module}::${fn}`))
+                    return `call to ${pkg}::${module}::${fn}`;
+                break;
+            }
+            case "TransferObjects": {
+                const to = pureAddress(data, command.TransferObjects.address);
+                if (to !== me)
+                    return `transfer to ${to ?? "a computed address"}`;
+                break;
+            }
+            case "SplitCoins":
+                if (command.SplitCoins.coin?.$kind !== "Input")
+                    return "split of the gas coin";
+                break;
+            default:
+                return `${command.$kind} command`;
+        }
+    }
+    return null;
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./general/providers/index.js";
+export * from "./general/utils/index.js";
+export * from "./packages/index.js";
+export * from "./types.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from "./general/providers/index.js";
+export * from "./general/utils/index.js";
+export * from "./packages/index.js";
+export * from "./types.js";

package/dist/packages/index.d.ts

@@ -0,0 +1,11 @@
+export { EMERGENCY_CLOSE_DISABLED_MS, MARKET_STATUS_ACTIVE, MARKET_STATUS_REDUCE_ONLY, MARKET_STATUS_RETIRED, ORDER_PARAMS_V1_BCS, ORDER_TX_NOTE, PUBLIC_INTS, bindTradingReferrerTxBody, transferAccountTxBody, cancelOrderTxBody, claimPendingMintTxBody, claimQuestTxBody, claimTxBody, exitEarlyBoundedTxBody, exitEarlyTxBody, releaseUnlockedTxBody, closePreviewBody, closeRetiredTxBody, depositTxBody, gameTxBody, openCratesTxBody, installTreasuryTxBody, lpHarvestTxBody, openAccountTxBody, registerBuilderTxBody, setBuilderPayoutTxBody, createBuilderTxBody, setBuilderFeeTxBody, builderOwnerTxBody, transferBuilderTxBody, approveBuilderTxBody, revokeBuilderApprovalTxBody, BUILDER_FEE_HARD_BPS, MAX_BUILDER_CREATE_FEE, setBuilderCreateFeeTxBody, stakeTxBody, sweepSurplusTxBody, unstakeTxBody, withdrawTxBody, decodeOrderParams, closeRetiredAsDelegateTxBody, emergencyCloseAsDelegateTxBody, grantDelegateTxBody, grantCloseDelegateTxBody, grantSessionAndTriggerTxBody, revokeSessionAndTriggerTxBody, revokeDelegateTxBody, NEAR_LIQ_DISTANCE_FRACTION, TRIGGER_PROOF_TTL_MS, TRIGGER_PROOF_VERSION, newTriggerIntentId, signTriggerProof, stopAgainstLiquidation, triggerBindBody, triggerPrepareBody, triggerProofMessage, triggerRequestBody, emergencyCloseDisabled, emergencyCloseTxBody, expireOrderTxBody, hasPendingOrderSlot, isEmergencyAfterDisabled, openPreviewBody, orderParamsFromJson, orderRefTxBody, requestCloseAsDelegateTxBody, requestCloseTxBody, requestOpenAsDelegateTxBody, requestOpenTxBody, assertDelegateLiveThroughFill, DELEGATE_FILL_MARGIN_MS, ORDER_ABORT_MESSAGES, ORDER_ABORT_NAMES, ORACLE_RESERVED_ABORT_CODES, ORDER_RESERVED_ABORT_CODES, TRADE_RESERVED_ABORT_CODES, MIN_CANCEL_DELAY_MS, ORDER_FINALIZED_EVENT_BCS, ORDER_OUTCOMES, ORDER_REFUND_SESSION_MESSAGE, ORDER_REQUESTED_EVENT_BCS, PARCHMENT_CANDLES_BATCH_MAX_MARKETS, PARCHMENT_SPONSORED_ACTIONS, PARCHMENT_TRADE_MODULES, ParchmentAccount, ParchmentMarket, TX_ACTIONS, TRADE_ABORT_MESSAGES, TRADE_ABORT_NAMES, FEE_MINT_ABORT_MESSAGES, FEE_MINT_ABORT_NAMES, MARKET_ABORT_MESSAGES, MARKET_ABORT_NAMES, ACCESS_ABORT_NAMES, ACCOUNT_ABORT_NAMES, CONFIG_ABORT_NAMES, BUILDER_ABORT_NAMES, REFERRAL_ABORT_NAMES, STAKING_ABORT_NAMES, DECLARED_NOT_RAISED_ABORT_CODES, EXCHANGE_ABORT_NAMES, HOLDER_BOOK_ABORT_NAMES, ACCOUNT_TRANSFER_ABORT_NAMES, ABORT_MODULE_PATHS, ABORT_NAME_MAPS, AUTHORITY_ABORT_NAMES, FEES_ABORT_NAMES, GAME_ABORT_MESSAGES, GAME_ABORT_NAMES, KEEPER_ABORT_NAMES, EVENT_GUARD_ABORT_NAMES, LIQ_BOOK_ABORT_NAMES, LP_ABORT_NAMES, ORACLE_ABORT_NAMES, ORACLE_ADAPTER_ABORT_NAMES, POSITION_ABORT_NAMES, TIMELOCK_ABORT_NAMES, LOCKED_MINT_ABORT_NAMES, MINT_CAP_ABORT_NAMES, UNCOVERED_MODULES, LOCKED_LEDGER_STATUSES, RETAINED_FEE_CURVE_DEFAULTS, RETAINED_FEE_CURVE_MAX_COV_BPS, addSetRetainedFeeCurveCall, lpRetainedFeeCurve, retainedFeeCurve, retainedStakerShareBps, abortMessage, abortName, boundFromSlippage, decodeAbortCode, decodeOrderFinalizedEvent, finalizedOrdersFromTx, orderOutcome, decodeOrderRequestedEvent, isParchmentTradeModule, marketIsActive, marketIsDelisted, marketIsRetired, marketMinHoldMs, marketNextSessionOpenMs, marketSessionEndsAtMs, liquidationPaused, requestsPausedMessage, orderAbortMessage, orderAbortName, effectiveCancelAfterMs, orderExpiresAfterMs, parchmentBaseTypePackageId, parchmentCallPackageId, parchmentCoreTypePackageId, parchmentGameTypePackageId, parchmentMintTypePackageId, parchmentTradeTypePackageId, requireSplitPackageIds, requestedOrderIdFromTx, requestedOrdersFromTx, SPONSOR_IN_FLIGHT_LIMIT, SPONSOR_NOT_DELEGATE, isSessionKeyRevoked, shouldPayOwnGas, sponsorBody, SESSION_KEY_EXPIRY_MARGIN_MS, SESSION_KEY_TTL_MS, MAX_SPONSOR_PROOF_LIFETIME_MS, SPONSOR_PROOF_LIFETIME_MS, assertSessionTradeKind, createSessionKey, isSponsoredCopyOf, liveSessionDelegate, sessionKeyExpiryMs, sessionKeyFromSecret, sessionKeySecret, signSessionSponsoredTx, signSponsorProof, sponsorProofMessage, tradeAbortMessage, FORCE_CLOSE_SESSION_MAX_IDS, BatchCloseError, CLOSE_BATCH_BUDGET, SPONSOR_BATCH_BUDGET, SUI_TX_LIMITS, batchCloseTx, closeBatchTopUps, closeBatchUsage, fitCloseBatch, legIsRequest, planCloseBatches, splitCloseBatches, txIntentViolation, untrustedConfigPackages, UNCHECKED_TX, GAME_REGISTRY_MAXIMA, gameEventLimitsFromDefinitions, playerProgressionEvents, addArmSessionCloseAdminCall, addArmSessionCloseCall, addSessionRefundCall, addForceCloseSessionCall, addMintPendingForCalls, buildMintPendingForTx, addOneSignatureOnboardingCalls, deriveAccountId, MONITORING_MAX_DAYS, monitoringPath, monitoringView, statsActivityPath, statsActivityView, STAKING_HISTORY_WINDOWS, stakingHistoryPath, stakingHistoryView, parseLivePrice, parseTrade, } from "./parchment/index.js";
+export type { ParchmentDelegateLiveness, BatchCloseClient, BatchCloseLeg, BatchCloseOptions, CloseBatchPlanLeg, CloseBatchUsage, GameEventLimits, ParchmentTrustedPackages, ParchmentTxTrust, ParchmentTxTrustSetting, ArmSessionCloseAdminCall, ArmSessionCloseCall, ForceCloseSessionCall, SessionRefundCall, AccountIdInput, OneSignatureOnboardingCalls, ParchmentSessionKey, ParchmentSponsorProof, StopPlacement, TriggerBindInput, TriggerIntentTarget, TriggerKind, TriggerProof, TriggerProofInput, TriggerSigner, TriggerTarget, ParchmentRetainedFeeCurve, SetRetainedFeeCurveCall, OrderParamsV1, FinalizedOrderRef, OrderFinalizedEventV1, OrderRequestedEventV1, ParchmentExecutedEventLike, ParchmentExecutedTxLike, ParchmentPackageScope, ParchmentTradeModule, RequestedOrderRef, SlippageAction, SlippageSide, ParchmentMonitoring, ParchmentMintCapStats, ParchmentMintEpoch, ParchmentMintDay, ParchmentQueueStats, ParchmentQueueDay, ParchmentMarketExposure, ParchmentSideExposure, ParchmentExposureDay, ParchmentFeeStats, ParchmentFeeFlows, ParchmentFeeDay, ParchmentMarketFillLag, ParchmentFillLags, ParchmentFillLagDay, ParchmentLagStats, ParchmentGapStats, ParchmentShortHoldStats, ParchmentShortHolds, ParchmentShortHoldDay, ParchmentMarketShortHolds, ParchmentStatsActivity, ParchmentMarketActivity, ParchmentMarketFlow, ParchmentMarketFlowDay, ParchmentCollateralFlow, ParchmentCollateralFlowDay, ParchmentStakingHistory, ParchmentStakingHistoryDays, ParchmentStakingHistoryPoint, ParchmentStakingDay, } from "./parchment/index.js";
+export { EVENT_CLOSE_ARMED_EVENT_BCS, EVENT_GUARD_MAX_WINDOW_MS, EVENT_LEVERAGE_CAP_UPDATED_EVENT_BCS, EVENT_PAUSE_UPDATED_EVENT_BCS, EVENT_REASON, addArmEventCloseCall, addClearEventLeverageCapCall, addClearEventPauseCall, addEventGuardAdminClearCall, addSetEventLeverageCapCall, addSetEventPauseCall, decodeEventCloseArmedEvent, decodeEventLeverageCapUpdatedEvent, decodeEventPauseUpdatedEvent, eventGuardEventType, } from "./parchment/index.js";
+export type { ArmEventCloseCall, EventCloseArmedEvent, EventGuardAdminClearCall, EventKeeperCall, EventLeverageCapUpdatedEvent, EventPauseUpdatedEvent, EventReason, SetEventLeverageCapCall, SetEventPauseCall, } from "./parchment/index.js";
+export { TRIGGER_LEVELS_COMMITTED_BCS, TRIGGER_LEVELS_SET_EVENT_BCS, decodeTriggerLevelsCommitted, decodeTriggerLevelsSetEvent } from "./parchment/index.js";
+export type { TriggerLevelsCommitted, TriggerLevelsSetEvent } from "./parchment/index.js";
+export { addRequestOpenWithTriggersCall, addRequestOpenWithTriggersAsDelegateCall, addSetTriggerLevelsCall, addSetTriggerLevelsAsDelegateCall } from "./parchment/index.js";
+export type { MintPendingForCalls } from "./parchment/index.js";
+export type { TriggerOpenCall, TriggerOpenWithCapCall, TriggerEditCall, TriggerEditWithCapCall, TriggerEditAsDelegateCall } from "./parchment/index.js";
+export { LOCKED_WEIGHT_SYNCED_EVENT_BCS, LOCKED_YIELD_CLAIMED_EVENT_BCS, LOCKED_YIELD_FORFEITED_EVENT_BCS, LOCKED_WEIGHT_BPS_UPDATED_EVENT_BCS, decodeLockedWeightSyncedEvent, decodeLockedYieldClaimedEvent, decodeLockedYieldForfeitedEvent, decodeLockedWeightBpsUpdatedEvent, addSyncLockedCall, addSyncLockedCalls, addForfeitLockedYieldCall, } from "./parchment/index.js";
+export type { LockedWeightSyncedEventV1, LockedYieldClaimedEventV1, LockedYieldForfeitedEventV1, LockedWeightBpsUpdatedEventV1, SyncLockedCall, } from "./parchment/index.js";