22 releases

0.8.1 Jan 13, 2021
0.7.2 Jan 14, 2021
0.7.1 Aug 24, 2020
0.7.0 Jun 17, 2020
0.2.10 Nov 27, 2019

#603 in Encoding

Download history 1465/week @ 2020-10-02 1251/week @ 2020-10-09 1447/week @ 2020-10-16 1425/week @ 2020-10-23 1748/week @ 2020-10-30 1468/week @ 2020-11-06 1986/week @ 2020-11-13 1135/week @ 2020-11-20 1593/week @ 2020-11-27 1602/week @ 2020-12-04 1425/week @ 2020-12-11 797/week @ 2020-12-18 277/week @ 2020-12-25 713/week @ 2021-01-01 982/week @ 2021-01-08 1058/week @ 2021-01-15

5,381 downloads per month
Used in 14 crates (3 directly)

Apache-2.0

67KB
1.5K SLoC

Borsh in Rust   Build Status Latest Version borsh: rustc 1.40+ License Apache-2.0 badge License MIT badge

borsh-rs is Rust implementation of the Borsh binary serialization format.

Borsh stands for Binary Object Representation Serializer for Hashing. It is meant to be used in security-critical projects as it prioritizes consistency, safety, speed, and comes with a strict specification.

Example

use borsh::{BorshSerialize, BorshDeserialize};

#[derive(BorshSerialize, BorshDeserialize, PartialEq, Debug)]
struct A {
    x: u64,
    y: String,
}

#[test]
fn test_simple_struct() {
    let a = A {
        x: 3301,
        y: "liber primus".to_string(),
    };
    let encoded_a = a.try_to_vec().unwrap();
    let decoded_a = A::try_from_slice(&encoded_a).unwrap();
    assert_eq!(a, decoded_a);
}

Features

Opting out from Serde allows borsh to have some features that currently are not available for serde-compatible serializers. Currently we support two features: borsh_init and borsh_skip (the former one not available in Serde).

borsh_init allows to automatically run an initialization function right after deserialization. This adds a lot of convenience for objects that are architectured to be used as strictly immutable. Usage example:

#[derive(BorshSerialize, BorshDeserialize)]
#[borsh_init(init)]
struct Message {
    message: String,
    timestamp: u64,
    public_key: CryptoKey,
    signature: CryptoSignature
    hash: CryptoHash
}

impl Message {
    pub fn init(&mut self) {
        self.hash = CryptoHash::new().write_string(self.message).write_u64(self.timestamp);
        self.signature.verify(self.hash, self.public_key);
    }
}

borsh_skip allows to skip serializing/deserializing fields, assuming they implement Default trait, similary to #[serde(skip)].

#[derive(BorshSerialize, BorshDeserialize)]
struct A {
    x: u64,
    #[borsh_skip]
    y: f32,
}

Releasing

After you merged your change into the master branch and bumped the versions of all three crates it is time to officially release the new version.

Make sure borsh, borsh-derive, borsh-derive-internal, and borsh-schema-derive-internal all have the new crate versions. Then run the publish.sh script:

sh publish.sh

Make sure you are on the master branch, then tag the code and push the tag:

git tag -a v9.9.9 -m "My superawesome change."
git push origin v9.9.9

License

This repository is distributed under the terms of both the MIT license and the Apache License (Version 2.0). See LICENSE-MIT and LICENSE-APACHE for details.

Dependencies

~0.8–1.3MB
~32K SLoC