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

package/dist/src/atomic/instant-withdraw.js

@@ -0,0 +1,122 @@
+/**
+ * Chain-agnostic Atomic Liquidity Vault (ALV) instant-withdraw quote core (BET-4111).
+ *
+ * There is NO on-chain preview/quote function on the ALV, so the SDK computes the
+ * quote client-side by mirroring the exact contract math. Both chains use the same
+ * formulas with a different fixed-point scale, so this module is parameterised by
+ * `scale` (EVM = 1e18, Sui = 1e9) and consumed by both the EVM and Sui readers, which
+ * supply the live on-chain inputs (rate/TVL/held-value/config) via RPC.
+ *
+ * Mirrors:
+ *  - swap-with-holdback: EVM `AtomicLiquidityLib.swapEmberShares`,
+ *    Sui `atomic_liquidity_vault::swap_ember_shares`
+ *  - plain instant withdraw: EVM `AtomicLiquidity.instantWithdraw`,
+ *    Sui `do_instant_withdraw_core`
+ *  - fixed point: `Math.mul = (a*b)/scale`, `Math.div = (a*scale)/b` (floor)
+ *  - fee curve: `_lookupFeeMultiplier` (ascending tiers; highest threshold <= utilization wins; 1x default)
+ */
+/** Fixed-point multiply: `(a * b) / scale`, floor (matches Solidity/Move `Math.mul`). */
+export function mulFp(a, b, scale) {
+    if (a === 0n || b === 0n)
+        return 0n;
+    return (a * b) / scale;
+}
+/** Fixed-point divide: `(a * scale) / b`, floor (matches Solidity/Move `Math.div`). */
+export function divFp(a, b, scale) {
+    if (b === 0n)
+        return 0n;
+    return (a * scale) / b;
+}
+/**
+ * Resolve the fee multiplier from an ascending curve at a given utilization.
+ * Returns the multiplier of the highest tier whose `threshold <= utilization`, or `scale`
+ * (1x) when the curve is empty / no tier matches. Mirrors `_lookupFeeMultiplier`.
+ */
+export function lookupFeeMultiplier(curve, utilization, scale) {
+    let multiplier = scale; // 1x
+    for (const tier of curve) {
+        if (utilization >= tier.threshold) {
+            multiplier = tier.multiplier;
+        }
+        else {
+            break; // ascending: once utilization < threshold, all later tiers are higher
+        }
+    }
+    return multiplier;
+}
+/**
+ * Quote the EmberShare swap-with-holdback path (source tokenized vault -> ALV).
+ * Mirrors `swapEmberShares` exactly: post-swap utilization drives the fee multiplier,
+ * `net = gross - fee - holdback` is paid now, the holdback is queued for later release.
+ */
+export function computeSwapQuote(inputs) {
+    const { scale, grossAmount, config, feeWaived, holdbackWaived } = inputs;
+    const newHeldValue = inputs.currentHeldValue + grossAmount;
+    const utilizationAtSwap = inputs.vaultTotalAssets === 0n
+        ? 0n
+        : divFp(newHeldValue, inputs.vaultTotalAssets, scale);
+    const feeMultiplier = lookupFeeMultiplier(config.feeMultiplierCurve, utilizationAtSwap, scale);
+    const effectiveFeePercentage = mulFp(config.feePercentage, feeMultiplier, scale);
+    const feeAmount = feeWaived ? 0n : mulFp(grossAmount, effectiveFeePercentage, scale);
+    const holdbackAmount = holdbackWaived
+        ? 0n
+        : mulFp(grossAmount, config.holdbackPercentage, scale);
+    // Mirror the contract's underflow guard.
+    const instantlyReceive = feeAmount + holdbackAmount > grossAmount
+        ? 0n
+        : grossAmount - feeAmount - holdbackAmount;
+    const withinUtilization = utilizationAtSwap <= config.maxUtilizationPercentage;
+    const withinEpochCapacity = grossAmount <= inputs.availableCapacity;
+    // Absolute held-value cap (0/undefined disables it); mirrors EmberShareHeldValueCapExceeded.
+    const maxHeldValueAbsolute = config.maxHeldValueAbsolute ?? 0n;
+    const withinHeldValueCap = maxHeldValueAbsolute === 0n || newHeldValue <= maxHeldValueAbsolute;
+    // Per-swap dust floor (0/undefined disables it); mirrors SwapAmountTooSmall.
+    const minSwapGross = config.minSwapGross ?? 0n;
+    const belowMinSwap = minSwapGross > 0n && grossAmount < minSwapGross;
+    return {
+        grossAmount,
+        instantlyReceive,
+        lockedAmount: holdbackAmount,
+        feeAmount,
+        effectiveFeePercentage,
+        holdbackPercentage: holdbackWaived ? 0n : config.holdbackPercentage,
+        utilizationAtSwap,
+        resultingShares: inputs.userShareBalance >= inputs.shareAmount
+            ? inputs.userShareBalance - inputs.shareAmount
+            : 0n,
+        belowMinSwap,
+        withinHeldValueCap,
+        withinCapacity: withinUtilization &&
+            withinEpochCapacity &&
+            withinHeldValueCap &&
+            !belowMinSwap &&
+            feeAmount + holdbackAmount <= grossAmount
+    };
+}
+/**
+ * Quote the ALV's own plain `instantWithdraw` path (atomic-share holders).
+ * Mirrors the contract: `net = gross - fee`, no holdback; capped by
+ * `cumulative + shares <= maxInstantWithdrawShares`.
+ */
+export function computePlainInstantQuote(inputs) {
+    const { scale, grossAmount, shareAmount } = inputs;
+    const feeAmount = mulFp(grossAmount, inputs.instantWithdrawFeePercentage, scale);
+    const instantlyReceive = feeAmount > grossAmount ? 0n : grossAmount - feeAmount;
+    const withinCapacity = inputs.cumulativeInstantWithdrawShares + shareAmount <=
+        inputs.maxInstantWithdrawShares;
+    return {
+        grossAmount,
+        instantlyReceive,
+        lockedAmount: 0n,
+        feeAmount,
+        effectiveFeePercentage: inputs.instantWithdrawFeePercentage,
+        holdbackPercentage: 0n,
+        utilizationAtSwap: 0n,
+        resultingShares: inputs.userShareBalance >= shareAmount
+            ? inputs.userShareBalance - shareAmount
+            : 0n,
+        belowMinSwap: false,
+        withinHeldValueCap: true,
+        withinCapacity
+    };
+}

