Compliance10 min read
MB
Editorial Team
·November 8, 2026

What Happens When an ERC-3643 Investor Changes Country?

An ERC-3643 investor country is a uint16 ISO 3166-1 numeric code stored per wallet in the Identity Registry Storage, written by an agent at registration and changed only through updateCountry. In the T-REX reference code it is not read from ONCHAINID claims, so when an investor moves, nothing changes on-chain until an agent updates every wallet.

TL;DR — Key Takeaways

  • ✓The field: In T-REX the investor country is a uint16 ISO 3166-1 numeric code stored per wallet address, set by an agent at registration and changed only by an agent calling updateCountry. It is not read from ONCHAINID claims.
  • ✓The check: CountryRestrictModule and CountryAllowModule read only the receiver's stored country. In code reading, a holder recorded in a restricted country can still sell but cannot receive.
  • ✓The bypass: forcedTransfer checks only isVerified and skips every compliance module, and wallet recovery copies the old wallet's country to the new one. Agent actions are outside the country rule.
  • ✓The procedure: A move of residence changes nothing on-chain until an agent updates every registered wallet, one call each. Freezing or redemption are separate decisions with their own transactions.
  • ✓The source: Read from the archived TokenySolutions/T-REX main branch at commit f1390127. The successor ERC-3643/ERC-3643 repository ships the same registry code but no modular country modules.

Ready to get started?

Join others who are already using our platform.

What Happens When an ERC-3643 Investor Changes Country?

Where does an ERC-3643 token get the investor's country?

From a uint16 field in the Identity Registry Storage, keyed by wallet address and written by an agent. The T-REX reference contracts do not derive it from any ONCHAINID claim, so a KYC update that records a new residence leaves the token's country unchanged.

Some public guides describe the country as something the token reads from a claim on the investor's ONCHAINID. The reference code does not do that. IRSStorage defines one struct per wallet with two fields: identityContract and investorCountry. registerIdentity(wallet, identity, country) fills both, and investorCountry(wallet) returns the stored number. isVerified walks the required claim topics and trusted issuers and never touches the country. The country modules call identityRegistry().investorCountry(_to) and nothing else. The only link between a KYC claim and the stored country is whatever the operator does by hand or with off-chain tooling.

The specification describes the same design. The Identity Registry links a wallet, an identity contract and a country code, and compliance uses “the country code corresponding to each investor in the Identity Registry”. A custom compliance module could read a residence claim instead, but that would be a new contract, not T-REX behaviour. How these per-token rules sit next to network-level controls is covered in the guide to smart contract compliance versus Layer-0 governance for RWA.

“It establishes the link between a wallet address, an Identity smart contract, and a country code corresponding to the investor's country of residence. This country code is set in accordance with the ISO-3166 standard.”

ERC-3643 specification, Identity Registry section

How does updateCountry work, and who can call it?

updateCountry(address, uint16) is onlyAgent on the Identity Registry and writes one wallet's entry in storage. There is no batch version, so an investor with three registered wallets needs three calls, and each must target a wallet that is already registered.

FunctionCallerEffect on countryEvent
registerIdentity(wallet, id, country)Registry agentSets the first value; reverts if the wallet is already storedIdentityRegistered, IdentityStored
updateCountry(wallet, country)Registry agentOverwrites one wallet; reverts “address not stored yet” for unknown walletsCountryUpdated, CountryModified
updateIdentity(wallet, id)Registry agentNone; the country stays as storedIdentityUpdated
deleteIdentity(wallet)Registry agentRemoves the entry; re-registering sets a fresh countryIdentityRemoved
recoveryAddress(lost, new, id) on the tokenToken agentRegisters the new wallet with the lost wallet's stored countryRecoverySuccess

Two details widen the scope of one update. First, the value is held per wallet, not per ONCHAINID, so the unit of work is the wallet list for that identity, not the investor. Second, one Identity Registry Storage can be bound to up to 300 identity registries (“cannot bind more than 300 IR to 1 IRS”). Every bound registry becomes an agent of the storage, so an updateCountry call made through one token's registry changes the country that every token sharing that storage reads. For a multi-token issuer that is a feature: one move, one update. It also means an agent of any of those registries can change the country seen by all of them.

“function updateCountry(address _userAddress, uint16 _country) external override onlyAgent { _tokenIdentityStorage.modifyStoredInvestorCountry(_userAddress, _country); emit CountryUpdated(_userAddress, _country); }”

IdentityRegistry.sol, TokenySolutions/T-REX main @ f1390127

The interface comment on CountryUpdated defines the value as “the numeric code (ISO 3166-1) of the new country”. Nothing in the contract checks that the number is a real ISO code, so the operator's mapping table is part of the control.

What do CountryRestrictModule and CountryAllowModule check?

