Setting Up Tiered Access with Multi-Token Models

Tiered token-gated access is a permissioning system where a user's privileges are determined by the specific combination of tokens they hold in their wallet. Unlike a single-token gate, a multi-token model allows for granular, role-based access control. Common implementations use a combination of ERC-20, ERC-721 (NFT), and ERC-1155 tokens to represent different membership levels, such as BASIC, PREMIUM, and VIP. This approach is foundational for creating sophisticated Web3 communities, exclusive content platforms, and feature-gated dApps, moving beyond simple binary access checks.

The core logic involves checking a user's wallet balance for specific token contracts. A smart contract or off-chain server validates ownership. For example, access to a premium Discord channel might require holding at least 1 PREMIUM_NFT, while submitting a governance proposal could require 100 GOV_TOKEN and 1 FOUNDER_NFT. This is often implemented using conditional checks in a Solidity require statement or via a signed message from a verification server. The key is defining clear, non-overlapping rules for each tier to prevent privilege escalation bugs.

Here is a basic Solidity example for a contract that gates minting functionality based on two tokens:

solidityCopy
interface IERC721 {
    function balanceOf(address owner) external view returns (uint256);
}

contract TieredMinter {
    IERC721 public premiumPass;
    IERC20 public utilityToken;

    constructor(address _premiumPass, address _utilityToken) {
        premiumPass = IERC721(_premiumPass);
        utilityToken = IERC20(_utilityToken);
    }

    function mintPremium(address to) external {
        // Tier 1: Must hold a Premium Pass NFT
        require(premiumPass.balanceOf(to) > 0, "Tier 1: Premium Pass required");
        _mint(to);
    }

    function mintElite(address to) external {
        // Tier 2: Must hold a Premium Pass AND 1000 utility tokens
        require(premiumPass.balanceOf(to) > 0, "Tier 2: Premium Pass required");
        require(utilityToken.balanceOf(to) >= 1000 ether, "Tier 2: 1000 UTIL required");
        _mintElite(to);
    }
}

This contract demonstrates a two-tier system where mintElite has stricter requirements than mintPremium.

For off-chain validation, such as gating website content or API access, a backend service typically handles verification. The flow involves: 1) The user connects their wallet (e.g., via MetaMask). 2) The frontend requests a signature for a nonce. 3) The backend receives the signature, recovers the signer's address, and queries blockchain RPC providers (like Alchemy or Infura) to check token balances. 4) Based on the predefined multi-token rules, the backend grants or denies access and may issue a session token. Libraries like ethers.js and viem simplify these RPC calls and balance checks.

When designing your tiers, consider composability and upgradability. Will new token types be added? Can users qualify for multiple tiers? Using a modular rule engine or an access control contract like OpenZeppelin's AccessControl can help manage complexity. Also, account for gas costs for on-chain checks and the user experience of off-chain verification. Always audit the security of the gating logic to prevent exploits, such as flash loan attacks to temporarily meet token balance requirements. Document the tier specifications clearly for users.

Real-world use cases include Friends with Benefits (FWB) using $FWB token tiers for city guild access, BanklessDAO gating different Discord channels with varying BANK token thresholds, and NFT projects like Bored Ape Yacht Club using NFT ownership for exclusive website areas. The multi-token model provides the flexibility to create rich, layered ecosystems. For further reading, consult the EIP-20, EIP-721 standards, and documentation for access control libraries.

A multi-token model for access control allows you to gate functionality based on a user's holdings across different token contracts. Common patterns include requiring a minimum balance of a governance token (e.g., ERC20), ownership of a specific NFT (e.g., ERC721), or a combination of both. The core logic resides in a modifier or function within your main contract that performs these checks before allowing an action. You'll need a basic understanding of Solidity, the OpenZeppelin Contracts library, and a development environment like Hardhat or Foundry.

