Watchers

Playing the game

Each turn, its deadline, the final step, and what happens to both bonds.

This is the guide for a side in a dispute: the defender whose answer was challenged, or the challenger. It follows the dispute's page turn by turn, then the same moves with the SDK, then a node playing them, and ends with what each result pays. The rules behind the moves are on The challenge game.

What a side needs

Its keyThe defender's or the challenger's wallet. Only that key can play that side's turns.
Its own runA run of the receipt's model on the receipt's input and seed. Every move is computed from it.
To move inside each deadlineA side that does not move in time loses its bond for this receipt.
Nothing for the last stepWhen one step is left, the network's keeper proves it on chain. Neither side signs anything for it.

The dispute's page

/disputes/<address> is reached from the receipt ("Open the dispute") or directly after challenging. It updates as each turn lands.

PartShows
The line at the topWhere the game stands: "In play" with who is on turn and the time left, "One step left" with the step's number that the keeper executes on chain, or "Resolved for the" winner, by step or by timeout.
The two claims"Operator" for the defender and "Watcher" for the challenger: each side's output, trace root and key. After the end, "won" and "lost its bond".
The intervalHow many steps are still disputed out of the model's count, and one row per turn: "Turn 1 · the watcher splits", then the part the next side kept, down to "One step".
The turn panel"Your turn" or the other side's, then "The last step" once one step is left; the turn's number, the countdown and the deadline in UTC, and the button for the move.
BondsEach side's bond while the game runs. After it, where the loser's bond went, row by row.
The step, executed on chainAfter a proven step: its number, operator and layer, the state leaves it read, and the root the program computed beside the root that was claimed.
TransactionsEvery challenge, bisect, prove_step and claim_timeout of the dispute, with its signature.

Playing a turn on the page

  1. Connect the side's wallet

    Without a wallet the turn panel shows Connect wallet. With a wallet that is neither side it reads "This wallet is not a side of this game." With the right wallet and the other side on turn it reads "Waiting for the other side to move."

  2. Have the run in this tab

    The page takes the move from the run made on the receipt's page in the same tab. If there is none, the panel shows "Run it again first", which opens the receipt and starts the run. When it has finished, come back to the dispute with the "Open the dispute" button on the receipt.

  3. Press Play turn

    On your turn the panel is titled "Your turn" and shows Play turn. The page computes the move from your run: the first part of the other side's points you disagree with, and your own states inside it. One signature sends it as a bisect. The stages Building, Signing, Sent, Confirmed appear under the button, and the interval gains a row.

  4. Wait for the other side

    The panel changes to the other side's turn with its own countdown. The page updates by itself when their move lands.

  5. The last step

    When one step is left the line at the top reads "One step left" with the step's number, and the panel is titled "The last step". There is nothing to sign on either side: the network's keeper builds the step's inputs and Merkle proofs and sends prove_step within seconds. The program executes the step, pays the bonds by its result, and the page shows the dispute resolved.

  6. Claim a timeout

    When the side on turn has let its deadline pass, the panel shows "deadline passed" and Claim timeout for any connected wallet. One signature sends claim_timeout and the side that missed its turn loses.

Keeping the run available

The run is held in the tab's memory and nowhere else. Moving between the receipt and the dispute inside the app keeps it. Reloading the page or closing the tab drops it, and the turn panel then shows "Run it again first". A run of the same model on the same input and seed gives the same roots, so running again restores exactly what was lost. It takes as long as the first run did, which counts against the turn's deadline.

The turn deadline

Each turn has to land within turn_deadline_secs of the Config account after the previous one. The deadline of the current turn is:

FromWhere
The pageThe countdown in the turn panel and "deadline" with its time in UTC, and the time left in the line at the top.
HTTPturnDeadline of GET /v1/disputes/:address, with turn naming the side.
SDKdeadline of laplace.dispute(address), in unix seconds, with turn.
SentResult
bisect after the deadlineRefused with TurnExpired (6020).
claim_timeout before the deadline has passedRefused with TurnOpen (6021).
claim_timeout after itThe side on turn loses, exactly as if a step had proven it wrong.

Anyone can send claim_timeout, and the network itself sends it for a timeout nobody claims. With one step left, the turn belongs to the side whose claimed state follows the step, and the keeper's proof lands well inside that deadline. The program's result is the same whoever sends the proof.

The same with the SDK

laplace.nextMove reads the dispute and computes this side's move from its run. laplace.playTurn computes it and sends it. At the last step there is nothing to send: the loop waits until the keeper's proof resolves the dispute.

TypeScript
import { createLaplace } from '@laplace/sdk'

const laplace = createLaplace({ rpcUrl, apiUrl, wallet })

const d = await laplace.dispute(dispute)
const { run } = await laplace.rerun(d.receipt)

