Early questions and suggestions

[tindzk]

I recently learned about Miden and like its long-term vision. Here are my early questions and suggestions:

• If the current folder is non-empty, it would be better to fail with an error:

  $ miden-client init --network testnet
  2025-10-25T12:08:01.534834Z  INFO miden_client_cli::commands::init: Template files successfully created in: "./templates"
  Config file successfully created at: /home/tim/dev/miden-client/miden-client.toml

  Other CLI programs such as cargo new behave as follows:

  $ cargo new .
      Creating binary (application) `miden-tests` package
  error: destination `/home/tim/miden-tests/.` already exists
  
  Use `cargo init` to initialize the directory

• Clarify the documentation that miden-client init creates files in the current folder. One might assume it creates the client in XDG_DATA_HOME or XDG_CONFIG_HOME.

• The configuration file references token_symbol_map.toml, but this file is not created. This line could be omitted or commented out.

• Explain the mutable account type here.

• miden-client new-wallet --mutable took 24s on a MacBook Pro M2 (Asahi). After “Database migrated to version 1”, no feedback on the current action is provided.

  $ miden-client new-wallet --mutable
  2025-10-25T12:16:14.952225Z  INFO rusqlite_migration: Database migrated to version 1
  Successfully created new wallet.

• The expected outputs are missing here (search for: You should see something like this:)

• I am getting an “Internal error” from the faucet

• “the note's details will be public”

  Which details of the note will be public? The recipient’s address, token amount, note tags etc.?

• “Do this periodically to keep informed about any updates on the node by running the sync command”

  Clarify what data gets synced and which operations it is needed for, e.g. is syncing required for sending notes?

• “Need a fresh start? All state is maintained in store.sqlite3, located in the directory defined in the miden-client.toml file.”

  It would be helpful to point out the implications. Before removing the state, is it possible to export all local notes and the accounts’ private keys, and then reinitialise the database?

• 50::<faucet-account-id>

  Why does the faucet’s account ID need to be specified? Is a UTXO model already implemented?

• Report an error if sender and target are equivalent:

  $ miden-client send --sender 0x10ba5d6783eb3990655b7a01077a7a --target 0x10ba5d6783eb3990655b7a01077a7a --asset 50::mtst1qzp4jgq9cy75wgp7c833ynr9f4cqqscqucc --note-type public
  Executing transaction...
  Error: cli::client_error
  
    × client error
    ├─▶ asset error
    ╰─▶ subtracting 50 from fungible asset amount 0 would underflow

• “To avoid state bloat, however, the client does not need to see the whole blockchain history, just the chain history intervals that are relevant to the user.”

  How is the chain history interval determined? Does this mean only the N most recent notes will be stored locally?

• SyncNotes allows filtering by note tags. Is it possible to only sync notes involving an account?

• What are note tags? The documentation mentions metadata, which I would interpret as a key-value dictionary. In the miden-node code, Vec<u32> is used. Are these u32 values predefined or can they be chosen arbitrarily?

• I am getting an error when syncing. Do I need to use a specific version with rpc.testnet.miden.io? If the testnet is not backwards-compatible, this could be mentioned in the documentation.

  $ miden-client sync
  2025-10-25T13:03:35.329007Z  INFO miden_client::rpc::tonic_client: Calling GetBlockHeaderByNumber: BlockHeaderByNumberRequest { block_num: Some(0), include_mmr_proof: Some(false) }
  Error: cli::client_error
  
    × client error
    ├─▶ rpc api error
    ├─▶ accept header validation failed: server rejected request - please check your version and
    │   network settings
    ╰─▶ server rejected request - please check your version and network settings

I'd be happy to contribute fixes for some of these issues.

[igamigo]

Thanks for taking the time to write this! The docs are being reworked alongside some of the UX, so I'm sure this will be helpful. Some notes and answers on some of your points:

If the current folder is non-empty, it would be better to fail with an error

Do you mean that init should fail if there are files in the target directory (currently, the cwd)? What would be the benefit of this?

Clarify the documentation that miden-client init creates files in the current folder

This is one of the specific points that is getting refactored soon, but currently this actually is specified in the commands reference. It's also mentioned in the CLI help (miden-client --help). It would probably help to mention it in tutorials to guide the user better though, but those will have to be reworked as part of the refactors anyway I'd imagine

The configuration file references token_symbol_map.toml, but this file is not created. This line could be omitted or commented out.

Yeah, I don't have a strong opinion here as I think it does help to have good defaults, but the file should probably be created to make it less confusing.

miden-client new-wallet --mutable took 24s on a MacBook Pro M2 (Asahi). After “Database migrated to version 1”, no feedback on the current action is provided.

