Policy Engine

The Policy Engine APIs evaluate policies (a set of rules) to govern the behavior of accounts or projects, such as enforce allowlists and denylists.

• A policy is a collection of rules with defined criteria.
• Each rule contains a specified action, operation, and criteria:
  • An action can either accept or reject a transaction if the criteria in the rule are met.
  • criteria is an array of logical expressions. All parameters must evaluate to true for the action to be applied.
  • An operation corresponds to a CDP v2 API:
    • signEvmTransaction or signSolTransaction for signing transactions (to set a transaction limit)
    • sendEvmTransaction for signing a transaction, and sending it to a supported network
    • signEvmHash for signing an arbitrary 32 byte hash.
    • signEvmMessage for signing an EIP-191 message.
    • prepareUserOperation for preparing user operations on a smart account.
    • sendUserOperation for sending user operations using a smart account.
• A rule indicates how an operation should behave, specifying whether a request with defined criteria should be accepted or rejected. Only signEvmTransaction and signSolTransaction operations are currently supported.

​

Policy Scope

Policies can be applied at the project and/or account level:

• Project-level policy: A project-level policy applies to all accounts in a CDP Project. Only one project-level policy can be applied to accounts within a CDP Project at any given time.
• Account-level policy: An account-level policy applies to one or more accounts. An account can have at most one account-level policy at any given time.

Thus, a single account can be assigned at most two policies at any given time: one project-level policy and one account-level policy.

Scope is specified in the scope field of a policy:

  "description": "Project-level policy",
  "scope": "account",
  ...

​

Policy Evaluation

Project-level policies are evaluated first, followed by account-level policies. The Policy Engine will process the request against each rule in the order it is defined within the rules array:

1. If the rule’s criteria (processed as a logical AND operation applied to a list of independently evaluated boolean expressions) are met, accept or reject behavior is applied immediately and the engine stops further evaluation of the policy.
2. If after policy evaluation, no rule’s criteria are met, the engine moves to processing the next policy (i.e., an account-level policy).
3. If no further policies exist, the request is rejected.

For example, the following policy is a project-level policy with two rules. The Policy Engine will:

1. Evaluate the first rule: For a signEvmTransaction request, accept the request if the transaction is less than or equal to 1000000000000000000 wei OR
2. Evaluate the second rule: if the request is a signEvmTransaction request, accept the request if the transaction is less than or equal to 2000000000000000000 wei AND the request is made to the address 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE.
3. If the request does not meet the criteria of either rule, the engine will move on to evaluate an account-level policy (if one exists).
4. Otherwise, the request is rejected.

Rules are processed in the order they are defined. Once a rule applies to an operation, subsequent rules are ignored.

{
  "description": "Project-level policy",
  "scope": "project",
  "rules": [
    {
      "action": "accept",
      "operation": "signEvmTransaction",
      "criteria": [
        {
          "type": "ethValue",
          "ethValue": "1000000000000000000",
          "operator": "<="
        }
      ]
    },
    {
      "action": "accept",
      "operation": "signEvmTransaction",
      "criteria": [
        {
          "type": "ethValue",
          "ethValue": "2000000000000000000",
          "operator": "<="
        },
        {
          "type": "evmAddress",
          "addresses": [
            "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE"
          ],
          "operator": "in"
        }
      ]
    }
  ]
}

​

Policy Application

Project-level policies are applied to all accounts in a CDP Project. They will apply retroactively even if the project-level policy is created after the account was created. To disable a project-level policy, you must remove the project-level policy from the CDP Project using the deletePolicy operation.

Account-level policies can be applied in two ways:

• By specifying the accountPolicy field in the request body of the createEvmAccount and createSolAccount operations.

• By specifying the accountPolicy field in the request body of the updateEvmAccount and updateSolanaAccount operations.

​

Criteria

The following criteria are supported:

​

SignEvmTransaction Criteria

​

ethValue

A criterion based on the value of the transaction. The transaction’s value field is compared to the criterion’s ethValue field using the operator field.

​

evmAddress

A criterion based on the recipient address of the transaction. The transaction’s to field is compared to the criterion’s addresses field using the operator field.

​

evmData

A criterion based on encoded transaction data that evaluates the function being called, as well as any number of arguments accessed by either name or index. Currently this criterion only supports primitive types; string, bool, uint(8,16,32,64,256), int(8,16,32,64,256), address, and both fixed and dynamic length bytes.

​

SendEvmTransaction Criteria

​

ethValue

