Escrow: holding players' items for your game

Some games need to put a player's items at stake: a duel for each other's gear, a dungeon where what you carry can be lost, a tournament buy-in. An NFT or a token in somebody's wallet cannot be taken without their signature, so a game that wants items to change hands by its rules has the player put them in an escrow first.

An escrow is an address on the chain that holds a player's NFTs and tokens for one game:

While the game is on, the game's referee (an arcade node your game names, the same kind that pays prize pools) moves items out of it, to the player or to somebody else, and only when your game's judge says so.
After the unlock time your game chose, the player alone can take everything back from their wallet, whatever the game or its referee says, even if the referee has vanished.

The arcade does not know your game's rules. Whether a duel was won, whether a dropped item was picked up, who gets what: your judge decides. The escrow only holds and moves.

Setting it up: the game's JSON

Name a referee and a judge in your game inscription's JSON, next to game:

{
  "game": {"name": "My Game"},
  "escrow": {
    "referee": {"pubkey": "02…", "node": "https://…"},
    "judge": "<the inscription id of your judge>",
    "params": {"anything": "your judge reads"},
    "unlock_hours": 24
  }
}

Field	What it is
`referee.pubkey`	the referee node's key, from its `/r/referee`
`referee.node`	where that node is, if it is not the arcade the player uses
`judge`	your judge: a JavaScript inscription (see The referee)
`params`	handed to your judge on every decision
`unlock_hours`	the longest an escrow can stay locked: 1 to 720 hours

The judge

The same kind of judge a refereed prize pool uses: judge(seed, inputs, params), in a sandbox with no network, no clock and no randomness. For an escrow it is asked one question, may these items go to this address?, and answers:

function judge(seed, inputs, params) {
  // params.escrow: {address, owner, unlock, game, inscriptions, tokens}
  // params.to:     the address asking to receive them
  // params.items:  what it asks for
  // inputs:        whatever the page sent as `replay` (your game's evidence)
  if (provesTheWin(inputs, params)) return {release: true};
  return {release: false, why: "that duel was not won"};
}

release: true moves the items; anything else refuses them and shows why. A judge may also return to, which must match the address asked for. The seed is the escrow's address.

The page: `arcade.escrow`

<script src="/r/escrow.js"></script>
<script>
arcade.escrow.open({hours: 6}).then(function (e) {
  // e: {escrow, owner, owner_pubkey, unlock, referee, game}
  return arcade.escrow.deposit(e.escrow, [{inscription: swordTxid},
                                          {token: 26, amount: '50'}]);
});
</script>

Call	What it does
`open({hours})`	this player's escrow in this game; unlocks on the hour, no later than `unlock_hours`. Sends nothing
`deposit(escrow, items)`	puts things in: one card for all of them, then one transaction each
`status(escrow)`	`{inscriptions, tokens, coins, owner, unlock, open}`
`release({escrow, owner, owner_pubkey, unlock, to, items, replay, coins})`	asks the referee; your judge decides
`mine()`	this player's escrows in this game that still hold something

An item is {inscription: id} or {token: id, amount: "50"}.

Only signed-in players can open or deposit, and each deposit is confirmed on a card in their own viewer and signed in their own browser.
Anybody may ask for a release (the winner of a duel, say); the judge decides. A release needs the escrow's facts that open returned (escrow, owner, owner_pubkey, unlock), so share them with the other players your own way, for example over arcade.realtime. When the referee is a different node, pass coins from status too.
Each item moves in its own transaction, so a release of three things is three transactions, in the next block.

What players can always count on

They put things in themselves. Nothing enters an escrow without the player's own signature, and the card says until when.
Before the unlock time, items leave only by your judge's decision, signed by the referee your game named. Players trust that referee, as they trust a prize pool's.
After the unlock time, the wallet page shows Held in escrow with a Take back button, and one press brings everything home. No game, judge or referee is involved; the chain enforces the time.

Costs