Rule Engines

Engines managing rules modules.

Overview

Rule engines are contracts that allow for other contracts to easily check the rules and restrictions of different modules for a given operation, such as when creating orders or settling them. The result of not adhering to these restrictions can lead to reductions in transaction amounts, or even a complete transaction revert. It is up to the contract calling the module to determine the resulting behavior after passing or failing a rule. Any module can be developed externally and added to a rules engine as long as it follows the interfaces for the operations it wants to add restrictions to. Modules can also be paused or removed from the engine. Existing modules can be found in Rule Modules.

Rules Engine

Each instrument has it's own rules engine smart contract that is deployed on instrument creation, more particularly RulesEngine.sol. This engine is used for applying rules when investors interact with the instrument. The Fund Admin managing the instrument is also the user managing this contract, and deciding which modules to register.

Module Operations

These functions are used for managing modules in the engine.

Register Module

  • Function: registerModule(address _module, bytes32 _role)

  • Purpose: Registers a new module in the rules engine by cloning an existing one.

  • Parameters:

    • address _module: Address of the deployed module to clone.

    • bytes32 _role: Role of the caller.

  • Validation Checks:

    • Checks that the caller has the correct role for a Fund Admin.

  • Behavior:

    • Initializes and registers the new module.

    • Store the operations the module supports.

    • Emits a ModuleRegistered event, signaling the module has been registered.

  • Return Values:

    • address: Address of the new cloned module.

  • Example:

    registerModule(0xDeployedModule, 0xFundAdminRole);

Get Module Clone

  • Function: getCloneAddress(address _module, uint256 _registrationTimestamp)

  • Purpose: Returns the address of a cloned module by providing the original and the time it was cloned.

  • Parameters:

    • address _module: Address of the deployed module that was used as a base.

    • uint256 _registrationTimestamp: Timestamp indicating when the module was cloned.

  • Return Values:

    • address: Address of the cloned module.

  • Example:

Edit Module

  • Function: editModuleClone(address _moduleClone, bool _status, bytes32 _role)

  • Purpose: Enables or disables an existing registered module.

  • Parameters:

    • address _moduleClone: Address of the cloned module.

    • bool _status: Status indicating if the module should be enabled or disabled.

    • bytes32 _role: Role of the caller.

  • Validation Checks:

    • Checks that the caller has the correct role for a Fund Admin.

  • Behavior:

    • Enables or disables the module.

    • Emits a ModuleUpdated event, signaling the module has been updated.

  • Example:

Delete Module

  • Function: deleteModuleClone(address _moduleClone, bytes32 _role)

  • Purpose: Removes a module from the rules engine.

  • Parameters:

    • address _moduleClone: Address of the cloned module.

    • bytes32 _role: Role of the caller.

  • Validation Checks:

    • Checks that the caller has the correct role for a Fund Admin.

  • Behavior:

    • Removes stored module operations.

    • Removes module from engine.

    • Emits a ModuleDeleted event, signaling the module has been deleted.

  • Example:

Rule Checking

This rules engine checks the operations described below, using the associated function to call the corresponding rule module. The module can return true/false if they are of bool type, or instead return a transaction amount if they are a numeric type. If the module is not present or disabled, it has no effect.

Operation
Function
Return

ADVISED_CREATE_BID

checkAdvisedCreateBid()

Bool

ADVISED_CREATE_REDEMPTION

checkAdvisedCreateRedemption()

Bool

ADVISED_BID_CONFIRMATION

checkAdvisedBidConfirmation()

Bool

ADVISED_BID_LOCK

checkAdvisedLockBid()

Bool

ADVISED_REDEMPTION_LOCK

checkAdvisedLockRedemption()

Bool

BID_CONFIRMATION

checkBidConfirmation()

Bool

REDEMPTION_CONFIRMATION

checkRedemptionConfirmation()

Bool

ADVISED_REDEMPTION_CONFIRMATION

checkAdvisedRedemptionConfirmation()

Bool

CREATE_BID

checkCreateBid()

Bool

CREATE_REDEMPTION

checkCreateRedemption()

Bool

BID_LOCK

checkLockBid()

Bool

REDEMPTION_LOCK

checkLockRedemption()

Bool

FORCED_REDEMPTION

checkForcedRedemption()

Bool

FORCED_TRANSFER

checkForcedTransfer()

Bool

RECEIVE

checkReceiver()

Bool

SEND

checkSender()

Bool

SETTLE_BIDS

checkSettleBids()

Numeric

SETTLE_REDEMPTIONS

checkSettleRedemptions()

Numeric

FILL

checkFill()

Bool

ORDER

checkOrder()

Bool

TRADE

checkTrade()

Bool

TRANSFER

checkTransfer()

Bool

ADVISED_BID_CANCELLATION

checkAdvisedBidCancellation()

Bool

ADVISED_REDEMPTION_CANCELLATION

checkAdvisedRedemptionCancellation()

Bool

STATIC_FLAG_CHECK

checkStaticFlags()

Bool

DYNAMIC_FLAG_CHECK

