@ember-finance/sdk 2.5.0 → 2.6.0-pre.0

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

@@ -162,4 +162,59 @@ export declare class EVMVaultAdminCalls extends EVMOnChainCalls {
      * @returns EvmOnChainCallResponse
      */
     updateVaultName(vaultAddress: string, newName: string, options?: IEvmCallOptions): Promise<EvmOnChainCallResponse>;
+    /** Atomic vault: set the external ERC-4626 strategy (address(0) to disable). Drain the old strategy first. */
+    setStrategy(vaultAddress: string, caller: string, newStrategy: string, options?: IEvmCallOptions): Promise<EvmOnChainCallResponse>;
+    /**
+     * Atomic vault: whitelist (or update) a source EmberShare with fee / capacity / holdback /
+     * utilization percentages, a per-swap minimum gross floor, and an absolute held-value cap.
+     *
+     * @param minSwapGross Minimum gross collateral value per swap (collateral units); 0 disables
+     *        the dust floor that would otherwise allow holdback-queue bloat.
+     * @param maxHeldValueAbsolute TVL-independent ceiling on this source share's post-swap held
+     *        value (collateral units); 0 disables it.
+     */
+    setEmberShareWhitelist(vaultAddress: string, caller: string, share: string, whitelisted: boolean, feePercentage: NumStr, maxCapacityPercentage: NumStr, holdbackPercentage: NumStr, maxUtilizationPercentage: NumStr, minSwapGross: NumStr, maxHeldValueAbsolute: NumStr, options?: IEvmCallOptions): Promise<EvmOnChainCallResponse>;
+    /** Atomic vault: set per-account swap waivers (fee and/or holdback); (false,false) removes them. */
+    setSwapWaiver(vaultAddress: string, caller: string, account: string, feeWaived: boolean, holdbackWaived: boolean, options?: IEvmCallOptions): Promise<EvmOnChainCallResponse>;
+    /**
+     * Atomic vault: add/update (remove=false) or remove (remove=true) a
+     * fee-multiplier curve tier for an EmberShare. `threshold` is a utilization
+     * percentage (1e18 = 100%); `multiplier` is a fee multiplier (1e18 = 1x, must
+     * be >= 1e18 on upsert). Admin only; routed through the protocol config.
+     */
+    updateEmberShareFeeMultiplierTier(vaultAddress: string, caller: string, share: string, threshold: NumStr, multiplier: NumStr, remove: boolean, options?: IEvmCallOptions): Promise<EvmOnChainCallResponse>;
+    /** Atomic vault: set the cumulative instant-withdraw cap (in shares). */
+    setMaxInstantWithdrawShares(vaultAddress: string, caller: string, newMax: NumStr, options?: IEvmCallOptions): Promise<EvmOnChainCallResponse>;
+    /** Atomic vault: set the instant-withdraw fee percentage. */
+    setInstantWithdrawFeePercentage(vaultAddress: string, caller: string, newFeePercentage: NumStr, options?: IEvmCallOptions): Promise<EvmOnChainCallResponse>;
+    /** Atomic vault: set the platform fee percentage. */
+    setFeePercentage(vaultAddress: string, caller: string, newFeePercentage: NumStr, options?: IEvmCallOptions): Promise<EvmOnChainCallResponse>;
+    /** Atomic vault: set the maximum TVL. */
+    setMaxTVL(vaultAddress: string, caller: string, newMaxTVL: NumStr, options?: IEvmCallOptions): Promise<EvmOnChainCallResponse>;
+    /** Atomic vault: set the minimum withdrawable shares. */
+    setMinWithdrawableShares(vaultAddress: string, caller: string, newMinWithdrawableShares: NumStr, options?: IEvmCallOptions): Promise<EvmOnChainCallResponse>;
+    /** Atomic vault: set the max rate change per update bound. */
+    setMaxRateChangePerUpdate(vaultAddress: string, caller: string, newMaxRateChangePerUpdate: NumStr, options?: IEvmCallOptions): Promise<EvmOnChainCallResponse>;
+    /** Atomic vault: set the minimum interval between rate updates (ms). */
+    setRateUpdateInterval(vaultAddress: string, caller: string, newInterval: NumStr, options?: IEvmCallOptions): Promise<EvmOnChainCallResponse>;
+    /** Atomic vault: rename the vault. */
+    setVaultName(vaultAddress: string, caller: string, newName: string, options?: IEvmCallOptions): Promise<EvmOnChainCallResponse>;
+    /** Atomic vault: set the vault validator contract. */
+    setVaultValidator(vaultAddress: string, caller: string, validator: string, options?: IEvmCallOptions): Promise<EvmOnChainCallResponse>;
+    /** Atomic vault: add/remove a sub-account. */
+    setSubAccountStatus(vaultAddress: string, caller: string, account: string, isSubAccount: boolean, options?: IEvmCallOptions): Promise<EvmOnChainCallResponse>;
+    /** Atomic vault: pause/unpause an operation ("deposits" | "withdrawals" | "privilegedOperations"). */
+    setPausedStatus(vaultAddress: string, caller: string, operation: string, paused: boolean, options?: IEvmCallOptions): Promise<EvmOnChainCallResponse>;
+    /** Atomic vault: rotate the admin role. */
+    setAdmin(vaultAddress: string, caller: string, newAdmin: string, options?: IEvmCallOptions): Promise<EvmOnChainCallResponse>;
+    /** Atomic vault: rotate the operator role. */
+    setOperator(vaultAddress: string, caller: string, newOperator: string, options?: IEvmCallOptions): Promise<EvmOnChainCallResponse>;
+    /** Atomic vault: rotate the rate-manager role. */
+    setRateManager(vaultAddress: string, caller: string, newRateManager: string, options?: IEvmCallOptions): Promise<EvmOnChainCallResponse>;
+    /** Atomic vault: transfer contract ownership (UUPS owner). */
+    transferOwnership(vaultAddress: string, newOwner: string, options?: IEvmCallOptions): Promise<EvmOnChainCallResponse>;
+    /** Atomic vault: renounce ownership (irreversible). */
+    renounceOwnership(vaultAddress: string, options?: IEvmCallOptions): Promise<EvmOnChainCallResponse>;
+    /** Atomic vault: upgrade the implementation and optionally call init data (UUPS). */
+    upgradeToAndCall(vaultAddress: string, newImplementation: string, data: string, options?: IEvmCallOptions): Promise<EvmOnChainCallResponse>;
 }

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

