SKIP TO CONTENT
TOKENIZATION6 minStandards That Ship / Ep. 8 · Stage 8-2

ERC-3643 Wallet Approval: How the Whitelist Works

An agent adds Bob’s wallet to a token’s whitelist, then removes it. What happens to the 50 units he already holds?

XIN
Pixel-art night scene of a small registry office on a cyan grid: a gatekeeper with a lantern stamps glowing lockboxes queued at a gate, and light threads run from the gate to one large open ledger book on a desk inside.

IN 30 SECONDS

An ERC-3643 identity registry is a wallet whitelist with credentials attached: an agent key adds a wallet, and every transfer checks the receiver. Removing a wallet stops new transfers to it, but its tokens stay.

KEY TAKEAWAYS · 3

  • ERC-3643 can implement the whitelist pattern: an agent key adds a wallet, and every transfer checks the receiver.
  • Removing a wallet blocks new transfers to it, but its tokens stay where they are.
  • The owner key can swap the identity registry. Who holds which key is for the issuer, its transfer agent and counsel.
On this page

How an ERC-3643 identity registry whitelists a wallet, step by step

IN SHORT Registry owners set the rules, an agent key adds the wallet, and every transfer checks the receiver against those rules again.

WORDS TO KNOW

Identity registry
The ERC-3643 contract that lists registered wallets and links each to an identity record.
Claim
A signed statement on an investor’s ONCHAINID, such as “passed identity checks”, from a party the token trusts.
Agent key
An address the owner appoints for daily actions, such as adding wallets or freezing. The owner key sets the rules.

IN PLAIN WORDS

The check lives in the token. Its Identity registry The ERC-3643 contract that lists registered wallets and links each to an identity record. See the glossary links each registered wallet to the investor’s identity record (ONCHAINID) and a country code. An Agent key An address the owner appoints for daily actions, such as adding wallets or freezing. The owner key sets the rules. See the glossary writes each entry.

STEP BY STEP

Sequence diagram: 6 participants: Registry owner, ID checker, Registry agent, Bob’s ID record, Identity registry, TokenSequence diagram: 6 participants: Registry owner, ID checker, Registry agent, Bob’s ID record, Identity registry, Token. Step 1: Registry owner to Identity registry, Set the rules. Step 2: ID checker to Bob’s ID record, Sign: ID checked. Step 3: Registry agent to Identity registry, Add Bob’s wallet. Step 4: Token to Identity registry, Is Bob verified?. Step 5: Identity registry to Bob’s ID record, Read Bob’s claims. Step 6: Identity registry to Token, Yes. Step 7: Token to Identity registry, Is Carol verified?.REGISTRY OWNER > IDENTITYREGISTRYSet the rulesID CHECKER > BOB’S ID RECORDSign: ID checkedREGISTRY AGENT > IDENTITYREGISTRYAdd Bob’s walletTOKEN > IDENTITY REGISTRYIs Bob verified?IDENTITY REGISTRY > BOB’S IDRECORDRead Bob’s claimsIDENTITY REGISTRY > TOKENYesTOKEN > IDENTITY REGISTRYIs Carol verified?

Step 1. Set the rules. The registry owners pick the required claims and trusted issuers. A deployment may give both to the token owner.

Pick a step to see it move
  1. Set the rules The registry owners pick the required claims and trusted issuers. A deployment may give both to the token owner.
  2. Sign a claim A trusted issuer signs a claim, such as a passed ID check, onto Bob’s ONCHAINID.
  3. Add the wallet An agent key adds Bob’s wallet, his ONCHAINID and a country code. That’s the whitelisting write.
  4. Ask On every transfer, mint (new tokens) and forced transfer (an agent move without the holder’s signature), the token asks about the receiver.
  5. Answer Yes only if every required topic has a valid claim from a trusted issuer.
  6. Refused Carol’s wallet was never added: the answer is no, and nothing moves.
Per the ERC-3643 spec and the T-REX reference code (v4.1.6). Bob is added and passes; Carol was never added.

The spec (status: Final) calls it “a dynamic whitelist of identities”. The right to hold the token isn’t a switch flipped once. It’s worked out again at each transfer, from the receiver’s Claim A signed statement on an investor’s ONCHAINID, such as “passed identity checks”, from a party the token trusts. See the glossary.

