Syntax for Defining a Policy

Policies are submitted to the Rules Engine SDK in the form of a JSON string, with the following available properties:

Policy: a string representing the name of the policy
PolicyType: either open or closed (any contract can subscribe to an open policy whereas closed policies must approve the calling contract)
ForeignCalls (optional): an array of Foreign Call JSON objects (defined below)
Trackers (optional): an array of Tracker JSON objects (defined below)
MappedTrackers (optional): an array of Mapped Tracker JSON objects (defined below)
Rules: an array of Rule JSON objects (defined below)

If you are not yet familiar with the concepts of Foreign Calls, Trackers, and Rules, check out the linked concept docs. Here is a starting example:

{
  "Policy": "Alice's Policy",
  "PolicyType": "open",
  "CallingFunctions": [
    {
      "name": "transfer(address recipient, uint256 amount)",
      "functionSignature": "transfer(address recipient, uint256 amount)",
      "encodedValues": "address recipient, uint256 amount, uint256 receiverBalance"
    }
  ],
  "ForeignCalls": [
    {
      "name": "GetAccessLevel",
      "address": "0xB7f8BC63BbcaD18155201308C8f3540b07f84F5e",
      "function": "accessLevel(address)",
      "returnType": "uint256",
      "valuesToPass": "0"
    }
  ],
  "Trackers": [
    {
      "name": "largeTransactionCount",
      "type": "uint256",
      "initialValue": 0
    }
  ],
  "MappedTrackers": [
    {
      "name": "largeTransactionCountPerUser",
      "keyType": "address",
      "valueType": "uint256",
      "initialKeys": ["0xB7f8BC63BbcaD18155201308C8f3540b07f84F5e"],
      "initialValues": [0]
    }
  ],
  "Rules": [
    {
      "Name": "Access level check",
      "Description": "Checks access level on transfer",
      "condition": "(receiverBalance + amount > 100) AND (FC:GetAccessLevel < 1)",
      "positiveEffects": [
        "revert(\"Recipient Access Level too low to increase balance above 100\")"
      ],
      "negativeEffects": [],
      "callingFunction": "transfer(address recipient, uint256 amount)"
    },
    {
      "Name": "Large transaction check",
      "Description": "Alerts and tracks large transactions",
      "condition": "amount > 10000",
      "positiveEffects": ["emit Whale alert", "TRU:largeTransactionCount += 1"],
      "negativeEffects": [],
      "callingFunction": "transfer(address recipient, uint256 amount)"
    }
  ]
}

Calling Functions

The functions that when called will invoke the Policy. You define these in the CallingFunctions top level property with the following details:

name: The name of the calling function (can also be the same as the functionSignature)
functionSignature: The signature of the calling function, which includes argument types and names
encodedValues: a list of values that will be encoded along with the call to the rules engine from the calling contract

Foreign Calls

The ForeignCalls property contains an array of Foreign Call JSON objects. These represent all of the Foreign Calls that will be available within the policy. Each object consists of the following properties:

name: The name of the foreign call (this is how it will be referred to in Rule condition and effect expressions). This must include parentheses at the end, with at least one character in between the parentheses (the characters between the parentheses have no significance, this is a bit of a design bug we will remove soon).
address: The address of the foreign contract being called
function: The function signature of the function that will be called on the foreign contract
returnType: The return type of the function (currently supported types include: uint256, address, bytes and string)
valuesToPass: Currently, arbitrary data cannot be passed into the foreign call parameters. Only the data incoming from the Calling Contract can be used (the encodedValues in the Rule). This valuesToPass is a mapping of the encodedValues that will be utilized in the parameters to the foreign call. For foreign calls with more than one parameter the valuesToPass is represented as a comma separated list of indices, for example 0, 1, 2
- For example, imagine the Rule’s encodedValues are address to, uint256 value. You want to pass the address as the foreign call parameter, so you would set "valuesToPass": "0"

Trackers

The Trackers property contains an array of Tracker JSON objects. These represent all of the Trackers that will be available within the policy. Each object consists of the following properties:

name: The name of the tracker (this is how it will be referred to in Rule condition and effect expressions)
type: The type of the tracker (currently supported types include: uint256, address, bytes and string)
initialValue: The initial value of the tracker

Check out the Tracker Guide for more info on implementing, usage, and testing of trackers.

Mapped Trackers

The MappedTrackers property contains an array of Mapped Tracker JSON objects. These represent all of the Mapped Trackers that will be available within the policy. Each object consists of the following properties:

name: The name of the tracker (this is how it will be referred to in Rule condition and effect expressions)
keyType: The key type of the tracker (currently supported types include: uint256, address, bytes and string)
valueType: The value type of the tracker (currently supported types include: uint256, address, bytes and string)
initialKeys: The initial keys of the tracker
initialValues: The initial values of the tracker

Check out the Tracker Guide for more info on implementing, usage, and testing of trackers.

Rules

Now’s the fun part! The Rules property contains an array of rule definition objects. These represent all of the rules that are configured for the policy. Each object consists of the following properties:

