# Rule Engines

## 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](/how-kaio-works/smart-contracts/rules/rule-modules.md).

## Rules Engine

Each instrument has it's own rules engine smart contract that is deployed on instrument creation, more particularly <mark style="color:red;">`RulesEngine.sol`</mark>. 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**:

  ```solidity
  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**:

  ```solidity
  getCloneAddress(0xDeployedModule, 1714557340);
  ```

#### 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**:

  ```solidity
  editModuleClone(0xClonedModule, true, 0xFundAdminRole);
  ```

#### 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**:

  ```solidity
  deleteModuleClone(0xClonedModule, 0xFundAdminRole);
  ```

### 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.

<table data-full-width="true"><thead><tr><th width="393">Operation</th><th width="440">Function</th><th>Return</th></tr></thead><tbody><tr><td><code>ADVISED_CREATE_BID</code></td><td><em>checkAdvisedCreateBid()</em></td><td>Bool</td></tr><tr><td><code>ADVISED_CREATE_REDEMPTION</code></td><td><em>checkAdvisedCreateRedemption()</em></td><td>Bool</td></tr><tr><td><code>ADVISED_BID_CONFIRMATION</code></td><td><em>checkAdvisedBidConfirmation()</em></td><td>Bool</td></tr><tr><td><code>ADVISED_BID_LOCK</code></td><td><em>checkAdvisedLockBid()</em></td><td>Bool</td></tr><tr><td><code>ADVISED_REDEMPTION_LOCK</code></td><td><em>checkAdvisedLockRedemption()</em></td><td>Bool</td></tr><tr><td><code>BID_CONFIRMATION</code></td><td><em>checkBidConfirmation()</em></td><td>Bool</td></tr><tr><td><code>REDEMPTION_CONFIRMATION</code></td><td><em>checkRedemptionConfirmation()</em></td><td>Bool</td></tr><tr><td><code>ADVISED_REDEMPTION_CONFIRMATION</code></td><td><em>checkAdvisedRedemptionConfirmation()</em></td><td>Bool</td></tr><tr><td><code>CREATE_BID</code></td><td><em>checkCreateBid()</em></td><td>Bool</td></tr><tr><td><code>CREATE_REDEMPTION</code></td><td><em>checkCreateRedemption()</em></td><td>Bool</td></tr><tr><td><code>BID_LOCK</code></td><td><em>checkLockBid()</em></td><td>Bool</td></tr><tr><td><code>REDEMPTION_LOCK</code></td><td><em>checkLockRedemption()</em></td><td>Bool</td></tr><tr><td><code>FORCED_REDEMPTION</code></td><td><em>checkForcedRedemption()</em></td><td>Bool</td></tr><tr><td><code>FORCED_TRANSFER</code></td><td><em>checkForcedTransfer()</em></td><td>Bool</td></tr><tr><td><code>RECEIVE</code></td><td><em>checkReceiver()</em></td><td>Bool</td></tr><tr><td><code>SEND</code></td><td><em>checkSender()</em></td><td>Bool</td></tr><tr><td><code>SETTLE_BIDS</code></td><td><em>checkSettleBids()</em></td><td>Numeric</td></tr><tr><td><code>SETTLE_REDEMPTIONS</code></td><td><em>checkSettleRedemptions()</em></td><td>Numeric</td></tr><tr><td><code>FILL</code></td><td><em>checkFill()</em></td><td>Bool</td></tr><tr><td><code>ORDER</code></td><td><em>checkOrder()</em></td><td>Bool</td></tr><tr><td><code>TRADE</code></td><td><em>checkTrade()</em></td><td>Bool</td></tr><tr><td><code>TRANSFER</code></td><td><em>checkTransfer()</em></td><td>Bool</td></tr><tr><td><code>ADVISED_BID_CANCELLATION</code></td><td><em>checkAdvisedBidCancellation()</em></td><td>Bool</td></tr><tr><td><code>ADVISED_REDEMPTION_CANCELLATION</code></td><td><em>checkAdvisedRedemptionCancellation()</em></td><td>Bool</td></tr><tr><td><code>STATIC_FLAG_CHECK</code></td><td><em>checkStaticFlags()</em></td><td>Bool</td></tr><tr><td><code>DYNAMIC_FLAG_CHECK</code></td><td><em>checkDynamicFlags()</em></td><td>Bool</td></tr><tr><td><code>DYNAMIC_FLAG_CHECK_FUNDS</code></td><td><em>checkDynamicFlagsFunds()</em></td><td>Bool</td></tr><tr><td><code>DYNAMIC_FLAG_CHECK_TOKENS</code></td><td><em>checkDynamicFlagsTokens()</em></td><td>Bool</td></tr></tbody></table>

## Dealer Rules Engine

The dealer rules engine (<mark style="color:red;">`DealerRulesEngine.sol`</mark>) 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**:

  ```solidity
  registerModule(0xDeployedModule);
  ```

#### 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**:

  ```solidity
  registerLibreModule(0xDeployedModule, 0xLibreAdminRole);
  ```

#### 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**:

  ```solidity
  editModuleClone(0xClonedModule, true);
  ```

#### 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**:

  ```solidity
  editModuleClone(0xClonedModule, true, 0xLibreAdminRole);
  ```

#### 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**:

  ```solidity
  deleteModuleClone(0xClonedModule);
  ```

#### 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**:

  ```solidity
  deleteLibreModuleClone(0xClonedModule, 0xLibreAdminRole);
  ```

### 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.

<table data-full-width="true"><thead><tr><th width="376">Operation</th><th width="298">Function</th><th width="169">Return</th><th>Owner</th></tr></thead><tbody><tr><td><code>LIBRE_STATIC_FLAG_CHECK</code></td><td><em>checkLibreStaticFlags()</em></td><td>Bool</td><td>KAIO Admin</td></tr><tr><td><code>LIBRE_DYNAMIC_FLAG_CHECK</code></td><td><em>checkLibreDynamicFlags()</em></td><td>Bool</td><td>KAIO Admin</td></tr><tr><td><code>LIBRE_DYNAMIC_FLAG_CHECK_FUNDS</code></td><td><em>checkLibreDynamicFlagsFunds()</em></td><td>Bool</td><td>KAIO Admin</td></tr><tr><td><code>LIBRE_DYNAMIC_FLAG_CHECK_TOKENS</code></td><td><em>checkLibreDynamicFlagsTokens()</em></td><td>Bool</td><td>KAIO Admin</td></tr><tr><td><code>STATIC_FLAG_CHECK</code></td><td><em>checkStaticFlags()</em></td><td>Bool</td><td>Dealers</td></tr><tr><td><code>DYNAMIC_FLAG_CHECK</code></td><td><em>checkDynamicFlags()</em></td><td>Bool</td><td>Dealers</td></tr><tr><td><code>DYNAMIC_FLAG_CHECK_FUNDS</code></td><td><em>checkDynamicFlagsFunds()</em></td><td>Bool</td><td>Dealers</td></tr><tr><td><code>DYNAMIC_FLAG_CHECK_TOKENS</code></td><td><em>checkDynamicFlagsTokens()</em></td><td>Bool</td><td>Dealers</td></tr></tbody></table>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.kaio.xyz/how-kaio-works/smart-contracts/rules/rule-engines.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.