@@ -220,4 +220,126 @@ export class EVMVaultAdminCalls extends EVMOnChainCalls {
         const txCall = this.txBuilder.updateVaultName(vaultAddress, newName);
         return this.execCall(txCall, options);
     }
+    // ============================================
+    // Atomic Liquidity Vault — vault admin actions (BFE-817/818)
+    // Gated via protocol-config; pass the admin as `caller`.
+    // ============================================
+    /** Atomic vault: set the external ERC-4626 strategy (address(0) to disable). Drain the old strategy first. */
+    async setStrategy(vaultAddress, caller, newStrategy, options) {
+        const txCall = this.txBuilder.atomicSetStrategy(vaultAddress, caller, newStrategy);
+        return this.execCall(txCall, options);
+    }
+    /**
+     * Atomic vault: whitelist (or update) a source EmberShare with fee / capacity / holdback /
+     * utilization percentages, a per-swap minimum gross floor, and an absolute held-value cap.
+     *
+     * @param minSwapGross Minimum gross collateral value per swap (collateral units); 0 disables
+     *        the dust floor that would otherwise allow holdback-queue bloat.
+     * @param maxHeldValueAbsolute TVL-independent ceiling on this source share's post-swap held
+     *        value (collateral units); 0 disables it.
+     */
+    async setEmberShareWhitelist(vaultAddress, caller, share, whitelisted, feePercentage, maxCapacityPercentage, holdbackPercentage, maxUtilizationPercentage, minSwapGross, maxHeldValueAbsolute, options) {
+        const txCall = this.txBuilder.atomicSetEmberShareWhitelist(vaultAddress, caller, share, whitelisted, feePercentage, maxCapacityPercentage, holdbackPercentage, maxUtilizationPercentage, minSwapGross, maxHeldValueAbsolute);
+        return this.execCall(txCall, options);
+    }
+    /** Atomic vault: set per-account swap waivers (fee and/or holdback); (false,false) removes them. */
+    async setSwapWaiver(vaultAddress, caller, account, feeWaived, holdbackWaived, options) {
+        const txCall = this.txBuilder.atomicSetSwapWaiver(vaultAddress, caller, account, feeWaived, holdbackWaived);
+        return this.execCall(txCall, options);
+    }
+    /**
+     * Atomic vault: add/update (remove=false) or remove (remove=true) a
+     * fee-multiplier curve tier for an EmberShare. `threshold` is a utilization
+     * percentage (1e18 = 100%); `multiplier` is a fee multiplier (1e18 = 1x, must
+     * be >= 1e18 on upsert). Admin only; routed through the protocol config.
+     */
+    async updateEmberShareFeeMultiplierTier(vaultAddress, caller, share, threshold, multiplier, remove, options) {
+        const txCall = this.txBuilder.atomicUpdateEmberShareFeeMultiplierTier(vaultAddress, caller, share, threshold, multiplier, remove);
+        return this.execCall(txCall, options);
+    }
+    /** Atomic vault: set the cumulative instant-withdraw cap (in shares). */
+    async setMaxInstantWithdrawShares(vaultAddress, caller, newMax, options) {
+        const txCall = this.txBuilder.atomicSetMaxInstantWithdrawShares(vaultAddress, caller, newMax);
+        return this.execCall(txCall, options);
+    }
+    /** Atomic vault: set the instant-withdraw fee percentage. */
+    async setInstantWithdrawFeePercentage(vaultAddress, caller, newFeePercentage, options) {
+        const txCall = this.txBuilder.atomicSetInstantWithdrawFeePercentage(vaultAddress, caller, newFeePercentage);
+        return this.execCall(txCall, options);
+    }
+    /** Atomic vault: set the platform fee percentage. */
+    async setFeePercentage(vaultAddress, caller, newFeePercentage, options) {
+        const txCall = this.txBuilder.atomicSetFeePercentage(vaultAddress, caller, newFeePercentage);
+        return this.execCall(txCall, options);
+    }
+    /** Atomic vault: set the maximum TVL. */
+    async setMaxTVL(vaultAddress, caller, newMaxTVL, options) {
+        const txCall = this.txBuilder.atomicSetMaxTVL(vaultAddress, caller, newMaxTVL);
+        return this.execCall(txCall, options);
+    }
+    /** Atomic vault: set the minimum withdrawable shares. */
+    async setMinWithdrawableShares(vaultAddress, caller, newMinWithdrawableShares, options) {
+        const txCall = this.txBuilder.atomicSetMinWithdrawableShares(vaultAddress, caller, newMinWithdrawableShares);
+        return this.execCall(txCall, options);
+    }
+    /** Atomic vault: set the max rate change per update bound. */
+    async setMaxRateChangePerUpdate(vaultAddress, caller, newMaxRateChangePerUpdate, options) {
+        const txCall = this.txBuilder.atomicSetMaxRateChangePerUpdate(vaultAddress, caller, newMaxRateChangePerUpdate);
+        return this.execCall(txCall, options);
+    }
+    /** Atomic vault: set the minimum interval between rate updates (ms). */
+    async setRateUpdateInterval(vaultAddress, caller, newInterval, options) {
+        const txCall = this.txBuilder.atomicSetRateUpdateInterval(vaultAddress, caller, newInterval);
+        return this.execCall(txCall, options);
+    }
+    /** Atomic vault: rename the vault. */
+    async setVaultName(vaultAddress, caller, newName, options) {
+        const txCall = this.txBuilder.atomicSetVaultName(vaultAddress, caller, newName);
+        return this.execCall(txCall, options);
+    }
+    /** Atomic vault: set the vault validator contract. */
+    async setVaultValidator(vaultAddress, caller, validator, options) {
+        const txCall = this.txBuilder.atomicSetVaultValidator(vaultAddress, caller, validator);
+        return this.execCall(txCall, options);
+    }
+    /** Atomic vault: add/remove a sub-account. */
+    async setSubAccountStatus(vaultAddress, caller, account, isSubAccount, options) {
+        const txCall = this.txBuilder.atomicSetSubAccountStatus(vaultAddress, caller, account, isSubAccount);
+        return this.execCall(txCall, options);
+    }
+    /** Atomic vault: pause/unpause an operation ("deposits" | "withdrawals" | "privilegedOperations"). */
+    async setPausedStatus(vaultAddress, caller, operation, paused, options) {
+        const txCall = this.txBuilder.atomicSetPausedStatus(vaultAddress, caller, operation, paused);
+        return this.execCall(txCall, options);
+    }
+    /** Atomic vault: rotate the admin role. */
+    async setAdmin(vaultAddress, caller, newAdmin, options) {
+        const txCall = this.txBuilder.atomicSetAdmin(vaultAddress, caller, newAdmin);
+        return this.execCall(txCall, options);
+    }
+    /** Atomic vault: rotate the operator role. */
+    async setOperator(vaultAddress, caller, newOperator, options) {
+        const txCall = this.txBuilder.atomicSetOperator(vaultAddress, caller, newOperator);
+        return this.execCall(txCall, options);
+    }
+    /** Atomic vault: rotate the rate-manager role. */
+    async setRateManager(vaultAddress, caller, newRateManager, options) {
+        const txCall = this.txBuilder.atomicSetRateManager(vaultAddress, caller, newRateManager);
+        return this.execCall(txCall, options);
+    }
+    /** Atomic vault: transfer contract ownership (UUPS owner). */
+    async transferOwnership(vaultAddress, newOwner, options) {
+        const txCall = this.txBuilder.atomicTransferOwnership(vaultAddress, newOwner);
+        return this.execCall(txCall, options);
+    }
+    /** Atomic vault: renounce ownership (irreversible). */
+    async renounceOwnership(vaultAddress, options) {
+        const txCall = this.txBuilder.atomicRenounceOwnership(vaultAddress);
+        return this.execCall(txCall, options);
+    }
+    /** Atomic vault: upgrade the implementation and optionally call init data (UUPS). */
+    async upgradeToAndCall(vaultAddress, newImplementation, data, options) {
+        const txCall = this.txBuilder.atomicUpgradeToAndCall(vaultAddress, newImplementation, data);
+        return this.execCall(txCall, options);
+    }
 }

