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 key | The defender's or the challenger's wallet. Only that key can play that side's turns. |
| Its own run | A run of the receipt's model on the receipt's input and seed. Every move is computed from it. |
| To move inside each deadline | A side that does not move in time loses its bond for this receipt. |
| Nothing for the last step | When 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.
| Part | Shows |
|---|---|
| The line at the top | Where 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 interval | How 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. |
| Bonds | Each side's bond while the game runs. After it, where the loser's bond went, row by row. |
| The step, executed on chain | After 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. |
| Transactions | Every challenge, bisect, prove_step and claim_timeout of the dispute, with its signature. |
Playing a turn on the page
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."
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.
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.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.
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_stepwithin seconds. The program executes the step, pays the bonds by its result, and the page shows the dispute resolved.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_timeoutand 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:
| From | Where |
|---|---|
| The page | The countdown in the turn panel and "deadline" with its time in UTC, and the time left in the line at the top. |
| HTTP | turnDeadline of GET /v1/disputes/:address, with turn naming the side. |
| SDK | deadline of laplace.dispute(address), in unix seconds, with turn. |
| Sent | Result |
|---|---|
bisect after the deadline | Refused with TurnExpired (6020). |
claim_timeout before the deadline has passed | Refused with TurnOpen (6021). |
claim_timeout after it | The 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.
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:
kind | Other fields | Means |
|---|---|---|
bisect | select, lo, hi, points | It 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. |
prove | step | One step is left. The network's keeper proves it, and any key may: proveStep sends it from a server key. |
claim-timeout | The other side is on turn and its deadline has passed. | |
wait | The other side is on turn and inside its deadline. Also returned for a key that is not a side. | |
resolved | The dispute is over. |
playTurn
laplace.playTurn(dispute, run) computes the move and sends it with the wallet:
| The move | Sends | Resolves to |
|---|---|---|
bisect | bisect, a v0 transaction | { kind: 'bisect', signature, lo, hi } |
prove | Nothing: the keeper proves the step | { kind: 'proving', step } |
claim-timeout | claim_timeout | { kind: 'claim-timeout', signature } |
wait, resolved | Nothing | { 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:
const signature = await laplace.claimTimeout(dispute)Errors
Each call throws LaplaceError on failure, with the program's refusal in programError:
| Name | Code | When |
|---|---|---|
NotYourTurn | 6019 | bisect from a key that is not the side on turn. |
TurnExpired | 6020 | bisect after the turn's deadline. |
TurnOpen | 6021 | claim_timeout before the deadline has passed. |
BadProof | 6022 | proveStep or a hand-built prove_step with a payload that does not check against the dispute's roots. |
BadStep | 6023 | proveStep or a hand-built prove_step with a payload built for a step other than the dispute's lo. |
WrongState | 6010 | bisect 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, SelectOutOfRange | 6017, 6018 | A 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.
laplace key import ./side-keypair.json
laplace watch --models judge,marketSo 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.
| Result | The challenger | The defender | The receipt |
|---|---|---|---|
| The challenger wins | Receives 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 wins | Loses 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:
| Ending | Winner |
|---|---|
prove_step, and the step leads to the claimed state | The side that claimed it. |
prove_step, and the step leads to another state | The other side. |
claim_timeout | The 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.