feat: update readmes for local development and devnet (#97)

* feat: add local development instructions

* feat: update commands to install deps and allow params

* feat: add readme with instructions on how to deploy a devnet

* chore: remove old documentation

DEVNET.md

@@ -0,0 +1,72 @@
+# Devnet
+
+A publicly accessible Lilypad network.
+
+## Components
+
+- A blockchain node
+- A solver service
+- A job creator service
+
+### Resource providers
+
+As is, the network cannot execute jobs, it needs resource providers to connect to the network and these in turn will be the ones running the jobs. Follow this instructions to [run a node in the Lilypad network](https://docs.lilypad.tech/lilypad/lilypad-milky-way-reference/run-a-node).
+
+## Deployments
+
+The three components have been isolated into docker containers and these components expose their services to the public via [Cloudflare tunnels](https://www.cloudflare.com/products/tunnel/) from inside the containers. This means there is no need to configure networking at the cloud service provider, just deploy the components using the appropriate build and run arguments to expose the services to the configured subdomains.
+
+The deployment processes for each component have the same three steps:
+
+- Build the docker image
+- Push the image to the container registry
+- Pull the image from the registry and execute the image in a container
+
+## Blockchain node
+
+There is a GitHub workflow to deploy the blockchain node, but it does not execute on code changes as there is no need to constantly deploy the blockchain node. There is ongoing work to implement a GitHub workflow that will compile and deploy the smart contracts.
+
+### Reset the blockchain
+
+If, for whatever reason, the blockchain node needs to be reset, this can be done in the following manner:
+
+1. `ssh` into the instance/pod running the blockchain node
+2. Connect into the `chain` container's shell (`docker exec -it chain /bin/bash`)
+3. In the container shell execute the reset script (`./reset`). This will stop the node, clear the blockchain data, restart the node and fund the admin account.
+4. Execute `./stack chain-boot` to compile, deploy and fund the smart contracts, token and accounts respectively. Change the configuration in the Hardhat scripts (`/hardhat.config.ts` and `/scripts/print-contract-env.ts`) to make sure the URLs point to the node's exposed subdomains (at the time of this write-up `8545` -> `https://devnet-chain-http.lilypad.tech` and `8546` -> `wss://devnet-chain-ws.lilypad.tech`).
+
+## Solver and Job creator
+
+When code changes reach the `main` branch, a GitHub workflow will trigger the flow that will first deploy and run the `solver` and then deploy and run the `job creator`. (*reminder*) The `solver` has to be up and running (and have registered its public URL to the blockchain) before the `job-creator` starts (the `job creator` will fail if it can't find the `solver`'s websocket server).
+
+## Deploying to a new cloud provider
+
+These steps have been used for [AWS](https://aws.amazon.com/) so maybe some changes have to be put in place for other providers but the overall flow should be similar.
+
+### VM instance
+
+Create a virtual machine to execute the component. The VM should have a running Docker daemon and should be able to pull an image from the chosen container registry.
+
+[`How to install docker`](https://serverfault.com/questions/836198/how-to-install-docker-on-aws-ec2-instance-with-ami-ce-ee-update)
+
+#### tldr;
+
+```sh
+sudo yum update -y
+sudo yum install docker -y
+sudo service docker start
+sudo usermod -a -G docker <vm-user>
+sudo systemctl enable docker (restart docker when VM instance restarts)
+```
+
+To grant access to the [ECR](https://aws.amazon.com/ecr/) registry from the VM execute `aws configure` with credentials that have `pull` permissions.
+
+### ECR repo
+
+Make sure the repo has been created.
+
+### Cloudflare tunnel
+
+Make sure the Cloudflare tunnel has been created and linked to the desired subdomain, and pass the token to the container in the build step.
+
+

LOCAL_DEVELOPMENT.md

@@ -0,0 +1,74 @@
+# Local development
+
+## Prerequisites
+
+- [Golang](https://go.dev/doc/install)
+- [node](https://nodejs.org/en/download/package-manager)
+- [Docker](https://docs.docker.com/engine/install/)
+- [Doppler](https://docs.doppler.com/docs/install-cli)
+
+## Getting started
+
+A minimal local Lilypad network consists of the following pieces of infrastructure:
+
+- One blockchain node
+- One solver service
+- One job creator service
+- One bacalhau node
+- One resource provider service
+
+Order matters because the `solver`, `job creator` and `resource provider` will right away try to connect to the `blockchain node`. First, the `solver` will update the state of a known smart contract to publish a URL where other services can connect to it. Then, the `job creator`, and `resource provider` will fetch from the `blockchain` the URL for the `solver` and try to connect to it.
+
+## Minimal local setup
+
+### 1. Blockchain node
+
+This has been implemented in a docker container and two functions are already in place to build and run the container: `./stack chain-docker-build` and `./stack chain-docker-run`. The run command accepts an optional parameter for a local path where to store the blockchain data. This is handy to keep the current state of the blockchain around even after restarts on the container. The first time this commands are executed the blockchain will be in its genesis state, several things need to happen:
+
+- Fund the admin account, which will be used to deploy the smart contracts and token.
+- Compile and deploy the smart contracts.
+- Create and fund the accounts with the native gas token and the Lilypad token.
+
+To do the first thing run the command `./stack chain-fund-admin`. Then, the remaining processes can be executed with the command `./stack chain-boot`. This last command executes via hardhat, so it will need the URL of the blockchain node where it will send the transactions (this is currently hardcoded to `http://localhost:8546`, which is ok for this setup but keep in mind in case you decide to configure things differently or if you want to run this command on a deployed blockchain node).
+
+### 2. Solver service
+
+This process can be executed directly if Golang has been installed or in a docker container. The commands are `./stack solver`,`./stack solver-docker-build` and `./stack solver-docker-run` respectively. The `solver` service will output a log line that reads that "the solver has been registered successfully" or "the solver already exists". It is best to wait for this output before starting the services that will try to connect to the `solver`.
+
+### 3. Job creator
+
+This process can be executed directly if Golang has been installed or in a docker container. The commands are `./stack job-creator`,`./stack job-creator-docker-build` and `./stack job-creator-docker-run` respectively. The `job-creator` service's main function is to listen to events from the blockchain to execute jobs and when it receives such an event it will relay the payload to the `solver`. So think about the `job-creator` as the "on-chain solver".
+
+### 4. Bacalhau node
+
+For the time being this process has to be executed directly. This means following the instructions to download their cli tool and expose it as a bin that can be used. Here's how to install the `bacalhau` tool:
+
+```sh
+# install the latest (at the time of this write-up it was 1.3.0)
+wget https://github.com/bacalhau-project/bacalhau/releases/download/v1.3.0/bacalhau_v1.3.0_linux_amd64.tar.gz
+# extract the downloaded archive and move the `bacalhau` binary to `/usr/local/bin`
+tar xfv bacalhau_v1.3.0_linux_amd64.tar.gz
+mv bacalhau /usr/local/bin
+```
+
+Once the tool has been installed, the following command can be used to start the node: `./stack bacalhau-node`.
+
+### 5. Resource provider
+
+For the time being this process has to be executed directly and needs Golang to be installed. This is the command to execute the service: `./stack resource-provider`. If you have a GPU you can use the following flag to use it: `./stack resource-provider --offer-gpu 1`
+
+#### Bacalhau and Resource provider as one component
+
+There is ongoing work to pack together the `bacalhau` node and `resource provider` service in a docker container as these two are highly coupled and can be abstracted into one component.
+
+## Running a job
+
+Once all the services are up and running this command can be used to trigger an on-chain job: `./stack run-cowsay-onchain`
+
+### Tests
+
+There are two commands that can be used to run existing tests: `./stack unit-tests` and `./stack integration-tests` (bear in mind the latter expects a blockchain node to be running locally).
+
+## Notes on tooling
+
+Things should work right out-of-the-box, no extra configuration should be needed as Doppler provides the environment variables that are required with the current setup.