package/dist/src/evm-vaults/on-chain-calls/vault-reader.d.ts

@@ -275,6 +275,12 @@ export declare class EVMVaultReader {
      * @returns Total supply
      */
     getTotalSupply(vaultAddress: string, isETHVault?: boolean): Promise<bigint>;
+    /**
+     * Escrowed (deferred) ETH withdrawal claimable by `account` on an EmberETHVault —
+     * accrued when a withdrawal couldn't be sent (the receiver rejected the ETH transfer).
+     * Claim via `claimWithdrawal` / `claimWithdrawalFor`. Returns 0 if none. EmberETHVault only.
+     */
+    getUnclaimedWithdrawals(vaultAddress: string, account: string): Promise<bigint>;
     /**
      * Converts assets to shares
      * @param vaultAddress The vault address

package/dist/src/evm-vaults/on-chain-calls/vault-reader.js

@@ -275,6 +275,15 @@ export class EVMVaultReader {
         const vault = this.getVaultContract(vaultAddress, isETHVault);
         return vault.totalSupply();
     }
+    /**
+     * Escrowed (deferred) ETH withdrawal claimable by `account` on an EmberETHVault —
+     * accrued when a withdrawal couldn't be sent (the receiver rejected the ETH transfer).
+     * Claim via `claimWithdrawal` / `claimWithdrawalFor`. Returns 0 if none. EmberETHVault only.
+     */
+    async getUnclaimedWithdrawals(vaultAddress, account) {
+        const vault = this.getVaultContract(vaultAddress, true);
+        return vault.unclaimedWithdrawals(account);
+    }
     /**
      * Converts assets to shares
      * @param vaultAddress The vault address

package/dist/src/evm-vaults/utils/deployment-parser.d.ts

@@ -20,6 +20,14 @@ export declare class EVMDeploymentParser {
      * Gets the protocol config proxy address
      */
     getProtocolConfigAddress(): string | undefined;
+    /**
+     * Resolves the protocol config that governs a specific vault. Atomic Liquidity vaults can be
+     * deployed against their own protocol config (carried per-vault in the deployment), which may
+     * differ from the global one; admin ops for an atomic vault MUST route through that config.
+     * Falls back to the global protocol config for non-atomic vaults (and atomic vaults that don't
+     * specify one).
+     */
+    getProtocolConfigAddressForVault(vaultAddress: string): string | undefined;
     /**
      * Gets the protocol config implementation address
      */

package/dist/src/evm-vaults/utils/deployment-parser.js

@@ -27,6 +27,17 @@ export class EVMDeploymentParser {
     getProtocolConfigAddress() {
         return this.deployment.contracts?.protocolConfig.proxyAddress;
     }
+    /**
+     * Resolves the protocol config that governs a specific vault. Atomic Liquidity vaults can be
+     * deployed against their own protocol config (carried per-vault in the deployment), which may
+     * differ from the global one; admin ops for an atomic vault MUST route through that config.
+     * Falls back to the global protocol config for non-atomic vaults (and atomic vaults that don't
+     * specify one).
+     */
+    getProtocolConfigAddressForVault(vaultAddress) {
+        const atomic = Object.values(this.deployment.contracts?.atomicLiquidityVaults ?? {}).find(v => v.proxyAddress?.toLowerCase() === vaultAddress.toLowerCase());
+        return atomic?.protocolConfig ?? this.getProtocolConfigAddress();
+    }
     /**
      * Gets the protocol config implementation address
      */

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

@@ -29,6 +29,21 @@ export interface ISuiDeployment {
             DepositCoinDecimals: number;
         };
     };
+    AtomicVaults?: {
+        [key: string]: {
+            Admin?: Address;
+            Operator?: Address;
+            RateManager?: Address;
+            Name: string;
+            MaxRateChangePerUpdate?: string;
+            FeePercentage?: string;
+            MinWithdrawalShares?: string;
+            SubAccounts?: Address[];
+            ObjectId: Address;
+            CollateralCoinType: Address;
+            CollateralCoinDecimals: number;
+        };
+    };
 }
 export interface IDeploymentConfig {
     rpc: string;

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

@@ -1,6 +1,7 @@
+import { BaseClient as SuiClient } from "@mysten/sui/client";
 import { OnChainCalls } from "./onchain-calls.js";
 import { ISuiDeployment, IVaultOptionalParams } from "../interfaces/index.js";
-import { OnChainCallResponse, Signer, SuiAddress, SuiClient, SuiTransactionBlockResponseOptions } from "@firefly-exchange/library-sui";
+import { OnChainCallResponse, Signer, SuiAddress, SuiTransactionBlockResponseOptions } from "@firefly-exchange/library-sui";
 import { NumStr } from "@firefly-exchange/library-sui";
 export declare class AdminCalls extends OnChainCalls {
     constructor(_network: string, _suiClient: SuiClient, _deployment: ISuiDeployment, _signer?: Signer, _walletAddress?: string);
@@ -85,4 +86,39 @@ export declare class AdminCalls extends OnChainCalls {
      * @returns OnChainCallResponse
      */
     updateMaxRateInterval(maxRateInterval: NumStr, options?: IVaultOptionalParams & SuiTransactionBlockResponseOptions): Promise<OnChainCallResponse>;
+    /**
+     * Create and execute a create-atomic-vault transaction. Allows admin to
+     * create a new atomic liquidity vault on the protocol.
+     * @param collateralCoinType The type of the collateral coin (T)
+     * @param vaultName Name of the vault
+     * @param adminAddress The admin address of the vault
+     * @param operatorAddress The operator address of the vault
+     * @param rateManagerAddress The rate manager address of the vault
+     * @param maxRateChangePerUpdate The maximum rate change per update
+     * @param feePercentage The fee percentage
+     * @param minWithdrawalShares The minimum withdrawal shares
+     * @param rateUpdateInterval The rate update interval
+     * @param maxTVL The maximum TVL of the vault
+     * @param subAccounts The sub accounts of the vault
+     * @param options Optional tx execution params
+     * @returns OnChainCallResponse
+     */
+    createAtomicVault(collateralCoinType: string, vaultName: string, adminAddress: SuiAddress, operatorAddress: SuiAddress, rateManagerAddress: SuiAddress, maxRateChangePerUpdate: NumStr, feePercentage: NumStr, minWithdrawalShares: NumStr, rateUpdateInterval: NumStr, maxTVL: NumStr, subAccounts: SuiAddress[], options?: IVaultOptionalParams & SuiTransactionBlockResponseOptions): Promise<OnChainCallResponse>;
+    /**
+     * Change the admin address of an atomic vault
+     * @param vaultId The id of the atomic vault
+     * @param adminAddress The new admin address
+     * @param options Optional tx execution params
+     * @returns OnChainCallResponse
+     */
+    atomicChangeVaultAdmin(vaultId: string, adminAddress: SuiAddress, options?: IVaultOptionalParams & SuiTransactionBlockResponseOptions): Promise<OnChainCallResponse>;
+    /**
+     * Set / unset a blacklisted account on an atomic vault
+     * @param vaultId The id of the atomic vault
+     * @param account The account to set the blacklist status for
+     * @param status Whether the account should be blacklisted
+     * @param options Optional tx execution params
+     * @returns OnChainCallResponse
+     */
+    atomicSetBlacklistedAccount(vaultId: string, account: SuiAddress, status: boolean, options?: IVaultOptionalParams & SuiTransactionBlockResponseOptions): Promise<OnChainCallResponse>;
 }

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

@@ -137,4 +137,60 @@ export class AdminCalls extends OnChainCalls {
         });
         return this.execCall(txb, options);
     }
