Setting Up an ERC-3643 Compliant Tokenization Framework

ERC-3643 is an open-source standard for permissioned tokens on Ethereum and other EVM-compatible chains. Unlike standard ERC-20 tokens, which are permissionless, ERC-3643 tokens have built-in controls for identity verification (onchainID), transfer rules, and compliance checks. This makes them suitable for tokenizing regulated assets like securities, funds, and real estate, where investor accreditation and jurisdictional rules must be enforced programmatically. The standard provides a modular framework where compliance logic is separated from core token functions, allowing for flexible adaptation to different regulatory regimes.

The core architecture revolves around three main smart contracts. First, the Token contract itself, which holds the balance and supply logic. Second, the Compliance contract, which contains the rules engine that validates every transfer against configurable conditions. Third, the Identity Registry, which stores and verifies the onchainID of token holders, linking their wallet address to a verified identity. This separation allows you to upgrade compliance rules without needing to migrate the token, a critical feature for long-lived regulated instruments. You can find the official reference implementations on the ERC-3643 Association GitHub.

To begin development, you'll need to set up your environment with Hardhat or Foundry and install the necessary packages. Start by forking the official repository. The key step is deploying the contracts in the correct order: first the Identity Registry, then the Compliance contract (passing the registry's address to its constructor), and finally the Token contract (linking to both the compliance and registry). Here's a simplified deployment script snippet:

javascriptCopy
const Identity = await ethers.getContractFactory('IdentityRegistry');
const identity = await Identity.deploy();

const Compliance = await ethers.getContractFactory('BasicCompliance');
const compliance = await Compliance.deploy(identity.address);

const Token = await ethers.getContractFactory('Token');
const token = await Token.deploy(identity.address, compliance.address);

After deployment, you must configure the compliance rules. The BasicCompliance contract includes functions like addAgent to authorize administrators and canTransfer which contains the core transfer validation logic. For most use cases, you will need to extend this contract to implement specific rules, such as checking if a sender is accredited, if the recipient's country is allowed, or if the transfer would breach ownership limits. All transfers call the compliance contract's canTransfer function, which must return true for the transaction to succeed. This on-chain enforcement is the foundation of the token's regulatory compliance.

Integrating an off-chain identity verification provider is essential for a production system. The onchainID is a smart contract wallet that holds claims issued by trusted attestors (like KYC providers). Before a user can receive tokens, their wallet address must be linked to a verified onchainID in the Identity Registry. Providers like Shyft or Veriff can perform the KYC/AML checks and issue a verifiable credential to the user's onchainID. Your application's front-end should guide users through this identity onboarding process before allowing them to interact with the token contract.

Finally, consider gas optimization and upgradeability. ERC-3643 interactions involve more contract calls than a simple ERC-20 transfer, increasing gas costs. Using a gas-efficient identity registry design and considering layer-2 solutions like Polygon or Arbitrum can mitigate this. For upgradeability, use the Proxy pattern for your Compliance contract so rules can be amended as regulations change, without affecting token holdings. Thoroughly test all compliance scenarios—successful transfers, blocked transfers, agent permissions, and identity revocations—using a comprehensive test suite before moving to a mainnet deployment.

Building on the ERC-3643 standard, also known as the Tokenized Assets Standard (TAS), requires a specific development environment. The core prerequisite is a solid understanding of Ethereum smart contract development using Solidity. You should be familiar with concepts like inheritance, interfaces, and the ERC-20 standard, as ERC-3643 extends these foundations. Essential tools include Node.js (v18+), npm or yarn, and a code editor like VS Code. You will also need access to an Ethereum node for testing; services like Alchemy, Infura, or a local Hardhat node are standard choices.

The primary dependency is the official @tokenizedassets/tas library, which provides the core smart contract interfaces and implementations. Install it via npm: npm install @tokenizedassets/tas. This package includes the key contracts: ICompliance, IToken, IModule, and their implementations, which handle the permissioning logic, transfer rules, and agent management central to the standard. For development and testing, pair this with a framework like Hardhat or Foundry. A typical hardhat.config.js will configure the Solidity compiler for version 0.8.20 or later, which is required for the library's use of custom errors and other modern features.

