fixup! docs: add readme

permissionless-arbitration/lua_node/README.md

@@ -1,13 +1,34 @@
 # Dave Lua node
 
-The Lua node is used for testing and prototyping only.
+This directory contains a prototype node written in Lua.
+The purpose of this Lua node is testing and prototyping only; the real production node is written in Rust.
+Furthermore, this node implements only compute (_i.e._ a one-shot computation, like a rollups with no inputs).
+
+Remember to either clone the repository with the flag `--recurse-submodules`, or run `git submodule update --recursive --init` after cloning.
+You need a docker installation to run the Dave Lua node.
 
 ## Run example
 
-Remember to either clone the repository with the flag `--recurse-submodules`, or run `git submodule update --recursive --init` after cloning.
 
-You need a docker installation to run the Dave Lua node.
-From the path `permissionless-arbitration/lua_node`, run the following command:
+This directory also has an example verification tournament, in which players compete against each other one at a time to prove the correct result of a computation.
+The computation binary is specified in the [`program`](program) directory.
+From this binary, the example program first generates a Cartesi Machine image, which fully specifies a computation.
+Then, it creates a local blockchain and deploys all the Dave smart contracts to it.
+Finally, it spawns multiple players to fight each other.
+
+Note that there may only be one instance of each claim (_i.e._ no duplicates).
+Players that are defending the same claim will join teams.
+These players come in multiple flavours:
+* The honest player is one that uses the honest strategy and defends the correct claim.
+The honest players will always emerge victorious.
+There may be multiple honest players; they'll help each other defending the correct claim.
+* One kind of dishonest player uses the honest strategy, but defends an incorrect claim.
+These dishonest players will always lose a match against the correct claim.
+* Another kind of dishonest player — called the _idle_ player — posts a claim, but never interacts with the blockchain again.
+If no other player is actively defending this claim, it will lose by timeout.
+
+To add more players of different kinds, you can edit the [`entrypoint.lua`](entrypoint.lua) file.
+To run the full example, execute the following command from this path (_i.e._ `permissionless-arbitration/lua_node`):
 
 ```
 docker build -t dave:latest -f Dockerfile ../../ && docker run --rm dave:latest

permissionless-arbitration/lua_node/program/README.md

@@ -2,28 +2,28 @@
 
 ## Generate programs
 
-```
-cd program
-```
+From this directory, run the following:
 
 ```
-docker run --platform linux/amd64 -it --rm -h playground \
+docker run --platform linux/amd64 -it --rm -h gen-program \
           -e USER=$(id -u -n) \
           -e GROUP=$(id -g -n) \
           -e UID=$(id -u) \
           -e GID=$(id -g) \
           -v (pwd):/home/$(id -u -n) \
           -w /home/$(id -u -n) \
-          diegonehab/playground:develop /bin/bash -c "./gen_machine_linux.sh"
+          cartesi/machine-emulator:0.15.2 /bin/bash -c "./gen_machine_simple.sh"
 ```
 
+Or
+
 ```
-docker run --platform linux/amd64 -it --rm -h playground \
+docker run --platform linux/amd64 -it --rm -h gen-program \
           -e USER=$(id -u -n) \
           -e GROUP=$(id -g -n) \
           -e UID=$(id -u) \
           -e GID=$(id -g) \
           -v (pwd):/home/$(id -u -n) \
           -w /home/$(id -u -n) \
-          diegonehab/playground:develop /bin/bash -c "./gen_machine_simple.sh"
+          cartesi/machine-emulator:0.15.2 /bin/bash -c "./gen_machine_linux.sh"
 ```