Start by installing the necessary dependencies. For a typical Hardhat project, run npm install @openzeppelin/contracts. Your contract must import the interfaces for the tokens it will check. For example, to check for an ERC20 balance and an ERC721 owner, import @openzeppelin/contracts/token/ERC20/IERC20.sol and @openzeppelin/contracts/token/ERC721/IERC721.sol. Store the contract addresses of these external tokens as immutable variables, set in the constructor, to ensure your access control points to the correct, unchangeable contracts.

The key implementation is an access control modifier. Create a modifier like requiresTier() that uses the imported interfaces to query the state of the msg.sender. For an ERC20 tier, call IERC20(tokenContract).balanceOf(msg.sender) >= minimumBalance. For an NFT tier, use IERC721(nftContract).ownerOf(tokenId) == msg.sender. You can combine conditions using logical operators (&&, ||) to create complex rules, such as requiring either a high ERC20 balance or ownership of a specific NFT series.

Always consider gas efficiency and security. Performing multiple external calls in a modifier adds gas cost. For frequently accessed functions, this is acceptable, but for optimal design, you might implement an internal view function that returns a user's tier status, which the modifier calls. Crucially, never trust tier status stored in your contract's state without a live check against the token contracts, as balances and ownership can change. The checks-effects-interactions pattern still applies; perform all access control checks at the very beginning of your function.

Test your setup thoroughly. Write unit tests that deploy mock ERC20 and ERC721 contracts, then test your main contract's gated functions with accounts that meet and fail the tier requirements. Use Foundry's vm.prank or Hardhat's hardhat-ethers to simulate different user addresses. Testing should verify that access is correctly granted, denied, and that the system responds properly to transfers of the underlying tokens—a user who sells their NFT should immediately lose access.

Finally, for production, verify your contract's interactions with the real token addresses on-chain. Use a block explorer to confirm the stored addresses are correct. Consider implementing an emergency override or a timelock-controlled mechanism to update token addresses in case of a critical migration. Document the tier requirements clearly for users, specifying the exact token contracts, required balances, or NFT collection IDs they must hold to interact with your protocol's features.

A multi-token model is a design pattern where a protocol issues distinct tokens to represent different rights or tiers of access. This is more flexible than a single-token system, allowing for granular control over features like staking requirements, fee discounts, governance power, and exclusive content. Common implementations involve a primary utility token (e.g., ERC-20) paired with a non-transferable soulbound token (ERC-721 or ERC-1155) that certifies membership status. This separation ensures that speculative trading of the utility token doesn't directly compromise the integrity of the access layer.

The core architecture typically uses a central AccessManager smart contract. This contract holds the logic that maps user token balances to specific permissions. For example, holding 1,000 PROTOCOL tokens might grant Tier 1 access, while also holding a non-transferable VIP_MEMBER NFT unlocks Tier 2. The AccessManager exposes functions like hasAccess(user, tier) that other contracts in the ecosystem can call to gate functionality. This pattern is used by protocols like Curve Finance with its veCRV model for gauge voting weight and by Friend.tech with its key-based access to chat rooms.

Implementing a basic tier check involves verifying balances in the require statement of a function. For instance, a function for a premium feature could be gated as follows:

solidityCopy
function accessPremiumFeature() external {
    IERC20 tierToken = IERC20(0x...);
    IERC721 memberNFT = IERC721(0x...);
    require(tierToken.balanceOf(msg.sender) >= 1000 ether, "Insufficient utility tokens");
    require(memberNFT.balanceOf(msg.sender) > 0, "Membership NFT required");
    // Execute premium feature logic
}

This ensures only users meeting both criteria can proceed.

Advanced designs incorporate time-based tiers using vesting or locking mechanisms. The widely adopted vote-escrow model, pioneered by Curve, requires users to lock their tokens for a set duration (e.g., 1-4 years) to receive veTokens. The quantity of veTokens is proportional to the amount locked and the lock time, creating a tiered system where longer, larger locks grant more governance power and higher rewards. This aligns long-term user incentives with protocol health.

