Developer workflows

IXO MultiClient SDK message patterns, step by step: query and signing clients, entities, claims, evaluation and tokens, with the errors each can return.

These workflows show the canonical message patterns from the @ixo/impactxclient-sdk README. For full type definitions, see @ixo/impactxclient-sdk and the proto definitions.

Prerequisites

  1. Install dependencies: @ixo/impactxclient-sdk. For the service that produces a decision, see Decision oracle.
  2. Choose the RPC endpoint and chain ID from Networks and endpoints.
  3. Choose the authentication for each API from Authentication matrix. On-chain writes require a funded signer (wallet or key management you control).
  4. Use a test network while you build. The testnet RPC endpoint is https://testnet.ixo.earth/rpc/.
npm install @ixo/impactxclient-sdk

1. Initialize query and signing clients

Reads use createQueryClient. Writes need a signer-backed createSigningClient. Both target the same RPC endpoint.

import {
  ixo,
  createQueryClient,
  createSigningClient,
} from "@ixo/impactxclient-sdk";

// From your environment. Testnet: https://testnet.ixo.earth/rpc/
const RPC_ENDPOINT = process.env.RPC_ENDPOINT!;

// `offlineSigner` is yours to create. See "Creating signers" in the SDK README.
// `signerAddress` is the ixo1… address of that signer.

const queryClient = await createQueryClient(RPC_ENDPOINT);
const signingClient = await createSigningClient(RPC_ENDPOINT, offlineSigner);

Errors: RPC misconfiguration surfaces as connection timeouts or JSON-RPC errors. Try a different node if your operator allows it, and confirm TLS and chainId against the network row in Networks and endpoints.

For signer setup (Cosmos-kit, Keplr, or getOfflineSigner from cosmjs-utils), see Creating signers in the SDK README.

2. Register an entity (digital twin)

Compose MsgCreateEntity, sign and broadcast.

const createEntityMsg = {
  typeUrl: "/ixo.entity.v1beta1.MsgCreateEntity",
  value: ixo.entity.v1beta1.MsgCreateEntity.fromPartial({
    ownerAddress: signerAddress,
    entityType: "asset",
    context: [
      ixo.iid.v1beta1.Context.fromPartial({
        key: "class",
        val: "did:ixo:entity:protocol123",
      }),
    ],
    verification: [],
    controller: [],
    service: [],
    linkedResource: [],
    accordedRight: [],
    linkedEntity: [],
    linkedClaim: [],
  }),
};

const response = await signingClient.signAndBroadcast(
  signerAddress,
  [createEntityMsg],
  "auto",
);

Read the resulting entity through the query client:

const entities = await queryClient.ixo.entity.v1beta1.entityList();

Errors: invalid entityType or context key/value pairs that the chain does not accept return failed transactions. Inspect code and rawLog on the broadcast response.

3. Submit a claim

const submitClaimMsg = {
  typeUrl: "/ixo.claims.v1beta1.MsgSubmitClaim",
  value: ixo.claims.v1beta1.MsgSubmitClaim.fromPartial({
    creator: signerAddress,
    claimId: "bafkreih...",
    collectionId: "12",
    adminAddress: collectionAdminAddress,
  }),
};

await signingClient.signAndBroadcast(signerAddress, [submitClaimMsg], "auto");

Errors: missing collectionId, schema mismatch, or insufficient authorization produce chain errors. Cross-check Claims management and Custom authorisations for IXO Claims.

4. Record an evaluation

MsgEvaluateClaim writes a decision to the chain. It does not make one. The decision comes from a separate service, and this step records its result.

If you use a decision oracle built with @ixo/decision-oracle, skip this step. The oracle records the decision for you, with the decision engine's signed receipt as the proof. See Decision oracle.

The example below is for a team that runs its own evaluation service.

// `evaluateWithMyService` stands for your own code. It is not part of the SDK.
const result = await evaluateWithMyService({ claimId: "bafkreih..." });

// The protocol's statuses: 1 approved, 2 rejected, 5 flagged (no final call, no payment).
const STATUS = { approved: 1, rejected: 2, flagged: 5 } as const;

const evaluateMsg = {
  typeUrl: "/ixo.claims.v1beta1.MsgEvaluateClaim",
  value: ixo.claims.v1beta1.MsgEvaluateClaim.fromPartial({
    creator: signerAddress,
    claimId: "bafkreih...",
    collectionId: "12",
    oracle: oracleAddress,
    adminAddress: collectionAdminAddress,
    status: STATUS[result.outcome], // set from the result, never hardcoded
    reason: 0,
    verificationProof: result.proofCid,
    amount: [],
  }),
};

await signingClient.signAndBroadcast(signerAddress, [evaluateMsg], "auto");

Errors: MsgEvaluateClaim failures usually point to authorization (your account holds no EvaluateClaimAuthorization on the collection) or to the claim's state. See Custom authorisations for IXO Claims.

5. Issue tokens against an evaluated claim

After approval, mint tokens with MsgMintToken against your token contract. Manage tokens covers the full family of token messages.

const mintMsg = {
  typeUrl: "/ixo.token.v1beta1.MsgMintToken",
  value: ixo.token.v1beta1.MsgMintToken.fromPartial({
    minter: signerAddress,
    contractAddress: tokenContractAddress,
    owner: recipientAddress,
    mintBatch: [
      ixo.token.v1beta1.MintBatch.fromPartial({
        name: "CARBON",
        index: "bafkreih...",
        amount: "3600",
        collection: "did:ixo:entity:collection456",
        tokenData: [],
      }),
    ],
  }),
};

await signingClient.signAndBroadcast(signerAddress, [mintMsg], "auto");

6. Verifiable credentials

Your programme's issuer keys, schemas, and registry or IXO Matrix storage govern how credentials are issued and verified. See Credential issuance and Identity and credentials. Implement issuance in the component that holds the issuer key. A verifier should check the signature, the issuer DID, the schema, and the revocation and status lists. For HTTP-oriented credential flows on Emerging, see Emerging API and the matching auth rules in Authentication matrix.

Error handling

  • HTTP service calls: use Error handling for status codes; add retry/backoff for 429 and transient 5xx.
  • GraphQL (Blocksync): partial errors may appear in a top-level errors array while data is non-null, so check both. Unauthenticated introspection may be disabled on some deployments.
  • DID resolution: if resolution fails, confirm the DID is registered on the expected network and that you query the correct registry or indexer endpoint.

Next steps