This site requires Javascript to be enabled.

Serialization formats

Serialization is a key aspect of working with smart contracts in CosmWasm, enabling developers to inspect, debug, and parse messages sent on the blockchain. This process is streamlined, allowing interactions without the need for complex libraries or the hassle of downloading custom schemas and ABIs. CosmWasm supports multiple serialization formats, each with its own strengths and use cases.

JSON

JSON (JavaScript Object Notation) remains the most widely used serialization format in CosmWasm, favored for its simplicity and human readability. It’s commonly used in APIs across various platforms and is self-describing, making it easy to work with.

Advantages and considerations

  • Human-Readable: JSON is easy to read and write, making it an excellent choice for debugging and inspecting messages.
  • Widely Supported: JSON is universally supported across different programming languages and environments.
  • Auto-Generated Schemas: CosmWasm auto-generates JSON Schema descriptors for the public API of contracts. These schemas can be used to inspect the contract’s API, validate messages, and enhance client-side tooling.

Limitations

  • Handling Large Numbers: JSON struggles with numbers larger than 2^53. In such cases, it is recommended to represent these numbers as strings.
  • Binary Data Representation: JSON doesn’t inherently distinguish between regular strings and base64-encoded binary data, which can lead to confusion.
  • Lack of Strict Schema: Unlike binary formats, JSON does not enforce a strict schema, which means that while the format is flexible, it requires careful validation and handling.

Usage in CosmWasm

CosmWasm provides extensive support for JSON through cosmwasm::serde and cw-template, making it easy to serialize and deserialize data within smart contracts. Developers have the flexibility to define custom parsing logic for messages. This custom logic is not enforced by the framework, meaning developers can choose to implement alternative serialization formats as long as the client supports the custom format.

Protobuf

Protocol Buffers (Protobuf) is a binary serialization format known for its compactness and strict schema enforcement. Protobuf offers several advantages over JSON, particularly in environments where efficiency and data integrity are critical.

Advantages

  • Compact and Efficient: Protobuf messages are smaller and faster to encode/decode compared to JSON, making them ideal for scenarios where bandwidth and performance are concerns.
  • Strict Schema Enforcement: Protobuf enforces a strict schema, which helps to prevent data inconsistencies and ensures that messages are structured as expected.
  • Widespread Support: Protobuf is widely supported across different platforms, and with the Cosmos SDK v0.39.0 upgrade, it became fully integrated into the Cosmos ecosystem, including support for gRPC.

Usage in CosmWasm

Protobuf is particularly useful in CosmWasm for scenarios where a more compact and efficient format is needed, or where strict schema enforcement is required. It’s commonly used in more complex contracts that benefit from these features, especially when working with large data sets or in performance-critical applications.

Cap’n proto

Cap’n Proto is an emerging serialization format known for its ultra-lean encoding, which allows zero-copy reads and eliminates the need for parsing. This format offers unparalleled efficiency, especially in systems where performance is paramount.

Advantages

  • Zero-Copy Reads: Cap’n Proto allows for direct access to serialized data without the need for deserialization, resulting in significant performance gains.
  • No Parsing Required: Unlike JSON and Protobuf, Cap’n Proto does not require parsing, which reduces overhead and speeds up data processing.
  • Strict Schema with Efficiency: Cap’n Proto combines the benefits of a strict schema with the efficiency of binary formats, making it an attractive option for high-performance applications.

Usage in CosmWasm

While Cap’n Proto is not yet a standard in CosmWasm, it has been proposed as an optional serialization format. Developers who prioritize efficiency and need strict schema enforcement may opt-in to use Cap’n Proto for specific contracts. It’s particularly suited for encoding internal data structures, such as Params, where performance is critical.