Conditions

The Roles SDK provides a convenient API for defining conditions on targets. Function inputs can be constrained to exact values, matched against patterns, or checked against condition functions.

Exact values

If a primitive, BigNumber, or array value is given, it will be used for an equality check. This also applies to placeholders. A contract function call will need to use this exact value to pass the condition.

To set an exact constraint on tuples, users can provide the expected tuple values as an array. To provide them as an object with named keys, it must be wrapped in a c.eq({ name: 'foo', age: 30 }) condition function, which enforces an exact match rather than a pattern match.

Matching patterns

If an object is given, it will be used as a matching pattern on tuples. In a matching pattern, the values to each key define the condition that shall be enforced on the respective parameter or tuple field. Each field condition can be either an exact value, a nested matching pattern, or a condition function.

Matching patterns can also be supplied as arrays using the c.matches([ 1, undefined, 3 ]) condition function. This allows using matching patterns on arrays or unnamed tuples. undefined elements in a pattern array will allow anything to pass for that tuple member.

Condition functions

Helper functions for defining conditions are provided under the c export:

import { c } from 'zodiac-roles-sdk;
 
c.or(1, 2, 3) // a condition that checks if a numeric parameter equals either of `1`, `2` or `3`

Comparisons

c.eq

See EqualTo operator

c.avatar

See EqualToAvatar operator

c.lt

Depending on the exact ABI type of the scoped parameter, maps to either a LessThan or a SignedIntLessThan operator.

c.gt

Depending on the exact ABI type of the scoped parameter, maps to either a GreaterThan or a SignedIntGreaterThan operator.

c.bitmask

See Bitmask operator

c.bitmask(params: {
  /** Offset in bytes at which to apply the mask, defaults to `0` */
  shift?: number
  /** The 15 bytes bitmask, each `1` means the bit at that position will be compared against the comparison value bit at the same position  */
  mask: BytesLike
  /** The 15 bytes comparison value, defines the expected value (`0` or `1`) for the bit at that position */
  value: BytesLike
})

Array conditions

c.some

See ArraySome operator

c.every

See ArrayEvery operator

c.subset

See ArraySubset operator

Branch conditions

c.and

See And operator

c.or

See Or operator

c.nor

See Nor operator

Tuple matching

c.matches

Allows defining a matching pattern to check the value against the current scope.

c.calldataMatches

The same as c.matches but skips over the first four bytes of the current scope, i.e. the function selector part of standard EVM call data.

This condition is most commonly used at the root node of the conditions tree for defining the conditions structure to be applied on the call parameters.

For this purpose, it takes the ABI types of all function parameters in the second argument. This information is required for encoding all sub conditions generated for the given matching pattern.

Additionally, c.calldataMatches can be used for setting conditions on bytes parameters that store standard-encoded EVM call data. There is a function overload that takes a permission object instead of a matching pattern + ABI types. This feature makes it convenient to use typed allow kits for scoping bytes parameters.

Example:

// Checks that bytes param in scope matches the calldata to the `claim_rewards(address)` function
// with the nested `address` param being equal to the address of the avatar
c.calldataMatches(
  allow.curve.stETH_ETH_gauge["claim_rewards(address)"](c.avatar)
);

Allowance conditions

c.withinAllowance

See WithinAllowance operator

c.etherWithinAllowance

See EtherWithinAllowance operator

c.callWithinAllowance

See CallWithinAllowance operator

Custom conditions

Not yet implemented in the SDK