@ember-finance/sdk 2.17.0 → 2.19.0

package/dist/src/placements/api.d.ts

@@ -0,0 +1,13 @@
+import { VaultsApi } from "../api/v2/index.js";
+/**
+ * The generated vaults client, on the fetch adapter so this module keeps one
+ * transport in the browser and in Node.
+ */
+export declare function vaultsApi(baseUrl: string): VaultsApi;
+/** Status and Retry-After of a failed call, or undefined when no response came back. */
+export declare function httpFailure(error: unknown): {
+    status: number;
+    retryAfter?: string;
+} | undefined;
+/** True for a transport failure (no response), which is worth retrying. */
+export declare function isNetworkError(error: unknown): boolean;

package/dist/src/placements/api.js

@@ -0,0 +1,26 @@
+import axios from "axios";
+import { Configuration, VaultsApi } from "../api/v2/index.js";
+/**
+ * The generated vaults client, on the fetch adapter so this module keeps one
+ * transport in the browser and in Node.
+ */
+export function vaultsApi(baseUrl) {
+    return new VaultsApi(new Configuration({
+        basePath: baseUrl.replace(/\/$/, ""),
+        baseOptions: { adapter: "fetch" }
+    }));
+}
+/** Status and Retry-After of a failed call, or undefined when no response came back. */
+export function httpFailure(error) {
+    if (!axios.isAxiosError(error) || !error.response)
+        return undefined;
+    const retryAfter = error.response.headers?.["retry-after"];
+    return {
+        status: error.response.status,
+        retryAfter: typeof retryAfter === "string" ? retryAfter : undefined
+    };
+}
+/** True for a transport failure (no response), which is worth retrying. */
+export function isNetworkError(error) {
+    return axios.isAxiosError(error) && !error.response && !axios.isCancel(error);
+}

package/dist/src/placements/pointers.d.ts

@@ -10,7 +10,6 @@ export interface HttpPointerSourceOptions {
     env?: PlatformEnv;
     /** Overrides `env` entirely. For a local deployment, or a proxy. */
     baseUrl?: string;
-    path?: string;
     /** How long a coin's rows may be reused, in milliseconds. Default 30s. */
     cacheMs?: number;
 }

package/dist/src/placements/pointers.js

@@ -1,5 +1,6 @@
 import { environmentConfig } from "../common/constants.js";
-import { isAbortError, isTransientStatus, retryAfterMs } from "./batch.js";
+import { httpFailure, isNetworkError, vaultsApi } from "./api.js";
+import { isTransientStatus, retryAfterMs } from "./batch.js";
 import { coinTypesMatch, normalizeCoinType } from "./sui.js";
 /**
  * Pointers held in memory. Useful for tests, and for pinning a known venue set
@@ -33,7 +34,7 @@ export function httpPointerSource(options = {}) {
     // makes, not to cache across a session: pointers change when a venue is
     // added, and a long window would keep a new one invisible.
     const baseUrl = options.baseUrl ?? environmentConfig[options.env ?? "prod"].apiHost;
-    const path = options.path ?? "/api/v2/vaults/placements";
+    const api = vaultsApi(baseUrl);
     const cacheMs = options.cacheMs ?? 30000;
     /**
      * One request for every coin. The endpoint answers with the whole registry
@@ -59,12 +60,7 @@ export function httpPointerSource(options = {}) {
         inFlight.set(key, { at: Date.now(), rows });
         return rows;
     };
-    const request = (coin) => {
-        const url = new URL(`${baseUrl.replace(/\/$/, "")}${path}`);
-        if (coin !== undefined)
-            url.searchParams.set("coin", coin);
-        return fetchPlacements(url.toString());
-    };
+    const request = (coin) => fetchPlacements(api, coin);
     const rowsFor = async (coin) => {
         if (Date.now() >= perCoinUntil) {
             try {
@@ -139,34 +135,31 @@ const FALLBACK_RECHECK_MS = 5 * 60000;
  * Retries transient failures. Every vault's venues now ride on this one
  * request, and callers keep a failed discover rather than retrying it.
  */