checkDynamicFlags()

Bool

DYNAMIC_FLAG_CHECK_FUNDS

checkDynamicFlagsFunds()

Bool

DYNAMIC_FLAG_CHECK_TOKENS

checkDynamicFlagsTokens()

Bool

Dealer Rules Engine

The dealer rules engine (DealerRulesEngine.sol) is a single contract used when a dealer's investors interact with KAIO. It checks rule modules registered and managed by each dealer separately for their investors. The engine can also check modules that are universal, i.e., applying to all investors regardless of their dealer.

Module Operations

These functions are used for managing modules in the engine.

Register Module

  • Function: registerModule(address _module)

  • Purpose: Registers a new module in the dealer rules engine for the dealer calling the function by cloning an existing one.

  • Parameters:

    • address _module: Address of the deployed module to clone.

  • Behavior:

    • Initializes and registers the new module for the calling Dealer.

    • Store the operations the module supports.

    • Emits a ModuleRegistered event, signaling the module has been registered.

  • Return Values:

    • address: Address of the new cloned module.

  • Example:

Register Universal Module

  • Function: registerLibreModule(address _module, bytes32 _role)

  • Purpose: Registers a new universal module in the rules engine by cloning an existing one.

  • Parameters:

    • address _module: Address of the deployed module to clone.

    • bytes32 _role: Role of the caller.

  • Validation Checks:

    • Checks that the caller has the correct role for the KAIO Admin.

  • Behavior:

    • Initializes and registers the new universal module.

    • Store the operations the module supports.

    • Emits a ModuleRegistered event, signaling the module has been registered.

  • Return Values:

    • address: Address of the new cloned module.

  • Example:

Edit Module

  • Function: editModuleClone(address _module, bool _status)

  • Purpose: Enables or disables an existing registered module for the calling dealer.

  • Parameters:

    • address _moduleClone: Address of the cloned module.

    • bool _status: Status indicating if the module should be enabled or disabled.

  • Validation Checks:

    • Checks that the caller is the same dealer that registered the module.

  • Behavior:

    • Enables or disables the module.

    • Emits a ModuleUpdated event, signaling the module has been updated.

  • Example:

Edit Universal Module

  • Function: editLibreModuleClone(address _module, bool _status, bytes32 _role)

  • Purpose: Enables or disables an existing registered universal module.

  • Parameters:

    • address _moduleClone: Address of the cloned module.

    • bool _status: Status indicating if the module should be enabled or disabled.

    • bytes32 _role: Role of the caller.

  • Validation Checks:

    • Checks that the caller has the correct role for the KAIO Admin.

  • Behavior:

    • Enables or disables the module.

    • Emits a ModuleUpdated event, signaling the module has been updated.

  • Example:

Delete Module

  • Function: deleteModuleClone(address _moduleClone)

  • Purpose: Removes a module from the rules engine for the calling dealer.

  • Parameters:

    • address _moduleClone: Address of the cloned module.

  • Validation Checks:

    • Checks that the caller is the same dealer that registered the module.

  • Behavior:

    • Removes stored module operations.

    • Removes module from engine.

    • Emits a ModuleDeleted event, signaling the module has been deleted.

  • Example:

Delete Universal Module

  • Function: deleteLibreModuleClone(address _moduleClone, bytes32 _role)

  • Purpose: Removes a universal module from the rules engine.

  • Parameters:

    • address _moduleClone: Address of the cloned module.

    • bytes32 _role: Role of the caller.

  • Validation Checks:

    • Checks that the caller has the correct role for the KAIO Admin.

  • Behavior:

    • Removes stored module operations.

    • Removes module from engine.

    • Emits a ModuleDeleted event, signaling the module has been deleted.

  • Example:

Rule Checking

The dealer rules engine checks the operations described below, using the associated function to call the corresponding rule module. The module can return true/false if they are of bool type, or instead return a transaction amount if they are a numeric type. If the module is not present or disabled, it has no effect. Some operations trigger modules set by the KAIO admin applicable to all investors, while others trigger dealer modules only applicable to the dealer's investors.

Operation
Function
Return
Owner

LIBRE_STATIC_FLAG_CHECK

checkLibreStaticFlags()

Bool

KAIO Admin

LIBRE_DYNAMIC_FLAG_CHECK

checkLibreDynamicFlags()

Bool

KAIO Admin

LIBRE_DYNAMIC_FLAG_CHECK_FUNDS

checkLibreDynamicFlagsFunds()

Bool

KAIO Admin

LIBRE_DYNAMIC_FLAG_CHECK_TOKENS

checkLibreDynamicFlagsTokens()

Bool

KAIO Admin

STATIC_FLAG_CHECK

checkStaticFlags()

Bool

Dealers

DYNAMIC_FLAG_CHECK

checkDynamicFlags()

Bool

Dealers

DYNAMIC_FLAG_CHECK_FUNDS

checkDynamicFlagsFunds()

Bool

Dealers

DYNAMIC_FLAG_CHECK_TOKENS

checkDynamicFlagsTokens()

Bool

Dealers

Last updated