Flap Tax Vault

Overview

When you use a smart contract as the "Funds Recipient Wallet", our system will try to parse it as a vault.

If you implement your smart contract following our Vault Specification, your Vault's information can be shown on our website.

Furthermore, if your vault is verified by our team or our auditing partners, your vault's "unverified" risk level can be updated to the corresponding risk level based on the audit results. And all audit reports will be uploaded to ipfs and available on our website for users to check. Users will be able to do their own research on the vaults before investing in your token.

If you are a developer , you can build a vault factory that deploys vaults following our Vault Specification. Once your vault factory is verified by our team or our auditing partners, all vaults deployed from your factory will have the same risk level as your factory. This way, you don't need to submit each vault for verification individually. Besides, you can charge a fee for each vault deployed from your factory to build your business upon Flap. Please refer to the "Vault Factory" section below for more details.

The Vault Specification

To be compatible with our VaultPortal system, your vault smart contract must inherit the VaultBase contract:

// SPDX-License-Identifier: MIT

pragma solidity ^0.8.13;

/// @title VaultBase
/// @notice Abstract base contract for all vault implementations
/// @author The Flap Team
/// @dev How to implement your own vault contract:
///
/// 1. **Inherit from this base contract**
///    - All vault implementations must extend this contract
///
/// 2. **Implement the description() method**
///    - This method should return a dynamic string describing the vault's current state
///    - The description should change based on vault state (e.g., balance, streaming status, etc.)
///    - Example: "Flap Tax Vault for TOKEN, this vault automatically buyback tokens, we have bought back 3.2M tokens. Developed by Alice (twitter.com/alice)"
///
/// 3. **Use _getPortal() for Portal interactions**
///    - Call this internal method to get the Portal address for the current chain
///    - The method reverts if the current chain is not supported
///    - Currently only BNB Chain (chain ID 56) and BNB Testnet (chain ID 97) are supported
///
/// 4. **Use _getGuardian() for Guardian address**
///    - Call this internal method to get the Guardian address for the current chain
///    - The Guardian is a privileged address that can always call permissioned functions if you have any
///    - The method reverts if the current chain is not supported
///    - Currently only BNB Chain (chain ID 56) and BNB Testnet (chain ID 97) are supported
///
/// 5. **Handle tax token revenue**
///    - Implement a receive() function to accept BNB from the tax token
///    - Process the revenue according to your vault's logic (accumulate, stream, buyback, etc.)
///
/// 6. **MANDATE: Guardian access to permissioned functions**
///    - If you have any permissioned functions that should be triggered by an external address,
///      and it is not suitable to make them public(e.g: buyback which may be sandwich attacked),
///      you MUST ALSO give the guardian address the permissions alongside other allowed addresses as a backup.
///    - The guardian can always call permissioned functions and must have the necessary roles/permissions
///    - It should not be able to revoke guardian's any access to permissioned functions unless the guardian itself renounces the access
///
abstract contract VaultBase {
    /// @notice Error thrown when the current chain is not supported
    error UnsupportedChain(uint256 chainId);

    /// @notice Get the Portal address for the current chain
    /// @dev Currently supports BNB Chain (chain ID 56) and BNB Testnet (chain ID 97)
    /// @return portal The Portal contract address
    function _getPortal() internal view returns (address portal) {
        uint256 chainId = block.chainid;
        if (chainId == 56) {
            // BNB Chain Portal
            return 0xe2cE6ab80874Fa9Fa2aAE65D277Dd6B8e65C9De0;
        } else if (chainId == 97) {
            // BNB Testnet Portal
            return 0x5bEacaF7ABCbB3aB280e80D007FD31fcE26510e9;
        }
        revert UnsupportedChain(chainId);
    }

    /// @notice Get the Guardian address for the current chain
    /// @dev Currently supports BNB Chain (chain ID 56) and BNB Testnet (chain ID 97)
    /// @return guardian The Guardian contract address
    function _getGuardian() internal view returns (address guardian) {
        uint256 chainId = block.chainid;
        if (chainId == 56) {
            // BNB Chain Guardian address
            return 0x9e27098dcD8844bcc6287a557E0b4D09C86B8a4b;
        } else if (chainId == 97) {
            // BNB Testnet Guardian address
            return 0x76Fa8C526f8Bc27ba6958B76DeEf92a0dbE46950;
        }
        revert UnsupportedChain(chainId);
    }

    /// @notice Returns a description of the vault
    /// @dev This method should be overridden by implementing contracts to provide
    ///      a dynamic description based on the vault's current state
    /// @return A string describing the vault's current state and configuration
    function description() public view virtual returns (string memory);
}

