From 40ddeb71bb2058a4a146d096b42dfd004f66009e Mon Sep 17 00:00:00 2001
From: Gabriel Coutinho de Paula <gcdepaula@protonmail.com>
Date: Sun, 24 Dec 2023 10:48:53 -0300
Subject: [PATCH] fixup! docs: add readme

---
 permissionless-arbitration/lua_node/README.md | 30 ++++++++++++++++---
 .../lua_node/program/README.md                | 14 ++++-----
 2 files changed, 33 insertions(+), 11 deletions(-)

diff --git a/permissionless-arbitration/lua_node/README.md b/permissionless-arbitration/lua_node/README.md
index 5f114033..4a71d7fa 100644
--- a/permissionless-arbitration/lua_node/README.md
+++ b/permissionless-arbitration/lua_node/README.md
@@ -1,13 +1,35 @@
 # 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 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 forces.
+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.
+Honest players never fight multiple matches at the same time.
+* 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 the current path path (_i.e._ [`permissionless-arbitration/lua_node`](.)):
 
 ```
 docker build -t dave:latest -f Dockerfile ../../ && docker run --rm dave:latest
diff --git a/permissionless-arbitration/lua_node/program/README.md b/permissionless-arbitration/lua_node/program/README.md
index 4f74431a..e630b696 100644
--- a/permissionless-arbitration/lua_node/program/README.md
+++ b/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"
 ```