Module envelope

Envelope format for HUGR packages.

The format is designed to be extensible and backwards-compatible. It consists of a header declaring the format used to encode the HUGR, followed by the encoded HUGR itself.

Use read_envelope and write_envelope for reading and writing envelopes from/to readers and writers, or call Package::load and Package::store directly.

Payload formats

The envelope may encode the HUGR in different formats, listed in EnvelopeFormat. The payload may also be compressed with zstd.

Some formats can be represented as ASCII, as indicated by the EnvelopeFormat::ascii_printable method. When this is the case, the whole envelope can be stored in a string.

Envelope header

The binary header format is 10 bytes, with the following fields:

Field	Size (bytes)	Description
Magic	8	MAGIC_NUMBERS constant identifying the envelope format.
Format	1	EnvelopeFormat describing the payload format.
Flags	1	Additional configuration flags.

Flags:

• Bit 0: Whether the payload is compressed with zstd.
• Bits 1-5: Reserved for future use.
• Bit 7,6: Constant “01” to make some headers ascii-printable.

Modules

serde_with

Derivation to serialize and deserialize Hugrs and Packages as envelopes in a serde compatible way.

Structs

EnvelopeConfig

Configuration for encoding an envelope.

ExtensionVersionMismatch

Error raised when the reported used version of an extension does not match the registered version in the extension registry.

WithGenerator

Wrap an error with a generator string.

ZstdConfig

Configuration for zstd compression.

Enums

EnvelopeError

Error type for envelope operations.

EnvelopeFormat

Encoded format of an envelope payload.

ExtensionBreakingError

Error raised when checking for breaking changes in used extensions.

PackageEncodingError

Error raised while loading a package.

Constants

GENERATOR_KEY

Key used to store the name of the generator that produced the envelope.

MAGIC_NUMBERS

Magic number identifying the start of an envelope.

USED_EXTENSIONS_KEY

Key used to store the list of used extensions in the metadata of a HUGR.

Functions

format_generator

Format a generator value from the metadata.

get_generator

Get the name of the generator from the metadata of the HUGR modules.

read_envelope

Read a HUGR envelope from a reader.

write_envelope

Write a HUGR package into an envelope, using the specified configuration.