• You must implement the description() method to return a dynamic string that describes your vault's current state. The description should change based on the vault's state (e.g., balance, status, etc.), we will learn an example from the following BlackHoleVault example.

• If you have any permissioned functions that should be triggered by an external address, and it is not suitable to make them public (e.g., buyback which may be sandwich attacked), you MUST ALSO give the guardian address the permissions alongside other allowed addresses as a backup. The guardian can always call permissioned functions and must have the necessary roles/permissions. It should not be able to revoke guardian's any access to permissioned functions unless the guardian itself renounces the access. At this moment, the guardian is an empty but upgradeable contract managed by Flap. In the ideal case, we don't need to implement any functionality in the guardian contract. It just serves as a trusted address that can step in when necessary to protect users' funds. Check the Flap Guardian section for more details.

The Example Vault Implementation - BlackHoleVault

Here is an example vault implementation called BlackHoleVault that inherits from the VaultBase contract and implements the required description() method:

• It inherits from VaultBase and implements the description() method to provide a dynamic description of the vault's state.

• Since it does not have any permissioned functions, it does not need to be associated with the guardian address.

// SPDX-License-Identifier: MIT

pragma solidity ^0.8.13;

import {VaultBase} from "src/interfaces/VaultBase.sol";

/// @title BlackHoleVault
/// @notice A vault that accepts BNB but provides no way to withdraw it
/// @author The Flap Team
/// @dev This vault acts as a permanent lock for tax revenue from tokens.
///      Once BNB is sent to this vault, it cannot be retrieved by anyone.
///      This can be used for deflationary tokenomics where tax revenue is
///      permanently burned/locked.
contract BlackHoleVault is VaultBase {
    /// @notice Emitted when BNB is received by the vault
    /// @param amount The amount of BNB received
    event BNBReceived(uint256 amount);

    /// @notice Accepts BNB transfers from the tax token
    /// @dev The received BNB is permanently locked in this contract
    receive() external payable {
        emit BNBReceived(msg.value);
    }

    /// @notice Returns a description of the vault's current state
    /// @dev Implements the VaultBase description() method
    /// @return A string describing the vault and the amount of BNB locked
    function description() public view override returns (string memory) {
        uint256 lockedBNB = address(this).balance;

        // Convert balance to string with 4 decimal places
        uint256 bnbWhole = lockedBNB / 1e18;
        uint256 bnbDecimals = (lockedBNB % 1e18) / 1e14; // 4 decimal places

        return string(
            abi.encodePacked(
                "BlackHole Vault - Permanently locks all received BNB. ",
                "Current locked amount: ",
                _toString(bnbWhole),
                ".",
                _padZeros(_toString(bnbDecimals), 4),
                " BNB. ",
                "WARNING: BNB sent to this vault cannot be recovered by anyone."
            )
        );
    }

    /// @notice Converts a uint256 to a string
    /// @param value The value to convert
    /// @return The string representation of the value
    function _toString(uint256 value) internal pure returns (string memory) {
        if (value == 0) {
            return "0";
        }

        uint256 temp = value;
        uint256 digits;
        while (temp != 0) {
            digits++;
            temp /= 10;
        }

        bytes memory buffer = new bytes(digits);
        while (value != 0) {
            digits -= 1;
            buffer[digits] = bytes1(uint8(48 + uint256(value % 10)));
            value /= 10;
        }

        return string(buffer);
    }

    /// @notice Pads a string with leading zeros to reach the desired length
    /// @param str The string to pad
    /// @param targetLength The desired length
    /// @return The padded string
    function _padZeros(string memory str, uint256 targetLength) internal pure returns (string memory) {
        bytes memory strBytes = bytes(str);
        if (strBytes.length >= targetLength) {
            return str;
        }

        bytes memory padded = new bytes(targetLength);
        uint256 paddingCount = targetLength - strBytes.length;

        for (uint256 i = 0; i < paddingCount; i++) {
            padded[i] = "0";
        }

        for (uint256 i = 0; i < strBytes.length; i++) {
            padded[paddingCount + i] = strBytes[i];
        }

        return string(padded);
    }
}