Both modules read only the receiver's stored country and ignore the sender and the amount. CountryRestrictModule blocks receivers in listed countries; CountryAllowModule blocks receivers outside its list. Both are plug-and-play and can be added to a live token.

In both files, moduleCheck comments out the _from and _value parameters and calls _getCountry(_compliance, _to). The post-transfer hooks (moduleTransferAction, moduleMintAction, moduleBurnAction) are empty, so the modules keep no state about holders. That is why isPlugAndPlay() and canComplianceBind() both return true, and ModularCompliance.addModule binds them to a token that already has holders without any preset. The contrast is the MaxBalanceModule, which keeps a per-identity ledger and refuses to bind to a live token until that ledger is preset.

PropertyCountryRestrictModuleCountryAllowModule
Passes whenReceiver country is not on the restricted listReceiver country is on the allowed list
Default after bindingEmpty list: every country passesEmpty list: every receiver fails (code reading)
Batch size per callFewer than 195 entries (require message says “maximum 195”)No limit in code
Duplicate add or removeReverts with a string errorSingle add or remove reverts with a custom error; batch calls do not
Who edits the listCompliance owner, through callModuleFunction; list functions are onlyComplianceCall
Scope of the listPer compliance contract, so one module deployment can serve several tokens with different lists

Note the split of authority. The registry agent decides which country a wallet is in. The compliance owner decides which countries are blocked. A residence change that should block an investor needs the right action from the first key; a new sanctions or offering restriction needs the second. Neither key can complete the rule alone.

“uint16 receiverCountry = _getCountry(_compliance, _to); if (isCountryRestricted(_compliance, receiverCountry)) { return false; } return true;”

CountryRestrictModule.sol, moduleCheck, TokenySolutions/T-REX main @ f1390127

What can an investor do after their country is updated?

In code reading, a holder whose wallet now records a restricted country can still send tokens to an eligible receiver, but cannot receive by transfer or mint. Agent forced transfers, burns and recoveries ignore the country entirely.

The table follows each token operation through Token.sol and ModularCompliance.canTransfer, which runs moduleCheck on every bound module. It assumes the investor's wallet is still verified and not frozen. We have read the code; we have not executed these paths.

Operation on a wallet recorded in a restricted countryCountry module consulted?Outcome (code reading)
Holder sends with transfer / transferFromYes, on the receiverSucceeds if the receiver is eligible
Someone sends to the holderYes, on the holder as receiverReverts “Transfer not possible”
Agent mint to the holderYes, canTransfer(address(0), holder)Reverts “Compliance not followed”
Agent burn from the holderNoSucceeds
Agent forcedTransfer to the holderNo; only isVerified(_to)Succeeds
Agent recoveryAddress for the holderNo; uses forcedTransferSucceeds; new wallet inherits the restricted country

Two gaps follow. If an agent updates only one of an investor's wallets, the others keep the old country, and the investor can move tokens from the updated wallet into a stale one, which still passes the receiver check. And because forcedTransfer skips canTransfer, the module does not bind the agent. That is by design, since forced transfers exist for court orders and corrections, but it means an agent can place tokens in a restricted wallet with no on-chain objection. This is an operational and governance risk, not a known exploit: we know of no incident in which it was used against a permissioned RWA token.

“if (_tokenIdentityRegistry.isVerified(_to)) { _transfer(_from, _to, _amount); _tokenCompliance.transferred(_from, _to, _amount); return true; }”

Token.sol, forcedTransfer, TokenySolutions/T-REX main @ f1390127

What happens when a whole jurisdiction is newly restricted?

Every holder already recorded in that country keeps their balance and the ability to send it out, and loses the ability to receive. That includes distributions paid in the same token by transfer or mint, which revert for those holders.

Adding a country to CountryRestrictModule is one owner call through callModuleFunction. It does not freeze, move or flag any existing balance, and the module emits AddedRestrictedCountry with no list of affected wallets. Finding the affected holders means scanning investorCountry for every holder wallet, or replaying CountryModified and IdentityStored events, off-chain.

Illustrative example (invented numbers, not a real issuer). A fund token has 400 holder wallets. Twelve are recorded with country code X. The compliance owner restricts X after a regulatory change. Those twelve wallets can still sell to eligible buyers. The next quarterly distribution, paid by minting units, reverts for each of the twelve, and a batch mint that includes them reverts as a whole if one entry fails. The issuer has to pay those holders another way, or hold their entitlement off-chain until they exit.

Whether restricted holders should be able to sell at all is a legal question the module does not answer. If the rule is “no one in country X may move these tokens”, the issuer needs a separate freeze with setAddressFrozen or freezePartialTokens. For sanctions, a freeze also triggers reporting duties covered in what an issuer must report after freezing sanctioned tokens.