+    // ============================================================================
+    // Atomic Liquidity Vault (BFE-818) — protocol admin methods
+    // ============================================================================
+    /**
+     * Create and execute a create-atomic-vault transaction. Allows admin to
+     * create a new atomic liquidity vault on the protocol.
+     * @param collateralCoinType The type of the collateral coin (T)
+     * @param vaultName Name of the vault
+     * @param adminAddress The admin address of the vault
+     * @param operatorAddress The operator address of the vault
+     * @param rateManagerAddress The rate manager address of the vault
+     * @param maxRateChangePerUpdate The maximum rate change per update
+     * @param feePercentage The fee percentage
+     * @param minWithdrawalShares The minimum withdrawal shares
+     * @param rateUpdateInterval The rate update interval
+     * @param maxTVL The maximum TVL of the vault
+     * @param subAccounts The sub accounts of the vault
+     * @param options Optional tx execution params
+     * @returns OnChainCallResponse
+     */
+    async createAtomicVault(collateralCoinType, vaultName, adminAddress, operatorAddress, rateManagerAddress, maxRateChangePerUpdate, feePercentage, minWithdrawalShares, rateUpdateInterval, maxTVL, subAccounts, options) {
+        const txb = options?.txBlock || new TransactionBlock();
+        this.txBuilder.createAtomicVault(collateralCoinType, vaultName, adminAddress, operatorAddress, rateManagerAddress, maxRateChangePerUpdate, feePercentage, minWithdrawalShares, rateUpdateInterval, maxTVL, subAccounts, { ...options, txBlock: txb });
+        return this.execCall(txb, options);
+    }
+    /**
+     * Change the admin address of an atomic vault
+     * @param vaultId The id of the atomic vault
+     * @param adminAddress The new admin address
+     * @param options Optional tx execution params
+     * @returns OnChainCallResponse
+     */
+    async atomicChangeVaultAdmin(vaultId, adminAddress, options) {
+        const txb = options?.txBlock || new TransactionBlock();
+        this.txBuilder.atomicChangeVaultAdmin(vaultId, adminAddress, {
+            ...options,
+            txBlock: txb
+        });
+        return this.execCall(txb, options);
+    }
+    /**
+     * Set / unset a blacklisted account on an atomic vault
+     * @param vaultId The id of the atomic vault
+     * @param account The account to set the blacklist status for
+     * @param status Whether the account should be blacklisted
+     * @param options Optional tx execution params
+     * @returns OnChainCallResponse
+     */
+    async atomicSetBlacklistedAccount(vaultId, account, status, options) {
+        const txb = options?.txBlock || new TransactionBlock();
+        this.txBuilder.atomicSetBlacklistedAccount(vaultId, account, status, {
+            ...options,
+            txBlock: txb
+        });
+        return this.execCall(txb, options);
+    }
 }

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

