feat: Audit tooling | NPG-6520

Cargo.toml

@@ -52,7 +52,7 @@ members = [
   "src/vit-testing/scheduler-service-lib",
   "src/voting-tools-rs",
   "src/cat-data-service",
-  "src/tally",
+  "src/audit",
 ]
 
 [workspace.dependencies]

src/audit/Cargo.toml

@@ -0,0 +1,60 @@
+[package]
+name = "audit"
+version = "0.1.0"
+edition = "2021"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+chain-crypto = { path = "../chain-libs/chain-crypto" }
+chain-vote = { path = "../chain-libs/chain-vote" }
+jormungandr-lib = { path = "../jormungandr/jormungandr-lib" }
+chain-addr = { path = "../chain-libs/chain-addr" }
+chain-core = { path = "../chain-libs/chain-core" }
+chain-impl-mockchain = { path = "../chain-libs/chain-impl-mockchain" ,features= ["audit"]}
+chain-ser = { path = "../chain-libs/chain-ser" }
+chain-storage = { path = "../chain-libs/chain-storage" }
+chain-time = { path = "../chain-libs/chain-time" }
+wallet = { path = "../chain-wallet-libs/wallet" }
+
+rand_core = "0.6"
+
+base64 = "0.21.0"
+bech32 = "0.8"
+
+clap = { version = "4", features = ["derive", "cargo"] }
+clap_complete_command = { version = "0.5" }
+
+color-eyre = "0.6"
+thiserror = "1.0.40"
+csv = "1.1"
+hex = "0.4"
+serde = "1.0"
+serde_json = "1.0"
+serde_yaml = "0.8.17"
+tracing.workspace = true
+tracing-subscriber.workspace = true
+rand = "0.8.3"
+
+
+[dev-dependencies]
+rand_chacha = "0.3"
+smoke = "^0.2.1"
+criterion = "0.3"
+chain-crypto = { path = "../chain-libs/chain-crypto", features=["property-test-api"]}
+
+[lib]
+name = "lib"
+path = "src/lib/mod.rs"
+
+[[bin]]
+name = "tally"
+path = "src/tally/bin/main.rs"
+
+[[bin]]
+name = "offline"
+path = "src/offline/bin/main.rs"
+
+[[bin]]
+name = "find"
+path = "src/find/bin/main.rs"

src/audit/README.md

