The steps of a claim workflow can run in two places: on the IXO Protocol, through its claims module, or through a service API such as the Impact Hub Registry. Use this guide to decide where each of your steps runs before you write the integration. After reading you will know the boundary between the two layers, the outline of the workflow, the statuses an evaluation can give, and what to check when a step fails.
This is a design guide. It helps you plan, and it gives you no complete sequence to run. For the messages step by step, see Developer workflows. For exact request and response contracts, use the API reference pages. To plan the collection itself, see Design a verified claims workflow.
Before you start
- Decide whether each claim operation runs at the protocol layer or the service layer.
- Confirm the endpoint and network values in Networks and endpoints. Use a test network while you build.
- Confirm the authentication each API requires in the Authentication matrix.
Protocol layer or service layer
| Layer | What runs there |
|---|---|
| Protocol | Claims module transactions and state queries, through protocol gateways |
| Service | Product-specific reporting and workflow APIs, for example the Registry service endpoints |
The workflow in outline
- Create or collect the claim data.
- Submit it to the layer you chose: the protocol or the service.
- Run the evaluation, and handle any dispute.
- Track the claim as its status changes.
An evaluation gives a claim one of the chain's statuses: pending (0), approved (1), rejected
(2), invalidated (4) or flagged (5). The status disputed (3) is no longer accepted on a new
evaluation. A dispute is a separate record. See
How claim disputes work on chain.
Shape of a protocol message
Illustrative example. It shows the shape of a claims module message and is not a tested call.
const msg = {
typeUrl: "/ixo.claims.v1beta1.MsgSubmitClaim",
value: {
creator,
claimId,
claimType,
data: claimData
}
};Check the result
A working integration gives you:
- a claim write that is accepted, or a query response, from the layer you targeted
- a clear record of whether each step ran through a protocol gateway or a service API
Troubleshooting
| Problem | What to do |
|---|---|
| A broadcast or a transaction fails | Read rawLog or code in the node's response. insufficient funds, unauthorized and sequence mismatch are common. Fix the fees, the signer or the account sequence. Compare your chainId and RPC URL with Networks and endpoints. |
| GraphQL returns a partial failure | Blocksync may return errors alongside partial data. If any required field is null, treat the response as failed for downstream writes, then re-check your filters and IDs. |
| A DID or an entity is not found | Confirm that the entity is indexed on the network you query. Lag between the registry and the indexer can produce a temporary "not found" result. |
Next steps
The SDK patterns for creating, submitting and evaluating, step by step.
How claim disputes work on chainWho can file a dispute, the stake, and how it is decided.
Choose an IXO APIAn API matrix for choosing RPC, REST, GraphQL or Registry for each step.
Blockchain RPC APIProtocol RPC methods and request patterns.
Registry APIRegistry endpoints for claim-linked records.
Identity and credentialsHow claims relate to DIDs and verifiable credentials.