Overview

5.0.0 (2025-05-05)

New Features

Version 5 of the Transfer Validator is focused on making improvements that keep up with changes on the Ethereum network to preserve the wallet to wallet OTC transfers in most cases and to add new features enabled by EIP-7702. In Version 5, Limit Break also goes beyond the scope of EIP-7702 and has future-proofed the Transfer Validator so that future updates can be made in order to keep up with additional changes to Ethereum that haven't even been considered or proposed yet. The re-design of the Transfer Validator will allow Limit Break to continue to adapt to future EIPs that could impact 20-C/721-C/1155-C without requiring migrations or actions from creators to keep up-to-date. The following subsections detail the key changes made from Version 4 to Version 5.

• Replaced Transfer Security Levels With Modular Rulesets
  • Feature: Ruleset Registration
  • Feature: Ruleset Binding
  • Feature: Automatic Updates
• Feature: Enhanced AMM Compatibility For Apptokens
• Feature: Default List Extension
• Feature: EIP-7702 OTC Option
• Feature: Smart Wallet OTC Option
• Feature: Global and Ruleset Options
• Feature: Whitelist Extension Contracts
• Feature: Expansion Lists
• Feature: Expansion Settings
• Feature: Transfer Validation Simulation Functions

Replaced Transfer Security Levels With Modular Rulesets

Prior versions of the transfer validator combined all the logic for security levels into a large, monolithic validation function. Version 5 replaces this monolithic function and transfer security levels with the concept of Rulesets. Rulesets are entirely read-only and unable to change EVM state, as their sole purpose is to determine if a given transfer should be allowed or blocked. Version 5 will initially ship with four rulesets that replicate and improve upon the previous nine transfer security levels (Vanilla, Soulbound, Blacklist, and Whitelist Rulesets).

Feature: Ruleset Registration

Over time, Limit Break can register new ruleset modules. These modules could be entirely new types of validation rulesets, or they can be upgrades to existing rulesets such as an augmented Whitelist ruleset that offers new transfer validation options, or patches issues created by new EIPs.

Because ruleset modules must not be able to modify EVM state during execution, the module registration process includes a code purity check. Every opcode in the module is checked against a set of invalid or banned opcodes that have the potential to change state, ensuring that registering a module that modifies the EVM at validation time is impossible.

Feature: Ruleset Binding

Upon successful registration, rulesets are bound to Ruleset Ids. Usable Ids range from 0-254.

Ruleset Id 0 is reserved for the default ruleset of the validator. It is currently bound to Ruleset Whitelist, so unless otherwise modified by the creator, the default validation ruleset for a 20-C/721-C/1155-C token is Whitelist with all default global and ruleset-specific option flags set to 0.

Ruleset Id 255 is reserved for creators that wish to opt out of Automatic Updates (more on this in a moment).

With up to 255 ruleset id bindings available, there is a lot of room for future expansion of the Creator Token Transfer Validator capabilities.

Feature: Automatic Updates

The system of registration and binding rulesets creates the opportunity for creators to get passive security upgrades to their creator tokens. In prior versions of the validator, the creator would have to migrate to a new validator. Once migrated to Version 5, creators automatically get access to enhancements without having to be notified to take specific actions!

Note: Creators can opt out of the Automatic Update feature by using Ruleset Id 255 for their token security policies and specifying a specific registered ruleset they want to use. When creators specify the exact ruleset address they wish to use this way, rebindings of rulesets to other ids will not change the validation behavior of their tokens.

Feature: Enhanced AMM Compatibility For Apptokens

Validator V5 enhances the pre-existing authorizer mode for token transfers by implementing support for authorized token amounts, extending support from ERC721-C to ERC20-C and ERC1155-C apptokens. This improved authorization mode can be used in Uniswap V4 hooks to create powerful apptokens with rules that execute inside of Uniswap! When the hook’s rules for a token have been satisfied, the hook can inform Validator V5 that the AMM address is authorized to transfer X number of apptokens. In the coming weeks, Limit Break will release a production-grade Apptoken Hook for Uniswap V4.

Furthermore, Limit Break is nearing completion of a native TokenMaster AMM for ERC20-C apptokens. TokenMaster AMM will be the best protocol for developers to program the trading rules for their tokens.

For developers, this means they can apply rules to AMMs that include, but are not limited to:

• LP Whitelisting
• Token pairing
• Custom token pricing ranges
• Fixed price tokens
• Swap fees
• Trading caveats such as NFT-gated swaps or task-gated swaps

Feature: Default List Extension

In prior versions of Transfer Validator, when creators switched to a custom list id instead of the default, they had to fully manage the custom list. If they still wanted access to default whitelisted protocols, for example, the creator had to add those protocols to their custom list in addition to the extra protocols they put into the list. Updates to the default list were not automatically reflected in the creators' custom lists either.

Version 5 adds an option to extend the default list with a custom list, making the addition of custom protocols much easier. When the creator opts into supplementing their custom list with the default list, they receive automatic updates that follow the custom list, plus they can easily add the additional protocols they want to work with to their custom list and both lists will be checked during transfer validation.

Feature: EIP-7702 OTC Option

