Improving the documentation by differentiating between user and canister ids more clearly

Developers Getting Started
1

Hi everyone

Couldn’t the documentation of the IC use terms that differentiate more clearly between canister ids and user ids? With that I mean that the words “id”, “principal” and “identifier” are currently all used interchangeably for both canisters and users/developers.

In the “Internet Computer Interface Specifications” under " Principals" it says:
Principals are generic identifiers for canisters, users and possibly other concepts in the future. As far as most uses of the IC are concerned they are opaque binary blobs with a length between 0 and 29 bytes, and there is intentionally no mechanism to tell canister ids and user ids apart.

I might be misunderstanding something but canister ids/identifiers/principals are simply shorter than user/developer ids/identifiers/principals and can thus be clearly differentiated:

  • canisters: rwlgt-iiaaa-aaaaa-aaaaa-cai
  • users: g3jww-sbmtm-gxsag-4mecu-72yc4-kef5v-euixq-og2kd-sav2v-p2sb3-pae

I would propose that the docs are modified to be more clear in describing the differences between the two and also in describing that id/identifiers/principals are the same thing and depending on what they refer to (users or canisters) differ in length.

In many cases in the docs it is not clear enough if the context is about user or canister ids. For example under “use the default cycles wallet” there is a sentence:
In a production environment, however, you need to explicitly register and transfer cycles to new canisters, specify the principals that can act as custodians, and manage the principals with ownership rights.

This leaves room for interpretation if canister or user ids are used as controllers or to manage ownership rights.

All in all I think the docs could be clearer in using these terms. It cost me way too much time to understand what is what, especially as the cycle wallets add to the confusion.

2 Likes
2

Hi Mathias, although it helps to know that Principals can be an umbrella term for canisters or users, I can understand the confusion. I think the documentation intentionally uses “Principal” to indicate both users and canisters.

If you read further down for cycles wallet docs it says:
‘A user principal or canister principal can be assigned to a controller or custodian role.’
Although lengths of principals in user vs canister is different, the cycles wallet will accept both types of principals as a custodian or a controller.

Also, there are some updates to the cycles wallet as described here: Future of the Cycles Wallet - #10 by kpeacock

3

Thank you very much, I’m starting to understand the basics and will look into the update concerning the cycles wallet.

Concerning the docs, I think some good charts could explain a lot of these things extremely efficient, which could speed up the developer onboarding process.

I think once there is an implementation of the SNS, the IC could benefit over-proportionally (compared to the ecosystems of less scalable blockchains) from onboarding semi-technical devs like me as not every dapp is required to handle millions/billions to be successful. Someone like me (who’s not really able to write secure code) could for example build a first iteration of a backend in motoko and then simply launch a DAO to get the community on board if the idea/MVP is of interest to others. I’m really looking forward to this…

Thanks again

1 Like