@rakelabs/disputes-sdk

Build Kleros-facing dispute workflows from a TypeScript app. The SDK prepares unsigned transactions for dispute creation, evidence submission, meta-evidence amendments, appeals, and event decoding; your user's wallet remains responsible for signing and broadcasting.

The SDK never holds private keys and never takes custody of funds.

Your app -> Disputes SDK -> unsigned transaction -> user wallet -> blockchain

Install

# Choose one integration. The SDK core has no Ethers or Viem dependency.
npm install @rakelabs/disputes-sdk @rakelabs/ethers-adapter ethers
# or
npm install @rakelabs/disputes-sdk @rakelabs/viem-adapter viem

Requirements:

• Node.js 20+
• an RPC client and ABI codec supplied by your wallet/RPC integration
• ethers is only needed for the ethers adapter shown below; viem integrations can be used instead

What You Build With It

Use this package when your application needs a standalone Kleros dispute contract:

• choose Kleros court parameters with extraData,
• publish or reference a MetaEvidence URI,
• create a dispute with a fixed number of ruling options,
• submit evidence documents,
• read dispute state, evidence timelines, rulings, and events,
• prepare appeal transactions when the ruling can be appealed.

If your product is specifically escrow or payment oriented, start with @rakelabs/klescrow-sdk or @rakelabs/dpayments-sdk. Use this package when you need direct dispute primitives.

Quick Start

import { BrowserProvider } from 'ethers';
import { Disputes, ABI, extraData } from '@rakelabs/disputes-sdk';
import {
  createEthersRpcClient,
  createEthersAbiCodec,
} from '@rakelabs/ethers-adapter';

const provider = new BrowserProvider(window.ethereum);
await provider.send('eth_requestAccounts', []);

const signer = await provider.getSigner();
const walletAddress = await signer.getAddress();

const rpc = createEthersRpcClient(provider);
const codec = createEthersAbiCodec(ABI);
const disputes = await Disputes.fromRpc(rpc, { codec, walletAddress });

const arbitratorExtraData = extraData.generalCourt();
const estimate = await disputes.factory.estimateCost(arbitratorExtraData);

console.log('Total dispute cost:', estimate.total.toString());

const { tx, disputeId } = await disputes.factory.prepareCreateDispute({
  arbitratorExtraData,
  metaEvidenceUri: 'ipfs://QmYourMetaEvidenceDocument',
  numberOfRulingOptions: 2n,
});

console.log(tx.preview);

const response = await signer.sendTransaction({
  to: tx.to,
  data: tx.data,
  value: BigInt(tx.value),
});
await response.wait();

const created = (await disputes.factory.getLogs(0, 'latest'))
  .find((event) => event.disputeId === disputeId);

if (!created) {
  throw new Error('Dispute creation event was not found');
}

const dispute = disputes.dispute(created.instance);

MetaEvidence and Evidence

Kleros workflows usually have two document layers:

• MetaEvidence describes the dispute category, question, policy, and ruling options.
• Evidence describes the proof submitted for one specific dispute.

Use @rakelabs/evidence-publisher to build and publish both document types to IPFS, then pass the returned ipfs://... URIs into this SDK.

Common Flows

Read State

const info = await dispute.read();

console.log(info.state);
console.log(info.owner);
console.log(info.providerDisputeId);
console.log(info.numberOfRulingOptions);

Submit Evidence

const evidenceTx = dispute.submitEvidence('ipfs://QmYourEvidenceDocument');
console.log(evidenceTx.preview);

await signer.sendTransaction({
  to: evidenceTx.to,
  data: evidenceTx.data,
  value: BigInt(evidenceTx.value),
});

Read Evidence Timeline

const timeline = await dispute.getEvidenceTimeline(0, 'latest');

for (const event of timeline) {
  console.log(event.submittedAt, event.party, event.evidenceUri);
}

Appeal

const [appealFeeWei, appealPeriod] = await Promise.all([
  dispute.appealCost(),
  dispute.appealPeriod(),
]);

if (appealPeriod.end === 0n) {
  throw new Error('No appeal window is currently open');
}

const appealTx = dispute.appeal('0x', appealFeeWei);
await signer.sendTransaction({
  to: appealTx.to,
  data: appealTx.data,
  value: BigInt(appealTx.value),
});

Arbitrator Extra Data

Kleros uses extraData to select the court and minimum juror count.

import {
  buildArbitratorExtraData,
  parseArbitratorExtraData,
  extraData,
} from '@rakelabs/disputes-sdk';

const encoded = buildArbitratorExtraData(0, 3);
const generalCourt = extraData.generalCourt();
const decoded = parseArbitratorExtraData(encoded);

console.log(generalCourt, decoded.subcourtId, decoded.minJurors);

Errors

The core SDK does not inspect wallet/provider exceptions. Your ethers or viem integration should extract revert data and pass it to its ABI codec.

import { decodeEthersError } from '@rakelabs/ethers-adapter';

try {
  await signer.sendTransaction({
    to: tx.to,
    data: tx.data,
    value: BigInt(tx.value),
  });
} catch (err) {
  const decoded = decodeEthersError(err, codec);
  if (decoded) {
    console.error(decoded.name, decoded.args);
  }
}

Documentation

This README and the linked guides describe the unreleased 0.2.0 API until that version is tagged. For 0.1.x usage, open the matching Git release tag.

Document	Use it for
docs/reference.md	API reference, types, actions, events, and common mistakes
docs/advanced.md	Reader, transaction builder, multicall, and implementation selection
docs/migration-0.1-to-0.2.md	Migrate from provider-based initialization
docs/on-chain.md	Contract-level behavior and event model

Safety Notes

• Always show tx.preview before requesting a signature.
• Store the dispute contract address after creation; it is the canonical on-chain handle.
• Publish durable MetaEvidence and Evidence URIs before submitting them on-chain.
• Check chain IDs, court parameters, ruling options, and contract addresses before sending transactions.
• This software interacts with autonomous contracts. Users transact at their own risk.