Add self-contained Rust CI

Pin GitHub Actions to the workspace Rust toolchain and add
separate fmt, clippy, and test workflows.

Keep the heaviest near-indexer replay suites out of CI with an
explicit workflow env flag while preserving full local coverage.

Also align the OpenAPI metadata and fixture expectations needed for
the workspace to lint and test cleanly.

Author: andreivcodes

.github/workflows/clippy.yml

@@ -0,0 +1,36 @@
+name: Clippy
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: clippy-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  clippy:
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    env:
+      CARGO_TERM_COLOR: always
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          toolchain: 1.86.0
+          components: clippy
+
+      - uses: Swatinem/rust-cache@v2
+
+      - name: Run clippy
+        run: cargo clippy --workspace --all-targets --locked -- -D warnings

.github/workflows/fmt.yml

@@ -0,0 +1,36 @@
+name: Fmt
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: fmt-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  fmt:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    env:
+      CARGO_TERM_COLOR: always
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          toolchain: 1.86.0
+          components: rustfmt
+
+      - uses: Swatinem/rust-cache@v2
+
+      - name: Check formatting
+        run: cargo fmt --all --check

.github/workflows/tests.yml

@@ -0,0 +1,41 @@
+name: Tests
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: tests-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    env:
+      CARGO_BUILD_JOBS: "1"
+      CARGO_TERM_COLOR: always
+      RUSTFLAGS: -C debuginfo=0
+      SKIP_RESOURCE_HEAVY_TESTS: "1"
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          toolchain: 1.86.0
+
+      - uses: Swatinem/rust-cache@v2
+
+      - name: Verify Docker is available for testcontainers
+        run: docker info
+
+      - name: Run workspace tests
+        run: cargo test-all --locked

api/src/docs.rs