The Flap Guardian

The Flap Guardian is a privileged address that can always call permissioned functions in vault contracts that implement our Vault Specification. The guardian serves as a backup mechanism to ensure that critical functions can be executed even if the primary authorized addresses are unable to do so.

At this moment, the guardian is an empty but upgradeable contract managed by Flap as follows:

// SPDX-License-Identifier: MIT

pragma solidity ^0.8.13;

/// @title FlapGuardian
/// @author The Flap Team
/// @notice Guardian contract for vault emergency management and CTO cases
/// @dev Currently, this contract does nothing, but this contract is upgradeable.
///      If your Vault has special permissions, you must grant the same permissions
///      to this contract. This allows it to act as a guardian for the Vault in case
///      of an emergency or CTO case.
contract FlapGuardian {
    /// @notice Returns the version of this contract
    /// @return version string
    function version() external pure returns (string memory) {
        return "0.0.1";
    }
}

Ideally, we don't need to implement any functionality in the guardian contract. It just serves as a trusted address that can step in when necessary to protect users' funds.

Adapter for Legacy Vaults

If you have built a vault to receive tax token revenue before the Vault Specification was introduced, you can still make your vault compatible with our VaultPortal system by creating an adapter contract that inherits from VaultBase and wraps around your existing vault. The adapter will implement the description() method and forward calls to your legacy vault as needed. This way, you can leverage our VaultPortal features without modifying your original vault contract.

Please reach out to our team for assistance in creating an adapter for your legacy vault.

Get Your Vault Verified

Please reach out to our team if you want to get your vault or vault factory verified by us or our auditing partners.

Before reaching out, please make sure:

• You have correctly implemented the Vault Specification in your vault contract. (The description() method, the guardian access to permissioned functions, etc.)

• You have passed some basic AI auditing tools. Check the "How to use AI to audit your smart contracts" below for more details. Using such tools can help you resolve some critical vulnerabilities before submitting for manual review. We strongly recommend you to use AI auditing tools even before deploying your smart contracts and tokens

VaultPortal

The VaultPortal is a registry that manages vault factories and their deployed vaults. It provides a unified interface for interacting with vaults across different chains.

Deployed Addresses

Chain	VaultPortal Address
BNB mainnet	0x90497450f2a706f1951b5bdda52B4E5d16f34C06
BNB testnet	0x027e3704fC5C16522e9393d04C60A3ac5c0d775f

Get Vault Info

We have two methods for fetching the vault info of a token:

• tryGetVault(address taxToken) : This method first tries to find the vault created through the VaultPortal. If not found, it will try to find the vault by searching all registered vault factories and manually verified vaults. You should use this method for most cases to avoid unnecessary reverts.

• getVault(address taxToken) : This method returns vault that created through the VaultPortal.

/// @notice Complete vault information returned to external callers
/// @dev This struct is used for view functions and includes human-readable description
/// @param vault The address of the vault contract
/// @param vaultFactory The address of the vault factory that created this vault (zero address if unknown)
/// @param description Human-readable description of the vault's purpose and functionality
/// @param isOfficial Whether this vault is marked as official/endorsed by the protocol
/// @param riskLevel The risk level classification from audit
struct VaultInfo {
    address vault;
    address vaultFactory;
    string description;
    bool isOfficial;
    RiskLevel riskLevel;
}

/// @notice Get the complete vault information for a tax token
/// @dev Reverts if no vault is found for the given tax token
/// @dev Attempts to fetch the vault's description by calling its description() function
/// @param taxToken The address of the tax token
/// @return info The VaultInfo struct containing complete vault details
function getVault(address taxToken) external view returns (VaultInfo memory info);

/// @notice Attempt to get vault information for a tax token without reverting
/// @dev First checks the internal mapping, then falls back to searching the Portal
/// @dev For fallback results, isOfficial and isVerified will always be false
/// @param taxToken The address of the tax token
/// @return found Whether a vault was found for this tax token
/// @return info The VaultInfo struct (empty if not found)
function tryGetVault(address taxToken) external view returns (bool found, VaultInfo memory info);

Get Audit Reports for A token

For each token, you can get its audit reports with pagination support using the getAuditReports method. If the token itself has no audit reports, it will fall back to its vault's factory's audit reports.

