Sync upstream v11.1.3 (merge conflicts)

[JOY (JOY)]

Upstream Sync - v11.1.3

Auto-merge with upstream v11.1.3 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.1.3 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, guides, and scripts for the Blockscout API v2, specifically targeting the advanced-filters and Arbitrum-related endpoints. It adds numerous OpenAPI schema modules, registers new operations in the controller files, and switches parameters from string keys to atom keys to support validation. Additionally, it adds agent guidelines, architecture documentation, and SPDX license headers across several files. The review feedback highlights a few critical issues: first, in ArbitrumController, the height parameter is cast to an Elixir integer but passed to calculate_celestia_data_key/2 which expects a string, potentially causing a runtime crash; second, in Arbitrum.Message, the use of allOf to override a primitive schema's description violates the repository's schema conventions, which recommend using Helper.extend_schema/2 at the property position instead; and third, in AdvancedFilter, the type enum is missing "ZRC-2", which will cause validation failures for Zilliqa transaction types.

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]

The height parameter is defined as an integer, which means CastAndValidate will cast it to an Elixir integer. However, calculate_celestia_data_key/2 expects height to be a string (as it was originally passed directly from string-keyed params without casting). Passing an integer will cause a runtime crash (e.g., ArgumentError or FunctionClauseError). Use Schemas.General.IntegerString to ensure it is validated and passed as a string.

      %OpenApiSpex.Parameter{
        name: :height,
        in: :path,
        required: true,
        schema: Schemas.General.IntegerString,
        description: "Celestia block height."
      },

[gemini-code-assist]

Using allOf with a single primitive leaf schema to override the description is discouraged by the repository's schema conventions. According to schema-conventions.md (§ Helper.extend_schema/2), Helper.extend_schema/2 should be used at the property position instead of allOf to avoid potential casting layer issues.

        origination_address_hash:
          Helper.extend_schema(General.AddressHashNullable.schema(),
            description: "Address that initiated the message on the originating chain."
          ),

References

1. Avoid %Schema{allOf: [Leaf], description: "..."} as the overlay mechanism. Use Helper.extend_schema at the property position instead. ^(link)

[gemini-code-assist]

The type enum is missing "ZRC-2", which is a valid transaction/token type on Zilliqa (as documented in the controller's description). Any response containing a ZRC-2 activity item will fail OpenAPI validation. Add "ZRC-2" to the enum list.

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