package/dist/src/ember-vaults.d.ts

@@ -1,4 +1,5 @@
-import { Signer as SuiSigner, SuiClient } from "@firefly-exchange/library-sui";
+import { Signer as SuiSigner } from "@firefly-exchange/library-sui";
+import { BaseClient as SuiClient } from "@mysten/sui/client";
 import { Signer as EvmSigner, Provider as EvmProvider } from "ethers";
 import { ISuiDeployment } from "./sui-vaults/interfaces/index.js";
 import { TxBuilder as SuiTxBuilder } from "./sui-vaults/on-chain-calls/index.js";

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

@@ -0,0 +1,98 @@
+import { Provider } from "ethers";
+import { FeeMultiplierTier, InstantWithdrawQuote } from "../../atomic/instant-withdraw.js";
+/**
+ * Read-only views for the Atomic Liquidity Vault (BFE-817/818).
+ *
+ * Write calls live on the role classes (EVMUserCalls.instantWithdraw /
+ * swapEmberShares, EVMOperatorCalls.supplyToStrategy / withdrawFromStrategy /
+ * redeemCollectedEmberShares / releaseUsersHoldback, EVMVaultAdminCalls.setStrategy /
+ * setEmberShareWhitelist / setSwapWaiver / setMaxInstantWithdrawShares /
+ * setInstantWithdrawFeePercentage). Shared lifecycle calls (deposit, redeemShares,
+ * cancelPendingWithdrawalRequest, processWithdrawalRequests, collectPlatformFee,
+ * updateVaultRate, pause/role/cap setters) reuse the existing EmberVault methods on
+ * those same classes.
+ *
+ * This reader uses an ethers Contract against the bundled AtomicLiquidity ABI and
+ * provides typed convenience getters plus a generic `read` for any view not covered.
+ *
+ * @example
+ * ```typescript
+ * const reader = new EVMAtomicLiquidityReader(provider);
+ * const rate = await reader.rate(vault);
+ * const supplied = await reader.getStrategyAssets(vault);
+ * const cfg = await reader.read(vault, "emberShareConfigs", [sourceShare]);
+ * ```
+ */
+export declare class EVMAtomicLiquidityReader {
+    provider: Provider;
+    constructor(_provider: Provider);
+    private contract;
+    /** A source EmberShare vault (ERC-4626) for read-only convertToAssets/balanceOf/accounts. */
+    private shareContract;
+    /** Generic view call for any function on the AtomicLiquidity ABI. */
+    read(vaultAddress: string, functionName: string, args?: unknown[]): Promise<unknown>;
+    /** roles() -> { admin, operator, rateManager }. */
+    roles(vaultAddress: string): Promise<unknown>;
+    /** rate() -> { value, maxRateChangePerUpdate, rateUpdateInterval, lastUpdatedAt }. */
+    rate(vaultAddress: string): Promise<unknown>;
+    /** Current external strategy address (zero if none). */
+    strategy(vaultAddress: string): Promise<string>;
+    /** Assets currently supplied to the strategy. */
+    getStrategyAssets(vaultAddress: string): Promise<bigint>;
+    /** Total assets (idle + strategy + outstanding). */
+    totalAssets(vaultAddress: string): Promise<bigint>;
+    /**
+     * Solvency margin (collateral units, signed): `totalAssets - totalLiabilities`. Negative
+     * means the vault is under-collateralised. Monitoring view added with the audit fixes.
+     */
+    solvencyMargin(vaultAddress: string): Promise<bigint>;
+    /** Total non-transferable shares in circulation. */
+    totalShares(vaultAddress: string): Promise<bigint>;
+    /** Non-transferable share balance of `account`. */
+    shareOf(vaultAddress: string, account: string): Promise<bigint>;
+    /** Cumulative instant-withdraw shares used. */
+    cumulativeInstantWithdrawShares(vaultAddress: string): Promise<bigint>;
+    /** Configured instant-withdraw cap (shares). */
+    maxInstantWithdrawShares(vaultAddress: string): Promise<bigint>;
+    /** Remaining instant-withdraw headroom (shares). */
+    availableInstantWithdrawShares(vaultAddress: string): Promise<bigint>;
+    /** Per-source-share swap config. */
+    emberShareConfigs(vaultAddress: string, share: string): Promise<unknown>;
+    /** Remaining swap capacity for a source share in the current epoch. */
+    availableEmberShareCapacity(vaultAddress: string, share: string): Promise<bigint>;
+    /** Length of the holdback FIFO for a source share. */
+    getHoldbackQueueLength(vaultAddress: string, share: string): Promise<bigint>;
+    /**
+     * Escrowed (deferred) holdback collateral claimable by `account` — accrued when a
+     * holdback payout couldn't be transferred to it during `releaseUsersHoldback` (e.g. a
+     * token-level blocklist). Claim via user `claimHoldback` / `claimHoldbackFor`. 0 if none.
+     */
+    unclaimedHoldback(vaultAddress: string, account: string): Promise<bigint>;
+    /** Whether `operation` ("deposits" | "withdrawals" | "privilegedOperations") is paused. */
+    pauseStatus(vaultAddress: string, operation: string): Promise<boolean>;
+    /** Per-account state (shares + pending withdrawals). */
+    getAccountState(vaultAddress: string, account: string): Promise<unknown>;
+    /** Convert a share amount to assets at the current rate. */
+    convertToAssets(vaultAddress: string, shares: bigint): Promise<bigint>;
+    /** Convert an asset amount to shares at the current rate. */
+    convertToShares(vaultAddress: string, assets: bigint): Promise<bigint>;
+    /** Contract version string. */
+    version(vaultAddress: string): Promise<string>;
+    /**
+     * Live quote for the EmberShare swap-with-holdback "instant withdraw": a holder of a
+     * source vault's shares (`share`) swaps `shareAmount` into this ALV, receiving most of
+     * the value instantly with a small % held back for later operator release.
+     *
+     * All dynamic inputs (rate, TVL, held value, epoch capacity, waivers) are read live via
+     * RPC. The fee-multiplier curve has no on-chain getter (the public `emberShareConfigs`
+     * getter omits the dynamic array), so pass it from bfvs `instantWithdrawConfig`; an empty
+     * curve means a 1x multiplier (matches the contract default).
+     */
+    previewSwapInstantWithdraw(vaultAddress: string, share: string, shareAmount: bigint, owner: string, feeMultiplierCurve?: FeeMultiplierTier[]): Promise<InstantWithdrawQuote>;
+    /**
+     * Live quote for the ALV's own plain `instantWithdraw` (atomic-share holders): burn
+     * `shareAmount` ALV shares for `gross - fee`, no holdback, capped by
+     * `maxInstantWithdrawShares`. All inputs read live via RPC.
+     */
+    previewPlainInstantWithdraw(vaultAddress: string, shareAmount: bigint, owner: string): Promise<InstantWithdrawQuote>;
+}

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