ADAM says: Picture a front desk: a clerk adds your badge, a reader checks it at each door. Where it breaks: this reader also holds the balances, and the proposal never says if the clerk’s job is a transfer agent’s.

WATCH OUT

Two catches in T-REX

With no claim topics set, any registered wallet passes. And an ordinary transfer checks the receiver’s identity only; the sender is checked for freezes and free balance.

Coming up next: So what happens to a wallet that’s removed while it still holds tokens?

A worked example: one wallet added, then removed

IN SHORT Removing a wallet from the whitelist stops new transfers to it, but its tokens stay where they are.

A WORKED EXAMPLE

Illustrative numbers

PASSBob joins the whitelist and receives 50 units

INPUT

Receiver
Bob, added by an agent
Transfer
Alice sends 50 units

WHAT HAPPENS

  1. Bob’s claims are valid, and the pause, freeze, balance and compliance checks pass.
  2. The transfer settles, and the off-chain register shows Bob with 50 units.

OUTPUT

Bob’s balance
50
Reconciliation
no difference

FLAGGEDLater, an agent deletes Bob’s identity

INPUT

Action
remove Bob’s wallet from the registry

WHAT HAPPENS

  1. The identity check on Bob’s wallet now says no, so new transfers to him fail.
  2. His 50 units don’t move: deleting an identity doesn’t burn (destroy) or move tokens.

OUTPUT

Bob’s balance
50 (still there)
Reconciliation
balance with no identity

ITEM GET

Removed is not emptied

Nothing on-chain broke, but the whitelist and the balances now disagree. Someone has to notice.

Coming up next: So who holds the keys that add and remove wallets?

Which role key does what

IN SHORT The owner key sets the rules and can swap the registry. Agent keys act on wallets, and each contract keeps its own list of agents.

ROLE KEYS IN T-REX
ERC-3643 role surface
Set claims and issuersowner key

Defines the requirements

Add or remove a walletagent key (registry)

Changes the whitelist

Forced transferagent key (token)

To a verified wallet, skipping the pre-transfer check

Recover a lost walletagent key (token)

Moves a holder to a new wallet

Swap the registry or rulesowner key

Replaces them outright

Selected actions and their key (T-REX main, v4.1.6; ownership per ERC-173). In T-REX, the agent actions share one agent role per contract. The note says what the action does, not who should legally hold the key.

WATCH OUT

Recovery has a gap

The code checks that the new wallet is a management key on the ONCHAINID the agent passes in. It doesn’t check that this ONCHAINID is the lost wallet’s, so that check belongs in the agent’s procedure.

Under the proposal, the transfer agent would keep exclusive control of the official list. Now say it holds the agent keys and the issuer holds the owner key. Then the issuer can swap the identity registry.

Is that still exclusive control? I won’t answer that as law.

I’d write the key map down. I’d put the owner key behind a multisig (a wallet needing several signatures) with named signers. And I’d ask counsel before deploying.

FAQ

Owners set the rules. An agent key adds each wallet, and every transfer checks the receiver: that can implement the whitelist pattern. Which legal entity should hold the agent key is for the issuer, its transfer agent and counsel.

STAGE CLEAR

What you now know

  • Who sets the rules, who adds a wallet, and why each transfer checks the receiver again.
  • Why a removed wallet still holds its tokens, and why the owner key matters for exclusive control.

Check yourself

Tap or click a question to see the answer.

Alice’s identity was deleted from the registry, but she still holds tokens. She sends some to Bob, who is verified. Does the deleted identity stop the transfer?

Not by itself. In T-REX, an ordinary transfer checks the receiver’s identity only. Alice is checked for freezes and free balance instead.

Next stage:Which records could form the official owner list of a tokenized security?6 min
Adam Boudjemaa
Adam Boudjemaa

Former CTO of Integra. Named author (1 of 5) of ERC-3643, first author of ERC-6960, co-author of ERC-7410, and co-author of ERC-8203, which is still a draft. Building production AI and regulated Web3 systems.

Have a project to ship or a role to fill?

Discuss your project or role
LinkedInTwitterGitHub
Follow the engineering notes

Get new articles on production AI and smart contracts by email.