Redeem covered shares

Redeeming covered shares stops coverage and returns the underlying yield-vault shares to the user. On redemption settlement, coverage ceases for the redeemed portion and the vault shares become available. The onchain 24-hour exit guarantee allows permissionless settlement if the keeper does not settle in time.

The code snippets on this page use Smokehouse USDC as a concrete example: the user redeems OC-bbqUSDC covered shares and receives bbqUSDC yield-vault shares in return.

Request a redemption

requestRedeem submits an asynchronous redemption request to stop coverage and redeem yield-vault shares.

function requestRedeem(uint256 shares, address controller, address owner)
    external returns (uint256 requestId);

Parameters

Name	Type	Description
shares	uint256	Amount of covered shares to redeem (e.g. OC-bbqUSDC).
controller	address	Controller for the resulting yield-vault shares (user wallet).
owner	address	Owner of the covered shares being redeemed (user wallet).

Returns

Name	Type	Description
requestId	uint256	Unique request ID for this redemption.

Example

// Redeem all covered shares (OC-bbqUSDC) for the deposited asset (bbqUSDC).
uint256 shares = metavault.balanceOf(msg.sender);
uint256 reqId = metavault.requestRedeem(shares, msg.sender, msg.sender);

Notes

• Each call to requestRedeem returns a unique requestId. Unlike deposits, redemptions are not controller-aggregated.

• The covered shares are locked in the Insured Vault on request and continue to be insured until settlement.

• owner must equal msg.sender.

• Only authorized bundlers may set controller != owner to operate on behalf of another user.

Cancel a redemption request

cancelRedeemRequest cancels a pending redemption request and refunds the covered shares synchronously in a single transaction.

function cancelRedeemRequest(uint256 requestId, address controller, address receiver)
    external returns (uint256 shares);

Parameters

Name	Type	Description
requestId	uint256	Unique request ID from requestRedeem.
controller	address	Controller whose pending request to cancel (user wallet).
receiver	address	Recipient of the refunded covered shares.

Returns

Name	Type	Description
shares	uint256	Covered share amount refunded.

Example

// Cancel the redemption request and receive OC-bbqUSDC back immediately.
metavault.cancelRedeemRequest(reqId, msg.sender, msg.sender);

Track pending redemption

pendingRedeemRequest returns the covered share amount still pending settlement for a given request.

function pendingRedeemRequest(uint256 requestId, address controller)
    external view returns (uint256 pendingShares);

Parameters

Name	Type	Description
requestId	uint256	Unique request identifier from requestRedeem.
controller	address	Controller (user wallet) to query.

Returns

Name	Type	Description
pendingShares	uint256	Covered shares pending settlement.

Example

uint256 sharesPending = metavault.pendingRedeemRequest(reqId, msg.sender);

Settlement

Pending redemption requests are settled typically within 2 Ethereum blocks (~30 seconds). During settlement, the covered shares are burned, coverage ends for the redeemed portion, and the corresponding bbqUSDC vault shares are earmarked for the controller. The assets then need to be delivered to the user's wallet via one of two paths:

Keeper push

This is the default and preferred UX.

The keeper calls pushRedeemAssets to deliver the settled bbqUSDC directly to the user's wallet.

User claim

Alternatively, the user can claim settled redemptions themselves. Use claimableRedeemRequest to check the settled amount, then call redeem or withdraw to claim.

claimableRedeemRequest returns the settled share amount for a specific request.

function claimableRedeemRequest(uint256 requestId, address controller)
    external view returns (uint256 claimableShares);

Parameters

Name	Type	Description
requestId	uint256	Unique request identifier from requestRedeem.
controller	address	Controller (user wallet) to query.

Returns

Name	Type	Description
claimableShares	uint256	Settled covered share amount for this request.

Example

uint256 sharesClaimable = metavault.claimableRedeemRequest(reqId, msg.sender);

Caveat: claimableRedeemRequest returns the original settled amount for the request. It does not decrease after the request is claimed (either via the Keeper push or user claim), because claims are tracked at the controller-aggregate level, not per-request. To check the actual remaining claimable shares across all requests, use claimableRedeemShares(controller) instead:

uint256 remainingClaimable = metavault.claimableRedeemShares(msg.sender);

Claim by shares

redeem claims yield-vault shares from settled redemption requests by specifying the covered share amount to burn.

function redeem(uint256 shares, address receiver, address controller)
    external returns (uint256 assets);

Parameters

Name	Type	Description
shares	uint256	Amount of settled covered shares to burn.
receiver	address	Recipient of the yield-vault shares.
controller	address	Controller authorized to claim (user wallet).

Returns

Name	Type	Description
assets	uint256	Yield-vault shares withdrawn.

Example

// Redeem settled covered shares for bbqUSDC.
metavault.redeem(sharesClaimable, msg.sender, msg.sender);

Claim by assets

withdraw claims an exact amount of yield-vault shares from settled redemption requests.

function withdraw(uint256 assets, address receiver, address controller)
    external returns (uint256 shares);

Parameters

Name	Type	Description
assets	uint256	Exact amount of yield-vault shares to withdraw.
receiver	address	Recipient of the yield-vault shares.
controller	address	Controller authorized to claim (user wallet).

Returns

Name	Type	Description
shares	uint256	Covered shares burned.

Example

// Withdraw an exact amount of bbqUSDC.
metavault.withdraw(5_000e18, msg.sender, msg.sender);

24-hour exit guarantee

settleMaturedRedemption provides an onchain exit guarantee. If a redemption request has not been settled by the keeper within 24 hours, anyone may call this function to settle it permissionlessly.

function settleMaturedRedemption(uint256 requestId) external;

Parameters

Name	Type	Description
requestId	uint256	Matured redemption request ID to settle.

Once settled, the controller can claim the yield-vault shares via redeem or withdraw.

Example

// After 24 hours, settle the matured redemption request.
metavault.settleMaturedRedemption(reqId);

// Then claim the yield-vault shares.
uint256 sharesClaimable = metavault.claimableRedeemRequest(reqId, controller);
metavault.redeem(sharesClaimable, controller, controller);