@@ -0,0 +1,212 @@
+import { Contract } from "ethers";
+import AtomicLiquidityABI from "../../abis/AtomicLiquidity.json" with { type: "json" };
+import EmberVaultABI from "../../abis/EmberVault.json" with { type: "json" };
+import { computeSwapQuote, computePlainInstantQuote } from "../../atomic/instant-withdraw.js";
+/** EVM fixed-point scale (1e18) used by the AtomicLiquidity contract math. */
+const EVM_SCALE = 10n ** 18n;
+/**
+ * Read-only views for the Atomic Liquidity Vault (BFE-817/818).
+ *
+ * Write calls live on the role classes (EVMUserCalls.instantWithdraw /
+ * swapEmberShares, EVMOperatorCalls.supplyToStrategy / withdrawFromStrategy /
+ * redeemCollectedEmberShares / releaseUsersHoldback, EVMVaultAdminCalls.setStrategy /
+ * setEmberShareWhitelist / setSwapWaiver / setMaxInstantWithdrawShares /
+ * setInstantWithdrawFeePercentage). Shared lifecycle calls (deposit, redeemShares,
+ * cancelPendingWithdrawalRequest, processWithdrawalRequests, collectPlatformFee,
+ * updateVaultRate, pause/role/cap setters) reuse the existing EmberVault methods on
+ * those same classes.
+ *
+ * This reader uses an ethers Contract against the bundled AtomicLiquidity ABI and
+ * provides typed convenience getters plus a generic `read` for any view not covered.
+ *
+ * @example
+ * ```typescript
+ * const reader = new EVMAtomicLiquidityReader(provider);
+ * const rate = await reader.rate(vault);
+ * const supplied = await reader.getStrategyAssets(vault);
+ * const cfg = await reader.read(vault, "emberShareConfigs", [sourceShare]);
+ * ```
+ */
+export class EVMAtomicLiquidityReader {
+    constructor(_provider) {
+        this.provider = _provider;
+    }
+    contract(vaultAddress) {
+        return new Contract(vaultAddress, AtomicLiquidityABI.abi, this.provider);
+    }
+    /** A source EmberShare vault (ERC-4626) for read-only convertToAssets/balanceOf/accounts. */
+    shareContract(share) {
+        return new Contract(share, EmberVaultABI.abi, this.provider);
+    }
+    /** Generic view call for any function on the AtomicLiquidity ABI. */
+    async read(vaultAddress, functionName, args = []) {
+        return this.contract(vaultAddress)[functionName](...args);
+    }
+    /** roles() -> { admin, operator, rateManager }. */
+    async roles(vaultAddress) {
+        return this.contract(vaultAddress).roles();
+    }
+    /** rate() -> { value, maxRateChangePerUpdate, rateUpdateInterval, lastUpdatedAt }. */
+    async rate(vaultAddress) {
+        return this.contract(vaultAddress).rate();
+    }
+    /** Current external strategy address (zero if none). */
+    async strategy(vaultAddress) {
+        return this.contract(vaultAddress).strategy();
+    }
+    /** Assets currently supplied to the strategy. */
+    async getStrategyAssets(vaultAddress) {
+        return this.contract(vaultAddress).getStrategyAssets();
+    }
+    /** Total assets (idle + strategy + outstanding). */
+    async totalAssets(vaultAddress) {
+        return this.contract(vaultAddress).totalAssets();
+    }
+    /**
+     * Solvency margin (collateral units, signed): `totalAssets - totalLiabilities`. Negative
+     * means the vault is under-collateralised. Monitoring view added with the audit fixes.
+     */
+    async solvencyMargin(vaultAddress) {
+        return this.contract(vaultAddress).solvencyMargin();
+    }
+    /** Total non-transferable shares in circulation. */
+    async totalShares(vaultAddress) {
+        return this.contract(vaultAddress).totalShares();
+    }
+    /** Non-transferable share balance of `account`. */
+    async shareOf(vaultAddress, account) {
+        return this.contract(vaultAddress).shareOf(account);
+    }
+    /** Cumulative instant-withdraw shares used. */
+    async cumulativeInstantWithdrawShares(vaultAddress) {
+        return this.contract(vaultAddress).cumulativeInstantWithdrawShares();
+    }
+    /** Configured instant-withdraw cap (shares). */
+    async maxInstantWithdrawShares(vaultAddress) {
+        return this.contract(vaultAddress).maxInstantWithdrawShares();
+    }
+    /** Remaining instant-withdraw headroom (shares). */
+    async availableInstantWithdrawShares(vaultAddress) {
+        return this.contract(vaultAddress).availableInstantWithdrawShares();
+    }
+    /** Per-source-share swap config. */
+    async emberShareConfigs(vaultAddress, share) {
+        return this.contract(vaultAddress).emberShareConfigs(share);
+    }
+    /** Remaining swap capacity for a source share in the current epoch. */
+    async availableEmberShareCapacity(vaultAddress, share) {
+        return this.contract(vaultAddress).availableEmberShareCapacity(share);
+    }
+    /** Length of the holdback FIFO for a source share. */
+    async getHoldbackQueueLength(vaultAddress, share) {
+        return this.contract(vaultAddress).getHoldbackQueueLength(share);
+    }
+    /**
+     * Escrowed (deferred) holdback collateral claimable by `account` — accrued when a
+     * holdback payout couldn't be transferred to it during `releaseUsersHoldback` (e.g. a
+     * token-level blocklist). Claim via user `claimHoldback` / `claimHoldbackFor`. 0 if none.
+     */
+    async unclaimedHoldback(vaultAddress, account) {
+        return this.contract(vaultAddress).unclaimedHoldback(account);
+    }
+    /** Whether `operation` ("deposits" | "withdrawals" | "privilegedOperations") is paused. */
+    async pauseStatus(vaultAddress, operation) {
+        return this.contract(vaultAddress).pauseStatus(operation);
+    }
+    /** Per-account state (shares + pending withdrawals). */
+    async getAccountState(vaultAddress, account) {
+        return this.contract(vaultAddress).getAccountState(account);
+    }
+    /** Convert a share amount to assets at the current rate. */
+    async convertToAssets(vaultAddress, shares) {
+        return this.contract(vaultAddress).convertToAssets(shares);
+    }
+    /** Convert an asset amount to shares at the current rate. */
+    async convertToShares(vaultAddress, assets) {
+        return this.contract(vaultAddress).convertToShares(assets);
+    }
+    /** Contract version string. */
+    async version(vaultAddress) {
+        return this.contract(vaultAddress).version();
+    }
+    /**
+     * Live quote for the EmberShare swap-with-holdback "instant withdraw": a holder of a
+     * source vault's shares (`share`) swaps `shareAmount` into this ALV, receiving most of
+     * the value instantly with a small % held back for later operator release.
+     *
+     * All dynamic inputs (rate, TVL, held value, epoch capacity, waivers) are read live via
+     * RPC. The fee-multiplier curve has no on-chain getter (the public `emberShareConfigs`
+     * getter omits the dynamic array), so pass it from bfvs `instantWithdrawConfig`; an empty
+     * curve means a 1x multiplier (matches the contract default).
+     */
+    async previewSwapInstantWithdraw(vaultAddress, share, shareAmount, owner, feeMultiplierCurve = []) {
+        const vault = this.contract(vaultAddress);
+        const src = this.shareContract(share);
+        const [grossAmount, cfg, vaultTotalAssets, availableCapacity, custodied, hasRedemption, feeWaived, holdbackWaived, userShareBalance] = await Promise.all([
+            src.convertToAssets(shareAmount),
+            vault.emberShareConfigs(share),
+            vault.totalAssets(),
+            vault.availableEmberShareCapacity(share),
+            src.balanceOf(vaultAddress),
+            vault.hasActiveRedemptionHistory(),
+            vault.feeWaivedAddresses(owner),
+            vault.holdbackWaivedAddresses(owner),
+            src.balanceOf(owner)
+        ]);
+        // currentHeldValue mirrors _heldShareValueInCollateral: custodied + pending
+        // (pending only when the ALV has an active redemption history), valued via the
+        // source vault's convertToAssets.
+        let heldShares = custodied;
+        if (hasRedemption) {
+            // EmberVault.accounts(address) has a single uint256 output
+            // (totalPendingWithdrawalShares); ethers v6 returns the bare bigint for
+            // single-output calls, not a named struct.
+            const pendingWithdrawalShares = (await src.accounts(vaultAddress));
+            heldShares += pendingWithdrawalShares;
+        }
+        const currentHeldValue = heldShares === 0n ? 0n : (await src.convertToAssets(heldShares));
+        return computeSwapQuote({
+            scale: EVM_SCALE,
+            grossAmount,
+            shareAmount,
+            userShareBalance,
+            currentHeldValue,
+            vaultTotalAssets,
+            availableCapacity,
+            config: {
+                feePercentage: cfg.feePercentage,
+                holdbackPercentage: cfg.holdbackPercentage,
+                maxUtilizationPercentage: cfg.maxUtilizationPercentage,
+                minSwapGross: cfg.minSwapGross,
+                maxHeldValueAbsolute: cfg.maxHeldValueAbsolute,
+                feeMultiplierCurve
+            },
+            feeWaived,
+            holdbackWaived
+        });
+    }
+    /**
+     * Live quote for the ALV's own plain `instantWithdraw` (atomic-share holders): burn
+     * `shareAmount` ALV shares for `gross - fee`, no holdback, capped by
+     * `maxInstantWithdrawShares`. All inputs read live via RPC.
+     */
+    async previewPlainInstantWithdraw(vaultAddress, shareAmount, owner) {
+        const vault = this.contract(vaultAddress);
+        const [grossAmount, instantWithdrawFeePercentage, cumulativeInstantWithdrawShares, maxInstantWithdrawShares, userShareBalance] = await Promise.all([
+            vault.convertToAssets(shareAmount),
+            vault.instantWithdrawFeePercentage(),
+            vault.cumulativeInstantWithdrawShares(),
+            vault.maxInstantWithdrawShares(),
+            vault.shareOf(owner)
+        ]);
+        return computePlainInstantQuote({
+            scale: EVM_SCALE,
+            grossAmount,
+            shareAmount,
+            userShareBalance,
+            instantWithdrawFeePercentage,
+            cumulativeInstantWithdrawShares,
+            maxInstantWithdrawShares
+        });
+    }
+}

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

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

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

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

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

