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_unchecked<R>( source: &mut R, ) -> Result<Package, DeserializationError>

where R: ByteReader,

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

Trust boundary

This skips embedded MAST validation and trusts serialized node digests. Use it only for bytes that were already validated before being persisted by the same trusted system.

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

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

Reads trusted package bytes without validating the embedded MAST forest.

Trust boundary

This skips embedded MAST validation and trusts serialized node digests. Use it only for bytes that were already validated before being persisted by the same trusted system.

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

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

where R: ByteReader,

Reads a trusted local package while validating the embedded MAST forest.

This keeps the same structural validation as Package::read_from, but allows package-owned debug sections to be decoded as trusted metadata. Use this only for local files or cache artifacts controlled by this process or build system. Do not use this for inbound artifacts from an untrusted channel; use Package::read_from instead so debug sections are discarded before the package is exposed to callers.

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

Reads trusted local package bytes while validating the embedded MAST forest.

See Package::read_from_trusted.

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 digest(&self) -> Word

Returns the digest of the package’s MAST artifact

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

Returns the digest of the exported procedure roots used by the linker.

pub fn content_digest(&self) -> Word

Returns a digest of the package content relevant to assembly and dependency resolution.

This is distinct from Self::digest, which is only the digest of the underlying MAST artifact. The content digest currently binds the MAST digest, package name, semantic version, package kind, manifest, and any semantic package sections. Package descriptions and opaque custom sections are intentionally excluded for now; kernel-section binding is added separately.

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_info(&self) -> Result<ModuleInfo, Report>

Get the ModuleInfo 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<PackageDebugInfo>, PackageDebugInfoError>

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

Package debug sections are trusted only for packages constructed in-process or read via the trusted same-domain readers such as Self::read_from_trusted, Self::read_from_bytes_trusted, Self::read_from_unchecked, and Self::read_from_bytes_unchecked. Normal untrusted readers discard debug sections before returning the package.

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 module_infos(&self) -> impl Iterator<Item = ModuleInfo>

Returns an iterator over the module infos of the library.

pub fn try_module_infos( &self, ) -> Result<Vec<ModuleInfo>, ManifestValidationError>

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

Unlike Self::module_infos, 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(&self) -> Result<Kernel, Report>

Get a Kernel 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 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 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 CodeBuilderLibrary for Package

fn as_code_builder_library(&self) -> &Package

impl CodeBuilderLibrary for Box<Package>

fn as_code_builder_library(&self) -> &Package

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 a sequence of bytes from the provided source, attempts to deserialize these bytes into Self, and returns the result.

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

Attempts to deserialize the provided bytes into Self and returns the result.

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) -> Package

Converts to this type from the input type.

impl From<Package> for AccountComponentCode

fn from(value: Package) -> AccountComponentCode

Converts to this type from the input type.

impl From<ProtocolLib> for Package

fn from(value: ProtocolLib) -> Package

Converts to this type from the input type.

impl From<StandardsLib> for Package

fn from(value: StandardsLib) -> Package

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<AccountComponentMetadata, <AccountComponentMetadata as TryFrom<&Package>>::Error>

Performs the conversion.