Wallet linking and the global identity registry

An ONCHAINID holds tokens itself, and its owner can also hold tokens in other addresses: an existing wallet, a second wallet, a wallet on another chain. For the register to treat those addresses as the same holder, each one is linked to the identity. An address that cannot link itself, such as a custody account that cannot sign, is registered for each asset by the Issuer's agent instead. The global identity registry is where those links are kept: one record per wallet, valid for every asset, under the control of the identity's owner.

From registration per token to one link

In the earlier model, a wallet became usable for a token when an agent of that token's Issuer registered it. The participant was a passive subject: to use a new wallet, it asked an authorized party to register it, for each token, one at a time.

The global identity registry inverts this.

	Registration per token	Global link
Who binds the wallet	A Registry Agent of each Issuer	The Identity Owner
How often	Once per token	Once
Proof	The agent's word	A proof from the wallet and a proof from the identity
Scope	One token	Every token, on every chain
Address format	An address on one chain	An ERC-7930 interoperable address

The registry is implemented by the IdentityFactory. The same contract that creates identities keeps the record of which wallets belong to which identity.

Interoperable addresses

The registry identifies a wallet by its ERC-7930 interoperable address: the type of chain, the chain, and the address in that chain's own format. A Solana account or an XRPL address is represented as naturally as an Ethereum one.

Two consequences:

• One identity spans every chain. The identity is the durable thing. Wallets, on whatever chain, are linked facets of it.

• A wallet is a wallet on a chain. The same address on two EVM chains is two entries. Each is linked separately, with the proof that fits its chain.

The registry stores the canonical encoding of each address, so one wallet has exactly one entry however its address was supplied.

Two proofs

A link requires two proofs, from two sides.

• Control of the wallet. The wallet itself agrees to be linked to this identity.

• Ownership of the identity. The identity itself asks for the link, which takes one of its MANAGEMENT keys.

Neither side can create a link alone. How the wallet gives its proof depends on where the wallet lives.

A wallet on the reference chain

The wallet signs a typed message, and the identity presents it.

• The message is ERC-712 typed data, LinkAccount(bytes account, address identity, uint256 nonce, uint256 expiry), so the wallet shows its owner what is being signed.

• The signature is accepted from an externally owned account, from a smart-contract wallet through ERC-1271, and from an ERC-7913 signer such as a passkey. For an ERC-7913 signer, the verifier must be on the factory's list of trusted verifiers.

• The nonce is per wallet and is consumed by the link. The expiry is mandatory: the binding is permanent, so the signature that creates it must be fresh.

• The call comes from the identity, so only a MANAGEMENT key of that identity can make it.

A wallet on another chain

A signature checked on the reference chain proves nothing about an address on another chain. A wallet on a non-EVM chain, or on a different EVM chain, proves control where it lives and sends the proof across.

• The wallet originates the message on its own chain. ERC-7786 authenticates the sender of a cross-chain message. The factory requires that sender to be the wallet named in the proposal. That is the proof of control.

• The gateway is trusted per origin chain. The factory accepts a proposal only from a gateway that Network governance has listed for the chain the message comes from.

• The identity settles the proposal. Nothing is linked when the message arrives. The proposal waits until the named identity accepts it, which links the wallet, or declines it, which deletes the proposal. An expired proposal can no longer be accepted.

• A local wallet cannot use this path. A wallet on the reference chain has to sign.

The first account

An identity is created with a first linked account: the caller that deployed it, or the account it was deployed for. See Identity types and factory gating. Every later link goes through one of the two paths above.

The rules of a binding

Rule	Meaning
A binding is sticky.	A wallet belongs to one identity. Once linked, it can never be linked to another.
A revocation is terminal.	The identity revokes a wallet with revokeAccount. The record stays on-chain with the status Revoked, and the wallet can never be linked again, to this identity or to any other.
An identity is not a wallet.	An ONCHAINID cannot be linked as a wallet of another identity. It already resolves to itself.
Links and keys are separate.	Linking a wallet gives it no key on the identity, and revoking a wallet removes no key. Revoking the last wallet of an identity does not disable the identity. Its keys still work and it can link a new wallet.
Some identities never link.	A single-binding identity, such as the identity of a token, keeps the one account set at its creation. It cannot link or revoke.

A wallet is in one of three states: never seen, Active or Revoked.

Why a binding cannot be undone

A link is a statement the register relies on to attribute ownership. Two properties follow from that.

• A revoked wallet keeps its owner. A wallet that still holds tokens must stay attributed to the identity that owned them, so that the identity can still move the position, and an agent can recover, burn or transfer it for the right holder. The registry keeps the record for that reason.

• A wallet cannot change identity. If a wallet could move from one identity to another, a position could change holder without a transfer, and rules that count holders or cap positions could be evaded.

When a wallet is compromised

The owner revokes it. From that moment:

• The wallet is no longer verified. It cannot receive the asset. It can still send: revoking a wallet does not stop its own key from transferring its free tokens.

• Its holdings remain attributed to the identity. The identity's position does not change.

• The identity itself is unaffected: its keys, its claims, its other wallets and its eligibility stay as they were.

• The position that sits in the revoked wallet is moved to an address the owner controls, in one of two ways.

	The owner moves it	An agent recovers it
Call	identityTransfer, ordered by the identity	recoveryAddress, by an agent of each asset
Needs	A key of the identity. The wallet's own key is not used.	A request to the Issuer, verified under its process
Free tokens	Moved	Moved
Frozen tokens	Stay in the wallet. A transfer cannot move frozen tokens.	Moved, and frozen again at the new address

For free tokens the result is the same. When part of the balance is frozen, only the agent's recovery moves it.

Eligibility is a fact about the identity, not about any one wallet. Revoking a wallet does not revoke the investor.

Reading the registry

Function	Returns
getIdentity(account)	The identity an active wallet is linked to, or zero. An ONCHAINID resolves to itself.
getIdentityWithType(account)	The same, with the identity's type.
getIdentityIncludingRevoked(account)	The identity and the status of a wallet binding, including a revoked one. For an ONCHAINID's own address it returns the identity itself, with the status Active.
getAccountStatus(account)	The status of a wallet binding. An ONCHAINID's own address is always Active: it cannot be revoked.
getAccounts(identity, start, end)	The active wallets of an identity, by pages.
getAccountsCount(identity)	The number of active wallets.
nonceForAccount(account)	The nonce a wallet must sign to be linked.
getPendingCrossChainLink(account)	The pending proposal for a wallet, if there is one.

How a token uses the registry

A token resolves a holding address to an identity in this order:

1. A local registration, if the asset has one. A Registry Agent of the asset can still register an address for that asset with registerIdentity. A local registration takes precedence over the global link for that asset, and an event signals when the two differ.

2. The global link otherwise. An address with no local registration resolves through the IdentityFactory.

For a wallet on a satellite chain, the token reads the global registry directly, by interoperable address. A satellite wallet is eligible for an asset when it is linked to an identity that satisfies the asset's requirements.

The work a participant does once, creating its identity and linking its wallets, carries across every asset it is eligible for. No Issuer has to register anything.