@@ -0,0 +1,62 @@
+import { BaseClient as SuiClient } from "@mysten/sui/client";
+import { FeeMultiplierTier, InstantWithdrawQuote } from "../../atomic/instant-withdraw.js";
+/**
+ * Read-only views + instant-withdraw quotes for the Sui Atomic Liquidity Vault (BET-4111).
+ *
+ * There is no on-chain preview function and no off-chain view calls on Sui, so this reads
+ * the ALV (and source vault) object fields directly and replicates the Move math
+ * (`calculate_amount_from_shares`, `get_vault_tvl`, `swap_ember_shares`,
+ * `do_instant_withdraw_core`) via the shared chain-agnostic quote core at scale 1e9.
+ *
+ * @example
+ * ```ts
+ * const reader = new SuiAtomicLiquidityReader(suiClient);
+ * const q = await reader.previewSwapInstantWithdraw(vaultId, sourceVaultId, 100_000000n, owner);
+ * ```
+ */
+export declare class SuiAtomicLiquidityReader {
+    suiClient: SuiClient;
+    constructor(suiClient: SuiClient);
+    /** Raw Move fields of the AtomicLiquidityVault object. */
+    private vaultFields;
+    /**
+     * Read a `Table<K, V>` entry value. Table entries are plain dynamic fields, so we
+     * resolve the `Field<K,V>` object id via `getDynamicField`, then fetch its json
+     * (`{ name, value }`). Returns the unwrapped `value`, or null if absent.
+     */
+    private readTableValue;
+    /** Rate value (1e9) of any vault object (ALV or source EmberVault). */
+    private rateValue;
+    /** Per-source-share EmberShare config from the `ember_share_configs` table. */
+    getEmberShareConfig(vaultId: string, sourceVaultId: string): Promise<{
+        whitelisted: boolean;
+        feePercentage: bigint;
+        holdbackPercentage: bigint;
+        maxCapacityPercentage: bigint;
+        maxUtilizationPercentage: bigint;
+        epochStartedAt: bigint;
+        epochUsedAmount: bigint;
+        feeMultiplierCurve: FeeMultiplierTier[];
+    } | null>;
+    /** Caller's ALV (non-transferable) share balance from the `shares` table. */
+    shareOf(vaultId: string, account: string): Promise<bigint>;
+    /**
+     * Live quote for the EmberShare swap-with-holdback "instant withdraw" on Sui.
+     * Reads ALV + source vault fields and replicates `swap_ember_shares` math.
+     *
+     * `currentHeldValue` defaults to 0 (the common case before any swap); pass it when the
+     * ALV already custodies source shares. `availableCapacity` (remaining 24h epoch capacity,
+     * collateral units) is bfvs-sourced when precise epoch accounting is required — when
+     * omitted, only the utilization cap gates `withinCapacity`.
+     */
+    previewSwapInstantWithdraw(vaultId: string, sourceVaultId: string, shareAmount: bigint, owner: string, opts?: {
+        availableCapacity?: bigint;
+        currentHeldValue?: bigint;
+        userShareBalance?: bigint;
+    }): Promise<InstantWithdrawQuote>;
+    /**
+     * Live quote for the ALV's own plain `instant_withdraw` on Sui (atomic-share holders).
+     * `net = gross - fee`, no holdback, capped by `max_instant_withdraw_shares`.
+     */
+    previewPlainInstantWithdraw(vaultId: string, shareAmount: bigint, owner: string): Promise<InstantWithdrawQuote>;
+}

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

