Difference between revisions of "Principal"

Latest revision as of 21:59, 18 January 2022

A principal is an identifier for an entity on the IC such as a user, a canister (dapps/smart contracts), or a subnet.

Types of principals

There are several types of principals.

Management principal

The management principal is used to reference the management canister.

Opaque principal

An opaque principal is chosen by the system. This kind of principal is used to reference any canister that is not the management canister.

Self-Authenticating principal

A self-authenticating principal is a hash of a public signature key. This kind of principal is for instance used to reference a subnet or user.

Derived principal

The principal is derived from a registering principal. This type of principal is currently not used.

Anonymous principal

The anonymous principal is used to reference an anonymous user.

Representation

Binary

A principal consists of a variable-length byte array of up to 29 bytes. The last byte is used to indicate the type. The table below gives the type inferred from the last byte.

Byte	Type
none	Management
`0x01`	Opaque
`0x02`	Self-Authenticating
`0x03`	Derived
`0x04`	Anonymous
`0x05`	Unassigned

Textual

A principal is shown in textual format by prepending it with its CRC-32 value in big-endian byte order, applying Base32 encoding without padding, grouping characters by length five, and separating them by a hyphen. The maximal length of the encoding, including hyphens, is 63 characters. The table below gives some common principals.

Principal	Description
`aaaaa-aa`	management canister
`rrkah-fqaaa-aaaaa-aaaaq-cai`	governance canister
`ryjl3-tyaaa-aaaaa-aaaba-cai`	ledger canister
`tdb26-jop6k-aogll-7ltgs-eruif-6kk7m-qpktf-gdiqx-mxtrf-vb5e6-eqe`	network nervous system
`2vxsx-fae`	anonymous user

@@ Line 1: / Line 1: @@
-A '''principal''' is a cryptographic identifier used to describe the sender or receiver of a [[message]]. There are several types of principals owing to the different contexts in which a message can be sent or received.
+A '''principal''' is an identifier for an entity on the IC such as a user, a canister (dapps/smart contracts), or a subnet.
+== Types of principals ==
+There are several types of principals.
+=== Management principal ===
+The management principal is used to reference the management canister.
+=== Opaque principal ===
+An opaque principal is chosen by the system. This kind of principal is used to reference any canister that is not the management canister.
+=== Self-Authenticating principal ===
+A self-authenticating principal is a hash of a public signature key. This kind of principal is for instance used to reference a subnet or user.
+=== Derived principal ===
+The principal is derived from a registering principal. This type of principal is currently not used.
+=== Anonymous principal ===
+The anonymous principal is used to reference an anonymous user.
+== Representation ==
+=== Binary ===
+A principal consists of a variable-length byte array of up to 29 bytes. The last byte is used to indicate the type. The table below gives the type inferred from the last byte.
+{| class="wikitable"
+|'''Byte'''
+|'''Type'''
+|-
+|none
+|Management
+|-
+|<code>0x01</code>
+|Opaque
+|-
+|<code>0x02</code>
+|Self-Authenticating
+|-
+|<code>0x03</code>
+|Derived
+|-
+|<code>0x04</code>
+|Anonymous
+|-
+|<code>0x05</code>
+|Unassigned
+|}
+=== Textual ===
+A principal is shown in textual format by prepending it with its [[wikipedia:Cyclic_redundancy_check#CRC-32_algorithm|CRC-32]] value in big-endian byte order, applying [[wikipedia:Base32|Base32]] encoding without padding, grouping characters by length five, and separating them by a hyphen. The maximal length of the encoding, including hyphens, is 63 characters. The table below gives some common principals.
+{| class="wikitable"
+!Principal
+!Description
+|-
+|<code>aaaaa-aa</code>
+|[[Management Canister|management canister]]
+|-
+|<code>rrkah-fqaaa-aaaaa-aaaaq-cai</code>
+|[[Governance Canister|governance canister]]
+|-
+|<code>ryjl3-tyaaa-aaaaa-aaaba-cai</code>
+|[[Ledger Canister|ledger canister]]
+|-
+|<code>tdb26-jop6k-aogll-7ltgs-eruif-6kk7m-qpktf-gdiqx-mxtrf-vb5e6-eqe</code>
+|[[Network Nervous System|network nervous system]]
+|-
+|<code>2vxsx-fae</code>
+|anonymous user
+|}