Addresses - defining the standard

[rem.codes]

I want to open up the conversation regarding account identifiers, principals, subaccounts and IcrcAccounts.

While talking with different ecosystem developers and users it’s appears that user controlled subaccounts are being integrated more and more by dapp developers, it seems that there is still a lot of confusion about the different “address types”.

Note that all data below is derived from the same data and all helper methods used can be found in different dfinity packages.

Principal

• widely adoptoped within the IC ecosystem
• does not support subaccounts
• recognizable format

import { Principal } from '@dfinity/principal';

const principal = Principal.fromText('wdarh-5xeo6-tbqmc-qmrpr-a5ppj-z4jbc-pprwe-gusfk-5qiaa-ocvfb-iqe');

// returns "wdarh-5xeo6-tbqmc-qmrpr-a5ppj-z4jbc-pprwe-gusfk-5qiaa-ocvfb-iqe"
const principalAsText = principal.toText();

//return "E477A6183050645F1075EF4E789089EF8D886A48AAEC10003855285102"
const principalAsHex = principal.toHex();

I don’t think principal.toHex() is actually used by developers but it does provide a valid hex that can be used which is the reason i added it.

AccountIdentifier

• added privacy
• not supported by most ICRC supported ledgers
• mainly used for transactions between the IC and centralized exchanges
• once converted it can’t be converted back (due to SHA-224)

import { AccountIdentifier, SubAccount } from '@dfinity/ledger-icp';
import { hexStringToUint8Array } from '@dfinity/utils';

const accountIdentifier = AccountIdentifier.fromPrincipal({ principal });

// returns "12f6a1ca374f7271ed2cc77470e5a7b1a649a21436367f898fbb639b3b12b21f"
const accountIdentifierhex = accountIdentifier.toHex()

