Enforcing On-Chain Investor Eligibility & Jurisdiction Limits in RWA Token Transfers

When tokenizing real-world assets (RWA), such as private credit, real-estate income rights, government bonds, or commodities, and issuing them on public chains, the hardest problem for issuers and engineering teams is look-through compliance for secondary-market peer-to-peer transfers, rather than off-chain asset registration.

Under traditional securities frameworks, including US SEC Reg D / Reg S, Singapore MAS, and EU MiCA, compliant issuance faces three firm legal boundaries:

  1. Individual investor holding limits: to prevent market concentration or triggering antitrust filing thresholds, an eligible investor’s holdings are often limited to a percentage of the total issuance, such as no more than 5% or 100,000 units;
  2. Statutory caps on accredited/non-accredited investors: certain private-placement exemptions impose a hard limit on the holders in one issuing entity, such as 99, 499, or 2000. Crossing that threshold forces the project to make disclosures at public-company standards;
  3. Jurisdiction restrictions: assets must not reach unauthorized jurisdictions, such as sanctioned countries or regions where the securities have not been registered.

If a team simply uses the standard OpenZeppelin ERC20 contract, or tracks and validates holdings only through a wallet-level mapping(address => uint256), secondary trading can expose the system to a serious multi-wallet Sybil bypass:

After completing off-chain KYC, one compliant investor can generate five EVM wallets (Wallet A ~ Wallet E) under the same identity credential. If the contract checks only balanceOf[wallet] <= maxHolding, that investor can hold 50,000 tokens in each wallet: 250,000 in total, or 25% of the entire issuance, bypassing the holding cap. Worse, when that investor reorganizes funds between Wallet A and Wallet B, a contract that counts holders whenever a recipient balance goes from zero to nonzero will inflate the statutory holder count to 2. This can trigger the investor cap and block legitimate transfers.

To handle multiple wallets belonging to one legal identity, exact net-holder accounting, and dynamic country lists, Aurum RWA uses a production on-chain compliance engine built on ERC-3643 and a modular architecture. This article examines its RwaComplianceModuleCore.sol implementation and Foundry boundary tests.


Architecture: From Off-Chain KYC to Two-Level Identity–Wallet Mapping

Enforcing On-Chain Investor Eligibility & Jurisdiction Limits in RWA Token Transfers

Aurum RWA separates investor governance into a wallet access layer, a decentralized identity credential layer (ONCHAINID), and a modular compliance assertion layer:

+-----------------------------------------------------------------------------------+
|                    Aurum RWA Secondary-Transfer Compliance Pipeline               |
+-----------------------------------------------------------------------------------+
|  1. Identity Registry & Claim Verification                                        |
|     - Bind each real investor to an independent Identity contract (ONCHAINID)     |
|     - Check claim topics: RWA_CLAIM_V1 KYC (Topic 1) and asset eligibility (Topic 3)|
|     - Aggregate country codes: ISO 3166-1 numeric codes (840 US, 826 UK)           |
+-----------------------------------------------------------------------------------+
                                       |
                                       v
+-----------------------------------------------------------------------------------+
|  2. Identity-Wallet Dual-Level Ledger                                             |
|     - walletIdentity[wallet] => identity (multiple wallets, one real identity)    |
|     - identityBalance[identity] aggregates tokens across all investor wallets    |
|     - walletBalance[wallet] tracks individual hot/cold wallet balances            |
+-----------------------------------------------------------------------------------+
                                       |
                                       v
+-----------------------------------------------------------------------------------+
|  3. Static Policy Assertions (RwaComplianceModuleCore: validateTransfer)          |
|     - Country filter: CountryMode (0: NONE, 1: ALLOWLIST, 2: BLOCKLIST)            |
|     - Time lock: block.timestamp >= transferUnlockAt (prevent pre-lockup trades) |
|     - Partial freeze: walletBalance[from] - frozenTokens >= transferAmount        |
+-----------------------------------------------------------------------------------+
                                       |
                                       v
+-----------------------------------------------------------------------------------+
|  4. Net Investor Count & Holding-Limit Boundary Calculations                     |
|     - Same-identity transfers (a == b): holder count and total holdings unchanged|
|     - Cross-identity transfers:                                                  |
|       * Sender identityBalance reaches zero: decrement investorCount by 1        |
|       * Recipient identityBalance rises from zero: increment investorCount by 1 |
|       * Recipient total: identityBalance[to] + q <= maxBalance                    |
+-----------------------------------------------------------------------------------+