Before writing any token logic, you must design your compliance framework. This involves implementing the ICompliance interface to define the rules for your token. A basic compliance contract might store a list of verified wallets or integrate with an on-chain KYC provider. You can extend the provided Compliance base contract. Simultaneously, plan your token modularity. ERC-3643 uses a modular architecture where features like transfer restrictions or investor caps are added via modules. Decide which modules (e.g., TransferModule, MintModule) your asset requires and prepare to deploy them as separate contracts that will be plugged into the main token.

A critical setup step is configuring the On-chain Agent (ONCHAINID). This is an identity smart contract (often an ERC-734/735 manager) that represents the token issuer and other privileged actors. The token contract will query the ONCHAINID to verify if an address holds the required Compliance Role or Agent Role to perform administrative actions. You can deploy a fresh ONCHAINID using the factory contracts provided in the @onchainid/solidity package, or use an existing identity if you have one. The token's constructor will require the address of this identity contract, linking the permissioned system together from the start.

Finally, establish a robust testing strategy. Write comprehensive tests for all compliance rules and module interactions using Hardhat (with Chai and Waffle) or Foundry's Solidity test suite. Test scenarios must include: successful transfers between verified wallets, blocked transfers to non-compliant addresses, agent role permissions for minting/burning, and the correct behavior when modules are added or removed. Testing on a forked mainnet or a local simulation is crucial before considering deployment. Once your environment is configured, dependencies are installed, and your compliance logic is drafted, you are ready to proceed with writing and deploying your ERC-3643 token contract.

The ERC-3643 standard defines a permissioned token framework for representing real-world assets (RWAs) on-chain. Unlike public ERC-20 tokens, it embeds on-chain compliance directly into the token's transfer logic. The architecture is modular, separating concerns into distinct contracts: a core token, a permissions registry, and compliance modules. This separation allows issuers to customize rules for identity verification, investor accreditation, and jurisdictional restrictions without modifying the core token contract. The standard is governed by the Tokenized Asset Coalition (TAC) and is widely adopted by security token platforms like Polymath and Tokeny.

The core of the system is the ERC-3643 token contract, which inherits from ERC-20. Its key function, canTransfer, is called before every transfer. This function queries an external Identity Registry to check if the sender and receiver have valid, verified identities with the required credentials. If the registry returns false, the transfer is reverted. This registry stores Identity Data Structures for each investor wallet, including expiry timestamps and investor type flags (e.g., isVerified, isAccredited). The token contract itself is agnostic to the specific compliance logic, relying on the registry's verdict.

Compliance rules are enforced by the Compliance Smart Contract, a separate module that the Identity Registry consults. This is where the business logic for transfer restrictions lives. A basic compliance contract might check if both parties are verified. A more advanced one could enforce transfer limits, holding periods, or check against a sanctions list. The modular design means you can upgrade or replace the compliance module without migrating the token, providing significant flexibility. You can deploy multiple compliance contracts for different share classes or jurisdictions within the same token ecosystem.

Here is a simplified code snippet showing the interaction between the token and the registry during a transfer attempt. The critical override is in the internal _transfer function.

solidityCopy
function _transfer(address from, address to, uint256 value) internal virtual override {
    // Query the Identity Registry via the token's controller
    require(
        tokenIdentityRegistry.isVerified(from) && tokenIdentityRegistry.isVerified(to),
        "Identity not verified"
    );
    // Query the Compliance contract
    require(
        tokenCompliance.canTransfer(from, to, value),
        "Transfer not compliant"
    );
    // Proceed with standard ERC-20 transfer logic
    super._transfer(from, to, value);
}

This pattern ensures non-compliant transfers are impossible, a fundamental requirement for regulated assets.

A practical deployment involves several steps. First, deploy the Identity Registry contract and the chosen Compliance contract. Next, deploy the main ERC-3643 token, passing the addresses of the registry and compliance contracts to its constructor. Then, an off-chain Trusted Issuer must onboard investors by submitting KYC/AML data, which is written to the Identity Registry, minting a Claim for the investor's wallet. Only after this claim is minted can the wallet receive tokens. The entire state—identities, compliance status, and token balances—is publicly verifiable on the blockchain, providing transparency to regulators and auditors.