Name: The name of the rule.
Description: A description of the rule.
condition: a string representing a conditional expression for the rule which must evaluate to a boolean (true or false) result. Specifics defined below
positiveEffects: an array of effect expressions to be executed if the condition evaluates to TRUE. Specifics defined below.
negativeEffects: an array of effect expressions to be executed if the condition evaluates to FALSE. Specifics defined below.
callingFunction: a string representation of the function signature this rule will be attached to, for example transfer(address recipient, uint256 amount)

Condition

Conditional expressions must evaluate to a boolean result. A conditional expression consists of values combined using operators, for example (receiverBalance + amount < 100) AND (FC:GetAccessLevel > 1). Values available to use in conditional expressions:

Static values of the following types: uint256, address, bytes (0x format), string
Referenced values:
- values encoded by the calling function. Referenced by the name listed in the encodedValues section for the rule.
- Trackers: trackers are referenced in the condition statement by TR: followed by the name of the tracker (as defined in the tracker JSON object in the policy), for example TR:largeTransactionCount
- MappedTrackers: mapped trackers are referenced in the condition statement by TR: followed by the name of the tracker (as defined in the tracker JSON object in the policy), followed by the key wrapped in parenthesis, for example TR:largeTransactionCount(sender)
- Result of a Foreign Call: foreign calls are referenced in the condition statement by FC: followed by the name of the foreign call (as defined in the foreign call JSON object in the policy), for example FC:GetAccessLevel

In the current version, strings are not character-delimited when using the SDK. Therefore, do not use special characters in strings like AND and OR or you will have unexpected behavior. If you use them in lowercase, there will be no problem.

Operators available to use in conditional expressions:

+: Add two values. Static values or references (must be uint values)
-: Subtract two values. Static values or references (must be uint values)
*: Multiply two values. Static values or references (must be uint values)
/: divide two values. Static values or references (must be uint values)
<: perform a less than comparison of two values. Static values or references (must be uint values)
>: perform a greater than comparison of two values. Static values or references (must be uint values)
<=: perform a less than or equal to comparison of two values. Static values or references (must be uint values)
>=: perform a greater than or equal to comparison of two values. Static values or references (must be uint values)
==: perform an equal to comparison of two values. Static values or references (all types supported)
AND: perform an AND operation on two expressions.
OR: perform an OR operation on two expressions.
( and ) : parenthesis allow for multiple “combined expressions” (described in detail in the NOTE below)

Order of operations is not assumed, it must be explicit. Any combination of more than 2 boolean expressions must be grouped using parentheses. For example:

Not Supported: 1 == 1 AND 2 == 2 OR 3 == 4
Supported: 1 == 1 AND (2 == 2 OR 3 == 4)

Effects (`positiveEffects` and `negativeEffects`)

Effects under the positiveEffects property are triggered if the rule Condition evaluates to TRUE. Effects under the negativeEffects property are triggered if the rule condition evaluates to false. Effects can be one of four types: revert, event, tracker update, or foreign call.

Revert Effects

A revert effect will revert the transaction when triggered. The syntax is: revert(“Revert message”), where the message is optional, so could also simply use revert. The message length limit is 32 bytes.

Event Effects

A event effect will emit an event when triggered. The syntax is: emit <Event message>, for example emit Whale alert!. This uses a generic event and logs the message.

Tracker Update Effects

A tracker update effect will update a tracker’s value when triggered. The syntax is TRU:<trackerName> <updateOperator> <expression>, for example TRU:largeTransactionCount += 1. The syntax for mapped tracker updates is TRU:<trackerName>(<key>) <updateOperator> <expression>, for example TRU:largeTransactionCount(sender) += 1. The name of the tracker is the name defined in the Trackers.name property. One of the following update operators must be used:

+=: add the value following the operator to the current value of the tracker (both tracker and value must be uint256 types)
-=: subtract the value following the operator from the current value of the tracker (both tracker and value must be uint256 types)
*=: multiply the value following the operator by the current value of the tracker (both tracker and value must be uint256 types)
/=: divide the tracker by the value following the operator (both tracker and value must be uint256 types)
=: assign the value of the tracker to the value after the operator (all types supported, uint256, address, bytes, string)

For the expression, this follows the same syntax as conditional expressions. Except, you will not use any relational or boolean operators (<, >, ==, AND, OR) since trackers cannot be booleans.

Special considerations should be taken when utilizing a tracker within an Open policy. Since the policy is open, any/all contracts may subscribe to the policy, therefore, update the trackers.

Foreign Call Effects

A foreign call effect will call a foreign contract when triggered. The syntax is the same as when using a foreign call to get a value for an expression, e.g. FC:UpdateVIPStatus.

Example Policies

Here are three more examples to help solidify the concepts.

Simple rule

Rule: Allow transfers if there is a minimum balance of 500 in the receiving wallet and don’t allow transfers if the amount being sent is more than 1000.

