Struct Package 

pub struct Package {
    pub name: PackageId,
    pub version: Version,
    pub description: Option<String>,
    pub kind: TargetType,
    pub manifest: PackageManifest,
    pub sections: Vec<Section>,
    /* private fields */
}

A package is a assembled artifact containing:

• Basic metadata like name, description, and semantic version
• The type of target the package represents, e.g. a library or executable
• A manifest describing the contents of the package, see PackageManifest for more details.
• A MastForest corresponding to the assembled target
• One or more custom sections containing metadata produced by the assembler or other tools which is relevant to the package, e.g. debug symbols.

Custom sections which are of particular interest:

• For account components, the package will contain a section that provides component metadata
• For executable packages which link against a kernel, the package will embed the kernel package in a custom section, so that executables are “self-contained”.
• When assembled with debug information, various types of debug info are emitted to custom sections for use by debuggers and other introspection tooling.

See SectionId for the set of well-known sections, and what they are used for.

Fields

name: PackageId

Name of the package

version: Version

An optional semantic version for the package

description: Option<String>

An optional description of the package

kind: TargetType

The project target type which produced this package

manifest: PackageManifest

The package manifest, containing the set of exported procedures and their signatures, if known.

sections: Vec<Section>

The set of custom sections included with the package, e.g. debug information, account metadata, etc.

Implementations

impl Package

pub fn read_from_trusted<R>( source: &mut R, ) -> Result<Package, DeserializationError>

where R: ByteReader,

Reads a package from trusted storage without validating the embedded MAST forest.

Trust boundary

This skips embedded MAST and manifest cross-check validation and trusts serialized node digests. Use it for a package written and retained by the same trusted system, such as a local build cache.

Do not use this for user-controlled packages, network input, or any other package that crosses a trust boundary. Use Package::read_from for those inputs.

pub fn read_from_bytes_trusted( bytes: &[u8], ) -> Result<Package, DeserializationError>

Reads package bytes from trusted storage without validating the embedded MAST forest.

Trust boundary

This skips embedded MAST and manifest cross-check validation and trusts serialized node digests. Use it for a package written and retained by the same trusted system, such as a local build cache. This method still applies the finite byte-read budget used by Package::read_from_bytes.

Do not use this for user-controlled packages, network input, or any other package that crosses a trust boundary. Use Package::read_from_bytes for those inputs.

impl Package

Construction

pub fn create( name: PackageId, version: Version, kind: TargetType, mast: Arc<MastForest>, exports: impl IntoIterator<Item = PackageExport>, dependencies: impl IntoIterator<Item = Dependency>, ) -> Result<Package, ManifestValidationError>

Construct a Package from its essential component parts

pub fn create_with_modules( name: PackageId, version: Version, kind: TargetType, mast: Arc<MastForest>, exports: impl IntoIterator<Item = PackageExport>, modules: impl IntoIterator<Item = PackageModule>, dependencies: impl IntoIterator<Item = Dependency>, ) -> Result<Package, ManifestValidationError>

Construct a Package from its essential component parts and module surface metadata.

pub fn with_advice_map(self, advice_map: AdviceMap) -> Package

Produces a new library with the existing MastForest and where all key/values in the provided advice map are added to the internal advice map.

pub fn extend_advice_map(&mut self, advice_map: AdviceMap)

Extends the advice map of this library

pub fn strip_debug_info(&mut self) -> Result<(), PackageStripError>

Removes all package-owned debug information from this package.

This removes well-known package debug sections and recursively strips an embedded kernel package if one is present.

pub fn without_debug_info(self) -> Result<Package, PackageStripError>

Returns this package with package-owned debug information removed.

impl Package

Accessors

pub const EXTENSION: &'static str = "masp"

The file extension given to serialized packages

pub fn mast_forest(&self) -> &Arc<MastForest>

Returns a reference to the MAST contained in this package

pub fn interface_commitment(&self) -> Result<Word, ManifestValidationError>

Returns the commitment to the exported procedure roots used by the linker.

pub fn mast_forest_commitment(&self) -> Word

Returns the commitment to the package’s MAST forest.

pub fn code_commitment(&self) -> Word

Returns the commitment to the package’s code.

This binds the public interface to the complete MAST forest which implements it.

pub fn dependency_commitment(&self) -> Word