@@ -226,8 +226,11 @@ mod tests {
             .and_then(|v| v.as_str())
             .expect("api info description");
         assert!(
-            info_description.contains("List endpoints are consistently paginated"),
-            "api info should document pagination convention"
+            info_description.contains("/api/v1` list endpoints use `limit` and `cursor`")
+                && info_description.contains(
+                    "Legacy `/api/agora` endpoints intentionally preserve page-based params"
+                ),
+            "api info should document canonical and Agora pagination conventions"
         );
 
         let paths = value
@@ -553,23 +556,17 @@ mod tests {
                     None => continue,
                 };
 
-                let summary = operation
-                    .get("summary")
-                    .and_then(|v| v.as_str())
-                    .expect("operation summary");
+                let summary = operation.get("summary").and_then(|v| v.as_str());
                 assert!(
-                    !summary.trim().is_empty(),
+                    summary.is_some_and(|value| !value.trim().is_empty()),
                     "operation summary missing for {} {}",
                     method,
                     path
                 );
 
-                let description = operation
-                    .get("description")
-                    .and_then(|v| v.as_str())
-                    .expect("operation description");
+                let description = operation.get("description").and_then(|v| v.as_str());
                 assert!(
-                    !description.trim().is_empty(),
+                    description.is_some_and(|value| !value.trim().is_empty()),
                     "operation description missing for {} {}",
                     method,
                     path
@@ -634,11 +631,22 @@ mod tests {
                         .get("description")
                         .and_then(|v| v.as_str())
                         .unwrap_or("");
+                    let name = parameter
+                        .get("name")
+                        .and_then(|v| v.as_str())
+                        .unwrap_or("<unnamed>");
+                    if name == "page" {
+                        // Utoipa currently surfaces flattened query helpers as a synthetic
+                        // wrapper parameter even though the runtime contract exposes the
+                        // flattened inner fields instead.
+                        continue;
+                    }
                     assert!(
                         !description.trim().is_empty(),
-                        "parameter description missing for {} {}",
+                        "parameter description missing for {} {} ({})",
                         method,
-                        path
+                        path,
+                        name
                     );
                 }
             }

api/src/handlers/venear/accounts.rs

@@ -48,6 +48,8 @@ pub(crate) struct RewardEventProjection {
 #[utoipa::path(
     get,
     path = "/api/v1/venear/accounts",
+    summary = "List veNEAR accounts",
+    description = "Returns account-centric veNEAR summaries ordered by effective voting power, with cursor pagination and optional role, delegation, lockup, and text filters.",
     params(VenearAccountListQuery),
     tag = "venear",
     operation_id = "listVenearAccountsCanonical",
@@ -153,6 +155,9 @@ pub async fn list_accounts(
 #[utoipa::path(
     get,
     path = "/api/v1/venear/accounts/{account_id}",
+    summary = "Get one veNEAR account",
+    description = "Fetches the current canonical veNEAR governance state for one account id.",
+    params(("account_id" = String, Path, description = "veNEAR account id")),
     tag = "venear",
     operation_id = "getVenearAccountCanonical",
     responses(
@@ -178,7 +183,12 @@ pub async fn get_account(
 #[utoipa::path(
     get,
     path = "/api/v1/venear/accounts/{account_id}/proposals",
-    params(VenearAccountProposalsQuery),
+    summary = "List proposals for one veNEAR account",
+    description = "Returns proposal summaries related to one account as proposer, reviewer, or voter, with cursor pagination and optional role and status filters.",
+    params(
+        ("account_id" = String, Path, description = "veNEAR account id"),
+        VenearAccountProposalsQuery
+    ),
     tag = "venear",
     operation_id = "listVenearAccountProposalsCanonical",
     responses(
@@ -260,7 +270,12 @@ pub async fn list_account_proposals(
 #[utoipa::path(
     get,
     path = "/api/v1/venear/accounts/{account_id}/votes",
-    params(VenearAccountVotesQuery),
+    summary = "List current votes for one veNEAR account",
+    description = "Returns the current effective votes cast by one account, with cursor pagination and optional proposal-status filtering.",
+    params(
+        ("account_id" = String, Path, description = "veNEAR account id"),
+        VenearAccountVotesQuery
+    ),
     tag = "venear",
     operation_id = "listVenearAccountVotesCanonical",
     responses(
@@ -342,7 +357,12 @@ pub async fn list_account_votes(
 #[utoipa::path(
     get,
     path = "/api/v1/venear/accounts/{account_id}/vote_history",
-    params(VenearAccountVoteHistoryQuery),
+    summary = "List vote history for one veNEAR account",
+    description = "Returns the full successful vote history for one account, with cursor pagination and optional proposal and event-type filters.",
+    params(
+        ("account_id" = String, Path, description = "veNEAR account id"),
+        VenearAccountVoteHistoryQuery
+    ),
     tag = "venear",
     operation_id = "listVenearAccountVoteHistoryCanonical",
     responses(
@@ -422,7 +442,12 @@ pub async fn list_account_vote_history(
 #[utoipa::path(
     get,
     path = "/api/v1/venear/accounts/{account_id}/voting_power_history",
-    params(VenearAccountVotingPowerHistoryQuery),
+    summary = "List voting power history for one veNEAR account",
+    description = "Returns derived voting-power mutations for one account, with cursor pagination and optional reason and proposal filters.",
+    params(
+        ("account_id" = String, Path, description = "veNEAR account id"),
+        VenearAccountVotingPowerHistoryQuery
+    ),
     tag = "venear",
     operation_id = "listVenearAccountVotingPowerHistoryCanonical",
     responses(
@@ -497,7 +522,12 @@ pub async fn list_account_voting_power_history(
 #[utoipa::path(
     get,
     path = "/api/v1/venear/accounts/{account_id}/rewards_events",
-    params(VenearAccountRewardsEventsQuery),
+    summary = "List reward events for one veNEAR account",
+    description = "Returns reward and claim events associated with one account, with cursor pagination and optional event-type filtering.",
+    params(
+        ("account_id" = String, Path, description = "veNEAR account id"),
+        VenearAccountRewardsEventsQuery
+    ),
     tag = "venear",
     operation_id = "listVenearAccountRewardsEventsCanonical",
     responses(

api/src/handlers/venear/activity.rs

@@ -27,6 +27,8 @@ struct OffsetCursor {
 #[utoipa::path(
     get,
     path = "/api/v1/venear/activity",
+    summary = "List veNEAR activity",
+    description = "Returns a normalized cross-domain veNEAR activity feed, with cursor pagination and optional kind, account, proposal, contract, event-type, and success filters.",
     params(VenearActivityQuery),
     tag = "venear",
     operation_id = "listVenearActivityCanonical",

api/src/handlers/venear/admin.rs

@@ -30,6 +30,8 @@ pub(crate) struct AdminActionProjection {
 #[utoipa::path(
     get,
     path = "/api/v1/venear/admin/actions",
+    summary = "List veNEAR admin actions",
+    description = "Returns admin and operator actions derived from canonical NEAR actions, with cursor pagination and optional contract, event-type, actor, and success filters.",
     params(VenearAdminActionsQuery),
     tag = "venear",
     operation_id = "listVenearAdminActionsCanonical",

api/src/handlers/venear/config.rs

@@ -50,6 +50,8 @@ pub(crate) struct ConfigSnapshotProjection {
 #[utoipa::path(
     get,
     path = "/api/v1/venear/config",
+    summary = "Get current veNEAR config snapshots",
+    description = "Returns the latest canonical config snapshots for each veNEAR contract tracked by the indexer.",
     tag = "venear",
     operation_id = "getVenearConfigCanonical",
     responses(
@@ -90,6 +92,8 @@ pub async fn get_config(
 #[utoipa::path(
     get,
     path = "/api/v1/venear/config/history",
+    summary = "List veNEAR config history",
+    description = "Returns normalized config change history derived from canonical NEAR actions, with cursor pagination and optional contract, field, and method filters.",
     params(VenearConfigHistoryQueryV2),
     tag = "venear",
     operation_id = "listVenearConfigHistoryCanonical",

api/src/handlers/venear/delegations.rs

@@ -44,6 +44,8 @@ pub(crate) struct DelegationEdgeProjection {
 #[utoipa::path(
     get,
     path = "/api/v1/venear/delegations",
+    summary = "List active veNEAR delegations",
+    description = "Returns the current active delegation edges, with cursor pagination and optional delegator and delegatee filters.",
     params(VenearDelegationsQueryV2),
     tag = "venear",
     operation_id = "listVenearDelegationsCanonical",
@@ -251,7 +253,12 @@ pub(crate) async fn load_active_delegations(
 #[utoipa::path(
     get,
     path = "/api/v1/venear/accounts/{account_id}/delegation_history",
-    params(VenearAccountDelegationHistoryQuery),
+    summary = "List delegation history for one veNEAR account",
+    description = "Returns inbound and outbound delegation events involving one account, with cursor pagination and optional direction, event-type, and counterparty filters.",
+    params(
+        ("account_id" = String, Path, description = "veNEAR account id"),
+        VenearAccountDelegationHistoryQuery
+    ),
     tag = "venear",
     operation_id = "listVenearAccountDelegationHistoryCanonical",
     responses(

api/src/handlers/venear/lockups.rs

@@ -50,6 +50,8 @@ pub(crate) struct LockupProjection {
 #[utoipa::path(
     get,
     path = "/api/v1/venear/lockups",
+    summary = "List veNEAR lockups",
+    description = "Returns current lockup summaries, with cursor pagination and optional owner, status, and delegatee-presence filters.",
     params(VenearLockupsQuery),
     tag = "venear",
     operation_id = "listVenearLockupsCanonical",
@@ -120,6 +122,9 @@ pub async fn list_lockups(
 #[utoipa::path(
     get,
     path = "/api/v1/venear/lockups/{lockup_account_id}",
+    summary = "Get one veNEAR lockup",
+    description = "Fetches the current canonical lockup detail for one lockup account id.",
+    params(("lockup_account_id" = String, Path, description = "veNEAR lockup account id")),
     tag = "venear",
     operation_id = "getVenearLockupCanonical",
     responses(
@@ -154,7 +159,12 @@ pub async fn get_lockup(
 #[utoipa::path(
     get,
     path = "/api/v1/venear/lockups/{lockup_account_id}/events",
-    params(VenearLockupEventsQuery),
+    summary = "List events for one veNEAR lockup",
+    description = "Returns lifecycle events for one lockup account, with cursor pagination and optional event-type filtering.",
+    params(
+        ("lockup_account_id" = String, Path, description = "veNEAR lockup account id"),
+        VenearLockupEventsQuery
+    ),
     tag = "venear",
     operation_id = "listVenearLockupEventsCanonical",
     responses(
@@ -233,7 +243,12 @@ pub async fn list_lockup_events(
 #[utoipa::path(
     get,
     path = "/api/v1/venear/accounts/{account_id}/lockup_events",
-    params(VenearAccountLockupEventsQuery),
+    summary = "List lockup events for one veNEAR account",
+    description = "Returns lockup lifecycle events associated with one account, with cursor pagination and optional event-type filtering.",
+    params(
+        ("account_id" = String, Path, description = "veNEAR account id"),
+        VenearAccountLockupEventsQuery
+    ),
     tag = "venear",
     operation_id = "listVenearAccountLockupEventsCanonical",
     responses(