Crate strict_encoding_derive[][src]

Expand description

Derivation macros for strict encoding. To learn more about the strict encoding please check strict_encoding crate.

Derivation macros

Library exports derivation macros #[derive(StrictEncode)], #[derive(StrictDecode)], #[derive(NetworkEncode)] and #[derive(NetworkDecode)], which can be added on top of any structure you’d like to support string encoding (see Example section below).

Encoding/decoding implemented by both of these macros may be configured at type and individual field level using #[strict_encoding(...)] and #[network_encoding(...)] attributes.

The difference between strict and network encoding is in the support of TLV (type-length-value) extensions: strict encoding, used for pure client-side-validation, does not allow use of TLVs, while in network protocol context this requirement is relaxed and specially-designed TLV encoding is allowed (see sections below on how to use TLV encoding). Network encoding TLV is not strictly BOLT-1 compatible; if you are looking for BOLT-1 TLV implementation, please check lightning_encoding_derive crate.


StrictEncode and StrictDecode behavior can be customized with #[strict_encoding(...)] attribute, which accepts different arguments depending to which part of the data type it is applied.

The same applies to NetworkEncode and NetworkDecode, which use #[network_encoding(...)] attribute with the same syntax and internal parameters.

Attribute arguments at type declaration level

Derivation macros accept #[strict_encoding()] attribute with the following arguments:


Applies TLV extension to the data type and allows use of tlv and unknown_tlvs arguments on struct fields.

NB: TLVs work only with structures and not enums.

crate = ::path::to::strict_encoding_crate

Allows to specify custom path to strict_encoding crate

repr = <uint>

Can be used with enum types only.

Specifies which unsigned integer type must represent enum variants during the encoding. Possible values are u8, u16, u32 and u64.

For enum veriants without associated values defaults to u8, independently of rust enum #[repr(...)] attribute value or presence (see also NB below).

NB: This argument is not equal to the rust #[repr(...)] attribute, which defines C FFI representation of the enum type. For their combined usage pls check examples below


Can be used with enum types only, where they define which encoding strategy should be used for representation of enum variants:

  • by_value - encodes enum variants using their value representation (see repr above)
  • by_order - encodes enum variants by their ordinal position starting from zero. Can’t be combined with by_value.

If neither of these two arguments is provided, the macro defaults to by_order encoding.

Attribute arguments at field and enum variant level

Derivation macros accept #[strict_encoding()] attribute with the following arguments


Skips field during serialization and initialize field value with Default::default() on type deserialization.

Allowed only for named and unnamed (tuple) structure fields and enum variant associated value fields.

value = <unsigned integer>

Allowed only for enum variants.

Assigns custom value for a given enum variant, overriding by_value and by_order directives defined at type level and the actual variant value, if any.

NB: If the value conflicts with the values of other enum variants, taken from either their assigned value (for by_value-encoded enums), order index (for by_order-encoded enums) or other variant’s value from with explicit value argument the compiler will error.

tlv = <unsigned 16-bit int>

Sets the TLV type id for the field. The field type MUST be Option and it must implement Default.


Specifies structure field which will be “capture all” for unknown odd TLV ids. The argument can be used only for a single field within a structure and the field type must be BTreeMap<usize, Box<[u8]>].

NB: if an unknown even TLV type id is met, error is raised and the value does not get into the field.


use strict_encoding::StrictEncode;

// All variants have custom values apart from the first one, which should has
// value = 1
#[derive(StrictEncode, StrictDecode)]
#[strict_encoding(by_value, repr = u32)]
enum CustomValues {
    Bit8 = 1,

    #[strict_encoding(value = 0x10)]
    Bit16 = 2,

    #[strict_encoding(value = 0x1000)]
    Bit32 = 4,

    #[strict_encoding(value = 0x100000)]
    Bit64 = 8,

assert_eq!(CustomValues::Bit8.strict_serialize(), Ok(vec![0x01, 0x00, 0x00, 0x00]));
assert_eq!(CustomValues::Bit16.strict_serialize(), Ok(vec![0x10, 0x00, 0x00, 0x00]));
assert_eq!(CustomValues::Bit32.strict_serialize(), Ok(vec![0x00, 0x10, 0x00, 0x00]));
assert_eq!(CustomValues::Bit64.strict_serialize(), Ok(vec![0x00, 0x00, 0x10, 0x00]));
use strict_encoding::StrictEncode;

#[derive(StrictEncode, StrictDecode)]
#[strict_encoding(by_order, repr = u16)]
enum U16 {
    Bit8 = 1, // this will be encoded as 0x0000, since we use `by_order` here
    Bit16 = 2,
    Bit32 = 4,
    Bit64 = 8,

assert_eq!(U16::Bit8.strict_serialize(), Ok(vec![0x00, 0x00]));
assert_eq!(U16::Bit16.strict_serialize(), Ok(vec![0x01, 0x00]));
assert_eq!(U16::Bit32.strict_serialize(), Ok(vec![0x02, 0x00]));
assert_eq!(U16::Bit64.strict_serialize(), Ok(vec![0x03, 0x00]));
use strict_encoding::{StrictDecode, StrictEncode};

#[derive(StrictEncode, StrictDecode)]
struct Skipping {
    pub data: Vec<u8>,

    // This will initialize the field upon decoding with Option::default()
    // value (i.e. `None`)
    pub ephemeral: Option<bool>,

let obj = Skipping {
    data: b"abc".to_vec(),
    ephemeral: Some(true),
let ser = obj.strict_serialize().unwrap();

assert_eq!(ser, vec![0x03, 0x00, b'a', b'b', b'c']);
let de = Skipping::strict_deserialize(&ser).unwrap();
assert_eq!(de.ephemeral, None);

Derive Macros

Derives StrictDecode implementation for the type, also providing TLV extension support.

Derives StrictEncode implementation for the type, also providing TLV extension support.

Derives StrictDecode implementation for the type.

Derives StrictEncode implementation for the type.