Subscription Book

Book for subscription logic.

General Description

The Subscription Book contains all the logic for the subscription lifecycle, accepting investments in Settlement Tokens and settling them in Security Tokens. Subscriptions 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 settlement tokens and minting the corresponding security tokens to investors. Certain restrictions on the subscription order lifecycle are enforced by modules applying specific rules and conditions.

Subscription Creation

Orders are first created by investors or dealers, signaling interest in subscribing to 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 subscription orders, indicating the amount of settlement tokens they intend to lock.

  • Parameters:

    • uint256 _amount: The amount of settlement 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 settlement tokens by the allowlist modules.

    • Checks that the amount of tokens is not zero.

    • Verifies the result of the checkCreateBid() 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 subscription orders on behalf of investors, indicating the amount of settlement tokens they intend to lock.

  • Parameters:

    • uint256 _amount: The amount of settlement 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 settlement 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 settlement tokens by the allowlist modules.

    • Verifies the result of the checkAdvisedCreateBid() 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:

Subscription 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 subscription 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 settlement tokens by the allowlist modules.

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

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

  • Behavior:

    • Marks the order as confirmed.

    • Registers the investor's participation in the subscription 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 subscription order on behalf of an investor.

  • Parameters:

    • uint256 _orderId: The Id of the order.

    • address _investorWallet: Wallet belonging to the investor to take settlement 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 settlement tokens by the allowlist modules.

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

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

  • Behavior:

    • Marks the order as confirmed.

    • Registers the investor's participation in the subscription process

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

  • Example:

Subscription Locking

Investors, dealers, or admins can lock orders after they have been confirmed. For an order to be locked, the required settlement tokens are transferred into the subscription 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 settlement 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 settlement tokens by the allowlist modules.

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

    • Verifies the result of the checkLockBid() 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 settlement tokens in the subscription 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 settlement tokens in the process.

  • Parameters:

    • uint256 _orderId: The Id of the order.

    • address _investorWallet: Wallet belonging to the investor to take settlement 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 settlement tokens by the allowlist modules.

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

    • Verifies the result of the checkAdvisedLockBid() 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 settlement tokens in the subscription 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 settlement 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 settlement 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 checkAdvisedLockBid() 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 settlement tokens in the subscription book.

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

  • Example:

Subscription 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 checkAdvisedBidCancellation() 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:

Subscription Settlement

Order that are locked can be settled by an admin. When an order is settled, the settlement tokens are burned, and the corresponding security tokens are minted. Orders are settled in batches.

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.

  • 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 checkSettleBids() function for relevant modules in the rules engine.

  • Behavior:

    • Burns the specified percentage of locked settlement tokens for the orders.

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

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

  • Example:

Restrictions

Restrictions are applied at multiple points during the subscription process. The main restrictions for subscriptions can be found in Subscription Modules.

Last updated