Molecule

https://github.com/nervosnetwork/molecule
Admin
Molecule is a minimalist and canonicalization serialization system, primarily used for CKB scripts...
Tokens:2,755
Snippets:29
Trust Score:7.9
License:MIT
Update:1 year ago
Show doc for...
Tokens:
Raw
### Installing Molecule Schema Compiler (Shell)

Source: https://github.com/nervosnetwork/molecule/blob/master/README.md

Installs the official Molecule schema compiler and code generator (`moleculec`) using the Cargo package manager, ensuring locked dependencies are used.

```Shell
cargo install moleculec --locked
```

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

### Start Fuzzer with Make (Shell)

Source: https://github.com/nervosnetwork/molecule/blob/master/fuzzing/c/README.md

Executes the 'start-fuzzer' target in the Makefile to run the project's fuzzer. This command initiates the fuzzing process as configured in the Makefile.

```Shell
make start-fuzzer
```

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

### Getting Help for Molecule Compiler (Shell)

Source: https://github.com/nervosnetwork/molecule/blob/master/README.md

Displays the help message and usage information for the `moleculec` command-line tool.

```Shell
moleculec --help
```

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

### Example Molecule Schema for Compatibility (mol)

Source: https://github.com/nervosnetwork/molecule/blob/master/docs/molecule_api.md

This Molecule schema example demonstrates how compatible reading works. An older schema (`Old`) can read data generated by a newer schema (`New`) that has added fields, but not removed ones. The `from_compatible_slice` API is used for this purpose.

```mol
vector Inner <byte>;

table Old {
    a: Inner,
    b: Inner,
}

table New {
    a: Inner,
    b: Inner,
    c: Inner,
}
```

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

### Defining Line Comments in Molecule

Source: https://github.com/nervosnetwork/molecule/blob/master/docs/schema_language.md

Demonstrates the syntax for single-line comments in the Molecule Schema Language, starting with `//`.

```molecule
// This is a line comment
```

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

### Run Fuzz Tests with Cargo Fuzz (shell)

Source: https://github.com/nervosnetwork/molecule/blob/master/fuzzing/rust/README.md

Executes the specified fuzz test using the `cargo fuzz` tool. This command starts the fuzzing process for the target named 'data'.

```shell
cargo fuzz run data
```

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

### Serialize BytesVec [0x1234] - Hex Bytes

Source: https://github.com/nervosnetwork/molecule/blob/master/docs/encoding_spec.md

Example serialization of a Molecule vector `BytesVec` containing a single `Bytes` item `0x1234`. Shows the full size, offset, and item data.

```Hex Bytes
# the full size is 14 bytes
0e 00 00 00
# one offset
08 00 00 00
# one item
02 00 00 00 12 34
```

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

### Serialize MixedType Table - Hex Bytes

Source: https://github.com/nervosnetwork/molecule/blob/master/docs/encoding_spec.md

Example serialization of a Molecule table `MixedType` with fields of different types (`Bytes`, `byte`, `Uint32`, `Byte3`). Shows the full size, offsets for each field, and the serialized data for each field.

```Hex Bytes
# the full size is 43 (0x2b) bytes
2b 00 00 00
# five offsets (20 bytes in total)
18 00 00 00, 1c 00 00 00, 1d 00 00 00, 21 00 00 00, 24 00 00 00
# five items (19 bytes in total)
00 00 00 00
ab
23 01 00 00
45 67 89
03 00 00 00, ab cd ef
```

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

### Serialize BytesVec Multiple Items - Hex Bytes

Source: https://github.com/nervosnetwork/molecule/blob/master/docs/encoding_spec.md

Example serialization of a Molecule vector `BytesVec` containing multiple `Bytes` items of varying lengths. Shows the full size, offsets for each item, and the serialized data for each item.

```Hex Bytes
# the full size is 52 (0x34) bytes
34 00 00 00
# five offsets (20 bytes in total)
18 00 00 00, 1e 00 00 00, 22 00 00 00, 28 00 00 00, 2d 00 00 00
# five items (28 bytes in total)
02 00 00 00, 12 34
00 00 00 00,
02 00 00 00, 05 67
01 00 00 00, 89
03 00 00 00, ab cd ef
```

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

### Serialize BytesVecOpt Some([0x]) - Hex Bytes

Source: https://github.com/nervosnetwork/molecule/blob/master/docs/encoding_spec.md

Example serialization of a Molecule option type `BytesVecOpt` containing `Some` with a `BytesVec` that has a single empty `Bytes` item (`[0x]`). Shows the serialized bytes of the inner `BytesVec`.

```Hex Bytes
# the full size of BytesVec is 12 bytes
0c 00 00 00
# the offset of Bytes
08 00 00 00
# the length of Bytes
00 00 00 00
```

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

### Serialize HybridBytes Union (BytesVec) - Hex Bytes

Source: https://github.com/nervosnetwork/molecule/blob/master/docs/encoding_spec.md

Example serialization of a Molecule union type `HybridBytes` containing a `BytesVec` with two `Bytes` items (`[0x123, 0x456]`). Shows the item type ID for `BytesVec` followed by the serialized bytes of the inner `BytesVec`.

```Hex Bytes
# Item Type Id
02 00 00 00
# the full size of BytesVec is 24 bytes
18 00 00 00
# two offsets of BytesVec (8 bytes in total)
0c 00 00 00, 12 00 00 00,
# two Bytes (12 bytes in total)
02 00 00 00, 01 23
02 00 00 00, 04 56
```

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

### Serialize HybridBytes Union (BytesVecOpt) - Hex Bytes

Source: https://github.com/nervosnetwork/molecule/blob/master/docs/encoding_spec.md

Example serialization of a Molecule union type `HybridBytes` containing a `BytesVecOpt` with `Some` containing a `BytesVec` with two `Bytes` items (`[0x123, 0x456]`). Shows the item type ID for `BytesVecOpt` followed by the serialized bytes of the inner `BytesVecOpt` (which is the serialized `BytesVec`).

```Hex Bytes
# Item Type Id
03 00 00 00
# the full size of BytesVec is 24 bytes
18 00 00 00
# two offsets of BytesVec (8 bytes in total)
0c 00 00 00, 12 00 00 00,
# two Bytes (12 bytes in total)
02 00 00 00, 01 23
02 00 00 00, 04 56
```

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

### Build Project with Make (Shell)

Source: https://github.com/nervosnetwork/molecule/blob/master/fuzzing/c/README.md

Executes the default 'all' target in the Makefile to build the project. This command compiles the necessary components based on the rules defined in the Makefile.

```Shell
make all
```

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

### Importing Types in Molecule

Source: https://github.com/nervosnetwork/molecule/blob/master/docs/schema_language.md

Demonstrates the syntax for importing type definitions from other Molecule schema files using the `import` keyword.

```molecule
import ../library/common_types;
```

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

### Configuring Molecule 0.7 for CKB Scripts (TOML)

Source: https://github.com/nervosnetwork/molecule/blob/master/README.md

Configures the Molecule dependency in a Cargo.toml file for use in CKB scripts, disabling default features to ensure a `no-std` environment.

```TOML
molecule = { version = "0.7", default-features = false }
```

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

### Generating Code with Molecule Compiler (Shell)

Source: https://github.com/nervosnetwork/molecule/blob/master/README.md

Uses the `moleculec` command-line tool to generate code from a Molecule schema file for a specified target programming language.

```Shell
moleculec --language <language> --schema-file <schema-file>
```

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

### Configuring Molecule 0.8+ for CKB Scripts (TOML)

Source: https://github.com/nervosnetwork/molecule/blob/master/README.md

Configures the Molecule dependency in a Cargo.toml file for versions 0.8 and later, disabling default features and explicitly enabling the `bytes_vec` feature for compatibility in CKB scripts.

```TOML
molecule = { version = "0.8.0", default-features = false, features = ["bytes_vec"] }
```

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

### Defining Block Comments in Molecule

Source: https://github.com/nervosnetwork/molecule/blob/master/docs/schema_language.md

Shows the syntax for multi-line block comments in Molecule, enclosed within `/*` and `*/`.

```molecule
/* This
   is
   a
   block
   comment
 */
```

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

### Generate Fuzz Coverage Report with Cargo Fuzz and Cargo Cov (shell)

Source: https://github.com/nervosnetwork/molecule/blob/master/fuzzing/rust/README.md

Generates a code coverage report for the fuzz tests. The first command collects coverage data, and the second command uses `cargo cov` to format this data into an HTML report.

```shell
cargo fuzz coverage data
cargo cov -- show target/x86_64-unknown-linux-gnu/coverage/x86_64-unknown-linux-gnu/release/data \
    --format=html \
    -instr-profile=fuzz/coverage/data/coverage.profdata \
    > data.html
```

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

### Defining Array Type in Molecule

Source: https://github.com/nervosnetwork/molecule/blob/master/docs/schema_language.md

Illustrates the syntax for defining an array type in Molecule, specifying the item type and a fixed size `N`.

```molecule
array ArrayName [ItemType; N];
```

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

### Defining Table Type in Molecule