The Whitelist ruleset includes a new option to either allow or block OTC transfers when the OTC transfer is performed by an EOA with an EIP-7702 delegation attached. This option is only evaluated when a collection is not configured to block all OTC. Because of the risk that transfer rules are bypassed by EOAs with 7702 delegates attached, the default behavior is to Block OTC from EOAs in delegation mode. Creators can toggle this setting to opt out of this protection and allow OTC from EOAs in delegation mode. Additionally, when blocking EOAs with delegates creators can whitelist trusted delegate code addresses, codehashes, or even specific delegate code factories that are known to be safe to broaden access to OTC transfers to as many users as possible. The ability to whitelist delegates is a powerful new features that sets the stage for the development and proliferation of appwallets, which are 7702 delegate implementations built to work with apptokens.

Feature: Smart Wallet OTC Option

As account abstraction wallets gain popularity, more and more users will hold tokens in smart contract wallets. The Whitelist ruleset includes a new option to either allow or block OTC transfers when the OTC transfer is performed by a smart wallet. This option is only evaluated when a collection is not configured to block all OTC. The default behavior is to Block OTC from Smart Wallets. Creators can toggle this setting to opt out of this protection. Additionally, when blocking OTC from smart wallets, creators can whitelist trusted smart wallet code addresses, codehashes, or even specific smart wallet factories that are known to be safe to broaden access to OTC transfers to as many users as possible.

Feature: Global and Ruleset Options

The Token Security Policy now includes an 8-bit Global Options field and a 16-bit Ruleset-Specific Options field. Global options generally apply to many rulesets (for example: account freezing and authorizer mode flags). Ruleset-specific options generally apply to a single ruleset. For example, the Whitelist ruleset makes use of 5 flags that fine-tune Whitelisting ruleset behavior.

New ruleset implementations can make use of up to 16 ruleset-specific option flags in addition to the standard global options.

Feature: Whitelist Extension Contracts

Version 5 introduces a new way to make more complex decisions about what accounts should be whitelisted, going beyond account address and codehash. Creators may add external contracts that query wallet factories, for example. This expands the possibilities for easily whitelisting protocols that create many contract instances, such as a wallet factory or AMM with individual pools.

Feature: Expansion Lists

Over time, new rulesets may require the use of new kinds of lists. Prior versions of the transfer validator only included blacklists, whitelists, and authorizer lists. The creation of a system of expansion lists allows new rulesets to incorporate new list types that can be attached to any list id.

For example, the following list types are currently defined:

List Type	List Type Id	Used In Rulesets
Blacklist	0	Blacklist
Whitelist	1	Whitelist
Authorizers	2	Blacklist + Whitelist
Whitelist Extension Contracts	3	Whitelist
EIP-7702 Delegate Whitelist	4	Whitelist
EIP-7702 Delegate Whitelist Extension Contracts	5	Whitelist

Version 5 of the Transfer Validator supports up to 256 total list types, plenty of room for future expansion.

Feature: Expansion Settings

Over time, new rulesets may require the use of new token-specific settings. Version 5 includes a system for setting arbitrary expansion settings as key-value pairs. Key-value pairs come in two forms: Expansion Words and Expansion Datums. Expansion Words have 32-byte keys and 32-byte values. Expansion Datums have 32-byte keys and variable length bytes values for maximum flexibility and future expansion. At this time, no rulesets currently use expansion settings, and this feature is solely for future-proofing.

Feature: Transfer Validation Simulation Functions

Simulation functions have been added as a convenience that make it easier for D'apps to check whether or not a transfer operation would be successful based upon configured rulesets, options, and whitelists. These functions are:

/**
     * @notice Simulates transfer validation of a collection with its current ruleset and options.
     * 
     * @dev    Authorization mode overrides are not taken into account.
     *
     * @param collection The address of the collection.
     * @param caller     The address initiating the transfer.
     * @param from       The address of the token owner.
     * @param to         The address of the token receiver.
     * @return isTransferAllowed True if the transfer is allowed, false otherwise.
     * @return errorCode         The error code if the transfer is not allowed.
     */
    function validateTransferSim(
        address collection, 
        address caller, 
        address from, 
        address to
    ) external view returns (bool isTransferAllowed, bytes4 errorCode);

    /**
     * @notice Simulates transfer validation of a collection with its current ruleset and options.
     *
     * @dev    Authorization mode overrides are not taken into account.
     *
     * @param collection The address of the collection.
     * @param caller     The address initiating the transfer.
     * @param from       The address of the token owner.
     * @param to         The address of the token receiver.
     * @param tokenId    The token id being transferred.
     * @return isTransferAllowed True if the transfer is allowed, false otherwise.
     * @return errorCode         The error code if the transfer is not allowed.
     */
    function validateTransferSim(
        address collection,
        address caller, 
        address from, 
        address to, 
        uint256 tokenId
    ) external view returns (bool isTransferAllowed, bytes4 errorCode);

    /**
     * @notice Simulates transfer validation of a collection with its current ruleset and options.
     *
     * @dev    Authorization mode overrides are not taken into account.
     *
     * @param collection The address of the collection.
     * @param caller     The address initiating the transfer.
     * @param from       The address of the token owner.
     * @param to         The address of the token receiver.
     * @param tokenId    The token id being transferred.
     * @param amount     The amount of the token being transferred.
     * @return isTransferAllowed True if the transfer is allowed, false otherwise.
     * @return errorCode         The error code if the transfer is not allowed.     
     */
    function validateTransferSim(
        address collection,
        address caller, 
        address from, 
        address to, 
        uint256 tokenId, 
        uint256 amount
    ) external view returns (bool isTransferAllowed, bytes4 errorCode);