# 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](https://github.com/ixofoundation/ixo-multiclient-sdk#readme). For full type definitions, see [`@ixo/impactxclient-sdk`](https://www.npmjs.com/package/@ixo/impactxclient-sdk) and the [proto definitions](https://github.com/ixofoundation/ixo-blockchain/tree/main/proto/ixo).

<Warning>
  Illustrative example. These steps show how each message is built and what can go wrong. They are
  not a tested project you can run as written: you supply the signer and every identifier, and the
  package version is not pinned to a tested release. Build against a test network, never against
  mainnet.
</Warning>

<Info>
  No single CLI covers every IXO operation. Use the SDK, Cosmos-compatible wallets, or deployment-specific CLIs your operator documents. For HTTP-oriented domain examples, see [Domain registration](/guides/domain-registration).
</Info>

## Prerequisites

1. Install dependencies: `@ixo/impactxclient-sdk`. For the service that produces a decision, see [Decision oracle](/build-an-oracle/decision-oracle).
2. Choose the RPC endpoint and chain ID from [Networks and endpoints](/reference/networks-and-endpoints).
3. Choose the authentication for each API from [Authentication matrix](/reference/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/`.

```bash
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.

```typescript
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](/reference/networks-and-endpoints).

For signer setup (Cosmos-kit, Keplr, or `getOfflineSigner` from `cosmjs-utils`), see [Creating signers](https://github.com/ixofoundation/ixo-multiclient-sdk#creating-signers) in the SDK README.

## 2. Register an entity (digital twin)

Compose `MsgCreateEntity`, sign and broadcast.

```typescript
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:

```typescript
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

```typescript
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](/guides/dev/ixo-claims) and [Custom authorisations for IXO Claims](/guides/dev/authz-custom).

## 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](/build-an-oracle/decision-oracle).

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

```typescript
// `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");
```

<Note>
  `evaluateWithMyService`, `result.outcome` and `result.proofCid` are placeholders for your own
  service and its answer. Test a rejection and an undecided claim as well as an approval. Recording
  an approval can release the payment a collection has promised, so an approval written by mistake
  costs real money on mainnet.
</Note>

**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](/guides/dev/authz-custom).

## 5. Issue tokens against an evaluated claim

After approval, mint tokens with `MsgMintToken` against your token contract. [Manage tokens](/guides/dev/tokens) covers the full family of token messages.

```typescript
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](/platforms/Emerging/credential-issuance) and
[Identity and credentials](/articles/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](/platforms/Emerging/emerging-api) and the matching auth rules in [Authentication matrix](/reference/authentication-matrix).

## Error handling

- **HTTP service calls:** use [Error handling](/api-reference/errors) 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

<CardGroup cols={2}>
  <Card title="IXO MultiClient SDK" icon="server" href="/sdk-reference/multiclient-sdk">
    The SDK's modules and types.
  </Card>
  <Card title="SDK and kit overview" icon="toolbox" href="/sdk-reference/index">
    Every SDK, and which one to use.
  </Card>
  <Card title="SDK patterns" icon="lightbulb" href="/guides/dev/examples">
    The same calls as snippets to adapt, with the inputs each one needs.
  </Card>
  <Card title="Decision oracle" icon="scale-balanced" href="/build-an-oracle/decision-oracle">
    The service that produces a decision and records it on chain.
  </Card>
</CardGroup>