Security considerations are paramount. Audit the AccessManager contract thoroughly, as it becomes a central point of failure. Use OpenZeppelin's Ownable or access control libraries for administrative functions. Ensure that the logic for calculating tiers is not manipulable and that token addresses are immutable after setup. For NFT-based tiers, consider making them soulbound (non-transferable) to prevent tier purchasing and ensure access is tied to user identity or contribution history.

When designing your model, clearly define the utility of each token. A common structure is: Token A for payments and liquidity, Token B (non-transferable) for governance rights, and Token C for special access passes. This separation allows for independent monetary policy and prevents one aspect of the ecosystem from being diluted by another. Always document the tier requirements and permissions clearly for users to ensure transparency and trust in the access system.

A single-token balance tier model is a straightforward yet powerful access control mechanism. It grants permissions based on the quantity of a specific ERC-20 token a user holds in their wallet. Common use cases include gating premium features in a dApp, providing voting weight in a DAO, or unlocking different membership levels in a community platform. This model is simpler to implement and audit than multi-token systems, as it relies on a single, verifiable on-chain state: the user's token balance.

The core logic involves defining threshold balances that correspond to specific tiers. For example, you might define: Tier 0 (No access): 0 tokens, Tier 1 (Basic): 1,000 tokens, Tier 2 (Premium): 10,000 tokens, Tier 3 (VIP): 100,000 tokens. A smart contract function, such as getUserTier(address user), would read the user's balance from the token contract and map it to the appropriate tier. This check is typically performed via a require statement or an if condition before allowing access to a protected function.

Here is a basic Solidity implementation snippet for a contract that checks tier eligibility:

solidityCopy
interface IERC20 {
    function balanceOf(address account) external view returns (uint256);
}

contract TieredAccess {
    IERC20 public membershipToken;
    uint256 public constant TIER_1_MIN = 1000 * 10**18;
    uint256 public constant TIER_2_MIN = 10000 * 10**18;

    constructor(address _tokenAddress) {
        membershipToken = IERC20(_tokenAddress);
    }

    function getTier(address user) public view returns (uint256) {
        uint256 bal = membershipToken.balanceOf(user);
        if (bal >= TIER_2_MIN) return 2;
        if (bal >= TIER_1_MIN) return 1;
        return 0;
    }

    function premiumFeature() external {
        require(getTier(msg.sender) >= 1, "Insufficient tier");
        // Execute premium logic
    }
}

Note the use of 10**18 to handle the token's decimals, assuming an 18-decimal standard.

When implementing this model, consider key security and design aspects. Use a decentralized oracle or the balanceOf view function directly for the most accurate and manipulation-resistant check. Be aware of potential flash loan attacks where a user borrows a large balance temporarily to access a tier; mitigate this by using a checkpointed balance (like a snapshot) or adding a timelock requirement. Furthermore, clearly communicate tier thresholds to users on the frontend to ensure transparency.

For production systems, enhance the basic model with additional features. You can create an expandable tier structure using arrays or mappings for dynamic threshold management. Implementing role-based access control (RBAC) alongside balance tiers allows for more granular permissions (e.g., a Tier 2 user with an additional "Admin" role). Events should be emitted when tier checks pass or fail for improved off-chain monitoring and indexing.

To integrate this with a frontend, your dApp should call the getTier view function to determine UI state. Combine this with wallet connection libraries like Wagmi or Ethers.js. Always design fallback states for when the RPC call fails. This model provides a clean, on-chain primitive for permissioning that is easy for users to understand—they simply acquire and hold more tokens to unlock greater access within your application's ecosystem.

Tiered access models are a common pattern in Web3 for gating features, content, or governance rights. Instead of a single membership token, these systems use multiple distinct tokens to represent different privilege levels. For example, a DAO might use a common GOV token for basic voting, a VIP NFT for early feature access, and a CONTRIBUTOR token for submitting proposals. This approach is more flexible than a single token with complex internal logic, as each token's supply and distribution can be managed independently.

The core implementation involves checking a user's balance for several token contracts. A basic Solidity access control function might look like this:

