SwitchWallet Proto Contracts

The proto/ directory holds the Protocol Buffers definitions that describe how AsoRock (the orchestrator) and the city nodes (Lagos, Abuja, Enugu) talk to each other over gRPC. A single schema here becomes the shared source of truth for the request/response payloads, RPC method names, enums, and error codes used across all services.

What is a .proto file?

Protocol Buffers (a.k.a. “protobuf”) is a language-neutral serialization format from Google. A .proto file declares:

• Services – the RPC endpoints and the request/response message types they use.
• Messages – strongly typed data structures with numbered fields.
• Enums – shared enumerations so all services agree on status values, error codes, etc.
• Options – hints for language-specific code generation (e.g. package names).

When you compile a .proto, tooling generates idiomatic client/server stubs in your target language, guaranteeing the orchestrator and MPC nodes share the exact same contract.

Current contents

• switchwallet.proto – Defines the ThresholdNode gRPC service with flows for interactive DKG, signing, and session event streaming. Inline comments also document the RSA metadata headers used for mutual authentication.

Using the contract

Generate code for each service at build-time (exact commands depend on the toolchain you adopt). A few common examples:

Rust (CGGMP21Node)

• Crates: tonic-build + prost.
• Typical build script snippet (build.rs):

  tonic_build::configure()
      .out_dir("src/generated")
      .compile(&["proto/switchwallet.proto"], &["proto"])?;

• Import generated modules under switchwallet::v1::*.

Node.js / TypeScript (BlockPayBot)

• Package options: grpc-tools + @grpc/proto-loader or ts-proto.
• Example using ts-proto:

  npx protoc \
    --plugin=./node_modules/.bin/protoc-gen-ts_proto \
    --ts_proto_out=src/generated \
    --ts_proto_opt=env=node,outputClientImpl=grpc-js \
    proto/switchwallet.proto

Go (optional future service)

• Tool: protoc-gen-go + protoc-gen-go-grpc.
• Command:

  protoc \
    --go_out=./gen \
    --go_opt=paths=source_relative \
    --go-grpc_out=./gen \
    --go-grpc_opt=paths=source_relative \
    proto/switchwallet.proto

About the option go_package / java_package

The package options in switchwallet.proto simply tell generators which namespace or module path to use. They are placeholders for now:

• go_package = "github.com/switchwallet/proto/switchwallet/v1" – update when you publish generated Go bindings, or remove if you do not target Go.
• java_package, csharp_namespace – likewise, adjust when those ecosystems adopt the contract.

Rust (prost/tonic) ignores these options, so keeping them does not affect our current code.

Workflow notes

1. Update switchwallet.proto when the cross-service contract changes.
2. Regenerate stubs in each codebase (Rust, Node.js, etc.) during development or CI.
3. Keep this README in sync with the tooling decisions so new team members understand how to consume the proto.

Last updated: 10 Nov 2025