state_getRuntimeVersion - JSON-RPC Method

Description

Returns the runtime version information including spec name, spec version, implementation name and version, and available APIs. This JSON-RPC method is essential for ensuring compatibility when constructing transactions and interacting with the chain.

Parameters

Parameter	Type	Required	Description
blockHash	string	No	Block hash to query version at. If omitted, uses latest block

Returns

Field	Type	Description
specName	string	Name of the runtime specification
implName	string	Name of the implementation
authoringVersion	number	Version of the authorship interface
specVersion	number	Version of the runtime specification
implVersion	number	Version of the implementation
apis	array	List of supported runtime APIs with versions
transactionVersion	number	Version of the transaction format
stateVersion	number	Version of the state format

Request Example

{
  "jsonrpc": "2.0",
  "method": "state_getRuntimeVersion",
  "params": [],
  "id": 1
}

Response Example

{
  "jsonrpc": "2.0",
  "result": {
    "specName": "polkadot",
    "implName": "parity-polkadot",
    "authoringVersion": 0,
    "specVersion": 9430,
    "implVersion": 0,
    "apis": [
      ["0xdf6acb689907609b", 4],
      ["0x37e397fc7c91f5e4", 2],
      ["0x40fe3ad401f8959a", 6],
      ["0xd2bc9897eed08f15", 3],
      ["0xf78b278be53f454c", 2],
      ["0xab3c0572291feb8b", 1],
      ["0xbc9d89904f5b923f", 1],
      ["0x37c8bb1350a9a2a8", 4]
    ],
    "transactionVersion": 24,
    "stateVersion": 1
  },
  "id": 1
}

Code Examples

JavaScript

const getRuntimeVersion = async (blockHash = null) => {
  const params = blockHash ? [blockHash] : [];
  
  const response = await fetch('https://api-polkadot.n.dwellir.com', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      jsonrpc: '2.0',
      method: 'state_getRuntimeVersion',
      params: params,
      id: 1
    })
  });
  
  const data = await response.json();
  return data.result;
};

// Check runtime version
const version = await getRuntimeVersion();
console.log(`Runtime: ${version.specName} v${version.specVersion}`);
console.log(`Transaction version: ${version.transactionVersion}`);

// Check for runtime upgrades
const checkForUpgrade = async () => {
  const current = await getRuntimeVersion();
  const previous = localStorage.getItem('lastRuntimeVersion');
  
  if (previous && JSON.parse(previous).specVersion < current.specVersion) {
    console.log('Runtime upgraded!');
    // Update transaction construction logic
  }
  
  localStorage.setItem('lastRuntimeVersion', JSON.stringify(current));
};

Python

import requests
import json

def get_runtime_version(block_hash=None):
    url = "https://api-polkadot.n.dwellir.com"
    headers = {
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    }
    
    params = [block_hash] if block_hash else []
    
    payload = {
        "jsonrpc": "2.0",
        "method": "state_getRuntimeVersion",
        "params": params,
        "id": 1
    }
    
    response = requests.post(url, headers=headers, data=json.dumps(payload))
    data = response.json()
    
    if "error" in data:
        raise Exception(f"RPC Error: {data['error']}")
    
    return data["result"]

# Get current runtime version
version = get_runtime_version()
print(f"Chain: {version['specName']}")
print(f"Spec Version: {version['specVersion']}")
print(f"Transaction Version: {version['transactionVersion']}")

# Check supported APIs
for api_id, api_version in version['apis']:
    print(f"API {api_id}: version {api_version}")

TypeScript (@polkadot/api)

import { ApiPromise, WsProvider } from '@polkadot/api';

async function checkRuntimeVersion() {
  const provider = new WsProvider('wss://api-polkadot.n.dwellir.com');
  const api = await ApiPromise.create({ provider });
  
  // Get runtime version
  const version = await api.rpc.state.getRuntimeVersion();
  
  console.log('Runtime Info:', {
    chain: version.specName.toString(),
    specVersion: version.specVersion.toNumber(),
    implVersion: version.implVersion.toNumber(),
    transactionVersion: version.transactionVersion.toNumber()
  });
  
  // Check specific APIs
  const hasStaking = version.apis.some(
    ([id]) => id.toHex() === '0xdf6acb689907609b'
  );
  console.log('Staking API available:', hasStaking);
  
  // Monitor for upgrades
  api.rpc.state.subscribeRuntimeVersion((version) => {
    console.log(`Runtime updated to spec version: ${version.specVersion}`);
  });
  
  await api.disconnect();
}

Runtime APIs

Common runtime API identifiers:

API ID	Description
0xdf6acb689907609b	Core runtime API
0x37e397fc7c91f5e4	Metadata API
0x40fe3ad401f8959a	Block builder API
0xd2bc9897eed08f15	Transaction payment API
0xf78b278be53f454c	Session keys API
0xab3c0572291feb8b	Account nonce API

Version Compatibility

Important Version Fields

1. specVersion: Changes indicate runtime logic updates
2. transactionVersion: Changes require transaction format updates
3. implVersion: Implementation-specific changes

Handling Upgrades

class RuntimeVersionManager {
  constructor(api) {
    this.api = api;
    this.currentVersion = null;
  }
  
  async initialize() {
    this.currentVersion = await this.api.rpc.state.getRuntimeVersion();
    this.subscribeToUpdates();
  }
  
  subscribeToUpdates() {
    this.api.rpc.state.subscribeRuntimeVersion((version) => {
      if (this.currentVersion.specVersion.lt(version.specVersion)) {
        console.log('Runtime upgrade detected');
        this.handleUpgrade(version);
      }
      this.currentVersion = version;
    });
  }
  
  handleUpgrade(newVersion) {
    // Refresh metadata
    // Update transaction construction
    // Notify users
    console.log(`Upgraded to spec version ${newVersion.specVersion}`);
  }
}

Use Cases

1. Transaction Construction: Ensure correct format version
2. API Compatibility: Check available runtime APIs
3. Upgrade Detection: Monitor for runtime upgrades
4. Version Management: Maintain compatibility across versions
5. Feature Detection: Check if specific APIs are available

Notes

• Runtime upgrades don't require node restarts
• Transaction version changes may break transaction construction
• Always check version before constructing transactions
• Cache version info to reduce RPC calls
• Subscribe to version updates for real-time monitoring

Related Methods

• state_getMetadata - Get full runtime metadata
• chain_getBlock - Check block for runtime upgrades
• system_chain - Get chain name
• rpc_methods - List available methods