-async function fetchPlacements(url) {
+async function fetchPlacements(api, coin) {
     for (let attempt = 1;; attempt++) {
         let waitMs;
         try {
-            const response = await fetch(url, {
-                headers: { Accept: "application/json" }
-            });
-            if (response.ok) {
-                const body = (await response.json());
-                return body.placements ?? [];
-            }
-            if (!isTransientStatus(response.status) || attempt >= FETCH_ATTEMPTS) {
-                throw new PointerSourceError(response.status);
-            }
-            waitMs = retryAfterMs(response.headers?.get("retry-after"));
-            // Retrying before the server asked would only add to the load it
-            // is shedding and fail again.
-            if (waitMs !== undefined && waitMs > RETRY_MAX_MS) {
-                throw new PointerSourceError(response.status);
-            }
+            const { data } = await api.getCoinPlacements(coin);
+            return data.placements ?? [];
         }
         catch (error) {
-            // fetch rejects only on network failure; retry that, not our own
-            // errors or an abort.
-            if (error instanceof PointerSourceError ||
-                isAbortError(error) ||
-                attempt >= FETCH_ATTEMPTS) {
-                throw error;
+            const failure = httpFailure(error);
+            if (!failure) {
+                // Only a transport failure is worth retrying, not an abort or a
+                // bug of our own.
+                if (!isNetworkError(error) || attempt >= FETCH_ATTEMPTS)
+                    throw error;
+            }
+            else {
+                if (!isTransientStatus(failure.status) || attempt >= FETCH_ATTEMPTS) {
+                    throw new PointerSourceError(failure.status);
+                }
+                waitMs = retryAfterMs(failure.retryAfter);
+                // Retrying before the server asked would only add to the load it
+                // is shedding and fail again.
+                if (waitMs !== undefined && waitMs > RETRY_MAX_MS) {
+                    throw new PointerSourceError(failure.status);
+                }
             }
         }
         const backoff = Math.min(RETRY_BASE_MS * 2 ** (attempt - 1), RETRY_MAX_MS);

package/dist/src/placements/vaults.js

@@ -1,4 +1,5 @@
 import { environmentConfig } from "../common/constants.js";
+import { httpFailure, vaultsApi } from "./api.js";
 /**
  * Resolves a vault to the receipt coins it issues, from the vaults API.
  *
@@ -6,14 +7,17 @@ import { environmentConfig } from "../common/constants.js";
  * each, so this returns one entry per chain rather than assuming a single coin.
  */
 export function httpVaultCoinsResolver(options = {}) {
-    const baseUrl = (options.baseUrl ?? environmentConfig[options.env ?? "prod"].apiHost).replace(/\/$/, "");
-    const get = async (path) => {
-        const response = await fetch(`${baseUrl}${path}`, {
-            headers: { Accept: "application/json" }
-        });
-        if (!response.ok)
-            throw new Error(`vaults api ${response.status} for ${path}`);
-        return (await response.json());
+    const api = vaultsApi(options.baseUrl ?? environmentConfig[options.env ?? "prod"].apiHost);
+    const get = async (path, call) => {
+        try {
+            return (await call()).data;
+        }
+        catch (error) {
+            const failure = httpFailure(error);
+            if (failure)
+                throw new Error(`vaults api ${failure.status} for ${path}`);
+            throw error;
+        }
     };
     // The chain catalogue is what carries the EVM network id. Without it an EVM
     // coin has no chainId, and every read for it fails rather than returning a
@@ -22,7 +26,7 @@ export function httpVaultCoinsResolver(options = {}) {
     const chainRefs = () => {
         if (chains)
             return chains;
-        chains = get("/api/v2/vaults/supported-chains").then(supported => {
+        chains = get("/api/v2/vaults/supported-chains", () => api.getSupportedChains()).then(supported => {
             const byIdentifier = new Map();
             for (const chain of supported) {
                 if (!chain.identifier)
@@ -51,10 +55,10 @@ export function httpVaultCoinsResolver(options = {}) {
     return {
         async coinsForVault(vaultId) {
             const [vaults, catalogue] = await Promise.all([
-                get(`/api/v2/vaults?vaultId=${encodeURIComponent(vaultId)}`),
+                get(`/api/v2/vaults?vaultId=${vaultId}`, () => api.getVaults(vaultId)),
                 chainRefs()
             ]);
-            const list = Array.isArray(vaults) ? vaults : [vaults];
+            const list = vaults;
             const vault = list.find(v => v.id === vaultId) ?? list[0];
             if (!vault)
                 throw new Error(`vault ${vaultId} not found`);

package/dist/src/sui-vaults/interfaces/index.d.ts

@@ -56,11 +56,34 @@ export interface ITxBuilderOptionalParams {
     txBlock?: TransactionBlock;
     gasBudget?: number;
     sender?: string;
+    /**
+     * Build the call against this package id instead of the deployment's.
+     *
+     * Guarded entry points abort unless invoked through the package whose
+     * compiled VERSION equals `ProtocolConfig.version`, so during an upgrade —
+     * new package published, version not yet increased — the callable package is
+     * the retired one, which no on-chain record names.
+     */
+    packageId?: string;
 }
 export interface IVaultOptionalParams extends ITxBuilderOptionalParams {
     dryRun?: boolean;
     returnTxb?: boolean;
 }
+/** `version` and the protocol-wide pause flag from the shared ProtocolConfig. */
+export interface IProtocolConfigState {
+    /** The package VERSION the protocol currently accepts, as a decimal string. */
+    version: string;
+    pauseNonAdminOperations: boolean;
+}
+/** Whether one package id can service a guarded call right now. */
+export interface IPackageSupportResult {
+    packageId: string;
+    /** True when this package's compiled VERSION equals `ProtocolConfig.version`. */
+    supported: boolean;
+    /** Abort or resolution reason when `supported` is false. */
+    reason?: string;
+}
 export interface ICancellationPendingWithdrawalRequest {
     sequence_number: NumStr;
     timestamp: NumStr;

package/dist/src/sui-vaults/on-chain-calls/admin.d.ts

@@ -1,8 +1,8 @@
 import { BaseClient as SuiClient } from "@mysten/sui/client";
 import { OnChainCalls } from "./onchain-calls.js";
-import { ISuiDeployment, IVaultOptionalParams } from "../interfaces/index.js";
+import { IPackageSupportResult, IProtocolConfigState, ISuiDeployment, IVaultOptionalParams } from "../interfaces/index.js";
 import { OnChainCallResponse, Signer, SuiAddress, SuiTransactionBlockResponseOptions } from "@firefly-exchange/library-sui";
-import { NumStr } from "@firefly-exchange/library-sui";
+import { Address, NumStr } from "@firefly-exchange/library-sui";
 export declare class AdminCalls extends OnChainCalls {
     constructor(_network: string, _suiClient: SuiClient, _deployment: ISuiDeployment, _signer?: Signer, _walletAddress?: string);
     /**
@@ -73,6 +73,61 @@ export declare class AdminCalls extends OnChainCalls {
      * @returns OnChainCallResponse
      */
     pauseNonAdminOperations(pause: boolean, options?: IVaultOptionalParams & SuiTransactionBlockResponseOptions): Promise<OnChainCallResponse>;
+    /**
+     * Guardian fast-path for pausing/unpausing all non-admin protocol operations.
+     * Needs no AdminCap — the signer must be the address `set_guardian` recorded.
+     *
+     * Only executes through the package whose compiled VERSION matches
+     * `ProtocolConfig.version`; pass `options.packageId` (see
+     * {@link getSupportedPackageId}) to route through a retired one while an
+     * upgrade is half-applied.
+     * @param pause True to pause non admin operations, false to resume
+     * @param options Optional tx execution params
+     * @returns OnChainCallResponse
+     */
+    guardianPauseNonAdminOperations(pause: boolean, options?: IVaultOptionalParams & SuiTransactionBlockResponseOptions): Promise<OnChainCallResponse>;
+    /**
+     * Set or clear the guardian address. AdminCap-gated.
+     * @param newGuardian The new guardian address, or the zero address to unset
+     * @param options Optional tx execution params
+     * @returns OnChainCallResponse
+     */
+    setGuardian(newGuardian: Address, options?: IVaultOptionalParams & SuiTransactionBlockResponseOptions): Promise<OnChainCallResponse>;
+    /** Reader for the shared ProtocolConfig; rebuilt per call so a deployment update is picked up. */
+    private protocolConfigReader;
+    /**
+     * Read `version` and `pause_non_admin_operations` off the shared ProtocolConfig.
+     * @returns The package VERSION the protocol accepts, and the protocol-wide pause flag
+     */
+    getProtocolConfigState(): Promise<IProtocolConfigState>;
+    /**
+     * Read the guardian address. See {@link SuiProtocolConfigReader.getGuardian} —
+     * it is a dynamic field, so it never shows up in the ProtocolConfig's contents,
+     * and an absent field reads as the zero address.
+     * @returns The guardian address, or the zero address when unset
+     */
+    getGuardian(): Promise<Address>;
+    /**
+     * Ask the chain whether a package id is the one the protocol currently accepts,
+     * by simulating `admin::verify_supported_package` against it.
+     *
+     * The compiled VERSION has no getter, so running the assert is the only way to
+     * find out. Simulated with checks disabled, so it needs no gas and no signer.
+     * @param packageId Package id to test; defaults to the deployment's
+     * @returns Whether the package is supported, and the abort reason when it is not
+     */
+    isPackageSupported(packageId?: string): Promise<IPackageSupportResult>;
+    /**
+     * First of `candidatePackageIds` that the protocol currently accepts, probed in
+     * order. Callers pass the deployment's package id followed by retired ones, so
+     * a half-applied upgrade still resolves to something callable.
+     * @param candidatePackageIds Package ids to probe, most-preferred first
+     * @returns The supported package id (null if none) and every probe result
+     */
+    getSupportedPackageId(candidatePackageIds?: string[]): Promise<{
+        supportedPackageId: string | null;
+        probes: IPackageSupportResult[];
+    }>;
     /**
      * Increase the protocol version
      * @param options Optional tx execution params

package/dist/src/sui-vaults/on-chain-calls/admin.js

@@ -1,5 +1,15 @@
 import { OnChainCalls } from "./onchain-calls.js";
+import { SUI_ZERO_ADDRESS, SuiProtocolConfigReader } from "./protocol-config-reader.js";
 import { TransactionBlock } from "@firefly-exchange/library-sui";
+/** Node resolution errors arrive percent-encoded. */
+const decodeReason = (message) => {
+    try {
+        return decodeURIComponent(message);
+    }
+    catch {
+        return message;
+    }
+};
 export class AdminCalls extends OnChainCalls {
     constructor(_network, _suiClient, _deployment, _signer, _walletAddress) {
         super(_network, _suiClient, _deployment, _signer, _walletAddress);
@@ -113,6 +123,116 @@ export class AdminCalls extends OnChainCalls {
         this.txBuilder.pauseNonAdminOperations(pause, { ...options, txBlock: txb });
         return this.execCall(txb, options);
     }
+    /**
+     * Guardian fast-path for pausing/unpausing all non-admin protocol operations.
+     * Needs no AdminCap — the signer must be the address `set_guardian` recorded.
+     *
+     * Only executes through the package whose compiled VERSION matches
+     * `ProtocolConfig.version`; pass `options.packageId` (see
+     * {@link getSupportedPackageId}) to route through a retired one while an
+     * upgrade is half-applied.
+     * @param pause True to pause non admin operations, false to resume
+     * @param options Optional tx execution params
+     * @returns OnChainCallResponse
+     */
+    async guardianPauseNonAdminOperations(pause, options) {
+        const txb = options?.txBlock || new TransactionBlock();
+        this.txBuilder.guardianPauseNonAdminOperations(pause, {
+            ...options,
+            txBlock: txb
+        });
+        return this.execCall(txb, options);
+    }
+    /**
+     * Set or clear the guardian address. AdminCap-gated.
+     * @param newGuardian The new guardian address, or the zero address to unset
+     * @param options Optional tx execution params
+     * @returns OnChainCallResponse
+     */
+    async setGuardian(newGuardian, options) {
+        const txb = options?.txBlock || new TransactionBlock();
+        this.txBuilder.setGuardian(newGuardian, { ...options, txBlock: txb });
+        return this.execCall(txb, options);
+    }
+    /** Reader for the shared ProtocolConfig; rebuilt per call so a deployment update is picked up. */
+    protocolConfigReader() {
+        return new SuiProtocolConfigReader(this.suiClient, this.parser.getProtocolConfig());
+    }
+    /**
+     * Read `version` and `pause_non_admin_operations` off the shared ProtocolConfig.
+     * @returns The package VERSION the protocol accepts, and the protocol-wide pause flag
+     */
+    async getProtocolConfigState() {
+        return this.protocolConfigReader().getProtocolConfigState();
+    }
+    /**
+     * Read the guardian address. See {@link SuiProtocolConfigReader.getGuardian} —
+     * it is a dynamic field, so it never shows up in the ProtocolConfig's contents,
+     * and an absent field reads as the zero address.
+     * @returns The guardian address, or the zero address when unset
+     */
+    async getGuardian() {
+        return this.protocolConfigReader().getGuardian();
+    }
+    /**
+     * Ask the chain whether a package id is the one the protocol currently accepts,
+     * by simulating `admin::verify_supported_package` against it.
+     *
+     * The compiled VERSION has no getter, so running the assert is the only way to
+     * find out. Simulated with checks disabled, so it needs no gas and no signer.
+     * @param packageId Package id to test; defaults to the deployment's
+     * @returns Whether the package is supported, and the abort reason when it is not
+     */
+    async isPackageSupported(packageId) {
+        const target = packageId || this.parser.getPackageId();
+        const txb = this.txBuilder.verifySupportedPackage({ packageId: target });
+        txb.setSender(SUI_ZERO_ADDRESS);
+        try {
+            const result = await this.suiClient.core.simulateTransaction({
+                transaction: txb,
+                checksEnabled: false
+            });
+            const simulated = result.Transaction ?? result.FailedTransaction;
+            const supported = result.$kind === "Transaction" &&
+                simulated?.status?.success === true;
+            return {
+                packageId: target,
+                supported,
+                reason: supported
+                    ? undefined
+                    : (simulated?.status?.error?.message ?? "unknown")
+            };
+        }
+        catch (error) {
+            // A package that predates the function fails at resolution rather than
+            // execution, and the node percent-encodes that message.
+            return {
+                packageId: target,
+                supported: false,
+                reason: decodeReason(error?.message ?? "unknown")
+            };
+        }
+    }
+    /**
+     * First of `candidatePackageIds` that the protocol currently accepts, probed in
+     * order. Callers pass the deployment's package id followed by retired ones, so
+     * a half-applied upgrade still resolves to something callable.
+     * @param candidatePackageIds Package ids to probe, most-preferred first
+     * @returns The supported package id (null if none) and every probe result
+     */
+    async getSupportedPackageId(candidatePackageIds) {
+        const candidates = candidatePackageIds && candidatePackageIds.length > 0
+            ? candidatePackageIds
+            : [this.parser.getPackageId()];
+        const probes = [];
+        for (const candidate of candidates) {
+            probes.push(await this.isPackageSupported(candidate));
+        }
+        return {
+            supportedPackageId: probes.find(p => p.supported)?.packageId ?? null,
+            probes
+        };
+    }
     /**
      * Increase the protocol version
      * @param options Optional tx execution params

package/dist/src/sui-vaults/on-chain-calls/index.d.ts

@@ -5,3 +5,4 @@ export * from "./vault-admin.js";
 export * from "./operator.js";
 export * from "./vault.js";
 export * from "./atomic-liquidity.js";
+export * from "./protocol-config-reader.js";

package/dist/src/sui-vaults/on-chain-calls/index.js

@@ -5,3 +5,4 @@ export * from "./vault-admin.js";
 export * from "./operator.js";
 export * from "./vault.js";
 export * from "./atomic-liquidity.js";
+export * from "./protocol-config-reader.js";

package/dist/src/sui-vaults/on-chain-calls/protocol-config-reader.d.ts

@@ -0,0 +1,24 @@
+import { BaseClient as SuiClient } from "@mysten/sui/client";
+import { IProtocolConfigState } from "../interfaces/index.js";
+/** The protocol's sentinel for "no guardian". */
+export declare const SUI_ZERO_ADDRESS: string;
+export declare class SuiProtocolConfigReader {
+    suiClient: SuiClient;
+    protocolConfigId: string;
+    constructor(_suiClient: SuiClient, _protocolConfigId: string);
+    /**
+     * Read `version` and `pause_non_admin_operations`.
+     * @returns The package VERSION the protocol accepts, and the protocol-wide pause flag
+     */
+    getProtocolConfigState(): Promise<IProtocolConfigState>;
+    /**
+     * Read the guardian address.
+     *
+     * The guardian is a dynamic field keyed by `b"guardian"`, not a struct field,
+     * so it never appears in the ProtocolConfig's contents. An absent field means
+     * the guardian was never set or has been cleared, which the protocol
+     * represents as the zero address.
+     * @returns The guardian address, or the zero address when unset
+     */
+    getGuardian(): Promise<string>;
+}

package/dist/src/sui-vaults/on-chain-calls/protocol-config-reader.js

@@ -0,0 +1,67 @@
+import { bcs } from "@mysten/sui/bcs";
+import { normalizeSuiAddress } from "@mysten/sui/utils";
+/** Matches `KEY_GUARDIAN` in `admin.move`. */
+const GUARDIAN_FIELD_KEY = "guardian";
+/** The protocol's sentinel for "no guardian". */
+export const SUI_ZERO_ADDRESS = normalizeSuiAddress("0x0");
+/** gRPC flattens Move structs; JSON-RPC keeps a `fields` wrapper. */
+const unwrapMoveFields = (value) => value?.fields ?? value;
+export class SuiProtocolConfigReader {
+    constructor(_suiClient, _protocolConfigId) {
+        this.suiClient = _suiClient;
+        this.protocolConfigId = _protocolConfigId;
+    }
+    /**
+     * Read `version` and `pause_non_admin_operations`.
+     * @returns The package VERSION the protocol accepts, and the protocol-wide pause flag
+     */
+    async getProtocolConfigState() {
+        const res = await this.suiClient.core.getObject({
+            objectId: this.protocolConfigId,
+            include: { json: true }
+        });
+        const fields = unwrapMoveFields(res.object?.json);
+        if (!fields || fields.version === undefined) {
+            throw new Error(`ProtocolConfig ${this.protocolConfigId} not found`);
+        }
+        return {
+            version: String(fields.version),
+            pauseNonAdminOperations: Boolean(fields.pause_non_admin_operations)
+        };
+    }
+    /**
+     * Read the guardian address.
+     *
+     * The guardian is a dynamic field keyed by `b"guardian"`, not a struct field,
+     * so it never appears in the ProtocolConfig's contents. An absent field means
+     * the guardian was never set or has been cleared, which the protocol
+     * represents as the zero address.
+     * @returns The guardian address, or the zero address when unset
+     */
+    async getGuardian() {
+        try {
+            const df = await this.suiClient.core.getDynamicField({
+                parentId: this.protocolConfigId,
+                name: {
+                    type: "vector<u8>",
+                    bcs: bcs
+                        .vector(bcs.u8())
+                        .serialize(new TextEncoder().encode(GUARDIAN_FIELD_KEY))
+                        .toBytes()
+                }
+            });
+            const fieldId = df?.dynamicField?.fieldId;
+            if (!fieldId)
+                return SUI_ZERO_ADDRESS;
+            const obj = await this.suiClient.core.getObject({
+                objectId: fieldId,
+                include: { json: true }
+            });
+            const value = unwrapMoveFields(obj.object?.json)?.value;
+            return value ? normalizeSuiAddress(String(value)) : SUI_ZERO_ADDRESS;
+        }
+        catch {
+            return SUI_ZERO_ADDRESS;
+        }
+    }
+}

package/dist/src/sui-vaults/on-chain-calls/tx-builder.d.ts

@@ -1,6 +1,6 @@
 import { SuiDeploymentParser } from "../utils/index.js";
 import { ISuiDeployment, ITxBuilderOptionalParams } from "../interfaces/index.js";
-import { NumStr, TransactionBlock } from "@firefly-exchange/library-sui";
+import { Address, NumStr, TransactionBlock } from "@firefly-exchange/library-sui";
 export declare class TxBuilder {
     parser: SuiDeploymentParser;
     constructor(_deployment: ISuiDeployment);
@@ -9,6 +9,13 @@ export declare class TxBuilder {
      * @param newDeployment The new deployment configuration
      */
     updateDeployment(newDeployment: ISuiDeployment): void;
+    /**
+     * Package id to build the call against: the caller's override when given,
+     * otherwise the deployment's. An override exists because a guarded call only
+     * executes through the package whose compiled VERSION matches
+     * `ProtocolConfig.version`, which is not always the newest one.
+     */
+    protected targetPackageId(options?: ITxBuilderOptionalParams): string;
     /**
      * Pauses or unpauses the non-admin operations
      * @param pause True if the non-admin operations should be paused, false otherwise
@@ -16,6 +23,40 @@ export declare class TxBuilder {
      * @returns TransactionBlock
      */
     pauseNonAdminOperations(pause: boolean, options?: ITxBuilderOptionalParams): TransactionBlock;
+    /**
+     * Guardian fast-path for pausing/unpausing all non-admin protocol operations.
+     * Callable directly by the guardian address — no AdminCap — and so the lever
+     * used during an incident.
+     *
+     * Aborts with EUnsupportedPackage (1000) unless it is invoked through the
+     * package whose compiled VERSION matches `ProtocolConfig.version`; pass
+     * `options.packageId` to route through a retired package while an upgrade is
+     * half-applied. See {@link verifySupportedPackage}.
+     * @param pause True to pause non admin operations, false to resume
+     * @param options Optional tx building params
+     * @returns TransactionBlock
+     */
+    guardianPauseNonAdminOperations(pause: boolean, options?: ITxBuilderOptionalParams): TransactionBlock;
+    /**
+     * Sets or clears the guardian address. AdminCap-gated. Pass the zero address
+     * to unset, which makes every guardian-gated entry point unreachable.
+     * @param newGuardian The new guardian address, or `0x0` to unset
+     * @param options Optional tx building params
+     * @returns TransactionBlock
+     */
+    setGuardian(newGuardian: Address, options?: ITxBuilderOptionalParams): TransactionBlock;
+    /**
+     * Asserts `ProtocolConfig.version` equals the VERSION compiled into the target
+     * package, aborting EUnsupportedPackage (1000) otherwise.
+     *
+     * On its own this changes nothing; it is built to be simulated. The compiled
+     * VERSION has no getter, so running this assert is the only way to ask whether
+     * a given package id is the one the protocol currently accepts — and it is the
+     * same check every guarded entry point performs first.
+     * @param options Optional tx building params; `packageId` selects the package to test
+     * @returns TransactionBlock
+     */
+    verifySupportedPackage(options?: ITxBuilderOptionalParams): TransactionBlock;
     /**
      * Increases the version of the protocol supported. Only admin can invoke this
      * @param options Optional tx building params

package/dist/src/sui-vaults/on-chain-calls/tx-builder.js

@@ -12,6 +12,15 @@ export class TxBuilder {
     updateDeployment(newDeployment) {
         this.parser.updateDeployment(newDeployment);
     }
+    /**
+     * Package id to build the call against: the caller's override when given,
+     * otherwise the deployment's. An override exists because a guarded call only
+     * executes through the package whose compiled VERSION matches
+     * `ProtocolConfig.version`, which is not always the newest one.
+     */
+    targetPackageId(options) {
+        return options?.packageId || this.parser.getPackageId();
+    }
     /**
      * Pauses or unpauses the non-admin operations
      * @param pause True if the non-admin operations should be paused, false otherwise
@@ -34,6 +43,80 @@ export class TxBuilder {
             txb.setSenderIfNotSet(options.sender);
         return txb;
     }
+    /**
+     * Guardian fast-path for pausing/unpausing all non-admin protocol operations.
+     * Callable directly by the guardian address — no AdminCap — and so the lever
+     * used during an incident.
+     *
+     * Aborts with EUnsupportedPackage (1000) unless it is invoked through the
+     * package whose compiled VERSION matches `ProtocolConfig.version`; pass
+     * `options.packageId` to route through a retired package while an upgrade is
+     * half-applied. See {@link verifySupportedPackage}.
+     * @param pause True to pause non admin operations, false to resume
+     * @param options Optional tx building params
+     * @returns TransactionBlock
+     */
+    guardianPauseNonAdminOperations(pause, options) {
+        const txb = options?.txBlock || new TransactionBlock();
+        txb.moveCall({
+            arguments: [
+                txb.object(this.parser.getProtocolConfig()),
+                txb.pure.bool(pause)
+            ],
+            target: `${this.targetPackageId(options)}::gateway::guardian_pause_non_admin_operations`
+        });
+        if (options?.gasBudget)
+            txb.setGasBudget(options.gasBudget);
+        if (options?.sender)
+            txb.setSenderIfNotSet(options.sender);
+        return txb;
+    }
+    /**
+     * Sets or clears the guardian address. AdminCap-gated. Pass the zero address
+     * to unset, which makes every guardian-gated entry point unreachable.
+     * @param newGuardian The new guardian address, or `0x0` to unset
+     * @param options Optional tx building params
+     * @returns TransactionBlock
+     */
+    setGuardian(newGuardian, options) {
+        const txb = options?.txBlock || new TransactionBlock();
+        txb.moveCall({
+            arguments: [
+                txb.object(this.parser.getProtocolConfig()),
+                txb.object(this.parser.getAdminCap()),
+                txb.pure.address(newGuardian)
+            ],
+            target: `${this.targetPackageId(options)}::gateway::set_guardian`
+        });
+        if (options?.gasBudget)
+            txb.setGasBudget(options.gasBudget);
+        if (options?.sender)
+            txb.setSenderIfNotSet(options.sender);
+        return txb;
+    }
+    /**
+     * Asserts `ProtocolConfig.version` equals the VERSION compiled into the target
+     * package, aborting EUnsupportedPackage (1000) otherwise.
+     *
+     * On its own this changes nothing; it is built to be simulated. The compiled
+     * VERSION has no getter, so running this assert is the only way to ask whether
+     * a given package id is the one the protocol currently accepts — and it is the
+     * same check every guarded entry point performs first.
+     * @param options Optional tx building params; `packageId` selects the package to test
+     * @returns TransactionBlock
+     */
+    verifySupportedPackage(options) {
+        const txb = options?.txBlock || new TransactionBlock();
+        txb.moveCall({
+            arguments: [txb.object(this.parser.getProtocolConfig())],
+            target: `${this.targetPackageId(options)}::admin::verify_supported_package`
+        });
+        if (options?.gasBudget)
+            txb.setGasBudget(options.gasBudget);
+        if (options?.sender)
+            txb.setSenderIfNotSet(options.sender);
+        return txb;
+    }
     /**
      * Increases the version of the protocol supported. Only admin can invoke this
      * @param options Optional tx building params

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@ember-finance/sdk",
     "description": "Ember Protocol SDK",
-    "version": "2.17.0",
+    "version": "2.19.0",
     "type": "module",
     "module": "./dist/index.js",
     "main": "./dist/index.js",