Comparing Three RWA Transfer-Compliance Approaches

Architecture dimension Standard OpenZeppelin ERC-20 + centralized blocklist Basic address-level compliance contract Aurum RWA modular identity and compliance engine (ERC-3643)
Investor identification Raw wallet addresses, with no real-identity binding Wallet allowlist mapping(address => bool) ONCHAINID identity contracts + claim tree
Protection against splitting holdings across wallets 0% protection (split wallets freely to bypass) 0% protection (only limits individual address balances) 100% immunity (mandatory aggregation at real-identity level)
Statutory holder count Unsupported Counts nonzero addresses, easily inflating the total past the cap Net-holder calculation (transfers within one identity add no holders)
Country-admission changes Unsupported Hard-coded country rules require contract upgrades Country Mode 0/1/2 supports smooth dynamic allowlist/blocklist switching
Court-ordered transfers and recovery Impossible (lost keys mean lost assets) Single-signature admin has excessive privileges and a centralized backdoor Controlled AgentController context + on-chain document-hash audit trail

Core Contract: RwaComplianceModuleCore.sol

In aurum-rwa/contracts/src/RwaComplianceModuleCore.sol, all compliance policies are encapsulated in modules. When executing transfer or transferFrom, ERC-3643’s Token.sol must call this compliance module through an external interface.

1. Policy Configuration and Layered Storage

The RuleConfig structure centrally manages country mode, unlock time, holding limits, and investor caps:

// Excerpt from aurum-rwa/contracts/src/RwaComplianceModuleCore.sol
    struct RuleConfig {
        uint8 countryMode; // 0: NONE (unrestricted), 1: ALLOWLIST, 2: BLOCKLIST
        uint16[] countries; // ISO 3166-1 numeric country codes
        uint64 transferUnlockAt; // Secondary-transfer unlock timestamp (enforce private-placement lockup)
        bool maxBalanceEnabled; // Enable per-identity holding limit
        uint256 maxBalance; // Maximum total holdings per identity
        bool maxInvestorsEnabled; // Enable statutory holder-count limit
        uint256 maxInvestors; // Maximum net holders, e.g. 99 or 2000
        uint256 issuanceCap; // Hard cap on total asset issuance
    }

    IRwaController public controller;
    uint256 public constant MAX_COUNTRIES = 250;
    uint256 public constant MAX_BATCH = 100;

    bool public bound;
    bool public ready;
    uint64 public policyVersion;
    RuleConfig private _policy;

    // Country-policy mapping
    mapping(uint16 => bool) public countryMember;
    // Two-level identity and wallet ledger
    mapping(address => uint16) public identityCountry;
    mapping(address => uint256) public identityBalance;
    mapping(address => uint256) public walletBalance;
    mapping(address => address) public walletIdentity;

    uint256 public investorCount; // Total net holders
    uint256 public lifetimeMinted;
    uint256 public trackedSupply;

2. Country Modes and Dual-Claim Verification

Before a transfer, the contract must confirm that recipient wallet to is properly bound to an identity, that the identity has compliant claims, and that its country is permitted:

// Excerpt from aurum-rwa/contracts/src/RwaComplianceModuleCore.sol
    function checkEligible(address w) public view {
        address id = _mapped(w);
        
        // 1. Check that the identity passed claim verification in IdentityRegistry
        if (!_registry().isVerified(w)) revert ClaimInvalid();
        
        uint16 country = identityCountry[id];
        
        // 2. Strict country-mode checks
        if (
            country == 0 ||
            (_policy.countryMode == 1 && !countryMember[country]) || // Allowlist: reject countries not listed
            (_policy.countryMode == 2 && countryMember[country])    // Blocklist: reject listed countries
        ) revert CountryRestricted();
    }

    function _mapped(address w) internal view returns (address id) {
        id = walletIdentity[w];
        if (
            id == address(0) || 
            controller.retiredWallet(w) || 
            address(_registry().identity(w)) != id || 
            _registry().investorCountry(w) != identityCountry[id]
        ) revert IdentityMismatch();
    }

