Redemption Book

Book for redemption logic.

General Description

The Redemption Book contains all the logic for the redemption lifecycle, accepting orders in Security Tokens and settling them in Settlement Tokens. Redemptions follow a lifecycle of order creation, confirmation, locking, and finally settlement. These first three steps can be done by investors (or by dealers/admins on their behalf) aggregately or separately, according to the instrument's configuration. Settlement is done by admins for multiple orders at once, burning security tokens and minting the corresponding settlement tokens to investors, while sending some to the KAIO Treasury as a fee. Certain restrictions on the redemption order lifecycle are enforced by modules applying specific rules and conditions.

Redemption Creation

Orders are first created by investors or dealers, signaling interest in redeeming the security tokens for an instrument. In order to settle this order, it must additionally be confirmed and locked. This may happen over separate transactions or in a single one, depending on how the given instrument is configured.

Investor Order Creation

  • Function: investorCreateOrder(uint256 _amount, uint256 _lockingHint)

  • Purpose: Allows investors to create redemption orders, indicating the amount of security tokens they intend to lock.

  • Parameters:

    • uint256 _amount: The amount of security tokens for the order.

    • _lockingHint: Hint of a nearby order Id to make locking more efficient. Can be ignored by using 0.

  • Validation Checks:

    • Ensures the caller is an investor allowed to perform the order creation for the amount of security tokens by the allowlist modules.

    • Checks that the amount of tokens is not zero.

    • Verifies the result of the checkCreateRedemption() function for relevant modules in the rules engine.

  • Behavior:

    • Creates and stores the initial order values.

    • Emits an OrderCreated event, signaling the order has been created.

  • Return Values:

    • uint256 orderId: The Id of the newly created order.

  • Example:

    investorCreateOrder(1000, 0);

Dealer Order Creation

  • Function: dealerCreateOrder(uint256 _amount, bytes32 _investorId, address _beneficiary, address _investorWallet, uint256 _lockingHint)

  • Purpose: Allows dealers to create redemptions orders on behalf of investors, indicating the amount of security tokens they intend to lock.

  • Parameters:

    • uint256 _amount: The amount of security tokens for the order.

    • bytes32 _investorId: The Id of the investor the order is created for.

    • address _beneficiary: Address that will receive the security tokens once the order is settled.

    • address _investorWallet: Wallet belonging to the investor to take security tokens from when locking.

    • _lockingHint: Hint of a nearby order Id to make locking more efficient. Can be ignored by using 0.

  • Validation Checks:

    • Ensures the caller is the investor's dealer.

    • Makes sure that the beneficiary is a wallet belonging to the investor.

    • Checks that the amount of tokens is not zero.

    • Ensures the investor is allowed to perform the order creation for the amount of security tokens by the allowlist modules.

    • Verifies the result of the checkAdvisedCreateRedemption() function for relevant modules in the rules engine.

  • Behavior:

    • Creates and stores the initial order values.

    • Emits an OrderCreated event, signaling the order has been created.

  • Return Values:

    • uint256 orderId: The Id of the newly created order.

  • Example:

Redemption Confirmation

After orders are created, they can then be confirmed. Investors or dealers attest to carrying out the created order, though at this step it may still be cancelled. In order to settle this order, it must additionally be locked. This may happen over separate transactions or in a single one, depending on how the given instrument is configured.

Investor Order Confirmation

  • Function: investorConfirmOrder(uint256 _orderId, uint256 _lockingHint)

  • Purpose: Allows investors to confirm an already created redemption order.

  • Parameters:

    • uint256 _orderId: The Id of the order.

    • _lockingHint: Hint of a nearby order Id to make locking more efficient. Can be ignored by using 0.

  • Validation Checks:

    • Checks that the caller is the investor that the order belongs to.

    • Ensures the investor is allowed to perform the order confirmation for the amount of security tokens by the allowlist modules.

    • Makes sure the order is not already confirmed and is available.

    • Verifies the result of the checkRedemptionConfirmation() function for relevant modules in the rules engine.

  • Behavior:

    • Marks the order as confirmed.

    • Registers the investor's participation in the redemption process

    • Emits an OrderConfirmed event, signaling the order has been confirmed.

  • Example:

Dealer Order Confirmation

  • Function: dealerConfirmOrder(uint256 _orderId, address _investorWallet, uint256 _lockingHint)

  • Purpose: Allows dealers to confirm an already created redemption order on behalf of an investor.

  • Parameters:

    • uint256 _orderId: The Id of the order.

    • address _investorWallet: Wallet belonging to the investor to take security tokens from when locking.

    • _lockingHint: Hint of a nearby order Id to make locking more efficient. Can be ignored by using 0.

  • Validation Checks:

    • Ensures the caller is the investor's dealer.

    • Ensures the investor is allowed to perform the order confirmation for the amount of security tokens by the allowlist modules.

    • Makes sure the order is not already confirmed and is available.

    • Verifies the result of the checkAdvisedRedemptionConfirmation() function for relevant modules in the rules engine.

  • Behavior:

    • Marks the order as confirmed.

    • Registers the investor's participation in the redemption process

    • Emits an OrderConfirmed event, signaling the order has been confirmed.

  • Example:

Redemption Locking

Investors, dealers, or admins can lock orders after they have been confirmed. For an order to be locked, the required security tokens are transferred into the redemption book. Once the order is locked, it is ready to be settled, and sent into the settlement queue.

Investor Order Locking

  • Function: investorLockTokens(uint256 _orderId, uint256 _lockingHint)

  • Purpose: Allows investors to lock in a confirmed order, locking the required security tokens in the process.

  • Parameters:

    • uint256 _orderId: The Id of the order.

    • _lockingHint: Hint of a nearby order Id to make locking more efficient. Can be ignored by using 0.

  • Validation Checks:

    • Checks that the caller is the investor that the order belongs to.

    • Ensures the investor is allowed to lock the order for the amount of security tokens by the allowlist modules.

    • Makes sure the order is already confirmed and is available.

    • Verifies the result of the checkLockRedemption() function for relevant modules in the rules engine.

  • Behavior:

    • Marks the order as not available (locked).

    • Inserts the order in the list of orders pending settlement.

    • Locks the required amount of security tokens in the redemption book.

    • Emits an OrderLocked event, signaling the order has been locked.

  • Example:

Dealer Order Locking

  • Function: dealerLockTokens(uint256 _orderId, address _investorWallet, uint256 _lockingHint)

  • Purpose: Allows dealers to to lock in a confirmed order on behalf of an investor, locking the required security tokens in the process.

  • Parameters:

    • uint256 _orderId: The Id of the order.

    • address _investorWallet: Wallet belonging to the investor to take security tokens from when locking.

    • _lockingHint: Hint of a nearby order Id to make locking more efficient. Can be ignored by using 0.

  • Validation Checks:

    • Ensures the caller is the investor's dealer.

    • Ensures the investor is allowed to lock the order for the amount of security tokens by the allowlist modules.

    • Makes sure the order is already confirmed and is available.

    • Verifies the result of the checkAdvisedLockRedemption() function for relevant modules in the rules engine.

  • Behavior:

    • Marks the order as not available (locked).

    • Inserts the order in the list of orders pending settlement.

    • Locks the required amount of security tokens in the redemption book.

    • Emits an OrderLocked event, signaling the order has been locked.

  • Example:

Admin Order Locking

  • Function: adminLockTokens(bytes32 _role, uint256 _orderId, address _investorWallet, uint256 _lockingHint)

  • Purpose: Allows admins to to lock in a confirmed order on behalf of an investor, locking the required security tokens in the process.

  • Parameters:

    • bytes32 _role: Role the admin possesses in order to access this function.

    • uint256 _orderId: The Id of the order.

    • address _investorWallet: Wallet belonging to the investor to take security tokens from when locking.

    • _lockingHint: Hint of a nearby order Id to make locking more efficient. Can be ignored by using 0.

  • Validation Checks:

    • Ensures the caller as the role they claim.

    • Ensure the role is allowed to call this function.

    • Ensures the investor is allowed to lock the order for the amount of settlement tokens by the allowlist modules.

    • Makes sure the order is already confirmed and is available.

    • Verifies the result of the checkAdvisedLockRedemption() function for relevant modules in the rules engine.

  • Behavior:

    • Marks the order as not available (locked).

    • Inserts the order in the list of orders pending settlement.

    • Locks the required amount of security tokens in the redemption book.

    • Emits an OrderLocked event, signaling the order has been locked.

  • Example:

Redemption Cancellation

Investors and dealers can cancel an order if it has not been locked yet. Additionally, admins can cancel orders even if they are locked. After an order is settled, it is not possible to cancel it.

Investor Order Cancelling

  • Function: investorCancelOrder(uint256 _orderId)

  • Purpose: Allows investors to cancel a confirmed order that has not yet been locked.

  • Parameters:

    • uint256 _orderId: The Id of the order.

  • Validation Checks:

    • Checks that the caller is the investor that the order belongs to.

    • Makes sure the order is already confirmed and not available.

  • Behavior:

    • Marks the order as cancelled.

    • The order and its changes/effects are removed

    • Emits an OrderCancelled event, signaling the order has been cancelled.

  • Example:

Dealer Order Cancelling

  • Function: dealerCancelOrder(uint256 _orderId)

  • Purpose: Allows dealers to cancel a confirmed order that has not yet been locked, on behalf of an investor.

  • Parameters:

    • uint256 _orderId: The Id of the order.

  • Validation Checks:

    • Ensures the caller is the investor's dealer.

    • Makes sure the order is already confirmed and not available.

    • Verifies the result of the checkAdvisedRedemptionCancellation() function for relevant modules in the rules engine.

  • Behavior:

    • Marks the order as cancelled.

    • The order and its changes/effects are removed

    • Emits an OrderCancelled event, signaling the order has been cancelled.

  • Example:

