blockscout/blockscout v11.0.0

BlockScout v11.0.0

on GitHub

⚠️ v11.0.0 Installation Requirements

For existing instances: Version v11.0.0 must be installed on top of v10.1. Installing it on versions earlier than v10.1 will fail.
For new (greenfield) installations, this requirement does not apply - you can install v11.0.0 directly.

💥 v11.0.0 API Breaking Changes

This release introduces breaking changes and behavioral updates across multiple API surfaces. Please review and update your integrations accordingly.

1. Asynchronous CSV Export (Conditional Breaking Change)

CSV export endpoints can now operate in asynchronous mode, depending on configuration.

⚠️ Important:
This is a breaking change only for instances where async export is enabled.
If async mode is disabled, behavior remains unchanged (synchronous CSV download).

🔍 Detection

GET /api/v2/config/csv-export

Response:

{
  "async_enabled": true
}

• true → async mode enabled (breaking change applies)
• false → legacy synchronous behavior

🔄 Behavior When Async Mode Is Enabled

All CSV export endpoints (same URLs and query params as before) no longer return a file directly.

New responses:

• 202 Accepted

  { "request_id": "<uuid>" }

  Export job is queued. Use the request_id to poll for status.

• 409 Conflict

  { "error": "..." }

  Too many pending export jobs from the same IP.
  Limit controlled by CSV_EXPORT_ASYNC_MAX_PENDING_TASKS_PER_IP.

• 500 Internal Server Error

  { "error": "..." }

  Failed to create export job.

📌 Affected Endpoints

• Address CSV exports:

  • transactions
  • token transfers
  • logs
  • internal transactions
  • Celo election rewards (where applicable)

• Token holders CSV

• GET /api/v2/advanced-filters/csv

📊 Status & Result Retrieval

GET /api/v2/csv-exports/:uuid

• 200 OK

  {
    "status": "pending | completed | failed",
    "file_id": "<id>",
    "expires_at": "<timestamp>"
  }

• 404 Not Found
  → Unknown request_id

2. BENS Fields May Be Missing (Conditional Breaking Change)

BENS (ENS-like) data is now conditionally included.

When BENS preload is disabled, responses will not include:

ens_domain_name

📌 Affected Endpoints

• /api/v2/transactions
• /api/v2/addresses/:hash/transactions
• /api/v2/blocks/:hash/transactions
• /api/v2/token-transfers
• /api/v2/addresses/:hash/token-transfers
• /api/v2/tokens/:address_hash_param/transfers

⚠️ Impact

Clients must treat ens_domain_name as optional.

3. WebSocket new_block Payload Is Now Variable (Conditional Breaking Change)

The new_block event (block channel) may include additional fields:

• metadata
• ens_domain_name

⚠️ Important

These fields are configuration-dependent:

• Present on some explorer instances
• Absent on others

✅ Recommendation

Handle these fields as optional in WebSocket consumers.

4. Polygon zkEVM Removal (Breaking Change)

Support for Polygon zkEVM has been completely removed.

❌ Removed

• polygon-zkevm chain type

• All endpoints under:

  /api/v2/zkevm/*
  

⚠️ Impact

Any integration relying on zkEVM endpoints must be removed or migrated.

5. Transaction Actions Deprecated (Breaking Change)

The transaction_actions field has been removed.

📌 Affected Endpoint

GET /api/v2/transactions/:hash

⚠️ Impact

Clients must stop relying on:

transaction_actions

6. Stricter Validation for Chain-Specific Endpoints (Breaking Change)

OpenAPI specifications have been expanded to additional chain types (Scroll, Zilliqa, Celo), introducing stricter input validation.

⚠️ Impact

Endpoints now reject invalid or loosely formatted input that may have previously been accepted.

📌 Affected Endpoints

• /api/v2/scroll/*
• /api/v2/transactions/scroll-batch/*
• /api/v2/validators/zilliqa/*
• /api/v2/celo/*
• /api/v2/addresses/:hash/celo/*

🚀 Features

• Async CSV export (#14028)
• FHE operations and tags (#13742)
• Restore BENS preloads on the main page under toggle and add blocks BENS preload toggle (#14262)
• /api/legacy/* wrappers for three ES-compatible RPC endpoints (#14239)
• Make token balances import chunk size configurable (#14250)
• Add toggle to disable transactions / token transfers BENS preload (#14159)
• Add ENS and metadata preloading in block channel (#12074)
• Add validation for IPFS links before sending requests to gateway (#14131)
• Add search by token address hash in /api/v2/tokens (#14102)
• Add :rename heavy index db operation type and implement zero-downtime index replacement for transactions table (#14052)
• Use libraries field from eth bytecode db response (#13948)

🐛 Bug Fixes

• Fix filecoin view error (#14255)
• Internal transactions on-demand fetcher: check existence of deleted internal transactions address placeholders (#14249)
• Fix OnDemand.InternalTransaction fetcher (#14242)
• Guard missing ETS table in contract creator fetcher (#14241)
• Address ids usage improvements (#14240)
• Fix timeouts for API v1 tokentx endpoint (#14185)
• Remove internal transaction error field references (#14213)
• Handle partial errors in ContractCode fetch_codes (#14211)
• Include bridged token query params in OpenAPI spec (#14209)
• Update changed constraint name in shrink IT migration (#14205)
• Fix contract internal transactions preload (#14203)
• Handle RPC errors in ContractCreator, limit retries to 5 (#14136)
• Prevent duplicate missing block range inserts (#14138)
• Implementation address hash retrieval logic in the old UI (#14192)
• Keycloak address displaying (#14155)
• Celo election rewards csv export (#14160)
• Sync GraphQL language enum with SmartContract schema (#14109)
• Don't insert PTO for non-traceable transactions (#14133)
• Fix pending ops migration overflow by adaptive batching and chunked inserts (#14135)
• State changes use token transfer type (#14073)
• Fix 500 error when apikey provided with disabled account (#14064)
• Fix ArgumentError in BlockScoutWeb.NFTHelper.get_media_src/2 (#14051)

🚜 Refactor

• Refactor RollupReorgMonitorQueue (#14196)
• Deduplicate json_rpc_named_arguments (#14194)
• Fully migrate to language enum field in smart_contracts table (#14049)
• Migrate address_names to composite primary key on (address_hash, name) (#14078)

📚 Documentation

• Add .dialyzer-ignore hygiene guideline to CONTRIBUTING (#14199)

⚡ Performance

• Optimize token1155tx API v1 endpoint (#14202)
• Optimize optional address preloads across tx endpoints (#14165)
• Optimize on demand hot contracts performance (#14150)
• Remove join to "blocks" in api/v2/blocks/:block_number/transactions API endpoint (#14162)
• Improve performance of /api/v2/tokens API endpoint (#14158)

⚙️ Miscellaneous Tasks

• Update LICENCE (#14201)
• Remove "transaction_hash", "block_hash" and "block_index" from internal transactions, migrate Address Hashes to Address IDs (#14099)
• Remove timeout for test for FillInternalTransactionsAddressIds (#14266)
• Increase default timeout for FillInternalTransactionsAddressIds (#14264)
• Expand action of API_DISABLE_CONTRACT_CREATION_INTERNAL_TRANSACTION_ASSOCIATION flag to preload smart-contract associations ((#14257)[https://github.com//pull/14257])
• Add Autoscout promo in the logs (#14234)
• Improve internal transactions migrations (#14233)
• Remove unused Explorer.Chain.Address.find_contract_addresses/2 function (#14220)
• Prevent deadlocks in IT fields removing migration (#14215)
• Filter blocks by BLOCK_RANGES in add_ranges_by_block_numbers (#13875)
• FillInternalTransactionsAddressIds improvements (#14208)
• Remove timeout between successful migrations (#14198)
• Add batch size env for FillInternalTransactionsAddressIds migration (#14204)
• Add Celo OpenAPI specs (#14197, #14229)
• Cover counters to multichain export with unit tests (#14193)
• Update credo config (#14147)
• Remove Polygon zkEVM support (#14188)
• Add Block.full_refetch (#14180)
• Remove deprecated files from the root folder (#14186)
• Remove deprecated "transaction actions" indexer (#14183)
• Stabilize various flaky tests (#14149)
• Return automatic chromedriver version definition (#14108)
• Move agents skills to .agents/skills folder (#14081)
• Put in order background db migrations on the "transactions" table (#14077)
• Drop transactions_operator_fee_constant_index (#14066)
• Unescape ampersand in token's metadata (#14055)
• Treat blocks with huge amount of transactions as massive (#13994)
• Add OpenAPI docs for Scroll and Zilliqa endpoints (#13972)
• Add all-in-one open API spec file (#14050)

📘 Updated Swagger Documentation

• Swagger files for version 11.0.0:
  https://github.com/blockscout/swaggers/tree/master/blockscout/11.0.0

💡 New environment variables

⛔ Deprecated environment variables