Serde Molecule

https://github.com/xujiandong/serde_molecule
Admin
An implementation of the Molecule serialization format for CKB using the Serde framework in Rust,...
Tokens:2,780
Snippets:18
Trust Score:8.3
License:MIT
Update:1 year ago
Show doc for...
Tokens:
Raw
### Configuring Cargo.toml for no_std Support

Source: https://github.com/xujiandong/serde_molecule/blob/main/README.md

This TOML snippet provides the necessary `Cargo.toml` configuration to enable `serde_molecule` and `serde` for `no_std` environments. It demonstrates how to disable default features and enable specific features like `alloc` for `serde_molecule` and `derive` for `serde`.

```TOML
serde_molecule = { version = "x.x.x", default-features = false, features = ["alloc"] }
serde = { version = "x.x.x", default-features = false, features = ["derive"] }
```

--------------------------------

### Rust to Molecule Type Mapping Reference

Source: https://github.com/xujiandong/serde_molecule/blob/main/serde_molecule/README.md

Provides a comprehensive mapping between Rust data types and their corresponding Molecule serialization types. Includes whether the Molecule type has a fixed size, serving as a reference for `serde_molecule` translations.

```APIDOC
| Rust Type | Molecule Type | Fixed Size |
| --------- | ------------- | ---------- |
| i8,u8     | byte          | yes |
| i16, u16, i32, u32, i64, u64, i128, u128 | array | yes |
| f32       | array([byte; 4]) | yes |
| f64       | array([byte; 8]) | yes |
| [u8; N]   | array([byte; N]) | yes |
| [T; N]    | array([T; N]) | yes |
| Vec<T>    | fixvec | no |
| struct     | table | no |
| #[serde(with = "struct_serde")] | struct | yes |
| #[serde(with = "dynvec_serde")] | dynvec | no |
| Option<T>  | option | no |
| enum       | union | no |
| String     | fixvec | no |
| BTreeMap   | dynvec | no |
| HashMap    | dynvec | no |
| BinaryHeap | fixvec | no |
| LinkedList | fixvec | no |
| VecDeque   | fixvec | no |
| HashSet    | fixvec | no |
| Tuple Struct|table  | no |
| Tuple Variant|table | no |
| Struct Variant|table| no |
| Tuple     | not supported | N/A|
```

--------------------------------

### Rust to Molecule Type Mapping Reference

Source: https://github.com/xujiandong/serde_molecule/blob/main/README.md

This table provides a comprehensive mapping between common Rust data types and their corresponding Molecule serialization types, indicating whether they are fixed-size. It serves as a reference for understanding how Rust data structures are represented in the Molecule format.

```APIDOC
| Rust Type | Molecule Type | Fixed Size |
| --------- | ------------- | ---------- |
| i8,u8     | byte          | yes |
| i16, u16, i32, u32, i64, u64, i128, u128 | array | yes |
| f32       | array([byte; 4]) | yes |
| f64       | array([byte; 8]) | yes |
| [u8; N]   | array([byte; N]) | yes |
| [T; N]    | array([T; N]) | yes |
| Vec<T>    | fixvec | no |
| struct     | table | no |
| #[serde(with = "struct_serde")] | struct | yes |
| #[serde(with = "dynvec_serde")] | dynvec | no |
| Option<T>  | option | no |
| enum       | union | no |
| String     | fixvec | no |
| BTreeMap   | dynvec | no |
| HashMap    | dynvec | no |
| BinaryHeap | fixvec | no |
| LinkedList | fixvec | no |
| VecDeque   | fixvec | no |
| HashSet    | fixvec | no |
| Tuple Struct|table  | no |
| Tuple Variant|table | no |
| Struct Variant|table| no |
| Tuple     | not supported | N/A|
```

--------------------------------

### Basic Serialization/Deserialization with serde_molecule in Rust

Source: https://github.com/xujiandong/serde_molecule/blob/main/serde_molecule/README.md

Demonstrates fundamental `serde_molecule` usage for custom structs. Shows deriving `Serialize`/`Deserialize`, then using `to_vec` for serialization and `from_slice` for deserialization, asserting data integrity.

```rust
use serde::{Serialize, Deserialize};
use serde_molecule::{to_vec, from_slice};

#[derive(Serialize, Deserialize)]
pub struct Table1 {
    pub f1: u8,
    pub f2: u16,
}

let t1 = Table1{f1: 0, f2: 0};
// serialize
let bytes = to_vec(&t1, false).unwrap();
// deserialize
let t2: Table1 = from_slice(&bytes, false).unwrap();
assert_eq!(t1.f1, t2.f1);
```

