> For the complete documentation index, see [llms.txt](https://docs.t-rex.network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.t-rex.network/guides/agents/17.-update-an-investors-registration.md). # 17. Update an investor's registration Updating a registration changes the identity that an address is registered with for an asset. An agent does it to correct a registration made under the wrong identity, or to follow an investor that has moved to a new ONCHAINID. It applies only to addresses that have a local registration. When the address holds tokens, the update changes who those tokens are attributed to, without any transfer, so it is an operation to use with care. ## At a glance | | | | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Triggered by** | Registry Agent | | **Actors** | Registry Agent, Issuer, Investor, Platform | | **Contracts** | `TREXRegistry`, `IdentityRegistryStorage`, `ModularCompliance` (for the effect on positions) | | **Preconditions** | The address has a local registration (see [06](/guides/agents/06.-register-an-investor-for-an-asset.md)); the caller holds `AGENT` in the asset's domain; the new identity exists; the Issuer has established, under its own process, that the address belongs to the new identity | | **Result** | For this asset, the address resolves to the new identity, and what the address holds is attributed to it | ## Actors and roles | Actor | Role in this flow | What they hold | | -------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------ | | Registry Agent | Submits the update. | `AGENT` on the `TREXRegistry` | | Issuer | Decides the correction. Does not transact in this flow. | Its own verification | | Investor | Is the subject of the update. Does not transact. | The new ONCHAINID | | Platform | Runs the reads, assesses the impact and submits with the Registry Agent's key. | The Registry Agent's signing key, or a key authorized for it | ## Sequence ```mermaid sequenceDiagram participant Platform participant Agent as Registry Agent participant Registry as TREXRegistry participant IRS as IdentityRegistryStorage Platform->>Registry: isLocallyRegistered(address), identity(address) (read) Platform->>Registry: isVerified for the new identity's claims (read) Platform->>Agent: impact assessed, submit Agent->>Registry: updateIdentity(address, newIdentity) Registry->>Registry: caller holds AGENT Registry->>IRS: modifyStoredIdentity(address, newIdentity) IRS->>IRS: registry holds IRS_WRITER IRS->>IRS: address and identity not zero, address registered IRS-->>Platform: IdentityModified(oldIdentity, newIdentity) IRS-->>Platform: InvestorIdentityChanged(address) Registry-->>Platform: IdentityUpdated(oldIdentity, newIdentity) ``` ## Step by step ### Step 1. Assess the update **Who:** Platform, on behalf of the Registry Agent **Call:** Off-chain, using read calls **Before the call:** The Issuer has decided that the address is to be attributed to another identity. **What happens:** The Platform reads `TREXRegistry.isLocallyRegistered(address)`, which must be true, and `TREXRegistry.identity(address)`, the identity the address is registered with. It reads `Token.balanceOf(address)`. If the address holds tokens, the update moves that position from the old identity to the new one in the compliance ledger. The Platform therefore checks, for the new identity, what a transfer would check: that it holds valid claims for the required topics, and that its position after the update respects the rules of the asset. The contract does not make these checks. **What changes:** Nothing on-chain. ### Step 2. Update the registration **Who:** Registry Agent (`AGENT`) **Call:** `TREXRegistry.updateIdentity(userAddress, identity)` **Before the call:** Step 1 is done. **What the contract checks:** 1. The caller holds `AGENT` in the asset's domain. Otherwise the call reverts with `AccessManagedUnauthorized`. 2. The identity storage accepts the registry as a writer: the registry holds `IRS_WRITER` in the storage's domain, which commissioning grants. Otherwise `AccessManagedUnauthorized`, naming the registry. 3. Neither the address nor the new identity is zero. Otherwise `ZeroAddress`. 4. The address has a local registration. Otherwise `AddressNotYetStored`. The eligibility of the new identity and the compliance rules are not evaluated. **What changes:** The storage replaces the identity recorded for the address. It emits `IdentityModified(oldIdentity, newIdentity)` and `InvestorIdentityChanged(address)`. It emits `IdentityOverridden` when the new registration differs from the global link of the address, or `IdentityOverrideReleased` when it now matches it. The registry emits `IdentityUpdated(oldIdentity, newIdentity)`. The compliance ledger follows at the next movement through the address: it moves the whole balance of the address from the position of the old identity to the position of the new one, and emits `WalletOwnerChanged`. ## State after the flow * `TREXRegistry.identity(address)` returns the new identity. * `TREXRegistry.isVerified(address)` reflects the claims of the new identity. * The registration applies to every asset whose registry is bound to the same identity storage. * The balance of the address is unchanged. No `Transfer` event was emitted. * After the next movement through the address, `ModularCompliance.positionOf` has moved the address's balance from the old identity to the new one, and `ModularCompliance.ownerOf(address)` returns the new identity. ## Failure modes | Symptom | Cause | Fix | | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | Reverts with `AccessManagedUnauthorized` | The caller does not hold `AGENT` in the asset's domain (step 2, check 1) | Grant the role: [25](/guides/issuer/25.-commission-a-suite-and-grant-roles.md) | | Reverts with `AccessManagedUnauthorized`, naming the registry | The registry does not hold `IRS_WRITER` on the identity storage: the suite is not commissioned, or the storage is shared and sits in another domain (step 2, check 2) | Commission the suite: [25](/guides/issuer/25.-commission-a-suite-and-grant-roles.md) | | Reverts with `ZeroAddress` | The address or the identity is zero (step 2, check 3) | Pass both. To remove a registration, use [18](/guides/agents/18.-remove-an-investors-registration.md) | | Reverts with `AddressNotYetStored` | The address has no local registration. It may resolve through the global link only (step 2, check 4) | Register it first: [06](/guides/agents/06.-register-an-investor-for-an-asset.md). The global link itself cannot be changed by an agent | | `updateCountry` reverts with `Deprecated` | The registry stores no country | Nothing to update. Country is attested by a claim | | After the update, the address cannot receive | The new identity lacks a valid claim for a required topic | Have claims issued to the new identity: [05](/guides/claim-issuer/05.-issue-a-claim-to-an-investor.md) | | After the update, a `PositionUnderflow` event appears and `positionGap` is not zero | The address moved more than the old identity held in the ledger, after registrations were changed in an inconsistent order | The Compliance Owner repairs the positions with `fixPosition` | | A rule is breached after the update | The new identity now holds more than a rule allows, since the update is not checked against the rules | Avoid it in step 1. Otherwise the Issuer regularizes with a forced transfer or a redemption | ## Common misunderstandings > **Wrong:** "Updating a registration is an administrative detail." > > **Right:** For an address that holds tokens, it changes who owns them in the register, without a transfer and without any gate being evaluated. It has the effect of a transfer of ownership. An Issuer treats it with the same care as a forced transfer. > **Wrong:** "An agent can change which identity a wallet is linked to." > > **Right:** An agent changes the local registration of an address for its asset. The global link, made by the owner in the `IdentityFactory`, is permanent and no agent can change it. The local registration takes precedence for the assets that share the storage, and only for them. > **Wrong:** "The update moves the tokens to the new identity." > > **Right:** The tokens stay at the same address. What changes is the identity the address resolves to. The balance is the same, and the position in the compliance ledger follows at the next movement. > **Wrong:** "This flow updates the investor's country." > > **Right:** There is no country in the registry. `updateCountry` reverts. A change of residence is a new claim from a Claim Issuer. ## Integration notes * Read `isLocallyRegistered(address)` first. An address that resolves only through the global link has nothing to update. * Before updating an address that holds tokens, evaluate the new identity as the recipient of a transfer of that balance: `isVerified`, and the rules against its resulting position. * Index `InvestorIdentityChanged(address)`. The standard `IdentityModified` event names the two identities and not the address. * Index `IdentityOverridden` and `IdentityOverrideReleased` after an update to know whether the asset now departs from the global link. * Read `ModularCompliance.positionGap()` after a series of updates. It is zero when every position is attributed. * When an investor only wants to hold at another address, an update is not the tool. The investor links the new wallet and transfers. ## Related flows * [06 Register an investor for an asset](/guides/agents/06.-register-an-investor-for-an-asset.md) : creating the local registration * [18 Remove an investor's registration](/guides/agents/18.-remove-an-investors-registration.md) : deleting it * [07 Link a wallet to an ONCHAINID](/guides/identity/07.-link-a-wallet-to-an-onchainid.md) : the owner's own, permanent link * [14 Execute a forced transfer](/guides/agents/14.-execute-a-forced-transfer.md) : moving a position to another holder with a `Transfer` event * [15 Recover a position from a lost wallet](/guides/agents/15.-recover-a-position-from-a-lost-wallet.md) : when the address, not the identity, has to change --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.t-rex.network/guides/agents/17.-update-an-investors-registration.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.