{
  "Policy": "Transfer Constraints",
  "PolicyType": "open",
  "CallingFunctions": [
    {
      "name": "transfer(address recipient, uint256 amount)",
      "functionSignature": "transfer(address recipient, uint256 amount)",
      "encodedValues": "address recipient, uint256 amount"
    }
  ],
  "ForeignCalls": [],
  "Trackers": [],
  "MappedTrackers": [],
  "Rules": [
    {
      "Name": "Transfer restrictions",
      "Description": "Limits transfer amounts and balances",
      "condition": "(receiverBalance + amount >= 500) AND (amount <= 1000)",
      "positiveEffects": [],
      "negativeEffects": ["revert(\"Transfer violates constraints\")"],
      "callingFunction": "transfer(address recipient, uint256 amount)"
    }
  ]
}

Rule using a Foreign Call

Rule: Block transfers over 50,000 unless the sender is a VIP.

{
  "Policy": "VIP Transfer Restriction",
  "PolicyType": "open",
  "CallingFunctions": [
    {
      "name": "transfer(address recipient, uint256 amount)",
      "functionSignature": "transfer(address recipient, uint256 amount)",
      "encodedValues": "address recipient, uint256 amount"
    }
  ],
  "ForeignCalls": [
    {
      "name": "isVIP",
      "address": "0x95222290DD7278Aa3Ddd389Cc1E1d165CC4BAfe5",
      "function": "isVIP(address)",
      "returnType": "uint256",
      "valuesToPass": "0"
    }
  ],
  "Trackers": [],
  "MappedTrackers": [],
  "Rules": [
    {
      "Name": "Transfer restrictions",
      "Description": "Limits transfer amounts and balances",
      "condition": "(amount > 50000) AND (FC:isVIP(recipient) == 0)",
      "positiveEffects": ["revert(\"Only VIP can transfer over 50K\")"],
      "negativeEffects": [],
      "callingFunction": "transfer(address recipient, uint256 amount)"
    }
  ]
}

Rule using a Tracker

Rule: Only allow 5 mints per day.

{
  "Policy": "Daily Mint Limit",
  "PolicyType": "open",
  "CallingFunctions": [
    {
      "name": "mint(uint256 amount)",
      "functionSignature": "mint(uint256 amount)",
      "encodedValues": "uint256 amount"
    }
  ],
  "ForeignCalls": [],
  "Trackers": [
    {
      "name": "dailyMintCount",
      "type": "uint256",
      "initialValue": 0
    }
  ],
  "MappedTrackers": [],
  "Rules": [
    {
      "Name": "Mint restrictions",
      "Description": "Limits mints",
      "condition": "TR:dailyMintCount < 5",
      "positiveEffects": ["TRU:dailyMintCount += 1"],
      "negativeEffects": ["revert(\"Daily mint limit reached\")"],
      "callingFunction": "mint(uint256 amount)"
    }
  ]
}

Rule using a Mapped Tracker

Rule: Only allow 5 mints per day per address.

{
  "Policy": "Daily Mint Limit Per Address",
  "PolicyType": "open",
  "CallingFunctions": [
    {
      "name": "mint(uint256 amount)",
      "functionSignature": "mint(uint256 amount)",
      "encodedValues": "uint256 amount"
    }
  ],
  "ForeignCalls": [],
  "Trackers": [],
  "MappedTrackers": [
    {
      "name": "dailyMintCount",
      "keyType": "address",
      "valueType": "uint256",
      "initialKeys": ["0xB7f8BC63BbcaD18155201308C8f3540b07f84F5e"],
      "initialValues": [0]
    }
  ],
  "Rules": [
    {
      "Name": "Mint restrictions",
      "Description": "Limits mints",
      "condition": "TR:dailyMintCount(minter) < 5",
      "positiveEffects": ["TRU:dailyMintCount(minter) += 1"],
      "negativeEffects": ["revert(\"Daily mint limit reached\")"],
      "callingFunction": "mint(uint256 amount)"
    }
  ]
}

Get Started

Core Concepts

Guides

Policy Configuration

Syntax for Defining a Policy

Calling Functions

Foreign Calls

Trackers

Mapped Trackers

Rules

Condition

Effects (`positiveEffects` and `negativeEffects`)

Revert Effects

Event Effects

Tracker Update Effects

Foreign Call Effects

Example Policies

Simple rule

Rule using a Foreign Call

Rule using a Tracker

Rule using a Mapped Tracker

Get Started

Core Concepts

Guides

​Syntax for Defining a Policy

​Calling Functions

​Foreign Calls

​Trackers

​Mapped Trackers

​Rules

​Condition

​Effects (positiveEffects and negativeEffects)

​Revert Effects

​Event Effects

​Tracker Update Effects

​Foreign Call Effects

​Example Policies

​Simple rule

​Rule using a Foreign Call

​Rule using a Tracker

​Rule using a Mapped Tracker

Syntax for Defining a Policy

Calling Functions

Foreign Calls

Trackers

Mapped Trackers

Rules

Condition

Effects (`positiveEffects` and `negativeEffects`)

Revert Effects

Event Effects

Tracker Update Effects

Foreign Call Effects

Example Policies

Simple rule

Rule using a Foreign Call

Rule using a Tracker

Rule using a Mapped Tracker