feat(minibf): add /accounts/{stake_address}/addresses/assets endpoint

[slowbackspace]

Summary

Closes #1067 by adding the Blockfrost-compatible GET /accounts/{stake_address}/addresses/assets endpoint.

• Aggregates native assets across the account’s current UTxOs, excluding lovelace
• Supports count, page, and order
• Returns 404 for unknown accounts and existing MiniBF errors for invalid requests and storage failures
• Shares one query facade across block-metadata lookups to respect the blocking-task limit
• Updates MiniBF documentation

Ordering semantics

Because the directions use different keys, desc is not necessarily the reverse of asc.

• asc: each asset’s oldest current UTxO
• desc: each asset’s newest current UTxO
• ties: asset unit ascending

This reproduces the reference implementation (blockfrost-backend-ryo, accounts_stake_address_addresses_assets.sql: MIN(txo.id) ASC / MAX(txo.id) DESC, tie-break (policy, name) ASC), with the tuple (slot, tx_index, output_index) standing in for db-sync's monotone txo.id. The route test accounts_by_stake_addresses_assets_uses_directional_ordering pins the exact asc and desc sequences, including the non-reversal and the tie-break cases.

Testing

• Route-level coverage: aggregation across UTxOs, direction-dependent ordering with position ties and unit tie-breaking (custom fixture state injected via the new TestApp::new_with_cfg_and_setup), pagination including past-the-end pages, invalid stake addresses, unknown accounts, storage failures
• Verified against live Blockfrost preview: the full 116-unit asset list of the blockfrost-tests fixture account is byte-identical in both asc and desc, as are pagination windows and the 400/404 error responses.

Known deviations

• Collateral-return UTxOs of failed txs are included. The reference blockfrost-backend-ryo query predates collateral-return outputs so Blockfrost misses assets held via unspent collateral returns. Dolos aggregates from the ledger-true UTxO set, so these appear naturally. Practically unobservable outside that rare case; same ledger-truth stance as fix(minibf): return affected addresses from /blocks/{hash_or_number}/addresses #1124
• Invalid stake addresses return a bare 400 (no JSON error body) — pre-existing behavior shared by all account endpoints, deliberately left untouched here

Summary by CodeRabbit

• New Features

  • Added an endpoint to retrieve assets held across all addresses associated with a stake address.
  • Aggregates asset quantities across relevant UTxOs.
  • Supports sorting holdings by oldest or newest and paginating results.
  • Provides validation and error handling for invalid stake addresses or unavailable asset data.

• Documentation

  • Updated the Mini Blockfrost API documentation to include the new endpoint.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 7cd5231f-6776-43ed-a0a3-b584d3e815fe

📥 Commits

Reviewing files that changed from the base of the PR and between f38f5d1 and c66271c.

📒 Files selected for processing (5)

• crates/minibf/src/lib.rs
• crates/minibf/src/mapping.rs
• crates/minibf/src/routes/accounts.rs
• crates/minibf/src/test_support.rs
• docs/content/apis/minibf.mdx

🚧 Files skipped from review as they are similar to previous changes (4)

• docs/content/apis/minibf.mdx
• crates/minibf/src/lib.rs
• crates/minibf/src/mapping.rs
• crates/minibf/src/test_support.rs

---

📝 Walkthrough

Walkthrough

MiniBF adds /accounts/{stake_address}/addresses/assets. The endpoint aggregates assets across stake-address UTxOs, supports ordering and pagination, includes endpoint tests and synthetic test setup, wires the route, and documents the endpoint.

Changes

Stake address assets

Layer / File(s)	Summary
Asset aggregation crates/minibf/src/mapping.rs	Adds AssetAggregate and ordered aggregation of asset quantities with oldest and newest UTxO positions.
Endpoint handler and routing crates/minibf/src/routes/accounts.rs, crates/minibf/src/lib.rs	Validates stake addresses, loads UTxOs and block metadata, aggregates and paginates assets, and registers the new GET route.
Endpoint fixtures and validation crates/minibf/src/test_support.rs, crates/minibf/src/routes/accounts.rs, docs/content/apis/minibf.mdx	Adds configurable synthetic test setup, endpoint helpers and tests for success, errors, aggregation, ordering, and pagination, and documents the route.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related PRs

• txpipe/dolos#735: Adds a related Mini Blockfrost asset endpoint with UTxO aggregation and pagination.
• txpipe/dolos#1127: Adds related stake-address account routing in minibf for a different endpoint.

Suggested labels: enhancement, area:minibf

Suggested reviewers: scarmuega, gonzalezzfelipe

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant MiniBF
  participant UTxOStore
  participant AssetAggregator

  Client->>MiniBF: GET /accounts/{stake_address}/addresses/assets
  MiniBF->>UTxOStore: Load stake UTxOs and block metadata
  MiniBF->>AssetAggregator: Aggregate assets by unit
  AssetAggregator-->>MiniBF: Quantities and UTxO positions
  MiniBF-->>Client: Ordered, paginated JSON assets

Loading

🚥 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 clearly identifies the new /accounts/{stake_address}/addresses/assets endpoint, which is the primary change.
Linked Issues check	✅ Passed	The PR implements the requested endpoint by aggregating assets over the stake-address UTxO index and adds routing, tests, and documentation.
Out of Scope Changes check	✅ Passed	The routing, aggregation, metadata lookup, tests, test support, and documentation changes directly support the endpoint objective.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/minibf-account-addresses-assets

---

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.}

[Copilot]

Pull request overview

Adds a Blockfrost-compatible MiniBF endpoint for listing the native assets held across all current UTxOs for a given stake address, integrating it into the existing facade/query patterns and expanding route-level coverage.

Changes:

• Added GET /accounts/{stake_address}/addresses/assets route, including pagination and direction-dependent ordering based on UTxO positions.
• Implemented asset aggregation logic over the account’s current UTxO set (excluding lovelace) with position tracking for ordering.
• Extended test support to allow synthetic fixture setup hooks and added route-level tests covering success/error/pagination/ordering semantics.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
docs/content/apis/minibf.mdx	Documents the new /accounts/{stake_address}/addresses/assets endpoint in the MiniBF API list.
crates/minibf/src/test_support.rs	Adds a setup hook constructor to mutate synthetic fixture state before building the app.
crates/minibf/src/routes/accounts.rs	Implements the new account-assets endpoint and adds comprehensive route tests.
crates/minibf/src/mapping.rs	Adds asset aggregation helper that sums quantities per unit and tracks oldest/newest UTxO positions.
crates/minibf/src/lib.rs	Registers the new route on the MiniBF router.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@crates/minibf/src/routes/accounts.rs`:
- Around line 297-371: Bound work in by_stake_addresses_assets before decoding
all UTxOs and issuing block_meta_by_tx_hash calls, reusing the sibling
by_stake_addresses handler’s pagination.enforce_max_scan_limit-style protection.
Ensure the cap limits both UTxO scanning and the resulting unique transaction
fan-out while preserving the existing pagination ordering and results within the
allowed scan range.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 72b580db-2763-4533-ae9c-df4bcf9bbc18

📥 Commits

Reviewing files that changed from the base of the PR and between e7bda35 and a99e953.

📒 Files selected for processing (5)

• crates/minibf/src/lib.rs
• crates/minibf/src/mapping.rs
• crates/minibf/src/routes/accounts.rs
• crates/minibf/src/test_support.rs
• docs/content/apis/minibf.mdx

[coderabbitai]

Note

GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer.