Trait Packable

Space-efficient value packing and unpacking.

Like Serialize and Deserialize, this trait is used to convert to a from Field array representations. Packable is used instead of those whenever the length of the resulting array needs to be minimized, for example in order to reduce the number of amount storage access operations, or the number of values that will be hashed together.

The associated constant N is the length of the Field array.

Automatic Derivation

The #[derive] macro can be used on any type that holds primitive values, or types that themselves also derive Packable. The resulting implementation does not attempt to tightly-pack values at all, and instead simply assigns a full Field to each value. This makes it suitable for types that are composed solely of Field-sized elements.

#[derive(Packable)]
struct FieldGrouping {
    a: Field,
    b: Field,
    c: Field,
}

#[derive(Packable)]
struct NestedStructs {
    fg: FieldGrouping,
    x: Field,
}

// Inefficient: there are gains to be had by manually implementing the trait instead of using `derive`
#[derive(Packable)]
struct SubFieldGrouping {
    a: bool,
    b: u32,
    c: u64,
}

Manual Implementation

If a type holds at least two elements smaller than a Field, then manually implementing Packable can result in reduced costs (assuming the sub-Field elements are small enough to be packed together).

The nature of cost reduction will depend on what the value is used for. For public storage, it will typically decrease both L2 gas (in the form of fewer SLOAD and SSTORE opcodes) and DA costs (due to there being fewer slots accessed). For notes, it will typically decrease proving times (due to fewer hash operations).

Note that packing and unpacking must also be runtime efficient for the previously mentioned gains to not be offset by this overhead. Bit-packing by multiplying and dividing by powers of 2 is often a good strategy, as this maps well to both AVM opcodes (for public contract functions) and proving backend primitives (for private contract functions).

struct TwoBooleans {
    a: bool,
    b: bool,
}

impl Packable for TwoBooleans {
    let N: u32 = 1;

    fn pack(self) -> [Field; Self::N] {
        // a in bit 1, b in bit 0
        [(self.a as Field) * 2.pow_32(1) + (self.b as Field)]
    }

    fn unpack(packed: [Field; Self::N]) -> Self {
        let b = (packed[0] as u1) != 0;
        let a = (((packed[0] - b as Field) / 2.pow_32(1)) as u1) != 0;

        Self { a, b }
    }
}