Returns the commitment used to identify this package during dependency resolution.

This binds the package code, identity, manifest, and sections which affect package use. Optional debug data, descriptions, and opaque custom sections are excluded.

pub fn artifacts_commitment(&self) -> Word

Returns the commitment to all serialized package data outside the MAST forest.

pub fn commitment(&self) -> Word

Returns the commitment to the complete package.

pub fn is_program(&self) -> bool

Returns true if this package was produced for an executable target

pub fn is_library(&self) -> bool

Returns true if this package was produced for a library or kernel target

pub fn is_kernel(&self) -> bool

Returns true if this package was produced specifically for a kernel target

pub fn entrypoint(&self) -> Option<Arc<Path>>

Returns the absolute path of the entrypoint procedure for this package, if it is executable

pub fn entrypoint_source_node(&self) -> Option<DebugSourceNodeId>

Returns the source/debug occurrence for the executable entrypoint, if recorded.

pub fn kernel_module_descriptor(&self) -> Result<ModuleDescriptor, Report>

Get the ModuleDescriptor corresponding to the kernel module, if this package contains the kernel

pub fn kernel_runtime_dependency(&self) -> Result<Option<&Dependency>, Report>

If this package depends on a kernel, this method extracts the Dependency corresponding to it.

Returns Err if the dependency metadata for this package contains multiple kernels.

pub fn debug_info( &self, ) -> Result<Option<DebugInfo<MastNodeId, DebugSourceNodeId>>, PackageDebugInfoError>

Decodes validated or trusted package-owned debug sections, if any are present.

Normal package readers validate debug sections before returning. Explicit trusted readers and in-process construction may defer validation until this method is called.

Decoding uses the fixed resource limits of Deserializable::read_from. Analysis tools that intentionally accept larger debug information can locate SectionId::DEBUG_INFO in Package::sections and call PackageDebugInfo::read_from_bytes_unmetered on its data. That alternative does not perform this method’s package-level reference validation.

This does not read legacy debug metadata from the embedded MastForest.

pub fn get_export_node_id(&self, path: impl AsRef<Path>) -> MastNodeId

Returns a MAST node ID associated with the specified exported procedure.

Panics

Panics if the specified procedure is not exported from this package.

pub fn is_reexport(&self, path: impl AsRef<Path>) -> bool

Returns true if the specified exported procedure is re-exported from a dependency.

pub fn get_procedure_root_by_path(&self, path: impl AsRef<Path>) -> Option<Word>

Returns the digest of the procedure with the specified name, or None if it was not found in the library or its library path is malformed.

pub fn get_procedure_node_by_path( &self, path: impl AsRef<Path>, ) -> Option<MastNodeId>

Returns the exact procedure node for the specified path, if it is present.

pub fn get_export_node(&self, export: &ProcedureExport) -> Option<MastNodeId>

Resolves the MAST node corresponding to export, or None if it cannot be found.

The returned node is the recorded export.node only when it points at a procedure root in this package’s forest whose digest matches export.digest; otherwise this falls back to a digest-based lookup.

This is the non-panicking counterpart to Package::get_export_node_id, though the two take different arguments: get_export_node_id resolves an export by path and panics if not found, while this method resolves an already-known &ProcedureExport and treats its recorded node as an untrusted hint rather than authoritative.

pub fn procedures_with_attribute<'a>( &'a self, attr: &'a str, ) -> impl Iterator<Item = &'a ProcedureExport> + 'a

Returns an iterator over the procedures exported by this package that carry the attribute named attr.

pub fn module_descriptors(&self) -> impl Iterator<Item = ModuleDescriptor>

Returns an iterator over the module descriptors of the package.

pub fn try_module_descriptors( &self, ) -> Result<Vec<ModuleDescriptor>, ManifestValidationError>

Returns module descriptors after validating that manifest module-surface metadata is complete.

Unlike Self::module_descriptors, this method does not synthesize missing module surfaces from item export paths. Link-time resolution relies on explicit module metadata so that modules remain distinct from exported items.

impl Package

Conversions

pub fn to_kernel_descriptor(&self) -> Result<KernelDescriptor, Report>

Get a KernelDescriptor from this package, if this package contains one.

pub fn try_embedded_kernel_package( &self, ) -> Result<Option<Box<Package>>, Report>

Extract the embedded kernel package from this package.