solidityCopy
function canAccessFeature(address user) public view returns (bool) {
    IERC20 govToken = IERC20(0x...);
    IERC721 vipNFT = IERC721(0x...);
    // Grant access if user holds at least 100 GOV tokens OR owns a VIP NFT
    return govToken.balanceOf(user) >= 100 * 10**18 || vipNFT.balanceOf(user) > 0;
}

This checks balances from two separate contracts. You can extend this with && operators for AND logic, requiring possession of multiple tokens.

For more complex tiering, consider an explicit tier struct that defines requirements. This makes the system upgradeable and easier to audit. You can store an array of Tier structs where each tier specifies required token addresses and minimum balances. The contract logic then iterates through these tiers to determine a user's highest unlocked level. This pattern is used by protocols like SushiSwap's MasterChef v2 for multi-token staking rewards and access.

Key considerations for production include gas optimization and security. Performing multiple external balanceOf calls can be expensive. Caching results or using a merkle proof system for off-chain verification can reduce costs. Always use the checks-effects-interactions pattern and reentrancy guards when your access function also executes state changes, like minting a reward. Verify all token contract addresses are immutable and correct to prevent exploits.

A practical use case is a gated newsletter where Article A requires Token X, Article B requires Token Y, and Article C requires both. The smart contract validates ownership, and a frontend like Lit Protocol can encrypt the content, only decrypting it for wallets that pass the on-chain check. This creates a seamless user experience where access is cryptographically enforced without central servers.

When deploying, thoroughly test all logic paths, especially edge cases like zero balances, paused token contracts, or malicious token implementations that could return false balances. Using established libraries like OpenZeppelin's SafeERC20 for token interactions is recommended. This multi-token model provides a robust, composable foundation for building sophisticated membership and reward systems in DeFi and social applications.

The ERC-1155 standard is uniquely suited for tiered models because a single contract can manage an infinite number of fungible and non-fungible tokens. Instead of deploying separate contracts for Bronze, Silver, and Gold memberships, you can define them as distinct token IDs (e.g., 1, 2, 3) within one contract. This approach drastically reduces gas costs for deployment and management, simplifies user interactions to a single contract address, and enables atomic batch operations where users can mint or transfer multiple tier tokens in a single transaction.

A core function for a tier system is balanceOfBatch, which allows you to check a user's holdings across all tiers with one on-chain call. For access control, your smart contract logic can check balanceOf(account, tokenId) > 0. For example, a function gated to Gold tier holders (tokenId=3) would include the modifier require(balanceOf(msg.sender, 3) > 0, "Gold tier required"). The safeBatchTransferFrom function also allows for efficient distribution, enabling an admin to airdrop specific tier tokens to multiple addresses in one transaction.

When designing the metadata, each token ID should have a distinct URI pointing to a JSON file that defines the tier's attributes, such as name, description, image, and custom properties like discountRate or accessLevel. You can use a base URI pattern (e.g., https://api.example.com/tier/{id}.json) or implement the uri(uint256 id) function to return a dynamic string. It's crucial that the metadata clearly communicates the benefits and permissions associated with each tier to the end-user.

For minting logic, you must decide on distribution rules. A common pattern is to restrict minting of higher tiers to holders of lower ones, implementing an upgrade path. Your mint function should validate prerequisites, such as requiring the user to burn a Silver token (tokenId=2) before minting a Gold token (tokenId=3). This can be done efficiently within the same contract using _burn and _mint. Always use the _safeMint and _safeBatchMint variants for ERC-1155 to ensure compatibility with contracts that implement the onERC1155Received hook.

Consider integrating with existing systems by using the tier token ID as a key in off-chain databases or frontend logic. Your dApp's backend can listen for TransferSingle and TransferBatch events to update user roles in real-time. For maximum flexibility, you can also make certain tokens non-transferable (soulbound) by overriding the safeTransferFrom functions to revert for specific token IDs, locking the tier to the original recipient's address.

