Skip to main content

core/Principal

Module for interacting with Principals (users and canisters).

Principals are used to identify entities that can interact with the Internet Computer. These entities are either users or canisters.

Example textual representation of Principals:

un4fu-tqaaa-aaaab-qadjq-cai

In Motoko, there is a primitive Principal type called Principal. As an example of where you might see Principals, you can access the Principal of the caller of your shared function.

persistent actor {
  public shared(msg) func foo() {
    let caller : Principal = msg.caller;
  };
}

Then, you can use this module to work with the Principal.

Import from the core library to use this module.

import Principal "mo:core/Principal";

Type Principal​

type Principal = Prim.Types.Principal

Function fromActor​

func fromActor(a : actor {  }) : Principal

Get the Principal identifier of an actor.

Example:

actor MyCanister {
  func getPrincipal() : Principal {
    let principal = Principal.fromActor(MyCanister);
  }
}

Function toLedgerAccount​

func toLedgerAccount(principal : Principal, subAccount : ?Blob) : Blob

Compute the Ledger account identifier of a principal. Optionally specify a sub-account.

Example:

let principal = Principal.fromText("un4fu-tqaaa-aaaab-qadjq-cai");
let subAccount : Blob = "\4A\8D\3F\2B\6E\01\C8\7D\9E\03\B4\56\7C\F8\9A\01\D2\34\56\78\9A\BC\DE\F0\12\34\56\78\9A\BC\DE\F0";
let account = Principal.toLedgerAccount(principal, ?subAccount);
assert account == "\8C\5C\20\C6\15\3F\7F\51\E2\0D\0F\0F\B5\08\51\5B\47\65\63\A9\62\B4\A9\91\5F\4F\02\70\8A\ED\4F\82";

Function toBlob​

func toBlob(p : Principal) : Blob

Convert a Principal to its Blob (bytes) representation.

Example:

let principal = Principal.fromText("un4fu-tqaaa-aaaab-qadjq-cai");
let blob = Principal.toBlob(principal);
assert blob == "\00\00\00\00\00\30\00\D3\01\01";

Function fromBlob​

func fromBlob(b : Blob) : Principal

Converts a Blob (bytes) representation of a Principal to a Principal value.

Example:

let blob = "\00\00\00\00\00\30\00\D3\01\01" : Blob;
let principal = Principal.fromBlob(blob);
assert Principal.toText(principal) == "un4fu-tqaaa-aaaab-qadjq-cai";

Function toText​

func toText(p : Principal) : Text

Converts a Principal to its Text representation.

Example:

let principal = Principal.fromText("un4fu-tqaaa-aaaab-qadjq-cai");
assert Principal.toText(principal) == "un4fu-tqaaa-aaaab-qadjq-cai";

Function fromText​

func fromText(t : Text) : Principal

Converts a Text representation of a Principal to a Principal value.

Example:

let principal = Principal.fromText("un4fu-tqaaa-aaaab-qadjq-cai");
assert Principal.toText(principal) == "un4fu-tqaaa-aaaab-qadjq-cai";

Function anonymous​

func anonymous() : Principal

Constructs and returns the anonymous principal.

Function isAnonymous​

func isAnonymous(p : Principal) : Bool

Checks if the given principal represents an anonymous user.

Example:

let principal = Principal.fromText("un4fu-tqaaa-aaaab-qadjq-cai");
assert not Principal.isAnonymous(principal);

Function isCanister​

func isCanister(p : Principal) : Bool

Checks if the given principal is a canister.

The last byte for opaque principal ids must be 0x01 https://internetcomputer.org/docs/current/references/ic-interface-spec#principal

Example:

let principal = Principal.fromText("un4fu-tqaaa-aaaab-qadjq-cai");
assert Principal.isCanister(principal);

Function isSelfAuthenticating​

func isSelfAuthenticating(p : Principal) : Bool

Checks if the given principal is a self authenticating principal. Most of the time, this is a user principal.

The last byte for user principal ids must be 0x02 https://internetcomputer.org/docs/current/references/ic-interface-spec#principal

Example:

let principal = Principal.fromText("6rgy7-3uukz-jrj2k-crt3v-u2wjm-dmn3t-p26d6-ndilt-3gusv-75ybk-jae");
assert Principal.isSelfAuthenticating(principal);

Function isReserved​

func isReserved(p : Principal) : Bool

Checks if the given principal is a reserved principal.

The last byte for reserved principal ids must be 0x7f https://internetcomputer.org/docs/current/references/ic-interface-spec#principal

Example:

let principal = Principal.fromText("un4fu-tqaaa-aaaab-qadjq-cai");
assert not Principal.isReserved(principal);

Function isController​

func isController(p : Principal) : Bool

Checks if the given principal can control this canister.

Example:

let principal = Principal.fromText("un4fu-tqaaa-aaaab-qadjq-cai");
assert not Principal.isController(principal);

Function hash​

func hash(principal : Principal) : Types.Hash

Hashes the given principal by hashing its Blob representation.

Example:

let principal = Principal.fromText("un4fu-tqaaa-aaaab-qadjq-cai");
assert Principal.hash(principal) == 2_742_573_646;

Function compare​

func compare(principal1 : Principal, principal2 : Principal) : {#less; #equal; #greater}

General purpose comparison function for Principal. Returns the Order ( either #less, #equal, or #greater) of comparing principal1 with principal2.

Example:

let principal1 = Principal.fromText("un4fu-tqaaa-aaaab-qadjq-cai");
let principal2 = Principal.fromText("un4fu-tqaaa-aaaab-qadjq-cai");
assert Principal.compare(principal1, principal2) == #equal;

Function equal​

func equal(principal1 : Principal, principal2 : Principal) : Bool

Equality function for Principal types. This is equivalent to principal1 == principal2.

Example:

let principal1 = Principal.fromText("un4fu-tqaaa-aaaab-qadjq-cai");
let principal2 = Principal.fromText("un4fu-tqaaa-aaaab-qadjq-cai");
ignore Principal.equal(principal1, principal2);
assert principal1 == principal2;

Note: The reason why this function is defined in this library (in addition to the existing == operator) is so that you can use it as a function value to pass to a higher order function. It is not possible to use == as a function value at the moment.

Example:

let principal1 = Principal.anonymous();
let principal2 = Principal.fromBlob("\04");
assert Principal.equal(principal1, principal2);

Function notEqual​

func notEqual(principal1 : Principal, principal2 : Principal) : Bool

Inequality function for Principal types. This is equivalent to principal1 != principal2.

Example:

let principal1 = Principal.fromText("un4fu-tqaaa-aaaab-qadjq-cai");
let principal2 = Principal.fromText("un4fu-tqaaa-aaaab-qadjq-cai");
ignore Principal.notEqual(principal1, principal2);
assert not (principal1 != principal2);

Note: The reason why this function is defined in this library (in addition to the existing != operator) is so that you can use it as a function value to pass to a higher order function. It is not possible to use != as a function value at the moment.

Function less​

func less(principal1 : Principal, principal2 : Principal) : Bool

"Less than" function for Principal types. This is equivalent to principal1 < principal2.

Example:

let principal1 = Principal.fromText("un4fu-tqaaa-aaaab-qadjq-cai");
let principal2 = Principal.fromText("un4fu-tqaaa-aaaab-qadjq-cai");
ignore Principal.less(principal1, principal2);
assert not (principal1 < principal2);

Note: The reason why this function is defined in this library (in addition to the existing < operator) is so that you can use it as a function value to pass to a higher order function. It is not possible to use < as a function value at the moment.

Function lessOrEqual​

func lessOrEqual(principal1 : Principal, principal2 : Principal) : Bool

"Less than or equal to" function for Principal types. This is equivalent to principal1 <= principal2.

Example:

let principal1 = Principal.fromText("un4fu-tqaaa-aaaab-qadjq-cai");
let principal2 = Principal.fromText("un4fu-tqaaa-aaaab-qadjq-cai");
ignore Principal.lessOrEqual(principal1, principal2);
assert principal1 <= principal2;

Note: The reason why this function is defined in this library (in addition to the existing <= operator) is so that you can use it as a function value to pass to a higher order function. It is not possible to use <= as a function value at the moment.

Function greater​

func greater(principal1 : Principal, principal2 : Principal) : Bool

"Greater than" function for Principal types. This is equivalent to principal1 > principal2.

Example:

let principal1 = Principal.fromText("un4fu-tqaaa-aaaab-qadjq-cai");
let principal2 = Principal.fromText("un4fu-tqaaa-aaaab-qadjq-cai");
ignore Principal.greater(principal1, principal2);
assert not (principal1 > principal2);

Note: The reason why this function is defined in this library (in addition to the existing > operator) is so that you can use it as a function value to pass to a higher order function. It is not possible to use > as a function value at the moment.

Function greaterOrEqual​

func greaterOrEqual(principal1 : Principal, principal2 : Principal) : Bool

"Greater than or equal to" function for Principal types. This is equivalent to principal1 >= principal2.

Example:

let principal1 = Principal.fromText("un4fu-tqaaa-aaaab-qadjq-cai");
let principal2 = Principal.fromText("un4fu-tqaaa-aaaab-qadjq-cai");
ignore Principal.greaterOrEqual(principal1, principal2);
assert principal1 >= principal2;

Note: The reason why this function is defined in this library (in addition to the existing >= operator) is so that you can use it as a function value to pass to a higher order function. It is not possible to use >= as a function value at the moment.