Skip to main content
The Contract Whitelist Policy enforces strict access control for blockchain transactions by ensuring that Vincent Apps can only interact with pre-approved smart contracts and execute specific whitelisted functions on those contracts. What contract functions are whitelisted is specified per contract, per chain ID, enabling fine grained control over which contracts are accessible on each blockchain network and precisely which functions can be called on those contracts.

​
Key Features

  • Multi-chain Support: Configure whitelists for multiple blockchain networks
  • Granular Function Control: Specify which functions are whitelisted using the Solidity function signature
  • Wildcard Support: Allow all functions for trusted contracts using the * wildcard

​
How It Works

The Contract Whitelist Policy is built using the Vincent Policy SDK and validates transactions against a hierarchical whitelist:
1

Transaction Parsing

Receives a serialized EVM transaction and parses it using ethers.js to extract the necessary components for validation.
2

Data Extraction

Extracts the chain ID (the chainId field in the transaction), target contract address (the to field in the transaction), and function selector (first 4 bytes of the transaction data field).
3

Whitelist Validation

Checks the transaction against the configured on-chain whitelist:
  • Is the chain ID whitelisted?
  • Is the contract address whitelisted for that chain?
  • Is the function selector allowed (explicitly or via wildcard)?
4

Result

Returns an allow or deny response with additional details about the validation outcome.

​
Getting Started

Depending on your role in the Vincent Ecosystem, you’ll be interacting with this Policy in different ways. Click on the link below that matches your role to see how to get started with this Policy:
  • Vincent App Managers: If you’ve created or are creating a Vincent App and you want to enable this Policy for your users to govern the execution of Vincent Abilities, go here.
  • Vincent App Delegatees: If you are a delegatee of a Vincent App that has a Vincent Ability enabled that supports this Policy, go here.
  • Vincent Ability Developers: If you’ve create or are creating a Vincent Ability and you want to support this Policy, go here.

​
Adding the Policy to your Vincent App

Vincent Abilities determine which Vincent Policies they support. Your Vincent App can only enabled this Policy for your users if a Vincent Ability your App uses has been configured to work with that Policy - Policies are per Ability, so one Ability supporting this Policy doesn’t mean your App can enable this Policy for every Ability it uses. If the Abilities your App uses have not been configured to support this Policy, you can contact the developers of those Abilities to request that they do so, or you can fork their code and enable the Policy yourself (also see the Ability Quickstart Guide to learn more about how to create your own Vincent Ability).

​
Executing a Vincent Ability that Supports this Policy

If you are a Delegatee to a Vincent App that has a Vincent Ability enabled that supports this Policy, there are a couple of things to be aware of as you execute Vincent Abilities on behalf of your users.

​
What’s Whitelisted

Vincent App Users set what contracts and functions are whitelisted per chain using the Policy parameters that are stored in the Vincent Registry contract. The Vincent App Users are able to update the whitelist at will, so you cannot rely on what contracts and functions are whitelisted for each chain when you execute an Ability on behalf of your users.

​
Checking Against the Whitelist

When you execute an Ability’s precheck function, and the Vincent User has enabled this Policy for the Ability, the precheck function of this Policy will also execute. This Policy’s precheck function will perform the same validation as the actual execution of the Policy, which will parse the transaction and check the chainId, to address, and function selector against the whitelist.
  • Allow Response
  • Deny Response
If the contract and function you’re trying to interact with on the Vincent User’s behalf is whitelisted, the precheck function will return Allow Response with the structure:
{
  chainId: number; // The validated chain ID
  contractAddress: string; // The validated contract address
  functionSelector: string; // The validated function selector
  wildcardUsed: boolean; // Whether wildcard was used for approval
}
The wildcardUsed field indicates whether the function was allowed via wildcard:
  • true: Function was allowed via wildcard
  • false: Function was explicitly whitelisted

​
Supporting this Policy in your Vincent Ability

If you’d like to provide the users of your Vincent Ability with the ability to restrict what contracts and functions Vincent Apps can interact with on their behalf, you can integrate this Policy into your Ability.
  • Installation
  • Configuration
  • Integration
Start by installing the @lit-protocol/vincent-policy-contract-whitelist package:
npm install --save @lit-protocol/vincent-policy-contract-whitelist
⌘I