{"id":5469,"library":"scalecodec","title":"Python SCALE Codec Library","description":"The `scalecodec` library is a Python implementation of the Substrate-specific Simple Concatenated Aggregate Little-Endian (SCALE) codec. It provides functionality for encoding and decoding data types used in Substrate-based blockchains, such as Polkadot and Kusama. The library is actively maintained, with frequent updates, and is currently at version 1.2.12, with a major version 2.0.0a (alpha) in development.","status":"active","version":"1.2.12","language":"en","source_language":"en","source_url":"https://github.com/polkascan/py-scale-codec","tags":["blockchain","substrate","polkadot","kusama","scale-codec","encoding","decoding"],"install":[{"cmd":"pip install scalecodec","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"symbol":"ScaleBytes","correct":"from scalecodec.base import ScaleBytes"},{"symbol":"RuntimeConfiguration","correct":"from scalecodec.type_registry import RuntimeConfiguration"},{"note":"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.","wrong":"runtime_config.create_scale_object(\"MetadataVersioned\") (for v2.0.0a+)","symbol":"MetadataVersioned","correct":"from scalecodec.metadata import MetadataVersioned"}],"quickstart":{"code":"from scalecodec.base import ScaleBytes\nfrom scalecodec.type_registry import RuntimeConfiguration\n\n# Initialize a runtime configuration (required for decoding types based on metadata)\n# For simple types, a basic config can be used.\n# For complex types, load a specific chain's metadata using load_type_registry()\nruntime_config = RuntimeConfiguration()\n\n# Example: Encode a Compact integer\ncompact_int_value = 100000000000000\ncompact_encoder = runtime_config.create_scale_object(\"Compact<u128>\")\nencoded_data = compact_encoder.encode(compact_int_value)\nprint(f\"Encoded {compact_int_value} (Compact<u128>): {encoded_data.to_hex()}\")\n\n# Example: Decode a Compact integer\nencoded_hex_value = \"0x0b00407a10f35a\" # The SCALE encoding for 100,000,000,000,000\ncompact_decoder = runtime_config.create_scale_object(\"Compact<u128>\")\ndecoded_value = compact_decoder.decode(ScaleBytes(encoded_hex_value))\nprint(f\"Decoded {encoded_hex_value} (Compact<u128>): {decoded_value}\")","lang":"python","description":"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`."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"2.0.0a and higher"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"<2.0.0a"},{"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)`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}