Skip to main content

system_version - JSON-RPC Method

Description#

Returns the node software implementation version string, identifying the specific release of the client software running on the connected node. This version string typically includes the node implementation name (such as "Acala Node"), version number, and sometimes build metadata. Unlike state_getRuntimeVersion which reports the blockchain runtime's version, this method reports the node software version - the actual executable binary that's communicating with peers, producing/validating blocks, and serving RPC requests. The node version can differ from the runtime version and is useful for debugging connectivity issues, identifying node implementation bugs, or verifying that infrastructure is running expected software releases.

Request Example#

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

Request Example (HTTP)#

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

Parameters#

This method takes no parameters and immediately returns the node version string.

Response Format#

Returns a simple string containing the node version information. The format varies by implementation but typically follows semantic versioning patterns like "Acala Node v2.14.0-abc123" where the components indicate major.minor.patch version numbers and potentially git commit hashes or build identifiers.

Node vs Runtime Version#

It's crucial to understand the distinction: the node version (system_version) represents the software executable, while the runtime version (state_getRuntimeVersion) represents the on-chain Wasm runtime that defines blockchain logic. Nodes can be upgraded independently of runtime upgrades. A node upgrade might improve performance, fix networking bugs, or add RPC features without changing blockchain behavior. Conversely, runtime upgrades change blockchain logic without requiring node software updates.

Use Cases#

  • Infrastructure Monitoring: Track which node versions are deployed across your infrastructure
  • Debugging: Identify whether issues stem from node software bugs in specific versions
  • Compatibility Testing: Verify node version compatibility with your application requirements
  • Security Audits: Ensure production nodes run versions without known security vulnerabilities
  • Support Requests: Include node version information when reporting issues to node maintainers
  • Performance Analysis: Correlate performance metrics with specific node releases

Best Practices#

Log the node version during application initialization for debugging purposes. When connecting to public RPC endpoints, be aware that the node version may change without notice as providers upgrade their infrastructure. For critical production applications running your own nodes, establish a testing and upgrade process for new node releases. Monitor node release notes for security patches or critical bug fixes that require immediate deployment.

Version Compatibility#

Most node versions maintain backward compatibility with a range of runtime versions, but extreme mismatches can cause issues. If you encounter unexpected errors or behavior, verify both the node version and runtime version are reasonably current. Substrate-based chains typically maintain node compatibility across several runtime upgrades, but deprecated features may eventually be removed from node software.

Monitoring and Alerting#

For production infrastructure, track node versions across your fleet and set up alerts when nodes run outdated versions. This helps identify stale deployments that may miss important security patches or performance improvements. Consider automating node version checks as part of your deployment pipelines.