> 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/issuer/03.-configure-required-claim-topics.md). # 03. Configure required claim topics The required claim topics are what an investor has to prove to hold the asset: identity verified, accredited, resident of a permitted jurisdiction. The Issuer sets them in the asset's eligibility registry, as a default set and, where needed, as a separate set for one type of identity. It does so before the first mint, and again whenever the requirements of the asset change. A change applies to every holder at the next eligibility check. ## At a glance | | | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Triggered by** | Issuer | | **Actors** | Issuer, Claim Issuer, Investor, Platform | | **Contracts** | `TREXRegistry` | | **Preconditions** | The token suite is deployed (see [01](/guides/issuer/01.-deploy-a-token-suite.md)); the suite is commissioned and the caller holds `OWNER` in the asset's domain (see [25](/guides/issuer/25.-commission-a-suite-and-grant-roles.md)); the Issuer and its Claim Issuers have agreed on the topic identifiers | | **Result** | `TREXRegistry` holds the set of claim topics an identity must satisfy, by default and per identity type | ## Actors and roles | Actor | Role in this flow | What they hold | | ------------ | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | | Issuer | Decides the requirements and submits the changes. | `OWNER` on the `TREXRegistry` | | Claim Issuer | Issues claims under the topics the Issuer requires. Does not transact in this flow. | Trusted for those topics (see [04](/guides/issuer/04.-add-a-trusted-claim-issuer.md)) | | Investor | Is affected: its eligibility is evaluated against the new set. Does not transact. | An ONCHAINID carrying claims | | Platform | Runs the reads and submits with the Issuer's key. | The Issuer's signing key, or a key authorized for it | ## Sequence ```mermaid sequenceDiagram participant Platform participant Issuer participant Registry as TREXRegistry Platform->>Registry: getClaimTopics() (read) Platform->>Registry: getTrustedIssuersForClaimTopic(topic) (read) Platform->>Issuer: impact assessed, submit Issuer->>Registry: addClaimTopic(topic) Registry->>Registry: caller holds OWNER, set not full, topic not present Registry-->>Platform: ClaimTopicAdded(topic) opt a set for one identity type Issuer->>Registry: addClaimTopicForIdentityType(identityType, topic) Registry-->>Platform: ClaimTopicAddedForIdentityType(identityType, topic) end opt a topic is no longer required Issuer->>Registry: removeClaimTopic(topic) Registry-->>Platform: ClaimTopicRemoved(topic) end ``` ## Step by step ### Step 1. Assess the change **Who:** Platform, on behalf of the Issuer **Call:** Off-chain, using read calls **Before the call:** The Issuer knows which topic it adds or removes. A topic is a number agreed between the Issuer and its Claim Issuers, for example ``. **What happens:** The Platform reads `TREXRegistry.getClaimTopics()` and, for each identity type the Issuer distinguishes, `TREXRegistry.getClaimTopicsForIdentityType(identityType)`. Before adding a topic, it reads `TREXRegistry.getTrustedIssuersForClaimTopic(topic)`. If that list is empty, no claim can satisfy the topic and every identity held to it becomes ineligible as soon as the topic is required. The Issuer trusts a Claim Issuer for the topic first (see [04](/guides/issuer/04.-add-a-trusted-claim-issuer.md)). For an asset that already has holders, the Platform also estimates how many of them hold a valid claim for the topic. **What changes:** Nothing on-chain. ### Step 2. Add a topic to the default set **Who:** Issuer (`OWNER`) **Call:** `TREXRegistry.addClaimTopic(claimTopic)` **Before the call:** Step 1 is done. **What the contract checks:** 1. The caller holds `OWNER` in the asset's domain. Otherwise the call reverts with `AccessManagedUnauthorized`. 2. The default set holds fewer than 15 topics. Otherwise `MaxClaimTopicsReached`. 3. The topic is not already in the set. Otherwise `ClaimTopicAlreadyExists`. **What changes:** The topic is added to the default set. The registry emits `ClaimTopicAdded(claimTopic)`. From the next eligibility check, every identity held to the default set needs a valid claim for this topic from a Claim Issuer trusted for it. ### Step 3. Define a set for one identity type Optional. Use it when one type of identity has different requirements, for example legal entities. **Who:** Issuer (`OWNER`) **Call:** `TREXRegistry.addClaimTopicForIdentityType(identityType, claimTopic)`, once per topic of the set **Before the call:** The Issuer has listed every topic that identities of that type must satisfy. The set of a type replaces the default set for that type. It does not add to it. **What the contract checks:** 1. The caller holds `OWNER`. Otherwise `AccessManagedUnauthorized`. 2. `identityType` is not zero. Otherwise `InvalidIdentityType`. 3. The set of that type holds fewer than 15 topics. Otherwise `MaxClaimTopicsReached`. 4. The topic is not already in that set. Otherwise `ClaimTopicAlreadyExists`. **What changes:** The topic is added to the set of that type. The registry emits `ClaimTopicAddedForIdentityType(identityType, claimTopic)`. As soon as the set of a type holds one topic, identities of that type are held to that set and no longer to the default set. ### Step 4. Remove a topic **Who:** Issuer (`OWNER`) **Call:** `TREXRegistry.removeClaimTopic(claimTopic)`, or `TREXRegistry.removeClaimTopicForIdentityType(identityType, claimTopic)` **Before the call:** The Issuer has decided that the topic is no longer required. **What the contract checks:** 1. The caller holds `OWNER`. Otherwise `AccessManagedUnauthorized`. 2. For the per-type function: `identityType` is not zero. Otherwise `InvalidIdentityType`. **What changes:** The topic leaves the set and the registry emits `ClaimTopicRemoved(claimTopic)` or `ClaimTopicRemovedForIdentityType(identityType, claimTopic)`. Removing a topic that is not in the set does nothing and emits nothing. When the set of a type becomes empty, identities of that type are held to the default set again. ## State after the flow * `TREXRegistry.getClaimTopics()` returns the default set. * `TREXRegistry.getClaimTopicsForIdentityType(identityType)` returns the set of a type, empty when the type follows the default. * `TREXRegistry.isVerified(address)` reflects the new requirements for every address, without any other transaction. * No balance has changed. A holder that no longer satisfies the requirements keeps its position and cannot receive more. ## Failure modes | Symptom | Cause | Fix | | --------------------------------------------------------------- | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Reverts with `AccessManagedUnauthorized` | The caller does not hold `OWNER` in the asset's domain (check 1 of steps 2 to 4) | Grant the role: [25](/guides/issuer/25.-commission-a-suite-and-grant-roles.md) | | Reverts with `MaxClaimTopicsReached` | The set already holds 15 topics (step 2, check 2; step 3, check 3) | Remove a topic that is no longer needed | | Reverts with `ClaimTopicAlreadyExists` | The topic is already in the set (step 2, check 3; step 3, check 4) | Nothing to do | | Reverts with `InvalidIdentityType` | `identityType` is zero (step 3, check 2; step 4, check 2) | Use the value of a real type | | After adding a topic, every investor is ineligible | No Claim Issuer is trusted for the topic, or investors hold no claim for it yet | Trust a Claim Issuer for the topic ([04](/guides/issuer/04.-add-a-trusted-claim-issuer.md)) and have claims issued ([05](/guides/claim-issuer/05.-issue-a-claim-to-an-investor.md)) before requiring the topic | | A topic added to the default set is not required from companies | `CORPORATE` has its own set, which replaces the default | Add the topic to the set of that type as well | | `removeClaimTopic` succeeds and nothing changes | The topic was not in the set | Read the set first | ## Common misunderstandings > **Wrong:** "Adding a claim topic adds the KYC to the investors." > > **Right:** A topic is a requirement, not a credential. Requiring a topic makes every identity that lacks a valid claim for it ineligible. The credentials come from Claim Issuers, who sign claims on each identity. > **Wrong:** "The set for a type adds to the default set." > > **Right:** It replaces it. An identity is held either to the set of its type or to the default set, never to both. A topic that every holder must satisfy is added to the default set and to each set defined for a type. > **Wrong:** "A change of topics applies to new investors only." > > **Right:** Eligibility is evaluated at each transfer, against the current configuration. A new requirement applies at once to every holder. Those who do not meet it keep their position and can no longer receive. > **Wrong:** "Removing a topic revokes the claims issued under it." > > **Right:** The claims stay on the identities and stay valid. The asset stops asking for them. ## Integration notes * Read `getTrustedIssuersForClaimTopic(topic)` before requiring a topic. An empty list makes the topic unsatisfiable. * For a live asset, add the trusted issuer first, let claims be issued, then require the topic. The order avoids an interval in which holders cannot receive. * The type of an identity is read from `IdentityFactory.identityTypeOf(identity)`. An identity the factory did not create has no type and is held to the default set. * There is no batch function for topics. Group several calls in one transaction through the caller's own account if it is a smart account. * Index `ClaimTopicAdded`, `ClaimTopicRemoved` and the two per-type events to keep an off-chain view of the requirements. * Topic identifiers are a convention between the Issuer and its Claim Issuers. Document them next to the asset. ## Related flows * [04 Add a trusted Claim Issuer](/guides/issuer/04.-add-a-trusted-claim-issuer.md) : whose claims satisfy a topic * [01 Deploy a token suite](/guides/issuer/01.-deploy-a-token-suite.md) : sets the first topics * [05 Issue a claim to an investor](/guides/claim-issuer/05.-issue-a-claim-to-an-investor.md) : how an identity comes to satisfy a topic * [20 Remove a trusted Claim Issuer](/guides/issuer/20.-remove-a-trusted-claim-issuer.md) : the other way requirements tighten * [08 Mint a position to an investor](/guides/positions/08.-mint-a-position-to-an-investor.md) : where eligibility is first checked --- # 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/issuer/03.-configure-required-claim-topics.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.