> ## Documentation Index
> Fetch the complete documentation index at: https://kleros-mintlify-6ebc7975.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Kleros V2 SDK

> @kleros/kleros-sdk TypeScript library reference: dispute template population, evidence handling, and Kleros V2 contract interactions on Arbitrum.

The Kleros SDK (`@kleros/kleros-sdk`) is a TypeScript library for interacting with the Kleros V2 protocol. It succeeds Archon and provides utilities for dispute template population, evidence handling, and contract interactions.

<Warning>
  The SDK is under active development. For production use, pin to a specific version and review the changelog before upgrading. ABIs from `@kleros/kleros-v2-contracts` are stable for direct contract interaction.
</Warning>

## Installation

```bash theme={null}
npm install @kleros/kleros-sdk
# Peer dependencies
npm install @kleros/kleros-v2-contracts viem
```

## Packages

The SDK lives at [github.com/kleros/kleros-v2](https://github.com/kleros/kleros-v2) inside the `kleros-sdk/` workspace. It is published as `@kleros/kleros-sdk`.

## Key Features

### Dispute Template Population

The SDK resolves `templateDataMappings` to populate `{{variable}}` placeholders in dispute templates. This is the primary use case - run mappings client-side to display rich dispute context.

```typescript theme={null}
import { populateTemplate } from "@kleros/kleros-sdk";

// disputeTemplate: the JSON template string from DisputeTemplateRegistry
// mappings: the JSON mappings array string from DisputeTemplateRegistry
// externalDisputeID: your app's dispute/transaction ID
const populated = await populateTemplate(
  disputeTemplate,
  mappings,
  externalDisputeID,
  { graphApiKey: process.env.GRAPH_API_KEY }
);

console.log(populated.title);       // "Escrow dispute: Widget delivery"
console.log(populated.description); // "Buyer claims goods were not delivered..."
```

### ExtraData Encoding / Decoding

```typescript theme={null}
import { encodeExtraData, decodeExtraData } from "@kleros/kleros-sdk";

// Encode: General Court (ID 1), 3 jurors
const extraData = encodeExtraData(1n, 3n);
// → "0x000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000003"

// Decode
const { courtId, minJurors } = decodeExtraData(extraData);
// → { courtId: 1n, minJurors: 3n }
```

### Evidence Submission

```typescript theme={null}
import { uploadEvidence, submitEvidence } from "@kleros/kleros-sdk";

// Upload evidence to IPFS
const { uri } = await uploadEvidence({
  name: "Delivery Receipt",
  description: "Screenshot showing delivery on Jan 15",
  fileURI: "/ipfs/QmFile...",
});

// Submit on-chain
await submitEvidence(walletClient, {
  arbitrator: KLEROS_CORE_ADDRESS,
  evidenceGroupID: txID,
  evidence: uri,
});
```

### Contract Discovery

```typescript theme={null}
import { getContracts } from "@kleros/kleros-sdk";

const contracts = await getContracts(chainId);
// → { klerosCore, sortitionModule, disputeKitClassic, templateRegistry, ... }
```

## Staking

```typescript theme={null}
import { setStake } from "@kleros/kleros-sdk";

// Stake 200 PNK in court 1
await setStake(walletClient, {
  courtId: 1n,
  amount: parseUnits("200", 18),
});
```

## Capabilities Summary

| Feature             | Description                                                                  |
| ------------------- | ---------------------------------------------------------------------------- |
| Template population | Resolves `templateDataMappings` to fill `{{variables}}` in dispute templates |
| ExtraData codec     | Encode/decode court ID + juror count for `createDispute()`                   |
| Evidence upload     | Upload evidence JSON to IPFS, emit on-chain `Evidence` event                 |
| Contract discovery  | Resolve KlerosCore, SortitionModule, etc. by chain ID                        |
| Staking             | Set/remove PNK stake in courts                                               |
| Dispute queries     | Fetch active disputes, juror votes, and draw status                          |
| Appeal crowdfunding | Contribute to appeal rounds                                                  |
| Content validation  | Verify evidence/template integrity via hash                                  |

## Source

[GitHub - kleros/kleros-v2/kleros-sdk](https://github.com/kleros/kleros-v2/tree/dev/kleros-sdk)