Add a laconic-faucet stack (#7)

Part of [laconicd testnet validator enrollment](https://www.notion.so/laconicd-testnet-validator-enrollment-6fc1d3cafcc64fef8c5ed3affa27c675)

Co-authored-by: Adw8 <adwaitgharpure@gmail.com>
Reviewed-on: #7
Co-authored-by: Prathamesh Musale <prathamesh.musale0@gmail.com>
Co-committed-by: Prathamesh Musale <prathamesh.musale0@gmail.com>

README.md

@@ -4,7 +4,9 @@ Stacks to run a node for laconic testnet
 
 - [testnet-laconicd stack documentation](stack-orchestrator/stacks/testnet-laconicd/README.md)
 - [laconic-console stack documentation](stack-orchestrator/stacks/laconic-console/README.md) (to run laconic registry CLI and console standalone)
+- [laconic-faucet stack documentation](stack-orchestrator/stacks/laconic-faucet/README.md)
 
 ## Testnet onboarding demo
 
 Follow steps in [testnet-onboarding-demo.md](./testnet-onboarding-demo.md) to run demo for onboarding testnet participants in laconicd chain
+

stack-orchestrator/compose/docker-compose-laconic-faucet.yml

@@ -0,0 +1,29 @@
+services:
+  start-faucet:
+    restart: unless-stopped
+    image: cerc/laconic-faucet:local
+    command: ["bash", "-c", "./start-faucet.sh"]
+    environment:
+      CERC_SCRIPT_DEBUG: ${CERC_SCRIPT_DEBUG}
+      CERC_LACONICD_RPC_ENDPOINT: ${CERC_LACONICD_RPC_ENDPOINT:-http://laconicd:26657}
+      CERC_FAUCET_KEY: ${CERC_FAUCET_KEY}
+      CERC_LACONICD_CHAIN_ID: ${CERC_LACONICD_CHAIN_ID:-laconic_9000-1}
+      CERC_TRANSFER_AMOUNT: ${CERC_TRANSFER_AMOUNT:-1000000}
+      CERC_PERIOD_TRANSFER_LIMIT: ${CERC_PERIOD_TRANSFER_LIMIT:-3000000}
+    volumes:
+      - faucet-data:/app/db
+      - ../config/laconic-faucet/start-faucet.sh:/app/start-faucet.sh
+      - ../config/laconic-faucet/config-template.toml:/app/environments/config-template.toml
+    ports:
+      - 3000
+    healthcheck:
+      test: ["CMD", "nc", "-vz", "127.0.0.1", "3000"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+      start_period: 5s
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+
+volumes:
+  faucet-data:

stack-orchestrator/config/laconic-faucet/config-template.toml

@@ -0,0 +1,13 @@
+[upstream]
+  rpcEndpoint = "REPLACE_WITH_CERC_LACONICD_RPC_ENDPOINT"
+  chainId = "laconic_9000-1"
+  denom = "photon"
+  prefix = "laconic"
+  gasPrice = "0.01"
+  faucetKey = "REPLACE_WITH_CERC_FAUCET_KEY"
+
+[server]
+  port=3000
+  transferAmount = "REPLACE_WITH_CERC_TRANSFER_AMOUNT"
+  periodTransferLimit = "REPLACE_WITH_CERC_PERIOD_TRANSFER_LIMIT"
+  dbDir = "db"

stack-orchestrator/config/laconic-faucet/start-faucet.sh

@@ -0,0 +1,30 @@
+#!/bin/bash
+
+set -e
+set -u
+if [ -n "$CERC_SCRIPT_DEBUG" ]; then
+  set -x
+fi
+
+config_template=$(cat environments/config-template.toml)
+target_config="./environments/local.toml"
+
+# Check if faucet key is set
+if [ -z "${CERC_FAUCET_KEY:-}" ]; then
+  echo "Error: CERC_FAUCET_KEY is not set. Exiting..."
+  exit 1
+fi
+
+echo "Using laconicd RPC endpoint: $CERC_LACONICD_RPC_ENDPOINT"
+echo "Transfer amount per request: $CERC_TRANSFER_AMOUNT"
+echo "Transfer limit for an address within a period: $CERC_PERIOD_TRANSFER_LIMIT"
+
+FAUCET_CONFIG=$(echo "$config_template" | \
+  sed -E "s|REPLACE_WITH_CERC_FAUCET_KEY|${CERC_FAUCET_KEY}|g; \
+          s|REPLACE_WITH_CERC_LACONICD_RPC_ENDPOINT|${CERC_LACONICD_RPC_ENDPOINT}|g; \
+          s|REPLACE_WITH_CERC_TRANSFER_AMOUNT|${CERC_TRANSFER_AMOUNT}|g; \
+          s|REPLACE_WITH_CERC_PERIOD_TRANSFER_LIMIT|${CERC_PERIOD_TRANSFER_LIMIT}|; ")
+
+echo "$FAUCET_CONFIG" > $target_config
+echo "Starting faucet..."
+node dist/index.js

stack-orchestrator/container-build/cerc-laconic-faucet/build.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+
+# Build cerc/laconic-faucet
+source ${CERC_CONTAINER_BASE_DIR}/build-base.sh
+docker build -t cerc/laconic-faucet:local ${build_command_args} ${CERC_REPO_BASE_DIR}/laconic-faucet

stack-orchestrator/stacks/laconic-faucet/README.md

@@ -0,0 +1,121 @@
+# laconic-faucet
+
+Instructions for running the laconic faucet
+
+## Setup
+
+* Clone the stack repo:
+
+  ```bash
+  laconic-so fetch-stack git.vdb.to/cerc-io/testnet-laconicd-stack
+  ```
+
+* Clone the laconic-faucet respository:
+
+  ```bash
+  laconic-so --stack ~/cerc/testnet-laconicd-stack/stack-orchestrator/stacks/laconic-faucet setup-repositories
+  ```
+
+* Build the container image:
+
+  ```bash
+  laconic-so --stack ~/cerc/testnet-laconicd-stack/stack-orchestrator/stacks/laconic-faucet build-containers
+  ```
+
+  This should create the `cerc/laconic-faucet` image locally
+
+## Create a deployment
+
+* Create a spec file for the deployment:
+
+  ```bash
+  laconic-so --stack ~/cerc/testnet-laconicd-stack/stack-orchestrator/stacks/laconic-faucet deploy init --output laconic-faucet-spec.yml
+  ```
+
+* Edit `network` in the spec file to map container ports to host ports as required:
+
+  ```bash
+  network:
+    ports:
+      laconic-faucet:
+        - '3000:3000'
+  ```
+
+* Create a deployment from the spec file:
+
+  ```bash
+  laconic-so --stack ~/cerc/testnet-laconicd-stack/stack-orchestrator/stacks/laconic-faucet deploy create --spec-file laconic-faucet-spec.yml --deployment-dir laconic-faucet-deployment
+  ```
+
+## Configuration
+
+* Inside the `laconic-faucet-deployment` deployment directory, open `config.env` file and set following env variables:
+
+  ```bash
+  # Private key of a funded faucet account
+  CERC_FAUCET_KEY=
+
+  # Optional
+
+  # laconicd RPC endpoint (default: http://laconicd:26657)
+  CERC_LACONICD_RPC_ENDPOINT=
+
+  # laconicd chain id (default: laconic_9000-1)
+  CERC_LACONICD_CHAIN_ID=
+
+  # Amount of tokens to transfer on a single request (default: 1000000)
+  CERC_TRANSFER_AMOUNT=
+
+  # Transfer limit for an address within a period (default: 3000000)
+  CERC_PERIOD_TRANSFER_LIMIT=
+  ```
+
+## Start the deployment
+
+  ```bash
+  laconic-so deployment --dir laconic-faucet-deployment start
+  ```
+
+## Check status
+
+* To list down and monitor the running container:
+
+  ```bash
+  # With status
+  docker ps
+
+  # Check logs for a container
+  docker logs -f <CONTAINER_ID>
+  ```
+
+## Run
+
+* Request tokens from the faucet for an account:
+
+  ```bash
+  curl -X POST http://localhost:3000/faucet \
+    -H "Content-Type: application/json" \
+    -d '{"address": "<laconicd_address>"}'
+
+  # Expected output:
+  # {"success":true,"txHash":"<tx_hash>"}
+  ```
+
+## Clean up
+
+* Stop the `laconic-faucet` service running in the background:
+
+  ```bash
+  # Stop the docker container
+  laconic-so deployment --dir laconic-faucet-deployment stop
+  ```
+
+* To stop the service and also delete data:
+
+  ```bash
+  # Stop the docker containers
+  laconic-so deployment --dir laconic-faucet-deployment stop --delete-volumes
+
+  # Remove deployment directory (deployment will have to be recreated for a re-run)
+  rm -r laconic-faucet-deployment
+  ```

stack-orchestrator/stacks/laconic-faucet/stack.yml

@@ -0,0 +1,9 @@
+version: "1.0"
+name: laconic-faucet
+description: "Faucet for laconicd"
+repos:
+  - git.vdb.to/cerc-io/laconic-faucet
+containers:
+  - cerc/laconic-faucet
+pods:
+  - laconic-faucet

stack-orchestrator/stacks/testnet-laconicd/README.md

@@ -28,7 +28,7 @@ Instructions for running a laconicd testnet full node and joining as a validator
   # laconicd
   laconic-so --stack ~/cerc/testnet-laconicd-stack/stack-orchestrator/stacks/testnet-laconicd setup-repositories
 
-  # laocnic cli and console
+  # laconic cli and console
   laconic-so --stack ~/cerc/testnet-laconicd-stack/stack-orchestrator/stacks/laconic-console setup-repositories
   ```
 

testnet-onboarding-demo.md

@@ -86,12 +86,13 @@
 
 - Follow these steps to install laconic-so: <https://git.vdb.to/cerc-io/stack-orchestrator#install>
 
-### Fixturenet laconicd Stack
+### Fixturenet laconicd Stack and laconic-faucet
 
 1. Clone the stack repos:
 
     ```bash
     laconic-so fetch-stack git.vdb.to/cerc-io/fixturenet-laconicd-stack --git-ssh --pull
+    laconic-so fetch-stack git.vdb.to/cerc-io/testnet-laconicd-stack --git-ssh --pull
     ```
 
 2. Clone required repositories:
@@ -99,6 +100,7 @@
     ```bash
     # laconicd
     laconic-so --stack ~/cerc/fixturenet-laconicd-stack/stack-orchestrator/stacks/fixturenet-laconicd setup-repositories --git-ssh --pull
+    laconic-so --stack ~/cerc/testnet-laconicd-stack/stack-orchestrator/stacks/laconic-faucet setup-repositories --git-ssh --pull
     ```
 
 3. Build the container images:
@@ -106,6 +108,7 @@
     ```bash
     # laconicd
     laconic-so --stack ~/cerc/fixturenet-laconicd-stack/stack-orchestrator/stacks/fixturenet-laconicd build-containers --force-rebuild
+    laconic-so --stack ~/cerc/testnet-laconicd-stack/stack-orchestrator/stacks/laconic-faucet build-containers --force-rebuild
     ```
 
 4. Create a deployment for stage 0:
@@ -167,12 +170,39 @@
             - '1317:1317'
       ```
 
-    - Create deployment from the spec files:
+    - Create a deployment from the spec file:
 
       ```bash
       laconic-so --stack ~/cerc/fixturenet-laconicd-stack/stack-orchestrator/stacks/fixturenet-laconicd deploy create --spec-file  stage1-spec.yml --deployment-dir stage1-deployment
       ```
 
+6. Create a deployment for laconic-faucet:
+    - Create spec file for the deployment:
+
+      ```bash
+      laconic-so --stack ~/cerc/testnet-laconicd-stack/stack-orchestrator/stacks/laconic-faucet deploy init --output laconic-faucet-spec.yml
+      ```
+
+    - Edit `network` in the spec file to map container port to host port as required:
+
+      ```bash
+      # laconic-faucet-spec.yml
+      ...
+      network:
+        ports:
+          laconic-faucet:
+            - '4000:3000'
+      ```
+
+    - Create a deployment from the spec file:
+
+      ```bash
+      laconic-so --stack ~/cerc/testnet-laconicd-stack/stack-orchestrator/stacks/laconic-faucet deploy create --spec-file laconic-faucet-spec.yml --deployment-dir laconic-faucet-deployment
+
+      # Place in the same namespace as stage0
+      cp stage0-deployment/deployment.yml laconic-faucet-deployment/deployment.yml
+      ```
+
 ### L1 eth and L2 optimism stacks
 
 1. Clone the stack repo:
@@ -304,19 +334,21 @@
     ```bash
     cd tls
     make create-cert
+
+    # Go back to go-nitro
+    cd ../
     ```
 
-4. Install `nitro-rpc-client` package globally (run outside of go-nitro):
+4. Install `nitro-rpc-client` package globally:
 
     ```bash
-    cd ~
+    # In go-nitro
-    # 'yarn global' commands only work with Yarn versions below 2.x.
+    npm install -g ./packages/nitro-rpc-client
 
-    npm install -g <go-nitro-repo-absolute-path>/packages/nitro-rpc-client
+    # Confirm global installation by running
+    nitro-rpc-client --version
     ```
 
-    - Replace `<go-nitro-repo-absolute-path>` with absolute path to the cloned go-nitro repo
-
 ## Run
 
 - Start L1, L2 stacks:
@@ -380,7 +412,7 @@
     - Read the bridge contract address from the L1 deployment records in the `op-node` container:
 
       ```bash
-      BRIDGE=$(laconic-so deployment --dir fixturenet-optimism-deployment exec op-node "cat /l1-deployment/$DEPLOYMENT_CONTEXT/.deploy" | jq -r .L1StandardBridgeProxy)
+      BRIDGE=$(laconic-so deployment --dir fixturenet-optimism-deployment exec op-node "cat /l1-deployment/$DEPLOYMENT_CONTEXT-deploy.json" | jq -r .L1StandardBridgeProxy)
 
       # Get the funded account's pk
       ACCOUNT_PK=$(laconic-so deployment --dir fixturenet-optimism-deployment exec op-node "jq -r '.AdminKey' /l2-accounts/accounts.json")
@@ -550,7 +582,6 @@
     ```
     # In laconic-wallet
     yarn start
-
     ```
 
   - Press `a` to run the application on android and wait till the wallet app opens up on your phone
@@ -579,28 +610,29 @@
   laconic-so deployment --dir stage0-deployment logs laconicd -f
   ```
 
+- Run laconic-faucet:
+
+  - Get private key of funded faucet account from laconicd
+
+    ```bash
+    laconic-so deployment --dir stage0-deployment exec laconicd "laconicd keys export alice --keyring-backend test --unarmored-hex --unsafe"
+    ```
+
+  - In `laconic-faucet-deployment/config.env` file, set the following env variables:
+
+    ```bash
+    # Private key of a funded faucet account
+    CERC_FAUCET_KEY=<faucet-account-pk>
+    ```
+
+  - Start the stack for laconic-faucet
+
+    ```bash
+    laconic-so deployment --dir laconic-faucet-deployment start
+    ```
+
 - In the wallet, add 2 accounts (Alice and Charlie) for both the networks (ethereum and laconicd) by selecting the network and clicking on `Add account`
 
-- Fund accounts on laconicd:
-  - Export laconic addresses of Alice and Charlie (take the addresses from laconic wallet):
-
-    ```bash
-    export A_LACONIC_ADDRESS=<Alice Laconic address>
-    export C_LACONIC_ADDRESS=<Charlie Laconic address>
-    ```
-
-  - Send photons from funded account to Alice and Charlie:
-
-    ```bash
-    # Send funds from funded account to Alice
-    laconic-so deployment --dir stage0-deployment exec laconicd "laconicd tx bank send alice $A_LACONIC_ADDRESS 100000000000photon --fees 100photon --keyring-backend test"
-
-    # Send funds from funded account to Charlie
-    laconic-so deployment --dir stage0-deployment exec laconicd "laconicd tx bank send alice $C_LACONIC_ADDRESS 100000000000photon --fees 100photon --keyring-backend test"
-    ```
-
-    TODO: Use a faucet for funding accounts
-
 - Go to go-nitro repo root and start the nitro bridge using CLI:
 
   ```bash
@@ -810,13 +842,14 @@
 - Onboard participants
   - Open the `testnet-onboarding-app` at <http://localhost:3000>
   - Connect to the testnet-onboarding app by clicking on the WalletConnect icon on the top right corner in the wallet and scanning QR code of the app
-  - Choose Alice's ethereum and laconicd account to onboard
+  - Choose Alice's nitro and laconicd account to onboard
-    - Use ethereum accounts for which ledger channels have been created on L2
+    - Use nitro accounts for which ledger channels have been created on L2
-  - Sign using the ethereum key
+  - Sign using the nitro key
     - Approve sign request on Wallet
+  - Fund the laconic account by clicking on the `REQUEST TOKENS FROM FAUCET` button
   - Send transaction request to the Wallet
     - Approve and send transaction to laconicd chain
-  - Repeat onboarding for other (Charlies's) account
+  - Repeat onboarding for other (Charlies's) account by clicking on the web app header "Testnet Onboarding"
   - List the participants on stage 1 (run in the directory where laconicd deployment was  created):
 
     ```bash
@@ -848,14 +881,11 @@
 
       # Remove the temporary data directory
       sudo rm -rf stage1-genesis
+
+      # Go back to the directory where deployments are created
+      cd -
       ```
 
-  - Change directory to stage1 deployment directory
-
-    ```bash
-    cd <stage1-deployment-directory-absolute-path>
-    ```
-
   - Copy over the generated genesis file (`.json`) containing the onboarding module state with funded participants to data directory in stage1 deployment (`stage1-deployment/data/genesis-config`):
 
     ```bash
@@ -914,8 +944,8 @@
 
   ```bash
   export BRIDGE_ADDRESS=0xBBB676f9cFF8D242e9eaC39D063848807d3D1D94
-  export A_ADDRESS=<Alice Ethereum address>
+  export A_ADDRESS=<Alice Nitro address>
-  export C_ADDRESS=<Charlie Ethereum address>
+  export C_ADDRESS=<Charlie Nitro address>
 
   # Starts virtual fund objective on L2 to create virtual channel from A' to C'
   nitro-rpc-client virtual-fund $C_ADDRESS $BRIDGE_ADDRESS -p 4008
@@ -1003,11 +1033,25 @@
 
     ```bash
     # Run where deployments are created
-    sudo rm -rf stage0-deployment/data/laconicd-data/*
+    sudo rm -rf 'stage0-deployment/data/laconicd-data/*'
-    sudo rm -rf stage0-deployment/data/genesis-config/*
+    sudo rm -rf 'stage0-deployment/data/genesis-config/*'
 
-    sudo rm -rf stage1-deployment/data/laconicd-data/*
+    sudo rm -rf 'stage1-deployment/data/laconicd-data/*'
-    sudo rm -rf stage1-deployment/data/genesis-config/*
+    sudo rm -rf 'stage1-deployment/data/genesis-config/*'
+    ```
+
+- Reset faucet deployment:
+  - Stop deployment and remove volumes:
+
+    ```bash
+    laconic-so deployment --dir laconic-faucet-deployment stop --delete-volumes
+    ```
+
+  - Remove data from the deployment
+
+    ```bash
+    # Run where deployments are created
+    sudo rm -rf 'laconic-faucet-deployment/data/faucet-data/*'
     ```
 
 ## Re-run
@@ -1068,9 +1112,22 @@
     sudo rm -rf fixturenet-eth-deployment
     ```
 
+- Clean up faucet deployment:
+  - Stop deployment and remove volumes:
+
+    ```bash
+    laconic-so deployment --dir laconic-faucet-deployment stop --delete-volumes
+    ```
+
+  - Clear deployment
+
+    ```bash
+    # Run where deployments are created
+    sudo rm -rf laconic-faucet-deployment
+    ```
+
 ## Future enhancements
 
-- Implement faucet in stage 0 laconicd chain for participants to send onboarding tx
 - Use latest optimism releases (e.g. v1.7.7) in fixturenet-optimism
 - Implement external stack for go-nitro
   - Add stack for bridge