Admin Order Cancelling

  • Function: adminCancelOrder(uint256 _orderId, bytes32 _role)

  • Purpose: Allows admins to cancel a confirmed order, even if it has been locked, on behalf of an investor.

  • Parameters:

    • bytes32 _role: Role the admin possesses in order to access this function.

    • uint256 _orderId: The Id of the order.

  • Validation Checks:

    • Ensures the caller as the role they claim.

    • Ensure the role is allowed to call this function.

    • Makes sure the order is confirmed or available.

  • Behavior:

    • Marks the order as cancelled.

    • The order and its changes/effects are removed

    • Emits an OrderCancelled event, signaling the order has been cancelled.

  • Example:

Redemption Settlement

Order that are locked can be settled by an admin. When an order is settled, the settlement tokens are burned, and the corresponding settlement tokens are minted. Orders are settled in batches. After an order has been partially settled, it can be rebalanced to complete the settlement. It is also possible for admins to carry out forced redemptions under certain circumstances, such as investor's holdings dropping below the minimum balance.

Admin Order Settlement

  • Function: settleOrders(uint256 _lastOrderId, uint256 _percentageToSettle, bytes32 _role)

  • Purpose: Allows admins to settle all locked orders until a desired order Id, settling the same percentage of each one. The un-audited NAV is used, but partially settled orders can then be rebalanced.

  • Parameters:

    • uint256 _lastOrderId: The Id of the last order to settle.

    • uint256 _percentageToSettle: The percentage of each order that should be settled, expressed in basis points (bps).

    • bytes32 _role: Role the admin possesses in order to access this function.

  • Validation Checks:

    • Ensures the caller as the role they claim.

    • Ensure the role is allowed to call this function.

    • Verifies the percentage to settle is between 0% and 100%.

    • Makes sure all orders to settle are locked.

    • Makes sure none of the orders to be settled have already been settled in the current round.

    • Verifies the result of the checkSettleRedemptions() function for relevant modules in the rules engine.

  • Behavior:

    • Burns the specified percentage of locked security tokens for the orders. Of that percentage, if the GATE_CRITERIA_3 is set to something different than 0, that percentage is settled proportionally per investor, leaving the rest for rebalancing.

    • Calculates the required fee to take from the settlement of each order.

    • Issues the corresponding settlement tokens (minus fee) to the beneficiary addresses in the orders.

    • Issues the fee to the KAIO Treasury in the form of settlement tokens.

    • Emits an OrderSettled event for each order, signaling it has been settled.

  • Example:

Admin Forced Order Settlement

  • Function: adminForceRedemption(bytes32 _investorId, bytes32 _role, uint256 _lockingHint)

  • Purpose: Allows admins to force a redemption for a given investor, in the case they are breaking some rule.

  • Parameters:

    • bytes32 _investorId: The Id of the investor.

    • bytes32 _role: Role the admin possesses in order to access this function.

    • _lockingHint: Hint of a nearby order Id to make locking more efficient. Can be ignored by using 0.

  • Validation Checks:

    • Ensures the caller as the role they claim.

    • Ensure the role is allowed to call this function.

    • Checks that the amount of tokens is not zero.

    • Makes sure all orders to settle are locked.

    • Makes sure none of the orders to be settled have already been settled in the current round.

    • Verifies the result of the checkForcedRedemption() function for relevant modules in the rules engine.

    • Verifies the result of the checkRedemptionConfirmation() function for relevant modules in the rules engine.

  • Behavior:

    • Forces the redemption of the investor's security tokens, combining all steps and doing an instant settlement.

    • Burns the locked security tokens of the investor.

    • Calculates the required fee to take from the settlement.

    • Issues the corresponding settlement tokens (minus fee) to the beneficiary addresses in the orders.

    • Issues the fee to the KAIO Treasury in the form of settlement tokens.

    • Emits an OrderSettled event , signaling the order has been settled.

  • Example:

Admin Order Rebalancing

  • Function: rebalanceSettlements(uint256 _lastOrderToRebalance, bytes32 _role)

  • Purpose: Rebalances previously partially settled orders to complete the settlement, using the audited NAV.

  • Parameters:

    • uint256 _lastOrderToRebalance: The Id of the last order to rebalance.

    • bytes32 _role: Role the admin possesses in order to access this function.

  • Validation Checks:

    • Ensures the caller as the role they claim.

    • Ensure the role is allowed to call this function.

    • Makes sure all orders to rebalance are locked.

  • Behavior:

    • Burns the remaining locked security tokens for the orders.

    • Calculates the required fee to take from the settlement of each order.

    • Issues the corresponding settlement tokens to the beneficiary addresses in the orders.

    • Issues the corresponding settlement tokens the KAIO Treasury.

    • Emits an OrderRebalanced event for each order, signaling it has been settled.

  • Example:

Restrictions

Restrictions are applied at multiple points during the redemption process. The main restrictions for redemptions can be found in Redemption Modules.

Fees

Fees are calculated and deducted during the redemption settlement. Detailed explanations of the fees can be found in Fees.

Last updated