Multi-Component Packages

[greenhat]

A high-level proposal for evolving the Miden package format (.masp) so a single package can carry multiple account components together with note scripts and transaction scripts in any configuration.

Motivation

Primary use case: one package shipping the app's account component(s) plus the note scripts and transaction scripts that interact with them. Secondary: one-file account creation in clients (auth + wallet + policy components described by a single package).

Today one package holds exactly one artifact, and the ecosystem visibly works around it:

• A package carries at most one ACCOUNT_COMPONENT_METADATA section, and AccountComponent::from_package maps one package to one component. Multi-component accounts require N files (miden-client new-account -p auth/basic-auth -p basic-wallet); auth components ship as separate packages in an auth/ subdirectory; the fungible-faucet package cannot carry the TokenPolicyManager component it needs, so the client injects it implicitly.
• miden-standards fakes bundling for scripts: all standard note/tx scripts are compiled into one big library package and extracted by path (NoteScript::from_library_reference), while account components ship as separate per-component .masp files. miden-agglayer repeats the same pattern.
• A note script referencing its account component works only across separate files, via manifest Dependency digests and a runtime dependency resolver.

Proposed model

Every package is a single MAST forest plus a set of one or more named parts describing what the forest contains. There is no separate "bundle" type; today's single-artifact package becomes the one-part degenerate case. (A package holds parts — the same container-of-parts vocabulary as the Open Packaging Conventions; "component" stays reserved for account components.)

Package {
    name: PackageId,
    version: Version,
    description: Option<String>,
    mast: Arc<MastForest>,      // ONE forest merged from all parts' code, with one merged advice map
    parts: Vec<PackagePart>,    // >= 1, unique names
    sections: Vec<Section>,     // package-level (debug info, source provenance)
}

PackagePart {
    name: PartName,             // unique within the package
    kind: TargetType,           // Library | AccountComponent | Note | TransactionScript | Executable | Kernel
    manifest: PartManifest,     // exports (procedures/constants/types) rooted in the shared forest, modules,
                                // dependencies (this part's external deps), optional entrypoint
    sections: Vec<Section>,     // part-level (account component metadata)
}

Validation rules:

• Part names are unique within a package.
• An Executable or Kernel part must be the only part in its package. Library-shaped kinds (Library, AccountComponent, Note, TransactionScript) combine freely in any configuration.
• A manifest entrypoint is only valid for Executable/Kernel parts. Note and transaction script parts keep identifying their entry procedure via the existing export attributes (@note_script, @transaction_script), which are unique per part — restoring the uniqueness that from_library wants and removing the need for path-based extraction workarounds.
• Package::kind() becomes a derived accessor (executable package iff its single part is executable); TargetType moves to the part level.

What moves where:

• The MAST forest is package-level: the assembler merges all parts' code into one forest with one merged advice map (MastForest::merge semantics — duplicate nodes dedup; advice-map entries are keyed by content digest, so overlaps are identical by construction). References between sibling parts dissolve into the merge and need no dependency records.
• Manifest moves into the part: each part's exports name its procedure roots inside the shared forest, with signatures and attributes as today.
• Dependencies are recorded per-part (in the part manifest): attribution — which external package a part's code references — must be captured at build time because it is not derivable later (external nodes carry procedure digests while Dependency.digest is a forest commitment; mapping one to the other requires fetching the dependency's manifest). With a single shared forest the package is the fetch/resolution unit, so Package::dependencies() (the derived, deduplicated union) drives fetching; the per-part records serve attribution, auditing, and tooling. A given PackageId must resolve to the same version/digest across the whole package (validated).
• Sections exist at both levels. ACCOUNT_COMPONENT_METADATA becomes part-level — each account component carries its own metadata section, resolving today's one-per-package restriction. Debug sections and PROJECT_SOURCE_PROVENANCE stay package-level: they describe the one forest and the project.

Identity, digests, addressing

• Package digest = the merged forest's commitment() — exactly today's package digest semantics; the content_digest analog additionally binds name/version/manifests/semantic sections as today.
• Part digest = the interface commitment over the part's exported procedure roots (the existing compute_nodes_commitment machinery, per part instead of per package). For account components this matches how AccountCode already commits to procedure roots.
• Addressing = package-id::part-name. Digests remain the cryptographic source of truth.
• Dependency gains an optional part qualifier: { name: PackageId, part: Option<PartName>, kind, version, digest }. Resolution always fetches the whole package (digest = the package digest); a part-qualified dependency can additionally bind the part's interface commitment for verification. The qualifier is optional because whole-package dependencies remain the common case (stdlib/protocol/kernel, wholesale library linking) and because part export sets may overlap (a component part selects a subtree of the lib part), so a plain module-path reference does not always attribute to a unique part — Some(part) is for dependencies that mean a specific part, e.g. FPI on an account component.

Producer: project assembler and miden-project.toml

