AccountId as unique account identifier (externally and internally)

[Dominik1999]

Canonical Identifier Requirement

For both UX and DevEx reasons, Miden must provide a single canonical identifier for accounts.

• UX perspective: Users must be able to unambiguously recognize their account across explorers, wallets, and applications. Especially once real assets are at stake, it should never be unclear whether a given account belongs to a user.

• DevEx perspective: Developers need to uniquely reference accounts when interacting with smart contracts, querying nodes, or passing account information between wallets and applications (e.g., via adapters).

Therefore, Miden requires one canonical identifier per account. This identifier could be either the AccountID or a canonical Address.

Current Role of Address

In miden-base v0.11, the concept of an Address was introduced. An account may expose multiple addresses, with two primary goals:

1. Private note encryption — by encoding the tuple (AccountID, PublicKey), the sender can determine how the recipient wants private notes encrypted.

2. Private account interfaces — by including interface information, an Address should prevent notes from becoming stale when targeted at private accounts.

However, in practice:

Goal (2) is only partially met. An Address does not encode the interface signature, only its identity. This means a sender cannot construct notes for an entirely unknown interface—only for interfaces that are either public in miden-stdlib or shared through an external library.

As a result, Address is primarily useful for private wallets exposing the basic wallet interface, enabling receipt of P2ID or P2IDE notes.

For other private accounts with custom interfaces, notes are typically pre-constructed in the frontend (e.g., using a TransactionRequest), not derived directly from an Address.

Proposed Direction

If the main utility of Address is to enable encrypted P2ID notes for private wallets, then the canonical identifier across all developer and user interfaces should revert to the AccountID.

This restores a single, universal identifier for accounts, ensuring consistency across wallets, nodes, and applications.

The Address can still be used as an auxiliary identifier, but communicated through separate channels (e.g., QR codes, wallet-to-wallet communication) when private wallets wish to receive encrypted notes.

In short:

• Canonical identifier: AccountID (used everywhere for UX/DevEx consistency).
• Auxiliary identifier: Address (used only for private wallets requiring P2ID encryption).

[mmagician]

The Address can still be used as an auxiliary identifier, but communicated through separate channels (e.g., QR codes, wallet-to-wallet communication) when private wallets wish to receive encrypted notes.

This should still be well supported from the wallet. For example, a "Receive" interface could expose a dropdown for how they user wants to receive notes (Address::AccountId; Address::Burner; Address::PaymentRequest).

[Mirko-von-Leipzig]

Especially once real assets are at stake, it should never be unclear whether a given account belongs to a user.

My understanding was that while a user should recognize their own account(s)/interfaces, one doesn't want others to recognize it unless its a public account. So addresses should not be traceable to a specific account in general, but rather it could be chosen by the interface/address whether this is possible?

[Mirko-von-Leipzig]

it is a private account, it can be traceable, but external observers would not see the contents. However, the owner of the private account would see that the account state root changed.

But then we're leaking metadata i.e. who's sending things to whom or no?

[Dominik1999]

