Integrator Guide¶

How to correctly consume Vault-K-NO through a 7540-compatible interface.

Rule 1: Do Not Use Request-Time Price as Payout Estimate¶

Do not use the share-to-asset conversion from requestRedeem as a reliable payout estimate. The actual USDC received is determined at keeper processing time using the quadratic curve and live NAV.

// WRONG — the redemption will not necessarily yield this amount
uint256 estimatedPayout = vault.sharePrice() * shares / 1e18;

// CORRECT — treat as unknown until WithdrawProcessed is observed
// Monitor the WithdrawProcessed event for the actual payout

If you need to display an estimate in a UI, clearly label it as an estimate and note it is subject to change based on fill level at processing time.

Rule 2: Monitor `WithdrawProcessed`, Not `claimableRedeemRequest`¶

For confirmation that a request has been fulfilled:

// Listen for:
event WithdrawProcessed(
    uint256 indexed requestId,
    address indexed receiver,
    uint256 payout,
    uint256 fee,
    uint256 avgExitPrice
);
// This is the authoritative confirmation of fulfillment with final amounts.

Do not poll claimableRedeemRequest() as the primary fulfillment signal.

Rule 3: Check Processability Before Queuing Large Redemptions¶

// Before submitting a large redemption request:
bool isLive     = !vault.paused();
uint256 capacity = vault.remainingDailyLiquidity();

// Note: capacity is a real-time proxy, not a guarantee.
// A large request may span multiple day windows.

Rule 4: Do Not Attempt Direct Fulfillment¶

The keeper is the sole authorized processor of the queue. Do not attempt to call processWithdrawals() from an integration — it will revert unless called from the permissioned keeper address.

Rule 5: Treat Exit Price as Unknown Until `WithdrawProcessed`¶

Request submitted → ... time passes ... → Keeper processes → WithdrawProcessed emitted
                    ↑                                          ↑
                    Price unknown                              Price known

Do not pre-compute or display a fixed redemption amount between request submission and WithdrawProcessed.

Recommended Interface Wrapper¶

A thin ERC-7540 wrapper contract over LiquidityVault is feasible and recommended for ecosystem compatibility.

Wrapper responsibilities: - Map 7540 function signatures to vault internal functions - Expose clear NatSpec documenting non-deterministic price semantics - Disclose all three points of divergence (price, capacity, keeper)

Wrapper does NOT require: - Changes to LiquidityVault, MarketAdapter, or HouseBuffer - Any vault logic modifications

The wrapper is a read/write forwarding layer only. Implementation is deferred to post-MVP.

NatSpec Template for Wrapper¶

/// @notice Submit a redemption request. Shares are locked until processed or cancelled.
/// @dev EXIT PRICE IS NON-DETERMINISTIC at request time. The actual USDC received
///      depends on: (1) aggregate market NAV at keeper processing time, (2) fill
///      position within the daily cap, (3) queue order. Monitor WithdrawProcessed
///      for the final payout. See ERC-7540 divergence documentation.
/// @param shares Number of vault shares to redeem
/// @param receiver Address to receive USDC payout
/// @param owner Must equal msg.sender (owner authorization not supported)
/// @return requestId Unique identifier for tracking and cancellation
function requestRedeem(
    uint256 shares,
    address receiver,
    address owner
) external returns (uint256 requestId);