const subaccount = SubAccount.fromBytes(hexStringToUint8Array(accountIdentifierhex)

// return "60cc844386ad1bd6747a7c024b63fbd610187e7d0910333863057410aefa4c1c"
const accountIdentifierWithSubaccount = AccountIdentifier.fromPrincipal({ principal, subaccount })

ICRCAccount

• widely supported within the ic ecosystem
• recognizable format
• supports subaccounts
• allows encoding and decoding to get the principal and subaccount

import { decodeIcrcAccount, encodeIcrcAccount } from '@dfinity/ledger-icrc';
import { principalToSubAccount } from '@dfinity/utils';

// returns "wdarh-5xeo6-tbqmc-qmrpr-a5ppj-z4jbc-pprwe-gusfk-5qiaa-ocvfb-iqe"
const icrcAccount = encodeIcrcAccount({ owner: principal });

// returns "wdarh-5xeo6-tbqmc-qmrpr-a5ppj-z4jbc-pprwe-gusfk-5qiaa-ocvfb-iqe-fwv5aqy.1de477a6183050645f1075ef4e789089ef8d886a48aaec100038552851020000"
const icrcAccountWithSubaccount = encodeIcrcAccount({ owner: principal, subaccount: principalToSubAccount(principal)})

If you want to read more about icrc account textual encode

I’m personally a fan of the ICRC account (textual encoding) because;

• a principal is also a valid ICRC account (without a subaccount)
• it allows the user to copy-paste the address only one time instead of a separate principal and subaccount
• it remain somewhat recognizable to the user.

For convenience we support the traditional and ICRC method on toolkit, but ideally we would remove manual in favor of ICRC accounts but this requires a widely adopted standard.

An other thing that i think could cause confusion and adoption problems is the naming, should it be called an icrcAccount which the user need to learn do a deep dive into what it is?

[marc0olo]

Hey @rem.codes,

thanks for sharing your thoughts. I am actually not sure if a “standard” is needed or do you consider the icrcAccount already as a standard that could benefit from a more generalized naming (independent of ICRC-1) ?

When looking at your screenshots, I have following comments and questions:

• If ICRC1 for transferring ICP is selected, I think the input label you currently show is totally fine (both, principal and icrcAccount are valid icrcAccounts )
• The behavior of Switch to Manual Account is not immediately clear to me. Is your intention here currently to allow the user to provide the principal and subaccount manually while doing the text encoding in the background?

So you are currently trying to avoid using the AccountIdentifier completely, right? As far as I have noticed, this is only supported by dapps and wallets to allow transfers from/to exchanges. If your the toolkit does not need to support that, this seems fine to me.

I think one thing to note is definitely that an icrcAccount that uses a principal without a subaccount, always results in the exact same textual representation as the principal.

I think it would be great to have simple web tooling UI available that allows to encode/decode icrcAccounts. Has anybody maybe created such tool already? That could also include some explainers.

[rem.codes]

@marc0olo

I am actually not sure if a “standard”

I get the confusion, i was more referring to “the standard to use by dapps” for providing addresses, If a dapp only allows principals an icrc1 account (with subaccount) would not work, but if they support icrc1 accounts a principal would work. how could we make this clear to the user in a “standard” way?

@marc0olo

The behavior of Switch to Manual Account is not immediately clear to me.

yes this is something i want to remove eventually but for now it’s there to;

• take away any uncertainty for the technical end user and
• know what to expect for those who are not familiar with icrc1 accounts and their encodings.

But if you would fill in the principal + subaccount it automatically gets converted to the icrc1 textual encoding and vice versa which goes into

@marc0olo

I think it would be great to have simple web tooling UI available that allows to encode/decode icrcAccounts. Has anybody maybe created such tool already? That could also include some explainers.

[marc0olo]

@rem.codes

@marc0olo

I am actually not sure if a “standard”

I get the confusion, i was more referring to “the standard to use by dapps” for providing addresses, If a dapp only allows principals an icrc1 account (with subaccount) would not work, but if they support icrc1 accounts a principal would work. how could we make this clear to the user in a “standard” way?

alright. I just checked OISY for this. depending on where the user clicks in the UI, there are following terms being used:

• Wallet address (probably a principal OR an icrcAccount without a subaccount)
• Your Addresses:
  • ICP Principal (seems fine as OISY does not use subaccounts here)
  • ICP Account (for exchanges, the AccountIdentifier mentioned above)

For sending tokens, OISY asks to enter the Wallet address of the recipient. I assume that for ICRC-1 compliant tokens, any icrcAccount could be used, right? @StefanBerger-DFINIT1

It is certainly a confusing topic

An alignment on how to deal with all of these identifiers in dapps would definitely be great.

[Snassy-icp]

Hi @rem.codes !

I think this comes down to the fact that the long account strings can’t really be typed in by a user who has just a principal and a subaccount, since there is a checksum in there.

It follows that for users who have a principal and a subaccount, there needs to be UX affordance to enter those, and receive the long account string with the checksum in return.

My view on this is that to start with there should be a “Recipient” box that allows the user to enter just a principal or a long account string.

Then, in a similar fashion to how a date picking calendar component might show up when editing a date value, the user could open an ICRC Account picker component to help them enter the ICRC Account.

The Account picker component may let you enter the principal in one box, and the subaccount using a different set of controls, depending on how the user wants to enter it. It can be a textbox taking a hex string. It can be a list of dropdowns for byte values. It can be a simple number. It can be a text field that is turned into bytes. It can even be another principal that gets converted to a subaccount (a common use case).

The reason is that the user may have gotten a subaccount to use in any of several formats - or they may even just have been given a method for concocting a subaccount (take the first five bytes of your principal, add this salt, hash it, add an index…).

For example, one scenario I have seen is that a user has a principal and a hex string for a subaccount. As we have observed, the user can’t just paste the hex string to the end of the principal to create a “long account string”. So the user needs a little tool where they can enter the values they have, the principal and the suubaccount, and get out a long account string that they can then use in the Recipients box.

Or they may have been told to send tokens to some canister principal id and to a subaccount generated from their own wallet principal. Again, the little tool would let them paste the canister id in one box, their own wallet principal in another (subaccount) box, and then click a button to generate and fill out the long account string in the Recipient box.

Yes, normally all this would be done under the hood for the user, it is mostly dapps that send tokens to each other using subaccounts. But not only. After a couple years on the Internet Computer I have seen enough situations where an ICRC! Account picker component could have come in handy.

The big question, to my mind, is what to call this “long account address with the checksum” format, so it becomes easier to reason and talk about. I recently ran a Twitter pool where users voted for calling these long account strings with principal, checksum, and subaccount “Extended Addresses,” which I quite like.

Note that this ICRC1 Account picker doesn’t have to be built into wallets, as long as there is a standard for the Extended Address format. The picker could be a standalone tool (and I am somewhat inclined to build one) but of course for most dapps it would be very handy to have such a component in the wallet, openable by a little button next to the Recipient box.

In my view we don’t need a standard for the Extended Address picker tools, all we need is to make sure the Extended Addresses format (principal, checksum, subaccount) become the standard for how to enter ICRC Accounts, and then any dapp creator can create their own, imaginative and sophisticated ICRC1 Account pickers just like app developers are free to create their own dazzling Calendar component inventions for letting users pick a date.

But we do need to make sure Extended Addresses is a standard that is used everywhere, and we should give this standard for how to enter in ICRC1 Accounts a name. I think ICRC Extended Address string is a good candidate.

[ysyms]

Can DFINITY enable exchanges to support Principal IDs? The dual-address confuses and unsettles new users.

[marc0olo]

I think making them supporting principal ids in general is possible. needs coordination effort (and implementation effort on their side) though. however, the block log of the ICP ledger currently only stores AccountIdentifier representation which means by default (without extra effort), dashboards and explorers would only make it possible to search by AccountIdentifier.

I just saw that https://www.icexplorer.io always shows both representations and allows to search for both. so maybe that issue isn’t that big (cc @bogwar @Dylan @ICExplorer_io)

still I assume they’d still want to support the AccountIdentifiers, too for backwards compatibility. so getting rid of all the confusion around this will probably not be easy

ultimately I agree with @rem.codes that it might be better to enable icrcAccount support instead of principal only if we would undertake that effort

[Dylan]

@marc0olo

I just saw that https://www.icexplorer.io always shows both representations and allows to search for both.

What I see on icexplorer for the accounts of ICP transactions is that an account ID is always shown, and a principal is sometimes shown. This makes sense. You can discover a lot of ICP account addresses by taking a list of all known principals (and subaccounts) and converting them to ICP account addresses, which is what I assume icexplorer has done. We plan to do something like this on the ICP Dashboard as well.