Skip to main content

state_getRuntimeVersion

Description#

Retrieves comprehensive version information about the Acala runtime, including specification version, implementation version, transaction version, and other critical versioning metadata. This information is essential for client applications to determine runtime compatibility, detect runtime upgrades, and maintain correct type registries. The specVersion increments with every runtime upgrade that changes the runtime's behavior or interface, while transactionVersion tracks changes affecting transaction encoding. Monitoring these version numbers allows applications to automatically invalidate cached metadata and refresh their understanding of the chain's capabilities after upgrades.

Request Example#

curl -s https://api-acala.n.dwellir.com/YOUR_API_KEY \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"state_getRuntimeVersion","params":[]}'

Parameters#

This method accepts an optional block hash parameter to query the runtime version at a specific historical block. When omitted, returns the version for the latest block state.

Response Example (Oct 9, 2025)#

{
  "specName": "acala",
  "implName": "acala",
  "authoringVersion": 1,
  "specVersion": 2300,
  "implVersion": 0,
  "transactionVersion": 3
}

Response Fields#

FieldTypeDescription
specNamestringRuntime specification identifier, typically the chain name
implNamestringRuntime implementation name (node software)
authoringVersionnumberBlock authoring version for validator compatibility
specVersionnumberRuntime specification version - increments with any runtime change
implVersionnumberImplementation version for node software releases
transactionVersionnumberTransaction format version - increments when encoding changes

Version Significance#

The specVersion is the most critical field for monitoring runtime upgrades. Any change to this number indicates a runtime upgrade has occurred, requiring metadata refresh and potential client logic updates. The transactionVersion changes less frequently and only when transaction encoding formats are modified, indicating that old transaction formats may no longer be valid.

Use Cases#

  • Upgrade Detection: Poll periodically to detect runtime upgrades and trigger metadata refresh
  • Compatibility Checking: Verify client expectations match the chain's runtime version
  • Transaction Encoding: Ensure transaction format matches the current transaction version
  • Historical Analysis: Determine which runtime version was active at historical blocks
  • Client Initialization: Validate compatibility during application startup
  • Monitoring Systems: Alert operators when runtime upgrades occur on production chains

Best Practices#

Poll this method regularly (every few blocks or minutes) to detect runtime upgrades promptly. When specVersion changes, immediately fetch fresh metadata using state_getMetadata and reinitialize your type registry. Store the version information alongside cached metadata to ensure cache validity. For applications processing historical data, always use the runtime version from the target block's era to ensure correct interpretation.

Runtime Upgrade Handling#

When a runtime upgrade is detected (changed specVersion), follow this sequence: fetch new metadata, decode it to update type definitions, clear any cached chain state that may have changed format, and reinitialize client libraries with the new types. Most Substrate client libraries provide automatic upgrade handling when properly configured.

Monitoring Pattern#

Implement a background task that checks state_getRuntimeVersion every 30-60 seconds. Compare against the last known version. On mismatch, trigger the upgrade handling workflow. This proactive approach prevents transaction failures or decoding errors that would occur if upgrades went undetected.