Commonware runtime in examples folder.

[farazshaikh]

I'm working on augmenting the VRF example so that participants can expose the VRF signature per round via an HTTP endpoint.

I initially tried using axum, which depends on tokio. However, the example package expects the runtime to come from commonware-runtime. Pulling in commonware-runtime means I’d also need to integrate it with axum, which isn't straightforward—especially since it introduces complexity around generics and compatibility.

In my opinion, the examples folder should rely on tokio and other standard tools. While I understand the value of commonware-runtime for deterministic testing and simulation, I don't think the examples folder is the right place for it. Examples should prioritize approachability and ease of experimentation, especially for developers exploring the library.

Moving forward, I see three possible options:

1. Add the HTTP endpoint using commonware-runtime (but this runs into a bunch of generic issues).

2. Keep the examples code untouched and just and an OS thread to run a vanilla axum server alongside.

3. Fork the entire examples folder and write a clean version using standard async tooling.

@patrick-ogrady — open to suggestions if there’s a simpler path. Adding an HTTP endpoint should ideally be a quick and clean change. Let me know what you think.

Let me know if you want this rewritten more formally, or tailored for a GitHub issue comment, PR description, or internal Slack/Discord message.

[patrick-ogrady]

Thanks for reaching out, @farazshaikh!

I'm working on augmenting the VRF example so that participants can expose the VRF signature per round via an HTTP endpoint. I initially tried using axum, which depends on tokio. However, the example package expects the runtime to come from commonware-runtime. Pulling in commonware-runtime means I’d also need to integrate it with axum, which isn't straightforward—especially since it introduces complexity around generics and compatibility.

We ran into this issue when exposing prometheus metrics over a port exposed by commonware-runtime and actually already implemented axum::serve::Listener for runtime::tokio:

monorepo/runtime/src/tokio/runtime.rs

Lines 564 to 576 in e3069b3

	impl axum::serve::Listener for Listener {
	type Io = TcpStream;
	type Addr = SocketAddr;
	async fn accept(&mut self) -> (Self::Io, Self::Addr) {
	let (stream, addr) = self.listener.accept().await.unwrap();
	(stream, addr)
	}
	fn local_addr(&self) -> io::Result<Self::Addr> {
	self.listener.local_addr()
	}
	}

Here is an example of using it with axum's router (which I think should be enough to get you unblocked for now): https://github.com/commonwarexyz/alto/blob/96a2faee19be13dd3fc0d65ded7156484e22de4a/chain/src/bin/validator.rs#L281-L296

In my opinion, the examples folder should rely on tokio and other standard tools. While I understand the value of commonware-runtime for deterministic testing and simulation, I don't think the examples folder is the right place for it. Examples should prioritize approachability and ease of experimentation, especially for developers exploring the library.

We opted to avoid using commonware-runtime for commonware-deployer because it felt too heavyweight for orchestrating a few shell commands. That, however, didn't rely on any commonware-runtime traits so it was pretty straightforward.

For the examples currently maintained, I can appreciate your rationale/suggestion. That being said, most people building with the Commonware Library use the runtime because they want OOB deterministic simulation testing (this is the first ask to have an example avoiding it).

If you want to implement some example that combines some primitives with commonware-runtime trait implementation(s) of some external project, I think that would be very cool (but we don't plan to do so in the short-term).

Hope this helps!

[farazshaikh]

Thx I ended up with a basic http server with routes without Axum / framework support . This is inline with the need for determinism.

Will send out a patch with some other works, merge it if it fits your bill

[farazshaikh]

hello why does the vrf skip rounds.
See round 174, 176, 177 have been skipped i.e there is no signature generated for these rounds.

I understand the concept of scratch/skip round in consensus for liveness. The skipping can be internal - but the "round numbers" and the threshold signature should be strictly monotonic i.e. if the arbiter skips are round it should increment the round the number.

Essentially there should be no gaps in (round, threshold_sig) pair.

For now just want to know the reasoning behind this design - and answer might be its just a VRF and not a monotonic VRF

[patrick-ogrady]

examples::vrf focuses on (1) demonstrating how to perform a DKG and any number of Reshares (via an "arbiter" process rather than over a replicated log) and (2) that the participants in each reshare can generate a simple threshold signature over the round where the reshare was successful. Because some nodes can be offline during a round or restart entirely (dropping their in-memory state), there is no guarantee that a signature is generated at each round nor are there any safeguards to ensure monotonicity when less than f faults. I went for "stupid simple" here to make it easy to grok.

threshold-simplex runs a production-style VRF for leader election that ensures there are no skips and that the VRF is over a monotonically increasing view number. You can play with that in examples::bridge (built to showcase threshold-simplex) or in our hosted demo alto. In alto, you can view all previous "Seeds" (VRF outputs) using the "pickaxe/search" icon in the top right (which allows you to replay the stream with Exoware):

Hope this helps (and sorry for any confusion)! We really need a walkthrough (or two)...