Add availability endpoint to axum API by ss-es · Pull Request #4216 · EspressoSystems/espresso-network

ss-es · 2026-04-23T06:27:00Z

This PR migrates the availability endpoint to Axum, with a copy of the old endpoint served at v1/availability and newer protobuf-specified endpoints served at v2/data and v2/consensus.

You can skip test_api.rs (this is just to render an example UI without having to compile espresso-node) and espresso.api.v2.rs (this is automatically generated).

gemini-code-assist

Code Review

This pull request expands the Espresso API by implementing the Data and Consensus APIs for v2 and the Availability API for v1. These changes introduce endpoints for retrieving namespace proofs, incorrect encoding proofs, state certificates, and stake tables, along with their corresponding proto definitions and Axum routing logic. The review feedback identifies a critical recurring logic error across several new handlers in crates/espresso/node/src/api/state.rs, where the join! macro is used twice on the same set of futures. This pattern is invalid as the first join! resolves the futures, causing subsequent calls to with_timeout or a second join! to fail during compilation.

github-actions · 2026-04-27T04:09:15Z

Unable to build without Cargo.lock file.

This means that after this change 3rd party projects may have
difficulties using crates in this repo as a dependency. If this
isn't easy to fix please open an issue so we can fix it later.

For the first failing build see: https://github.com/EspressoSystems/espresso-network/actions/runs/24975975015

To reproduce locally run

cargo generate-lockfile
cargo check --all-targets

This PR can still be merged.

ss-es · 2026-04-27T06:18:06Z

+                .await
+                .map(Json)
+                .map_err(ApiError::Internal)
+        };


this part here feels a bit verbose and could probably be condensed. exploring options in the next PR.

ss-es · 2026-04-27T06:26:45Z

+
+        // Fetch block and VID common data
+        let ds = &*self.data_source;
+        let timeout = std::time::Duration::from_millis(500);


this seems a bit weird, but the existing incorrect_encoding_proof path uses get_block_for_ns_proof which (I believe) does essentially the same thing

ss-es · 2026-04-27T06:29:38Z

+                })?;
+
+                // Store the fetched certificate
+                ds.insert_state_cert(epoch, cert.clone()).await?;


this mirrors the existing get_state_cert in espresso/node/src/api/endpoints/availability.rs, though maybe we should revisit the behaviour

sveitser · 2026-04-30T09:48:59Z

+    /// Get namespace proof by block height
+    /// Path: GET /v1/availability/namespace/{namespace}/block/{height}
+    pub const NAMESPACE_PROOF_BY_HEIGHT_ROUTE: &str =
+        "/v1/availability/namespace/{namespace}/block/{height}";


Is the change of parameter order intentional?

espresso-network/crates/espresso/node/api/availability.toml

Lines 1 to 10 in 178357d

[route.getnamespaceproof]

PATH = [

"block/:height/namespace/:namespace",

"block/hash/:hash/namespace/:namespace",

"block/payload-hash/:payload-hash/namespace/:namespace",

]

":height" = "Integer"

":hash" = "TaggedBase64"

":payload-hash" = "TaggedBase64"

":namespace" = "Integer"

no definitely not, very good catch!

added tests to ensure this doesn't happen: 9d917b1

sveitser · 2026-04-30T09:53:57Z

