Skip to main content

state_getMetadata

Description#

Retrieves the complete runtime metadata for the Acala blockchain in SCALE-encoded format. Runtime metadata is the comprehensive schema that describes all pallets, storage items, extrinsics, events, errors, and constants available in the chain's runtime. This metadata is essential for any client application interacting with the blockchain, as it provides the type information necessary to properly encode transactions, decode storage values, parse events, and understand the chain's capabilities. The metadata format evolves through versions (V14, V15, etc.), with newer versions providing enhanced type information and features. Client libraries like Polkadot.js API and SubXT use this metadata to provide type-safe interfaces to the blockchain.

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_getMetadata","params":[]}'

Parameters#

This method accepts an optional block hash parameter. When omitted, returns metadata for the latest block state. Historical metadata can be retrieved by providing a specific block hash, though metadata typically only changes during runtime upgrades.

Response Format#

Returns a hexadecimal string containing SCALE-encoded metadata. The raw response is not human-readable and must be decoded using Substrate metadata decoding libraries. The decoded metadata contains structured information about all runtime components, organized by pallets with their associated types, calls, events, and storage layouts.

Metadata Contents#

The metadata provides complete runtime information including:

  • Pallets: All installed pallets (System, Balances, DeFi modules, etc.)
  • Storage Items: Every storage value, map, and double map with their key and value types
  • Extrinsics: All callable functions with parameter types and documentation
  • Events: All event types that can be emitted by the runtime
  • Errors: All possible runtime errors with their meanings
  • Constants: Runtime constants like existential deposit, block time, etc.
  • Type Registry: Complete type definitions for encoding and decoding all data structures

Use Cases#

  • Client Initialization: Initialize Substrate client libraries with proper type information
  • Transaction Construction: Understand available extrinsics and their parameter requirements
  • Event Parsing: Decode event logs from blocks with correct type interpretation
  • Storage Queries: Determine storage key structures for accessing chain state
  • Documentation Generation: Automatically generate API documentation from metadata
  • Type Safety: Provide compile-time or runtime type checking for blockchain interactions

Best Practices#

Cache metadata locally to avoid repeated fetching, as it's large (often several MB encoded) and rarely changes. Monitor state_getRuntimeVersion to detect runtime upgrades that invalidate cached metadata. When an upgrade occurs, fetch fresh metadata and reinitialize your client's type registry. Most Substrate client libraries handle metadata caching and refresh automatically. For archive queries at historical blocks, ensure you use the metadata from that runtime version, not the current version.

Metadata Versioning#

Metadata has evolved through multiple versions (V14 introduced significant improvements, V15 added additional features). Modern chains typically use V14 or later. Client libraries should support multiple metadata versions for compatibility with different chains and historical blocks. The metadata itself includes version information in its encoded format.

Performance Considerations#

Metadata responses are large and take time to transfer and decode. Expect initial metadata fetch to be one of the slowest operations in client initialization. However, since metadata rarely changes, the caching benefit far outweighs this one-time cost. Consider compressing cached metadata if storing on disk.