@@ -99,4 +99,14 @@ export declare class EVMOperatorCalls extends EVMOnChainCalls {
      * @returns EvmOnChainCallResponse
      */
     setDepositAllowList(vaultAddress: string, user: string, status: boolean, options?: IEvmCallOptions): Promise<EvmOnChainCallResponse>;
+    /** Atomic vault: supply `assets` of idle collateral into the external ERC-4626 strategy. */
+    supplyToStrategy(vaultAddress: string, assets: NumStr, options?: IEvmCallOptions): Promise<EvmOnChainCallResponse>;
+    /** Atomic vault: withdraw `assets` of collateral back from the strategy into the vault. */
+    withdrawFromStrategy(vaultAddress: string, assets: NumStr, options?: IEvmCallOptions): Promise<EvmOnChainCallResponse>;
+    /** Atomic vault: submit `amount` of collected source `share` for redemption on the source vault. */
+    redeemCollectedEmberShares(vaultAddress: string, share: string, amount: NumStr, options?: IEvmCallOptions): Promise<EvmOnChainCallResponse>;
+    /** Atomic vault: release the holdback FIFO for `share` at `unwindingPercentage` (1e18=100%), up to `maxEntries`. */
+    releaseUsersHoldback(vaultAddress: string, share: string, unwindingPercentage: NumStr, maxEntries: NumStr, options?: IEvmCallOptions): Promise<EvmOnChainCallResponse>;
+    /** Atomic vault: move `amount` of collateral to a registered sub-account. */
+    supplyToSubAccount(vaultAddress: string, subAccount: string, amount: NumStr, options?: IEvmCallOptions): Promise<EvmOnChainCallResponse>;
 }

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

