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

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

@@ -0,0 +1,209 @@
+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) {
+            const pending = (await src.accounts(vaultAddress));
+            heldShares += pending.totalPendingWithdrawalShares;
+        }
+        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,86 @@ 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;
+    /** 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;
 }