Today the project model allows at most one [lib] target plus N [[bin]] targets, and the assembler emits one package per selected target. Proposed: miden-project.toml is the single authoring surface for the whole package, and per-kind tables ([[component]] for account components, [[note]], [[tx-script]]) declare parts in one of two flavors — carved out of the [lib] module tree by module path, or compiled 1:1 from a Rust crate referenced by its folder.

An (imaginary) hybrid workspace — the library and one account component written in MASM, everything else in Rust; each crate compiles to exactly one part, and parts are handed to the project assembler in memory (there is no on-disk part format):

[package]
name = "my-dapp"
version = "0.1.0"

[lib]
name = "helpers"
namespace = "my::dapp"
path = "masm/mod.masm"
deps = ["miden-core", "miden-protocol", "miden-standards"]

[[component]]
name = "auth"
path = "my::dapp::auth"
deps = ["miden-core", "miden-protocol", "miden-standards", "partner-dapp"]
# MASM part, carved from [lib] by module path; metadata authored inline:

[[component.storage.slots]]
name = "demo::single_value"
description = "single word slot"
type = "word"
default-value = "0x1"

[[component.storage.slots]]
name = "demo::statemap"
type = { key = "word", value = "word" }
default-values = [
    { key = "0x000000000000ed5d", value = "0x10" },
]

[[component]]
name = "wallet"
crate = "crates/wallet"
namespace = "my:dapp/wallet@0.1.0"
deps = ["miden-core", "miden-protocol", "miden-standards"]
# Rust part, compiled 1:1 from the crate; metadata comes from the crate's macros

[[note]]
name = "transfer"
crate = "crates/transfer-note"
namespace = "my:dapp/transfer@0.1.0"
deps = ["miden-core", "miden-protocol", "miden-standards", "wallet", "partner-dapp"]

[[tx-script]]
name = "admin"
crate = "crates/admin-tx"
namespace = "miden:base/transaction-script@1.0.0"
deps = ["miden-core", "miden-protocol", "miden-standards", "wallet", "transfer"]

[dependencies]
miden-core      = { linkage = "dynamic", version = "0.25" }
miden-protocol  = { linkage = "dynamic", version = "0.16" }
# whole-package dependency
miden-standards = { linkage = "dynamic", version = "0.16" }
# part-qualified dependency on another app's account component (e.g. for FPI)
partner-dapp    = { linkage = "dynamic", version = "1.0", part = "vault" }

• The whole project builds into one package: [lib] (if present) is assembled once, each crate part is compiled from its crate, and the project assembler merges all parts' code into the shared forest. Orchestration: cargo miden build → midenc → project assembler; pure-MASM projects go through the miden bundle CLI. Mixing MASM-carved and crate parts in one project is possible (eventually). Package name/version are stamped from [package] (also fixing today's hardcoded 0.0.0).
• Part metadata is authored in the part's native source: TOML properties for MASM parts, macro-derived from the Rust types for crate parts (as today) — either way it is serialized into the part's metadata section, so consumers see one uniform shape.
• A part declares everything it depends on by name in deps — sibling parts and external packages alike, the latter resolving to [dependencies] entries (which hold the coordinates: version, linkage). Sibling edges (e.g. a note using its account component) give the assembler the build order and dissolve at package level; external ones are what the built part's manifest records.
• Part namespaces are declared in (or derived from) this file, so name/namespace collisions are caught by validating the project manifest.
• [[bin]] targets are unchanged: each still produces its own single-part Executable package.
• [lib] alone, with no part tables, produces today's plain library package.

Consumers (high-level deltas)

Protocol (miden-protocol / miden-standards / miden-tx):

• AccountComponent::from_package(&pkg, part_name, &init) — the name is optional when the package has exactly one account-component part. AccountComponentCode wraps the shared forest plus the part's manifest and metadata instead of a whole package.
• NoteScript::from_package(&pkg, part_name) / TransactionScript::from_package(&pkg, part_name) select a script part and use its unique attributed export. from_library_reference-style digest stubs remain for lazy loading.
• Executor/prover package loading (insert_package and friends) registers the single package forest (and its merged advice map) in the MastForestStore — one insert per package.
• miden-standards and miden-agglayer build scripts collapse from "one bundled scripts library + N per-component files" to one multi-part package each — formalizing the bundle pattern they already hand-roll.

Client (CLI):

• new-account --package dapp.masp enumerates the account-component parts, selects auth via the per-part @auth_script attribute, and prompts per part schema; faucet and TokenPolicyManager finally ship together. A part filter flag covers partial use.
• call procedure lookup gains an optional part qualifier.

Compiler (midenc / cargo-miden) — besides driving production (above), it consumes multi-part packages as dependencies:

• Dependency intake. Dependency packages enter compilation through the package registry (compiler-side HybridPackageRegistry → VM project resolver). A registered package now contributes all of its parts; a project dependency may reference the whole package or a single part, and dependency entries in miden-project.toml (and cargo metadata) gain the part-qualified package-id::part-name form.
• Linking. Dynamic linking resolves calls against the target part's manifest (export paths, digests, signatures) and records a part-qualified Dependency; static linking copies the referenced procedures from the dependency's shared forest. The implied link libraries (miden-core, miden-protocol) are unaffected until they themselves become multi-part.
• FPI / source-level bindings. #[account(package::Interface)] wrappers become #[account(package::Component)] assuming the component has exactly one interface that has the same name as the component. We probably can enforce Component name = interface name everywhere.

