miden-mast-package 0.24.0

Package containing a compiled Miden MAST artifact with declared dependencies and exports
Documentation

Overview

The miden-mast-package crate provides the Package type, which represents a Miden package. It contains a compiled MastForest together with package metadata, exports, runtime dependencies, and optional custom sections.

Binary Format

The header contains the following fields:

  • MASP\0 magic bytes;
  • Version of the package binary format (currently 6.0.0);

The package data contains:

  • Package name
  • Package semantic version
  • Package description (optional)
  • Package target kind
  • MAST artifact (MastForest)
  • Package manifest containing:
    • List of exports, where each export has:
      • Name
      • Digest
    • List of dependencies, where each dependency has:
      • Name
      • Target kind
      • Semantic version
      • Digest
  • Optional custom sections, including package-owned debug sections and the embedded kernel package section used by executable packages

Package digests are derived from the underlying MAST artifact. Registry implementations typically use the semantic version together with that digest as the exact published package identity.

Debug Sections and Trust

Package-owned debug information lives in optional debug custom sections, not in the embedded MastForest. Readers choose how those sections are handled:

  • Package::read_from and Package::read_from_bytes are for untrusted artifacts. They validate the embedded MAST forest and discard package-owned debug sections before returning the package.
  • Package::read_from_trusted and Package::read_from_bytes_trusted are for trusted local files or cache entries. They validate the embedded MAST forest and preserve package-owned debug sections so Package::debug_info can decode them.
  • Package::read_from_unchecked and Package::read_from_bytes_unchecked are same-domain trusted cache readers. They preserve package-owned debug sections, but skip MAST validation because the bytes must already have been validated before persistence.

Embedded kernel package bytes are carried in the opaque kernel custom section. An untrusted read may carry that section, but decoding the embedded kernel through the package API uses the untrusted reader and strips nested debug sections before exposing the kernel package. Artifacts serialized for consumption by an untrusted path should be produced from Package::without_debug_info or after Package::strip_debug_info.

License

This project is dual-licensed under the MIT and Apache 2.0 licenses.