> 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/identity-onchainid/claim-issuers-trust-and-reputation.md).

# Claim issuers, trust and reputation

The protocol never issues or attests a claim. Claim Issuers do: KYC and AML providers, accreditation verifiers, the compliance function of an Issuer. Every eligibility decision rests on their attestations, so the protocol is precise about how far each one is trusted, by whom, and for what.

Trust in a Claim Issuer is not one thing. It is three separate questions, answered in three different places.

| Question                                                      | Answered by                                    | Where                        |
| ------------------------------------------------------------- | ---------------------------------------------- | ---------------------------- |
| Is this a Claim Issuer?                                       | The type of its identity, recorded at creation | `IdentityFactory`            |
| May it write its claims onto identities on its own authority? | Its standing in the network                    | `ReputationRegistry`         |
| Do its claims make an investor eligible for this asset?       | The Issuer of the asset                        | `TREXRegistry` of that asset |

The second and the third are independent. An issuer with full standing in the network counts for nothing toward an asset that does not list it. An asset can list an issuer that has no standing in the network at all.

## What a Claim Issuer is on-chain

A Claim Issuer is an ONCHAINID of type `CLAIM_ISSUER`.

* **It is created by an authorized party.** The type cannot be self-deployed. See [Identity types and factory gating](/identity-onchainid/identity-types-and-factory-gating.md).
* **It signs with `CLAIM_SIGNER` keys.** A claim is valid only while the key that signed it holds that purpose on the issuer's identity.
* **It answers for its claims.** Anyone can ask it whether a claim is valid, with `isClaimValid`. The register asks at every eligibility check.
* **It revokes.** It marks a claim as revoked, or withdraws a signing key, and the effect is immediate.

An issuer can also be a contract that is not an identity, provided it answers `isClaimValid`. That is how external attestation systems are connected. See [External attestations](/identity-onchainid/external-attestations.md).

## The two levels of trust

```mermaid
flowchart TB
    subgraph W["Writing a claim: network level"]
        direction LR
        CI1["Claim Issuer"] -->|"adds its claim"| ID1["Investor ONCHAINID"]
        RR["ReputationRegistry<br/>score and threshold"] -.->|"allows the write<br/>without a key grant"| ID1
    end
    subgraph R["Counting a claim: asset level"]
        direction LR
        TK["Token"] -->|"isVerified"| REG["TREXRegistry<br/>required topics, trusted issuers"]
        REG -->|"reads the claim"| ID2["Investor ONCHAINID"]
        REG -->|"isClaimValid"| CI2["Claim Issuer"]
    end
```

|                  | Network level: standing                                                                      | Asset level: trusted issuer                                              |
| ---------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| **Decides**      | Whether the issuer may add its own claims to an identity without the owner granting it a key | Whether a claim from this issuer satisfies a required topic of the asset |
| **Decided by**   | The `REPUTATION_MANAGER` role                                                                | The Issuer of the asset, with the `OWNER` role on its registry           |
| **Expressed as** | A reputation score, compared to a threshold                                                  | A list of issuers, each with the topics it is trusted for                |
| **Scope**        | Every identity in the network                                                                | One asset, or the assets that share its configuration                    |
| **Withdrawn by** | Setting the score below the threshold                                                        | Removing the issuer from the list, or a topic from its entry             |

### Asset level: whose claims count

The Issuer of an asset names the Claim Issuers it trusts, and for each one the topics it trusts it for.

| Function                                       | Effect                                                |
| ---------------------------------------------- | ----------------------------------------------------- |
| `addTrustedIssuer(issuer, claimTopics)`        | Trusts an issuer for a list of topics.                |
| `updateIssuerClaimTopics(issuer, claimTopics)` | Replaces the list of topics an issuer is trusted for. |
| `removeTrustedIssuer(issuer)`                  | Stops trusting an issuer for every topic.             |

For eligibility, only a claim from an issuer trusted for that topic counts. An issuer trusted for one topic is not trusted for another. Each change applies at the next eligibility check, for every investor at once: removing an issuer makes every identity that relied on it alone ineligible.

A registry accepts up to 50 trusted issuers, and up to 15 topics per issuer. The registry does not check what the address of an issuer is. Whom to trust is the Issuer's responsibility.

The recommendation is to trust only Claim Issuers whose identity was created by the `IdentityFactory` with the type `CLAIM_ISSUER`, and adapters governed by Network governance. An issuer that comes from another source is unlikely to be accepted by the other participants of the ecosystem, and `IdentityFactory.identityTypeOf(issuer)` tells the difference in one read.

### Network level: who may write

A claim reaches an identity in one of two ways. Without standing, it takes the owner's consent: the owner adds the claim, or has granted the issuer a claim key. See [Claims: issuance, validity, revocation](/identity-onchainid/claims-issuance-validity-revocation.md).