Registry / package manager:

• PackageId stays the distribution and version-resolution unit; part-qualified lookups (package-id::part-name) resolve inside the fetched package. Whole-package resolution uses the derived dependency union. Resolver logic is otherwise unchanged.

@bitwalker @mooori @bobbinth @PhilippGackstatter @igamigo

[bobbinth]

Thank you for writing this up! One preliminary comment:

My original thinking was that keep account components / notes / tx scripts as separate tables rather than putting everything under component table. I've imagined it something like this:

[package]
name = "miden-standards"
version = "0.1.0"

[lib]
name = "standards"
namespace = "miden::standards"
path = "mod.masm"

[[component]]
name = "basic_wallet"
path = "miden::standards::wallets::basic"

[[component]]
name = "singlesig"
path = "miden::standards::auth::singlesig"

[[note]]
name = "p2id"
path = "miden::standards::notes::p2id"

This would output 4 packages:

• 1 library package.
• 2 account component packages which would depend on the library. The dependency would be dynamic - though, we could probably add options to make it static.
• 1 note package - also with dynamic dependency on the library.

Also, the above example is pretty "truncated" - for each component/note etc. we'd have additional properties containing component's metadata (e.g., storage layout).

What's the motivation for putting every artifact under "component" table? One of the hesitations I have is that it may be confusing to call notes/tx scripts etc. "components" as it is already a pretty overloaded term.

[greenhat]

Thank you for writing this up! One preliminary comment:

My original thinking was that keep account components / notes / tx scripts as separate tables rather than putting everything under component table. I've imagined it something like this:

[package]
name = "my-dapp"
version = "0.1.0"

[lib]
name = "standards"
namespace = "miden::standards"
path = "mod.masm"

[[component]]
name = "basic_wallet"
path = "miden::standards::wallets::basic"

[[component]]
name = "singlesig"
path = "miden::standards::auth::singlesig"

[[note]]
name = "p2id"
path = "miden::standards::notes::p2id"

This would output 4 packages:

My goal for this redesign was to produce one package for this case instead of 4. I misunderstood the idea. I thought that we wanted everything defined (account components, note scripts, tx script, etc.) to end up in one package.

• 1 library package.
• 2 account component packages which would depend on the library. The dependency would be dynamic - though, we could probably add options to make it static.
• 1 note package - also with dynamic dependency on the library.

I see that it is in line with our existing model of producing a .masp package for every project. The difference is that we want to describe a set of projects (workspace?) in one miden-project.toml file instead of per project. Sounds right?

The hybrid approach could be placing all account components in one .masp file. So this would produce:

• 1 library package.
• 1 account components package which would depend on the library.
• 1 note package - also with dynamic dependency on the library.

Is this something we want to pursue?

Also, the above example is pretty "truncated" - for each component/note etc. we'd have additional properties containing component's metadata (e.g., storage layout).

What's the motivation for putting every artifact under "component" table? One of the hesitations I have is that it may be confusing to call notes/tx scripts etc. "components" as it is already a pretty overloaded term.

I agree, the "component" term is already pretty loaded. Using it here as "any project type that can be included in the package" is too much.

[bobbinth]

I see that it is in line with our existing model of producing a .masp package for every project. The difference is that we want to describe a set of projects (workspace?) in one miden-project.toml file instead of per project. Sounds right?

The hybrid approach could be placing all account components in one .masp file. So this would produce:

• 1 library package.
• 1 account components package which would depend on the library.
• 1 note package - also with dynamic dependency on the library.

Yes, this could be interesting as well - but I don't have a formed opinion yet. Curious what @bitwalker and others think.

[greenhat]

Following up on our call, I will:

1. Pick a better term for the package item to avoid calling it a "component".
2. Redesign the package to have one MAST forest merged from all included items and merged advice map.
3. Adopt the toml scheme from the Multi-Component Packages #1290 (comment) comment

[greenhat]

@bitwalker @bobbinth I updated the discussion.

What's changed:

1. I want to try the term "package part"; let me know if you prefer any other (I have "item" in reserve);
2. The package has one MAST forest and one advice map;
3. The miden-project.toml format switched to the one suggested in Multi-Component Packages #1290 (comment) and the example describes an imaginary hybrid workspace with mixed Rust and MASM parts.

Open questions:

1. Changing the code of one part (say, the tx script) forces a new version and a new digest of the whole package. How would we handle the upgrades of the deployed code? Upgrade everything even though only the tx script was changed?
2. The package part identity is weakened (no digest for the package part). Is that okay? Or do we need to come up with a substitution?

[greenhat]

When I think of the one (merged) MAST forest in the package as a code blob. Then I can think of the metadata for each package part as a "view" into this code blob (a subset of the exported procedures). So the term "view" might be a good fit too.