for (;;) {
  const move = await laplace.nextMove(dispute, run)
  if (move.kind === 'resolved') break
  if (move.kind === 'wait' || move.kind === 'prove') {
    await new Promise((r) => setTimeout(r, 2000)) // at 'prove', the keeper proves the step
    continue
  }
  const sent = await laplace.playTurn(dispute, run) // bisect or claim-timeout
  console.log(sent.kind, 'signature' in sent ? sent.signature : '')
}

const { winner, resolvedBy } = await laplace.dispute(dispute)
console.log(winner, resolvedBy)

rpcUrl and apiUrl are the network's addresses (Addresses), wallet is the side's signer and dispute is the dispute's address. A side that already holds its run, from laplace.rerun before challenging, passes that one.

nextMove

laplace.nextMove(dispute, run, signer?) sends nothing. signer defaults to the wallet's key. It returns one of:

kindOther fieldsMeans
bisectselect, lo, hi, pointsIt is this side's turn. select is the part of the other side's points it disagrees with first, [lo, hi] that part, points its own state roots inside it.
provestepOne step is left. The network's keeper proves it, and any key may: proveStep sends it from a server key.
claim-timeoutThe other side is on turn and its deadline has passed.
waitThe other side is on turn and inside its deadline. Also returned for a key that is not a side.
resolvedThe dispute is over.

playTurn

laplace.playTurn(dispute, run) computes the move and sends it with the wallet:

The moveSendsResolves to
bisectbisect, a v0 transaction{ kind: 'bisect', signature, lo, hi }
proveNothing: the keeper proves the step{ kind: 'proving', step }
claim-timeoutclaim_timeout{ kind: 'claim-timeout', signature }
wait, resolvedNothing{ kind }

Every move playTurn sends is a v0 transaction, so a browser wallet's signTransaction is all the game asks of it.

claimTimeout

laplace.claimTimeout(dispute) sends claim_timeout from any wallet, a side's or not, and resolves to the signature:

TypeScript
const signature = await laplace.claimTimeout(dispute)

Errors

Each call throws LaplaceError on failure, with the program's refusal in programError:

NameCodeWhen
NotYourTurn6019bisect from a key that is not the side on turn.
TurnExpired6020bisect after the turn's deadline.
TurnOpen6021claim_timeout before the deadline has passed.
BadProof6022proveStep or a hand-built prove_step with a payload that does not check against the dispute's roots.
BadStep6023proveStep or a hand-built prove_step with a payload built for a step other than the dispute's lo.
WrongState6010bisect once one step is left, prove_step before that, or any move on a resolved dispute. The second of two proofs for the same step ends here.
PointCount, SelectOutOfRange6017, 6018A hand-built bisect with the wrong number of points or a select beyond the parts. nextMove computes both.

Letting a node play

A node started with the side's key plays every turn by itself. laplace serve and laplace watch both do it, in a loop of their own beside their answers or re-runs: every second the node reads the disputes its key is a side of, runs the receipt's input again if it does not hold the run, and sends its next move, timeouts included. At the last step the node proves the step itself, beside the keeper.

Shell
laplace key import ./side-keypair.json
laplace watch --models judge,market

So a challenge opened from the browser can be handed to a node: import the wallet's keypair into the CLI's key file and start laplace watch. The node picks the dispute up within a second, whichever model it is on. Run a watcher and Run a node cover running one as a service.

What each ending pays

The dispute ends by a proven step or by a claimed timeout, and both pay the same way. The loser's whole bond for this receipt leaves the vault in that instruction: slash_winner_bps of it to the winner's wallet, rounded down, and the rest to the protocol's fee recipient. The current value is protocol.slashWinnerBps of GET /v1/network.

ResultThe challengerThe defenderThe receipt
The challenger winsReceives the winner's part of the defender's bond in its wallet. Its own bond stays locked behind its answer, and returns to its wallet at finalize together with the receipt's fee less the protocol share.Loses the bond behind this answer. For an operator it leaves bond_locked and disputes_lost rises by one.answered, with the challenger's output and trace root, the challenger as answerer, and a fresh full window.
The defender winsLoses the bond it posted with the challenge.Receives the winner's part of the challenger's bond in its wallet. Its own bond stays locked behind the answer and unlocks at finalize, when the fee is paid to it. For an operator disputes_won rises by one.answered, with the same answer. Its window resumes with the time it had left when the challenge landed.

How the winner is decided:

EndingWinner
prove_step, and the step leads to the claimed stateThe side that claimed it.
prove_step, and the step leads to another stateThe other side.
claim_timeoutThe side that was not on turn.

After the end the page's Bonds panel lists each movement ("To the winner", "To the protocol") with its key and amount, and GET /v1/disputes/:address returns them as result.moves. A lost bond describes the split.

A receipt that came back to answered can be challenged again inside its window, and the challenger whose answer now stands is the defender of that dispute.