Not how I understand it. So here is a private account (https://testnet.midenscan.com/account/mtst1qqz3jveu8urgryq9zdj0f827qpcqqd5vadt). Everyone can see that there are account updates, but external people don't know what those updates were about.

So the chain always needs track and verify state root updates for every account.

[Mirko-von-Leipzig]

So the chain always needs track and verify state root updates for every account.

Agreed; but it shouldn't be possible to track the account's interfaces/addresses unless they're designed to be public.

[Dominik1999]

You mean there should be no mapping from Address -> AccountID?

[Mirko-von-Leipzig]

Yes; or at least no public one unless that's the intended effect of the Address

[igamigo]

This restores a single, universal identifier for accounts, ensuring consistency across wallets, nodes, and applications.

The Address can still be used as an auxiliary identifier, but communicated through separate channels (e.g., QR codes, wallet-to-wallet communication) when private wallets wish to receive encrypted notes.

Isn't this already the case? AccountId is the actual universal identifier whereas the address encodes some subset of data from an account, for various purposes.

From my experience by addressing feedback from users, the change of meaning of the Address struct between 0.10 and 0.11 has definitely been very confusing. However, I'm not sure if this is a design problem more than it is a documentation and expectation problem. Users expect "address" == "identity". It likely hasn’t helped that this was also true prior to 0.11, and that the only variant available today is tied to an account ID, with current guidance suggesting using an unspecified account interface to avoid ambiguity.
So I wonder if some of this confusion can be partially avoided by documenting this more, or even changing the Address struct name. For docs, explicitly saying "account ID" == "identity" and "address" == "addressability" and a "when to use" table would be nice. For naming, even though it does feel appropriate, but maybe something like SendAddress/RouteAddress is better.
Additionally I think the fact that the address looks more human-readable also makes it the preferred solution for displaying an account's identifier. Could this be mitigated a bit by having more specific address prefixes? Or encoding the account ID as a bech32 string in a way that's more easily identifiable as well.

[bobbinth]

In miden-base v0.11, the concept of an Address was introduced. An account may expose multiple addresses, with two primary goals:

1. Private note encryption — by encoding the tuple (AccountID, PublicKey), the sender can determine how the recipient wants private notes encrypted.
2. Private account interfaces — by including interface information, an Address should prevent notes from becoming stale when targeted at private accounts.

I think this doesn't fully describe the purpose of the Address. The main purpose is for the recipient to communicate to the sender all the information needed for the sender to send payments to the recipient. The simple way to think about this is: if I want to share a QR code with someone for them to send me a payment, what will this QR code include. This consists of several things:

• The identity of the recipient - e.g., account ID right now, public key and maybe other things in the future.
• "Interface" of the recipient - to specify what kind of notes the recipient can accept (right now, basic wallet is the only option).
• Discovery info - specifically, info about how to build the tag for the notes so that the recipient can find the notes.
• Encryption - info about how the sender should encrypt the note (if the recipient wants the notes to encrypted).
• Maybe more things in the future.

If the recipient does not communicate this info to the sender, the sender cannot reliably create a note that the recipient will be able to find and consume. For example, if the sender uses 16 bits of account ID to build a note tag, but the recipient expects 14 bits, the recipient won't find the note.

In short:

• Canonical identifier: AccountID (used everywhere for UX/DevEx consistency).
• Auxiliary identifier: Address (used only for private wallets requiring P2ID encryption).

To clarify: Address is not an account identifier. It is the means for sender and recipient to exchange info about how the sender should send stuff to the recipient. In theory, the same address could be shared by many accounts (this would require public key based addresses).

So, the only real identifier of an account is AccountId, and that's what should be used almost everywhere except for specific use cases where addresses are needed.

These specific use cases all revolve around wallets. Specifically, from the end-user perspective, they don't usually care about account IDs. Here, I'm thinking about the following user flows:

1. I want someone to send me assets (e.g., a faucet or another user): I'll share my address with them.
2. I want to interact with some app and my wallet tracks more than one account. Here, I'll need to select an account to use. This could be done using an address, but a better approach may be to use a human-readable name.
3. I want to look up my transaction history on the block explorer. Since the block explorer may not be aware of my address, we have a couple options:
   a. Try to search by address. In cases when the block explorer can resolve the address to account ID, nothing else is needed. This could be pretty user-friendly (e.g., the block explore could make it clear that the address belongs to the found account's ID).
   b. In cases when an address cannot be resolved to an account ID (e.g., with public key based addresses in the future), the block explorer could communicate this to the user, and ask the user to provide account ID.

Since we don't have public key addresses yet, case 3b is not something we need to worry about for now. So, all flows I can think of should be covered by making the address the thing that the end user sees in the wallet.

Though, it is possible that I'm missing some flows here.

[PhilippGackstatter]

Iiuc, we want an identifier and also the ability to address it by providing additional info like note tag length and the underlying account interface. So far we have treated these as separate concepts, but perhaps we can integrate them into a single construct. We could try to do this by making the info completely optional. So for AccountIdAddress in Rust terms this would be (naively):

pub struct AccountIdAddress {
    id: AccountId,
    tag_len: Option<u8>,
    interface: Option<AddressInterface>,
}

When encoded, it would look something like this (it's one of many potential approaches):

• mtst1qzp4jgq9cy75wgp7c833ynr9f4 (Account ID)
• mtst1qzp4jgq9cy75wgp7c833ynr9f4#cqqscqucc (Account ID + BasicWallet Info = an address)
• mtst1qzp4jgq9cy75wgp7c833ynr9f4#fq54fbdfa (Account ID + WalletPlus Info = another address)

By default, a wallet would display an address, i.e. the account ID with the optional data, but it would always be safe to strip away everything after and including the # to get the account ID. If that account ID is actually a public key, then searching for it in the explorer would simply point out that a public key cannot be resolved to an account. In particular, it would also allow the explorer to encode every account ID into an address without needing AddressInterface::Unspecified or anything like that.

This approach would more clearly highlight to developers that an account ID or address has two parts to it, one of which is "stable", the other isn't. Users would most likely just copy whatever the wallet displays anyway, and when searching for it in the explorer, it can highlight the part of the address that matches the account ID. Is it as good as a single, unique, stable identifier? Probably not, but it seems a bit better than the current situation.

This would probably also have an impact on how we name things. It doesn't really make sense to refer to an account ID without the info as an address because it's just an account ID, though we could treat it as a valid address on the implementation level. I haven't come up with a good scheme for this, but I'm sure it's solvable if we go in that direction.

Side note

• This would also allow us to get rid of AddressInterface::Unspecified.
• The above examplees are not valid bech32, so we'd have to come up with our own mechanism for checksumming this correctly, but that's a technical problem we could solve.
• I like the # visually, but there may be better choices so that double-clicking the address selects everything, but that is also a secondary concern. Edit: We'd probably want a URL-safe character for this.

[PhilippGackstatter]

Making a large number of fields optional may lead to too many combinations. For account ID address, we probably care about the following options:

Completely agree, and that's actually what I meant. I should've reflected that in the Rust snippet.

If this is the direction we want to take, we could look a bit more into what alternatives there are to hex and bech32 encoding, but from a quick research it looks like most blockchain address encodings are base32-based. In those, underscore and 1 and some other characters excluded from the base32 set are the only options for the address to still be considered a single word. I think _ is the better choice if we want to make the distinction more visually obvious. Technically, even our current bech32 address encoding shares the same prefix with other addresses that contain the same account ID. That's why I picked #, but as mentioned, it's not an overall good choice.

One of the drawbacks here, as you mentioned, is that we are no longer using standard bech32 encoding - and so, we'll need to develop our own. Not super complicated, but would still require some careful consideration.

Yes, I think primarily the difference would be that we'd have to make some decisions:

• Do we want to checksum only the prefix part of the address, i.e. account ID, public key, etc. or also the tag length? I think we'd want to checksum everything.
• This would imply that we need either:
  • one checksum that can be validated with the address info part missing,
  • or two checksums where the first validates the "prefix" and the second validates the address info.

But I guess these are technical questions we can figure out once we have agreed on that direction.

[Dominik1999]

Thank you @PhilippGackstatter, this is a really good idea.

I’m in favor of keeping the canonical identifier as a plain bech32-encoded AccountID (e.g., HRP mt), and adding optional context after a # separator (or any other separator to make it clickable, however, can you also only make the first part clickable?) The base bech32 string stays the single source of truth for UX/DevEx (checksummed, lowercase, stable).

We could even encode optional hints URI-style key=value pairs, comma-separated, e.g.:

mtd1qq...xyz#pk=rpo_falcon512:ak1qq...abc,if=wallet-basic

whereas

pk = algorithm + (bech32m) key or key hash

if = interface identifier (+ optional version)

All #… fields are non-canonical and safe to strip—great for QR/“share address” flows without polluting the core ID. For privacy, wallets can rotate pk or use key handles so scanning a QR doesn’t create durable linkability.

We’ll document HRPs, length limits, and an ABNF so parsers are interoperable. Later, if we want richer “payment request” links, we can define a miden: URI that embeds this base ID, similar to EIP-681, without changing the canonical identifier.

[bobbinth]

I think URL-based approach could be very interesting - it does make things much more explicit. The main drawback is that it is going to be quite a bit longer - but maybe that's not a big deal. We could even use the standard URL format - e.g., something like:

mm1qzp4jgq9cy75wgp7c833ynr9f4?i=basic_wallet&tl=14&pk=0x13456...798

The format is basically:

<identifier>?key1=value1&key2=value2

If we go this route, do we still need to encode the identifier in bech32? Also, we should probably design it so that in the future, when we have public-key-based identifiers, the identifier part looks sufficiently visually different from the account-id-based identifier.

[PhilippGackstatter]

Thanks for the pointer to EIP681 @Dominik1999 (link for reference: https://eips.ethereum.org/EIPS/eip-681). I think that direction may get us two things for the price of one, namely a miden URI scheme for standardization and a solution to the issues we've had with addresses.

We could even use the standard URL format:

If we do want a URL then I think we need to define a scheme to follow the standard. Standardizing such a scheme (e.g. miden:) would already set us up for interoperability similar to the EIP mentioned above or the bitcoin: scheme and at the same time solve the address issues.

So I think it would look something like:

miden:mm1qzp4jgq9cy75wgp7c833ynr9f4?i=basic_wallet&tl=14&pk=0x13456...798

That is what would go into a QR code, such that when scanned, the operating system would invoke the app registered for the miden: scheme and open a wallet.

I'm not sure if that itself already directly needs to be the encoding of an Address. If we want to extend miden: to something else in the future (see below) this may be limiting. So I wonder if the "address information" itself should just be a data format that can be easily encoded into a miden: URI, which would be separate functionality. So, the address could implement serialization to JSON or some other format, and then it can be encoded into an URI at the place where it's needed (generating a QR code, "show address" button in the wallet). This data format could be something like:

{
    "address": {
        "type": "AccountId", // For extensibility
        "value": "mm1qzp4jgq9cy75wgp7c833ynr9f4"
    },
    "tag_length": 14,
    "interface": "BasicWallet",
    "encryption_key": "0x1234567890..." // Simplified
}

This would then only be something that developers see. What users see would be this information encoded into a miden: URI. (Also only if they manually want to input their address into, say, the faucet web page, as this could also be done automatically by the wallet adapter). Whenever the Miden context is clear, we may also be able to omit the miden: scheme, such as in the faucet web page, similar to how http: is often omitted for web addresses.

So my main point is that I think there is a difference between a miden URL and an address encoding. E.g. we may want to be able to encode different things behind miden:, e.g.:

• a plain address, that just specifies an account ID plus some additional info, e.g. interface, ...
• a payment request (Introduce Payment/Invoice struct #1727), that additionally includes requested amount and currency.
• other things in the future

On the code level, we could define both Address and functionality to encode it into a URL in miden-standards (tbd). That way, future extensions to miden: would naturally go into miden-standards as well.

If we go this route, do we still need to encode the identifier in bech32?

This route would mean we go back to account IDs shown in wallets or in the explorer, so I think bech32 still has some benefits there over hex encoding (visually distinct from, say, a transaction ID, mm prefixing, checksumming) so I'd bring it back for AccountIds.

[PhilippGackstatter]

miden:mm1qzp4jgq9cy75wgp7c833ynr9f4?i=basic_wallet&tl=14&pk=0x13456...798

Thinking about it again, I think this exact structure may not really make sense, because there is no implied action here. Or in other words, what would a miden: handler do when invoked with that? In a realistic example, say, for payment requests, this would probably have to look something like miden:requestPayment?address=mm1.... But the address itself is not a meaningful action, so miden:mm1... doesn't make sense.

So I guess something more along the lines of what @Dominik1999 proposed makes sense, i.e. our own format that is not a URI with key-value support.

In that case, there are two overall approaches: Making the key-values visually inspectable or not.

Not Inspectable

This would be something like the original proposal (possibly even without the #):

mtst1qzp4jgq9cy75wgp7c833ynr9f4#cqqscqucc

Inspectable

A sub-question here is whether key-value is useful or if just values are good enough, i.e. key-value vs order-based.

One reason in favor of key-values is that it'd be easier to make data optional compared to if it has to follow an order. In any case, we could pick some url safe characters to deliminate this, using . and _ it'd be:

# Order-based
mm1qzp4jgq9cy75wgp7c833ynr9f4.BasicWallet.14.0x13456798
# Key-value-based
mm1qzp4jgq9cy75wgp7c833ynr9f4.if_BasicWallet.tag_14.pk_0x13456798

Though, using reserved characters may be nicer, e.g. ?if=BasicWallet&tag=14 (and could be percent-encoded in URIs).

Conclusion

I guess the main question between the inspectable and non-inspectable option is whether there is a major benefit for making the address data easily readable. One benefit of the inspectable option is that it might be much clearer to developers and end-users that stripping that data doesn't change the actual identifier (the account ID).