PoW Faucet

.dockerignore

@@ -0,0 +1,13 @@
+.dockerignore
+.DS_Store
+.env*
+.git
+.github
+.gitignore
+.vscode
+dist
+Dockerfile
+LICENSE.md
+node_modules
+npm-debug.log
+README.md

.env.example

@@ -0,0 +1,17 @@
+API_PORT=3000
+
+AUTHORIZED_HOST="*"
+
+ENABLE_CAPTCHA=true
+CAPTCHA_SECRET=6LefC8...
+
+FAUCET_PRIVATE_KEY=edsk...
+
+REDIS_PASSWORD=password
+REDIS_URL=redis://localhost:6379
+
+RPC_URL=http://localhost:8732
+
+DISABLE_CHALLENGES=false
+
+MAX_BALANCE=6000

.gitignore

@@ -1,2 +1,3 @@
 node_modules/
-.env
+dist/
+.env

Dockerfile

@@ -1,13 +1,18 @@
-FROM node:16-alpine
+FROM node:18-alpine
 
-WORKDIR /tezos-faucet-backend
+USER node
 
-COPY package.json .
+WORKDIR /app
+
+RUN chown node:node /app
+
+COPY --chown=node:node package.json ./
+COPY --chown=node:node package-lock.json ./
 
 RUN npm install
 
-COPY . .
+COPY --chown=node:node . ./
 
-RUN ./node_modules/typescript/bin/tsc -p ./tsconfig.json
+RUN ./node_modules/typescript/bin/tsc
 
-CMD ["node", "./dist/api.js"]
+CMD ["node", "--enable-source-maps", "./dist/src/api.js"]

README.md

@@ -1,28 +1,73 @@
-# Tezos testnet faucet API
+# Tezos Faucet Backend
 
 ## Overview
 
