Implement online ceremony

Provide implementation of client and server for online contributions.
The server waits for contributions from the clients and orchestrates
the ceremony. Clients connect to the server, contribute and disconnect.

Signed-off-by: Wojciech Zmuda <[email protected]>

Author: wzmuda

.github/workflows/ci.yml

@@ -44,6 +44,8 @@ jobs:
         uses: actions/setup-go@v5
         with:
           go-version: '1.24'
+      - name: Generate code from gRPC protocol definition
+        run: go generate ./...
       - name: Build
         run: go build ./...
       - name: Test

.gitignore

@@ -1,6 +1,8 @@
 .idea/
 
-*.ph1
-*.ph2
+# Generated protobuf code
+**/ceremony.pb.go
+**/ceremony_grpc.pb.go
 
 trusted-setup
+.DS_Store

README.md

@@ -1,10 +1,42 @@
 # ZKP Trusted Setup Ceremony Coordinator
 
+**Warning**
+Please note that this tool is under development. Please consider it unusable before the first release.
+
 ## Overview
 This utility program allows for performing a Trusted Setup Ceremony in a Multi-Party Computation fashion. It is meant
 to be used by the Coordinator of the ceremony, as well as by the Contributors. In the end, the Coordinator will obtain
 Proving and Verifying Keys, which can be used to generate proofs for the circuit the ceremony was conducted for.
 
+### Online mode
+
+The primary mode of the program. In this mode, the Coordinator runs the ceremony server, which is responsible for
+accepting contributions from the Contributors. The Contributors connect to the Coordinator and contribute to the
+ceremony.
+
+See help for `server` and `client` commands for details.
+
+### Offline mode
+
+In this mode, the Coordinator and the Contributors run the ceremony locally. The Coordinator initializes the ceremony
+and generates the initial Phase 2 file. The Coordinator sends the file to the first Contributor. The Contributor
+generates their contribution and sends them to the Coordinator in the form of a Phase 2 file. The Coordinator verifies
+the contributions and, if the verification is positive, sends it to the next Contributor.
+
+In this mode, sending Phase 2 files must be performed manually by the Coordinator and Contributors.
+
+At the end of the ceremony, the Coordinator will have a list of accepted contributions. The Coordinator can then
+perform the final verification and extract the Proving and the Verifying Keys.
+
+See help for `init`, `contrib`, `verify` and `extract` commands for details.
+
+### Snarkjs powers of tau (ptau) -> Phase 1 conversion
+
+The tool can convert a Snarkjs powers of tau file to a Phase 1 file. This step is performed by the Coordinator before
+the initialization of the offline mode ceremony, if the Coordinator has a ptau file that they wish to use in the ceremony.
+
+This step is not necessary if the Coordinator already has a Phase 1 file.
+
 ## Constraints
 
 Gnark version used for implementing the circuit the ceremony will be conducted for must match the Gnark version used
@@ -14,20 +46,57 @@ Your Gnark project must satisfy the following constraints:
 - Supported curve: BN254
 - Supported backend: Groth16
 
+## Prerequisites
+
+These are one-time steps that must be done in order to build the program.
+
+Install [Go](https://go.dev/dl/). Any recent version will do. Look into `go.mod` to see the minimum required version.
+
+Install [Protocol Buffer Compiler](https://protobuf.dev/installation/).
+
+Install gRPC for Go:
+
+```shell
+go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest
+```
+
+## Build
+
+To build the project, run:
+```shell
+$ go generate ./...
+$ go build .
+````
+
+in the project's root directory.
+
+The test suite can be executed with:
+```shell
+$ go test -v ./...
+```
+
 ## Usage
 
-Run the program with `go run .` or `go run <command> <options>`.
+Run the program with:
+```shell
+$ go run . <command> <options>
+
+# or, after the program was built
+./trusted-setup <command> <options>
+```
 
 Running the program with no arguments lists the available commands. Running the program with the command but without
 options will display the command's help.
 
 ## Commands
 
-### `help`
+### General purpose commands
+
+#### `help`
 
 Print help.
 
-### `ptau`
+#### `ptau`
 
 Convert a Snarkjs powers of tau file to a Phase 1 file. This step is performed by the Coordinator.
 
@@ -38,9 +107,54 @@ tau file to a Phase 1 file, which can be used to initialize the Phase 2 of the c
 - `--ptau` - A Snarkjs powers of tau file,
 - `--phase1` - The output Phase 1 file.
 
-### `init`
+### Online mode commands
+
+#### `server`
+
+Start a Ceremony server. This step is performed by the Coordinator.
+
+The server is responsible for orchestrating the ceremony, receiving contributions from the participants and, in the end,
+generating Proving and Verifying Keys.
+
+The server is configured with a JSON file. An example configuration is shown below:
+```json5
+{
+  // A human-readable name for the ceremony that will be sent to contributors.
+  // Used for identification purposes; can be any reasonably sized string.
+  "ceremonyName": "test ceremony",
+  // The IP address on which the server will listen on.
+  "host": "127.0.0.1",
+  // The TCP port on which the server will listen on.
+  "port": 7312,
+  // The path to the R1CS file generated from a Gnark circuit.
+  "r1cs": "resources/server.r1cs",
+  // The path to the Phase 1 file (possibly generated from a ptau file - see the `ptau` command for details).
+  "phase1": "resources/server.ph1",
+}
+```
+
+Coordination of the ceremony is automatic. No action from the Coordinator is required besides starting the server
+and stopping it with CTRL+C at any arbitrary moment. At CTRL+C, the server stops accepting new contributions and starts
+key extraction from the existing contributions.
+
+- `--config` - Path to a JSON file containing the server configuration.
+
+#### `client`
+
+Connect to a Ceremony server and provide contributions. This step is performed by the Contributors.
+
+The client is responsible for connecting to the server and providing contributions. The client is configured with
+a host and port of the server. Participation in the ceremony is automatic. No action from the Contributor is required
+besides starting the client.
+
+- `--host` - The IP address of the server,
+- `--port` - The port of the server.
+
+### Offline mode commands
+
+#### `init`
 
-Initialize Phase 2 of the ceremony for the given R1CS with a Phase 1 file.  This step is performed by the Coordinator.
+Initialize Phase 2 of the ceremony for the given R1CS with a Phase 1 file. This step is performed by the Coordinator.
 
 This step outputs a Phase 2 file based on the provided R1CS and Phase 1 file. The Coordinator must provide the R1CS file
 generated from a Gnark circuit and the Phase 1 file either generated in the previous step or from another
@@ -58,7 +172,7 @@ The command outputs a beacon value, which must then be passed as an argument to
 - `--phase2` - The output path for the Phase 2 file,
 - `--srscommons` - The output path for circuit-independent components of the Groth16 SRS.
 
-### `contribute`
+#### `contribute`
 
 Contribute randomness to Phase 2. This step is performed by all the participants of the ceremony.
 
@@ -70,7 +184,7 @@ appended to the name.
 
 - `--phase2` - The existing Phase 2 file created in the `init` step or in the previous run of the `contribute` step.
 
-### `verify`
+#### `verify`
 
 Verify the last randomness contributed to Phase 2. This step is performed by the Coordinator.
 
@@ -85,7 +199,7 @@ If the verification is successful, the Coordinator can either:
 - `--phase2prev` - A Phase 2 file being an input to the contribution
 - `--phase2next` - A Phase 2 file that was contributed to.
 
-### `extract-keys`
+#### `extract-keys`
 
 Extract the Proving and Verifying Keys. This step is performed by the Coordinator.
 

go.mod

@@ -6,9 +6,12 @@ require (
 	github.com/consensys/gnark v0.13.0
 	github.com/consensys/gnark-crypto v0.18.0
 	github.com/drand/go-clients v0.2.3
+	github.com/golang/protobuf v1.5.4
 	github.com/stretchr/testify v1.10.0
 	github.com/urfave/cli/v3 v3.3.8
 	github.com/worldcoin/ptau-deserializer v0.2.0
+	google.golang.org/grpc v1.73.0
+	google.golang.org/protobuf v1.36.6
 )
 
 replace github.com/worldcoin/ptau-deserializer => github.com/reilabs/ptau-deserializer v0.0.0-20250630133456-6f3242b72b0a
@@ -41,6 +44,7 @@ require (
 	github.com/prometheus/procfs v0.17.0 // indirect
 	github.com/ronanh/intcomp v1.1.1 // indirect
 	github.com/rs/zerolog v1.34.0 // indirect
+	github.com/stretchr/objx v0.5.2 // indirect
 	github.com/x448/float16 v0.8.4 // indirect
 	go.dedis.ch/fixbuf v1.0.3 // indirect
 	go.uber.org/multierr v1.11.0 // indirect
@@ -51,7 +55,5 @@ require (
 	golang.org/x/sys v0.33.0 // indirect
 	golang.org/x/text v0.26.0 // indirect
 	google.golang.org/genproto/googleapis/rpc v0.0.0-20250414145226-207652e42e2e // indirect
-	google.golang.org/grpc v1.71.1 // indirect
-	google.golang.org/protobuf v1.36.6 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
 )

go.sum

@@ -113,6 +113,8 @@ github.com/ronanh/intcomp v1.1.1/go.mod h1:7FOLy3P3Zj3er/kVrU/pl+Ql7JFZj7bwliMGk
 github.com/rs/xid v1.6.0/go.mod h1:7XoLgs4eV+QndskICGsho+ADou8ySMSjJKDIan90Nz0=
 github.com/rs/zerolog v1.34.0 h1:k43nTLIwcTVQAncfCw4KZ2VY6ukYoZaBPNOE8txlOeY=
 github.com/rs/zerolog v1.34.0/go.mod h1:bJsvje4Z08ROH4Nhs5iH600c3IkWhwp44iRc54W6wYQ=
+github.com/stretchr/objx v0.5.2 h1:xuMeJ0Sdp5ZMRXx/aWO6RZxdr3beISkG5/G/aIRr3pY=
+github.com/stretchr/objx v0.5.2/go.mod h1:FRsXN1f5AsAjCGJKqEizvkpNtU+EGNCLh3NxZ/8L+MA=
 github.com/stretchr/testify v1.10.0 h1:Xv5erBjTwe/5IxqUQTdXv5kgmIvbHo3QQyRwhJsOfJA=
 github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
 github.com/urfave/cli/v3 v3.3.8 h1:BzolUExliMdet9NlJ/u4m5vHSotJ3PzEqSAZ1oPMa/E=
@@ -141,8 +143,8 @@ go.opentelemetry.io/otel/metric v1.35.0 h1:0znxYu2SNyuMSQT4Y9WDWej0VpcsxkuklLa4/
 go.opentelemetry.io/otel/metric v1.35.0/go.mod h1:nKVFgxBZ2fReX6IlyW28MgZojkoAkJGaE8CpgeAU3oE=
 go.opentelemetry.io/otel/sdk v1.35.0 h1:iPctf8iprVySXSKJffSS79eOjl9pvxV9ZqOWT0QejKY=
 go.opentelemetry.io/otel/sdk v1.35.0/go.mod h1:+ga1bZliga3DxJ3CQGg3updiaAJoNECOgJREo9KHGQg=
-go.opentelemetry.io/otel/sdk/metric v1.34.0 h1:5CeK9ujjbFVL5c1PhLuStg1wxA7vQv7ce1EK0Gyvahk=
-go.opentelemetry.io/otel/sdk/metric v1.34.0/go.mod h1:jQ/r8Ze28zRKoNRdkjCZxfs6YvBTG1+YIqyFVFYec5w=
+go.opentelemetry.io/otel/sdk/metric v1.35.0 h1:1RriWBmCKgkeHEhM7a2uMjMUfP7MsOF5JpUCaEqEI9o=
+go.opentelemetry.io/otel/sdk/metric v1.35.0/go.mod h1:is6XYCUMpcKi+ZsOvfluY5YstFnhW0BidkR+gL+qN+w=
 go.opentelemetry.io/otel/trace v1.35.0 h1:dPpEfJu1sDIqruz7BHFG3c7528f6ddfSWfFDVt/xgMs=
 go.opentelemetry.io/otel/trace v1.35.0/go.mod h1:WUk7DtFp1Aw2MkvqGdwiXYDZZNvA/1J8o6xRXLrIkyc=
 go.opentelemetry.io/proto/otlp v1.5.0 h1:xJvq7gMzB31/d406fB8U5CBdyQGw4P399D1aQWU/3i4=
@@ -173,8 +175,8 @@ google.golang.org/genproto/googleapis/api v0.0.0-20250414145226-207652e42e2e h1:
 google.golang.org/genproto/googleapis/api v0.0.0-20250414145226-207652e42e2e/go.mod h1:085qFyf2+XaZlRdCgKNCIZ3afY2p4HHZdoIRpId8F4A=
 google.golang.org/genproto/googleapis/rpc v0.0.0-20250414145226-207652e42e2e h1:ztQaXfzEXTmCBvbtWYRhJxW+0iJcz2qXfd38/e9l7bA=
 google.golang.org/genproto/googleapis/rpc v0.0.0-20250414145226-207652e42e2e/go.mod h1:qQ0YXyHHx3XkvlzUtpXDkS29lDSafHMZBAZDc03LQ3A=
-google.golang.org/grpc v1.71.1 h1:ffsFWr7ygTUscGPI0KKK6TLrGz0476KUvvsbqWK0rPI=
-google.golang.org/grpc v1.71.1/go.mod h1:H0GRtasmQOh9LkFoCPDu3ZrwUtD1YGE+b2vYBYd/8Ec=
+google.golang.org/grpc v1.73.0 h1:VIWSmpI2MegBtTuFt5/JWy2oXxtjJ/e89Z70ImfD2ok=
+google.golang.org/grpc v1.73.0/go.mod h1:50sbHOUqWoCQGI8V2HQLJM0B+LMlIUjNSZmow7EVBQc=
 google.golang.org/protobuf v1.36.6 h1:z1NpPI8ku2WgiWnf+t9wTPsn6eP1L7ksHUlkfLvd9xY=
 google.golang.org/protobuf v1.36.6/go.mod h1:jduwjTPXsFjZGTmRluh+L6NjiWu7pchiJ2/5YcXBHnY=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=

main.go

@@ -9,13 +9,17 @@ import (
 	"github.com/urfave/cli/v3"
 
 	"github.com/reilabs/trusted-setup/offline"
+	"github.com/reilabs/trusted-setup/online"
 )
 
 func main() {
 	app := &cli.Command{
 		Name:  filepath.Base(os.Args[0]),
 		Usage: "a ZKP Trusted Setup Ceremony Coordinator",
-		Description: "This program allows for initializing a trusted setup ceremony and contributing to it.\n" +
+		Description: "This program allows for initializing a trusted setup ceremony and contributing to it.\n\n" +
+			"The program has two modes:\n" +
+			"- the online mode: run an automated ceremony server and let clients connect and contribute\n" +
+			"- the offline mode: orchestrate the ceremony yourself, manually managing contributions\n\n" +
 			"Phase 2 of the ceremony can be initialized from a previously generated Phase 1 file\n" +
 			"or from a Snarkjs powers of tau file. New contributions can be added to Phase 2.\n" +
 			"The contributions can be verified. Proving and verifying keys can be exported from the\n" +
@@ -31,9 +35,12 @@ func main() {
 		},
 		DefaultCommand: "help",
 		Suggest:        true,
-		Commands:       offline.Commands,
+		Commands:       []*cli.Command{},
 	}
 
+	app.Commands = append(app.Commands, offline.Commands...)
+	app.Commands = append(app.Commands, online.Commands...)
+
 	if err := app.Run(context.Background(), os.Args); err != nil {
 		log.Fatal(err)
 	}

online/actions/client.go

@@ -0,0 +1,16 @@
+package actions
+
+import (
+	"context"
+
+	"github.com/urfave/cli/v3"
+
+	"github.com/reilabs/trusted-setup/online/client"
+)
+
+func Client(_ context.Context, cmd *cli.Command) error {
+	host := cmd.String("host")
+	port := cmd.String("port")
+
+	return client.ConnectAndContribute(host, port)
+}