Verification happens off the ledger, and what reaches the identity is the result, which the asset reads at the moment of transfer.
Evidence stays with the verifier. The ledger records only the result: a topic, the issuer that signed it, and an expiry date when one is set.
One identity serves every asset of the organisation on a network, and each asset applies its own rule to the same record.
The identity check reads claims at transfer time, so untrusting an issuer or revoking a verification takes effect on the next check, with no cleanup transaction.
Why on-chain identity exists
A regulated token must know who holds it, and a wallet address says nothing about the person or company behind it. One investor can also hold several wallets. An On-Chain Identity is a contract on the ledger that stands for one subject: a person, an organisation, or a contract such as a token. Every wallet the subject uses points to that one contract, so the token checks the identity the address is linked to, not the address alone.
The identity holds verification results. When an issuer you appoint has checked a subject, it signs the result onto the identity, and every asset that accepts that issuer reads the same result. A wallet already cleared for one instrument does not repeat the same check for the next one, as long as the next asset's rule accepts the same topics and issuers.
A typical tokenisation programme screens investors in one system and records ownership in another, and the two can drift apart. Asset Lifecycle names that gap as a reconciliation risk. An On-Chain Identity narrows it for eligibility: the issuer's result sits on the ledger the asset transfers on, and the asset reads it inside the transfer. Until the issuer records a change, the ledger keeps the old result.
The platform does not decide who counts as an accredited investor or whether a screening result is acceptable. Your compliance function and the issuers you appoint decide that. The platform puts their result where the asset reads it at the moment of transfer.
What a claim is
A claim is one signed statement on an identity, such as “this subject passed know-your-customer checks”. The Console calls a claim a verification, and the API calls it a claim. Each claim carries three fields:
- A topic, the named kind of statement, such as know-your-customer, anti-money-laundering or accredited investor. The organisation keeps a catalogue of topics, which the platform seeds when it deploys the system. Verification topics explains how to add more.
- An issuer, the identity that signed the claim. A claim counts only when the registry the asset consults trusts that issuer for that topic.
- A value. For the investor eligibility topics, the value is a fixed pass value with an optional expiry date. These topics are know-your-customer, anti-money-laundering, know-your-transaction, know-your-business, qualified institutional investor, professional investor, accredited investor, accredited investor verified, and Regulation S. Topics that describe an asset, such as base price or collateral, carry structured fields that pricing and minting read.
An identity holds at most one claim per issuer and topic. An issuer that signs the same topic again replaces its earlier claim, so a renewal is one write. Two different issuers can each hold a claim for the same topic on the same identity.
The platform refuses to issue a claim when the issuing identity is not trusted for that topic. A transfer checks trust again, so a claim from an issuer outside its mandate never counts. When a person issues an investor eligibility claim, the platform also refuses it until the subject's know-your-customer profile is approved, whether the claim lands on an EVM identity or on a Canton party. Approve the profile first, as Verify a participant describes. A compliance provider's verdict does not wait for that profile. The profile stays off the ledger, so no contract checks it. The identity contract checks the issuer's signature when it stores the claim, and the asset checks the trusted issuers registry at each transfer. In both cases the platform issues a claim only to an identity that the organisation's identity registry holds.
A revoke through the issuer identity leaves the claim on the identity with its revoked state visible. A revoke made without the issuer identity removes the claim. The next transfer to that wallet fails when the asset requires that topic and no other trusted issuer's claim covers it. A connected compliance provider can issue and revoke claims for you: an approved verdict issues the matching claim, a rejected verdict revokes it, and a monitoring alert revokes only when its severity reaches the threshold you set for that topic on the provider.
An expiry date alone does not change the identity registry's result. An asset that must refuse expired claims runs the Claim expiry compliance module, which rejects a mint or transfer to a recipient whose claim on a required topic has expired.
The identity registry
The identity registry is the contract that links each wallet to an identity, together with the country that compliance rules read. Each organisation has its own identity registry on each network it uses, as part of its system, the set of platform contracts the organisation runs on that network. A token checks this registry before a wallet may hold or receive it.
A wallet's registration is in one of three states. The Identity tab of a participant, the platform's record of one person or organisation, shows them as Approved, Pending approval, and Not registered, and the detail page of a user shows Registered and Pending registration:
- Approved means the registry holds an active entry, and tokens can see the wallet.
- Pending approval means a request to register the wallet is waiting, and an Identity manager has not accepted it. The request comes from the wallet's holder, from creating the identity, or from installing the identity on another network. An Identity manager is the system role that registers, changes and recovers identities.
- Not registered means the registry holds no entry for the wallet.
A participant with no identity on the network shows “Requires an identity” on that tab.
Registering a wallet activates every wallet of the same owner that is not active yet in one transaction, including a pending wallet and the smart wallet paired with the signing key. Removing a registration takes the wallet out of the registry, and the identity contract stays on the ledger with its claims. Only an Identity manager removes an approved registration. A wallet's holder can withdraw only their own pending request, so a holder cannot drop out of the registry to get around a lock-up.
The registry also carries a lost-wallet marker. A wallet marked lost cannot receive tokens again, and a recovery never registers a lost wallet to the new identity.
The identity factory, the contract that creates identities, links each wallet or contract to one identity and refuses a second one for the same wallet or contract. A participant holds one identity per network. A recovery replaces that identity with a new one and links the two.
A participant also holds one registry entry per identity registry, whichever way its identity is created: through the identity endpoints, as a new participant or user, through an invitation, through the install on another network, or through a multisig wallet. Two creates for the same participant never run side by side in one registry. While one runs, or waits for funding or an approval, a second is refused with a conflict, and the first keeps its place until it ends. A second wallet joins the identity only by being registered on the identity that already exists. A recovery is the exception: it replaces the identity, so it takes no such place.
On a second network, the participant installs its identity there, and the install files a pending registration that an Identity manager accepts. On-chain identity in the Console shows the steps.
Trusted issuers
The trusted issuers registry records which issuers count for which topics. An issuer is itself an identity on the ledger, so the registry names that identity rather than a signing key. The keys the issuer signs with live on its identity, and revocation lives with the issuer too, keyed to the signature. Trusted issuers shows how a verification policy manager, the system role that manages trusted issuers and topics, adds and removes them.
A trusted issuers registry can inherit from a parent, and from its parent's parent, to a depth of three levels: the asset's own list, the organisation's list, and the network-wide list that every organisation on that network inherits. Inheritance adds rather than overrides: a registry trusts its own issuers plus the ones its parents trust. An organisation cannot remove one inherited issuer, and its verification policy manager can detach the organisation's list from its parent entirely. An issuer that one organisation trusts is not trusted by another organisation, even on the same network, and a valid signature from that issuer still fails there.
Each asset records the identity registry it consults when it is created, and a holder of its Governance role can replace it later with a direct contract call. The claims on an identity are shared, but the trust decision is not, so one asset may count a claim that the asset beside it ignores.
Where identity and eligibility meet
When an asset tests a recipient, the ledger combines four records that different roles administer: the identity registry that binds the wallet to an identity, the catalogue of topics, the claims on the identity, and the trusted issuers for each topic. A rejected transfer traces back to one of these four.
The asset's rule is an expression over topics, joined by and, or, and not, with at most 32 elements. The token's Governance role sets it with “Edit holder rule” on the token's “Compliance” tab, or through the compliance expression route of the Platform API. An asset with no expression still needs a registered wallet that is not marked lost. The check resolves its conditions in order, and the first one that fails ends it: the transfer reverts, and nothing moves.
Four conditions are evaluated on the ledger in this order, and the first that fails ends the check and reverts the transfer.
For each required topic, the check collects the claims under that topic, compares their issuer with the trusted list for the topic, then asks the issuer's own identity whether the claim is still valid. A revoked claim stays visible on the identity while it fails that last question.
The token's core identity check evaluates the recipient. Compliance modules can add rules about the sender. A burn has no recipient, so the recipient identity check does not run. A forced transfer by a Custodian, the asset role that freezes, forces transfers and recovers tokens, skips the compliance modules, the pause and any freeze on the sending wallet, and refuses a receiving wallet whose address is frozen. On an asset whose identity registry holds the topic expression, a forced transfer still runs the identity check in full, expression included. On an asset that applies its topic rule through an identity verification compliance module, a forced transfer checks only that the recipient is registered and its wallet is not marked lost, because forced transfers skip compliance modules.
When a holder loses a wallet
An Identity manager recovers a user who lost access to their wallet. The recovery replaces the user's wallet and identity on the ledger, and it cannot be undone. On the ledger one Identity manager acts alone and names the replacement wallet, and that wallet can then claim the lost wallet's balance of every token, so treat Identity manager as a role that can move holdings. A recovery made through the platform asks a second person by default, because the “Recovery” group of the Administration family in Approvals starts on. An owner can turn it off, and an organisation with no owner or administrator besides the person recovering runs the recovery without one.
The recovery:
- It gives the user a replacement wallet and a new identity, and marks the lost wallets as lost in the registry, so no token can be sent to them again.
- It leaves what the lost wallet is still owed claimable by the replacement wallet: a failed sale's refund, fixed-yield coupons and interest. The lost wallet cannot claim them itself, so each has a recovered-wallet claim route that pays the replacement wallet.
- It records in the registry which wallet replaced which, so an auditor can follow one subject across the change. It also links the new identity to the identity it replaced, so a limit kept per investor, such as a token sale's allocation cap, keeps applying to the replacement wallet.
- It issues again, signed by the organisation's operations signer, every standing claim that the organisation's own issuer identity signed on the lost identity. A claim from another issuer does not move. That issuer signs it again on the new identity, so plan that step into your runbook.
- It moves the user's balances to the replacement wallet one token at a time, through the Custodian's forced recovery call signed by the operator who runs the recovery. A token whose call fails stays on the lost wallet, and a Custodian of that asset recovers it.
- It rebinds the custody gateway of the lost identity, whether the identity is the gateway's current or a former client, to the replacement wallet and then the replacement smart wallet, so the client keeps its gateway. While the Custodian's forced recovery has not moved the receipts held for custody, the gateway refuses the rebind and the recovery stops with that reason. Execute it again after the token recovery finishes.
- It signs the user out of every session, removes their sign-in code and passkeys, and resets their wallet verification: the transaction PIN, the transaction code and the recovery codes. When mail delivery is configured, it emails the user that an administrator recovered their wallet.
A recovery made before the registry kept the link between identities has no link, so a token sale's allocation cap does not follow that recovery on the ledger. A System manager adds the missing link with a contract call on the registry's storage contract, using the wallets and identity from the recovery's own event. Add it before a sale sets caps.
On-chain identity in the Console gives the recovery steps and what each screen shows.
The integration contract
To an integration, an On-Chain Identity is one address. The identity endpoints read an identity by wallet or by identity address, search for one, list the organisation's identities, and return the acting account's own identity. They also create an identity, register a wallet, file a pending registration, change a registration's country, remove a registration, and preview, run and follow a recovery. Creating an identity for a wallet its holder keeps in a browser or embedded wallet needs that wallet's own signature: the first request answers with the identity factory payload to sign, and the repeated request carries the signature.
What a caller can read depends on its role. A System manager, an Identity manager or a verification issuer can read any identity in the organisation. Every other caller reads only the identities of wallets its acting participant holds, and a bank rail manager can also read the identity of the organisation's bank rail wallet. A read of the caller's own identity returns an explicit not-provisioned result when the acting account has no identity yet.
Issuing a claim is a ledger write, so it follows the platform's asynchronous mutation contract. Wait for it to settle inside the window you ask for, or take the accepted response and follow its status link. Acceptance means the platform recorded your instruction, and the outcome is the request's own Settlement Verdict, the recorded end state the platform reports once the write resolves.
The API has three reads. Reading an identity returns its address, its registration state, and the claims on it, each marked with whether the consulted registry trusts its issuer. A registration-status read returns one value to branch on: no system, no identity, not registered, pending, or active. An eligibility read returns allowed, needs-action or blocked, with a reason for each failing rule from the platform's error catalogue, so an integration can tell a holder what to fix.
An eligibility result is a diagnosis, not a reservation. It describes the moment it ran, and the asset repeats the real check inside the transfer. A clear read followed by a revocation still ends in a reverted transfer.
Replacing the organisation identity before setup
Only the system factory can record an identity as the organisation's identity, and it does so in the transaction that creates the system. Anyone can still use the identity factory to create an identity for the system's address before the system exists. When that happens, a System manager, the system role that administers the organisation's contracts, can replace it with a contract call. This works only before the system's one-time setup runs, and the replacement identity always carries the contract identity claim that the factory issues.
Controls and evidence
For a control function, an On-Chain Identity is a preventive control with a readable history. It records that a check was made, by which issuer, for which topic, and when it stopped counting. The material behind the check stays in the systems that already hold it.
What reaches the ledger is a topic, the issuing identity, a signature and a value. The platform does not write identity documents, review notes or provider payloads to the ledger, so they stay under your existing retention rules. Claim values are public, so keep personal data out of them.
Write eligibility rules positively and withdraw eligibility by revoking a claim. A rule that reads “verified and not sanctioned” lets through a wallet that no one ever screened, because a missing sanctions claim reads as false and the negation turns it into true. Screening results still belong in the record as evidence, and the enforcing step is revoking the eligibility claim the rule requires. A rule that excludes the holders of a sanctions claim has a second flaw, because a holder can remove that claim from their own identity. To enforce a sanctions list directly, use an identity block list, which the issuer maintains and the holder has no key to edit. A recovery gives the holder a new identity, so add that identity to the list after any recovery.
The evidence trail sits on the ledger. Issues, changes, removals and revocations each land as a timestamped event with their topic and issuing identity, so a holder's eligibility history can be rebuilt from the ledger alone. Registration, country, the lost-wallet marker and recovery links sit in the registry beside it.
Frequently asked questions
Does a holder's personal data end up on a blockchain?
Identity documents and review notes stay off the ledger. The ledger exposes addresses, topics, issuers, signatures and claim values. Those records can be linked with other information, so assess them under your privacy policy.
What happens when a screening flags a holder?
Your reviewer revokes the eligibility claim the asset requires, or a connected compliance provider revokes it when its alert meets the severity threshold you set. From that moment, a transfer to the holder fails on any asset that requires that topic and has no other trusted claim to accept. Transfers that settled before the flag stay settled. The revocation leaves the holder's existing balance where it is, and the holder can still send tokens out, because the identity check reads the recipient. To stop outgoing transfers, freeze the wallet or the position through the asset's controls.
What if someone steals an issuer's signing key?
Remove the stolen key from the issuer's identity. Each claim check recovers the signer from the signature and asks whether that signer's key still carries the claim-signing purpose on the issuer's identity, so every claim the stolen key signed fails from the next read. Issuing those claims again under the remaining key restores them. Removing the issuer from a registry reaches only that level: a registry that inherits the issuer from a parent still trusts it until the parent removes it too.
Can a holder delete a claim from their own identity?
A holder who controls a key with that permission can remove a claim from their identity, and the removal is itself a recorded event. The removal costs them their own eligibility. A rule that demands a present, valid claim cannot be satisfied by deleting anything. A rule that excludes the holders of a claim can be satisfied that way. The platform checks every such rule when it is saved, and the claim topic's “Use in exclusions” setting decides whether the save goes through, needs the author to accept the risk, or is refused. Excluding holders of a claim describes the check.
Is this the same identity as the login account?
No. Sign-in, two-factor authentication and wallet verification govern who may operate the Console. An On-Chain Identity governs whether a subject may hold a regulated asset. A user with full Console access and no claims cannot receive a restricted token, and revoking someone's Console access leaves their claims as they were.