From bf02b14547fb6e11e777c56f41d121f2489a340c Mon Sep 17 00:00:00 2001
From: Xendarboh <1435589+xendarboh@users.noreply.github.com>
Date: Tue, 29 Oct 2024 16:50:36 -0700
Subject: [PATCH 01/21] feat(genconfig): add option to set binary prefix

---
 genconfig/genconfig.go | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)

diff --git a/genconfig/genconfig.go b/genconfig/genconfig.go
index dfffc98..753a1ca 100644
--- a/genconfig/genconfig.go
+++ b/genconfig/genconfig.go
@@ -51,6 +51,7 @@ type GenconfigInput struct {
 	addrBind         string
 	baseDir          string
 	basePort         int
+	binPrefix        string
 	binSuffix        string
 	cfgType          string
 	identifier       string
@@ -64,6 +65,7 @@ type GenconfigInput struct {
 type katzenpost struct {
 	baseDir   string
 	outDir    string
+	binPrefix string
 	binSuffix string
 	logLevel  string
 	logWriter io.Writer
@@ -313,7 +315,7 @@ func (s *katzenpost) genNodeConfig(identifier string, isGateway bool, isServiceN
 		spoolCfg := &sConfig.CBORPluginKaetzchen{
 			Capability:     "spool",
 			Endpoint:       "+spool",
-			Command:        s.baseDir + "/memspool" + s.binSuffix,
+			Command:        s.binPrefix + "memspool" + s.binSuffix,
 			MaxConcurrency: 1,
 			Config: map[string]interface{}{
 				"data_store": s.baseDir + "/" + cfg.Server.Identifier + "/memspool.storage",
@@ -325,7 +327,7 @@ func (s *katzenpost) genNodeConfig(identifier string, isGateway bool, isServiceN
 			mapCfg := &sConfig.CBORPluginKaetzchen{
 				Capability:     "pigeonhole",
 				Endpoint:       "+pigeonhole",
-				Command:        s.baseDir + "/pigeonhole" + s.binSuffix,
+				Command:        s.binPrefix + "pigeonhole" + s.binSuffix,
 				MaxConcurrency: 1,
 				Config: map[string]interface{}{
 					"db":      s.baseDir + "/" + cfg.Server.Identifier + "/map.storage",
@@ -338,7 +340,7 @@ func (s *katzenpost) genNodeConfig(identifier string, isGateway bool, isServiceN
 				pandaCfg := &sConfig.CBORPluginKaetzchen{
 					Capability:     "panda",
 					Endpoint:       "+panda",
-					Command:        s.baseDir + "/panda_server" + s.binSuffix,
+					Command:        s.binPrefix + "panda_server" + s.binSuffix,
 					MaxConcurrency: 1,
 					Config: map[string]interface{}{
 						"fileStore": s.baseDir + "/" + cfg.Server.Identifier + "/panda.storage",
@@ -355,7 +357,7 @@ func (s *katzenpost) genNodeConfig(identifier string, isGateway bool, isServiceN
 				proxyCfg := &sConfig.CBORPluginKaetzchen{
 					Capability:     "http",
 					Endpoint:       "+http",
-					Command:        s.baseDir + "/proxy_server" + s.binSuffix,
+					Command:        s.binPrefix + "proxy_server" + s.binSuffix,
 					MaxConcurrency: 1,
 					Config: map[string]interface{}{
 						// allow connections to localhost:4242
@@ -483,6 +485,7 @@ func ParseFlags() GenconfigInput {
 	flag.StringVar(&gi.addr, "address", addr, "Address to publish (and bind to if -address-bind not set)")
 	flag.StringVar(&gi.addrBind, "address-bind", "", "Address to bind to")
 	flag.StringVar(&gi.baseDir, "dir-base", "", "Absolute path as installation directory in config files (default -dir-out)")
+	flag.StringVar(&gi.binPrefix, "binary-prefix", "", "Prefix for binaries")
 	flag.StringVar(&gi.binSuffix, "binary-suffix", "", "Suffix for binaries")
 	flag.StringVar(&gi.cfgType, "type", "", "Type of config to generate: mix, gateway, servicenode, client1, client2")
 	flag.StringVar(&gi.identifier, "identifier", "", "Node identifier; lowercase alphanumeric with 4 to 20 characters (default -type)")
@@ -515,6 +518,7 @@ func Genconfig(gi GenconfigInput) error {
 	addrBind := &gi.addrBind
 	baseDir := &gi.baseDir
 	basePort := &gi.basePort
+	binPrefix := &gi.binPrefix
 	binSuffix := &gi.binSuffix
 	cfgType := &gi.cfgType
 	identifier := &gi.identifier
@@ -617,6 +621,7 @@ func Genconfig(gi GenconfigInput) error {
 
 	s.baseDir = *baseDir
 	s.outDir = *outDir
+	s.binPrefix = *binPrefix
 	s.binSuffix = *binSuffix
 	s.basePort = uint16(*basePort)
 	s.lastPort = s.basePort + 1

From 0f8eb906153b9cf3e108f5f6c1197665aa2bc913 Mon Sep 17 00:00:00 2001
From: Xendarboh <1435589+xendarboh@users.noreply.github.com>
Date: Wed, 30 Oct 2024 11:28:14 -0700
Subject: [PATCH 02/21] feat(genconfig): configure http_proxy ServiceNode
 plugin

---
 genconfig/genconfig.go | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/genconfig/genconfig.go b/genconfig/genconfig.go
index 753a1ca..ed16ec8 100644
--- a/genconfig/genconfig.go
+++ b/genconfig/genconfig.go
@@ -369,6 +369,21 @@ func (s *katzenpost) genNodeConfig(identifier string, isGateway bool, isServiceN
 				cfg.ServiceNode.CBORPluginKaetzchen = append(cfg.ServiceNode.CBORPluginKaetzchen, proxyCfg)
 				s.hasProxy = true
 			}
+
+			// 0KN JSON RPC - HTTP Proxy
+			httpProxyCfg := &sConfig.CBORPluginKaetzchen{
+				Capability:     "http_proxy",
+				Endpoint:       "http_proxy",
+				Command:        s.binPrefix + "http_proxy" + s.binSuffix,
+				MaxConcurrency: 1,
+				Disable:        false,
+				Config: map[string]interface{}{
+					"config":  s.binPrefix + "http_proxy_config.toml",
+					"log_dir": s.baseDir + "/" + cfg.Server.Identifier,
+				},
+			}
+			cfg.ServiceNode.CBORPluginKaetzchen = append(cfg.ServiceNode.CBORPluginKaetzchen, httpProxyCfg)
+
 			cfg.Debug.NumKaetzchenWorkers = 4
 		}
 

From 6788c44bd58d5312ba7eb3b40bdf263e021a470c Mon Sep 17 00:00:00 2001
From: Xendarboh <1435589+xendarboh@users.noreply.github.com>
Date: Fri, 25 Oct 2024 15:25:49 -0700
Subject: [PATCH 03/21] feat(docker): add node/Dockerfile and Makefile.appchain

---
 .dockerignore            |  5 +++
 docker/Makefile.appchain | 51 ++++++++++++++++++++++++++++++
 docker/node/Dockerfile   | 67 ++++++++++++++++++++++++++++++++++++++++
 3 files changed, 123 insertions(+)
 create mode 100644 .dockerignore
 create mode 100644 docker/Makefile.appchain
 create mode 100644 docker/node/Dockerfile

diff --git a/.dockerignore b/.dockerignore
new file mode 100644
index 0000000..b40c49e
--- /dev/null
+++ b/.dockerignore
@@ -0,0 +1,5 @@
+.git
+.gitignore
+docker/Makefile.appchain
+docker/node/
+docker/*.sh
diff --git a/docker/Makefile.appchain b/docker/Makefile.appchain
new file mode 100644
index 0000000..bc11eb7
--- /dev/null
+++ b/docker/Makefile.appchain
@@ -0,0 +1,51 @@
+net ?= /tmp/appchain-mixnet
+base := /mixnet
+docker_image ?= zkn/node:latest
+docker_user ?= $(shell [ "$(docker)" = "podman" ] && echo 0:0 || echo $${SUDO_UID:-$$(id -u)}:$${SUDO_GID:-$$(id -g)})
+docker := $(shell if which podman|grep -q .; then echo podman; else echo docker; fi)
+docker_compose ?= DOCKER_USER=$(docker_user) $(shell if which podman|grep -q .; then echo DOCKER_HOST="unix://$$XDG_RUNTIME_DIR/podman/podman.sock"; fi) docker compose
+docker_args := --user ${docker_user}
+docker_run := $(docker) run $(docker_args) --network=host --rm --volume $(shell readlink -f $(net)):$(base)
+
+num_mixes=3
+num_gateways=1
+num_servicenodes=1
+
+export
+
+$(net):
+	mkdir -vp $(net)
+
+image: $(net)/image.stamp
+$(net)/image.stamp: $(net)
+	$(docker) build -t $(docker_image) -f ./node/Dockerfile ../
+	touch $(net)/image.stamp
+
+config: $(net)/docker-compose.yml
+$(net)/docker-compose.yml: $(net) $(net)/image.stamp
+	./genconfig.sh
+
+start: config image $(net)/run.stamp
+$(net)/run.stamp:
+	cd $(net); $(docker_compose) up --remove-orphans -d; $(docker) compose top
+	touch $(net)/run.stamp
+
+wait: $(net)/run.stamp
+	$(docker_run) $(docker_image) /opt/zkn/fetch -f $(base)/client/client.toml
+
+probe: $(net)/run.stamp
+	$(docker_run) $(docker_image) /opt/zkn/walletshield \
+		-config $(base)/client2/client.toml \
+		-log_level DEBUG \
+		-probe \
+		-probe_count 1
+
+.PHONY: stop
+stop:
+	[ -e $(net) ] && cd $(net) && $(docker_compose) down --remove-orphans
+	rm -fv $(net)/run.stamp
+
+.PHONY: clean
+clean: stop
+	$(docker) rmi $(docker_image)
+	rm -fv $(net)/image.stamp
diff --git a/docker/node/Dockerfile b/docker/node/Dockerfile
new file mode 100644
index 0000000..29c2e55
--- /dev/null
+++ b/docker/node/Dockerfile
@@ -0,0 +1,67 @@
+FROM ubuntu:latest AS builder
+
+ARG VERSION_GO=1.22.3
+ARG KATZENPOST_DIR=/tmp/katzenpost.opt
+ARG ENABLE_WARPED_EPOCH=true
+
+ENV GOROOT=/usr/local/go
+ENV PATH=$GOROOT/bin:$PATH
+ENV GOCACHE=/root/.cache/go-build
+ENV GO_BUILD_OPTS="-trimpath -ldflags=-buildid= -ldflags=-X=github.com/katzenpost/katzenpost/core/epochtime.WarpedEpoch=${ENABLE_WARPED_EPOCH}"
+
+# Install build dependencies
+RUN apt-get update && apt-get install -y \
+  build-essential \
+  git \
+  wget \
+  && rm -rf /var/lib/apt/lists/*
+
+# Install Go
+RUN f=go${VERSION_GO}.linux-amd64.tar.gz \
+  && wget https://dl.google.com/go/${f} \
+  && tar -C /usr/local -xzf ${f} \
+  && rm ${f}
+
+# Copy the project source
+COPY . /src
+
+# Build Katzenpost components
+RUN --mount=type=cache,target="${GOCACHE}" \
+  mkdir /dest \
+  # clone 0KN opt-specific katzenpost branch
+  && make katzenpost_dir=${KATZENPOST_DIR} -C /src/docker clone-katzenpost \
+  # a function to build and move the binary
+  && build() { cd ${KATZENPOST_DIR}/$1 ; b=$(basename $1) ; go build ${GO_BUILD_OPTS} ; chmod u+x $b ; mv $b /dest/$2; } \
+  # clients
+  && build authority/cmd/fetch fetch \
+  && build ping ping \
+  # server
+  && build server/cmd/server server \
+  ## servicenode plugins
+  && build http/proxy/client proxy_client \
+  && build http/proxy/server proxy_server \
+  && build memspool/server/cmd/memspool memspool \
+  && build pigeonhole/server/cmd/pigeonhole pigeonhole \
+  && build panda/server/cmd/panda_server panda_server \
+  && build server_plugins/cbor_plugins/echo-go echo_server
+
+# Build 0KN mix network components
+RUN --mount=type=cache,target="${GOCACHE}" \
+  # a function to build and move the binary
+  build() { cd /src/$1 ; b=$(basename $1) ; go build ${GO_BUILD_OPTS} ; chmod u+x $b ; mv $b /dest/$2; } \
+  # pki
+  && build pki pki \
+  # genconfig
+  && build genconfig/cmd/genconfig genconfig \
+  # servicenode plugin: http_proxy
+  && build server_plugins/cbor_plugins/http_proxy/cmd/http_proxy http_proxy \
+  && cp /src/server_plugins/cbor_plugins/http_proxy/http_proxy_config.toml /dest/ \
+  # clients
+  && build apps/walletshield walletshield
+
+
+FROM ubuntu:latest AS node
+
+COPY --from=builder /dest /opt/zkn
+
+CMD ["/bin/bash"]

From caea4f254c096711c72d61bfc1bfcbfd2caff97b Mon Sep 17 00:00:00 2001
From: Xendarboh <1435589+xendarboh@users.noreply.github.com>
Date: Wed, 30 Oct 2024 11:37:38 -0700
Subject: [PATCH 04/21] feat(docker): update genconfig

---
 docker/genconfig.sh | 63 +++++++++++++++++++++------------------------
 1 file changed, 29 insertions(+), 34 deletions(-)

diff --git a/docker/genconfig.sh b/docker/genconfig.sh
index bb9d2d4..8d6dc85 100755
--- a/docker/genconfig.sh
+++ b/docker/genconfig.sh
@@ -1,31 +1,30 @@
 #!/bin/bash
 
-# This script is invoked by ./Makefile to generate config files for a local
-# test network using appchain pki. Variables set by the Makefile are read from
-# the environment. This is intended to be run from within the katzenpost docker
-# container.
+# This script is invoked by ./Makefile to generate a docker-compose.yml file
+# for a local test network using appchain pki. Variables set by the Makefile
+# are read from the environment.
 
 port=30000
-dir_base="/${net_name}"
-dir_out=${dir_base}
-binary_suffix=".${distro}"
-
-rm -rf ${dir_out} && mkdir -p ${dir_out}
+dir_base=${base}
+dir_out=${net}
+binary_prefix="/opt/zkn/"
 
 echo "Generating config files for local network:"
-echo "  num gateways: ${gateways}"
-echo "  num servicenodes: ${serviceNodes}"
-echo "  num mixes: ${mixes}"
-echo "  binary-suffix: ${binary_suffix}"
-echo "  distro: ${distro}"
-echo "  dir-base: ${dir_base}"
-echo "  dir-out: ${dir_out}"
-
-gencfg="../genconfig/cmd/genconfig/genconfig \
-  -input ./network.yml \
-  -binary-suffix ${binary_suffix} \
-  -dir-base ${dir_base} \
-  -dir-out ${dir_out}"
+echo "  num_gateways: ${num_gateways}"
+echo "  num_servicenodes: ${num_servicenodes}"
+echo "  num_mixes: ${num_mixes}"
+
+gencfg="${docker} run ${docker_args} --rm \
+  --volume $(readlink -f ./network.yml):/tmp/network.yml \
+  --volume $(readlink -f ${dir_out}):${dir_base} \
+  ${docker_image} \
+  ${binary_prefix}genconfig \
+    -input /tmp/network.yml \
+    -binary-prefix ${binary_prefix} \
+    -dir-base ${dir_base} \
+    -dir-out ${dir_base}"
+
+echo "genconfig: ${gencfg}"
 
 cat <<EOF > ${dir_out}/prometheus.yml
 scrape_configs:
@@ -38,9 +37,9 @@ EOF
 cat <<EOF > ${dir_out}/docker-compose.yml
 x-common-service: &common-service
   restart: "no"
-  image: katzenpost-${distro}_base
+  image: ${docker_image}
   volumes:
-    - ./:${dir_base}
+    - ${dir_out}:${dir_base}
   network_mode: host
 
 services:
@@ -49,7 +48,7 @@ services:
     restart: "no"
     image: docker.io/prom/prometheus
     volumes:
-      - ./:${dir_base}
+      - ${dir_out}:${dir_base}
     command: --config.file="${dir_base}/prometheus.yml"
     network_mode: host
 
@@ -67,21 +66,17 @@ function gencfg_node () {
   cat <<EOF >> ${dir_out}/docker-compose.yml
   ${id}-auth:
     <<: *common-service
-    command: ${dir_base}/pki${binary_suffix} -f ${dir_base}/${id}-auth/authority.toml
+    command: ${binary_prefix}pki -f ${dir_base}/${id}-auth/authority.toml
 
   ${id}:
     <<: *common-service
-    command: ${dir_base}/server${binary_suffix} -f ${dir_base}/${id}/katzenpost.toml
+    command: ${binary_prefix}server -f ${dir_base}/${id}/katzenpost.toml
     depends_on:
       - ${id}-auth
 
 EOF
 }
 
-for i in $(seq 1 ${gateways}); do gencfg_node gateway ${i}; done
-for i in $(seq 1 ${serviceNodes}); do gencfg_node servicenode ${i}; done
-for i in $(seq 1 ${mixes}); do gencfg_node mix ${i}; done
-
-# FIXME: client*/config.toml generated with, to include, gateway('s auth)
-# ${gc} -type client1
-# ${gc} -type client2
+for i in $(seq 1 ${num_gateways}); do gencfg_node gateway ${i}; done
+for i in $(seq 1 ${num_servicenodes}); do gencfg_node servicenode ${i}; done
+for i in $(seq 1 ${num_mixes}); do gencfg_node mix ${i}; done

From 1ea30dd1851571154367cbc2dc9532940ac76c42 Mon Sep 17 00:00:00 2001
From: Xendarboh <1435589+xendarboh@users.noreply.github.com>
Date: Wed, 30 Oct 2024 12:51:27 -0700
Subject: [PATCH 05/21] feat(docker): conform variable names

---
 docker/Makefile.appchain | 23 +++++++++++++++--------
 docker/genconfig.sh      | 15 ++++++++-------
 docker/node/Dockerfile   |  8 +++++---
 3 files changed, 28 insertions(+), 18 deletions(-)

diff --git a/docker/Makefile.appchain b/docker/Makefile.appchain
index bc11eb7..66f9090 100644
--- a/docker/Makefile.appchain
+++ b/docker/Makefile.appchain
@@ -1,12 +1,14 @@
 net ?= /tmp/appchain-mixnet
-base := /mixnet
+dir_base := /mixnet
+dir_bin := /opt/zkn
 docker_image ?= zkn/node:latest
-docker_user ?= $(shell [ "$(docker)" = "podman" ] && echo 0:0 || echo $${SUDO_UID:-$$(id -u)}:$${SUDO_GID:-$$(id -g)})
 docker := $(shell if which podman|grep -q .; then echo podman; else echo docker; fi)
+docker_user ?= $(shell [ "$(docker)" = "podman" ] && echo 0:0 || echo $${SUDO_UID:-$$(id -u)}:$${SUDO_GID:-$$(id -g)})
 docker_compose ?= DOCKER_USER=$(docker_user) $(shell if which podman|grep -q .; then echo DOCKER_HOST="unix://$$XDG_RUNTIME_DIR/podman/podman.sock"; fi) docker compose
 docker_args := --user ${docker_user}
-docker_run := $(docker) run $(docker_args) --network=host --rm --volume $(shell readlink -f $(net)):$(base)
+docker_run := $(docker) run $(docker_args) --network=host --rm --volume $(shell readlink -f $(net)):$(dir_base)
 
+warped?=true
 num_mixes=3
 num_gateways=1
 num_servicenodes=1
@@ -18,7 +20,12 @@ $(net):
 
 image: $(net)/image.stamp
 $(net)/image.stamp: $(net)
-	$(docker) build -t $(docker_image) -f ./node/Dockerfile ../
+	$(docker) build \
+		--build-arg DIR_BIN=$(dir_bin) \
+		--build-arg ENABLE_WARPED_EPOCH=$(warped) \
+		--file ./node/Dockerfile \
+		--tag $(docker_image) \
+		../
 	touch $(net)/image.stamp
 
 config: $(net)/docker-compose.yml
@@ -31,11 +38,11 @@ $(net)/run.stamp:
 	touch $(net)/run.stamp
 
 wait: $(net)/run.stamp
-	$(docker_run) $(docker_image) /opt/zkn/fetch -f $(base)/client/client.toml
+	$(docker_run) $(docker_image) $(dir_bin)/fetch -f $(dir_base)/client/client.toml
 
 probe: $(net)/run.stamp
-	$(docker_run) $(docker_image) /opt/zkn/walletshield \
-		-config $(base)/client2/client.toml \
+	$(docker_run) $(docker_image) $(dir_bin)/walletshield \
+		-config $(dir_base)/client2/client.toml \
 		-log_level DEBUG \
 		-probe \
 		-probe_count 1
@@ -48,4 +55,4 @@ stop:
 .PHONY: clean
 clean: stop
 	$(docker) rmi $(docker_image)
-	rm -fv $(net)/image.stamp
+	rm -rfv $(net)
diff --git a/docker/genconfig.sh b/docker/genconfig.sh
index 8d6dc85..36cad25 100755
--- a/docker/genconfig.sh
+++ b/docker/genconfig.sh
@@ -1,15 +1,16 @@
-#!/bin/bash
+#!/bin/bash -e
 
 # This script is invoked by ./Makefile to generate a docker-compose.yml file
 # for a local test network using appchain pki. Variables set by the Makefile
 # are read from the environment.
 
 port=30000
-dir_base=${base}
 dir_out=${net}
-binary_prefix="/opt/zkn/"
 
 echo "Generating config files for local network:"
+echo "  dir_base: ${dir_base}"
+echo "  dir_bin: ${dir_bin}"
+echo "  dir_out: ${dir_out}"
 echo "  num_gateways: ${num_gateways}"
 echo "  num_servicenodes: ${num_servicenodes}"
 echo "  num_mixes: ${num_mixes}"
@@ -18,9 +19,9 @@ gencfg="${docker} run ${docker_args} --rm \
   --volume $(readlink -f ./network.yml):/tmp/network.yml \
   --volume $(readlink -f ${dir_out}):${dir_base} \
   ${docker_image} \
-  ${binary_prefix}genconfig \
+  ${dir_bin}/genconfig \
     -input /tmp/network.yml \
-    -binary-prefix ${binary_prefix} \
+    -binary-prefix ${dir_bin}/ \
     -dir-base ${dir_base} \
     -dir-out ${dir_base}"
 
@@ -66,11 +67,11 @@ function gencfg_node () {
   cat <<EOF >> ${dir_out}/docker-compose.yml
   ${id}-auth:
     <<: *common-service
-    command: ${binary_prefix}pki -f ${dir_base}/${id}-auth/authority.toml
+    command: ${dir_bin}/pki -f ${dir_base}/${id}-auth/authority.toml
 
   ${id}:
     <<: *common-service
-    command: ${binary_prefix}server -f ${dir_base}/${id}/katzenpost.toml
+    command: ${dir_bin}/server -f ${dir_base}/${id}/katzenpost.toml
     depends_on:
       - ${id}-auth
 
diff --git a/docker/node/Dockerfile b/docker/node/Dockerfile
index 29c2e55..533a982 100644
--- a/docker/node/Dockerfile
+++ b/docker/node/Dockerfile
@@ -1,8 +1,8 @@
 FROM ubuntu:latest AS builder
 
-ARG VERSION_GO=1.22.3
-ARG KATZENPOST_DIR=/tmp/katzenpost.opt
 ARG ENABLE_WARPED_EPOCH=true
+ARG KATZENPOST_DIR=/tmp/katzenpost.opt
+ARG VERSION_GO=1.22.3
 
 ENV GOROOT=/usr/local/go
 ENV PATH=$GOROOT/bin:$PATH
@@ -62,6 +62,8 @@ RUN --mount=type=cache,target="${GOCACHE}" \
 
 FROM ubuntu:latest AS node
 
-COPY --from=builder /dest /opt/zkn
+ARG DIR_BIN=/opt/zkn
+
+COPY --from=builder /dest ${DIR_BIN}
 
 CMD ["/bin/bash"]

From 1fe7567b99c2690820c93d3cf9651cddc6d9cd0f Mon Sep 17 00:00:00 2001
From: Xendarboh <1435589+xendarboh@users.noreply.github.com>
Date: Wed, 30 Oct 2024 14:05:43 -0700
Subject: [PATCH 06/21] feat(docker): compose: set docker user

---
 docker/genconfig.sh | 1 +
 1 file changed, 1 insertion(+)

diff --git a/docker/genconfig.sh b/docker/genconfig.sh
index 36cad25..390261c 100755
--- a/docker/genconfig.sh
+++ b/docker/genconfig.sh
@@ -39,6 +39,7 @@ cat <<EOF > ${dir_out}/docker-compose.yml
 x-common-service: &common-service
   restart: "no"
   image: ${docker_image}
+  user: ${docker_user}
   volumes:
     - ${dir_out}:${dir_base}
   network_mode: host

From 1ae7bfbf2cc6f9c7ed4a8c6ffc048d86099270de Mon Sep 17 00:00:00 2001
From: Xendarboh <1435589+xendarboh@users.noreply.github.com>
Date: Fri, 1 Nov 2024 18:05:44 -0700
Subject: [PATCH 07/21] feat(docker): add configurable probe_count to Makefile

---
 docker/Makefile.appchain | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/docker/Makefile.appchain b/docker/Makefile.appchain
index 66f9090..49e5a4a 100644
--- a/docker/Makefile.appchain
+++ b/docker/Makefile.appchain
@@ -13,6 +13,8 @@ num_mixes=3
 num_gateways=1
 num_servicenodes=1
 
+probe_count ?= 1
+
 export
 
 $(net):
@@ -45,7 +47,7 @@ probe: $(net)/run.stamp
 		-config $(dir_base)/client2/client.toml \
 		-log_level DEBUG \
 		-probe \
-		-probe_count 1
+		-probe_count $(probe_count)
 
 .PHONY: stop
 stop:

From 89518b38993f058f8f1ffaf348e3c9fb6f1b469c Mon Sep 17 00:00:00 2001
From: Xendarboh <1435589+xendarboh@users.noreply.github.com>
Date: Fri, 1 Nov 2024 18:07:10 -0700
Subject: [PATCH 08/21] feat(docker): add support for docker agent image

---
 docker/Makefile.appchain |  3 ++-
 docker/genconfig.sh      | 18 ++++++++++++++++++
 2 files changed, 20 insertions(+), 1 deletion(-)

diff --git a/docker/Makefile.appchain b/docker/Makefile.appchain
index 49e5a4a..b62d395 100644
--- a/docker/Makefile.appchain
+++ b/docker/Makefile.appchain
@@ -2,6 +2,7 @@ net ?= /tmp/appchain-mixnet
 dir_base := /mixnet
 dir_bin := /opt/zkn
 docker_image ?= zkn/node:latest
+docker_image_agent ?= zkn/agent:latest
 docker := $(shell if which podman|grep -q .; then echo podman; else echo docker; fi)
 docker_user ?= $(shell [ "$(docker)" = "podman" ] && echo 0:0 || echo $${SUDO_UID:-$$(id -u)}:$${SUDO_GID:-$$(id -g)})
 docker_compose ?= DOCKER_USER=$(docker_user) $(shell if which podman|grep -q .; then echo DOCKER_HOST="unix://$$XDG_RUNTIME_DIR/podman/podman.sock"; fi) docker compose
@@ -31,7 +32,7 @@ $(net)/image.stamp: $(net)
 	touch $(net)/image.stamp
 
 config: $(net)/docker-compose.yml
-$(net)/docker-compose.yml: $(net) $(net)/image.stamp
+$(net)/docker-compose.yml: genconfig.sh $(net) $(net)/image.stamp
 	./genconfig.sh
 
 start: config image $(net)/run.stamp
diff --git a/docker/genconfig.sh b/docker/genconfig.sh
index 390261c..7cea9e8 100755
--- a/docker/genconfig.sh
+++ b/docker/genconfig.sh
@@ -11,6 +11,8 @@ echo "Generating config files for local network:"
 echo "  dir_base: ${dir_base}"
 echo "  dir_bin: ${dir_bin}"
 echo "  dir_out: ${dir_out}"
+echo "  docker_image: ${docker_image}"
+echo "  docker_image_agent: ${docker_image_agent}"
 echo "  num_gateways: ${num_gateways}"
 echo "  num_servicenodes: ${num_servicenodes}"
 echo "  num_mixes: ${num_mixes}"
@@ -66,9 +68,25 @@ function gencfg_node () {
   port=$((port+2))
 
   cat <<EOF >> ${dir_out}/docker-compose.yml
+  ${id}-agent:
+    <<: *common-service
+    image: ${docker_image_agent}
+    command: >
+      pnpm run agent \
+        --ipfs \
+        --ipfs-data ${dir_base}/ipfs-data \
+        --listen \
+        --key ${dir_base}/${id}-auth/appchain.key \
+        --socket ${dir_base}/${id}-auth/appchain.sock \
+        --socket-format cbor \
+        --tx-status-retries 20 \
+        --debug
+
   ${id}-auth:
     <<: *common-service
     command: ${dir_bin}/pki -f ${dir_base}/${id}-auth/authority.toml
+    depends_on:
+      - ${id}-agent
 
   ${id}:
     <<: *common-service

From 13a8a3768a4d2f785ecd6edc466709d71dddf3c2 Mon Sep 17 00:00:00 2001
From: Xendarboh <1435589+xendarboh@users.noreply.github.com>
Date: Sun, 3 Nov 2024 07:38:03 -0800
Subject: [PATCH 09/21] fix(docker): genconfig.sh: set metrics endpoint

---
 docker/genconfig.sh | 14 +++++++++++---
 1 file changed, 11 insertions(+), 3 deletions(-)

diff --git a/docker/genconfig.sh b/docker/genconfig.sh
index 7cea9e8..adfeee5 100755
--- a/docker/genconfig.sh
+++ b/docker/genconfig.sh
@@ -61,11 +61,19 @@ EOF
 function gencfg_node () {
   type=${1}
   id=${type}${2}
+  metrics="127.0.0.1:$((port+2))"
 
-  ${gencfg} -port ${port} -type ${type} -identifier ${id} || exit 1
+  ${gencfg} \
+    -type ${type} \
+    -identifier ${id} \
+    -metrics ${metrics} \
+    -port ${port} \
+    || exit 1
 
-  echo "    - 127.0.0.1:${port}" >> ${dir_out}/prometheus.yml
-  port=$((port+2))
+  echo "    - ${metrics}" >> ${dir_out}/prometheus.yml
+
+  # increment port for the next node
+  port=$((port+10))
 
   cat <<EOF >> ${dir_out}/docker-compose.yml
   ${id}-agent:

From e002556fb22fbf785be98ee09abb71e79de850e5 Mon Sep 17 00:00:00 2001
From: Xendarboh <1435589+xendarboh@users.noreply.github.com>
Date: Mon, 4 Nov 2024 12:35:52 -0800
Subject: [PATCH 10/21] chore(docker): network.yml: disable client decoy
 traffic for local dev network

---
 docker/network.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docker/network.yml b/docker/network.yml
index 85e4bc9..124466e 100644
--- a/docker/network.yml
+++ b/docker/network.yml
@@ -1,6 +1,6 @@
 # Example network configuration file; configures local test network using appchain pki
 build_datetime: '1728353595'
-kp_client_debug_DisableDecoyTraffic: false
+kp_client_debug_DisableDecoyTraffic: true
 kp_client_debug_EnableTimeSync: false
 kp_client_debug_InitialMaxPKIRetrievalDelay: 0
 kp_client_debug_PollingInterval: 0

From 8d8003e174de56e93a76bb2e377d11039109dad5 Mon Sep 17 00:00:00 2001
From: Xendarboh <1435589+xendarboh@users.noreply.github.com>
Date: Mon, 4 Nov 2024 12:39:22 -0800
Subject: [PATCH 11/21] feat(docker): Makefile: add _start target that does not
 rebuild/reconfig

---
 docker/Makefile.appchain | 1 +
 1 file changed, 1 insertion(+)

diff --git a/docker/Makefile.appchain b/docker/Makefile.appchain
index b62d395..b2e32e8 100644
--- a/docker/Makefile.appchain
+++ b/docker/Makefile.appchain
@@ -35,6 +35,7 @@ config: $(net)/docker-compose.yml
 $(net)/docker-compose.yml: genconfig.sh $(net) $(net)/image.stamp
 	./genconfig.sh
 
+_start: $(net)/run.stamp
 start: config image $(net)/run.stamp
 $(net)/run.stamp:
 	cd $(net); $(docker_compose) up --remove-orphans -d; $(docker) compose top

From 35e01e60f9f4727deffb3b7d8518f8f45ca941c7 Mon Sep 17 00:00:00 2001
From: Xendarboh <1435589+xendarboh@users.noreply.github.com>
Date: Mon, 4 Nov 2024 13:00:41 -0800
Subject: [PATCH 12/21] feat(docker): node/Dockerfile: use cache mount for apt

---
 docker/node/Dockerfile | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/docker/node/Dockerfile b/docker/node/Dockerfile
index 533a982..ce6f956 100644
--- a/docker/node/Dockerfile
+++ b/docker/node/Dockerfile
@@ -10,11 +10,14 @@ ENV GOCACHE=/root/.cache/go-build
 ENV GO_BUILD_OPTS="-trimpath -ldflags=-buildid= -ldflags=-X=github.com/katzenpost/katzenpost/core/epochtime.WarpedEpoch=${ENABLE_WARPED_EPOCH}"
 
 # Install build dependencies
-RUN apt-get update && apt-get install -y \
+RUN \
+  --mount=type=cache,target=/var/cache/apt \
+  --mount=type=cache,target=/var/lib/apt \
+  apt-get update && apt-get install -y --no-install-recommends \
   build-essential \
+  ca-certificates \
   git \
-  wget \
-  && rm -rf /var/lib/apt/lists/*
+  wget
 
 # Install Go
 RUN f=go${VERSION_GO}.linux-amd64.tar.gz \

From eb0bc36f2b7166af7932097bd5ac9c43afb524c7 Mon Sep 17 00:00:00 2001
From: Xendarboh <1435589+xendarboh@users.noreply.github.com>
Date: Mon, 4 Nov 2024 13:02:49 -0800
Subject: [PATCH 13/21] feat(docker): node/Dockerfile: facilitate overloading
 of cloned katzenpost dir

---
 docker/node/Dockerfile | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docker/node/Dockerfile b/docker/node/Dockerfile
index ce6f956..a57d214 100644
--- a/docker/node/Dockerfile
+++ b/docker/node/Dockerfile
@@ -1,7 +1,7 @@
 FROM ubuntu:latest AS builder
 
 ARG ENABLE_WARPED_EPOCH=true
-ARG KATZENPOST_DIR=/tmp/katzenpost.opt
+ARG KATZENPOST_DIR=/src/katzenpost
 ARG VERSION_GO=1.22.3
 
 ENV GOROOT=/usr/local/go
@@ -31,8 +31,8 @@ COPY . /src
 # Build Katzenpost components
 RUN --mount=type=cache,target="${GOCACHE}" \
   mkdir /dest \
-  # clone 0KN opt-specific katzenpost branch
-  && make katzenpost_dir=${KATZENPOST_DIR} -C /src/docker clone-katzenpost \
+  # clone 0KN opt-specific katzenpost branch, if one does not exist
+  && if [ ! -d "${KATZENPOST_DIR}" ]; then make katzenpost_dir=${KATZENPOST_DIR} -C /src/docker clone-katzenpost ; fi \
   # a function to build and move the binary
   && build() { cd ${KATZENPOST_DIR}/$1 ; b=$(basename $1) ; go build ${GO_BUILD_OPTS} ; chmod u+x $b ; mv $b /dest/$2; } \
   # clients

From 708c81f5ae3aa8f405b13813ff9a019cfda16186 Mon Sep 17 00:00:00 2001
From: Xendarboh <1435589+xendarboh@users.noreply.github.com>
Date: Mon, 4 Nov 2024 15:45:40 -0800
Subject: [PATCH 14/21] revert(docker/Makefile): restore pki=voting only
 (pki=appchain uses Makefile.appchain)

---
 docker/Makefile | 39 ++++-----------------------------------
 1 file changed, 4 insertions(+), 35 deletions(-)

diff --git a/docker/Makefile b/docker/Makefile
index eeb9f66..93d8960 100644
--- a/docker/Makefile
+++ b/docker/Makefile
@@ -1,23 +1,14 @@
-# appchain, voting
-pki?=voting
-
 warped?=true
 mixes=3
+auths=3
 gateways=1
 serviceNodes=1
 
-# only used by pki=voting
-auths=3
 UserForwardPayloadLength=30000
 
 distro=alpine
-
-# pki=appchain requires debian (katzenpost alpine docker image does not have bash)
-ifeq ($(pki), appchain)
-	distro = debian
-endif
-
-net_name=mixnet
+net_name=voting_mixnet
+docker_compose_yml=$(net_name)/docker-compose.yml
 sh=$(shell if echo ${distro}|grep -q alpine; then echo sh; else echo bash; fi)
 cache_dir=cache
 log_level=DEBUG
@@ -34,7 +25,6 @@ docker_run_sh=$(docker) run ${docker_args} $(mount_net_name) $(mount_opt) --rm k
 katzenpost_dir?=/tmp/katzenpost.opt
 katzenpost_version?=$(shell grep -E '^	github.com/katzenpost/katzenpost ' ../go.mod | awk '{print $$2}')
 net_dir=$(katzenpost_dir)/docker/$(net_name)
-docker_compose_yml=$(net_dir)/docker-compose.yml
 
 # export variables to the environment for consumption by invoked Makefile(s)
 export
@@ -62,7 +52,7 @@ help:
 	@$(MAKE) -e -C $(katzenpost_dir)/docker $@
 
 .PHONY: custom-binaries
-custom-binaries: $(net_dir)/http_proxy.$(distro) $(net_dir)/pki.$(distro)
+custom-binaries: $(net_dir)/http_proxy.$(distro)
 
 .PHONY: custom-config
 custom-config:
@@ -79,27 +69,6 @@ clone-katzenpost:
 			$(katzenpost_dir); \
 	fi
 
-# this genconfig target is intended to be run within the katzenpost docker container
-# for pki=appchain
-.PHONY: genconfig
-genconfig:
-	cd ../genconfig/cmd/genconfig && go build
-	./genconfig.sh
-
-$(docker_compose_yml): $(distro)_base.stamp | $(net_name) $(cache_dir)
-	@if [ "$(pki)" = "appchain" ]; then \
-		$(docker_run_sh) 'cd /go/opt/docker ; make pki=appchain genconfig'; \
-	else \
-		$(MAKE) -e -C $(katzenpost_dir)/docker $@; \
-	fi
-
-.PHONY: $(distro)_base.stamp
-$(distro)_base.stamp:
-	$(MAKE) -e -C $(katzenpost_dir)/docker $@
-
-$(net_dir)/pki.$(distro): $(katzenpost_dir)/docker/$(distro)_base.stamp $(docker_compose_yml) | $(net_name) $(cache_dir)
-	$(docker_run_sh) 'cd /go/opt/pki ; go build -trimpath -ldflags ${ldflags} && mv pki /$(net_name)/pki.$(distro)'
-
 $(net_dir)/http_proxy.$(distro): $(katzenpost_dir)/docker/$(distro)_base.stamp | $(net_name) $(cache_dir)
 	$(docker_run_sh) 'cd /go/opt/server_plugins/cbor_plugins/http_proxy/cmd/http_proxy ; go build -trimpath -ldflags ${ldflags} && mv http_proxy /$(net_name)/http_proxy.$(distro)'
 	cp ../server_plugins/cbor_plugins/http_proxy/http_proxy_config.toml $(net_dir)/servicenode1/

From 5b0d45be32466147fbb84bb596bf167ea87e2d66 Mon Sep 17 00:00:00 2001
From: Xendarboh <1435589+xendarboh@users.noreply.github.com>
Date: Mon, 4 Nov 2024 16:10:45 -0800
Subject: [PATCH 15/21] feat(genconfig): use absolute path for auth's
 IdentityPublicKeyPem

---
 genconfig/genconfig.go | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/genconfig/genconfig.go b/genconfig/genconfig.go
index ed16ec8..e144b71 100644
--- a/genconfig/genconfig.go
+++ b/genconfig/genconfig.go
@@ -471,7 +471,7 @@ func (s *katzenpost) genAuthorizedNodes() ([]*vConfig.Node, []*vConfig.Node, []*
 	for _, nodeCfg := range s.nodeConfigs {
 		node := &vConfig.Node{
 			Identifier:           nodeCfg.Server.Identifier,
-			IdentityPublicKeyPem: filepath.Join("../", nodeCfg.Server.Identifier, "identity.public.pem"),
+			IdentityPublicKeyPem: filepath.Join(s.outDir, nodeCfg.Server.Identifier, "identity.public.pem"),
 		}
 		if nodeCfg.Server.IsGatewayNode {
 			gateways = append(gateways, node)

From 18578b2c66a9200e6765de295e693b6502a6f5bf Mon Sep 17 00:00:00 2001
From: Xendarboh <1435589+xendarboh@users.noreply.github.com>
Date: Mon, 4 Nov 2024 16:47:35 -0800
Subject: [PATCH 16/21] fix(genconfig): remove redundant directory creation

---
 genconfig/genconfig.go | 1 -
 1 file changed, 1 deletion(-)

diff --git a/genconfig/genconfig.go b/genconfig/genconfig.go
index e144b71..d426c06 100644
--- a/genconfig/genconfig.go
+++ b/genconfig/genconfig.go
@@ -716,7 +716,6 @@ func Genconfig(gi GenconfigInput) error {
 	}
 
 	os.Mkdir(s.outDir, 0700)
-	os.Mkdir(filepath.Join(s.outDir, s.baseDir), 0700)
 
 	if *voting {
 		// Generate the voting authority configurations

From 6ab74cee7bd6a3642afe1f5110b64dbe062a0cd6 Mon Sep 17 00:00:00 2001
From: Xendarboh <1435589+xendarboh@users.noreply.github.com>
Date: Mon, 4 Nov 2024 17:29:00 -0800
Subject: [PATCH 17/21] feat(genconfig): create default http_proxy_config.toml
 file

---
 genconfig/genconfig.go | 18 +++++++++++++++++-
 1 file changed, 17 insertions(+), 1 deletion(-)

diff --git a/genconfig/genconfig.go b/genconfig/genconfig.go
index d426c06..38e5efc 100644
--- a/genconfig/genconfig.go
+++ b/genconfig/genconfig.go
@@ -378,11 +378,14 @@ func (s *katzenpost) genNodeConfig(identifier string, isGateway bool, isServiceN
 				MaxConcurrency: 1,
 				Disable:        false,
 				Config: map[string]interface{}{
-					"config":  s.binPrefix + "http_proxy_config.toml",
+					"config":  s.baseDir + "/" + cfg.Server.Identifier + "/http_proxy_config.toml",
 					"log_dir": s.baseDir + "/" + cfg.Server.Identifier,
 				},
 			}
 			cfg.ServiceNode.CBORPluginKaetzchen = append(cfg.ServiceNode.CBORPluginKaetzchen, httpProxyCfg)
+			// create empty default http_proxy_config.toml file
+			httpProxyConfigFile := filepath.Join(s.outDir, cfg.Server.Identifier, "http_proxy_config.toml")
+			saveFileContents(httpProxyConfigFile, "[Networks]\n")
 
 			cfg.Debug.NumKaetzchenWorkers = 4
 		}
@@ -847,6 +850,19 @@ func saveCfg(cfg interface{}, outDir string) error {
 	return enc.Encode(cfg)
 }
 
+func saveFileContents(filename string, contents string) error {
+	log.Printf("writing %s", filename)
+	f, err := os.Create(filename)
+	if err != nil {
+		return fmt.Errorf("os.Create(%s) failed: %s", filename, err)
+	}
+	defer f.Close()
+	if _, err := f.WriteString(contents); err != nil {
+		return fmt.Errorf("f.WriteString() failed: %s", err)
+	}
+	return nil
+}
+
 func cfgIdKey(cfg interface{}, outDir string) sign.PublicKey {
 	var priv, public string
 	var pkiSignatureScheme string

From 1f7bb61b2a731eadd5bde7f6cc03965361db79f5 Mon Sep 17 00:00:00 2001
From: Xendarboh <1435589+xendarboh@users.noreply.github.com>
Date: Mon, 4 Nov 2024 17:30:22 -0800
Subject: [PATCH 18/21] feat(docker): node/Dockerfile: don't include
 http_proxy_config.toml

---
 docker/node/Dockerfile | 1 -
 1 file changed, 1 deletion(-)

diff --git a/docker/node/Dockerfile b/docker/node/Dockerfile
index a57d214..5ad9247 100644
--- a/docker/node/Dockerfile
+++ b/docker/node/Dockerfile
@@ -58,7 +58,6 @@ RUN --mount=type=cache,target="${GOCACHE}" \
   && build genconfig/cmd/genconfig genconfig \
   # servicenode plugin: http_proxy
   && build server_plugins/cbor_plugins/http_proxy/cmd/http_proxy http_proxy \
-  && cp /src/server_plugins/cbor_plugins/http_proxy/http_proxy_config.toml /dest/ \
   # clients
   && build apps/walletshield walletshield
 

From a26aa08ba56ac65ffc32d65a98017fec60fa57a3 Mon Sep 17 00:00:00 2001
From: Xendarboh <1435589+xendarboh@users.noreply.github.com>
Date: Mon, 4 Nov 2024 17:38:19 -0800
Subject: [PATCH 19/21] feat(docker): genconfig.sh: add http_proxy config for
 servicenodes

---
 docker/genconfig.sh | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/docker/genconfig.sh b/docker/genconfig.sh
index adfeee5..ee819a4 100755
--- a/docker/genconfig.sh
+++ b/docker/genconfig.sh
@@ -105,6 +105,9 @@ function gencfg_node () {
 EOF
 }
 
-for i in $(seq 1 ${num_gateways}); do gencfg_node gateway ${i}; done
-for i in $(seq 1 ${num_servicenodes}); do gencfg_node servicenode ${i}; done
 for i in $(seq 1 ${num_mixes}); do gencfg_node mix ${i}; done
+for i in $(seq 1 ${num_gateways}); do gencfg_node gateway ${i}; done
+for i in $(seq 1 ${num_servicenodes}); do
+  gencfg_node servicenode ${i}
+  cp ../server_plugins/cbor_plugins/http_proxy/http_proxy_config.toml ${dir_out}/servicenode${i}/http_proxy_config.toml
+done

From 03ea8a7236bf80b3deb02e89a0325c0cb01d179c Mon Sep 17 00:00:00 2001
From: Xendarboh <1435589+xendarboh@users.noreply.github.com>
Date: Mon, 4 Nov 2024 17:59:08 -0800
Subject: [PATCH 20/21] chore(docker): node/Dockerfile: default
 ENABLE_WARPED_EPOCH to false

---
 docker/node/Dockerfile | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docker/node/Dockerfile b/docker/node/Dockerfile
index 5ad9247..afa7b20 100644
--- a/docker/node/Dockerfile
+++ b/docker/node/Dockerfile
@@ -1,6 +1,6 @@
 FROM ubuntu:latest AS builder
 
-ARG ENABLE_WARPED_EPOCH=true
+ARG ENABLE_WARPED_EPOCH=false
 ARG KATZENPOST_DIR=/src/katzenpost
 ARG VERSION_GO=1.22.3
 
@@ -56,7 +56,7 @@ RUN --mount=type=cache,target="${GOCACHE}" \
   && build pki pki \
   # genconfig
   && build genconfig/cmd/genconfig genconfig \
-  # servicenode plugin: http_proxy
+  # servicenode plugins
   && build server_plugins/cbor_plugins/http_proxy/cmd/http_proxy http_proxy \
   # clients
   && build apps/walletshield walletshield

From 25ce76a05ae086dedc8743092e5c6828ad0870fa Mon Sep 17 00:00:00 2001
From: Xendarboh <1435589+xendarboh@users.noreply.github.com>
Date: Mon, 4 Nov 2024 21:57:01 -0800
Subject: [PATCH 21/21] docs(docker): update README with appchain-pki info

---
 docker/README.md | 73 ++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 65 insertions(+), 8 deletions(-)

diff --git a/docker/README.md b/docker/README.md
index 620863b..9a3f9be 100644
--- a/docker/README.md
+++ b/docker/README.md
@@ -1,10 +1,67 @@
-# Docker Test Network
+# Dockerized Test Networks
 
-The Makefile and scripts here allow developers of 0KN mix network apps and server-side plugins to
-locally run an offline Katzenpost test network with a podman-compatible docker-compose
-configuration. It is meant for developing and testing client and server mix network components as
-part of the core developer work flow.
+This directory provides Makefiles and scripts to set up a local, offline test network for developing
+and testing 0KN mix network applications and server-side plugins. The setup leverages a
+Podman-compatible `docker-compose` configuration for simulating a Katzenpost network environment.
 
-This Makefile covers 0KN-specifics and proxies other targets to Katzenpost's `docker/Makefile`.
-Refer to [Katzenpost Docker test network](https://github.com/katzenpost/katzenpost/tree/main/docker)
-for more info.
+The goal is to support core development workflows by enabling local testing of both client and
+server mix network components in isolated, controlled conditions.
+
+There are two Makefiles available, each corresponding to a different PKI.
+
+- **`Makefile`:** (Default) Manages a local test network using Katzenpost’s voting PKI.
+- **`Makefile.appchain`:** Uses 0KN’s ZKAppChain PKI.
+
+## Voting PKI
+
+This setup, managed by the default `Makefile`, covers 0KN-specifics and proxies other targets to
+Katzenpost's `docker/Makefile`. For additional details, refer to the [Katzenpost Docker Test
+Network documentation](https://github.com/katzenpost/katzenpost/tree/main/docker). The voting PKI
+functionality offers less complex local testing of 0KN mix plugins and client apps that do not
+require the appchain.
+
+## Appchain PKI
+
+This Makefile builds and manages a network of dockerized nodes from
+[`node/Dockerfile`](./node/Dockerfile). It uses the [genconfig](../genconfig/) utility to create
+configurations for nodes from the network info in [network.yml](./network.yml) using the
+appchain-powered [pki](../pki/). Node interactions with the appchain are managed through the
+appchain-agent, utilizing UNIX domain sockets for communication.
+
+### Prerequisites
+
+To run the Appchain PKI network, ensure the following components are available:
+
+- [appchain-agent](https://github.com/0KnowledgeNetwork/appchain-agent) Docker image
+- An operational 0KN ZKAppChain
+
+### Example Workflow
+
+```bash
+# build the appchain-agent docker image
+cd appchain-agent && make image
+
+# start local appchain instance, then:
+
+# build the docker image, configure, start the network, wait for the epoch, then probe
+net=/tmp/appchain-mixnet make -f Makefile.appchain start wait probe
+
+# stop the network and clean up
+net=/tmp/appchain-mixnet make -f Makefile.appchain clean
+
+# build the docker image and configure (without starting network)
+# to inspect or manually edit the configuration files before continuing
+net=/tmp/appchain-mixnet make -f Makefile.appchain config
+
+# start the network without rebuilding or reconfiguring, wait for the epoch
+net=/tmp/appchain-mixnet make -f Makefile.appchain _start wait
+
+# test the network with a client sending 10 test probes
+net=/tmp/appchain-mixnet probe_count=10 make -f Makefile.appchain probe
+
+# watch log files
+tail -f /tmp/appchain-mixnet/*/*.log
+
+# stop the network (without cleaning up)
+net=/tmp/appchain-mixnet make -f Makefile.appchain stop
+```