In _requiredTopicsPresent, the contract requires the registry to contain two independent claims:

  • General KYC claim (Topic 1): proves that the investor completed basic identity due diligence and anti-money-laundering screening;
  • Asset-specific eligibility claim (Topic 3): an issuer-signed accredited-investor authorization for a specific block.chainid and address(_token()), preventing a credential for asset A from being misused to buy higher-threshold asset B.

3. Aggregating Multi-Wallet Holdings and Calculating Net Holders (_limits and _move)

The central design is to calculate holdings and holder-count changes at the identity level:

// Excerpt from aurum-rwa/contracts/src/RwaComplianceModuleCore.sol
    function _limits(address from, address to, uint256 q) internal view {
        address a = from == address(0) ? address(0) : walletIdentity[from];
        address b = walletIdentity[to];

        // Core optimization: allow immediately if sender and recipient belong to the same real investor identity
        if (a == b) return;

        // 1. Assert identity-level holding limit (prevent multi-wallet splitting bypasses)
        uint256 oldTo = identityBalance[b];
        if (_policy.maxBalanceEnabled && oldTo + q > _policy.maxBalance) {
            revert HoldingLimitExceeded();
        }

        // 2. Project the change in net holder count
        uint256 nextCount = investorCount;
        
        // Decrement net holders by 1 if this transaction fully empties the sender identity
        if (a != address(0) && q == identityBalance[a]) --nextCount;
        
        // Increment net holders by 1 if recipient previously held zero and now receives a positive amount
        if (oldTo == 0 && q > 0) ++nextCount;

        // 3. Assert the holder cap (also protect existing holders when limits are reduced)
        if (_policy.maxInvestorsEnabled && nextCount > _policy.maxInvestors && nextCount > investorCount) {
            revert InvestorLimitExceeded();
        }
    }

During the actual _move state transition, token transfers and global identity-ledger updates are fully atomic:

// Excerpt from aurum-rwa/contracts/src/RwaComplianceModuleCore.sol
    function _move(address from, address to, uint256 q) internal {
        if (from == to) return;
        address a = walletIdentity[from];
        address b = walletIdentity[to];

        // 1. Debit and credit actual wallet-level balances
        if (from != address(0)) walletBalance[from] -= q;
        if (to != address(0)) walletBalance[to] += q;

        // Same identity: identity-level holdings and holder count remain unchanged
        if (a == b) return;

        // 2. Maintain sender legal identity's total holdings and holder count
        if (from != address(0)) {
            identityBalance[a] -= q;
            if (identityBalance[a] == 0) --investorCount;
        }

        // 3. Maintain recipient legal identity's total holdings and holder count
        if (to != address(0)) {
            if (identityBalance[b] == 0) ++investorCount;
            identityBalance[b] += q;
        }
    }

4. Transfer Preconditions and Partial-Freeze Protection (_validate)

Beyond count and amount limits, _validate integrates several hard locks:

  • Liquidity lockup: prohibit secondary transfers while block.timestamp < _policy.transferUnlockAt;
  • Partial token freeze: compliance authorities may freeze some wallet units for judicial investigations or collateral requirements. Transfers must assert sufficient available balance (walletBalance[from] - frozenTokens >= q) and cannot move court-frozen units.
// Excerpt from aurum-rwa/contracts/src/RwaComplianceModuleCore.sol
    function _freezeCheck(address from, uint256 q) internal view {
        uint256 f = _token().getFrozenTokens(from);
        if (f != controller.accountedFrozen(from)) revert FreezeAccountingMismatch();
        if (f > walletBalance[from] || q > walletBalance[from] - f) {
            revert InsufficientAvailableBalance();
        }
    }

Foundry Tests: Compliance Boundaries and Negative Assertions

The aurum-rwa/contracts/test/Core.t.sol suite rigorously regression-tests compliance edge cases.

1. Same-Identity Transfers Must Not Inflate Holder Counts

Scenario: Alice owns two wallets, alice and alice2, and transfers 60 tokens from wallet 1 to wallet 2. The investor count must remain 1. Even with maxInvestors set to 1, self-transfers must proceed without false count-inflation alerts:

// Excerpt from aurum-rwa/contracts/test/Core.t.sol
    function testIdentityMultipleWalletsSelfAndNetInvestorCount() public {
        controller.registerWallet(_req(address(0)), alice2, address(aliceId), 840);
        _mint(alice, 100);
        _transfer(alice, alice2, 60);
        _transfer(alice2, alice2, 10);
        _same(address(aliceId), 100);
        require(module.investorCount() == 1, "one identity");

        // Force the maximum investor count down to 1
        _pause();
        RwaComplianceModule.RuleConfig memory p = module.policy();
        p.maxInvestors = 1;
        _policy(p);
        controller.unpause(_req(address(0)), REF);

        // A transfer to new investor Bob must revert because it exceeds the holder cap
        vm.expectRevert();
        vm.prank(alice);
        token.transfer(bob, 1);

        // Transfers between Alice's own two wallets remain unrestricted
        _transfer(alice2, alice, 60);
        
        // Alice transfers all tokens to Bob: Alice exits (-1), Bob enters (+1), so net count stays 1
        _transfer(alice, bob, 100);
        require(module.investorCount() == 1, "net count");
    }

2. Rejecting Multi-Wallet Attempts to Exceed Holding Limits

Scenario: policy limits one investor to 1,000 tokens. Alice attempts to hold 1,000 in one wallet and 1 in another. Whether through a direct mint or third-party transfer, the contract throws HoldingLimitExceeded:

// Excerpt from aurum-rwa/contracts/test/Core.t.sol
    function testMultiWalletCannotBypassMaxHolding() public {
        controller.registerWallet(_req(address(0)), alice2, address(aliceId), 840);
        _mint(alice, 1000); // Reach the identity-level limit
        _transfer(alice, alice2, 500);

        // Attempt to mint 1 extra unit to alice2; the contract blocks it at identity level
        AgentController.Request memory r = _req(alice2);
        vm.expectRevert(HoldingLimitExceeded.selector);
        controller.mint(r, r.operationId, alice2, 1, REF);

        // Attempt a 1-unit transfer from third-party Bob to alice2; enforce a revert
        _mint(bob, 1);
        vm.expectRevert();
        vm.prank(bob);
        token.transfer(alice2, 1);
    }

3. Smooth Country Allowlist/Blocklist Switching

The test verifies allowlist mode (countryMode = 1, allowing only the US, 840): minting or transferring to UK investor Bob, 826, immediately raises CountryRestricted. After switching to blocklist mode (countryMode = 2, blocking the US, 840), the compliance engine updates its blocking rules seamlessly:

// Excerpt from aurum-rwa/contracts/test/Core.t.sol
    function testCountryAllowlistBlocklistIdentityConsistency() public {
        _pause();
        RwaComplianceModule.RuleConfig memory p = module.policy();
        p.countryMode = 1; // Allow only the US, 840
        p.countries = new uint16[](1);
        p.countries[0] = 840;
        _policy(p);
        controller.unpause(_req(address(0)), REF);

        _mint(alice, 100);
        
        // Minting to UK investor Bob is blocked directly by country rules
        AgentController.Request memory r = _req(bob);
        vm.expectRevert(CountryRestricted.selector);
        controller.mint(r, r.operationId, bob, 1, REF);
    }

Four Rules for Production RWA Transfer Compliance

  1. Never use wallet addresses as the unit for holdings and investor counts: introduce decentralized identities (Identity / ONCHAINID) at the contract level and aggregate multiple wallets under a unique legal identity to eliminate wallet-splitting Sybil bypasses;
  2. Calculate net holders at state boundaries: increment only when an identity’s total balance changes from zero to nonzero; decrement only when it reaches zero. Transfers between wallets under one identity are internal transfers and must not inflate the count;
  3. Distinguish fully frozen assets from partially available tokens: precisely lock pledged or disputed assets through partial freezes, and strictly assert walletBalance - frozenTokens >= transferAmount during transfers;
  4. Policy changes must support gradual transitions for existing holdings: when regulations reduce investor or holding caps, block additional violations without preventing existing compliant holders from closing positions and exiting normally.

Enterprise RWA Tokenization and Compliance Architecture Consulting

Fone builds full-stack RWA tokenization architectures for institutional real-estate trusts, private-credit funds, commodity warehouse receipts, and compliant bonds under SEC / MAS / MiCA requirements. Our Aurum RWA solution has implemented the complete production lifecycle from investor KYC and asynchronous NAV subscriptions to mandatory on-chain transfer compliance and judicial asset recovery: