Docs

system_version - Asset Hub RPC Method

Get the node implementation version on Asset Hub. Essential for compatibility checking, runtime upgrades, and monitoring node deployments across the Polkadot's system parachain managing $4.5B+ in DOT tokens, native USDC/USDT, and NFTs network.

Returns the node implementation version string on Asset Hub. This version reflects the client software version (e.g., 0.9.43-ba6af1743a0), not the on-chain runtime version.

Why Asset Hub? Build on Polkadot's system parachain managing $4.5B+ in DOT tokens, native USDC/USDT, and NFTs with 50-90% lower fees than Relay Chain, fee payment in any supported asset, 1.5M+ accounts migrated, and trustless Ethereum bridge access.

When to Use This Method

system_version is essential for asset issuers, stablecoin integrators, and teams requiring low-cost token management on Polkadot:

  • Compatibility Checking -- Verify the node client version supports the features your application requires on Asset Hub
  • Upgrade Monitoring -- Track node software versions across your validator or collator fleet after runtime upgrades
  • Diagnostics and Debugging -- Include version information in bug reports and support requests for native stablecoin transfers (USDC, USDT), DOT staking and governance, and cross-chain asset management via XCM
  • Multi-Node Management -- Ensure all nodes in your infrastructure are running consistent versions

Best Practices

  • Check the runtime version before using version-specific Substrate APIs
  • Track version changes during runtime upgrades to detect compatibility issues
  • Use with system_chain and system_properties for full network context
  • Different nodes on the same network should return the same version (unless upgrading)

Code Examples

Common Use Cases

1. Node Fleet Version Monitoring

Track version consistency across multiple Asset Hub nodes:

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

async function checkFleetVersions(endpoints) {
  const versions = await Promise.all(
    endpoints.map(async (endpoint) => {
      const provider = new WsProvider(endpoint);
      const api = await ApiPromise.create({ provider });
      const version = await api.rpc.system.version();
      const name = await api.rpc.system.name();
      await api.disconnect();
      return { endpoint, version: version.toString(), name: name.toString() };
    })
  );

  const unique = new Set(versions.map((v) => v.version));
  if (unique.size > 1) {
    console.warn('Version mismatch detected across fleet!');
  }

  versions.forEach((v) => {
    console.log(`${v.endpoint}: ${v.name} v${v.version}`);
  });
}

2. Pre-Upgrade Compatibility Check

Verify node version before executing operations:

JavaScript
async function ensureMinVersion(api, minVersion) {
  const version = await api.rpc.system.version();
  const versionStr = version.toString();
  const [major, minor, patch] = versionStr.split('-')[0].split('.').map(Number);
  const [minMajor, minMinor, minPatch] = minVersion.split('.').map(Number);

  if (
    major < minMajor ||
    (major === minMajor && minor < minMinor) ||
    (major === minMajor && minor === minMinor && patch < minPatch)
  ) {
    throw new Error(
      `Node version ${versionStr} is below minimum ${minVersion}`
    );
  }

  console.log(`Node version ${versionStr} meets minimum ${minVersion}`);
  return true;
}

3. Node Identity Dashboard

Gather full node identity information:

JavaScript
async function getNodeIdentity(api) {
  const [version, name, chain, properties] = await Promise.all([
    api.rpc.system.version(),
    api.rpc.system.name(),
    api.rpc.system.chain(),
    api.rpc.system.properties()
  ]);

  return {
    client: name.toString(),
    version: version.toString(),
    chain: chain.toString(),
    tokenSymbol: properties.tokenSymbol.toString(),
    ss58Format: properties.ss58Format.toString()
  };
}

Error Handling

Common errors and solutions:

Error CodeDescriptionSolution
-32603Internal errorNode may be starting up -- retry after delay
-32005Rate limit exceededReduce request frequency or implement client-side rate limiting
Connection refusedNode unreachableVerify the RPC endpoint URL and that the node is running