When two strangers trade over the internet, the hardest part is not the transaction — it is what happens when things go wrong. Traditional crypto escrow services solve this by holding your funds in their own wallet, asking you to trust that they will adjudicate fairly. Kaspa Escrow takes a different path: funds sit in an on-chain covenant, and the dispute resolution layer — an E2E chat, an AI forensics engine, and a human arbiter — works entirely around that contract without ever touching the keys.
This article walks through the off-chain coordination that makes disputes work: how private conversations stay private until a dispute is filed, how an AI reads the evidence and renders a recommendation, and how a human arbiter produces the only signature that can move funds in a contested deal.
The On-Chain Foundation
Before diving into the off-chain flow, it helps to understand what the contract enforces. The Kaspa Escrow contract (escrow.sil) defines ten spending paths. The ones relevant to disputes are:
dispute(buyerSig)— transitions the UTXO fromACTIVEtoDISPUTED, resetting its age and starting the arbiter deadline timer.arbitrateToBuyer(arbSig),arbitrateToSeller(arbSig),arbitrateSplit(arbSig)— three paths the human arbiter can sign, each paying only to buyer, seller, or both (each split output must be at least 1 KAS).timeoutToBuyer()/timeoutToSeller()— keyless paths that activate when the arbiter deadline expires, ensuring funds escape even if every off-chain actor disappears.
The critical invariant: no path in the contract can pay anyone outside {buyer, seller, feeSpk}. The arbiter physically cannot redirect funds elsewhere. This is not a promise — it is a script enforced by every Kaspa node.
Five Stages of a Dispute
Stage 1 — Claims
When the buyer opens a dispute, both parties submit a structured statement: refund, release, or split (with a proposed ratio). Each statement is authenticated by the party's deal token. The server records it, but the on-chain UTXO does not change yet. The buyer's dispute transaction moves the covenant into DISPUTED mode, resetting the UTXO age and starting the arbiter deadline.
Dispute window — a period set at deal creation (24–168 DAA hours depending on template) during which the buyer can file a dispute. If no dispute is filed, the seller can claim funds via autoRelease. The arbiter deadline is a longer window (72–240 hours) that starts when a dispute is filed; if it expires without resolution, the contract's timeout path pays out automatically.
The window presets are whitelisted server-side: goods deals default to 72-hour dispute / 168-hour arbiter; OTC deals use 24/72; services use 120/240. Neither party can widen the window after funding. The time-like counting uses DAA score — you can read more about how DAA score governs temporal windows in the Kaspa knowledge base.
Stage 2 — Chat Key Reveal
This is the privacy boundary. Throughout the deal, both parties communicate using the Kasia protocol — each message is ECIES-encrypted (ECDH on secp256k1 + ChaCha20-Poly1305) and anchored in the BlockDAG as a transaction. The server relays ciphertexts; it never sees plaintext.
When a dispute is filed, each party must reveal their chat private key to the mediator. The server validates that the revealed key matches the party's chat public key — it explicitly rejects escrow funding keys, enforcing that chat and financial keys remain separate cryptographic identities. Once both keys are in server memory, the mediator can decrypt the full conversation thread.
Normal deal: Party A ──[ECIES ciphertext]──▶ Server ──▶ Party B
Server sees nothing.
Dispute filed: Party A reveals chat_sk ──▶ Server decrypts thread
Party B reveals chat_sk ──▶ Server decrypts thread
AI mediator reads plaintext, renders verdict.Media attachments follow the same pattern: each file is encrypted with a per-file key, uploaded as a blob, and described inside an E2E message. The mediator verifies SHA-256 hashes against on-chain anchors to detect tampering. The chat private key lives only in server memory — it is never persisted to disk or database.
Stage 3 — AI Forensics and Verdict
With the chat thread decrypted, two automated systems engage in sequence.
Media forensics (media_probe.rs) examines every attachment:
- Integrity checks: SHA-256 hash vs. on-chain anchor, magic-byte verification, EXIF extraction for images.
- Images: fed to a vision model for content classification.
- Video: extracted keyframes and audio track via ffmpeg/ffprobe.
- Documents: PDFs parsed via poppler.
- Goods tracking: S10 tracking number verification, Russian Post SOAP API lookup.
- OTC verification: for deals with a supported counter-leg (USDT on Tron/TON/ETH/BSC, USDC on multiple EVM chains, BTC, LTC), the system queries on-chain explorers to verify the claimed transaction ID. This is advisory only — a status badge visible to both parties, not a contract-enforced condition.
Temp files during forensics live only in RAM (/dev/shm), never persisted to disk.
The forensics report is structured into a prompt for the AI mediator (arbiter.rs). The mediator's behavioral instructions are embedded in the binary at compile time. It calls an OpenAI-compatible endpoint (production: xiaomi/mimo-v2.5-pro via OpenRouter, temperature 0, strict JSON output) with the full transcript, evidence, and party claims. The response is a structured verdict: recommendation (refund, release, or split), rationale, and confidence score.
The AI verdict is non-binding. It is a recommendation that both parties see. Neither the on-chain contract nor the server acts on it automatically.
Stage 4 — Acceptance
If both parties agree with the AI verdict, or if the losing party concedes, the resolution becomes a local browser operation. The conceding party signs a release or refund transaction in their browser — keys never leave the device. For a split, both parties produce partial signatures that the server combines into a mutual transaction.
This is the optimistic path — no arbiter involvement, dispute fee only. The contract also supports an even simpler case: if the entire dispute window expires without any dispute being filed, the autoRelease keyless path pays the seller automatically. The server's watcher broadcasts this transaction.
Stage 5 — Human Arbitration
If neither party accepts the AI verdict within the configured window (default 24 hours), the system escalates to the human arbiter. The arbiter accesses a dedicated web panel behind two-factor authentication (nginx basic auth plus either a signed Telegram initData or an admin token).
The panel shows the full timeline: both claims, the decrypted chat thread with on-chain message anchors, the AI verdict with its rationale, all forensics evidence, and OTC verification status. The arbiter renders a binding decision by signing one of three transactions locally in the browser:
arbitrateToBuyer(arbSig) → 100% to buyer
arbitrateToSeller(arbSig) → 100% to seller
arbitrateSplit(arbSig) → custom ratio, each output ≥ 1 KASThe arbiter's private key is an offline 64-character hex string. It enters the browser only during signing and is erased immediately after. On the server, only the public key is stored. If the arbiter's key is lost, disputed deals resolve only through the contract-level timeout — which is exactly the safety net the system is designed around.
How Kaspa Forge Runs This in Production
The entire dispute stack runs inside a single Rust/axum process (port 8795) that also serves Kaspa Safe, marketplace listings, and deposit deals. Key modules:
dispute_api.rs— HTTP routes forclaim,reveal,escalate, state polling, and mutual-signature collection.arbiter.rs— AI mediator: reconstructs the transcript from revealed keys, calls the LLM, parses the structured JSON verdict.media_probe.rs— forensic engine handling images, video, documents, carrier tracking, and cross-chain OTC verification.watcher.rs::run_escrow— 10-second polling loop that handles auto-release after dispute windows, timeout payouts after arbiter deadlines, and pre-alerts to both parties at 50% and 90% of window expiry.
The arbiter also has a Telegram Mini App hub in a private bot for mobile-friendly case management. All notifications — Telegram, email, and web push — fan out from a single dispatch function. The escrow contract is compiled from escrow.sil into the WASM core at build time; transaction builders for all ten paths are reused by both the browser (via WASM) and the server (as an rlib). A self-test suite of 52 checks validates every spending path in the Kaspa VM.
Trade-offs and Honest Limitations
The AI verdict is advisory, not binding. This is deliberate: an LLM cannot be trusted with financial finality. The trade-off is speed — if both parties reject the AI recommendation, resolution depends on human availability.
Chat key reveal is all-or-nothing. Once a party reveals their chat key, the mediator sees the entire conversation history, not just messages relevant to the dispute. There is no selective disclosure in the current Kasia protocol. Parties should understand that filing a dispute means full transcript access by the mediator.
The arbiter is a single point of trust for disputed deals. The contract constrains the arbiter to paying only buyer or seller, but the judgment itself is subjective. The AI mediator mitigates this by providing a structured rationale displayed alongside the evidence, making reasoning auditable. Every decision is logged, including whether the arbiter agreed with the AI.
Timeout paths are fee-free by design. If the arbiter disappears, the contract ensures funds escape — but without the service fee. This is intentional: the service earns nothing from unresolved disputes, removing any incentive to delay resolution.
Forensics depth varies by deal template. Goods deals benefit from carrier tracking and photo analysis; OTC deals get on-chain counter-leg verification across 17 blockchain networks. Service and digital-goods deals rely more heavily on chat evidence, where the AI mediator's text analysis does the heavy lifting.
The dispute layer sits on top of a covenant that physically cannot pay anyone except buyer, seller, or the fee address — even the arbiter's key is constrained to those outputs. If you want to see how the on-chain contract enforces this, read how the vault and escrow contracts work. Or try Kaspa Escrow for a P2P deal where funds stay in the contract, not in a middleman's wallet.
FAQ
Can the AI mediator steal my funds?
No. The AI mediator produces a non-binding recommendation only. It has no signing key. Funds move only through on-chain covenant paths — buyer signature, seller signature, or human arbiter key — never through the AI.
What happens if neither party reveals their chat key?
The dispute stalls at the reveal stage. The on-chain arbiter deadline still ticks; once it expires, the covenant's timeout path pays out automatically (to buyer or seller, depending on the contract parameter set at deal creation), with no service fee.
Does revealing my chat key expose my escrow private key?
No. The chat key and the escrow funding key are separate cryptographic keys. The server explicitly rejects escrow keys during reveal. Revealing the chat key lets the mediator read the conversation, but gives no access to the escrow UTXO.
How does Kaspa Escrow prevent the arbiter from stealing funds?
The on-chain contract escrow.sil hard-codes that every spending path pays only to buyer, seller, or the service fee address. The arbiter can sign a split between buyer and seller — but cannot redirect funds to any third party, including themselves.
What is the difference between the AI verdict and the human arbiter decision?
The AI verdict is advisory — it recommends a resolution based on the chat transcript and evidence, but neither party is bound by it. The human arbiter's signed transaction is the only binding decision, enforced by the on-chain contract.
Put your KAS where theft can be cancelled
A covenant vault on Kaspa mainnet: your keys, your rules, our tooling. Free on-chain, forever.
Create a vault