kleros-ipfs-upload

# Kleros IPFS Upload (x402)

Upload Kleros-ecosystem files to IPFS via `https://kleros-ipfs-gateway.fly.dev/upload-to-ipfs`, an x402-protected gateway that charges $0.01 USDC per upload on Base mainnet. The returned IPFS CID is content-addressable and dereferenceable through any IPFS gateway, and indexed by Kleros's Graph Node for subgraph discoverability.

The gateway is a thin reverse-proxy in front of a Filebase-backed pinning service operated by Kleros. Every upload is pinned to Filebase indefinitely as long as Kleros runs the gateway — a reasonable assumption for artifacts the Kleros ecosystem itself depends on (the team has a strong incentive to keep this live), but **not** a substitute for a general-purpose pinning provider if the content is unrelated to Kleros.

## When to use this skill

Trigger this skill when the user is uploading **Kleros-ecosystem content**:

- Dispute **evidence** attachments — screenshots, documents, contracts, transcripts.
- **Meta-evidence** JSON — the policy/spec referenced by a court or arbitrator smart contract at dispute creation.
- **Court / dispute / arbitrator policies** — JSON describing rules, fees, juror counts, appeal mechanics.
- **Kleros Curate item metadata** — JSON for items submitted to a Curate list (e.g. tokens, badges).
- **Juror / arbitrator justifications** — rulings, dissents, deliberation rationale.
- Any artifact whose CID will end up in a Kleros smart contract event, transaction, or subgraph.
- The user explicitly names this gateway (`kleros-ipfs-gateway.fly.dev` etc.) or this skill.
- The user is asking the agent to **test, validate, or sanity-check** this gateway or this skill itself (e.g. "smoke-test the Kleros IPFS gateway" / "verify pay-and-upload works"). A deliberate end-to-end test is a legitimate trigger even if no Kleros artifact is being uploaded for real use.

## When NOT to use this skill

- Generic "store this file on IPFS" / "get me a CID for X" requests with no Kleros relevance. **Use Pinata, web3.storage, Filebase directly, or any other general pinning provider.** This gateway charges per upload — that's wasteful if the user only needs a CID and doesn't benefit from Kleros's pinning durability or subgraph integration.
- Anything resembling personal cloud storage, NFT metadata for non-Kleros projects, software releases, large media archives, or backup data.
- Content explicitly bound to a non-Kleros ecosystem (e.g. another DAO's snapshot, another marketplace's metadata) — even if the format happens to look like a Kleros artifact.

You are free to *upload* whatever the user wants (they're paying), but absent a Kleros connection there's no reason to prefer this skill over a general-purpose alternative.

## Quickstart

Two paths depending on what your agent already has:

- **If you already have x402 tooling** (an x402 skill / SDK / a model that knows `x402-fetch`): skip the bundled scripts and inline the snippet further down — the gateway is a plain `POST /upload-to-ipfs` behind a standard x402 paywall, nothing Kleros-specific in the payment flow.
- **Otherwise**, run the bundled `scripts/pay-and-upload.ts` end-to-end — it exists so x402-unaware agents don't have to rediscover the flow:

```bash
cd path/to/this-skill/scripts
npm install
EVM_PRIVATE_KEY=0xYourPayerKey npx tsx pay-and-upload.ts /path/to/file.json
```

`npm install` creates a `package-lock.json` and a `node_modules/` in the scripts dir — both are fine to leave in place or delete after use; not committed to the skill on purpose so dep versions stay fresh.

On success the script prints every CID reported by the gateway, one per line (so you can capture the normal
single CID with `$(npx tsx pay-and-upload.ts ...)`). The array-shaped response is legacy API structure, not
batch-upload support. On failure the script exits non-zero and logs the gateway's error body to stderr.

Defaults: `OPERATION=evidence`, `GATEWAY_URL=https://kleros-ipfs-gateway.fly.dev`. Override `OPERATION` with an env var; see the "Request shape" section for valid values.

## One file per paid upload; reuse identical files

Each paid request must contain exactly one multipart part named `file`. Never append multiple `file` parts or
batch different files into one request. If two files have different content, make two separate paid uploads —
one request and one payment per file. This applies even when the files belong to the same Curate or dispute
workflow.

IPFS CIDs are content-addressed. If the same byte-for-byte file is needed in multiple places, upload it once
and reuse the returned CID everywhere. Do not make a second paid upload for the same policy PDF, logo image,
evidence display interface, or other identical file just because multiple Kleros artifacts reference it.

For multi-artifact jobs, keep a small artifact map before submitting transactions:

- `policy.pdf` -> `/ipfs/<CID>`
- `logo.png` -> `/ipfs/<CID>`
- `registrationMetaEvidence.json` -> `/ipfs/<CID>`
- `clearingMetaEvidence.json` -> `/ipfs/<CID>`
- `evidenceDisplayInterface` -> `/ipfs/<CID>/index.html`

When a shared policy, logo, or evidence display interface is referenced by both registration and clearing
MetaEvidence JSON, put the same CID in both JSON files. Reuse CIDs only for exact same files. If a file
changes by even one byte, make a separate paid upload for each distinct file and label each CID clearly.
Registration and clearing MetaEvidence JSON are therefore separate uploads whenever their JSON bytes differ,
even when both reference the same reusable policy, logo, or evidence display interface CIDs.

If you're writing your own client inside an existing Node project, the core is small enough to inline:

```ts
import { wrapFetchWithPayment, createSigner } from "x402-fetch";

const operation = process.env.OPERATION ?? "evidence";

const signer = await createSigner("base", privateKey);
const fetchWithPay = wrapFetchWithPayment(fetch, signer);

const form = new FormData();
form.append("file", new Blob([bytes]), "e