@@ -0,0 +1,42 @@
+# Audit Tooling:
+
+## Offline audit
+
+### Download Fund State
+Download historical fund state from [*here*](https://github.com/input-output-hk/catalyst-core) in order to replay and audit the voting event.
+
+The official published results can be found in this file in the form of **activevoteplans.json**.
+
+**activevoteplans.json** = FINAL RESULTS.
+
+If you would like to re-generate **activevoteplans.json** yourself, via a live node and historical fragments - [*see here for instructions*](./balance/README.md)
+
+If not, you can begin the audit with the following steps.
+
+*Example usage:*
+
+```
+cargo build --release -p audit
+```  
+
+*Cross reference offline tallies with published catalyst tallies.*
+
+```bash
+
+OFFICIAL_RESULTS=/tmp/activevoteplans.json 
+BLOCK0=/tmp/fund9-leader-1/artifacts/block0.bin
+FRAGMENTS_STORAGE=/tmp/fund9-leader-1/persist/leader-1
+
+./target/release/offline --fragments $FRAGMENTS_STORAGE --block0 $BLOCK0 --official-results $OFFICIAL_RESULTS
+
+```
+
+This will create three files:
+- *ledger_after_tally.json* **(decrypted ledger state after tally)** *should match official results!*
+- *ledger_before_tally.json* **(encrypted ledger state before tally)** 
+- *decryption_shares.json* **(decryption shares for each proposal)**
+
+[*See here for next steps of audit process*](src/tally/README.md)
+
+### Find my vote
+[*See here for instructions on how to find your voting history*](src/find/README.md)

src/audit/balance/Earthfile

@@ -0,0 +1,26 @@
+VERSION 0.7
+build:
+    FROM ../../../+builder
+    RUN pwd
+    RUN cargo build --locked --release --bin jormungandr
+
+    # Store the artifact
+    SAVE ARTIFACT target/release/jormungandr jormungandr
+    SAVE IMAGE --cache-hint
+
+docker:
+    FROM ../../../+deployment
+    WORKDIR /app
+    ARG tag="latest"
+    ARG registry
+
+    COPY +build/jormungandr .
+    COPY entry.sh .
+
+    COPY node_config.yaml .
+    RUN chmod +x entry.sh
+    RUN pwd
+    ENV NODE_CONFIG_PATH=/app/node_config.yaml
+    ENV BIN_PATH=/app/jormungandr
+    ENTRYPOINT ["/app/entry.sh"]
+    SAVE IMAGE --push ${registry}jormungandr:$tag

src/audit/balance/README.md

@@ -0,0 +1,40 @@
+### Reproduce published results
+### Start and load live node with historical state
+
+Pre-requisites
+- Install [Earthly CLI](https://earthly.dev/get-earthly)
+- Docker or Podman
+- Git
+
+```bash
+cd balance
+
+# Mount local path as a volume in the container
+MOUNT_PATH=/tmp/fund9-leader-1:/leader1stuff
+
+HISTORICAL_STATE=/leader1stuff/persist/leader-1
+BLOCK_0=/leader1stuff/artifacts/block0.bin
+
+earthly +build && earthly +docker
+docker run  --net=host -v $MOUNT_PATH --env STORAGE_PATH=$HISTORICAL_STATE --env GENESIS_PATH=$BLOCK_0 jormungandr
+```
+
+### Spin up node to retrieve vote results
+
+Takes several minutes to replay state and stabilize before it is possible to retrieve vote results ⌛
+
+Try after ~5 mins, if it has not replayed and stabilized. 
+The following error will be shown - `Internal server error: Blockchain tip not set in REST/RPC context`.
+
+⏳
+
+```bash
+curl http://127.0.0.1:10000/api/v0/vote/active/plans > activevoteplans.json 
+```
+
+**activevoteplans.json** = FINAL RESULTS.
+
+##### Make sure the jormungandr container has been stopped once you have successfully retrieved the results. 
+```bash
+sudo docker docker stop $JORMUNGANDR_CONTAINER_ID
+```

src/audit/balance/entry.sh

@@ -0,0 +1,73 @@
+#!/bin/bash
+
+# Enable strict mode
+set +x
+set -o errexit
+set -o pipefail
+set -o nounset
+set -o functrace
+set -o errtrace
+set -o monitor
+set -o posix
+shopt -s dotglob
+
+echo ">>> Entering entrypoint script..."
+# Verify the storage path exists
+if [[ ! -d "$STORAGE_PATH" ]]; then
+    echo "ERROR: storage path does not exist at: $STORAGE_PATH";
+    echo ">>> Aborting..."
+    exit 1
+fi
+# Verify config is present
+if [[ ! -f "$NODE_CONFIG_PATH" ]]; then
+    echo "ERROR: node configuration is absent at: $NODE_CONFIG_PATH"
+    echo ">>> Aborting..."TH"
+    exit 1
+fi
+# Verify genesis block is present
+if [[ ! -f "$GENESIS_PATH" ]]; then
+    echo "ERROR: genesis block is absent at: $GENESIS_PA
+    echo ">>> Aborting..."
+    exit 1
+fi
+# Allow overriding jormungandr binary
+if [[ ! -f "$BIN_PATH" ]]; then
+    echo "ERROR: path to jormungandr binary is absent at: $BIN_PATH"
+    echo ">>> Aborting..."
+    exit 1
+fi
+echo ">>> Using the following parameters:"
+echo "Storage path: $STORAGE_PATH"
+echo "Node config: $NODE_CONFIG_PATH"
+echo "Genesis block: $GENESIS_PATH"
+echo "Binary path: $BIN_PATH"
+args=()
+args+=("--storage" "$STORAGE_PATH")
+args+=("--config" "$NODE_CONFIG_PATH")
+args+=("--genesis-block" "$GENESIS_PATH")
+
+# Define the command to be executed
+ARGS="${args[*]}"
+EXTRA_ARGS=$*
+CMD="$BIN_PATH $ARGS $EXTRA_ARGS"
+echo ">>> Executing command: $CMD"
+
+# Wait for DEBUG_SLEEP seconds if the DEBUG_SLEEP environment variable is set
+if [ -n "${DEBUG_SLEEP:-}" ]; then
+  echo "DEBUG_SLEEP is set to $DEBUG_SLEEP. Sleeping..."
+  sleep "$DEBUG_SLEEP"
+fi
+
+echo "Starting node..."
+# Expand the command with arguments and capture the exit code
+set +e
+eval "$CMD"
+EXIT_CODE=$?
+set -e
+
+# If the exit code is 0, the executable returned successfully
+if [ $EXIT_CODE -ne 0 ]; then
+  echo "Error: jormungandr returned with exit code $EXIT_CODE"
+  exit 1
+fi
+

src/audit/balance/node_config.yaml

@@ -0,0 +1,29 @@
+---
+rest:
+  listen: "127.0.0.1:10000"
+jrpc:
+  listen: "127.0.0.1:10002"
+p2p:
+  bootstrap:
+    trusted_peers: []
+  connection:
+    public_address: /ip4/127.0.0.1/tcp/10001
+    allow_private_addresses: true
+    whitelist: ~
+  policy:
+    quarantine_duration: 1s
+  layers:
+    topics_of_interest:
+      messages: high
+      blocks: high
+log:
+  format: json
+  level: TRACE
+  output: stdout
+mempool:
+  pool_max_entries: 10000
+  log_max_entries: 100000
+  persistent_log: ~
+bootstrap_from_trusted_peers: false
+skip_bootstrap: true
+

src/audit/src/find/README.md

@@ -0,0 +1,22 @@
+### Find my vote
+
+Retrieve voting key history and metadata via offline fragment analysis replay.    
+
+*Example usage:*
+
+```
+cargo build --release -p audit
+```  
+
+Voting key is present in the first field as per defined in [CIP-36](https://cips.cardano.org/cips/cip36/); user is given a link to cardanoscan after they vote, their voting key is present in the [metadata, e.g](https://cardanoscan.io/transaction/9f3706e8b26bc0c88ef74e0b020bf148dc90301e3a1e3c465db1f4d206729b7b?tab=metadata)
+
+
+```bash
+
+VOTING_KEY='e5b0a5c250f78b574b8b17283bcc6c7692f72fc58090f4a0a2362497d28d1a85'
+FRAGMENTS_STORAGE=/tmp/fund9-leader-1/persist/leader-1
+
+./target/release/find --fragments $FRAGMENTS_STORAGE --voting-key $VOTING_KEY
+
+```
+