Kleros v2

---

Deployments

⛓️ Contracts addresses

🗃️ Subgraph endpoints

⚖️ Web frontend

Content

Package	Description
bots	Automation of the on-chain upkeep of the smart contracts. Anyone willing to spend some gas may run these bots and contribute to the upkeep operations.
contracts	Smart contracts of the arbitration protocol.
kleros-app	Library of React hooks and utilities shared by the Kleros frontend apps.
kleros-sdk	SDK which facilitates the creation of arbitrable applications, the interactions with the arbitrator, the rendering of the dispute and evidence information.
subgraph	The indexing layer.
web	The court frontend intended for the jurors and parties in a dispute.

Contributing

Prerequisites

• Install NodeJS 16:
  • on Red Hat Linux: sudo dnf module install nodejs:16
  • on Ubuntu Linux: sudo snap install node --classic
  • on MacOS via brew: brew install node
• Install Yarn v1.22: npm install -g yarn
  • Then upgrade Yarn to v3: yarn set version berry
• Install Volta.sh: curl https://get.volta.sh | bash
• Install Docker Desktop to run the local graph node.
• Shell utilities: jq, yq
  • on Red Hat Linux: sudo dnf install jq yq
  • on Ubuntu Linux: sudo snap install jq yq
  • on MacOS via brew: brew install jq yq

Install the dependencies

$ yarn install

# Foundry libraries
$ git submodule update --init --recursive -j 4

Hardhat CLI auto-completion (optional)

$ npm i -g hardhat-shorthand

$ hardhat-completion install
✔ Which Shell do you use ? · bash
✔ We will install completion to ~/.bashrc, is it ok ? (y/N) · true

$ exec bash

Full Stack Local Deployment

Run the commands below from the top-level folder. Alternatively, it is possible to cd into the relevant package first and then call yarn without workspace @kleros/xxxx.

Shortcut using tmux

Requires tmux, Docker, curl, jq, and lsof.

scripts/run-local-stack.sh orchestrates the full stack: preflight clean -> contract build -> Hardhat node (deploy) -> graph-node (tmux panes) -> populate -> viem generate -> subgraph deploy -> web. Logs go to a temp dir printed at start.

yarn local-stack                    # start (default: clean preflight, then attach tmux)
yarn stop-local-stack               # kill tmux, stop graph-node, free :8545
yarn rebuild-local-stack            # stop + full clean + start

yarn local-stack --pin <tag|commit> # pin contracts first (see contracts/README.md)

Detach tmux: Ctrl+b then d. Stop everything: yarn stop-local-stack.

Env	Default	Purpose
LOCAL_STACK_SKIP_CLEAN=1	off	Skip wiping deployments / graph data on start
LOCAL_STACK_TIMEOUT=600	600	Seconds per readiness wait (RPC, deploy, subgraph sync)

Manual step-by-step (separate shells) is below if you prefer not to use the shortcut.

Shell 1 - Local RPC with Contracts Deployed

$ yarn workspace @kleros/kleros-v2-contracts start-local
...
Started HTTP and WebSocket JSON-RPC server at http://127.0.0.1:8545/

⏳ Wait until deployment is complete.

In a new terminal run:

$ yarn workspace @kleros/kleros-v2-contracts populate:local

This will populate the courts local by pulling devnet courts.

Note: Whenever contracts are redeployed or their ABIs change, you must regenerate the typed wagmi/viem contract bindings used by the frontend.

yarn workspace @kleros/kleros-v2-contracts viem:generate-hardhat

Shell 2 - Local Graph Node

Requires Docker desktop to be installed and running

$ yarn workspace @kleros/kleros-v2-subgraph start-local-indexer
...
graph-node-graph-node-1  | INFO Successfully connected to IPFS node at: http://ipfs:5001/
graph-node-graph-node-1  | INFO Pool successfully connected to Postgres, pool: main, shard: primary, component: Store
...
graph-node-graph-node-1  | INFO Connected to Ethereum, capabilities: archive, traces, network_version: 31337, provider: mainnet-rpc-0

⏳ Wait until the graph service is ready.

Shell 3 - Subgraph Rebuild and Local Deploy

⚠️ This step modifies subgraph.yaml and creates a backup file. See further down on how to restore it.

$ yarn workspace @kleros/kleros-v2-subgraph rebuild-deploy:local
...
✔ Upload subgraph to IPFS

Build completed: QmZVaZQ9qcXPia9YnFEKk7D1dEDHbfyDiJi1sqJ6E1NydB

Deployed to http://localhost:8000/subgraphs/name/kleros/kleros-v2-core-local/graphql

Subgraph endpoints:
Queries (HTTP):     http://localhost:8000/subgraphs/name/kleros/kleros-v2-core-local

Shell 4 - Frontend Pointing to the Local Subgraph

Note: If not already built, or on any change, build kleros-app first.

yarn workspace @kleros/kleros-app build

$ yarn workspace @kleros/kleros-v2-web start-local
✔ Parse Configuration
✔ Generate outputs
✔ Validating plugins
✔ Resolving contracts
✔ Running plugins
✔ Writing to src/hooks/contracts/generated.ts
Server running at http://localhost:1234
✨ Built in 2.35s

Redeploying

# Contracts
$ yarn workspace @kleros/kleros-v2-contracts deploy-local

# If contracts were updated
$ yarn workspace @kleros/kleros-v2-contracts viem:generate-hardhat

# Subgraph
$ yarn workspace @kleros/kleros-v2-subgraph rebuild-deploy:local

# If contracts were updated, restart web server to regenerate the wagmi hooks
$ yarn workspace @kleros/kleros-v2-web start-local

Simulating Arbitration Activity

$ yarn workspace @kleros/kleros-v2-contracts simulate-local

Stopping

Just press Ctrl + c in each terminal.

Docker containers and data removal

yarn workspace @kleros/kleros-v2-subgraph stop-local-indexer

Restoring subgraph.yaml

From a backup file

Every versions were saved as subgraph.yaml.bak.<timestamp>.

Based on the ArbitrumSepolia deployment artifacts

yarn workspace @kleros/kleros-v2-subgraph update

Based on the last commit

git restore subgraph.yaml

Run a local Blockscout explorer to inspect transactions on hardhat (Optional)

Make sure hardhat node is running.

Step 1 - Clone blockscout repo

git clone https://github.com/blockscout/blockscout.git

Step 2: Start the Docker compose stack

docker-compose -f hardhat-network.yml up -d

This should run a Blockscout locally at http://localhost.