feat(api): Scala-compat /emission/at + fix auth-layer capture of the router fallback

[arkadianet]

Summary

Two stacked defects made GET /emission/at/{blockHeight} answer 403 invalid.api-key on a node with security configured:

1. The route was never implemented — the honest answer was a 404.
2. The api_key middleware was mounted with Router::layer, which also wraps the subtree's implicit fallback; Router::merge then propagates that wrapped fallback into the assembled router. Net effect: every unmatched path node-wide rejected on the key instead of 404ing, masking "route does not exist" as "you need a key". The blockchain indexer status-gate had the same latent capture (unknown paths would have answered 503 indexer-syncing during catch-up once the auth wrap was gone).

The fallback fix

• All route middleware (require_api_key ×2, enforce_status_gate) now mounts via route_layer — matched routes only, the fallback stays pristine. Unmatched paths answer a plain, ungated 404 (house unmounted-surface rule).
• Scala's whole-prefix gating survives via explicit catch-all routes: unknown /wallet/* and /node/* subpaths still reject on the key first (parity with pathPrefix(...) & withAuth, probed live against the reference node), then 404 once the key passes.
• The public /wallet/ui statics are unaffected — exact-path routes outrank the gated wildcard (pinned by the existing wallet_ui_auth_scope tests).

The endpoint

GET /emission/at/{blockHeight} — EIP-27-aware Scala-parity quintuple (height, minerReward, totalCoinsIssued, totalRemainCoins, reemitted) mirroring EmissionApiRoute.emissionInfoAtHeight. Public (no withAuth in Scala), mounted in every node mode — the schedule is static per-network math.

• Cumulative-issuance primitives join ergo-mining::emission_rules with Scala line citations: issued_coins_after_height (incl. the fixedRate × (fixedRatePeriod − 1) quirk), coins_and_blocks_total (verbatim walk), emission_info_at_height (takes Option<&ReemissionSettings> — None ⇒ reemitted: 0 for specs without EIP-27).
• ergo-api stays traits-only: new EmissionSchedule view + EmissionInfoJson wire shape; ergo-node's EmissionScheduleBridge implements it over the chain spec, caching coinsTotal at boot (Scala holds it as a lazy val).
• GET /emission/scripts is deferred — the emission/reemission/pay2Reemission tree predefs aren't exposed in the workspace yet. Documented in compatibility.md; its live-Scala oracle capture ships at test-vectors/api/emission/scripts.json.

Testing

• TDD throughout: the fallback regression test was red (403 ≠ 404) before the fix; the emission tests were captured-oracle-first.
• 17 differential vectors captured from a live Scala mainnet node (test-vectors/api/emission/): genesis edge, fixed-rate boundary 525599/525600, founders end 655199/655200, EIP-27 activation 777216/777217, the 15 ERG era, emission end 2080799/2080800, past-the-end clamps. Pins coinsTotal = 97,739,925 ERG, blocksTotal = 2,080,799.
• New assembled-router mount-matrix tests close the previously documented coverage gap in tests/auth.rs (the real merge path was untested — exactly where this bug lived).
• Full workspace suite green; live-verified on a deployed node: byte-identical /emission/at responses vs the reference Scala node at three heights, /zzz → 404 bare, prefix gating intact, malformed height → 400.

Docs

CHANGELOG.md (Added + Fixed), docs/configuration.md + docs/operating.md (gate-scope clarification, /emission/* listed public), docs/compatibility.md (/emission surface status).

🤖 Generated with Claude Code

Summary by CodeRabbit

Release Notes

• New Features

  • Added /emission/at/{blockHeight} API endpoint for querying per-height emission schedule data, including EIP-27-aware reemission handling.

• Bug Fixes

  • Fixed API key authentication behavior: unknown paths now return 404 Not Found instead of 403 Forbidden when the api_key gate is configured.

• Documentation

  • Clarified API security scope and authentication boundaries for /wallet/* and /node/* routes.
  • Documented the new emission endpoint with known limitations (emission scripts endpoint not yet implemented).

[coderabbitai]

Warning

Review limit reached

@arkadianet, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 50 minutes and 34 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 3730910e-f146-413d-b5ee-8a697b88dc4d

📥 Commits

Reviewing files that changed from the base of the PR and between 933117c and 89b5a8d.

📒 Files selected for processing (4)

• ergo-api/src/server.rs
• ergo-mining/src/emission_rules.rs
• ergo-node/src/api_bridge.rs
• ergo-node/src/node/boot.rs

📝 Walkthrough

Walkthrough

This PR introduces a Scala-compatible /emission/at/{blockHeight} REST endpoint and fixes API-key middleware to return 404 (not 403) for unknown routes. Emission computation is added to mining rules, bridged through an adapter in the node layer, and mounted into the server when configured; auth gating now uses route-scoped middleware instead of subtree-wide layers.

Changes

Emission API & Auth Behavior

Layer / File(s)	Summary
Documentation updates CHANGELOG.md, docs/compatibility.md, docs/configuration.md, docs/operating.md	CHANGELOG and docs clarify new /emission/at/{blockHeight} endpoint (EIP-27-aware), confirm /emission/scripts remains unimplemented, and document corrected API-key gating behavior (unknown routes return ungated 404, not 403).
Auth middleware fallback correction ergo-api/src/auth.rs, ergo-api/src/wallet/mod.rs, ergo-api/tests/auth.rs	Introduces unknown_gated_subpath handler returning 404 for post-auth catches; updates /wallet/* and admin shutdown routing to use route_layer (not layer) so auth only applies to matched routes, preventing fallback from masking unmatched paths as 403.
Emission computation logic ergo-mining/src/emission_rules.rs	Adds cumulative-emission helpers (issued_coins_after_height, coins_and_blocks_total) and EmissionInfo struct composing miner reward, issued/remaining coins, and reemission amount (EIP-27-aware). Extends tests with live-Scala oracle vector validation.
Emission API contract & routing ergo-api/src/emission.rs, ergo-api/src/lib.rs	Defines EmissionSchedule trait and EmissionInfoJson struct with camelCased fields; implements emission_router that mounts GET /emission/at/:height and attaches schedule as shared state.
Emission bridge (mining → API) ergo-node/src/api_bridge.rs, ergo-node/src/api_bridge/emission.rs	Implements EmissionScheduleBridge as trait adapter, caching coins_total and delegating emission_info_at to mining rules; exposes bridge through api_bridge module and validates against live-Scala vectors.
Server context & route mounting ergo-api/src/server.rs, ergo-node/src/node/boot.rs	ServerCtx adds optional emission field; router construction threads field through legacy/test paths (as None) and production path (as EmissionScheduleBridge); admin and blockchain routes switch to route_layer to restrict gating scope.
Auth behavior & emission routing tests ergo-api/tests/openapi_native_runtime_mount.rs	Adds regression tests for auth fallback behavior (unknown paths return 404, never 403), whole-prefix gating on /wallet/* and /node/* (403 without key, 404 with), and /emission/at/:height public access with JSON envelope validation.
Emission test vectors (Scala oracle) test-vectors/api/emission/*	Captures per-height emission snapshots at key mainnet heights and scripts fixture; used for live-Scala oracle validation.
Test helper updates (ServerCtx) ergo-api/tests/*.rs	Updates all test fixtures to include emission: None field in ServerCtx initializers across blockchain, wallet, mempool, and integration test suites.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 Hopping with glee, the API takes flight,
New emission routes shining in pure Scala light,
Auth gates now answer with proper 404s,
Not hiding as 403s behind closed doors,
Whole-prefix paths guarded, the routing pure and bright! 🚀

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the two main changes: implementing the Scala-compatible /emission/at endpoint and fixing the auth-layer middleware mounting issue that was incorrectly capturing router fallbacks.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/api-emission-at-and-fallback-403

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}