@@ -0,0 +1,174 @@
+import { bcs } from "@mysten/sui/bcs";
+import { computeSwapQuote, computePlainInstantQuote } from "../../atomic/instant-withdraw.js";
+/** Sui fixed-point scale (1e9) used by the Atomic Liquidity Vault Move math. */
+const SUI_SCALE = 1000000000n;
+const unwrapMoveFields = (value) => value?.fields ?? value;
+const toBig = (v) => v === undefined || v === null ? 0n : BigInt(v);
+/** `math::div(a, b)` = floor(a * scale / b). */
+const divFloor = (a, b) => (b === 0n ? 0n : (a * SUI_SCALE) / b);
+/** `math::div_ceil(a, b)` = ceil(a * scale / b) — used by `calculate_amount_from_shares`. */
+const divCeil = (a, b) => b === 0n ? 0n : (a * SUI_SCALE + (b - 1n)) / b;
+/**
+ * Read-only views + instant-withdraw quotes for the Sui Atomic Liquidity Vault (BET-4111).
+ *
+ * There is no on-chain preview function and no off-chain view calls on Sui, so this reads
+ * the ALV (and source vault) object fields directly and replicates the Move math
+ * (`calculate_amount_from_shares`, `get_vault_tvl`, `swap_ember_shares`,
+ * `do_instant_withdraw_core`) via the shared chain-agnostic quote core at scale 1e9.
+ *
+ * @example
+ * ```ts
+ * const reader = new SuiAtomicLiquidityReader(suiClient);
+ * const q = await reader.previewSwapInstantWithdraw(vaultId, sourceVaultId, 100_000000n, owner);
+ * ```
+ */
+export class SuiAtomicLiquidityReader {
+    constructor(suiClient) {
+        this.suiClient = suiClient;
+    }
+    /** Raw Move fields of the AtomicLiquidityVault object. */
+    async vaultFields(vaultId) {
+        const res = await this.suiClient.core.getObject({
+            objectId: vaultId,
+            include: { json: true }
+        });
+        const fields = unwrapMoveFields(res.object?.json);
+        if (!fields)
+            throw new Error(`Atomic vault ${vaultId} not found`);
+        return fields;
+    }
+    /**
+     * Read a `Table<K, V>` entry value. Table entries are plain dynamic fields, so we
+     * resolve the `Field<K,V>` object id via `getDynamicField`, then fetch its json
+     * (`{ name, value }`). Returns the unwrapped `value`, or null if absent.
+     */
+    async readTableValue(parentId, nameType, keyAddress) {
+        try {
+            const df = await this.suiClient.core.getDynamicField({
+                parentId,
+                name: { type: nameType, bcs: bcs.Address.serialize(keyAddress).toBytes() }
+            });
+            const fieldId = df?.dynamicField?.fieldId;
+            if (!fieldId)
+                return null;
+            const obj = await this.suiClient.core.getObject({
+                objectId: fieldId,
+                include: { json: true }
+            });
+            return unwrapMoveFields(obj.object?.json)?.value;
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Rate value (1e9) of any vault object (ALV or source EmberVault). */
+    async rateValue(vaultId) {
+        const res = await this.suiClient.core.getObject({
+            objectId: vaultId,
+            include: { json: true }
+        });
+        const fields = unwrapMoveFields(res.object?.json);
+        return toBig(unwrapMoveFields(fields?.rate)?.value);
+    }
+    /** Per-source-share EmberShare config from the `ember_share_configs` table. */
+    async getEmberShareConfig(vaultId, sourceVaultId) {
+        const fields = await this.vaultFields(vaultId);
+        const tableId = unwrapMoveFields(fields.ember_share_configs)?.id?.id;
+        if (!tableId)
+            return null;
+        {
+            const cfg = unwrapMoveFields(await this.readTableValue(tableId, "0x2::object::ID", sourceVaultId));
+            if (!cfg)
+                return null;
+            const curve = (cfg.fee_multiplier_curve || []).map((t) => {
+                const tf = unwrapMoveFields(t);
+                return {
+                    threshold: toBig(tf.threshold),
+                    multiplier: toBig(tf.multiplier)
+                };
+            });
+            return {
+                whitelisted: !!cfg.whitelisted,
+                feePercentage: toBig(cfg.fee_percentage),
+                holdbackPercentage: toBig(cfg.holdback_percentage),
+                maxCapacityPercentage: toBig(cfg.max_capacity_percentage),
+                maxUtilizationPercentage: toBig(cfg.max_utilization_percentage),
+                epochStartedAt: toBig(cfg.epoch_started_at),
+                epochUsedAmount: toBig(cfg.epoch_used_amount),
+                feeMultiplierCurve: curve
+            };
+        }
+    }
+    /** Caller's ALV (non-transferable) share balance from the `shares` table. */
+    async shareOf(vaultId, account) {
+        const fields = await this.vaultFields(vaultId);
+        const tableId = unwrapMoveFields(fields.shares)?.id?.id;
+        if (!tableId)
+            return 0n;
+        return toBig(await this.readTableValue(tableId, "address", account));
+    }
+    /**
+     * Live quote for the EmberShare swap-with-holdback "instant withdraw" on Sui.
+     * Reads ALV + source vault fields and replicates `swap_ember_shares` math.
+     *
+     * `currentHeldValue` defaults to 0 (the common case before any swap); pass it when the
+     * ALV already custodies source shares. `availableCapacity` (remaining 24h epoch capacity,
+     * collateral units) is bfvs-sourced when precise epoch accounting is required — when
+     * omitted, only the utilization cap gates `withinCapacity`.
+     */
+    async previewSwapInstantWithdraw(vaultId, sourceVaultId, shareAmount, owner, opts = {}) {
+        const fields = await this.vaultFields(vaultId);
+        const atomicRate = toBig(unwrapMoveFields(fields.rate)?.value);
+        const totalShares = toBig(fields.total_shares);
+        const feeWaived = fields.fee_waived_addresses || [];
+        const holdbackWaived = fields.holdback_waived_addresses || [];
+        const [config, sourceRate] = await Promise.all([
+            this.getEmberShareConfig(vaultId, sourceVaultId),
+            this.rateValue(sourceVaultId)
+        ]);
+        if (!config)
+            throw new Error(`source vault ${sourceVaultId} not whitelisted`);
+        // gross = calculate_amount_from_shares(source, shareAmount) = div_ceil(shares, sourceRate)
+        const grossAmount = divCeil(shareAmount, sourceRate);
+        // tvl = get_vault_tvl(atomic) = div(total_shares, atomicRate)
+        const vaultTotalAssets = divFloor(totalShares, atomicRate);
+        return computeSwapQuote({
+            scale: SUI_SCALE,
+            grossAmount,
+            shareAmount,
+            userShareBalance: opts.userShareBalance ?? 0n,
+            currentHeldValue: opts.currentHeldValue ?? 0n,
+            vaultTotalAssets,
+            // Default to "epoch capacity not binding" when not supplied; the on-chain
+            // swap still enforces it. Pass from bfvs for an exact pre-check.
+            availableCapacity: opts.availableCapacity ?? grossAmount,
+            config: {
+                feePercentage: config.feePercentage,
+                holdbackPercentage: config.holdbackPercentage,
+                maxUtilizationPercentage: config.maxUtilizationPercentage,
+                feeMultiplierCurve: config.feeMultiplierCurve
+            },
+            feeWaived: feeWaived.includes(owner),
+            holdbackWaived: holdbackWaived.includes(owner)
+        });
+    }
+    /**
+     * Live quote for the ALV's own plain `instant_withdraw` on Sui (atomic-share holders).
+     * `net = gross - fee`, no holdback, capped by `max_instant_withdraw_shares`.
+     */
+    async previewPlainInstantWithdraw(vaultId, shareAmount, owner) {
+        const fields = await this.vaultFields(vaultId);
+        const atomicRate = toBig(unwrapMoveFields(fields.rate)?.value);
+        const grossAmount = divCeil(shareAmount, atomicRate);
+        const userShareBalance = await this.shareOf(vaultId, owner);
+        return computePlainInstantQuote({
+            scale: SUI_SCALE,
+            grossAmount,
+            shareAmount,
+            userShareBalance,
+            instantWithdrawFeePercentage: toBig(fields.instant_withdraw_fee_percentage),
+            cumulativeInstantWithdrawShares: toBig(fields.cumulative_instant_withdraw_shares),
+            maxInstantWithdrawShares: toBig(fields.max_instant_withdraw_shares)
+        });
+    }
+}

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

@@ -4,3 +4,4 @@ export * from "./user.js";
 export * from "./vault-admin.js";
 export * from "./operator.js";
 export * from "./vault.js";
+export * from "./atomic-liquidity.js";

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

@@ -4,3 +4,4 @@ export * from "./user.js";
 export * from "./vault-admin.js";
 export * from "./operator.js";
 export * from "./vault.js";
+export * from "./atomic-liquidity.js";

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

@@ -1,4 +1,5 @@
-import { DryRunTransactionBlockResponse, OnChainCallResponse, Signer, SuiClient, SuiTransactionBlockResponse, SuiTransactionBlockResponseOptions, TransactionBlock } from "@firefly-exchange/library-sui";
+import { BaseClient as SuiClient } from "@mysten/sui/client";
+import { DryRunTransactionBlockResponse, OnChainCallResponse, Signer, SuiTransactionBlockResponse, SuiTransactionBlockResponseOptions, TransactionBlock } from "@firefly-exchange/library-sui";
 import { Address } from "@firefly-exchange/library-sui";
 import { SuiDeploymentParser } from "../utils/deployment-parser.js";
 import { ISuiDeployment, IVaultOptionalParams } from "../interfaces/index.js";