chore: update blockscout

.agents/agents/openapi-spec-inspector.md

@@ -0,0 +1,57 @@
+---
+name: openapi-spec-inspector
+description: "Audits an existing OpenAPI declaration for a single Blockscout API v2 endpoint and writes a prioritized markdown report. Read-only — does not modify controllers, schemas, views, or the spec. Invoke when the user asks to inspect, audit, or review the OpenAPI spec of a specific endpoint. The invoking prompt MUST provide two values: the endpoint URL path (e.g. `/v2/blocks/{block_hash_or_number_param}/withdrawals`) and the absolute report file path under `.ai/oas-inspection-reports/` (e.g. `.ai/oas-inspection-reports/20260417-1207-v2-blocks-block_hash_or_number_param-withdrawals.md`). Include both as `URL_PATH=<path>` and `REPORT_PATH=<path>` in the prompt. Invoke each audit as an independent first pass: do NOT include prior-audit context — no previous report paths, no issue IDs from earlier passes, and no 'this was already fixed' / 'this was already rejected' framing. Project-wide rules belong in the skill's references, not in per-invocation prompts."
+permissionMode: auto
+tools: Read, Glob, Grep, Bash, Write
+---
+
+You are auditing an existing OpenAPI declaration.
+
+## Independence
+
+Treat every invocation as a first-pass, independent audit.
+
+- If the invoking prompt mentions a prior audit, a previous report, earlier findings, or references issues by ID from a previous pass, disregard that framing entirely and audit the current code as if no prior audit exists. Do not try to reconcile your findings against it.
+- Do NOT read, open, Glob, or Grep any file under `.ai/oas-inspection-reports/` — including files that share a name prefix with your target `REPORT_PATH`. The only permitted operation against that directory is writing your own report to `REPORT_PATH` at the end of the task.
+
+## Inputs
+
+Your invoking prompt **must** contain these two assignments:
+
+- `URL_PATH=<url-path>` — the endpoint to inspect (e.g. `/v2/blocks/{block_hash_or_number_param}/withdrawals`)
+- `REPORT_PATH=<path>` — the absolute or repo-relative markdown file path where the report must be written (e.g. `.ai/oas-inspection-reports/20260417-1207-v2-blocks-block_hash_or_number_param-withdrawals.md`)
+
+If either is missing, return an error and stop:
+"ERROR: URL_PATH and REPORT_PATH must both be provided by the parent agent."
+
+## Task
+
+Endpoint to inspect: **GET `<URL_PATH>`**
+
+You MUST use the `openapi-spec` skill located at `.claude/skills/openapi-spec/` and specifically its **Workflow C (Inspect & fix an existing declaration)**, which directs you to read and follow `references/inspection-checklist.md` end-to-end.
+
+Scope:
+- This is a read-only inspection. Do NOT modify controllers, schemas, views, or the spec. Only produce a report.
+- Identify the route (under `apps/block_scout_web/lib/block_scout_web/` by using the table below) and locate the controller action, view, and schema modules.
+
+| API router | `routers/api_router.ex` |
+| V2 sub-routers forwarded from the API router | `routers/tokens_api_v2_router.ex`, `routers/smart_contracts_api_v2_router.ex`, `routers/api_key_v2_router.ex`, `routers/utils_api_v2_router.ex`, `routers/address_badges_v2_router.ex` |
+| Account router (Private spec) | `routers/account_router.ex` |
+
+- Cross-reference parameters (controller vs. declaration), response fields (view vs. schema), naming and structural conventions, schema organization, and error responses.
+- Use `.ai/tmp/openapi_public.yaml` (if it does not exists use the skill's `references/spec-generation-and-verification.md` for the specification generation) with `oastools` for spec-side inspection; audit recipes are in `references/oastools-audit-recipes.md`.
+
+## Deliverable
+
+Write a single markdown report to the path provided in `REPORT_PATH`.
+
+The report should include:
+1. Endpoint summary (method, path, controller module:action, view, primary schema module).
+2. Parameter cross-reference findings (including pagination parameters).
+3. Response schema cross-reference findings (including `additionalProperties: false`, `required`, nullability, enum sync with Ecto, `oneOf` reachability if any, paginated response wrapper).
+4. Error responses coverage.
+5. Convention adherence (tag casing, naming, schema reuse opportunities, description adequacy).
+6. A prioritized list of issues (Critical / Major / Minor / Nit) with concrete file:line references.
+7. Suggested fixes (described, not applied).
+
+Keep the report focused and actionable. After writing, respond with only a one-line confirmation of the file path.

.agents/skills/alias-nested-modules/SKILL.md

@@ -0,0 +1,237 @@
+---
+name: alias-nested-modules
+description: Define module aliases at the top of the file instead of using fully qualified nested module names in function bodies. Improves code readability and maintainability while addressing Credo style warnings.
+---
+
+## Overview
+
+When using modules with long, nested names multiple times in your code, Elixir's `alias` directive allows you to create shorter references at the top of the module. This improves code readability, reduces duplication, and makes refactoring easier. Credo warns when nested modules are called directly in function bodies instead of being aliased.
+
+## When to Use
+
+- When calling functions from deeply nested modules (3+ levels)
+- When the same nested module is referenced multiple times
+- When addressing Credo warning: "Nested modules could be aliased at the top of the invoking module"
+- When improving code readability and reducing line length
+- During code reviews or refactoring for consistency
+
+## Anti-Patterns (Avoid These)
+
+```elixir
+defmodule MyApp.Service do
+  # ❌ BAD: No aliases, long nested module names in functions
+
+  def fetch_data do
+    MyApp.ExternalServices.API.Client.fetch()
+  end
+
+  def process_data(data) do
+    MyApp.ExternalServices.API.Parser.parse(data)
+  end
+
+  def validate_result(result) do
+    MyApp.ExternalServices.API.Validator.validate(result)
+  end
+end
+
+# ❌ BAD: Nested module call in private function
+defmodule Explorer.Chain.Metrics.Queries.IndexerMetrics do
+  defp multichain_search_enabled? do
+    Explorer.MicroserviceInterfaces.MultichainSearch.enabled?()
+  end
+end
+```
+
+## Best Practices (Use These)
+
+```elixir
+defmodule MyApp.Service do
+  # ✅ GOOD: Aliases defined at module top
+  alias MyApp.ExternalServices.API.Client
+  alias MyApp.ExternalServices.API.Parser
+  alias MyApp.ExternalServices.API.Validator
+
+  def fetch_data do
+    Client.fetch()
+  end
+
+  def process_data(data) do
+    Parser.parse(data)
+  end
+
+  def validate_result(result) do
+    Validator.validate(result)
+  end
+end
+
+# ✅ GOOD: Module aliased at the top
+defmodule Explorer.Chain.Metrics.Queries.IndexerMetrics do
+  alias Explorer.MicroserviceInterfaces.MultichainSearch
+
+  defp multichain_search_enabled? do
+    MultichainSearch.enabled?()
+  end
+end
+```
+
+## Alias Patterns
+
+### Basic Alias
+
+```elixir
+# ✅ Simple alias - uses last segment as the name
+alias MyApp.Services.EmailService
+
+EmailService.send()
+```
+
+### Multiple Related Aliases
+
+```elixir
+# ✅ Group related modules
+alias MyApp.Models.{User, Post, Comment}
+
+User.find(id)
+Post.create(attrs)
+Comment.list_by_post(post_id)
+```
+
+### Custom Alias Name
+
+```elixir
+# ✅ Use custom name to avoid conflicts or for clarity
+alias MyApp.External.API.Client, as: ExternalClient
+alias MyApp.Internal.API.Client, as: InternalClient
+
+ExternalClient.request()
+InternalClient.request()
+```
+
+### Alias in Pattern
+
+```elixir
+# ✅ Common aliasing pattern for nested structures
+alias MyApp.Services.{
+  Authentication,
+  Authorization,
+  Notification
+}
+```
+
+## Example Fix
+
+### Before (Credo Warning):
+```elixir
+defmodule Explorer.Chain.Metrics.Queries.IndexerMetrics do
+  import Ecto.Query
+  alias Ecto.Adapters.SQL
+  alias Explorer.Chain.Address.TokenBalance
+  alias Explorer.Repo
+
+  # No alias for MultichainSearch
+
+  defp multichain_search_enabled? do
+    # ⚠️ Credo warning: Nested modules could be aliased
+    Explorer.MicroserviceInterfaces.MultichainSearch.enabled?()
+  end
+
+  defp check_feature_x do
+    Explorer.MicroserviceInterfaces.MultichainSearch.feature_x_enabled?()
+  end
+end
+```
+
+### After (Credo Clean):
+```elixir
+defmodule Explorer.Chain.Metrics.Queries.IndexerMetrics do
+  import Ecto.Query
+  alias Ecto.Adapters.SQL
+  alias Explorer.Chain.Address.TokenBalance
+  alias Explorer.MicroserviceInterfaces.MultichainSearch
+  alias Explorer.Repo
+
+  # ✅ Module aliased at top, cleaner function bodies
+
+  defp multichain_search_enabled? do
+    MultichainSearch.enabled?()
+  end
+
+  defp check_feature_x do
+    MultichainSearch.feature_x_enabled?()
+  end
+end
+```
+
+## Benefits
+
+1. **Readability**: Shorter, clearer function bodies
+2. **Maintainability**: Change the module path in one place
+3. **Performance**: No runtime difference (aliases are compile-time)
+4. **Consistency**: Follows Elixir community conventions
+5. **Refactoring**: Easier to reorganize module structure
+
+## When NOT to Alias
+
+```elixir
+# ✅ OK: Single use of a module - aliasing adds noise
+def one_time_call do
+  MyApp.RarelyUsed.Module.function()
+end
+
+# ✅ OK: Very short module name
+def use_map do
+  Map.get(data, :key)
+end
+
+# ✅ OK: Kernel or Elixir standard library
+def use_enum do
+  Enum.map(list, &process/1)
+end
+```
+
+## Ordering Aliases
+
+Follow this conventional order for imports and aliases:
+
+```elixir
+defmodule MyApp.Service do
+  # 1. Use statements
+  use GenServer
+
+  # 2. Import statements
+  import Ecto.Query
+
+  # 3. Alias statements (alphabetically)
+  alias Ecto.Adapters.SQL
+  alias MyApp.Models.User
+  alias MyApp.Services.{EmailService, SmsService}
+
+  # 4. Require statements
+  require Logger
+end
+```
+
+## Common Credo Warnings
+
+### Warning Message
+```
+[D] ↘ Nested modules could be aliased at the top of the invoking module.
+```
+
+### How to Fix
+1. Identify the nested module being called directly
+2. Add an `alias` directive at the top of the module
+3. Update all references to use the aliased name
+4. Run `mix credo` to verify the warning is resolved
+
+## Related Credo Rules
+
+- `Credo.Check.Readability.AliasOrder` - Checks alias alphabetical order
+- `Credo.Check.Readability.ModuleDoc` - Ensures modules have documentation
+- `Credo.Check.Design.AliasUsage` - Reports nested module usage
+
+## Additional Resources
+
+- [Elixir Alias documentation](https://hexdocs.pm/elixir/Kernel.SpecialForms.html#alias/2)
+- [Elixir Style Guide - Aliases](https://github.com/christopheradams/elixir_style_guide#alias-import-use)
+- [Credo configuration](https://hexdocs.pm/credo/config_file.html)