--------------------------------

### Adding Serde Molecule Dependencies to Cargo.toml

Source: https://github.com/xujiandong/serde_molecule/blob/main/README.md

This TOML snippet illustrates how to add `serde` and `serde_molecule` as dependencies in a Rust project's `Cargo.toml` file, enabling the use of the serialization framework and the Molecule implementation.

```TOML
serde = { version = "???", features = ["derive"] }
serde_molecule = { version = "???" }
```

--------------------------------

### Basic Serialization and Deserialization with Serde Molecule

Source: https://github.com/xujiandong/serde_molecule/blob/main/README.md

This snippet demonstrates the fundamental usage of `serde_molecule` for serializing and deserializing a custom Rust struct. It shows how to derive `Serialize` and `Deserialize` traits and use `to_vec` and `from_slice` functions for data conversion.

```Rust
use serde::{Serialize, Deserialize};
use serde_molecule::{to_vec, from_slice};

#[derive(Serialize, Deserialize)]
pub struct Table1 {
    pub f1: u8,
    pub f2: u16,
}

let t1 = Table1{f1: 0, f2: 0};
// serialize
let bytes = to_vec(&t1, false).unwrap();
// deserialize
let t2: Table1 = from_slice(&bytes, false).unwrap();
assert_eq!(t1.f1, t2.f1);
```

--------------------------------

### Configuring Cargo.toml for no_std Support in serde_molecule

Source: https://github.com/xujiandong/serde_molecule/blob/main/serde_molecule/README.md

Shows `Cargo.toml` configuration for `no_std` support in `serde_molecule` and `serde`. Involves disabling default features and enabling `alloc` for `serde_molecule` and `derive` for `serde`.

```toml
serde_molecule = { version = "x.x.x", default-features = false, features = ["alloc"] }
serde = { version = "x.x.x", default-features = false, features = ["derive"] }
```

--------------------------------

### Adding serde_molecule and Serde Dependencies to Cargo.toml

Source: https://github.com/xujiandong/serde_molecule/blob/main/serde_molecule/README.md

Illustrates declaring `serde` and `serde_molecule` as dependencies in `Cargo.toml`. Specifies enabling the `derive` feature for `serde`, essential for automatic trait implementation.

```toml
serde = { version = "???", features = ["derive"] }
serde_molecule = { version = "???" }
```

--------------------------------

### Using Structs Instead of Tuples for Serde Molecule Serialization in Rust

Source: https://github.com/xujiandong/serde_molecule/blob/main/README.md

This Rust code snippet demonstrates the recommended approach of using a `struct` instead of a general tuple for data serialization with `serde_molecule`. Due to Serde's internal implementation, general tuples have limited support, while tuple structs and tuple variants are mapped to Molecule tables. Using a struct ensures proper serialization behavior.

```rust
use serde::{Deserialize, Serialize};

// Instead of this:
// type MyTuple = (u8, String);

// Use this:
#[derive(Serialize, Deserialize)]
struct MyStruct {
    field1: u8,
    field2: String,
}
```

--------------------------------

### Molecule Schema for Map Types

Source: https://github.com/xujiandong/serde_molecule/blob/main/README.md

This snippet defines the Molecule schema for representing Rust map types like `BTreeMap` and `HashMap`. It shows how maps are structured as a `vector` of `MapEntry` tables, each containing a `key` and `value`, though `HashMap` is not recommended due to arbitrary order.

```APIDOC
table MapEntry {
    key: KEY_TYPE,
    value: VALUE_TYPE,
}

vector Map <MapEntry>;
```

--------------------------------

### Replace Rust Tuples with Structs for Serde Molecule

Source: https://github.com/xujiandong/serde_molecule/blob/main/serde_molecule/README.md

Demonstrates how to replace a Rust tuple type with a struct when using `serde_molecule` for serialization and deserialization. This approach is recommended due to Serde's limited support for general tuples, ensuring better compatibility and avoiding potential issues.

```rust
use serde::{Deserialize, Serialize};

// Instead of this:
// type MyTuple = (u8, String);

// Use this:
#[derive(Serialize, Deserialize)]
struct MyStruct {
    field1: u8,
    field2: String,
}
```

--------------------------------

### Serializing Dynamic-Sized Vectors with dynvec_serde

