Skip to content

DeFi Whitelisting Rules

Overview

Gatekeeper's whitelisting engine evaluates the decoded transaction against a set of rule conditions. Rules are defined as declarative policy objects, grouped into a "protocol preset", and then loaded into the Gatekeeper instance as part of the bundle (see Architecture).

There are two major challenges when building DeFi whitelisting rules.

  1. Knowing what to allow and what constraints to enforce
  2. Ensuring that the desired activity is permitted, but ONLY that activity.

A Basic Example

Let's take a ERC-4626 vault on a lending protocol. Say, Aave v3.

Goal: allow basic supply & withdraw operations on a single Pool.

The Naive Approach: simply add the contract address to an Allowlist.

Let's dig deeper: The vault has a supply function to deposit assets into the vault to earn yield or use as collateral.

The function looks like this:

supply(address asset,uint256 amount,address onBehalfOf,uint16 referralCode)

If that 3rd param - onBehalfOf - is not the sender, then this deposits funds...on behalf of another account.

This has very legitimate use-cases at the protocol level, but for a typical user depositing from their own wallet, that parameter should ALWAYS match their address.

Address-only allowlists are not enough. Function-level allowlists are also not enough.

Even simple scenarios require a dynamic parameter-level constraint.

So what's our rule criteria?

  • Transaction to must match the Aave pool address, on the correct chain.
  • The function selector must be supply.
  • The onBehalfOf parameter must match the sender's address.

Okay great! Simple enough. Ship to prod.

But wait. Users still can't deposit.

The supplied asset needs to have an allowance set first.

We need to call the approve function on our token (let's say, USDC). The function looks like this:

approve(address _spender, uint256 _value)

Now we add another rule with the following criteria:

  • Transaction to must match the USDC token address, on the correct chain.
  • The function selector must be approve.
  • The _spender parameter must match the Aave pool address.

Great! Now repeat this for the other functions we want to allow.

Gatekeeper's Approach

Gatekeeper decouples this process from the rest of your stack, encapsulating the complexity of DeFi whitelisting into a lightweight service.

  • Rule criteria are defined as declarative configuration. No new code needed per-protocol.
  • Support for nested transactions, bundled/multicall transactions, and off-chain message/data signature requests.
  • Narval provides pre-built whitelisting presets for a growing catalog of DeFi protocols, and can support on custom rule definition.
  • We run extensive testing against thousands of transaction variants to ensure rules only permit exactly the desired activity.

How it Works

  1. Decide the whitelisting rule to use, or create a new one.
  2. Ensure it's included in your Gatekeeper bundle.
  3. Pass the protocolPreset in your /evaluate request.