Design a claims integration

Decide which steps of a claim workflow run on the IXO Protocol and which run through a service API, with the evaluation statuses and the common failures.

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.

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

LayerWhat runs there
ProtocolClaims module transactions and state queries, through protocol gateways
ServiceProduct-specific reporting and workflow APIs, for example the Registry service endpoints

The workflow in outline

  1. Create or collect the claim data.
  2. Submit it to the layer you chose: the protocol or the service.
  3. Run the evaluation, and handle any dispute.
  4. 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

ProblemWhat to do
A broadcast or a transaction failsRead 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 failureBlocksync 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 foundConfirm 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