@ember-finance/sdk 2.17.0 → 2.18.0

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.18.0",
     "type": "module",
     "module": "./dist/index.js",
     "main": "./dist/index.js",