From c9a7d1956eb192bb8a8cb573ccbe945b8ac3196a Mon Sep 17 00:00:00 2001 From: rymnc <43716372+rymnc@users.noreply.github.com> Date: Wed, 6 Sep 2023 10:47:58 +0530 Subject: [PATCH] chore(rln-relay): updated docs --- docs/operators/how-to/run-with-rln.md | 4 +- docs/tutorial/onchain-rln-relay-chat2.md | 43 +++----------- docs/tutorial/rln-keystore-generator.md | 73 ++++++++++++++++++++++++ tools/rln_keystore_generator/README.md | 2 +- 4 files changed, 84 insertions(+), 38 deletions(-) create mode 100644 docs/tutorial/rln-keystore-generator.md diff --git a/docs/operators/how-to/run-with-rln.md b/docs/operators/how-to/run-with-rln.md index da8533b191..570131740e 100644 --- a/docs/operators/how-to/run-with-rln.md +++ b/docs/operators/how-to/run-with-rln.md @@ -42,7 +42,7 @@ Follow [Step 10](../droplet-quickstart.md#10-run-nwaku) of the [droplet quicksta ```bash export SEPOLIA_WS_NODE_ADDRESS= -export RLN_RELAY_CONTRACT_ADDRESS="0x9C09146844C1326c2dBC41c451766C7138F88155" # Replace this with any compatible implementation +export RLN_RELAY_CONTRACT_ADDRESS="0xF471d71E9b1455bBF4b85d475afb9BB0954A29c4" # Replace this with any compatible implementation $WAKUNODE_DIR/wakunode2 \ --store:true \ --persist-messages \ @@ -62,7 +62,7 @@ If you are running the nwaku node within docker, follow [Step 2](../docker-quick ```bash export WAKU_FLEET= export SEPOLIA_WS_NODE_ADDRESS= -export RLN_RELAY_CONTRACT_ADDRESS="0x9C09146844C1326c2dBC41c451766C7138F88155" # Replace this with any compatible implementation +export RLN_RELAY_CONTRACT_ADDRESS="0xF471d71E9b1455bBF4b85d475afb9BB0954A29c4" # Replace this with any compatible implementation docker run -i -t -p 60000:60000 -p 9000:9000/udp statusteam/nim-waku:v0.12.0 \ --dns-discovery:true \ --dns-discovery-url:"$WAKU_FLEET" \ diff --git a/docs/tutorial/onchain-rln-relay-chat2.md b/docs/tutorial/onchain-rln-relay-chat2.md index 46ed3b43bd..69b3e12b82 100644 --- a/docs/tutorial/onchain-rln-relay-chat2.md +++ b/docs/tutorial/onchain-rln-relay-chat2.md @@ -8,16 +8,14 @@ This differs from the prior test scenarios in which the RLN group was static and ## Prerequisites To complete this tutorial, you will need -1. An rln keystore file with credentials to the rln membership smart contract you wish to use. You may obtain this by registering to the smart contract and generating a keystore. - +1. An rln keystore file with credentials to the rln membership smart contract you wish to use. You may obtain this by registering to the smart contract and generating a keystore, or by using the [rln-keystore-generator](./rln-keystore-generator.md) which does that for you. ## Overview Figure 1 provides an overview of the interaction of the chat2 clients with the test fleets and the membership contract. -At a high level, when a chat2 client is run with Waku-RLN-Relay mounted in on-chain mode, the passed in credential will get displayed on the console of your chat2 client. -You may copy the displayed RLN credential and reuse them for the future execution of the chat2 application. -Proper instructions in this regard is provided in the following [section](#how-to-persist-and-reuse-rln-credential). +At a high level, when a chat2 client is run with Waku-RLN-Relay mounted in on-chain mode. + Under the hood, the chat2 client constantly listens to the membership contract and keeps itself updated with the latest state of the group. In the following test setting, the chat2 clients are to be connected to the Waku test fleets as their first hop. @@ -47,7 +45,7 @@ Run the following command to set up your chat2 client. --content-topic:/toy-chat/3/mingde/proto \ --rln-relay:true \ --rln-relay-dynamic:true \ ---rln-relay-eth-contract-address:0x9C09146844C1326c2dBC41c451766C7138F88155 \ +--rln-relay-eth-contract-address:0xF471d71E9b1455bBF4b85d475afb9BB0954A29c4 \ --rln-relay-cred-path:xxx/xx/rlnKeystore.json \ --rln-relay-cred-password:xxxx \ --rln-relay-eth-client-address:xxxx \ @@ -60,8 +58,8 @@ In this command - the `rln-relay` flag is set to `true` to enable the Waku-RLN-Relay protocol for spam protection. - the `--rln-relay-dynamic` flag is set to `true` to enable the on-chain mode of Waku-RLN-Relay protocol with dynamic group management. - the `--rln-relay-eth-contract-address` option gets the address of the membership contract. - The current address of the contract is `0x9C09146844C1326c2dBC41c451766C7138F88155`. - You may check the state of the contract on the [Sepolia testnet](https://sepolia.etherscan.io/address/0x9C09146844C1326c2dBC41c451766C7138F88155). + The current address of the contract is `0xF471d71E9b1455bBF4b85d475afb9BB0954A29c4`. + You may check the state of the contract on the [Sepolia testnet](https://sepolia.etherscan.io/address/0xF471d71E9b1455bBF4b85d475afb9BB0954A29c4). - the `--rln-relay-cred-path` option denotes the path to the keystore file described above - the `--rln-relay-cred-password` option denotes the password to the keystore - the `rln-relay-eth-client-address` is the WebSocket address of the hosted node on the Sepolia testnet. @@ -153,31 +151,6 @@ Once you are done with the test, make sure you close all the chat2 clients by ty quitting... ``` -## How to persist and reuse RLN credential - -You may pass the `rln-relay-cred-path` config option to specify a path to a file for 1) persisting RLN credentials and 2) retrieving persisted RLN credentials. - -If the keystore exists in the path provided, it is used, and will default to the 0th element in the credential array. -If the keystore does not exist in the path provided, a new keystore will be created and added to the directory it was supposed to be in. - -You may provide an index to the credential you wish to use by passing the `rln-relay-cred-index` config option. - -You may provide an index to the membership you wish to use (within the same membership set) by passing the `rln-relay-membership-group-index` config option. - -```bash -./build/chat2 --fleet:test \ ---content-topic:/toy-chat/3/mingde/proto \ ---rln-relay:true \ ---rln-relay-dynamic:true \ ---rln-relay-eth-contract-address:0x9C09146844C1326c2dBC41c451766C7138F88155 \ ---rln-relay-eth-client-address:your_sepolia_node \ ---ports-shift:0 \ ---rln-relay-cred-path:./rlnKeystore.json \ ---rln-relay-cred-password:your_password \ ---rln-relay-membership-index:0 \ ---rln-relay-membership-group-index:0 -``` - # Sample test output In this section, a sample test of running two chat clients is provided. @@ -193,7 +166,7 @@ You can check this fact by looking at `Bob`'s console, where `message3` is missi **Alice** ```bash -./build/chat2 --fleet:test --content-topic:/toy-chat/3/mingde/proto --rln-relay:true --rln-relay-dynamic:true --rln-relay-eth-contract-address:0x9C09146844C1326c2dBC41c451766C7138F88155 --rln-relay-cred-path:rlnKeystore.json --rln-relay-cred-password:password --rln-relay-eth-client-address:wss://sepolia.infura.io/ws/v3/12345678901234567890123456789012 --ports-shift=1 +./build/chat2 --fleet:test --content-topic:/toy-chat/3/mingde/proto --rln-relay:true --rln-relay-dynamic:true --rln-relay-eth-contract-address:0xF471d71E9b1455bBF4b85d475afb9BB0954A29c4 --rln-relay-cred-path:rlnKeystore.json --rln-relay-cred-password:password --rln-relay-eth-client-address:wss://sepolia.infura.io/ws/v3/12345678901234567890123456789012 --ports-shift=1 ``` ``` @@ -236,7 +209,7 @@ your rln identity commitment key is: bd093cbf14fb933d53f596c33f98b3df83b7e9f7a19 **Bob** ```bash -./build/chat2 --fleet:test --content-topic:/toy-chat/3/mingde/proto --rln-relay:true --rln-relay-dynamic:true --rln-relay-eth-contract-address:0x9C09146844C1326c2dBC41c451766C7138F88155 --rln-relay-cred-path:rlnKeystore.json --rln-relay-cred-index:1 --rln-relay-cred-password:password --rln-relay-eth-client-address:wss://sepolia.infura.io/ws/v3/12345678901234567890123456789012 --ports-shift=2 +./build/chat2 --fleet:test --content-topic:/toy-chat/3/mingde/proto --rln-relay:true --rln-relay-dynamic:true --rln-relay-eth-contract-address:0xF471d71E9b1455bBF4b85d475afb9BB0954A29c4 --rln-relay-cred-path:rlnKeystore.json --rln-relay-cred-index:1 --rln-relay-cred-password:password --rln-relay-eth-client-address:wss://sepolia.infura.io/ws/v3/12345678901234567890123456789012 --ports-shift=2 ``` ``` diff --git a/docs/tutorial/rln-keystore-generator.md b/docs/tutorial/rln-keystore-generator.md new file mode 100644 index 0000000000..869babf365 --- /dev/null +++ b/docs/tutorial/rln-keystore-generator.md @@ -0,0 +1,73 @@ +# rln-keystore-generator + +This document describes how to run and use the `rln-keystore-generator` tool. +It is meant to be used to generate and persist a set of valid RLN credentials to be used with rln-relay. + +## Pre-requisites + +1. An EOA with some ETH to pay for the registration transaction ($PRIVATE_KEY) +2. An RPC endpoint to connect to an Ethereum node ($RPC_URL) + +## Usage + +1. First, we compile the binary + + ```bash + make -j12 rln-keystore-generator + ``` + This command will fetch the rln static library and link it automatically. + + +2. Define the arguments you wish to use + + ```bash + export RPC_URL="https://sepolia.infura.io/v3/..." + export PRIVATE_KEY="0x..." + export RLN_CONTRACT_ADDRESS="0xF471d71E9b1455bBF4b85d475afb9BB0954A29c4" + export RLN_CREDENTIAL_PATH="rlnKeystore.json" + export RLN_CREDENTIAL_PASSWORD="xxx" + ``` + +3. Dry run the command to ensure better degree of execution + + ```bash + ./build/rln_keystore_generator \ + --rln-relay-eth-client-address:$RPC_URL \ + --rln-relay-eth-private-key:$PRIVATE_KEY \ + --rln-relay-eth-contract-address:$RLN_CONTRACT_ADDRESS \ + --rln-relay-cred-path:$RLN_CREDENTIAL_PATH \ + --rln-relay-cred-password:$RLN_CREDENTIAL_PASSWORD + ``` + By default, the tool will not execute a transaction. It will execute only if `--execute` is passed in. + +4. Run the keystore generator with the onchain registration + + ```bash + ./build/rln_keystore_generator \ + --rln-relay-eth-client-address:$RPC_URL \ + --rln-relay-eth-private-key:$PRIVATE_KEY \ + --rln-relay-eth-contract-address:$RLN_CONTRACT_ADDRESS \ + --rln-relay-cred-path:$RLN_CREDENTIAL_PATH \ + --rln-relay-cred-password:$RLN_CREDENTIAL_PASSWORD \ + --execute + ``` + + What this does is - + a. generate a set of valid rln credentials + b. registers it to the contract address provided + c. persists the credentials to the path provided + +5. You may now use this keystore with wakunode2 or chat2. + +## Troubleshooting + +1. `KeystoreCredentialNotFoundError` + + ``` + KeystoreCredentialNotFoundError: Credential not found in keystore + ``` + This is most likely due to multiple credentials present in the same keystore. + To navigate around this, both chat2 and wakunode2 have provided an option to specify the credential index to use (`--rln-relay-membership-index`). + Please use this option with the appropriate tree index of the credential you wish to use. + + diff --git a/tools/rln_keystore_generator/README.md b/tools/rln_keystore_generator/README.md index d982abf2bd..7e909c6175 100644 --- a/tools/rln_keystore_generator/README.md +++ b/tools/rln_keystore_generator/README.md @@ -1,3 +1,3 @@ # rln_keystore_generator -TODO! \ No newline at end of file +Documentation on running the `rln-keystore-generator` can be found [here](../../docs/tutorial/rln-keystore-generator.md) \ No newline at end of file