@@ -136,4 +136,32 @@ export class EVMOperatorCalls extends EVMOnChainCalls {
         const txCall = this.txBuilder.setVaultDepositAllowList(vaultAddress, user, status);
         return this.execCall(txCall, options);
     }
+    // ============================================
+    // Atomic Liquidity Vault — operator actions (BFE-817/818)
+    // ============================================
+    /** Atomic vault: supply `assets` of idle collateral into the external ERC-4626 strategy. */
+    async supplyToStrategy(vaultAddress, assets, options) {
+        const txCall = this.txBuilder.atomicSupplyToStrategy(vaultAddress, assets);
+        return this.execCall(txCall, options);
+    }
+    /** Atomic vault: withdraw `assets` of collateral back from the strategy into the vault. */
+    async withdrawFromStrategy(vaultAddress, assets, options) {
+        const txCall = this.txBuilder.atomicWithdrawFromStrategy(vaultAddress, assets);
+        return this.execCall(txCall, options);
+    }
+    /** Atomic vault: submit `amount` of collected source `share` for redemption on the source vault. */
+    async redeemCollectedEmberShares(vaultAddress, share, amount, options) {
+        const txCall = this.txBuilder.atomicRedeemCollectedEmberShares(vaultAddress, share, amount);
+        return this.execCall(txCall, options);
+    }
+    /** Atomic vault: release the holdback FIFO for `share` at `unwindingPercentage` (1e18=100%), up to `maxEntries`. */
+    async releaseUsersHoldback(vaultAddress, share, unwindingPercentage, maxEntries, options) {
+        const txCall = this.txBuilder.atomicReleaseUsersHoldback(vaultAddress, share, unwindingPercentage, maxEntries);
+        return this.execCall(txCall, options);
+    }
+    /** Atomic vault: move `amount` of collateral to a registered sub-account. */
+    async supplyToSubAccount(vaultAddress, subAccount, amount, options) {
+        const txCall = this.txBuilder.atomicSupplyToSubAccount(vaultAddress, subAccount, amount);
+        return this.execCall(txCall, options);
+    }
 }

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