A tiered access system is dynamic; users will upgrade for more features or downgrade to save costs. Your smart contract must handle these transitions securely and predictably. The core logic involves checking a user's current tier, validating their eligibility for the new tier (often by holding a specific NFT or token balance), and then executing the state change. This process must account for prorated credits, cooldown periods, and preventing downgrades that would violate active subscriptions. A common pattern is to use an upgradeTo and downgradeTo function, each guarded by modifiers that verify the caller owns the requisite tokens for the target tier.

When a user upgrades, you must decide how to handle the remainder of their current subscription period. A fair approach is to apply a pro-rated credit from their existing payment toward the new, more expensive tier. For example, if a user has 15 days left in a $10/month Basic tier and upgrades to a $30/month Pro tier, you might calculate the credit value ($5) and reduce the cost of the Pro tier accordingly. This requires your contract to track subscription start times and values. Conversely, downgrades typically take effect at the end of the current billing cycle to avoid service interruption and simplify accounting, a model used by services like Chainlink Functions subscriptions.

Security is paramount during state transitions. Your contract must prevent users from downgrading to a tier for which they no longer hold the required token, as this would break the access model. Implement a check that reverts the transaction if the user's balance of the tier-gating token (e.g., an ERC-1155 NFT) is zero. Additionally, consider adding a timelock or cooldown on frequent tier switches to prevent gaming the system and to reduce on-chain transaction spam. Events should be emitted for all tier changes to allow off-chain indexers and frontends to update user interfaces in real time.

From a user experience perspective, the upgrade/downgrade flow should be seamless. Your frontend application should fetch the user's current tier and available options from the smart contract, often by calling a view function like getEligibleTiers(address user). When a user initiates a change, the frontend should clearly display the financial implications—any prorated credit, the new recurring cost, and the effective date of the change. For downgrades, a clear warning about features that will be lost is essential. Integrating this with a wallet like MetaMask requires building a transaction that calls the appropriate contract function with the new tierId as a parameter.

Here is a simplified Solidity code snippet illustrating the core upgrade logic, excluding payment handling for clarity. It assumes tiers are represented by NFT IDs and that a user can only hold one tier NFT at a time.

solidityCopy
function upgradeTo(uint256 newTierId) external {
    require(tierNFT.balanceOf(msg.sender, newTierId) > 0, "Must hold new tier NFT");
    uint256 currentTierId = userTier[msg.sender];
    require(newTierId > currentTierId, "Can only upgrade to higher tier");
    // Optional: Check cooldown period
    require(block.timestamp >= lastChange[msg.sender] + cooldownPeriod, "In cooldown");
    // Execute upgrade logic (e.g., calculate proration, update state)
    userTier[msg.sender] = newTierId;
    lastChange[msg.sender] = block.timestamp;
    emit TierChanged(msg.sender, currentTierId, newTierId);
}

Testing your upgrade/downgrade logic is critical. Write comprehensive unit tests that simulate: a successful upgrade with credit, a failed upgrade due to missing the new tier NFT, a downgrade scheduled for the next cycle, and an attempt to bypass a cooldown. Use forked mainnet tests if your system interacts with live price oracles or token contracts. Finally, consider the administrative view: you may need emergency functions to pause tier changes or migrate users during a contract upgrade. Documenting these state transition rules clearly in your contract's NatSpec comments and external documentation is key for both users and auditors.

A tiered access model structures user permissions based on token holdings, enabling features like VIP memberships, governance weight, or gated content. Using a single token for all tiers is inefficient; it forces users to hold more tokens than necessary, increasing their capital lockup and your contract's gas costs for balance checks. A multi-token model solves this by deploying separate ERC-20 or ERC-1155 contracts for each tier (e.g., BRONZE, SILVER, GOLD). This design allows for precise, gas-efficient permission checks—a contract only needs to verify the user's balance of a specific tier token, not their total holdings across a monolithic token.