Returns Ok(None) if the kernel custom section is not present.

Returns an error if:

• The embedded package is not a kernel
• The package manifest of self does not declare a kernel dependency
• The embedded kernel does not match the declared kernel dependency

pub fn to_dependency(&self) -> Dependency

Get a Dependency that represents this package

pub fn make_executable( &self, entrypoint: &QualifiedProcedureName, ) -> Result<Package, Report>

Derive a new executable package from this one by specifying the entrypoint to use.

To succeed, the following must be true:

• This package was produced from a library target
• The entrypoint procedure is exported from this package according to the manifest
• The entrypoint procedure can be resolved to a node in the MAST of this package

The resulting package has a target type and manifest reflecting what would have been used if the package was originally assembled as an executable, however the underlying miden_core::mast::MastForest is left untouched, so the resulting package may still contain nodes in the forest which are now unused.

impl Package

Serialization

pub fn write_to_file(&self, path: impl AsRef<Path>) -> Result<(), Error>

Write this package to path

pub fn write_masp_file(&self, dir: impl AsRef<Path>) -> Result<(), Error>

Write this package to a file in dir named $name.masp, where $name is the package name.

pub fn deserialize_from_file( path: impl AsRef<Path>, ) -> Result<Package, DeserializationError>

Reads a package file from an untrusted path.

This validates the embedded MAST forest and discards package-owned debug sections before returning the package. Use this for user-provided paths or bytes received across a trust boundary.

pub fn deserialize_from_file_trusted( path: impl AsRef<Path>, ) -> Result<Package, DeserializationError>

Reads a trusted local package file.

This skips embedded MAST and manifest cross-check validation, preserves package-owned debug sections, and should be used only for files/cache entries controlled by the same trusted build or execution system. Use Self::read_from_bytes for bytes received across a trust boundary.

Trait Implementations

impl AsRef<Package> for AccountComponentCode

fn as_ref(&self) -> &Package

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<Package> for ProtocolLib

fn as_ref(&self) -> &Package

Converts this type into a shared reference of the (usually inferred) input type.

impl Clone for Package

fn clone(&self) -> Package

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Package

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Deserializable for Package

fn read_from<R>(source: &mut R) -> Result<Package, DeserializationError>

where R: ByteReader,

Reads and validates a package from potentially adversarial input.

This validates the embedded MAST forest, manifest references, and package-owned debug information before returning. The caller’s ByteReader controls the resource budget. For a byte slice, prefer Package::read_from_bytes, which applies a finite byte-read budget. Use Package::read_from_trusted for packages written and retained by the same trusted system when repeating these checks is unnecessary.

fn read_from_bytes(bytes: &[u8]) -> Result<Package, DeserializationError>

Reads and validates a package from a potentially adversarial byte slice.

This is the recommended reader for untrusted package bytes. It applies a finite byte-read budget and validates the embedded MAST forest, manifest references, and package-owned debug information. Use Package::read_from_bytes_trusted for packages written and retained by the same trusted system when repeating these checks is unnecessary.

fn min_serialized_size() -> usize

Returns the minimum serialized size for one instance of this type.

fn read_from_bytes_with_budget( bytes: &[u8], budget: usize, ) -> Result<Self, DeserializationError>

Deserializes Self from bytes with a byte budget limit.

impl Eq for Package

impl From<AccountComponentCode> for Package

fn from(value: AccountComponentCode) -> Self

Converts to this type from the input type.

impl From<Package> for AccountComponentCode

fn from(value: Package) -> Self

Converts to this type from the input type.

impl From<ProtocolLib> for Package

fn from(value: ProtocolLib) -> Self

Converts to this type from the input type.

impl PartialEq for Package

fn eq(&self, other: &Package) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl Serializable for Package

fn write_into<W>(&self, target: &mut W)

where W: ByteWriter,

Serializes self into bytes and writes these bytes into the target.

fn to_bytes(&self) -> Vec<u8>

Serializes self into a vector of bytes.

fn get_size_hint(&self) -> usize

Returns an estimate of how many bytes are needed to represent self.

impl StructuralPartialEq for Package

impl TryFrom<&Package> for AccountComponentMetadata

type Error = AccountError

The type returned in the event of a conversion error.

fn try_from(package: &Package) -> Result<Self, Self::Error>

Performs the conversion.