Miden Rust Project Structure

[partylikeits1983]

Opening this discussion to propose a consistent layout for a Miden-Rust workspace.

Below is a sketch of how a simple “counter” project could be organized. The repository would not include a frontend; a separate app can consume the compiled package artifacts for the note, account, and transaction scripts produced here. The structure is loosely inspired by how Foundry organizes a Solidity project.

Each subdirectory under accounts/, notes/, and tx-scripts/ is a standalone Rust crate (with its own Cargo.toml). The goal is to keep account, note, and transaction scrip logic modular and independently testable.

<project-name>/
├─ lib/ # Shared Rust libs + wit-deps (reusable across src/)
│  └─ <dep>/
│     └─ ... # e.g., shared note/account utilities in Rust
│
├─ src/ # Miden onchain code sources 
│  ├─ accounts/
│  │  └─ counter/
│  │     ├─ lib.rs # Main account logic in Rust
│  │     └─ bindings.rs
│  ├─ notes/
│  │  └─ counter_note/
│  │     ├─ lib.rs # Note script in Rust
│  │     └─ bindings.rs
│  └─ tx-scripts/
│     └─ counter_tx_script/
│        ├─ lib.rs # Tx script in Rust
│        └─ bindings.rs
│
├─ scripts/ # Rust client interaction(CLI tasks, deploy/invoke)
│  ├─ Cargo.toml
│  └─ src/
│     ├─ deploy.rs
│     └─ increment.rs
│
├─ tests/ # Tests
│  ├─ unit/ # Pure unit tests using `MockChain`
│  └─ integration/ # end-to-end tests using the Rust client
│     ├─ Cargo.toml
│     └─ src/
│        └─ counter_e2e.rs
│
├─ .miden/ # Tooling config: compiler version, profiles, fmt (not sure how this is defined in midenup)
├─ Cargo.toml # Workspace root (src/, script/, test/ as members)
├─ miden.toml # Project config (paths, profiles, tool versions)
└─ README.md

[bobbinth]

cc @Dominik1999 and @mmagician as this would also be relevant to how we set up projects for things like faucet, multisig etc.

[bobbinth]

