Overview
Table of contents to the available rules
| Rule | Purpose |
|---|---|
| Pause | The purpose of the pause rule is to allow developers to pause the entirety of an application for maintenance, security or any other reason. Pausing the application means that no transfer of tokens is allowed at any level (with the few exceptions listed in the Role Applicability section). |
| Account Max Value By Risk | The account-max-value-by-risk-score rule enforces accumulated balance limits in U.S. dollars for user accounts based on a protocol assigned risk score to that account via the application manager. Risk scores are ranged between 0-99. Balance limits are set by range based on the risk scores given at rule creation. For example, if risk scores given in the array are: 25,50,75 and balance limits are: 500,250,100. The balance limit ranges are as follows: 0-24 = NO LIMIT, 25-49 = 500, 50-74 = 250, 75-99 = 100. |
| Account Max Value By Access Level | The purpose of this rule is to provide balance limits for accounts at the application level based on an application defined segment of users. The segments are defined as the access levels of the accounts. This rule may be used to provided gated accumulation of assets to ensure accounts cannot accumulate more assets without performing other actions defined by the application. For example, the application may decide users may not accumulate any assets without performing specific onboarding activities. The application developer may set a maximum balance of 1000 for the next access level. As accounts are introduced to the ecosystem, they may not receive any assets until the application changes their access level to a higher value. |
| Account Max Value Out By Access Level | The purpose of this rule is to provide limits on the amount of funds that an account can remove from the application’s economy based on an application defined segment of users. The segments are defined as the access levels of the accounts. This rule may be used to provide gated withdrawal limits of assets to ensure accounts cannot withdraw more US Dollars or chain native tokens without first performing other actions defined by the application. For example, the application may decide users may not withdraw without performing specific onboarding activities. The application developer may set the most restrictive withdraw limit of 1000 for the next access level. As accounts are introduced to the ecosystem, they may not withdraw from the ecosystem until the application changes their access level to a higher value. This rule does not prevent the accumulation of protocol supported assets. |
| Account Deny For No Access Level | The purpose of this rule is to provide a way to prevent the transfer of assets for accounts that do not have an access level or whose access level has been set to 0. For example, the application may decide users may not accumulate or transfer any assets without first performing specific onboarding activities. The application developer may set the account deny for no access level rule to active. As accounts are introduced to the ecosystem, they may not receive any assets until the application changes their access level to a higher value. |
| Oracle | The purpose of the account-approve-deny-oracle rule is to check if an address in the transaction is an approved or denied address. Addresses are added to the oracle lists by the owner of the oracle contract for any reason that the owner deems necessary. Oracle rules are applied per action type and for burn and sell actions the sender address is checked. For all other actions, the receiver address is checked. If an address is not on an approved oracle list, they will be denied from receiving application tokens. This rule can be used to restrict transfers to only specific contract addresses or wallets that are approved by the oracle owner. An example is NFT exchanges that support ERC2981 royalty payments. The deny list is designed as a tool to reduce the risk of malicious actors in the ecosystem. If an address is on the deny oracle list they are denied receiving tokens. Any address not on the deny list will pass this rule check. |
| Account Min/Max Token Balance | The account-min-max-token-balance rule enforces token balance thresholds for user accounts with specific tags. This allows developers to set lower and upper limits on the amount of each token the user account can hold. This rule attempts to mitigate the risk of token holders selling more than the minimum allowed amount and accumulating more than the maximum allowed amount of tokens for each specific tag. It can also be used to prevent token holders from rapidly flooding the market with newly acquired tokens since a dramatic increase in supply over a short time frame can cause a token price crash. This is done by associating an opional period with the rule. |
| Account Max Trade Size | The Account Max Trade Size Rule is an account based measure which restricts an account’s ability to buy or sell more of a token. This may be put in place to restrict large transactions from occurring against suspected malicious accounts or other accounts of interest. The amount of buys or sells allowed depends on the account’s tags. Different accounts may get different buy and sell restrictions depending on their tags. |
| Account Max Tx Value By Risk Score | The purpose of this rule is to prevent accounts identified as “risky” from moving large amounts of US Dollars in tokens within a specified period of time. This attempts to mitigate the existential, ethical or legal risks to an economy posed by such accounts. |
| Token Max Trading Volume | The purpose of the token-max-trading-volume rule is to reduce high trading volatility periods by allowing developers to set a maximum volume (as a percentage of the token’s total supply) that can be traded within a period of time. When the trading volume maximum is reached, transfers are suspended until the next period begins. Trading volume is the accumulated total number of tokens transferred during each period, and reset with each new period by the first transaction of that period. |
| Token Max Buy/Sell Volume | The token-max-buy-sell-volume rule enforces a limit on the amount of tokens purchased or sold during a certain time period. This rule sets the limit as a percentage of the token’s total supply. The rule will apply to the token designated when a buy or sell action is detected. |
| Token Max Supply Volatility | The purpose of this rule is to prevent a sudden increase or decrease in the supply of a token. This can help to prevent a sudden crash or spike in the price of a token due to sharp changes in the supply side, which could lead to severe damages to the health of the economy in the long run. |
| Token Max Daily Trades | The token-max-daily-trades rule enforces a daily limit on the number of trades for each token within a collection. In the context of this rule, a “trade” is a transfer of a token from one address to another. Example uses of this rule: to mitigate price manipulation of tokens in the collection via the limitation of wash trading or the prevention of malfeasance for holders who transfer a token between addresses repeatedly. When this rule is active and the tradesAllowedPerDay is 0 this rule will act as a pseudo “soulBound” token, preventing all transfers of tokens in the collection. |
| Token Minimum Hold Time | The purpose of the token-min-hold-time rule is to reduce trade volitility by preventing transfers of tokens for a number of hours after ownership is acquired, either via minting or transfers. This rule allows developers to specifiy a number of hours, up to 43830 (5 years), that each tokenId must be held for. |
| Token Minimum Transaction | The purpose of the token-min-tx-size rule is to prevent micro-trades or dust trades within an ecosystem. A developer can set the minimum number of tokens required per transfer to prevent these types of trades. |
How Rules Work
The protocol allows rule administrators to add rules to the Rule Processor Diamond. The rule id generated by the protocol is then used within an application to apply to user economic actions. The rules are immutable and cannot be removed or modified once created. A rule administator may add a new rule to the Rule Processor diamond at any time. The protocol will return a rule id that is used by the application to set the rule within each applicable handler contract.
Token level rules are applied in token handlers and application level rules in the application handler. Within each rule document above is the scope of that rule and the level in which it applies. Within the handler contract is a set rule function that receives the rule id for each applicable rule for that handler. A token handler does not have an activate function for application level rules and vice versa. The set rule function sets the rule per applicable economic action type. Each rule will only apply to the action types set in the activate rule function. Multiple action types may be used for each rule by sending all the desired types to the set rule function.
Rule application is a two step process. First, the rule admin must obtain a rule id, either from creating a rule or using an already created rule. Then, they must apply the rule id to the applicable handler through the appropriate set rule function. Once the rule is added to the protocol and set in the handler, all economic actions of that type will validate the action through the protocol using the provided rule parameters. The application developer sets the rule applicability and may activate and deactivate as needed. One or many rules may be active at a time.
Rule deactivation is done by sending a “false” boolean with the desired economic action types to the activate function. When rule active status is set to “false”, the economic action type will not be validated through the protocol. Rule admins can check the activation status of a rule at any time. Within the handler contracts are functions that return the activation status of the rule. The rule id for each rule and economic action type may be retrieved through the get rule id functions in each handler.