docs: add readme

README.md

@@ -1,3 +1,81 @@
 # Dave
 
-A fraud-proof system.
+Dave is a permissionless, interactive fraud-proof system. This repo contains the Dave software suite, including support for both rollups and compute (_i.e._ a one-shot computation, like a rollup without inputs):
+
+* Solidity smart contracts;
+* off-chain testing node in Lua;
+* off-chain reference node in Rust;
+* dispute algorithm specification.
+
+
+## Running Dave
+
+This project uses git submodules.
+Remember to either clone the repository with the flag `--recurse-submodules`, or run `git submodule update --recursive --init` after cloning.
+
+To run the Lua node, follow the instructions [here](permissionless-arbitration/lua_node/README.md).
+
+
+## What's in a name
+
+Our fraud-proof system is called _Dave_.
+Just Dave.
+It's neither an acronym nor an abbreviation, but a name.
+Like most names, it should be written in lower case with an initial capital, that is, "Dave".
+
+Dave is permissionless.
+This means anyone can participate in the consensus.
+Since anyone can participate, there's the possibility of Sybil attacks, where an attacker can generate an army of fake personas and try to shift the consensus in their favour.
+
+Dave's security is one of N: a single honest validator can enforce the correct result.
+It doesn't matter if it's you against the world.
+If you're honest, Dave's got your back; you can fight a mountain of powerful, well-funded crooks and win, using a single laptop in a timely manner.
+
+Dave is inspired by the David vs. Goliath archetype.
+
+
+## Execution Environment
+
+Dave uses the [Cartesi Machine](https://github.com/cartesi/machine-emulator) as its execution environment.
+The Cartesi Machine is a RISC-V emulator.
+Its onchain implementation can be found [here](https://github.com/cartesi/machine-solidity-step).
+The Cartesi Machine state-transition function is implemented in two layers: the big-machine and the micro-architecture.
+The former implements the RV64GC ISA, while the latter implements the much smaller RV64IM ISA.
+Using a technique called _machine swapping_ and leveraging good compilers, we implement in Solidity only the micro-architecture's state-transition function, while the execution environment can support a much larger set of extensions.
+
+Nevertheless, Dave was designed to be agnostic on its execution environment.
+As long as one can provide a self-contained state-transition function, Dave will work.
+
+
+## Algorithm
+
+Dave is based on the Permissionless Refereed Tournaments primitive.
+The paper can be found [here](https://arxiv.org/abs/2212.12439).
+The maximum delay grows logarithmically on the number of Sybils, whereas the computation resources and stakes are constant, and don't grow on the number of Sybils.
+
+
+## Status
+
+The project is still in its prototyping stages.
+
+
+
+## Contributing
+
+Thank you for your interest in Cartesi!
+Head over to our [Contributing Guidelines](CONTRIBUTING.md) for instructions on how to sign our Contributors Agreement and get started with Cartesi!
+
+Please note we have a [Code of Conduct](CODE_OF_CONDUCT.md), please follow it in all your interactions with the project.
+
+## License
+
+The repository and all contributions are licensed under [APACHE 2.0](https://www.apache.org/licenses/LICENSE-2.0).
+Please review our [LICENSE](LICENSE) file.
+
+---
+
+<div align="center">
+  <a href="https://cartesi.io"><img alt="Dave" src="doc/assets/dave-img.jpeg" width=600></a>
+  <br />
+  <h3><a href="https://github.com/cartesi/dave">Dave</a>.</h3>
+</div>

permissionless-arbitration/lua_node/README.md

@@ -1,7 +1,36 @@
-# Permissionless Arbitration (NxN) Lua prototype Node
+# Dave Lua node
+
+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
 
+
+This directory also has an example _verification tournament_ program, 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 nxn_playground:latest -f Dockerfile ../../ && docker run --rm nxn_playground:latest
+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"
 ```