What should a residence-change runbook include?

A trigger, a full wallet list for the identity, one updateCountry call per wallet, a separate freeze or redemption decision, and evidence linking the KYC record to each transaction. The token enforces none of these steps on its own.

StepWhat to doEvidence to keep
TriggerInvestor notice, periodic KYC refresh, sanctions screening hit, or a regulatory change to the country listSource document and date received
Wallet listList every wallet whose identity() resolves to the investor's ONCHAINID, across every registry bound to the same storageWallet list and the block it was read at
UpdateCall updateCountry for each wallet with the ISO 3166-1 numeric code from a fixed mapping tableTransaction hashes, signer, CountryUpdated events
Read-backConfirm investorCountry returns the new code for every walletRead-back output
Freeze or redeemDecide whether to freeze, force a redemption, or allow sell-only status; each is a separate agent actionLegal basis and approver
RegisterUpdate the off-chain securityholder record and offering-exemption files to matchRegister extract after the change

Wallet recovery is part of this runbook too. Because recoveryAddress copies the lost wallet's stored country, a stale code carries over to the new wallet unless someone checks it, which is one more record for the reconciliation described in how an RWA issuer should recover a lost wallet.

Who does this apply to, and what was not checked?

It applies to issuers, transfer agents and operators running T-REX modular compliance with a country module. The registry behaviour is the same in the successor ERC-3643/ERC-3643 repository, but that repository ships no modular country modules.

All behaviour above is read from the TokenySolutions/T-REX repository at commit f1390127 on its main branch. The repository is archived and points to ERC-3643/ERC-3643. In that successor repository (main at commit 2f0704de), IdentityRegistry.updateCountry, modifyStoredInvestorCountry and Token.forcedTransfer match the code quoted here, but the modular modules folder holds only AbstractModule, AbstractModuleUpgradeable, IModule, ModuleProxy and TestModule. Country rules there sit in legacy compliance features (CountryRestrictions, CountryWhitelisting), which we did not review. Both T-REX module files carry a header that adds a Creative Commons Attribution-NonCommercial 4.0 licence on top of GPL-3.0, which matters for teams copying them.

We did not check which module versions deployed tokens use, and we did not check whether any hosted platform updates the stored country automatically from KYC data. If yours does, the runbook still needs the read-back and evidence steps, because the chain records only the agent call, not the reason for it.

Sources: IdentityRegistry.sol, IdentityRegistryStorage.sol, IIdentityRegistry.sol, CountryRestrictModule.sol, CountryAllowModule.sol, ModularCompliance.sol and Token.sol, all TokenySolutions/T-REX main @ f1390127 (repository archived, read 2026-11-08); ERC-3643/ERC-3643 contracts @ 2f0704de; ERC-3643 specification.

Frequently Asked Questions

Does an ERC-3643 token read the investor's country from their ONCHAINID?

Not in the T-REX reference code. The country is a uint16 stored per wallet address in the Identity Registry Storage, next to the link to the ONCHAINID contract. An agent sets it in registerIdentity and changes it with updateCountry. isVerified checks claims from trusted issuers but never reads the country, and the country modules read only investorCountry(wallet). A KYC claim that records a new residence changes nothing on its own.

Who can change an investor's country on an ERC-3643 token?

Only an agent of the Identity Registry, through updateCountry(address, uint16). The registry then writes to the storage contract, which accepts the call because a bound registry is an agent of the storage. The list of restricted or allowed countries is a different setting: it lives in the compliance module and is changed by the compliance owner through callModuleFunction. Two different keys control the two halves of a country rule.

Can an investor in a newly restricted country still sell their tokens?

In code reading, yes. CountryRestrictModule and CountryAllowModule check only the receiver's stored country and ignore the sender. A holder whose wallet is recorded in a restricted country can transfer to an eligible buyer, but cannot receive tokens by transfer or mint. Existing balances are not frozen. We have not executed this; it follows from the moduleCheck functions at T-REX commit f1390127.

Does forcedTransfer respect country restrictions?

No. In Token.sol, forcedTransfer requires only that the receiver passes isVerified, then moves the tokens and calls compliance.transferred. It never calls canTransfer, so no module's moduleCheck runs. An agent can move tokens into a wallet recorded in a restricted country. Wallet recovery uses forcedTransfer too and copies the lost wallet's country to the new wallet. Agent actions need their own approval control.

How many wallets must be updated when one investor moves?

Every wallet the investor has registered. The storage key is the wallet address, so an investor with three wallets linked to one ONCHAINID has three country entries. The Identity Registry has no batch updateCountry function, so each wallet takes its own call. If the storage is shared by several tokens, one update changes the country for all of them.

Ready to get started?

Join others who are already using our platform.