<div align="center"> <img src="./docs/img/raptor-animated.svg" alt="ERC-3643 Raptor — animated T-Rex mascot for the Raptor permissioned token standard implementation" width="820"/>

ERC-3643 Raptor

An educational, gas-optimized reference implementation of the ERC-3643 (T-REX) Permissioned Token Standard, the token standard used for onchain securities and Real World Asset (RWA) tokenization on Ethereum.

Not audited. Not for production. For mainnet security token deployments, use Tokeny's T-REX. Raptor is for learning, forking, and prototyping.

</div>

---

What is ERC-3643?

ERC-3643 (also called T-REX, short for Token for Regulated EXchanges) is an Ethereum token standard for regulated securities and Real World Assets. It extends ERC-20 with onchain identity verification, programmable transfer compliance, and agent-controlled freeze and recovery.

Tokeny Solutions wrote the original implementation and the spec was ratified as EIP-3643. It's widely used for compliant security token issuance on Ethereum and other EVM chains.

Plain ERC-20 can't verify who holds a token. ERC-3643 fixes that. Every transfer runs two onchain checks: the recipient must be linked to a verified ONCHAINID carrying valid KYC/AML claims, and the transfer has to satisfy the issuer's compliance rules (country caps, investor caps, transfer windows, and so on).

Raptor is a stripped-down, readable version of that standard for people learning how it works. Read it in one sitting, run it in one evening.

<div align="center"> <img src="./docs/img/ecosystem.svg" alt="ERC-3643 at the center of the Real World Asset tokenization ecosystem — treasuries, equities, real estate, bonds, private credit, funds" width="900"/> </div>

Why ERC-3643 Matters for RWA Tokenization

Tokenized Treasuries, tokenized bonds, tokenized private equity, tokenized real estate: every RWA category eventually needs the same thing, a token that only verified and compliant investors can hold. ERC-3643 is the standard that solves it.

What it adds on top of ERC-20:

• Onchain identity gating. Every holder needs a verified ONCHAINID with claims (KYC, AML, accreditation, jurisdiction) signed by authorized issuers. No ONCHAINID, no transfer.
• Compliance at the contract level. Transfers are rejected if they violate programmable rules: country caps, maximum holder counts, lockup windows, whitelists, accreditation checks.
• Agent controls for issuers. Agents can freeze wallets, freeze partial balances, force transfers, recover lost wallets, and pause the token entirely.
• Full ERC-20 compatibility. Wallets, DEXs, and indexers treat it like any ERC-20. The extra checks only fire on writes.

What Is Raptor?

Raptor = Regulated Asset Platform for Tokenized Operations & Resources.

Raptor is an educational, gas-optimized ERC-3643 implementation written in Solidity 0.8.17. It covers the full ERC-3643 core: Token, IdentityRegistry, IdentityRegistryStorage, ClaimTopicsRegistry, ClaimIssuersRegistry, and BasicCompliance.

Design choices vs. the Tokeny reference:

• Uses OpenZeppelin AccessControl instead of custom AgentRole / OwnerRoles.
• Uses OpenZeppelin Pausable instead of a custom pause contract.
• Extended batch API: batchTransferFrom, batchBurn, batchFreezePartialTokens, and friends.
• Metadata (name, symbol, decimals) is immutable at deploy time, matching standard ERC-20 behavior.
• Deliberately non-upgradeable. Proxies add moving parts that obscure how the standard actually works.

What Raptor leaves out on purpose: upgradeable proxies, DVD (Delivery-vs-Delivery) atomic settlement, and modular compliance. All of that belongs in production. See the comparison table for the full diff.

Table of Contents

• What is ERC-3643?
• Why ERC-3643 matters for RWA tokenization
• What is Raptor?
• Features
• Architecture
• How a transfer works
• Quick start
• Deployment
• Testing & coverage
• Contract API
• Differences vs. production T-REX
• Building a custom compliance module
• AI-ready: agents, Claude, Cursor, Copilot
• Security
• Contributing
• Roadmap
• Keywords (SEO/GEO)
• Credits
• License

Features

• Full ERC-3643 core — Token, IdentityRegistry, IdentityRegistryStorage, ClaimTopicsRegistry, ClaimIssuersRegistry, BasicCompliance.
• Gas-optimized — unchecked loop counters, precomputed role hashes, inline returns, consolidated checks.
• OpenZeppelin AccessControl instead of custom AgentRole / OwnerRoles.
• OpenZeppelin Pausable replaces the custom pause mechanism.
• Extended batch API — batchTransfer, batchTransferFrom, batchForcedTransfer, batchMint, batchBurn, batchSetAddressFrozen, batchFreezePartialTokens, batchUnfreezePartialTokens.
• Comprehensive test suite — Hardhat + Mocha + Chai with composable fixtures.
• CI hardened — Slither static analysis, CodeQL, Gitleaks secret scan, Dependabot, multi-version Node matrix.
• AI-ready — AGENTS.md, CLAUDE.md, .cursorrules, Copilot instructions, docs/llms.txt.

Architecture

<div align="center"> <img src="./docs/img/architecture.svg" alt="ERC-3643 Raptor architecture — Token, IdentityRegistry, ClaimTopicsRegistry, ClaimIssuersRegistry, Compliance" width="860"/> </div>

The system has five core contracts. Token is the ERC-20 entry point. Before every user transfer, it calls IdentityRegistry.isVerified(to) and Compliance.canTransfer(from, to, amount). The identity check walks the claim graph: IdentityRegistryStorage provides the wallet-to-ONCHAINID binding, ClaimTopicsRegistry says which claim types are required, and ClaimIssuersRegistry says which issuers are trusted to sign those claims.

For the complete role matrix and contract-level breakdown, see docs/ARCHITECTURE.md.

How a Transfer Works

Every user-initiated transfer passes through this sequence of gates:

<div align="center"> <img src="./docs/img/transfer-flow.svg" alt="Animated diagram: ERC-3643 transfer passes through pause, freeze, balance, identity, and compliance gates before balances update" width="980"/> </div>

Spelled out:

1. Token.transfer(to, amount) called
2. require: token not paused
3. require: sender wallet not frozen
4. require: recipient wallet not frozen
5. require: sender free balance (balance - frozenAmount) >= amount
6. IdentityRegistry.isVerified(to)  <-- KYC/AML claim check
7. Compliance.canTransfer(from, to, amount)  <-- programmable rule check
8. Update balances, emit Transfer event
9. Compliance.transferred(from, to, amount)  <-- post-hook for accounting

Steps 6 and 7 are what separate ERC-3643 from plain ERC-20. Step 6 enforces investor verification through ONCHAINID. Step 7 gives the compliance module a place to track state (counting holders per country to enforce a Reg D cap, for example).

Agent-controlled operations (forcedTransfer, mint, burn, recoveryAddress) skip the pause check but still respect the frozen-balance invariant. See SECURITY.md for the full threat model.

Quick Start

Requirements: Node 18+ (20 LTS recommended), npm 10+, git.

git clone https://github.com/Aboudjem/ERC-3643.git
cd ERC-3643
npm install
npm test

That runs the full test suite against a local Hardhat node. If it's green, you're ready.

Deployment

Local Hardhat Node

npm run build
npx hardhat node                                    # terminal 1
npx hardhat run scripts/deploy.js --network localhost  # terminal 2

Testnet (Sepolia, Polygon Amoy, Base Sepolia)

Copy .env.example to .env, fill in RPC_URL and PRIVATE_KEY, then add a network entry to hardhat.config.ts:

networks: {
  sepolia: {
    url: process.env.SEPOLIA_RPC_URL,
    accounts: [process.env.PRIVATE_KEY],
  },
}

Then deploy:

npx hardhat run scripts/deploy.js --network sepolia

Verify on Etherscan by adding ETHERSCAN_API_KEY to .env and appending --verify to the command.

Testing & Coverage

npm test                 # full test suite
npm run coverage         # line + branch coverage report (coverage/)
REPORT_GAS=true npm test # gas report per function
npm run lint             # solhint + eslint + prettier check
npm run lint:fix         # auto-fix formatting and lint
`