Key considerations for developers include gas optimization for frequent compliance checks, designing upgrade pathways for modules, and ensuring secure off-chain data feeds for oracle-dependent rules. The standard's extensibility also allows for composable modules, such as adding a DRS (Direct Registration System) module for tracking beneficial ownership off-chain. For full specifications and reference implementations, consult the official ERC-3643 documentation.

The ERC-3643 standard (formerly T-REX) is designed for Security Tokens and other regulated assets, mandating on-chain identity verification and rule enforcement. Unlike public ERC-20 tokens, ERC-3643 tokens can only be held and transferred by wallets that have passed a Know Your Customer (KYC) check and meet specific compliance rules. This is managed by two primary smart contracts: the Identity Registry and the Compliance contract. The Identity Registry stores and manages the verified identity status of investor addresses, while the Compliance contract encodes the legal and regulatory rules that govern token transfers.

Deployment begins with the Identity Registry. You will deploy a contract like IdentityRegistry.sol, which acts as a whitelist. This contract stores the Identity of an investor, which typically includes a country code, an investorID, and an expiryDate for the KYC validity. Only identities stored here can interact with the token. The registry provides critical functions like registerIdentity, updateIdentity, and deleteIdentity. It's common to integrate with an off-chain identity provider (like Shyft, Veriff, or Netki) that performs the actual KYC checks and then calls these functions via a secure, permissioned backend.

Next, you deploy the Compliance smart contract. This is the rule engine for your token. The standard provides a ModularCompliance.sol contract that allows you to attach and detach compliance modules. Each module enforces a specific rule, such as checking if the transfer amount is below a limit (MaxBalanceModule), verifying the investor's country is not restricted (CountryRestrictionModule), or ensuring the receiver's identity is valid before a transfer completes. You initialize the Compliance contract and then bind your chosen modules to it, creating a customizable rule set tailored to your security offering's requirements.

Finally, you must link these components. The Compliance contract holds a reference to the Identity Registry to verify user status during rule checks. When you later deploy the ERC-3643 token contract itself (Step 2), you will pass the addresses of both the Identity Registry and the Compliance contract to its constructor. This creates the foundational triangle: the Token queries the Compliance for approval on every transfer, and the Compliance in turn checks investor data in the Identity Registry. This architecture ensures that non-compliant transfers are automatically reverted on-chain.

For developers, the official ERC-3643 documentation and the Tokeny Solutions GitHub repository provide the canonical smart contract implementations and deployment scripts. Testing this setup on a testnet like Sepolia is crucial. You should write and run scripts to verify that: identities can be registered, compliance rules are enforced, and unauthorized transfers fail as expected before proceeding to token deployment.

Before deployment, ensure your development environment is configured. You will need Node.js (v18+), npm or yarn, and access to an EVM-compatible blockchain like Ethereum mainnet, Polygon, or a testnet such as Sepolia. Install the OpenZeppelin Contracts library and the official ERC-3643 package via npm: npm install @openzeppelin/contracts @tokeny/ERC-3643. Use a framework like Hardhat or Foundry for compilation and scripting. Securely store your deployer wallet's private key in an environment variable (e.g., PRIVATE_KEY) using a .env file, never in source code.

The core of deployment is configuring the contract constructor. The Token constructor requires several key parameters that define your security token's compliance rules. You must set the _onchainID address (the identity registry contract), the _claimTopicsRegistry address, and the _trustedIssuersRegistry address. Crucially, you must also define the token's _compliance contract address; this can be a pre-deployed instance of a standard compliance module like ModularCompliance or a custom implementation. These parameters permanently encode the token's regulatory framework on-chain.

Write a deployment script (e.g., deploy.js in Hardhat) to orchestrate the process. The script should: 1. Connect the wallet using the provider and private key, 2. Deploy any necessary registry contracts if not already existing, 3. Deploy the chosen compliance contract and configure its rules, 4. Finally, deploy the main Token.sol contract, passing the registry and compliance addresses to the constructor. Always estimate gas costs before sending the transaction and handle potential reverts. Example script templates are available in the ERC-3643 documentation.

After a successful transaction, immediately verify and publish your contract's source code on a block explorer like Etherscan or Polygonscan. Verification is critical for transparency, security audits, and user trust. Use the --verify flag in Hardhat or the explorer's manual upload tool, providing the constructor arguments used. Once verified, interact with the contract through the explorer's "Write Contract" interface to perform initial actions: setting the name and symbol via the setIdentity function, and calling addAgent to grant administrative permissions to designated wallets for managing token transfers and identities.