Source: https://github.com/nervosnetwork/molecule/blob/master/docs/schema_language.md

Illustrates the syntax for defining a table type in Molecule, similar to a struct with named and typed fields, but potentially with different serialization characteristics (often used for variable-size fields).

```molecule
table TableName {
    field_name_1: FieldType1,
    field_name_2: FieldType2,
    field_name_3: FieldType3,
}
```

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

### Defining the Builder Trait in Rust

Source: https://github.com/nervosnetwork/molecule/blob/master/docs/molecule_api.md

The `Builder` trait is used to construct and serialize Molecule structures using the builder pattern. It allows setting fields and then converting the builder into the final serialized `Entity` structure via the `build` method, or writing directly to an I/O writer.

```Rust
pub trait Builder: Default {
    type Entity: Entity;
    const NAME: &'static str;
    fn expected_length(&self) -> usize;
    fn write<W: io::Write>(&self, writer: &mut W) -> io::Result<()>;
    fn build(&self) -> Self::Entity;
}
```

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

### Defining Option Type in Molecule

Source: https://github.com/nervosnetwork/molecule/blob/master/docs/schema_language.md

Provides the syntax for defining an option type in Molecule, which represents a value that may or may not be present, containing an optional item type.

```molecule
option OptionName (ItemType);
```

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

### Defining Struct Type in Molecule

Source: https://github.com/nervosnetwork/molecule/blob/master/docs/schema_language.md

Provides the syntax for defining a struct type in Molecule, which is a composite type with named and typed fields.

```molecule
struct StructName {
    field_name_1: FieldType1,
    field_name_2: FieldType2,
    field_name_3: FieldType3,
}
```

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

### Defining the Reader Trait in Rust

Source: https://github.com/nervosnetwork/molecule/blob/master/docs/molecule_api.md

The `Reader` trait is generated for each Molecule structure in Rust. It provides methods for accessing the internal fields of a structure and includes static methods for verifying data slices, supporting both strict and compatible verification.

```Rust
pub trait Reader<'r>: Sized + fmt::Debug + Clone + Copy {
    type Entity: Entity;
    const NAME: &'static str;
    fn verify(slice: &[u8], compatible: bool) -> VerificationResult<()>;
    fn new_unchecked(slice: &'r [u8]) -> Self;
    fn as_slice(&self) -> &'r [u8];
    fn from_slice(slice: &'r [u8]) -> VerificationResult<Self> {
        Self::verify(slice, false).map(|_| Self::new_unchecked(slice))
    }
    fn from_compatible_slice(slice: &'r [u8]) -> VerificationResult<Self> {
        Self::verify(slice, true).map(|_| Self::new_unchecked(slice))
    }
    fn to_entity(&self) -> Self::Entity;
}
```

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

### Defining Union Type in Molecule

Source: https://github.com/nervosnetwork/molecule/blob/master/docs/schema_language.md

Shows the syntax for defining a union type in Molecule, which can hold a value of one of several specified item types.

```molecule
union UnionName {
    ItemType1,
    ItemType2,
    ItemType3,
}
```

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

### Serializing Array of Bytes (Byte3) - Byte Sequence

Source: https://github.com/nervosnetwork/molecule/blob/master/docs/encoding_spec.md

Demonstrates the serialization of a fixed-size array `Byte3` containing three byte values (01, 02, 03). The bytes are stored consecutively in the serialized output.

```Byte Sequence
01 02 03
```

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

### Defining Vector Type in Molecule

Source: https://github.com/nervosnetwork/molecule/blob/master/docs/schema_language.md

Shows the syntax for defining a vector type in Molecule, which is a composite type with a single item type and variable size.

```molecule
vector VectorName <ItemType>;
```

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

### Defining the Entity Trait in Rust

Source: https://github.com/nervosnetwork/molecule/blob/master/docs/molecule_api.md

The `Entity` trait represents a serialized data structure in Molecule's Rust implementation. It provides methods for creating, accessing, and verifying data, including handling compatible schema versions. It's important to distinguish between `as_slice` (complete data) and `raw_data` (data without header).

```Rust
pub trait Entity: fmt::Debug + Default + Clone {
    type Builder: Builder;
    const NAME: &'static str;
    fn new_unchecked(data: Bytes) -> Self;
    fn as_bytes(&self) -> Bytes;
    fn as_slice(&self) -> &[u8];
    fn from_slice(slice: &[u8]) -> VerificationResult<Self>;
    fn from_compatible_slice(slice: &[u8]) -> VerificationResult<Self>;
    fn new_builder() -> Self::Builder;
    fn as_builder(self) -> Self::Builder;
}
```
Tokens:
Raw