Here is how I might organize it (very similar to @partylikeits1983's layout - though there are some small differences):

.
├── .miden
│   └── tooling config, client DB, profiles etc.
├── bin
│   └── # any binaries a project needs to run will go here (e.g., a front end server)
├── crates
│   └── # various off-chain crates will go here (i.e., off-chain business logic)
├── contracts
│   └── # account components, note and tx scripts will go here (each in a separate crate)
├── scripts
│   └── # deployment and other scripts could go here
├── tests
│   └── # integration tests will go here
├── miden-project.toml
├── Cargo.toml
└── README.md

[Dominik1999]

I think this layout makes sense. For sure, we need something similar for TypeScript or should we even have both in our "Project"?

Two minor points:

• Should we call Account components, note and tx scripts "Contracts"? Or simply "onchain code"?
• Does the Compiler need a folder? currently it has wit and wit-deps

[bitwalker]

Calling notes and tx scripts "contracts" seems odd to me, but you all would know better than I what terminology makes the most sense there. To my eye though, account components represent the real "contract", with notes facilitating specific functions of the contract, and tx scripts kind of also fitting into that latter bucket, but also functioning as a more general tool for custom behaviors. Anyway, just my two cents as someone who isn't carrying any baggage from other chains/protocols 😅

The compiler should be fine with the above - the WIT-related directory(ies) would belong to individual crates, rather than at the top-level.

Otherwise, the rest of this looks good to me. My only additional suggestion might be to add a deploy directory, that is essentially like scripts, but contains only deployment scripts and related things. The scripts directory would then be used for more general scripts. That would set the stage then for some of the miden-related commands proposed by @Keinberger, e.g.:

• miden script foo executes the script named foo in the scripts directory, i.e. scripts/foo.rs. We could still support a more explicit version as well, e.g. miden script foo.rs would execute a script named foo.rs in the current working directory; the bottom line is that it provides a more ergonomic form for common scripts used by a project.
• miden deploy --profile dev executes the deployment script for the named profile, e.g. in this example, it would execute deploy/dev.rs. We would naturally also pair up the "profile" here with configuration provided in miden-project.toml for the target network, etc. Our default project template would emit a barebones deployment script(s) for the networks available at the time (e.g. we might generate both test and release profiles that target testnet/mainnet respectively).

[bobbinth]

Should we call Account components, note and tx scripts "Contracts"? Or simply "onchain code"?

Calling notes and tx scripts "contracts" seems odd to me, but you all would know better than I what terminology makes the most sense there. To my eye though, account components represent the real "contract", with notes facilitating specific functions of the contract, and tx scripts kind of also fitting into that latter bucket, but also functioning as a more general tool for custom behaviors.

i went with "contracts" because it is a term we use in conversations when referring to any on-chain code. i think that applies well (though not ideally) to account components and nots, but not too well to tx scripts. But I also didn't want to put tx scripts into a separate directory. Overall, I'm fine with some other name - though, I'm not sure "onchain code" is better.

[Keinberger]

Hey all, just came out of a call with @partylikeits1983 about this, here's our thoughts.

We propose the following structure:

├── .miden # (miden-client config files, profiles, etc...)
├── lib # packages & wit files
│   ├── packages
│   └── wit
├── contracts # account components, note and tx scripts go here (each contract as individual crate)
├── scripts # deployment and other scripts
├── tests # all testing logic for contracts
├── Cargo.toml
├── README.md
└── .gitignore # ignores lib/packages from pushing to github

A few thoughts on this approach: We deliberately omitted a bin directory because most projects will likely house the frontend in a separate project, and not every project may need binaries—especially for developers just trying things out locally. The default template should be as lean as possible, similar to how Foundry approaches this. If needed, people can implement binaries themselves and structure them the way they want without default gatekeeping.

Similarly, we've excluded a crates directory for off-chain business logic. Although many projects may eventually need something like this, the same principle applies: the default template should remain lean and not impose unnecessary structure upfront.

Regarding the contracts directory, we're not proposing an opinionated sub-folder structure (like separate accounts/, notes/, tx-scripts/ directories). In reality, we now also have auth scripts, which would mean four subdirectories, making the template feel blown up and harder to navigate for newcomers. Every project may have different needs, and gatekeeping them into a default structure might not serve them well when they need to amend it. Other popular frameworks also avoid this level of prescription for the same reason.

Most importantly though, there's a need to get a project structure out as soon as possible to publish a Quick Start Guide for our developers.

Some aspects of the structure outlined above cannot be implemented yet (the .miden folder and packages/wit folder placement). That means to get something out immediately, the v1 will look slightly different:

├── wit # wit interface files
├── contracts # account components, note and tx scripts go here
├── scripts # deployment and other scripts
├── tests # all testing logic for contracts
├── Cargo.toml
└── README.md

Unfortunately, as of right now the miden client and its files live directly inside the root of the project, which is why we won't have a .miden directory for the first iteration. The compiled packages (.masp files) will remain inside of the target folder, which is less ideal but works for now given how the Rust compiler currently operates. The wit directory will be in the root.

For now, I think this is fine. I will work on refactoring the miden-client to 1) allow for a global config in a home directory and 2) allow for a local config inside a .miden directory instead of having the files scattered in root. Once that change is done, we can amend the project structure to provide a default .miden local config. We'll most likely have that merged in the coming days.

[Dominik1999]

That looks very good, thank you.

Some aspects of the structure outlined above cannot be implemented yet (the .miden folder and packages/wit folder placement).

Can you quickly explain the reason? Does it make sense to first enable this and then implement the better project structure? If not, it looks good to me.

Where does the package land that I compile in that structure? Ideally, I can somehow use it in the files in the scripts folder, right?

[bobbinth]

A few thoughts on this approach: We deliberately omitted a bin directory because most projects will likely house the frontend in a separate project, and not every project may need binaries—especially for developers just trying things out locally. The default template should be as lean as possible, similar to how Foundry approaches this. If needed, people can implement binaries themselves and structure them the way they want without default gatekeeping.

Yes, agreed - let's not make bin a part of the default template. I do think that for projects that require binaries we should recommend putting these into the bin directory (that's how we've done it for the faucet, and maybe for multisig as well?), but of course, it will be up to people to decide where they would go.

Similarly, we've excluded a crates directory for off-chain business logic. Although many projects may eventually need something like this, the same principle applies: the default template should remain lean and not impose unnecessary structure upfront.

Same thoughts as above: fine not to have as a part of default template, but whenever such crates are needed, we should recommend that they go into the crates directory.

A couple of additional comments:

• Why do we need to have the explicit lib directory? Wouldn't this be automatically managed by the workspace (I'm assuming this directory is for dependencies?)
• We probably need to have miden-project.toml file. This will be the file that defines dependencies, profiles, etc. - though, the exact format for it is still to be defined.

