ERC-2746: 规则引擎标准

pragma solidity ^0.6.0;

/**
    @title ERC-2746 Rules Engine Standard
    @dev See https://eips.ethereum.org/EIPS/eip-2746
 */
 interface ERCRulesEngine {

    /**
        @dev Should emit when a RuleTree is invoked.
        @dev 应该在 RuleTree 被调用时发出。
        The `ruler` is the ID and owner of the RuleTree being invoked.  It is also likely msg.sender.
        `ruler`是被调用的 RuleTree 的 ID 和所有者。它也可能是 msg.sender。
    */
    event CallRuleTree(
        address indexed ruler
    );

    /**
        @dev Should emit when a RuleSet is invoked.
        @dev 应该在 RuleSet 被调用时发出。
        The `ruler` is the ID and owner of the RuleTree in which the RuleSet is stored.  It is also likely msg.sender.
        `ruler`是存储 RuleSet 的 RuleTree 的 ID 和所有者。它也可能是 msg.sender。
        The 'ruleSetId' is the ID of the RuleSet being invoked.
        'ruleSetId'是被调用的 RuleSet 的 ID。
    */
    event CallRuleSet(
        address indexed ruler,
        bytes32 indexed tmpRuleSetId
    );

    /**
        @dev Should emit when a Rule is invoked.
        @dev 应该在 Rule 被调用时发出。
        The `ruler` is the ID and owner of the RuleTree in which the RuleSet is stored.  It is also likely msg.sender.
        `ruler`是存储 RuleSet 的 RuleTree 的 ID 和所有者。它也可能是 msg.sender。
        The 'ruleSetId' is the ID of the RuleSet being invoked.
        'ruleSetId'是被调用的 RuleSet 的 ID。
        The 'ruleId' is the ID of the Rule being invoked.
        'ruleId'是被调用的 Rule 的 ID。
        The 'ruleType' is the type of the rule being invoked.        
        'ruleType'是被调用的规则的类型。
    */
    event CallRule(
        address indexed ruler,
        bytes32 indexed ruleSetId,
        bytes32 indexed ruleId,
        uint ruleType
    );

    /**
        @dev Should emit when a RuleSet fails.
        @dev 应该在 RuleSet 失败时发出。
        The `ruler` is the ID and owner of the RuleTree in which the RuleSet is stored.  It is also likely msg.sender.
        `ruler`是存储 RuleSet 的 RuleTree 的 ID 和所有者。它也可能是 msg.sender。
        The 'ruleSetId' is the ID of the RuleSet being invoked.
        'ruleSetId'是被调用的 RuleSet 的 ID。
        The 'severeFailure' is the indicator of whether or not the RuleSet is a leaf with a 'severe' error flag.
        'severeFailure'是指示 RuleSet 是否是具有“严重”错误标志的叶子的指标。
    */
    event RuleSetError (
        address indexed ruler,
        bytes32 indexed ruleSetId,
        bool severeFailure
    );	

    /**
        @notice Adds a new Attribute to the data domain.
        @dev 向数据域添加新属性。
        @dev Caller should be the deployer/owner of the rules engine contract.  An Attribute value can be an optional alternative if it's not a string or numeric.
        @dev 调用者应为规则引擎合约的部署者/所有者。如果属性值不是字符串或数字，则它可以是可选的替代值。
        @param _attrName    Name/ID of the Attribute
        @param _attrName    属性的名称/ID
        @param _maxLen      Maximum length of the Attribute (if it is a string)
        @param _maxLen      属性的最大长度（如果它是字符串）
        @param _maxNumVal   Maximum numeric value of the Attribute (if it is numeric)
        @param _maxNumVal   属性的最大数值（如果它是数字）
        @param _defaultVal  The default value for the Attribute (if one is not found from the source)
        @param _defaultVal  属性的默认值（如果从源中找不到）
        @param _isString    Indicator of whether or not the Attribute is a string
        @param _isString    指示属性是否为字符串
        @param _isNumeric   Indicator of whether or not the Attribute is numeric
        @param _isNumeric   指示属性是否为数字
    */    
    function addAttribute(bytes32 _attrName, uint _maxLen, uint _maxNumVal, string calldata _defaultVal, bool _isString, bool _isNumeric) external;

    /**
        @notice Adds a new RuleTree.
        @notice 添加新的 RuleTree。
        @param _owner          Owner/ID of the RuleTree
        @param _owner          RuleTree 的所有者/ID
        @param _ruleTreeName   Name of the RuleTree
        @param _ruleTreeName   RuleTree 的名称
        @param _desc           Verbose description of the RuleTree's purpose
        @param _desc           RuleTree 用途的详细描述
    */
    function addRuleTree(address _owner, bytes32 _ruleTreeName, string calldata _desc) external;

    /**
        @notice Adds a new RuleSet onto the hierarchy of a RuleTree.
        @notice 在 RuleTree 的层次结构上添加新的 RuleSet。
        @dev RuleSets can have child RuleSets, but they will only be called if the parent's Rules execute to create boolean 'true'.
        @dev RuleSet 可以有子 RuleSet，但只有在父级的规则执行结果为布尔值“true”时才会调用它们。
        @param _owner           Owner/ID of the RuleTree
        @param _owner           RuleTree 的所有者/ID
        @param _ruleSetName     ID/Name of the RuleSet
        @param _ruleSetName     RuleSet 的 ID/名称
        @param _desc            Verbose description of the RuleSet
        @param _desc            RuleSet 的详细描述
        @param _parentRSName    ID/Name of the parent RuleSet, to which this will be added as a child
        @param _parentRSName    父 RuleSet 的 ID/名称，将作为子 RuleSet 添加到其中
        @param _severalFailFlag Indicator of whether or not the RuleSet's execution (as failure) will result in a failure of the RuleTree.  (This flag only applies to leaves in the RuleTree.)
        @param _severalFailFlag 指示 RuleSet 的执行（作为失败）是否会导致 RuleTree 失败。 （此标志仅适用于 RuleTree 中的叶子。）
        @param _useAndOp        Indicator of whether or not the rules in the RuleSet will execute with 'AND' between them.  (Otherwise, it will be 'OR'.)
        @param _useAndOp        指示 RuleSet 中的规则是否将使用“AND”运算符执行。 （否则，它将是“OR”。）
        @param _failQuickFlag   Indicator of whether or not the RuleSet's execution (as failure) should immediately stop the RuleTree.
        @param _failQuickFlag   指示 RuleSet 的执行（作为失败）是否应立即停止 RuleTree。
    */    
    function addRuleSet(address _owner, bytes32 _ruleSetName, string calldata _desc, bytes32 _parentRSName, bool _severalFailFlag, bool _useAndOp, bool _failQuickFlag) external;

    /**
        @notice Adds a new Rule into a RuleSet.
        @notice 将新规则添加到规则集。
        @dev Rule types can be implemented as any type of action (greater than, less than, etc.)
        @dev 规则类型可以实现为任何类型的操作（大于、小于等）
        @param _owner           Owner/ID of the RuleTree
        @param _owner           RuleTree 的所有者/ID
        @param _ruleSetName     ID/Name of the RuleSet to which the Rule will be added
        @param _ruleSetName     将添加规则的规则集的 ID/名称
        @param _ruleName        ID/Name of the Rule being added
        @param _ruleName        要添加的规则的 ID/名称
        @param _attrName        ID/Name of the Attribute upon which the Rule is invoked
        @param _attrName        调用规则的属性的 ID/名称
        @param _ruleType        ID of the type of Rule
        @param _ruleType        规则类型的 ID
        @param _rightHandValue  The registered value to be used by the Rule when performing its action upon the Attribute
        @param _rightHandValue  规则在对属性执行操作时使用的已注册值
        @param _notFlag         Indicator of whether or not the NOT operator should be performed on this Rule.
        @param _notFlag         指示是否应对此规则执行 NOT 运算符。
    */    
    function addRule(address _owner, bytes32 _ruleSetName, bytes32 _ruleName, bytes32 _attrName, uint _ruleType, string calldata _rightHandValue, bool _notFlag) external;

    /**
        @notice Executes a RuleTree.
        @notice 执行规则树。
        @param _owner           Owner/ID of the RuleTree
        @param _owner           RuleTree 的所有者/ID
    */
    function executeRuleTree(address _owner) external returns (bool);
    
    /**
        @notice Retrieves the properties of a Rule.
        @notice 检索规则的属性。
        @param _owner           Owner/ID of the RuleTree
        @param _owner           RuleTree 的所有者/ID
        @param _ruleSetName     ID/Name of the RuleSet where the Rule resides
        @param _ruleSetName     规则所在的 RuleSet 的 ID/名称
        @param _ruleIdx         Index of the rule in the RuleSet's listing 
        @param _ruleIdx         规则在 RuleSet 列表中的索引
        @return bytes32         ID/Name of Rule
        @return bytes32         规则的 ID/名称
        @return uint            Type of Rule
        @return uint            规则类型
        @return bytes32         Target Attribute of Rule
        @return bytes32         规则的目标属性
        @return string          Value mentioned in Rule
        @return string          规则中提到的值
        @return bool            Flag for NOT operator in Rule
        @return bool            规则中 NOT 运算符的标志
        @return bytes32[]       Values that should be provided in delegated call (if Rule is custom operator)
        @return bytes32[]       应在委托调用中提供的值（如果规则是自定义运算符）
    */
    function getRuleProps(address _owner, bytes32 _ruleSetName, uint _ruleIdx) external returns (bytes32, uint, bytes32, string memory, bool, bytes32[] memory);

    /**
        @notice Retrieves the properties of a RuleSet
        @notice 检索 RuleSet 的属性
        @param _owner        Owner/ID of the RuleTree
        @param _owner        RuleTree 的所有者/ID
        @param _ruleSetName  ID/Name of the RuleSet
        @param _ruleSetName  RuleSet 的 ID/名称
        @return string       Verbose description of the RuleSet
        @return string       RuleSet 的详细描述
        @return bool         Flag that indicates whether this RuleSet's failure (if a leaf) will cause the RuleTree to fail
        @return bool         指示此 RuleSet 的失败（如果是叶子）是否会导致 RuleTree 失败的标志
        @return bool         Flag that indicates whether this RuleSet uses the AND operator when executing rules collectively
        @return bool         指示此 RuleSet 在集体执行规则时是否使用 AND 运算符的标志
        @return uint         Indicates the number of rules hosted by this RuleSet
        @return uint         指示此 RuleSet 托管的规则数
        @return uint         The quantity of child RuleSets
        @return uint         子规则集的数量
        @return bytes32[]    The list of RuleSets that are children of this RuleSet
        @return bytes32[]    作为这个 RuleSet 的子 RuleSet 列表
    */
    function getRuleSetProps(address _owner, bytes32 _ruleSetName) external returns (string memory, bool, bool, uint, uint, bytes32[] memory);

    /**
        @notice Retrieves the properties of a RuleSet
        @notice 检索 RuleSet 的属性
        @param _owner        Owner/ID of the RuleTree
        @param _owner        RuleTree 的所有者/ID
        @return bytes32      Name of the RuleTree
        @return bytes32      RuleTree 的名字
        @return string       Verbose description of the RuleTree
        @return string       RuleTree 的详细描述
        @return bytes32      ID/Name of the RuleSet that serves as the root node for the RuleTree
        @return bytes32      作为 RuleTree 根节点的 RuleSet 的 ID/名称
    */
    function getRuleTreeProps(address _owner) external returns (bytes32, string memory, bytes32);
    
    /**
        @notice Removes a RuleTree.
        @notice 移除一个 RuleTree。
        @param _owner           Owner/ID of the RuleTree
        @param _owner           RuleTree 的所有者/ID
    */
    function removeRuleTree(address _owner) external returns (bool);    
}