ERC-3643 Tutorial

Overview

ERC-3643 is a permissioned token standard designed for regulated assets and compliant security tokens. Unlike ERC-20 or ERC-1155, ERC-3643 introduces identity verification, claim-based compliance, and enforced transfer restrictions directly at the smart contract level.

In the context of Watr Network, ERC-3643 enables compliant tokenization of regulated commodities such as:

Copper-backed security tokens
Gold certificates
Rare-earth metal shares
Tokenized commodity warehouse receipts

This tutorial demonstrates how to implement a regulated Copper Security Token using the TrustPool architecture, adapted for commodity tokenization.

Unlike permissionless tokens:

Only verified investors can hold tokens
Every transfer passes identity checks
Compliance rules are enforced automatically
Issuers retain regulatory control

This implementation is based on the TrustPool ERC-3643 contract suite.

Architecture Overview

The system consists of modular contracts:

Together they create a compliance-by-design token ecosystem.

Commodity Use Case: Copper Token (CST)

We rename:

ERC3643Token.sol → CopperSecurityToken.sol

Example: 1 CST token = 1 regulated copper unit

This token: - Can only be held by KYC verified investors - Requires AML claim - Enforces jurisdiction restrictions - Enforces investor cap limits

Contract Roles

1. Claim Topic Registry

Defines required claims:

Example topics:

1 → KYC Verified
2 → AML Cleared
3 → Accredited Investor
100 → Commodity Investor Authorization

Admin functions:

addClaimTopic(uint256 topic)
removeClaimTopic(uint256 topic)

2. Trusted Issuers Registry

Registers authorized KYC providers and compliance entities.

Functions:

addTrustedIssuer(address issuer, uint[] topics)
removeTrustedIssuer(address issuer)

Only claims signed by trusted issuers are accepted.

3. Identity Contract

Each investor deploys an on-chain identity contract.

Stores: - Claims - Claim issuers - Claim topics

Key functions: - addClaim() - removeClaim()

4. Identity Registry

Maps wallet → identity contract.

Core functions:

registerIdentity(address wallet, identity, uint16 country)
deleteIdentity(address wallet)
isVerified(address wallet)

This ensures only whitelisted identities participate.

5. Compliance Contract

Handles transfer validation.

Core function:

canTransfer(address from, address to, uint256 amount)

Checks: - Both identities verified - Required claims present - Country allowed - Transfer limits not exceeded

6. CopperSecurityToken (ERC3643Token)

Extends ERC-20 but integrates compliance engine.

Core functions:

transfer()
transferFrom()
mint()
burn()
forcedTransfer()
pause()
setAddressFrozen()

Transfers automatically call:

IdentityRegistry.isVerified()
Compliance.canTransfer()

If either fails → transfer reverts.

Deployment Order

Deploy contracts in this order:

ClaimTopicRegistry
TrustedIssuersRegistry
IdentityRegistry
Compliance
CopperSecurityToken
TokenFactory

Then configure:

Set required claim topics
Add trusted issuers
Link Compliance to Token
Link IdentityRegistry to Token

ERC-3643 Playground Repository

Watr provides an ERC-3643 playground repository on GitHub: Watr-Protocol/erc-3643-playground.

The repository includes:

Core ERC-3643 smart contracts
ABI files for contract integration
A step-by-step README for deployment
A UI playground for interacting with deployed contracts

You can follow the README to deploy the contracts, then run the UI either on your local machine or in the cloud. Once deployed, the UI allows you to connect a wallet and interact with the contracts from the previous deployment step.

Example Hardhat Deployment Script

async function main() {

  const ClaimTopics = await ethers.getContractFactory("ClaimTopicRegistry");
  const claimTopics = await ClaimTopics.deploy();

  const Trusted = await ethers.getContractFactory("TrustedIssuersRegistry");
  const trusted = await Trusted.deploy();

  const IdentityRegistry = await ethers.getContractFactory("IdentityRegistry");
  const identityRegistry = await IdentityRegistry.deploy(
      trusted.target,
      claimTopics.target
  );

  const Compliance = await ethers.getContractFactory("Compliance");
  const compliance = await Compliance.deploy();

  const Token = await ethers.getContractFactory("ERC3643Token");
  const copper = await Token.deploy(
      identityRegistry.target,
      compliance.target,
      "Copper Security Token",
      "CST",
      18
  );

  console.log("CopperSecurityToken:", copper.target);
}

Investor Onboarding Flow

Step 1: Investor deploys Identity contract
Step 2: KYC Provider issues claim
Step 3: Admin registers identity in IdentityRegistry
Step 4: Investor can now receive CST tokens

If any step missing → transfer fails.

Minting Example

await copper.mint(investorAddress, ethers.parseUnits("100", 18));

Mint bypasses compliance but requires verified identity.

Transfer Example

await copper.transfer(receiver, ethers.parseUnits("10", 18));

Internally checks:

isVerified(sender)
isVerified(receiver)
canTransfer()

Forced Transfer (Regulatory Action)

await copper.forcedTransfer(from, to, amount);

Used for: - Court orders - Regulatory clawbacks - Lost wallet recovery

Freezing Investor

await copper.setAddressFrozen(investor, true);

Prevents further transfers.

Why ERC-3643 for Commodities?

Use ERC-3643 when:

Commodity is regulated
Investor eligibility matters
Jurisdiction restrictions apply
Secondary trading must remain compliant
Issuer retains regulatory authority

Examples:

Tokenized copper warehouse shares
Precious metals fund
Rare earth mining equity tokens
Commodity-backed STO

Comparison

Feature	ERC-20	ERC-1155	ERC-3643
Fungible	✓	✓	✓
Multi-token	✗	✓	✗
Identity required	✗	✗	✓
Compliance engine	✗	✗	✓
Regulated securities	✗	✗	✓

Security & Production Recommendations

Replace Ownable with AccessControl
Use multisig for admin
Add upgradability (UUPS or Transparent Proxy)
Separate compliance modules for modular updates
Audit identity verification logic carefully

Conclusion

ERC-3643 introduces regulated tokenization to the commodity ecosystem.

For Watr Network, it enables:

Compliant copper tokens
Identity-bound asset ownership
Regulatory-grade commodity token infrastructure
Permissioned secondary markets

Unlike ERC-20 or ERC-1155, ERC-3643 ensures that compliance is enforced at the protocol level, making it ideal for regulated commodity markets.

Overview​