Post-deployment, integrate the contract address into your front-end application and back-end services. Use libraries like ethers.js or web3.js to create an instance of your token contract. The primary interface will be the ERC-3643 ABI, which includes functions like canTransfer (for checking transfer validity), balanceOf (which returns 0 for non-verified holders), and the various agent functions for compliance management. Thoroughly test all flows—identity minting, transfer with claims, and forced transfers—on testnet before considering any mainnet operations.

Transfer restriction rules are the programmable compliance engine of an ERC-3643 token. These rules are implemented as smart contract functions that evaluate every transfer and transferFrom call, returning true or false based on custom logic. The primary interface for this is the ICompliance.sol contract. Your compliance contract must implement the canTransfer function, which receives parameters like the sender's address (_from), receiver's address (_to), and token amount (_value). This is where you codify your jurisdiction's regulations and internal policies.

A common starting point is implementing rules based on on-chain identity verification. For example, you can restrict transfers to only wallets that have a valid, non-expired Verified Investor certificate issued by an on-chain identity provider like Tokeny's T-REX or Polygon ID. The rule would query the identity registry to check the receiver's (_to) status before approving the transfer. Other typical rules include enforcing transfer windows (e.g., only during trading hours), setting daily volume limits per wallet, or blocking transfers to sanctioned addresses via integration with oracle services like Chainlink.

For development and testing, you can use the ERC-3643 Foundry Template or OpenZeppelin-style libraries that provide modular, auditable rule components. Below is a simplified example of a compliance contract checking for a specific investor status:

solidityCopy
function canTransfer(address _from, address _to, uint256 _value) external view override returns (bool) {
    // 1. Check if receiver ('_to') is verified
    (bool isVerified, uint256 expiryDate) = identityRegistry.isVerified(_to);
    if (!isVerified || expiryDate < block.timestamp) {
        return false;
    }
    // 2. (Optional) Check against a sanctions oracle
    if (sanctionsOracle.isSanctioned(_to)) {
        return false;
    }
    // 3. If all checks pass, allow the transfer
    return true;
}

This function structure allows you to stack multiple conditions, creating a comprehensive ruleset.

After deploying your custom Compliance.sol contract, you must link it to your main token contract. This is done by calling the setCompliance function on the token, passing the address of your new compliance module. It's critical to thoroughly test all rule logic on a testnet using a suite of scenarios: valid transfers, transfers to unverified addresses, expired certificates, and volume limit breaches. Tools like Hardhat or Foundry are ideal for this. Remember, once live, updating the compliance contract requires careful migration, as the token holds a single reference to it.

Effective rule configuration balances regulatory adherence with user experience. Overly restrictive rules can hinder liquidity and usability, while lax rules introduce compliance risk. Start with a core set of essential rules for your launch jurisdiction, and design the system to be upgradeable to accommodate future regulatory changes or new business requirements. The ERC-3643 standard's separation of concerns—keeping compliance logic in a separate, swappable contract—is key to maintaining this flexibility long-term.

The ERC-3643 standard delegates identity verification to external, specialized providers known as On-Chain KYC/AML Providers. These are smart contracts that maintain a registry of verified investor addresses and their compliance status (e.g., VERIFIED, EXPIRED, SUSPENDED). Your token contract does not store personal data; instead, it queries these provider contracts to check if a wallet address is authorized to send or receive tokens. This separation of concerns enhances privacy and allows for modular upgrades to the compliance logic without modifying the core token contract.

To integrate a provider, your token's constructor or an initialization function must set the provider's contract address. This is done by calling the setCompliance function inherited from the ERC-3643 base contracts. For example, using the OpenZeppelin-based implementation, you would pass the provider's address to the compliance module. A common provider is the Tokeny Solutions' T-REX suite, but you can also integrate custom or alternative providers like Quadrata or Veriff that offer on-chain attestations. The key is that the provider contract must implement the specific interface (IIdentityRegistry) defined by the ERC-3643 standard.

Once integrated, every token transfer function (like transfer or transferFrom) will internally call the provider's isVerified function. If the sender or receiver's address is not in a valid state, the transaction will revert. This enforcement is gas-efficient and automatic, occurring on-chain without manual intervention. Providers typically offer off-chain KYC portals where users submit documentation; upon approval, the provider's oracle or admin mints an Identity NFT or updates a registry mapping to reflect the user's verified status on-chain.

Developers must handle edge cases such as expiry and revocation. A provider should emit events when a status changes, allowing your dApp's frontend to react accordingly. You may also need to implement logic for forced transfers (via a forcedTransfer function) which allows a compliance officer to move tokens between addresses even if one is non-verified, useful for regulatory actions or recovering from lost keys, while maintaining the total supply and compliance record.

For testing, you can deploy a mock provider contract that manually sets addresses as verified. In production, ensure you understand the provider's slashing mechanisms, update delays, and fee structures. The choice of provider impacts the security, cost, and user experience of your tokenized asset. Always verify the provider's audit reports and their on-chain reputation within the ERC-3643 ecosystem before integration.

After deploying your Token and Compliance smart contracts and configuring the initial rules, the next step is to mint tokens to the first investors. In ERC-3643, the mint function is permissioned and should be called by an address with the Minter role. This function interacts with the attached Compliance contract to verify the recipient's identity and eligibility before creating new tokens. A typical minting call requires the recipient's address and the amount. It's crucial to ensure the recipient's wallet is already verified and onboarded through the identity registry, as the compliance check will fail otherwise.

For example, using a deployed Token contract instance in a script, you would call:

javascriptCopy
await tokenContract.mint(investorAddress, ethers.parseEther("1000"));

This triggers an internal call to _checkAndUpdateTransfers within the compliance module. The compliance contract will validate the transfer against all active rules—such as country restrictions, investor accreditation status, and holding period locks—before allowing the mint. If any rule is violated, the transaction will revert, ensuring no non-compliant tokens are ever created.

Executing a compliant transfer between two users follows a similar but more complex path. When a user calls transfer or transferFrom, the token contract delegates the compliance check. The compliance contract evaluates the transaction context, which includes the sender's and receiver's identities, the amount, and the token ID (if applicable). Rules like transfer restrictions (daily limits), lock-up periods, and whitelist requirements are enforced at this stage. Successful transfers will also call the compliance contract's _transferActions hook, which can update internal state, such as decrementing a user's used daily limit.

Developers must handle the revert scenarios gracefully. Common reasons for a failed transfer include the receiver not being verified, the transfer exceeding a volume limit, or attempting to move tokens during a lock-up period. Front-end applications should catch these transaction reverts and parse the custom error messages from the compliance contract to provide clear feedback to users, such as "Transfer failed: Recipient is not on the whitelist" or "Daily transfer limit exceeded."

Finally, it's essential to monitor and log all minting and transfer events. The ERC-3643 standard emits standard ERC-20 Transfer events, but your compliance contract should emit custom events for rule violations, successful compliance checks, and identity status changes. These events are critical for off-chain monitoring, reporting, and auditing purposes. Tools like The Graph can be used to index these events, providing a real-time dashboard of all compliant activity on-chain.

Your framework is now operational with a deployed PermissionedToken (ERC-3643) contract, a connected ONCHAINID for identity management, and a configured TrustedIssuersRegistry. The next critical phase is operationalizing this system. This involves integrating your chosen compliance provider (like Tokeny, Quadrata, or Fractal) to manage the KYC/AML verification process that populates the ONCHAINID with claims. You must also develop or integrate a dApp interface where users can submit verification, request tokens, and where authorized agents can execute transfers on their behalf via the transferByPartition function.

For ongoing management, establish clear processes for key roles. Compliance Officers will need a dashboard to review and approve investor statuses, while Transfer Agents require tools to process on-chain transfers for verified users. Regularly audit the TrustedIssuersRegistry and the claims within your identity contracts to ensure they are current and valid. Remember, the _isTransferAuthorized function in your token contract will check these claims for every transfer attempt, enforcing your compliance rules automatically.

To deepen your understanding, explore the official ERC-3643 documentation and the ONCHAINID repository. For production deployment, conduct thorough security audits on your entire stack, consider implementing a pause mechanism for the token contract in case of emergencies, and plan your upgrade strategy for the proxy contracts. The final step is to connect your framework to real-world liquidity by listing your permissioned token on a compliant exchange like Swarm Markets or Archax.