A Claim Issuer with standing does not need that grant. It adds its claims directly, which is what lets it deliver a credential to an investor's identity in one step. The write is accepted when both conditions hold:

1. The issuer's identity is recorded by the `IdentityFactory` with the type `CLAIM_ISSUER`.
2. Its reputation score is at least the claim-add threshold.

Claims from such an issuer are approved by default. Asking the owner to accept each claim would add a step to every onboarding, for every investor and every credential. The protocol controls who can be a Claim Issuer instead: the creation of a `CLAIM_ISSUER` identity is gated, so only parties recognized by the network hold one, and the reputation score withdraws the privilege from an issuer that no longer deserves it. Unwanted claims are stopped at the source, not at each identity.

Standing is narrow on purpose.

* **It covers the issuer's own claims only.** An issuer can never add a claim attributed to another issuer, nor remove one.
* **It leaves the owner in control of the identity.** The owner does not approve these writes in advance, and it can remove any claim from its identity afterward. Where the owner has granted the issuer a claim key, the write is authorized by that grant and standing is not consulted.
* **It confers no eligibility.** A claim written this way counts only for the assets that trust the issuer.
* **It cannot make an invalid claim valid.** The identity still asks the issuer to confirm the claim when it is added.

## The reputation registry

The `ReputationRegistry` keeps a score for identities and one threshold.

| Element                    | Meaning                                                                               | Set with                          |
| -------------------------- | ------------------------------------------------------------------------------------- | --------------------------------- |
| **Default score per type** | The score of every factory-created identity of that type that has no score of its own | `setDefault(identityType, score)` |
| **Explicit score**         | The score of one identity. It overrides the default, including when it is zero.       | `setReputation(identity, score)`  |
| **Claim-add threshold**    | The score an issuer must reach to add claims without a key grant                      | `setClaimAddThreshold(threshold)` |

All three are set by the `REPUTATION_MANAGER` role. Reading is open to anyone.

`reputationOf(identity)` returns the effective score, resolved in this order:

1. The explicit score, if one was ever set.
2. Otherwise the default for the identity's type, as recorded by the factory.
3. Otherwise zero: an address the factory did not create has no default.

Because the type comes from the factory's record, a contract cannot claim the default of a `CLAIM_ISSUER` by declaring that type itself.

### One lever for granting, vetting and revoking

Trust is a single number consulted at the moment of decision. Every change of standing is the same operation.

| Situation                                  | Operation                                                                                      |
| ------------------------------------------ | ---------------------------------------------------------------------------------------------- |
| A new Claim Issuer is onboarded            | It is created with the type `CLAIM_ISSUER` and receives the default score of that type.        |
| An issuer is vetted further, or downgraded | `setReputation` with the new score.                                                            |
| An issuer is found to be compromised       | `setReputation` with zero. Its direct writes are refused from the next transaction.            |
| The network raises its bar                 | `setClaimAddThreshold` with a higher value. Every issuer below it loses direct writes at once. |

Consumers read the score the same way whatever produced it: a governance decision, or an automated process that holds the `REPUTATION_MANAGER` role and derives scores from on-chain activity.

> **Trust statement.** The `REPUTATION_MANAGER` decides which Claim Issuers can write onto any identity in the network without the owner's grant. It does not decide eligibility for any asset. Who holds this role, and by what process it acts, is a governance matter of the network.

## What withdrawing trust does

| Who acts               | Action                                            | Effect on claims already issued                                                                                           |
| ---------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| The Issuer of an asset | Removes the Claim Issuer from its trusted issuers | They remain valid and stop counting for that asset.                                                                       |
| The network            | Sets the issuer's score below the threshold       | They remain valid and keep counting where the issuer is trusted. The issuer can no longer add claims without a key grant. |
| The Claim Issuer       | Revokes a claim                                   | That claim stops being valid everywhere.                                                                                  |
| The Claim Issuer       | Withdraws a signing key                           | Every claim signed with that key stops being valid everywhere.                                                            |

Lowering an issuer's reputation does not invalidate the claims it has issued. When an issuer is compromised, the Issuers that trust it remove it from their registries, which is what stops its claims from counting.

## Onboarding a Claim Issuer

1. **Create its identity.** A party holding the creation role for `CLAIM_ISSUER` deploys the identity for the issuer's account. The issuer's account is its only manager. The party that deployed it holds no key.
2. **Set up signing.** The issuer adds `CLAIM_SIGNER` keys for its signing service and keeps `MANAGEMENT` with its governance.
3. **Standing applies.** The identity has the default score of its type. The `REPUTATION_MANAGER` adjusts it if needed.
4. **Issuers trust it.** Each Issuer that relies on it adds it to the trusted issuers of its asset, for the relevant topics.
5. **It issues.** It verifies investors off-chain, signs claims and adds them to their identities.


---

# 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/identity-onchainid/claim-issuers-trust-and-reputation.md?ask=<question>&goal=<user_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.