From a security perspective, multi-token models limit blast radius. If a vulnerability is discovered in one tier's token logic, it is isolated from the others. Furthermore, you can implement upgradeable or pausable logic per tier without affecting all users. A common pattern is to use the ERC-1155 Multi-Token Standard, which bundles multiple token types (tiers) into a single contract, reducing deployment costs and simplifying management. Each token ID represents a different access level, and the balanceOf function checks are inherently gas-optimized for batch operations.

Here's a basic Solidity example using an abstracted checker contract. This contract verifies access by checking the balance of a specific ERC-1155 token ID, which corresponds to a user tier.

solidityCopy
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.19;

interface IERC1155 {
    function balanceOf(address account, uint256 id) external view returns (uint256);
}

contract TieredAccess {
    IERC1155 public tierToken;
    uint256 public constant GOLD_TIER_ID = 1;
    uint256 public constant SILVER_TIER_ID = 2;

    constructor(address _tierTokenAddress) {
        tierToken = IERC1155(_tierTokenAddress);
    }

    function accessGoldFeature() external view {
        require(tierToken.balanceOf(msg.sender, GOLD_TIER_ID) > 0, "Insufficient tier");
        // Proceed to gold-tier functionality
    }
}

This pattern minimizes on-chain computation. The check is a simple SLOAD for the token contract address and a call to balanceOf, which is far cheaper than calculating complex weightings from a single token balance.

To implement this system, start by defining clear access tiers and their corresponding privileges. Use ERC-1155 for gas-efficient batch transfers and single-contract management, or deploy separate ERC-20 tokens if tiers require independent transferability and liquidity. The access control contract should store the token contract address and tier IDs as immutable variables. For maximum optimization, consider using EIP-165 to support interface detection and storing tier IDs in packed uint256 storage slots. Always include a function to update the token contract address in case of an upgrade, secured behind a multi-signature or timelock.

Real-world applications include NFT-gated communities with multiple membership levels, DeFi protocols with tiered fee discounts based on staking, and DAOs where voting power is segmented into specialized councils. For instance, a protocol might issue GOVERNANCE, SECURITY, and GRANTS tokens to separate powers. The key gas saving comes from avoiding redundant storage reads and complex math. By isolating permissions into discrete token balances, you reduce the average cost of permission checks, which are often the most frequent operations in such systems.

When auditing your tiered access system, focus on the token contract's security as the root of trust. Ensure minting/burning is properly restricted, typically to an admin or a minter role. Verify that the access contract correctly handles the return value of balanceOf. For ERC-1155, remember that the standard allows for batched balanceOfBatch queries, which can be used to check multiple tiers in a single call for compound permissions. Finally, document the tier IDs and their associated privileges off-chain (e.g., in your project's documentation) to prevent confusion and ensure correct integration by other developers.

The tiered access model you've built demonstrates a flexible pattern for gating functionality based on token holdings. Key components include: a TierManager contract defining token requirements, a checkAccess function for on-chain verification, and a modular design that separates logic from your core application. This approach is more gas-efficient and secure than checking balances directly in every function, and it allows for centralized management of tier criteria, such as adjusting the required balance of ERC20 tokens like USDC or updating the list of valid `ERC721** collections.

For production use, several critical enhancements are necessary. First, implement robust access control using OpenZeppelin's Ownable or AccessControl to restrict who can update tiers. Second, add comprehensive event emission (e.g., TierUpdated, AccessChecked) for off-chain monitoring and indexing. Third, consider integrating a merkle proof system for allowlists if you need to support snapshot-based token holdings without requiring a live balance. Finally, always include pausable functionality and upgradeability considerations (using transparent proxies or the UUPS pattern) to manage future changes securely.

To test your implementation thoroughly, write extensive unit tests with Foundry or Hardhat. Simulate edge cases: users holding multiple qualifying NFTs, transfers that change tier status mid-transaction, and reentrancy attempts. For frontend integration, use the wagmi and viem libraries to call your checkAccess view function and conditionally render UI components. The next logical step is to explore more advanced models, such as time-weighted token balances (using ERC20Votes), composable tier logic with AND/OR operators, or integrating with a decentralized identity standard like ERC-6551 for token-bound accounts.