Crate ark_serialize

Source
Expand description

ark-serialize

ark-serialize defines the CanonicalSerialize and CanonicalDeserialize traits for serializing and deserializing Rust data structures to bytes efficiently. The interfaces offered by these traits are specialized for serializing cryptographic objects. In particular, they offer special support for compressed representation of elliptic curve elements. Most types in arkworks-rs implement these traits.

§Usage

To use ark-serialize, add the following to your Cargo.toml:

ark-serialize = "0.4"

If you additionally want to derive implementations of the CanonicalSerialize and CanonicalDeserialize traits for your own types, you can enable the derive feature:

ark-serialize = { version = "0.4", features = ["derive"] }

§Examples

Let us first see how to use ark-serialize for existing types:

// We'll use the BLS12-381 pairing-friendly group for this example.
use ark_test_curves::bls12_381::{G1Projective as G1, G2Projective as G2, G1Affine, G2Affine};
use ark_serialize::{CanonicalSerialize, CanonicalDeserialize};
use ark_std::UniformRand;

let mut rng = ark_std::test_rng();
// Let's sample uniformly random group elements:
let a: G1Affine = G1::rand(&mut rng).into();
let b: G2Affine = G2::rand(&mut rng).into();

// We can serialize with compression...
let mut compressed_bytes = Vec::new();
a.serialize_compressed(&mut compressed_bytes).unwrap();
// ...and without:
let mut uncompressed_bytes = Vec::new();
a.serialize_uncompressed(&mut uncompressed_bytes).unwrap();

// We can reconstruct our points from the compressed serialization...
let a_compressed = G1Affine::deserialize_compressed(&*compressed_bytes).unwrap();

// ... and from the uncompressed one:
let a_uncompressed = G1Affine::deserialize_uncompressed(&*uncompressed_bytes).unwrap();

assert_eq!(a_compressed, a);
assert_eq!(a_uncompressed, a);

// If we trust the origin of the serialization
// (eg: if the serialization was stored on authenticated storage),
// then we can skip some validation checks, which can greatly reduce deserialization time.
let a_uncompressed_unchecked = G1Affine::deserialize_uncompressed_unchecked(&*uncompressed_bytes).unwrap();
let a_compressed_unchecked = G1Affine::deserialize_compressed_unchecked(&*compressed_bytes).unwrap();
assert_eq!(a_uncompressed_unchecked, a);
assert_eq!(a_compressed_unchecked, a);

If we want to serialize our own structs, we can derive implementations of the CanonicalSerialize and CanonicalDeserialize traits if all fields implement these traits. For example:

use ark_test_curves::bls12_381::{G1Affine, G2Affine};
use ark_serialize::{CanonicalSerialize, CanonicalDeserialize};

#[derive(CanonicalSerialize, CanonicalDeserialize)]
pub struct MyStruct {
    a: G1Affine,
    b: G2Affine,
}

We can also implement these traits manually. For example:

use ark_test_curves::bls12_381::{G1Affine, G2Affine};
use ark_serialize::{CanonicalSerialize, CanonicalDeserialize, Compress, SerializationError, Valid, Validate};
use ark_std::io::{Read, Write};

pub struct MyStruct {
    a: G1Affine,
    b: G2Affine,
}

impl CanonicalSerialize for MyStruct {
    // We only have to implement the `serialize_with_mode` method; the other methods 
    // have default implementations that call the latter.
    //
    // Notice that `serialize_with_mode` takes `mode: Compress` as an argument. This 
    // is used to indicate whether we want to serialize with or without compression.
    fn serialize_with_mode<W: Write>(&self, mut writer: W, mode: Compress) -> Result<(), SerializationError> {
        self.a.serialize_with_mode(&mut writer, mode)?;
        self.b.serialize_with_mode(&mut writer, mode)?;
        Ok(())
    }

    fn serialized_size(&self, mode: Compress) -> usize {
        self.a.serialized_size(mode) + self.b.serialized_size(mode)
    }
}

impl CanonicalDeserialize for MyStruct {
    // We only have to implement the `deserialize_with_mode` method; the other methods 
    // have default implementations that call the latter.
    fn deserialize_with_mode<R: Read>(mut reader: R, compress: Compress, validate: Validate) -> Result<Self, SerializationError> {
        let a = G1Affine::deserialize_with_mode(&mut reader, compress, validate)?;
        let b = G2Affine::deserialize_with_mode(&mut reader, compress, validate)?;
        Ok(Self { a, b })
    }
}

// We additionally have to implement the `Valid` trait for our struct.
// This trait specifies how to perform certain validation checks on deserialized types.
// For example, we can check that the deserialized group elements are in the prime-order subgroup.
impl Valid for MyStruct {
    fn check(&self) -> Result<(), SerializationError> {
        self.a.check()?;
        self.b.check()?;
        Ok(())
    }
}

Macros§

  • serialize_to_vec
    Serializes the given CanonicalSerialize items in sequence. serialize_to_vec![a, b, c, d, e] is identical to the value of buf after (a, b, c, d, e).serialize_compressed(&mut buf).

Structs§

  • EmptyFlags
    Flags to be encoded into the serialization.

Enums§

  • Compress
    Whether to use a compressed version of the serialization algorithm. Specific behavior depends on implementation. If no compressed version exists (e.g. on Fp), mode is ignored.
  • SerializationError
    This is an error that could occur during serialization
  • Validate
    Whether to validate the element after deserializing it. Specific behavior depends on implementation. If no validation algorithm exists (e.g. on Fp), mode is ignored.

Traits§

  • CanonicalDeserialize
    Deserializer in little endian format. This trait can be derived if all fields of a struct implement CanonicalDeserialize and the derive feature is enabled.
  • CanonicalDeserializeWithFlags
    Deserializer in little endian format allowing flags to be encoded.
  • CanonicalSerialize
    Serializer in little endian format. This trait can be derived if all fields of a struct implement CanonicalSerialize and the derive feature is enabled.
  • CanonicalSerializeHashExt
    The CanonicalSerialize induces a natural way to hash the corresponding value, of which this is the convenience trait.
  • CanonicalSerializeWithFlags
    Serializer in little endian format allowing to encode flags.
  • Flags
    Represents metadata to be appended to an object’s serialization. For example, when serializing elliptic curve points, one can use a Flag to represent whether the serialization is the point at infinity, or whether the y coordinate is positive or not. These bits will be appended to the end of the point’s serialization, or included in a new byte, depending on space available.
  • Read
    The Read trait allows for reading bytes from a source.
  • Valid
  • Write

Functions§