-Backend for Tezos faucet front app: https://github.com/oxheadalpha/tezos-faucet.
+The Tezos Faucet Backend (frontend code [here](https://github.com/oxheadalpha/tezos-faucet)) provides a reliable and secure way to distribute Tez to users. Through the implementation of a Proof of Work (PoW) mechanism, combined with CAPTCHA, we ensure users expend computational resources, thereby preventing bots and malicious actors from spamming and draining the faucet.
 
-## Prerequisite
+Here's a general flow of how it works:
 
-Create a ReCaptcha project (shared with faucet front app).
+1. **Requesting Tez**: A user initiates the process by making a request for tez. The backend responds by sending a challenge to the user.
+2. **Solving Challenges**: The user must solve the challenge by finding a correct solution. The complexity of the challenge can vary, and the user doesn't know in advance how many challenges they'll need to solve.
+3. **Verification & Receiving Tez**: Once the user submits a solution, the backend verifies it. If the solution is correct but there are more challenges to be solved, the user will be sent another challenge. This repeats until all challenges are solved correctly. Only then is the requested Tez granted to the user.
 
+## Prerequisites
 
-## Local run for development
+- **Node.js** v18
+- **Captcha** (Optional): Create a Google [ReCaptcha](https://www.google.com/recaptcha/about/) project. The public site key will be shared with the frontend. Activate domain verification in ReCAPTCHA parameters to allow only communication from the frontend faucet app.
+- **Redis** (Optional): If `DISABLE_CHALLENGES` is not set to `false`, set up a Redis server to store PoW challenge data. It's recommended to use a single-instance Redis setup for the challenge data, as this ensures atomicity and helps in avoiding potential exploits. Given that the challenge data isn't persistent or long-term essential, a single instance suffices and is easier to maintain.
 
-Compile Typescript sources to `/dist` directory:
+## Config
+
+Set environment variables or add them to a `.env` file. See [.env.example](.env.example). The [src/env.ts](src/env.ts) file handles necessary type conversions from environment variable strings.
+
+Mandatory:
+
+- `FAUCET_PRIVATE_KEY`: Faucet's private key to sign transactions
+- `CAPTCHA_SECRET`: faucet ReCAPTCHA secret key (mandatory if `ENABLE_CAPTCHA=true`)
+- `RPC_URL`: Tezos node RPC URL to connect to
+
+### Profile Configuration
+
+Profiles are configured in the [profiles.json](./profiles.json) file. Each profile is an object with the following properties:
+
+- `amount`: The amount of Tez to be distributed for the specified profile. Default for `USER`: `1`, for `BAKER`: `6000`.
+- `challengesNeeded`: The number of challenges needed if no CAPTCHA is provided. Default for both `USER` and `BAKER`: `6`.
+- `challengesNeededWithCaptcha`: The number of challenges needed if a valid CAPTCHA is provided. Default for both `USER` and `BAKER`: `5`.
+- `difficulty`: The difficulty level of the challenge if no CAPTCHA is provided. Default for both `USER` and `BAKER`: `5`.
+- `difficultyWithCaptcha`: The difficulty level of the challenge if a valid CAPTCHA is provided. Default for both `USER` and `BAKER`: `4`.
+
+The [src/profiles.ts](src/profiles.ts) file imports this JSON file and validates these properties. If any property is missing or invalid, an error will be thrown. If `DISABLE_CHALLENGES` is `true`, only `amount` is required.
+
+Optional:
+
+- `API_PORT`: API listening port (default: `3000`)
+- `AUTHORIZED_HOST`: CORS origin whitelist (default `*`)
+- `DISABLE_CHALLENGES`: `true` to disable challenges (default: `false`)
+- `ENABLE_CAPTCHA`: `true` to enable ReCAPTCHA, `false` otherwise (default: `true`)
+- `MAX_BALANCE`: maximum address balance beyond which sending of XTZ is refused (default: `6000`)
+
+## Running the API
+
+Install dependencies and compile Typescript sources to `/dist` directory:
 
 ```
+npm install
 npm run build
 ```
 
-Run API with `nodemon`:
+Run API:
+
 ```
-npm run serve
+npm run start
 ```
 
-## Deploy
+For developing with auto reloading:
+
+```
+npm run dev
+```
+
+## Docker
 
 ### Build
 
@@ -36,85 +81,54 @@ docker build . -t tezos-faucet-backend
 docker run -p 3000:3000 tezos-faucet-backend
 ```
 
-## Config
+## API Endpoints
 
-Set environment variables
+### GET /info
 
-Mandatory:
+Returns general information about the faucet, including the faucet's address, whether captcha is enabled, the max balance allowed, and the Tez amounts granted per profile.
 
-- `FAUCET_PRIVATE_KEY`: private key of the faucet, to sign transaction
-- `FAUCET_ADDRESS`: faucet address
-- `FAUCET_CAPTCHA_SECRET`: faucet ReCAPTCHA secret key (mandatory if ENABLE_CAPTCHA=true)
-- `RPC_URL`: Tezos node RPC URL to connect to
-
-Optional:
-
-- `ENABLE_CAPTCHA`: true to enable ReCAPTCHA, false otherwise (default: true)
-- `AUTHORIZED_HOST`: authorized host, for CORS (default: *).
-- `API_PORT`: API listening port (default: 3000)
-- `FAUCET_AMOUNT_USER`: number of XTZ to send for a regular request (default: 1)
-- `FAUCET_AMOUNT_BAKER`: number of XTZ to send for a baker request (default: 6000)
-- `MAX_BALANCE`: maximum user balance beyond which sending of XTZ is refused (default: 6000)
-
-## Security
-
-Activate domain verification in ReCAPTCHA parameters to allow only calls from the Front faucet.
-
-## Use
-
-### Request
-
-Request URL:
-```
-POST /send
-```
+Example response:
 
-Request body:
-```
+```json
 {
-    captchaToken:"...",
-    address:"tz1...",
-    profile:"USER"
+  "faucetAddress": "tz1...",
+  "captchaEnabled": true,
+  "maxBalance": 6000,
+  "profiles": {
+    "user": {
+      "profile": "USER",
+      "amount": 1,
+      "currency": "tez"
+    },
+    "baker": {
+      "profile": "BAKER",
+      "amount": 6000,
+      "currency": "tez"
+    }
+  }
 }
 ```
 
-- `token`: ReCaptcha user response token
-- `address`: address to send XTZ to
-- `profile`: USER for a regular user who will get 1 xtz. BAKER for a baker profile, who will get 6000 xtz.
-
-### Response
+### POST /challenge
 
-#### Success
+Initiates the Tez request procedure. The user provides their address, profile type (`BAKER` or `USER`), and captcha token (optional).
 
-Return code: HTTP 200
+If a challenge already exists for the user's address in Redis it will be returned in the response. Otherwise the endpoint generates a new challenge and stores it, along with associated data in Redis.
 
-Response body:
-```
-{
-    "status": "SUCCESS",
-    "txHash":"..."
-}
-```
+The response contains the challenge string, a challenge counter starting at 1, and the difficulty. The challenge counter indicates the current challenge in a series of Proof of Work challenges that the user must complete. Users aren't privy in advance to the exact number of PoW challenges they'll need to solve to receive the requested Tez.
 
-- `status`: SUCCESS
-- `txHash`: hash of transaction
+### POST /verify
 
+Allows users to submit solutions to the challenges. The user provides their address, nonce, solution string, and profile type.
 
-#### Error
+The endpoint verifies the solution by trying to regenerate it using the challenge string and nonce.
 
-Return code:
+If the solution is correct but the required number of challenges have not yet been satisfied, a new challenge is generated and returned in the response.
 
-- HTTP 400: Bad request (wrong captcha token)
-- HTTP 500: Server or Tezos node error
+If all challenges have been completed, the user's address is granted the Tez amount for their profile type. The transaction hash is returned to indicate the transfer was successful.
 
+## Programmatic Faucet Usage
 
-Response body:
-```
-{
-    "status": "ERROR",
-    "message": "Captcha error"
-}
-```
+For programmatic usage of the faucet, we provide a `getTez.js` script located in the `/scripts` directory of the frontend repository. Please refer to it for more details on how to use it. This script can be run from a JavaScript program or directly from a shell. It interacts with the backend to request Tez, solve the required challenges, and verify the solutions.
 
-- `status`: ERROR
-- `message`: error message
+Please note that the `getTez.js` script does not use CAPTCHA. Therefore, when using the programmatic faucet, challenges can be configured to be more difficult and require more of them to be solved.