@@ -280,6 +280,27 @@ export declare class EVMTxBuilder {
      * @returns Transaction call object
      */
     collectPlatformFee(vaultAddress: string, isETHVault?: boolean): ITransactionCall;
+    /**
+     * EmberETHVault: claim the caller's own escrowed (deferred) ETH withdrawal — accrued
+     * when a withdrawal couldn't be sent (receiver rejected the transfer). EmberETHVault only.
+     */
+    claimWithdrawal(vaultAddress: string): ITransactionCall;
+    /**
+     * EmberETHVault: deliver `receiver`'s escrowed ETH withdrawal on their behalf
+     * (permissionless — funds can only go to `receiver`). EmberETHVault only.
+     */
+    claimWithdrawalFor(vaultAddress: string, receiver: string): ITransactionCall;
+    /**
+     * EmberETHVault: redirect the CALLER's own escrowed ETH withdrawal to `to`. For a
+     * receiver that can transact but can no longer receive ETH; delivers only the
+     * caller's own escrow. EmberETHVault only.
+     */
+    claimWithdrawalTo(vaultAddress: string, to: string): ITransactionCall;
+    /**
+     * EmberETHVault: owner recovery of `receiver`'s escrowed ETH to `to` (a permanently
+     * unpayable receiver). Owner-only (called directly on the vault). EmberETHVault only.
+     */
+    recoverUnclaimedWithdrawal(vaultAddress: string, receiver: string, to: string): ITransactionCall;
     /**
      * Withdraws assets from the vault without redeeming shares (operator only)
      * Used by operators to move funds to sub-accounts for strategy execution
@@ -501,4 +522,92 @@ export declare class EVMTxBuilder {
      * @returns Transaction call object
      */
     bridgeSend(adapterAddress: string, sendParam: IOFTSendParam, fee: IOFTMessagingFee, refundAddress: string): ITransactionCall;
+    private atomicCall;
+    /** Claim the caller's own escrowed (deferred) holdback collateral. */
+    atomicClaimHoldback(vaultAddress: string): ITransactionCall;
+    /** Deliver `recipient`'s escrowed holdback on their behalf (permissionless). */
+    atomicClaimHoldbackFor(vaultAddress: string, recipient: string): ITransactionCall;
+    /**
+     * Redirect the CALLER's own escrowed holdback to `to`. For a recipient that can
+     * transact but can no longer receive the collateral token (e.g. token blacklist);
+     * moves only the caller's own escrow.
+     */
+    atomicClaimHoldbackTo(vaultAddress: string, to: string): ITransactionCall;
+    /**
+     * Owner recovery of `recipient`'s escrowed holdback to `to` (a permanently unpayable
+     * recipient). Owner-only, called directly on the vault (not via protocol config).
+     */
+    atomicRecoverUnclaimedHoldback(vaultAddress: string, recipient: string, to: string): ITransactionCall;
+    /**
+     * Builds an atomic-vault ADMIN call routed through the vault's protocol config. Atomic admin
+     * setters are `onlyProtocolConfig`, so they must be invoked on the EmberProtocolConfig (which
+     * forwards msg.sender as `caller`) — never on the vault directly. Targets the vault's OWN
+     * protocol config (atomic vaults may use a config distinct from the global one). Each config
+     * forwarder takes the vault address as its first argument and derives `caller` from msg.sender.
+     */
+    private atomicConfigCall;
+    /** Instant (capped, fee'd) withdraw of `shares` to `receiver`; auto-pulls from strategy. */
+    atomicInstantWithdraw(vaultAddress: string, shares: NumStr, receiver: string): ITransactionCall;
+    /** Swap `shareAmount` of a whitelisted source EmberShare into this vault's collateral. */
+    atomicSwapEmberShares(vaultAddress: string, share: string, shareAmount: NumStr, receiver: string): ITransactionCall;
+    /** Supply `assets` of idle collateral into the external ERC-4626 strategy. */
+    atomicSupplyToStrategy(vaultAddress: string, assets: NumStr): ITransactionCall;
+    /** Withdraw `assets` of collateral back from the strategy into the vault. */
+    atomicWithdrawFromStrategy(vaultAddress: string, assets: NumStr): ITransactionCall;
+    /** Submit `amount` of collected source `share` for redemption on the source EmberVault. */
+    atomicRedeemCollectedEmberShares(vaultAddress: string, share: string, amount: NumStr): ITransactionCall;
+    /** Release the holdback FIFO for `share` at `unwindingPercentage` (1e18 = 100%), up to `maxEntries`. */
+    atomicReleaseUsersHoldback(vaultAddress: string, share: string, unwindingPercentage: NumStr, maxEntries: NumStr): ITransactionCall;
+    /** Set the external ERC-4626 strategy (address(0) to disable). Drain the old strategy first. */
+    atomicSetStrategy(vaultAddress: string, _caller: string, newStrategy: string): ITransactionCall;
+    /**
+     * Whitelist (or update) a source EmberShare with fee / capacity / holdback / utilization
+     * percentages, a per-swap minimum gross floor (`minSwapGross`, 0 disables), and a
+     * TVL-independent absolute held-value cap (`maxHeldValueAbsolute`, 0 disables).
+     */
+    atomicSetEmberShareWhitelist(vaultAddress: string, _caller: string, share: string, whitelisted: boolean, feePercentage: NumStr, maxCapacityPercentage: NumStr, holdbackPercentage: NumStr, maxUtilizationPercentage: NumStr, minSwapGross: NumStr, maxHeldValueAbsolute: NumStr): ITransactionCall;
+    /** Set per-account swap waivers (fee and/or holdback); (false,false) removes them. */
+    atomicSetSwapWaiver(vaultAddress: string, _caller: string, account: string, feeWaived: boolean, holdbackWaived: boolean): ITransactionCall;
+    /**
+     * 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).
+     */
+    atomicUpdateEmberShareFeeMultiplierTier(vaultAddress: string, _caller: string, share: string, threshold: NumStr, multiplier: NumStr, remove: boolean): ITransactionCall;
+    /** Set the cumulative instant-withdraw cap (in shares). */
+    atomicSetMaxInstantWithdrawShares(vaultAddress: string, _caller: string, newMax: NumStr): ITransactionCall;
+    /** Set the instant-withdraw fee percentage. */
+    atomicSetInstantWithdrawFeePercentage(vaultAddress: string, _caller: string, newFeePercentage: NumStr): ITransactionCall;
+    /** Set the platform fee percentage. */
+    atomicSetFeePercentage(vaultAddress: string, _caller: string, newFeePercentage: NumStr): ITransactionCall;
+    /** Set the maximum TVL. */
+    atomicSetMaxTVL(vaultAddress: string, _caller: string, newMaxTVL: NumStr): ITransactionCall;
+    /** Set the minimum withdrawable shares. */
+    atomicSetMinWithdrawableShares(vaultAddress: string, _caller: string, newMinWithdrawableShares: NumStr): ITransactionCall;
+    /** Set the max rate change per update bound. */
+    atomicSetMaxRateChangePerUpdate(vaultAddress: string, _caller: string, newMaxRateChangePerUpdate: NumStr): ITransactionCall;
+    /** Set the minimum interval between rate updates (ms). */
+    atomicSetRateUpdateInterval(vaultAddress: string, _caller: string, newInterval: NumStr): ITransactionCall;
+    /** Rename the vault. */
+    atomicSetVaultName(vaultAddress: string, _caller: string, newName: string): ITransactionCall;
+    /** Set the vault validator contract. */
+    atomicSetVaultValidator(vaultAddress: string, _caller: string, validator: string): ITransactionCall;
+    /** Add/remove a sub-account. */
+    atomicSetSubAccountStatus(vaultAddress: string, _caller: string, account: string, isSubAccount: boolean): ITransactionCall;
+    /** Pause/unpause one operation ("deposits" | "withdrawals" | "privilegedOperations"). */
+    atomicSetPausedStatus(vaultAddress: string, _caller: string, operation: string, paused: boolean): ITransactionCall;
+    /** Move `amount` of collateral to a registered sub-account (operator). */
+    atomicSupplyToSubAccount(vaultAddress: string, subAccount: string, amount: NumStr): ITransactionCall;
+    /** Rotate the admin role. */
+    atomicSetAdmin(vaultAddress: string, _caller: string, newAdmin: string): ITransactionCall;
+    /** Rotate the operator role. */
+    atomicSetOperator(vaultAddress: string, _caller: string, newOperator: string): ITransactionCall;
+    /** Rotate the rate-manager role. */
+    atomicSetRateManager(vaultAddress: string, _caller: string, newRateManager: string): ITransactionCall;
+    /** Transfer contract ownership (UUPS owner). */
+    atomicTransferOwnership(vaultAddress: string, newOwner: string): ITransactionCall;
+    /** Renounce ownership (irreversible). */
+    atomicRenounceOwnership(vaultAddress: string): ITransactionCall;
+    /** Upgrade the implementation and optionally call init data (UUPS). */
+    atomicUpgradeToAndCall(vaultAddress: string, newImplementation: string, data: string): ITransactionCall;
 }