Python SCALE Codec Library

Warnings

• breaking Version 2.0.0a (alpha) introduces a 'new from the ground up object based implementation' which fundamentally changes how types are handled and instantiated. This is a significant breaking change from v1.x's string-based type parsing.
  Fix: Review the v2.x documentation and migration guides once stable. Code relying on `runtime_config.create_scale_object("TypeName")` will need to be refactored to use direct object instantiation like `TypeName.new()` or similar patterns for v2.x.
• gotcha The SCALE codec is not self-describing; it requires prior knowledge of the data's type definition for correct decoding. Attempting to decode data without the correct type context (e.g., from blockchain metadata) will lead to incorrect or failed decoding.
  Fix: Always ensure your `RuntimeConfiguration` is initialized with the correct type registry or chain metadata for the specific data you are trying to decode. For Substrate chains, this typically involves loading the chain's `MetadataVersioned`.
• gotcha When decoding a byte array, the `decode()` method by default expects the entire byte stream to be consumed. If you are decoding a partial stream or a byte array with trailing data, this will raise an error.
  Fix: Pass `check_remaining=False` to the `decode()` method if you expect valid trailing bytes after the intended object has been decoded. For example: `decoder.decode(scale_bytes, check_remaining=False)`.
• gotcha For composite types (structures), the SCALE codec ignores field names; only the order of fields matters for encoding and decoding. Re-encoding data that was decoded with an assumed order into a different field order will result in a different (and likely incorrect) byte array.
  Fix: Maintain a consistent and correct ordering of fields for composite types according to the source (e.g., blockchain runtime metadata) to ensure predictable encoding and decoding behavior.

Install

• pip install scalecodec Install stable version

Imports

• ScaleBytes

  from scalecodec.base import ScaleBytes

• RuntimeConfiguration

  from scalecodec.type_registry import RuntimeConfiguration

• MetadataVersioned

  from scalecodec.metadata import MetadataVersioned

  For `scalecodec` v2.x (alpha and future stable releases), `MetadataVersioned` is directly imported and instantiated as an object, replacing the `create_scale_object` method used in v1.x.

Quickstart

This quickstart demonstrates encoding and decoding a 'Compact' integer, a common SCALE type for large numbers. It shows the typical pattern of initializing a `RuntimeConfiguration` and using `create_scale_object` for type-specific encoding/decoding in `scalecodec` v1.x. For complex types, you would load a chain's metadata into the `RuntimeConfiguration`.

from scalecodec.base import ScaleBytes
from scalecodec.type_registry import RuntimeConfiguration

# Initialize a runtime configuration (required for decoding types based on metadata)
# For simple types, a basic config can be used.
# For complex types, load a specific chain's metadata using load_type_registry()
runtime_config = RuntimeConfiguration()

# Example: Encode a Compact integer
compact_int_value = 100000000000000
compact_encoder = runtime_config.create_scale_object("Compact<u128>")
encoded_data = compact_encoder.encode(compact_int_value)
print(f"Encoded {compact_int_value} (Compact<u128>): {encoded_data.to_hex()}")

# Example: Decode a Compact integer
encoded_hex_value = "0x0b00407a10f35a" # The SCALE encoding for 100,000,000,000,000
compact_decoder = runtime_config.create_scale_object("Compact<u128>")
decoded_value = compact_decoder.decode(ScaleBytes(encoded_hex_value))
print(f"Decoded {encoded_hex_value} (Compact<u128>): {decoded_value}")