/// @notice Audit report for a tax token
/// @param auditor The address of the auditor who submitted this report
/// @param riskLevel The risk level classification from this audit
/// @param ipfsCid The IPFS CID of the audit report document
struct AuditReport {
    address auditor;
    RiskLevel riskLevel;
    string ipfsCid;
}

/// @notice Get recent audit reports for a tax token with pagination
/// @dev Returns reports starting from the most recent (end of array)
/// @dev If the token has no audit reports, falls back to its factory's audit reports
/// @param taxToken The address of the tax token
/// @param offset The number of reports to skip from the end (0 = most recent)
/// @param limit The maximum number of reports to return
/// @return reports The array of audit reports
/// @return total The total number of audit reports for this token
function getAuditReports(address taxToken, uint256 offset, uint256 limit)
    external
    view
    returns (AuditReport[] memory reports, uint256 total);

VaultFactory

You can implement a vault factory that deploys vaults following our Vault Specification. Your vault factory must implement the IVaultFactory interface as follows:

// SPDX-License-Identifier: MIT

pragma solidity ^0.8.13;

/// @title IVaultFactory
/// @notice Interface that all vault factory contracts must implement
/// @dev Each vault type must have a corresponding factory contract that implements this interface
interface IVaultFactory {
    /* ========== ERRORS ========== */

    /// @notice Thrown when caller is not the vault portal
    error OnlyVaultPortal();

    /// @notice Thrown when zero address is provided
    error ZeroAddress();

    /* ========== FUNCTIONS ========== */
    /// @notice Creates a new vault instance for a tax token
    /// @dev IMPORTANT: The taxToken does not exist yet when this method is called.
    ///      The VaultPortal predicts the token address and passes it here.
    ///      The actual token will be created AFTER the vault is created.
    /// @param taxToken The predicted address of the tax token (not yet deployed)
    /// @param quoteToken The quote token address (e.g., address(0) for native BNB)
    /// @param creator The original msg.sender to VaultPortal who initiated token creation
    /// @param vaultData Custom encoded data specific to this vault type
    /// @return vault The address of the newly created vault
    function newVault(address taxToken, address quoteToken, address creator, bytes calldata vaultData)
        external
        returns (address vault);

    /// @notice Checks if a quote token is supported by this vault factory
    /// @param quoteToken The quote token address to check
    /// @return supported True if the quote token is supported, false otherwise
    function isQuoteTokenSupported(address quoteToken) external view returns (bool supported);
}

• Currently, we only support BNB (quoteToken == address(0)) as the quote token. But in the future, we may support other quote tokens as well. And your vault factory must implement the isQuoteTokenSupported method to indicate which quote tokens are supported.

• The newVault method will be called by the VaultPortal when a new tax token is being created. Your factory must create a new vault instance for the predicted tax token address and return the vault address. Please note that the tax token does not exist yet when this method is called. The VaultPortal predicts the token address and passes it here. The actual token will be created AFTER the vault is created.

Note that if you want to get your vault factory verified by us or our auditing partners, you must follow the following guidelines:

• The factory must implement the IVaultFactory interface correctly.

• The factory contract can not be upgradeable. If you want to upgrade your factory in the future, you must deploy a new factory contract and get it verified again.

• The Vault deployed from your factory can charge at most 10% as a fee from the tax revenue. The fee structure must be clearly described in the vault's description() method.

• You need to at least pass some basic AI auditing tools before submitting for manual review. Check the "How to use AI to audit your smart contracts" below for more details. Using such tools can help you resolve some critical vulnerabilities before submitting for manual review. We strongly recommend you to use AI auditing tools even before deploying your smart contracts and tokens

FAQ

How to use AI to audit your smart contracts?

You can use any AI for auditing your smart contracts. For example, you can use google's AI studio which is free to use. The prompt is as follows:

You are a professional smart contract auditor. Generate an audit report for the following Solidity smart contract code. Identify potential vulnerabilities, code smells, questions, and best practice violations. Provide recommendations for improvements.  

Return the result in markdown format and put the markdown in a code block.  

======================== 

<Your Solidity Code Here>

This could help you identify some common vulnerabilities and issues in your smart contracts. And if your comments are clear enough, it will even help you identify some logical issues. However, please note that AI tools are not perfect and may miss some vulnerabilities or provide incorrect suggestions. Alwaysreview your smart contracts before deploying them on mainnet.