[Keinberger]

That looks very good, thank you.

Some aspects of the structure outlined above cannot be implemented yet (the .miden folder and packages/wit folder placement).

Can you quickly explain the reason? Does it make sense to first enable this and then implement the better project structure? If not, it looks good to me.

@Dominik1999

Well for the .miden directory the client CLI would need to be amended to not put all files in the root, but rather inside of this directory. As part of this change, a global home .miden directory would also be implemented.

Since this change will most likely only be available during next week, it will most likely not be part of the initial project structure directly. We can add it immediately after that change is merged into the miden-client though.

Where does the package land that I compile in that structure? Ideally, I can somehow use it in the files in the scripts folder, right?

Right now, it lands inside of the target root folder (which is a bit hidden). I talked to Denys and we are going to change up the location of the packages for the V1 already. The packages will live inside of contracts/target/.

[Keinberger]

@bobbinth Sounds good!

A couple of additional comments:

• Why do we need to have the explicit lib directory? Wouldn't this be automatically managed by the workspace (I'm assuming this directory is for dependencies?)
• We probably need to have miden-project.toml file. This will be the file that defines dependencies, profiles, etc. - though, the exact format for it is still to be defined.

I just came out of a discussion with Denys, and we'll rename the lib folder to just target. That way it is more clear that the folder holds artifacts.

Completely agree with you on the need for a miden-project.toml file! As part of V1, that won't exist (since it's still yet to be finalized), but in the V2 version this will definitely be there!

[Keinberger]

Hey again all,

I just came out of a call with @greenhat where we discussed the Rust project structure in more detail. Overall, we agreed on the structure I outlined above, but with some small modifications.

Most importantly, because of the pressing need to update the project structure for the Quick Start Guide, we'll have two iterations for the project structure.

Temporary iteration / V1

├── contracts # account components, note and tx scripts go here (each contract as individual crate)
│   ├── target/packages/ # Holds the .masp package files (contains a sub directory for both release and debug)
├── scripts # deployment and other scripts
├── tests # all testing logic for contracts
├── helpers # helper logic for working with `.masp` files for the `tests` and `scripts` directory
├── Cargo.toml
├── README.md # contains instructions on how to work in the workspace
└── .gitignore # ignores target from pushing to github

Key changes from previous proposal:

helpers directory added: We need this directory in order to practically use the .masp files from code inside of the scripts and tests folders. Without these utilities, the code would be incredibly blown up and barely usable without a deep dive. Since we cannot get those utilities merged into the Rust client quickly enough, we'll include a temporary helpers directory for now.

Artifacts placement changed: We've moved the compiled .masp files from the hidden root target folder to contracts/target/packages/. This standardizes the location and makes the output files 1) more obvious to developers who want to work with them and 2) more seamless to integrate inside of the scripts and tests directories.

miden new command needed: Each contract is its own individual crate. We need to standardize how to create crates for accounts, notes, tx scripts, and auth scripts. Theoretically we could add all four types to the base template and rely on people copying everything, but that would blow up the project environment unnecessarily.

Timeline: Mid next week

Note: In order for those changes to be implemented / work, we'll make an "emergency release" on the Rust compiler, so that the artifacts folder placement changes. Furthermore, this will allow developers to install cargo-miden normally, without having to specify the next branch.

Next iteration / V2

├── .miden # holds files for the Rust client
├── contracts # account components, note and tx scripts go here (each contract as individual crate)
│   ├── target/packages/ # Holds the .masp package files (contains a sub directory for both release and debug)
├── scripts # deployment and other scripts
├── tests # all testing logic for contracts
├── Cargo.toml
├── README.md # contains instructions on how to work within the workspace
├── miden-project.toml # Workspace configuration, profiles, etc...
└── .gitignore # ignores target from pushing to github

What changes from V1 to V2:

The V2 structure removes the temporary helpers directory and adds proper configuration files. However, this iteration depends on a few external changes that need to be completed first:

Profile configuration needs to be finalized before we can add the miden-project.toml file. This file will define workspace configuration and profiles, but the exact format is still being discussed.

Helper utilities currently in the temporary helpers folder need to be integrated directly into the Rust client. Once that's done, we can remove the helpers directory entirely since the functionality will be available through the client itself.

Rust client CLI support for local .miden folder needs to be implemented. This will prevent Rust client files from being scattered in the root of the project. More importantly, it will also allow developers to skip the manual client initialization step after instantiating a new project, making the setup experience smoother.