+                    .to_string();
+
+                Ok(v2::Transaction {
+                    namespace: tx.namespace.0 as u32,


It seems we have namespace ID as u64 and u32 in different places. Maybe a comment why this is fine here?

I think u32 was how the old Tide API was casting it in some places. But u64 is the internal type, and I think this is actually better to just make a u64 for consistency (especially since it only eliminates conversions)

fixed: 6ad876c

sveitser · 2026-04-30T10:03:44Z

+        Ok(proofs)
+    }
+
+    async fn get_incorrect_encoding_proof(


I'm confused. This function always returns an error.

oops, fixed: 9864160

the code is a bit weird, but I think this follows the existing behaviour around line 413 in crates/espresso/node/src/api/endpoints/availability.rs. unfortunately I think this specific endpoint is hard to add to the test, we don't have any existing tests for it and I'm not sure if anyone is using this endpoint anyway

sveitser · 2026-04-30T10:09:09Z

This PR adds the axum migration for the espresso node availability API overlay but most of the availability API is from the hotshot query service. I think we can merge this first but just wanted to mention it, it kind of confused me at first.

Ayiga · 2026-05-01T16:33:17Z

+
+// IP address (v4 or v6) with port
+message InetAddr {
+  string ip = 1;    // IP address string (e.g., "127.0.0.1" or "::1")


Are we expecting to be able to concatenate the port and the ip without inspecting the ip value itself?

If so, then we may actually want to store [::1] instead of just ::1 for convenience.

fixed here: 9864160

sveitser

I think this is fine but what about the query service availability API? The comment I left here: #4216 (comment)

github-actions · 2026-05-07T15:43:57Z

Nextest failures (1) in this run

Test	Attempts	Time (s)	Main history
`hotshot-new-protocol::tests::restarts::late_start_one_node_with_epochs`	1	55.12	passing

See the step summary for flaky tests and slowest tests.

add availability endpoint

eae4c87

gemini-code-assist Bot reviewed Apr 23, 2026

View reviewed changes

Comment thread crates/espresso/node/src/api/state.rs Outdated

Comment thread crates/espresso/node/src/api/state.rs Outdated

Comment thread crates/espresso/node/src/api/state.rs Outdated

Comment thread crates/espresso/node/src/api/state.rs Outdated

ss-es commented Apr 24, 2026

View reviewed changes

Comment thread crates/espresso/api/src/axum.rs Outdated

ss-es commented Apr 24, 2026

View reviewed changes

Comment thread crates/espresso/api/src/axum.rs Outdated

ss-es commented Apr 24, 2026

View reviewed changes

Comment thread crates/serialization/api/proto/v2/consensus.proto Outdated

ss-es commented Apr 24, 2026

View reviewed changes

Comment thread crates/serialization/api/proto/v2/consensus.proto Outdated

ss-es added 11 commits April 24, 2026 12:46

update proto definitions with more detail

b5c2851

remove types defined in axum.rs

9f26eab

remove unhelpful comments

4bf2129

cleanup

e1a08f0

collapse swagger by default

1192448

add example values

be65c6f

cleanup

d94ea9e

cleanup examples

592fea6

update readme

3fc97f3

Merge branch 'main' into ss/axum-2

318ebee

fix formatting

e4ec214

ss-es added 3 commits April 27, 2026 01:10

update with serialization fixes/cleanup

33e6ca2

fix inconsistency

a6d2f64

move descriptions into routes

846fe8d

ss-es commented Apr 27, 2026

View reviewed changes

clippy

bdbb33d

ss-es marked this pull request as ready for review April 27, 2026 06:42

ss-es requested review from bfish713, imabdulbasit, jbearer and sveitser as code owners April 27, 2026 06:42

ss-es added 2 commits April 27, 2026 10:37

cargo sort

67c708c

update

178357d

sveitser reviewed Apr 30, 2026

View reviewed changes

ss-es added 9 commits May 1, 2026 00:03

add new v1 API tests

408e4dc

fix reward merkle tree

06c508a

fix reward balance endpoint

f94e2a4

refactor test

ab8103e

fix latest reward balance

96ac79a

fix routes

7d86f58

fix test

dafaccd

rustfmt

d6f02f5

fix reward-amounts

f28b106

Ayiga reviewed May 1, 2026

View reviewed changes

Merge branch 'ss/axum-tests-1' into ss/axum-2

5a678c8

ss-es changed the base branch from main to ss/axum-tests-1 May 4, 2026 05:32

ss-es added 3 commits May 4, 2026 02:02

add parity tests

9d917b1

update incorrect_encoding_proof

9864160

u32 -> u64

6ad876c

sveitser self-requested a review May 6, 2026 09:51

sveitser approved these changes May 6, 2026

View reviewed changes

Base automatically changed from ss/axum-tests-1 to main May 6, 2026 14:43

ss-es added 3 commits May 6, 2026 11:09

fix examples

c030d35

Merge branch 'main' into ss/axum-2

3a35fa3

Merge branch 'main' into ss/axum-2

3b7072f

ss-es merged commit d015da3 into main May 7, 2026
169 of 175 checks passed

ss-es deleted the ss/axum-2 branch May 7, 2026 17:13

	[route.getnamespaceproof]
	PATH = [
	"block/:height/namespace/:namespace",
	"block/hash/:hash/namespace/:namespace",
	"block/payload-hash/:payload-hash/namespace/:namespace",
	]
	":height" = "Integer"
	":hash" = "TaggedBase64"
	":payload-hash" = "TaggedBase64"
	":namespace" = "Integer"

Conversation

ss-es commented Apr 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Apr 27, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sveitser Apr 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sveitser commented Apr 30, 2026

Uh oh!

Ayiga May 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sveitser left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented May 7, 2026

Nextest failures (1) in this run

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

ss-es commented Apr 23, 2026 •

edited

Loading

sveitser Apr 30, 2026 •

edited

Loading

Ayiga May 1, 2026 •

edited

Loading