A criterion based on the value of the transaction. The transaction’s value field is compared to the criterion’s ethValue field using the operator field.

​

evmAddress

A criterion based on the recipient address of the transaction. The transaction’s to field is compared to the criterion’s addresses field using the operator field.

​

evmNetwork

A criterion based on the intended network of the transaction. The network field in the sendEvmTransaction request body is compared to the criterion’s networks field using the operator field.

​

evmData

A criterion based on encoded transaction data that evaluates the function being called, as well as any number of arguments accessed by either name or index. Currently this criterion only supports primitive types; string, bool, uint(8,16,32,64,256), int(8,16,32,64,256), address, and both fixed and dynamic length bytes.

​

SendUserOperation Criteria

​

ethValue

A criterion based on the value of the user operation. The operation’s value fields are compared to the criterion’s ethValue field using the operator field.

​

evmAddress

A criterion based on the recipient address of the operation. The operation’s to fields are compared to the criterion’s addresses field using the operator field.

​

evmData

A criterion based on encoded transaction data that evaluates the function being called, as well as any number of arguments accessed by either name or index. Currently this criterion only supports primitive types; string, bool, uint(8,16,32,64,256), int(8,16,32,64,256), address, and both fixed and dynamic length bytes.

​

PrepareUserOperation Criteria

​

ethValue

A criterion based on the value of the user operation. The operation’s value fields are compared to the criterion’s ethValue field using the operator field.

​

evmAddress

A criterion based on the recipient address of the user operation. The operation’s to fields are compared to the criterion’s addresses field using the operator field.

​

evmNetwork

A criterion based on the intended network of the user operation. The network field in the prepareUserOperation request body is compared to the criterion’s networks field using the operator field.

​

evmData

A criterion based on encoded transaction data that evaluates the function being called, as well as any number of arguments accessed by either name or index. Currently this criterion only supports primitive types; string, bool, uint(8,16,32,64,256), int(8,16,32,64,256), address, and both fixed and dynamic length bytes.

​

SignEvmHash Criteria

The signEvmHash operation does not accept any criteria. To prevent this operation from being executed by any account, specify a rule with signEvmHash as the operation, and reject as its action.

​

SignEvmMessage Criteria

​

evmMessage

A criterion based on the intended message to be signed. The match field in the criteria is a RE2 compliant regular expression that will be executed against the message in the API request.

​

SignSolTransaction Criteria

​

solAddress

A criterion based on the recipient addresses of the transaction. The criterion’s address field is compared to the list of addresses in the transaction’s accountKeys (for legacy transactions) or staticAccountKeys (for V0 transactions) array using the operator field.

​

Restricting Contract Interactions on Ethereum

Smart contract function restrictions serve as a critical security and governance mechanism in decentralized applications, allowing developers and organizations to implement fine-grained access controls over their protocol interactions. One of the primary use cases for function restrictions is protecting high-risk operations from unauthorized access such as:

• Fund transfers - Contract upgrades - Parameter modifications - Emergency pauses Policy Engine supports such restrictions that evaluate against transaction data with the evmData criterion for the signEvmTransaction, and sendEvmTransaction operations.

​

Examples

​

Limiting USDC Spend

This policy restricts USDC transactions on the Base network to transfers of 10,000 tokens or less. It applies to both signing and sending transactions to the USDC contract address, using the ERC20 ABI to validate that only transfer function calls with a value parameter under the specified limit are permitted.

  "description": "Limit USDC Spend",
  "scope": "account",
  "rules": [
    {
      "action": "accept",
      "operation": "sendEvmTransaction",
      "criteria": [
        {
          "type": "evmNetwork",
          "networks": ["base"],
          "operator": "in"
        },
        {
          "type": "evmAddress",
          "addresses": ["0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"],
          "operator": "in"
        },
        {
          "type": "evmData",
          "abi": "erc20",
          "conditions": [
            {
              "function": "transfer",
              "params": [
                {
                  "name": "value",
                  "operator": "<=",
                  "value": "10000"
                }
              ]
            }
          ]
        }
      ]
    },
    {
      "action": "accept",
      "operation": "signEvmTransaction",
      "criteria": [
        {
          "type": "evmAddress",
          "addresses": ["0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"],
          "operator": "in"
        },
        {
          "type": "evmData",
          "abi": "erc20",
          "conditions": [
            {
              "function": "transfer",
              "params": [
                {
                  "name": "value",
                  "operator": "<=",
                  "value": "10000"
                }
              ]
            }
          ]
        }
      ]
    }
  ]
} ```.