That sounds strange. It takes ~1 second to initialize a new client and create a wallet on an M3 in my experience. There is some extra work that is performed (it might retrieve the genesis block if you don't have it, etc.) but it shouldn't take that long. If you can provide more context (what version, how you installed it, if you did it on a fresh new client, etc.) we can continue investigating this.

Which details of the note will be public? The recipient’s address, token amount, note tags etc.?

Basically all of them. Metadata (NoteMetadata) is always visible for any given note ID, but details (assets and recipient) are not put on-chain for private notes.

Why does the faucet’s account ID need to be specified? Is a UTXO model already implemented?

In Miden, fungible assets are identified by their faucet account ID and a specific amount. Read more about it here (and here for how notes and assets relate to the UTXO model).

SyncNotes allows filtering by note tags. Is it possible to only sync notes involving an account?

Are you referring to the SyncNotes RPC endpoint? If so, no, all endpoints match against note tags (see "Note discovery" on the docs), but these can express specific use cases. Some of the context on endpoints can be found in this discussion, and also docs for NoteTag should contain more details.
Communicating private note details that are targeted to specific accounts is currently being implemented (although not as part of the node's RPC spec); see #1229 for more details.

Report an error if sender and target are equivalent

Even though it's not precisely an error condition, I think we could do this, since there's probably not a lot of use-cases where you might want to do this other than experimenting or moving assets out of your account and into notes.

What are note tags? The documentation mentions metadata, which I would interpret as a key-value dictionary. In the miden-node code, Vec is used. Are these u32 values predefined or can they be chosen arbitrarily?

Where is the metadata mentioned? The link you pasted might not be the correct one. Again, the "Note discovery" doc article should help here. Also, not sure which miden-node code you are referencing.

I am getting an error when syncing. Do I need to use a specific version with rpc.testnet.miden.io? If the testnet is not backwards-compatible, this could be mentioned in the documentation.

Yes, that error occurs when you are using a non-matching RPC version, or if you have data related to another chain - basically, if your store's genesis block commitment does not match the network's. Currently only one version of the API is deployed on Testnet (0.11), so clients version 0.11.x should work here.

[tindzk]

Thanks for the detailed reply! It clarified many of the questions I had.

Do you mean that init should fail if there are files in the target directory (currently, the cwd)? What would be the benefit of this?

Yes. Before running the command, I assumed it would create a global client. I was in the client's source folder and had to read the log output carefully to find out which files were created and then remove them manually. A better UX would be to only create those files in a non-empty folder if the user explicitly sets a CLI parameter.

That sounds strange. It takes ~1 second to initialize a new client and create a wallet on an M3 in my experience. There is some extra work that is performed (it might retrieve the genesis block if you don't have it, etc.) but it shouldn't take that long. If you can provide more context (what version, how you installed it, if you did it on a fresh new client, etc.) we can continue investigating this.

I compiled the latest version from Git (commit d8f56fe).

I can reproduce the issue in a new folder by running miden-client init --network testnet; miden-client new-wallet --mutable. The issue appears to be related to excessive memory allocations which slow down execution due to swapping. When I ran strace, I noticed multiple sbrk() syscalls while the program appeared unresponsive.

On the first invocation, it took 19s. I had Firefox open, and htop showed 14 / 15.2 GB memory and 18.3 / 32 GB swap used.

After closing Firefox, I tried again and it only took 3s.

Is it possible to reduce peak memory usage? If not, mentioning the memory requirements and the expected runtime for this command would improve UX.

In Miden, fungible assets are identified by their faucet account ID and a specific amount. Read more about it here (and here for how notes and assets relate to the UTXO model).

Can the faucet's account ID be inferred? Specifying the faucet for every transfer seems redundant.

It might be helpful to add a clarifying sentence to the client tutorial, possibly including these links for reference.

Also, there is a discrepancy here: According to this page, a note can store 255 assets, but here it states 256.

Are you referring to the SyncNotes RPC endpoint? If so, no, all endpoints match against note tags (see "Note discovery" on the docs), but these can express specific use cases.

I see. This allows narrowing down notes to the prefixes of client accounts. The documentation could be clarified on how to obtain the tag value of an account, including whether the prefix is little- or big-endian.

If the node operator manages many accounts, using more than u32 should not significantly compromise security when fetching notes. In my view, prefixes should be arbitrarily long and the length configurable in the client. The user may want to increase the prefix to u64 and trade off anonymity for speed.

Where is the metadata mentioned? The link you pasted might not be the correct one. Again, the "Note discovery" doc article should help here. Also, not sure which miden-node code you are referencing.

Indeed. I meant this link. It might be helpful to expand the glossary explanation as "metadata" could be misunderstood.

As for miden-node, I was referring to rpc.proto which defines note_tags as Vec<u32>:

    // Specifies the tags which the requester is interested in.
    repeated fixed32 note_tags = 3;