Rule Modules
Modules for compliance rules
Introduction
Rules Modules are smart contracts that allow for specific checks to be applied to certain operations, making sure functionality is bound to rules being followed. Modules are registered in Rules Engines. These will call the appropriate check function in the module when the corresponding operation is being performed, as described in Rule Engines. Thus, modules must list the operations for which they will perform checks. To ensure safety modules can only add additional restrictions on functionality, not modify it in other ways.
The modules detailed below are the ones currently used, but new modules can be added in the future, be it platform-wide or only applying in specific scenarios.
Allowlist Modules
KAIO Requirements Module
Contract
LibreRequirementsModule.sol
Associated Rules Engine
Dealer Rules Engine
Triggers
Creating an order
Confirming an order
Locking an order
Transferring tokens
Parameters
BLOCKED: Indicates if the investor is blocked.INVESTOR_TYPE: Category the investor belongs to.MAX_INVESTOR_TYPE: Maximum investor category allowed.KYC_PASSED: Indicates if the investor has passed KYC checks.AML_PASSED: Indicates if the investor has passed AML checks.SANCTIONS_PASSED: Indicates if the investor has passed sanctions checks.RESIDENCE: Residence of the investor.JURISDICTION_ALLOWED: Indicates if the jurisdiction is allowed in KAIO.SELF_CERTIFICATION_REQUIRED: Indicates if a self certification is needed for the jurisdiction.SELF_CERTIFICATION: Indicates if the investor has a self certification.FITNESS_TEST_REQUIRED: Indicates if a fitness test is needed for the jurisdiction.FITNESS_TEST: Indicates if the investor has passed a fitness test.INVESTOR_ALLOWLISTED_REQUIRED: Indicates if the instrument requires investors to be individually allowed manually.DISCLOSURE_DOCUMENTS_REQUIRED: Indicates if the level of disclosure documents needed by the fund for the jurisdiction.DISCLOSURE_DOCUMENTS: Disclosure documents level of the fund.LISTED_ON_REGULATED_VENUE_REQUIRED: Indicates if the fund being listed on a regulated venue is needed for the jurisdiction.LISTED_ON_REGULATED_VENUE: Indicates if the fund is listed on a regulated venue.LOCAL_AIFM_REQUIRED: Indicates if the fund having a local AIFM is needed for the jurisdiction.LOCAL_AIFM: Indicates if the fund has a local AIFM.NON_EU_AIFM_REQUIRED: Indicates if the fund having a non EU AIFM is needed for the jurisdiction.NON_EU_AIFM: Indicates if the fund has a local non EU AIFM.MINIMUM_INVESTMENT_REQUIRED: Indicates if a minimum investment is needed in the instrument.NO_MINIMUM_INVESTMENT_HOLDER_NUMBER: Number of holder for which the instrument does not enforce a minimum investment.MINIMUM_INVESTMENT: Minimum investment in settlement tokens required when subscribing to the instrument.
Explanation
KAIO requirements can be any restriction the KAIO Admin decides to set on investors in order to interact with the system. The platform conditions for MVP that are implemented in LibreRequirementsModule.sol are complex, and are based on the limitations investors and funds receive from their jurisdictions, as presented in the table below.
Restrictions
Investor has a proper type.
Investor has passed KYC checks.
Investor has passed AML checks.
Investor has passed sanctions checks.
Investor's residence is an allowed jurisdiction.
Investor has self certification if their jurisdiction requires it.
Investor has fitness test if their jurisdiction requires it.
Investor is allowed directly for the instrument they are using if the instrument requires it.
The fund that owns the instrument that the Investor is using has the proper disclosure documents level if the jurisdiction the Investor belongs to requires it.
The fund that owns the instrument that the Investor is listed on a regulated venue if the jurisdiction the Investor belongs to requires it.
The fund that owns the instrument that the Investor is using has a local AIFM if the jurisdiction the Investor belongs to requires it.
The fund that owns the instrument that the Investor is using has a local non-EU AIFM if the jurisdiction the Investor belongs to requires it.
The Investor's investment if above the minimum investment of their jurisdiction for their type of user.
Example
In this example, an investor is trying to subscribe to an instrument. The investor has a proper type, since it is smaller in value than the maximum investor type. They have also passed KYC, AML, and sanction checks successfully, and their residence is allowed in the jurisdiction. While they do not have a fitness test or a self certification, their jurisdiction does not require either of them. The jurisdictions does not require the fund the instrument belongs to be listed in a regulated venue, have local AIFM or a local non-EU AIFM, but it does require a disclosure documents level of 1. The fund has an disclosure documents level of 2, so it meets that requirement. Finally the instrument does not require the investor to be allowed manually, but it does require a minimum investment of $10,000 in settlement tokens. Since the investor meets all other requirements, they will be able to subscribe as long as their investment is of 10,000 settlement tokens or above.
Dealer Requirements Module
Contract
N/A
Associated Rules Engine
Dealer Rules Engine
Triggers
Creating an order
Confirming an order
Locking an order
Transferring tokens
Parameters
N/A
Explanation
Dealer requirements can be any restriction a Dealer decides to set on their investors in order to interact with KAIO. Currently there are no conditions a Dealer has requested, but an example of what this could look like is provided in AllowlistModuleDealerExample1.sol.
Restrictions
N/A
Example
N/A
Instrument Requirements Module
Contract
InstrumentRequirementsModule.sol
Associated Rules Engine
Rules Engine
Triggers
Creating an order
Confirming an order
Locking an order
Transferring tokens
Parameters
RESIDENCE: Residence of the investor.RESIDENCES_ALLOWED: Residences allowed in the instrument.NATIONALITIES: Nationalities of the investor.NATIONALITIES_ALLOWED: Nationalities allowed in the instrument.INVESTOR_TYPE: Category the investor belongs to.INVESTOR_TYPES_ALLOWED: Investor types allowed in the instrument.
Explanation
Instrument requirements can be any restriction an Instrument Admin decides to set on investors in order to interact with their instrument. An example of what this could look like is provided in AllowlistModuleInstrumentExample1.sol. Currently InstrumentRequirementsModule.sol is the only implementation, and Fund Admins are free to use it or extend it as they please.
Restrictions
The nationalities of the Investor are all allowed in the instrument.
The residence of the Investor is allowed in the instrument.
The investor type of the Investor is allowed in the instrument.
Example
In this example, an investor is trying to subscribe to an instrument that has its own restrictions for residence, nationality, and type. While their residence and investor type are allowed by the instrument, their nationality is not, since they have a French nationality and only German nationality is accepted. This means they will not be able to subscribe to the instrument while their information and the instruments restrictions do not change.
Subscription Modules
Cut Off Module
Contract
BidCutOffModule.sol
Associated Rules Engine
Rules Engine
Trigger
Locking a subscription order
Parameters
SUBSCRIPTION_CUT_OFF_PERIOD: First component of the period of time for which cut offs happen, indicating days. It is measured in seconds, counting backwards from the end of the subscription period.SUBSCRIPTION_CUT_OFF_TIME: Second component of the period of time for which cut offs happen, indicating the hour the cut off will begin the previous day. It is measured in seconds.
Explanation
This amount of time is split into two components. The first is the cut off period itself, which is subtracted backwards from the end of the subscription period. Then there is the cut off time, which is the time of day of the previous day when the cut off will go into effect. Together they provide an amount of time for which the cut off happens at the end of each subscription period.
Restrictions
Locking an order must happen before the cut off time of a period.
Example
In this example an investor is trying to lock a subscription order 3 days before the period ends, at 20:00 UTC. It is the 27th of April, and the period ends at the end of the month (May 1st). In this case the cut off period starts at 16:00 UTC 3 days before the period ends. Since the investor tried to lock once the cut off period started, they will not be able to lock their order until the cut off period ends and the next period starts.
Aggregation Limit Module
Contract
BidsAggregationLimitModule.sol
Associated Rules Engine
Rules Engine
Trigger 1
Creating a subscription order
Parameters 1
SUBSCRIPTION_SIZE_MULTIPLE: Smallest denomination unit an order amount can have.
Explanation 1
The multiple defines the smallest possible unit of settlement tokens that investors can transact with.
Restrictions 1
The amount of the order must be a multiple of the subscription size multiple.
Example 1
In this example, an investor is trying to create a subscription order worth 9.3792 settlement tokens (settlement tokens have 6 decimal places). Since this number is not a multiple of 0.001, which is the subscription size multiple, the order creation is not allowed. The investor can instead create an order for 9.379 settlement tokens, which will be allowed.
Trigger 2
Settling subscription orders
Parameters 2
LOCAL_AGGREGATE_MINIMUM_HOLDING: Minimum holding amount between all investors for the feeder fund.INSTRUMENT_TOKEN: Security token address.REDEMPTION_BOOK: Redemption book address.SUBSCRIPTION_BOOK: Subscription book address.AGGREGATED_MINIMUM_SUBSEQUENT_SUBSCRIPTION: Minimum amount for subsequent subscriptions between all investors.
Explanation 2
There are capacity restrictions to meet for settling the combined subscriptions of all investors. These are related to the new amount being subscribed, and the overall holdings once the settlement is done.
Restrictions 2
The percentage used to settle has to be 100%.
The settlement must take place during a valid subscription period.
The to be settled must be above the aggregated minimum subsequent subscription.
The amount to be settled plus the existing holdings must be above the local aggregate minimum holding.
Example 2
In this example an admin is settling the pending subscription orders. They are settling 100% of the selected orders, and the settlement is taking place during a valid subscription period. The existing holdings are $98,000, and the amount to settle is $14,000. Since the total amount after the settlement will be larger than the local aggregate minimum holding ($100,000), and the amount to settle is above the aggregated minimum subsequent subscription ($10,000), the settlement can take place. This results in $112,00 in total holdings.
Round Limit Module
Contract
RoundAmountLimitModule.sol
Associated Rules Engine
Rules Engine
Trigger
Creating a subscription order
Parameters
MAXIMUM_SUBSCRIPTION_AMOUNT: Maximum amount of settlement tokens that can be subscribed in a given subscription round
Explanation
There is a maximum amount of subscriptions that can be done in a given round, measured in the amount of settlement tokens used in the orders.
Restrictions
The aggregated amount of settlement tokens in all the orders created in the round should not exceed the maximum subscription amount.
Example
In this example an investor is trying to create a subscription order worth $1,500. The aggregated amount of subscriptions in the current round is $48,700. Since with the incoming subscription the total amount would be above the maximum subscription amount, the order creation would fail. The investor could create a different order worth $1,300, and this one would be created successfully.
End Module
Contract
SubscriptionEndModule.sol
Associated Rules Engine
Rules Engine
Triggers
Creating a subscription order
Confirming a subscription order
Locking a subscription order
Settling subscription orders
Parameters
SUBSCRIPTION_START: Start date for subscriptions in an instrument.SUBSCRIPTION_END: End date for subscriptions in an instrument.
Explanation
The operations interacting with the subscription book need to happen between the subscription start and subscription end dates.
Restrictions
Operations must take place after subscription start.
Operations must take place before the subscription end.
Example
In this example, an investor is locking a subscription order the 1st of May of 2024 (2024/05/01). Since this is after the subscription start (2024/04/25) and before the subscription end (2033/05/18), it is allowed.
Size Module
Contract
SubscriptionSizeModule.sol
Associated Rules Engine
Rules Engine
Trigger 1
Transferring tokens
Parameters 1
SUBSCRIPTION_BOOK: Subscription book address.REDEMPTION_BOOK: Redemption book address.INSTRUMENT_TOKEN: Security token address.UNAUDITED_NAV_PER_SHARE: Unaudited net asset value of the instrument, per each security token.LOCAL_INVESTOR_MINIMUM_HOLDING: Minimum amount of security tokens an investor needs to hold, denominated in USD using the instruments NAV.
Explanation 1
When transferring their tokens, investors need to keep their balance above the minimum holding, unless they are transferring their entire balance. Transfer between the addresses belonging to the same investor (internal transfers) are exempt.
Restrictions 1
Internal transfers between addresses of the same investor are allowed, and no restrictions are applied.
Transfers should result in investors' balances being above the local investor minimum holding, or 0.
As an exception to the previous, a transfer is allowed if the recipient investor's balance is above 0 but below the local investor minimum holding, even if the resulting balance would still be below this minimum.
Example 1
In this example, an investor is transferring tokens to another investor. The sender has 1900 security tokens worth $2489. The recipient has no tokens. The sender wants to send 1000 tokens to the recipient. Since this would leave both investors above the minimum holding ($1179 and $1310), it is allowed.
Trigger 2
Confirming a subscription order
Parameters 2
SUBSCRIPTION_BOOK: Subscription book address.REDEMPTION_BOOK: Redemption book address.INSTRUMENT_TOKEN: Security token address.UNAUDITED_NAV_PER_SHARE: Unaudited net asset value of the instrument, per each security token.LOCAL_INVESTOR_MINIMUM_HOLDING: Minimum amount of security tokens an investor needs to hold, denominated in USD using the instruments NAV.INVESTOR_MINIMUM_INITIAL_SUBSCRIPTION: Minimum amount of settlement tokens used when doing an initial subscription.INVESTOR_MINIMUM_SUBSEQUENT_SUBSCRIPTION: Minimum amount of settlement tokens used when doing subsequent subscriptions.
Explanation 2
When their holding is below the minimum investor holding, investor's can only confirm additional subscription orders if they would bring their holding above the minimum.
Restrictions 2
An investor's net holding plus the incoming subscriptions must put their holdings above the minimum investor holding.
The incoming subscription amount must be above the investor minimum subsequent subscription, or alternatively above the investor minimum initial subscription if the investor's holdings are 0.
Example 2
In this example an investor is trying to confirm a subscription order. Their current holdings are $800. The order they are trying to confirm is for $300 in settlement tokens. While the initial subscription minimum does not apply (since it is not the investor's first subscription), and the holdings after the settlement of $1300 would be above the minimum investor holding ($1000), the order can't be confirmed. This is because it is below the $500 investor minimum subsequent subscription. Alternatively, if the investor tried with an order worth $500 or above, it would be confirmed successfully.
Trigger 3
Confirming a redemption order
Parameters 3
SUBSCRIPTION_BOOK: Subscription book address.REDEMPTION_BOOK: Redemption book address.INSTRUMENT_TOKEN: Security token address.UNAUDITED_NAV_PER_SHARE: Unaudited net asset value of the instrument, per each security token.LOCAL_INVESTOR_MINIMUM_HOLDING: Minimum amount of security tokens an investor needs to hold, denominated in USD using the instruments NAV.
Explanation 3
Investors can only confirm redemption orders if doing so would not bring their holding below the minimum investor holding.
Restrictions 3
An investor's net holding minus the outgoing redemptions must keep their holdings above the minimum investor holding.
Example 3
In this example an investor is trying to confirm a redemption order worth $200 in security tokens. Their current holding of security tokens is worth $1,800. Since the redemption could be settled without their holdings going below the local investor minimum holding of $1000, the redemption confirmation is allowed.
Total Investors Limit Module
Contract
TotalInvestorsLimitModule.sol
Associated Rules Engine
Rules Engine
Trigger
Creating a subscription order
Parameters
MAXIMUM_SUBSCRIPTION_INVESTORS_PER_ROUND: Maximum number of investors that can participate in a subscription round.
Explanation
There is a maximum number of investors that can participate in a subscription round, after which now new investors are permitted to subscribe. Already subscribed investors can continue to create orders normally.
Restrictions
The number of investors that created orders in the current subscription phase must be below the maximum subscription investors per round.
Example
In this example an investor is trying to create a subscription order. They already have holdings from previous rounds, but no orders previously created in the current one. There are already orders belonging to 165 different investors, and since the maximum subscription investors per round is 150, the investor is not allowed to create an order. They will have to wait until the current round finishes and create an order in the next round instead.
Redemption Modules
Forced Redemption Module
Contract
ForcedRedemptionModule.sol
Associated Rules Engine
Rules Engine
Trigger
Forcing a redemption
Parameters
GLOBAL_AGGREGATE_MINIMUM_BREACH: Indicates if the global aggregate amount of tokens has dropped below the minimum.LOCAL_INVESTOR_MINIMUM_HOLDING: Minimum amount of security tokens an investor needs to hold, denominated in USD using the instruments NAV.INSTRUMENT_TOKEN: Security token address.FORCED_REDEMPTION_TOP_UP_PERIOD: Period for which an investor can do top ups of their security token holdings before a forced redemption can be done. Expressed inFORCED_REDEMPTION_TOP_UP_PERIOD_UNIT.
Explanation
Forced redemptions are allowed whenever the investor's holdings are below the local minimum, or when the aggregate holdings of all investors are below the global minimum.
Restrictions
The global aggregate minimum must be breached, or the investor's holdings must be below the local minimum holding for longer than the duration of the top up period.
Example
In this example an admin is trying to perform a forced redemption for an investor, whose holdings are $6,430. In the past 7 days, their maximum holdings were $7,122. Since they were below the local investor minimum holding of $10,000 for all the top up period, the forced redemption is allowed, regardless of the global aggregate minimum not being breached.
Gate Criteria 1 Module
Contract
Gate1Module.sol
Associated Rules Engine
Rules Engine
Trigger
Settling redemption orders
Parameters
GATE_CRITERIA_1: Percent of the total supply that can be redeemed in a period, expressed in basis points (bps).INSTRUMENT_TOKEN: Security token address.
Explanation
The gate 1 criteria module limits the amount that can be redeemed in a period, based on the total existing supply. Amounts exceeding are reduced to fit this restriction.
Restrictions
The amount redeemed in a period must not surpass the gate 1 criteria, which is a percentage of the total supply of the security token.
If the aggregated amount to redeem is larger than the gate 1 criteria, only the amount allowed is redeemed, proportionally per each locked order.
Example
In this example, the total supply of the security token is 2300. An admin is performing a settlement of the two orders in the period by two different investors, of 170 and 290 security tokens respectively. Since the gate criteria one is 10%, the maximum allowed amount is 230, but the aggregated redemptions reach 460, double the allowed amount. Because of this, the order amount settled will be reduced proportionally, to 85 tokens for the first investor and 145 tokens for the second one. The orders will thus be partially settled, and the remaining pending amounts will be carried over to the next period.
Notice Period
Contract
NoticePeriodModule.sol
Associated Rules Engine
Rules Engine
Trigger
Settling redemption orders
Parameters
REDEMPTION_NOTICE_PERIOD: Period for which redemption orders cannot be settled after creation. Expressed inREDEMPTION_NOTICE_PERIOD_UNIT.
Explanation
Before settling a redemption order, the notice period for that order has to end.
Restrictions
The time between order creation and order settlement must exceed the notice period duration.
Example
In this example an admin is trying to settle an order recently created, 2 weeks prior. Since the redemption notice period is of 3 months, this settlement will not be allowed. The admin will have to wait until after the period has concluded in order to settle the order.
End Module
Contract
RedemptionEndModule.sol
Associated Rules Engine
Rules Engine
Triggers
Creating a redemption order
Confirming a redemption order
Settling redemption orders
Parameters
REDEMPTION_START: Start date for redemptions in an instrument.REDEMPTION_END: End date for redemptions in an instrument.
Explanation
The operations interacting with the redemption book need to happen between the redemption start and redemption end dates.
Restrictions
Operations must take place after redemption start.
Operations must take place before the redemption end.
Example
In this example, an investor is confirming a redemption order the 1st of May of 2024 (2024/05/01). Since this is after the redemption start (2024/04/25) and before the redemption end (2033/05/18), it is allowed.
Volume Limit Module
Contract
VolumeLimitModule.sol
Associated Rules Engine
Rules Engine
Trigger
Settling redemption orders
Parameters
INSTRUMENT_TOKEN: Security token address.REDEMPTION_VOLUME_LIMIT: Percent of the maximum amount of tokens held between all investors that can be settled per redemption round. Expressed in basis points (bps).REDEMPTION_LOOKBACK_PERIOD: Period of time the lookback is done on, expressed inREDEMPTION_LOOKBACK_PERIOD_UNIT.
Explanation
The volume limit module limits the amount that can be redeemed in a period, based on the maximum supply in the lookback period. Amounts exceeding are reduced to fit this restriction.
Restrictions
The amount redeemed in a period must not surpass the redemption volume limit, which is a percentage of the maximum supply of the security token during the redemption lookback period.
If the aggregated amount to redeem is larger than the volume limit, only the amount allowed is redeemed, proportionally per each locked order.
Example
In this example an admin is trying to settle redemption orders with an aggregated amount of 254,000 tokens. The maximum token supply in the last 12 months was of 823,000 tokens. Since the amount to settle is under de volume limit (50% of 823,000), the redemption is allowed.
Other Modules
Halt Module
Contract
HaltModule.sol
Associated Rules Engine
Rules Engine
Triggers
Transferring tokens
Forcing token transfers
Creating an order
Confirming an order
Locking an order
Cancelling an order
Settling orders
Parameters
GLOBAL_AGGREGATE_MINIMUM_BREACH: Indicates if the global aggregate amount of tokens has dropped below the minimum.REDEMPTION_BOOK: Redemption book address.
Explanation
Most operations are rejected whenever the system is halted, due to the global minimum holdings amount being breached.
Restrictions
System is not halted.
Example
In this example an investor is trying to confirm a subscription order. Since the global minimum has been breached, the system is halted, and this confirmation is not allowed. The investor must wait until the breach is resolved to be able to confirm their order.
Holdings Module
Contract
HoldingsModule.sol
Associated Rules Engine
Rules Engine
Trigger 1
Confirming a subscription or redemption order
Parameters 1
INSTRUMENT_TOKEN: Security token address.SUBSCRIPTION_BOOK: Subscription book address.REDEMPTION_BOOK: Redemption book address.UNAUDITED_NAV_PER_SHARE: Unaudited net asset value of the instrument, per each security token.LOCAL_INVESTOR_MINIMUM_HOLDING: Minimum amount of security tokens an investor needs to hold, denominated in USD using the instruments NAV.INVESTOR_MINIMUM_SUBSEQUENT_SUBSCRIPTION: Minimum amount of settlement tokens used when doing subsequent subscriptions.LOCAL_AGGREGATE_MINIMUM_HOLDING: Minimum holding amount between all investors for the feeder fund.
Explanation 1
When confirming subscription or redemption orders, investor specific minimums should be respected. This includes minimum subsequent subscription amounts as well, but only when the investor holdings are above the minimum.
Restrictions 1
The investor's security token balance should be above the local investor minimum holding or 0 when the order eventually gets settled.
If the investor's balance is above the local investor minimum holding, subscription order amounts should be above the investor minimum subsequent subscription.
Redemption orders must not make the aggregate holdings between investors go below the local aggregate minimum holding.
Example 1
In this example an investor is trying to confirm a redemption order. Their current holdings are worth $12,000. The order they are trying to confirm is for $1,500 in security tokens. Since the local aggregate minimum holding is $101,200, the order cannot be confirmed. This is because even though the investor would still be above the local investor minimum holding of $10,000, the local aggregate minimum holdings would be breached. The investor could alternatively confirm a redemption order of $1,200 or below to avoid the breach.
Trigger 2
Transferring tokens
Parameters 2
INSTRUMENT_TOKEN: Security token address.SUBSCRIPTION_BOOK: Subscription book address.REDEMPTION_BOOK: Redemption book address.UNAUDITED_NAV_PER_SHARE: Unaudited net asset value of the instrument, per each security token.LOCAL_INVESTOR_MINIMUM_HOLDING: Minimum amount of security tokens an investor needs to hold, denominated in USD using the instruments NAV.
Explanation 2
When transferring their tokens, investors need to keep their balance above the minimum holding, unless they are transferring their entire balance. Transfer between the addresses belonging to the same investor (internal transfers) are exempt.
Restrictions 2
Internal transfers between addresses of the same investor are allowed, and no restrictions are applied.
Transfers should result in investors' balances being above the local investor minimum holding, or 0.
As an exception to the previous, a transfer is allowed if the recipient investor's balance is above 0 but below the local investor minimum holding, even if the resulting balance would still be below this minimum.
The investor transferring their security tokens must have enough token holdings to cover the transfer, excluding tokens used for redemption confirmations.
Example 2
In this example, an investor is transferring token 462 security tokens to another investor, worth $564. The sender's holdings are $10,750 in total, with the recipient's being $27,340. The sender has a confirmed redemption order worth $750. Taking into account this redemption, the transfer would put their holdings below the local investor minimum holding of $10,000, and thus is not allowed to take place. The sender could cancel their redemption order to be able to perform the transfer.
Last updated