Timeline: Next few weeks

Let me know your thoughts!

[greenhat]

I made #737 for changing cargo miden new behavior to make the above Miden project (workspace).

[greenhat]

To iterate faster on the Miden project (workspace) structure I suggest we put it in a separate repo (miden-project-template?) and then cargo miden new <NAME> will copy it as is and put it in the folder NAME. This allows you to change the template independently of the compiler releases.

[Keinberger]

That sounds good for iteration purposes. We'll still need the release though so that people do not have to install the Miden compiler from the next branch though.

[greenhat]

I'm working on it. As soon as #735 and #722 are merged, I'd like to test the new release process. After I get it working, I'll make a compiler release including the updated command #737

[greenhat]

I would like to clarify the terminology. We're starting to use the term "Miden project", referring to the workspace we are discussing here, which consists of the contracts code and some off-chain code. Since we used the "Miden project" term for contracts up to this point I think we might add to the confusion. How do we want to call an individual Miden contract project, like counter-contract? It could be written in Rust or MASM. Since we're using "Miden project" for the whole workspace, how about "Miden contract"? Or "Rust Miden contract" and "MASM Miden contract" is we want to distinguish the env.
Alternatively, we can call this workspace "Miden workspace" analogous to the Rust world and keep calling the individual contracts "Miden project".

[bobbinth]

Good point! I don't have strong preferences either way - so, the two options are:

1. "Miden contract" for on-chain code (whether Rust or MASM) and "Miden project" for the whole thing (including of-chain crates, scripts, etc.).
2. "Miden project" for the on-chain code and "Miden workspace" for the whole thing.

Maybe I have a slight preference toward option 1 - but very very slight.

[greenhat]

I also have a slight preference toward option one, but OTOH, I think that calling it the "Miden workspace" may be more aligned with the Rust ecosystem, where almost every sufficiently complex project is a workspace. We need to be sure that introducing "Miden project" == "Cargo workspace" mental overhead is worth it.

[Keinberger]

Honestly I do not have a strong preference for either of the two naming schemes. Nevertheless, I think that using "Miden project" solely for a single contract could also be confusing to users. Usually, a project refers to a complete set of code, i.e. the whole thing. Because of that, going for option 1 leaves us with the least confusing naming scheme IMO.

[Keinberger]

FYI everyone, I created this repository for our template workspace / project: https://github.com/Keinberger/miden-project-environment

There is an open PR here to bind the "cargo miden new" command to instantiating a workspace with this github repository.

Reason for deviating from original approach:

In the last approach that I outlined - which I agreed upon with Alex and Denys - the scripts/ and tests/ folder would have been in the root of the repository.

Unfortunately having the tests and the scripts in the root does not really work. If having both in the root there are two options:

1. The Rust workspace would also be a Rust crate, nevertheless, this would create the problem of not being able to seamlessly add new scripts. Those would have to be declared as individual binaries inside of the Cargo.toml file, therefore this option is not viable.
2. The environment would be a pure virtual workspace, and both the tests and scripts folder would be individual crates. This would work, but since the tests would be an individual crate, the tests would actually inside of a nested tests folder, i.e. tests/tests from the root. This would be super weird. To add to that, the scripts itself would also sit more nested inside of scripts/src/bin. Therefore this option is also not viable.

That's why I opted to move both the scripts and the tests inside of an integration crate. This keeps the root more clean, and also makes it more clear where to work with our Rust client (integration), and where the contracts development happens (contracts). I pitched this to both Alex and Denys, all 3 of us agree that this approach is good.

[Keinberger]

One question: should we move https://github.com/Keinberger/miden-project-environment under 0xMiden org?

Good question, we can definitely do that if you want! @greenhat What do you think?

[greenhat]

Oh sure. I thought it was the plan to eventually move it under our org. It needs to be changed only at

compiler/tools/cargo-miden/src/commands/new_project.rs

Line 194 in f7c3b4e

git: Some("https://github.com/Keinberger/miden-project-environment".into()),

. Please don't hesitate to make a PR or ping me to make one after the move.

[bobbinth]

btw, we already have https://github.com/0xMiden/project-template - is this being used for anything? If not, should we just use this repo? (we can also rename it to miden-project-template.

@Keinberger - I made you an admin there.

[Keinberger]

Nice, I added the new template code there! I kept the repo name the same, I think it is good as is.

[Keinberger]

Created this PR to amend the template git repo URL in the compiler repo: #763