Sync upstream v11.2.2 (merge conflicts)

[JOY (JOY)]

Upstream Sync - v11.2.2

Auto-merge with upstream v11.2.2 failed. Version/workflow conflicts were auto-resolved,
but the following files have code conflicts that need manual resolution:

docker-compose/envs/common-blockscout.env

To resolve:

1. Check out this branch locally
2. Resolve remaining conflicts
3. Push and merge this PR
4. Then create tag v11.2.2 to trigger Docker build

Upstream release notes

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[gemini-code-assist]

Code Review

This pull request introduces comprehensive OpenAPI specifications for the advanced filter and Arbitrum endpoints, updates the real-time event notifier to optimize broadcasting based on active subscribers, and adds extensive documentation and SPDX license headers. Feedback on these changes highlights several critical issues: a distributed-mode bug in the notifier's subscriber check that silences updates in clustered environments, a performance regression where non-preloaded token transfers are published to GraphQL subscriptions, a missing 'ZRC-2' enum value in the advanced filter schema, a missing Ecto enum sync comment in the commitment transaction schema, and a potential FunctionClauseError crash in the advanced filter controller when the optional 'q' parameter is omitted.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

Checking local subscribers using Registry.lookup(BlockScoutWeb.PubSub, topic) is a critical bug in distributed or split-mode deployments (such as separate API/Indexer mode).

In a multi-node cluster (using libcluster and a distributed Phoenix PubSub adapter like Phoenix.PubSub.PG2 or Redis), the local Registry on any given node only contains subscription information for processes running on that specific node.

If Blockscout is deployed in separate API/Indexer mode, the indexer node processes blockchain events and runs the Notifier, but has no local websocket subscribers. Similarly, in a multi-node API pool, a subscriber might be connected to Node A while the event is processed on Node B.

Because Registry.lookup/2 only queries the local node's registry, checking address_has_subscribers?/1 on the indexer node or a different API node will return false, causing the event to be silently filtered out and never broadcasted to the nodes where subscribers actually reside. This completely breaks real-time updates for users in clustered or split-mode environments.

To restore correct distributed real-time updates, these local subscriber checks should be bypassed or removed entirely, allowing Phoenix PubSub to handle the distribution of messages to nodes with active subscriptions.

  defp has_subscribers?(_topic), do: true

[gemini-code-assist]

Publishing non-preloaded token_transfers to Absinthe GraphQL subscriptions is an efficiency regression.

In the original implementation, Subscription.publish/3 was called with token_transfers that were part of all_token_transfers_full (which had been fully preloaded with :token, :transaction, :from_address, and :to_address associations).

By publishing non-preloaded structs, any active GraphQL subscription clients querying nested fields (such as token, transaction, fromAddress, or toAddress) will trigger synchronous, on-demand database queries during resolution. Under high load, this will lead to severe N+1 query issues and massive database strain.

To prevent this, ensure that only fully preloaded token transfers are published to the GraphQL subscription.

[gemini-code-assist]

The type enum list is missing the "ZRC-2" token type, which is a valid token type on Zilliqa chains.

The parameter description for transaction_types in AdvancedFilterController explicitly mentions:
Allowed values: ... (plus ZRC-2 on Zilliqa).

If a Zilliqa chain is used and a ZRC-2 transfer is returned, the view will emit "ZRC-2". Since this value is not declared in the enum list of the schema, response validation in tests or client-side validation will fail.

Please add "ZRC-2" to the enum list to ensure full compatibility with Zilliqa chains.

      type: %Schema{
        type: :string,
        enum: [
          "coin_transfer",
          "contract_interaction",
          "contract_creation",
          "ERC-20",
          "ERC-721",
          "ERC-1155",
          "ERC-404",
          "ERC-7984",
          "ZRC-2"
        ],

[gemini-code-assist]

According to the repository's schema conventions in schema-conventions.md, every enum: property in an OpenAPI schema must have a comment pointing to the source Ecto field or type (e.g., # Enum values must be kept in sync with Explorer.Chain.<Module> :<field_name> field.).

The status property in CommitmentTransaction is missing this mandatory sync comment. Please add a comment above the property definition pointing to the source Ecto field or type to ensure future maintainability.

      # Enum values must be kept in sync with Explorer.Chain.Arbitrum.L1Batch :status field.
      status: %Schema{
        type: :string,
        enum: ["unfinalized", "finalized"],
        nullable: true,
        description: "Finalization status of the Parent chain transaction."
      }

References

1. Every enum: property in an OpenAPI schema must have a comment pointing to the source Ecto field. ^(link)

[gemini-code-assist]

The list_methods/2 action only defines a clause for when q is present and is a binary. However, the :q parameter is declared as optional (required: false) in the OpenAPI spec.

If a client requests /api/v2/advanced-filters/methods without the q parameter, params will either omit :q or have it as nil. In either case, the current clause will fail to match, resulting in a FunctionClauseError crash.

Please add a fallback clause to handle the case when q is missing or nil (e.g., to return the default list of popular methods as described in the endpoint documentation).