Source: https://github.com/xujiandong/serde_molecule/blob/main/README.md

This Rust snippet demonstrates how to use the `#[serde(with = "dynvec_serde")]` attribute to correctly serialize `Vec`-like containers whose elements are not of a fixed size into Molecule's `dynvec` type. This is crucial for handling variable-length data structures.

```Rust
use serde_molecule::dynvec_serde;
#[derive(Serialize, Deserialize)]
struct RawTransaction {
    // ...
    #[serde(with = "dynvec_serde")]
    pub outputs: Vec<CellOutput>,
}
```

--------------------------------

### Serializing Dynamic Vectors with dynvec_serde in Rust

Source: https://github.com/xujiandong/serde_molecule/blob/main/serde_molecule/README.md

Demonstrates using `#[serde(with = "dynvec_serde")]` for `Vec`-like containers with non-fixed-size elements. This annotation ensures correct serialization as `dynvec`, overriding the default `fixvec` behavior.

```rust
use serde_molecule::dynvec_serde;
#[derive(Serialize, Deserialize)]
struct RawTransaction {
    // ...
    #[serde(with = "dynvec_serde")]
    pub outputs: Vec<CellOutput>,
}
```

--------------------------------

### Serializing Fixed-Size Structs with struct_serde

Source: https://github.com/xujiandong/serde_molecule/blob/main/README.md

This Rust snippet illustrates the use of the `#[serde(with = "struct_serde")]` attribute to explicitly mark a field as a Molecule `struct`. This is necessary when a field represents a fixed-size Molecule struct rather than the default `table` type, ensuring correct serialization behavior.

```Rust
use serde_molecule::struct_serde;

#[derive(Serialize, Deserialize)]
pub struct CellInput {
    pub since: u64,
    #[serde(with = "struct_serde")]
    pub previous_output: OutPoint,
}
```

--------------------------------

### Serializing Molecule Structs with struct_serde in Rust

Source: https://github.com/xujiandong/serde_molecule/blob/main/serde_molecule/README.md

Illustrates `#[serde(with = "struct_serde")]` to explicitly mark a field as a Molecule `struct`. This is crucial for correct serialization when a field corresponds to a fixed-size Molecule struct, as fields default to `table`s.

```rust
use serde_molecule::struct_serde;

#[derive(Serialize, Deserialize)]
pub struct CellInput {
    pub since: u64,
    #[serde(with = "struct_serde")]
    pub previous_output: OutPoint,
}
```

--------------------------------

### Handling Large Arrays with big_array_serde

Source: https://github.com/xujiandong/serde_molecule/blob/main/README.md

This Rust snippet shows how to use the `#[serde(with = "big_array_serde")]` attribute to serialize Rust arrays larger than 32 elements, overcoming a limitation in the standard Serde framework. This enables proper serialization of large fixed-size byte arrays into Molecule.

```Rust
use serde::{Deserialize, Serialize};
use serde_molecule::big_array_serde;

#[derive(Serialize, Deserialize)]
struct BigArray {
    f1: u8,
    #[serde(with = "big_array_serde")]
    f2: [u8; 33],
    #[serde(with = "big_array_serde")]
    f3: [u8; 64],
}
```

--------------------------------

### Molecule Schema for Rust Map Types

Source: https://github.com/xujiandong/serde_molecule/blob/main/serde_molecule/README.md

Defines the Molecule schema for serializing Rust map types like `BTreeMap` and `HashMap`. Maps are represented as a `vector` of `MapEntry` tables, each containing `key` and `value` fields.

```APIDOC
table MapEntry {
    key: KEY_TYPE,
    value: VALUE_TYPE,
}

vector Map <MapEntry>;
```

--------------------------------

### Handling Large Arrays with big_array_serde in Rust

Source: https://github.com/xujiandong/serde_molecule/blob/main/serde_molecule/README.md

Demonstrates `#[serde(with = "big_array_serde")]` for serializing arrays larger than 32 elements. This annotation addresses a standard Serde limitation, enabling `serde_molecule` to correctly handle large fixed-size arrays.

```rust
use serde::{Deserialize, Serialize};
use serde_molecule::big_array_serde;

#[derive(Serialize, Deserialize)]
struct BigArray {
    f1: u8,
    #[serde(with = "big_array_serde")]
    f2: [u8; 33],
    #[serde(with = "big_array_serde")]
    f3: [u8; 64],
}
```
Tokens:
Raw