> For the complete documentation index, see [llms.txt](https://tokenization.gitbook.io/tokenf/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tokenization.gitbook.io/tokenf/erc-3643-t-rex-and-tokenf.md). # ERC-3643 (T-REX) & TokenF ### Introduction This document aims to provide insights into the improvements offered by the TokenF framework over the [ERC-3643 standard](https://eips.ethereum.org/EIPS/eip-3643) and [its implementation by TokenY](https://github.com/TokenySolutions/T-REX). The intention is not to label original implementation as "bad", but to highlight areas where enhancements are deemed necessary for a more robust and efficient token standard. ### ERC-3643 Overview #### 1. ERC20 compliance ERC-3643 aligns with the ERC20 standard. It incorporates all ERC20 methods, making it readily applicable on various exchanges and other protocols. #### 2. Roles ERC-3643 defines two key roles: Owner and Agents. Owner has the authority to set Agents, manage dependencies, and modify the name and symbol of the token. Agents are responsible for executing supplementary administrative methods, such as tokens minting, burning, freezing, etc. #### 3. Transfers The ERC-3643 token contract defines multiple transfer methods designed to modify token balances. Each of these methods incorporates various checks and hooks that are designed to be adaptable by the client.
MethodDescription
mintThis function can only be executed by an Agent. Validates the recipient's verification status using IdentityRegistry.isVerified. Utilizes ModularCompliance.canTransfer to verify compliance before executing the mint. Executes the mint using ERC20._mint. Invokes ModularCompliance.created to handle compliance-related actions.
burnThis function can only be executed by an Agent. Validates that the user's balance is sufficient for the requested burn amount. Computes the free balance by subtracting any frozen tokens from the user's total balance. If the burn amount exceeds the free balance, unfreezes the necessary tokens. Executes the burn using ERC20._burn. Invokes ModularCompliance.destroyed to handle compliance-related actions.
transferThis function is callable only when the token is not paused. It ensures that both the sender's and recipient's wallets are not frozen. Checks for sufficient balance, considering any frozen tokens. Validates the recipient's verification status using IdentityRegistry.isVerified. Utilizes ModularCompliance.canTransfer to verify compliance before executing the transfer. Executes the transfer using _transfer. Calls ModularCompliance.transferred to handle compliance-related actions.
transferFromSimilar to transfer.
forcedTransferThis function can only be executed by an Agent. Validates that the sender's balance is sufficient for the transfer. Computes the free balance by subtracting any frozen tokens from the sender's total balance. If the requested transfer amount exceeds the free balance, unfreezes the necessary tokens to fulfill the transfer. Checks if the recipient is verified using IdentityRegistry.isVerified. Executes the transfer using _transfer. Calls ModularComplianace.transferred to handle compliance-related actions.
#### 4. Tokens freezing In the ERC-3643 token contract, Agents have the capability to selectively freeze a specified amount of tokens within user wallets through the `freezePartialTokens` method, unfreeze specific frozen tokens with `unfreezePartialTokens`, and freeze or unfreeze entire wallets using `setAddressFrozen`. This functionality restricts users from utilizing the frozen tokens and wallets, preventing their transfer to other users. #### 5. Batch methods The ERC-3643 token contract incorporates a suite of batch methods designed to streamline the execution of multiple transfers or freezes within a single transaction. These methods include: * `batchTransfer` * `batchForcedTransfer` * `batchMint` * `batchBurn` * `batchSetAddressFrozen` * `batchFreezePartialTokens` * `batchUnfreezePartialTokens` #### 6. Pausable In the ERC-3643 token contract, Agents possess the capability to pause the contract. When the contract is in a paused state, users are temporarily restricted from interacting with the token. However, Agents retain the ability to perform actions, such as `forcedTransfer`, within the contract despite the pause. #### 7. Modular Сompliance (MC) ERC-3643 tokens have the ability to adopt multiple compliant rules, allowing Owner to customize these rules as needed. This is made through the integration of the `ModularCompliance` contract, which serves as a dependency for each token. `ModularCompliance` features hooks that activate when token transfer methods are executed (see Transfers section for reference). During this process, `ModularCompliance` iterates through all stored modules, delegating hook execution to each one. Examples of modules are provided below.
ModuleDescription
ConditionalTransferModuleRequires transfers to be pre-approved before they can be executed
CountryAllowModuleManages country-based restrictions
ExachangeMonthlyLimitsModuleDisallows transferring more tokens than the set monthly limit
MaxBalanceModuleLimits the number of tokens per user
SupplyLimitModuleLimits the total supply
TransferFeesModuleEnables the charging of fees for token transfers
#### 8. Identity Registry and ONCHAIN-ID T-REX integrates `IdentityRegistry` (IR) for user KYC status validation using the `IdentityRegistry.isVerified` function. `IdentityRegistry` comprises three contracts:
ContractFunctionality
IdentityRegistryStorage (IRS)Agents handle storage of user identities with associated country information.
TrustedIssuersRegistry (TIR)Owner can set Trusted Issuers who are authorized to set claim topics.
ClaimTopicsRegistry (CTR)Owner can define and manage claim topics.
These contracts are tightly integrated with the ONCHAIN-ID KYC system, implementing ERC-734 and ERC-735 standards for identity management. **9. Recovery** In the ERC3643 token contract, the `recoveryAddress` function serves as a tool for recovering tokens linked to a lost or compromised wallet. Triggered by Agent, the process involves validating the investor's identity using the ONCHAIN-ID. Once successfully verified, it removes the previous identity from the IRS, establishes the identity of the new wallet, transfers the investor's tokens to the new address and, if necessary, performs a partial token or address freeze. #### 10. Deployment The deployment process can be initiated through the `TREXFactory` contract and includes various components such as `Token` itself, `TrustedIssuersRegistry` (TIR), `ClaimTopicsRegistry` (CTR), `IdentityRegistryStorage` (IRS), `IdentityRegistry` (IR), `ModularCompliance` (MC) and corresponding modules. It involves creating instances of these contracts, configuring relationships between them, and establishing roles. #### 11. Upgradeability Every system contract is deployed under a proxy, which maintains a reference to the `TREXAuthority` contract. The `TREXAuthority` contract, in turn, serves as a repository for all implementations, including Token, TIR, CTR, and others. In the `fallback` function of the proxy, the implementation contract is dynamically retrieved from the `TREXAuthority`, and a `delegatecall` is then made to it. 
fallback() external payable {
    address logic = (
        ITREXImplementationAuthority(getImplementationAuthority())
    ).getTokenImplementation();

    assembly {
        // ...

        let success := delegatecall(..., logic, ...)
 
        // ...
    }
}
This mechanism is similar to the Beacon Proxy pattern. To upgrade the implementation, one must interact with the `TREXAuthority` contract, which affects all proxies bound to it. #### 12. DVD The `DVDTransferManager` contract is designed to handle the exchange of two different tokens between a maker and a taker, including both ERC20 and T-REX tokens (similar to Swapica). #### 13. DVA The `DVATransferManager` contract introduces a multi-acceptance requirement for transfers, indicating a design where multiple approvals are essential for executing asset transfers ### TokenF Overview The primary challenge associated with the ERC-3643 standard lies in its inherent complexity, requiring the intricate management of multiple contracts and a substantial level of technical expertise. This complexity can hinder widespread adoption of the standard as it resembles more of a specialized service rather than a standard that [can be readily used by anyone](https://ethereum.stackexchange.com/questions/148806/how-to-deploy-a-token-using-the-erc-3643-standard). To address these issues, the TokenF framework has been envisioned to provide a simplified and accessible implementation of the ERC-3643 standard. Here are some ideas on how to do this. * Inherit from the ERC20 token standard instead of forking. * Replace the custom implementation of roles with the `AccessControl` or `RBAC` contract. * Consolidate compliance logic within the `beforeTransfer` or `update` hooks instead of dispersing it across individual transfer functions. * Refactor the `forcedTransfer` functionality to exclude unfreeze logic. * Replace batch methods with `Multicall`. * Inherit the `ERC20Pausable` contract instead of implementing a custom pausable mechanism. * Expand the modular compliance to include KYC checks, allowing integration with various KYC services. This removes the dependency on ONCHAIN-ID and provides flexibility for users to choose their preferred KYC provider. * Transform the recovery mechanism into a role-based function, eliminating the need for identity checks. Users could then adopt and customize this function based on their specific requirements. * For a basic deployment, the process should only include the proxy token contract. This should align with deploying traditional non-security tokens, ensuring a straightforward and familiar experience for users. * Make the token an abstract contract with an internal initializer function.