Struct ic_agent::export::Principal

pub struct Principal { /* private fields */ }

Generic ID on Internet Computer.

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.

Note a principal is not necessarily tied with a public key-pair, yet we need at least a key-pair of a related principal to sign requests.

A Principal can be serialized to a byte array (Vec<u8>) or a text representation, but the inner structure of the byte representation is kept private.

Example of using a Principal object:

use ic_principal::Principal;

let text = "aaaaa-aa";  // The management canister ID.
let principal = Principal::from_text(text).expect("Could not decode the principal.");
assert_eq!(principal.as_slice(), &[]);
assert_eq!(principal.to_text(), text);

Serialization is enabled with the “serde” feature. It supports serializing to a byte bufer for non-human readable serializer, and a string version for human readable serializers.

use ic_principal::Principal;
use serde::{Deserialize, Serialize};
use std::str::FromStr;

#[derive(Serialize)]
struct Data {
    id: Principal,
}

let id = Principal::from_str("2chl6-4hpzw-vqaaa-aaaaa-c").unwrap();

// JSON is human readable, so this will serialize to a textual
// representation of the Principal.
assert_eq!(
    serde_json::to_string(&Data { id: id.clone() }).unwrap(),
    r#"{"id":"2chl6-4hpzw-vqaaa-aaaaa-c"}"#
);

// CBOR is not human readable, so will serialize to bytes.
assert_eq!(
    serde_cbor::to_vec(&Data { id: id.clone() }).unwrap(),
    &[161, 98, 105, 100, 73, 239, 205, 171, 0, 0, 0, 0, 0, 1],
);

Implementations

impl Principal

pub const MAX_LENGTH_IN_BYTES: usize = 29usize

pub const fn management_canister() -> Principal

Construct a Principal of the IC management canister

pub fn self_authenticating<P>(public_key: P) -> Principal

where P: AsRef<[u8]>,

Available on crate feature self_authenticating only.

Construct a self-authenticating ID from public key

pub const fn anonymous() -> Principal

Construct an anonymous ID.

pub const fn from_slice(slice: &[u8]) -> Principal

Construct a Principal from a slice of bytes.

Panics

Panics if the slice is longer than 29 bytes.

pub const fn try_from_slice(slice: &[u8]) -> Result<Principal, PrincipalError>

Available on crate feature convert only.

Construct a Principal from a slice of bytes.

pub fn from_text<S>(text: S) -> Result<Principal, PrincipalError>

where S: AsRef<str>,

Available on crate feature convert only.

Parse a Principal from text representation.

pub fn to_text(&self) -> String

Available on crate feature convert only.

Convert Principal to text representation.

pub fn as_slice(&self) -> &[u8]

Return the Principal’s underlying slice of bytes.

Trait Implementations

impl AsRef<[u8]> for Principal

fn as_ref(&self) -> &[u8]

Converts this type into a shared reference of the (usually inferred) input type.

impl CandidType for Principal

fn _ty() -> Type

fn idl_serialize<S>( &self, serializer: S ) -> Result<(), <S as Serializer>::Error>

where S: Serializer,

fn ty() -> Type

fn id() -> TypeId

impl Clone for Principal

fn clone(&self) -> Principal

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Principal

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Principal

Available on crate feature serde only.

fn deserialize<D>( deserializer: D ) -> Result<Principal, <D as Deserializer<'de>>::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for Principal

Available on crate feature convert only.

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl FromStr for Principal

Available on crate feature convert only.

type Err = PrincipalError

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Principal, <Principal as FromStr>::Err>

Parses a string s to return a value of this type.

impl Hash for Principal

fn hash<__H>(&self, state: &mut __H)

where __H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for Principal

fn cmp(&self, other: &Principal) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized + PartialOrd,

Restrict a value to a certain interval.

impl PartialEq for Principal

fn eq(&self, other: &Principal) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for Principal

fn partial_cmp(&self, other: &Principal) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl Serialize for Principal

Available on crate feature serde only.

fn serialize<S>( &self, serializer: S ) -> Result<<S as Serializer>::Ok, <S as Serializer>::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl TryFrom<&[u8]> for Principal

Available on crate feature convert only.

type Error = PrincipalError

The type returned in the event of a conversion error.

fn try_from( bytes: &[u8] ) -> Result<Principal, <Principal as TryFrom<&[u8]>>::Error>

Performs the conversion.

impl TryFrom<&Vec<u8>> for Principal

Available on crate feature convert only.

type Error = PrincipalError

The type returned in the event of a conversion error.

fn try_from( bytes: &Vec<u8> ) -> Result<Principal, <Principal as TryFrom<&Vec<u8>>>::Error>

Performs the conversion.

impl TryFrom<&str> for Principal

Available on crate feature convert only.

type Error = PrincipalError

The type returned in the event of a conversion error.

fn try_from(s: &str) -> Result<Principal, <Principal as TryFrom<&str>>::Error>

Performs the conversion.

impl TryFrom<Vec<u8>> for Principal

Available on crate feature convert only.

type Error = PrincipalError

The type returned in the event of a conversion error.

fn try_from( bytes: Vec<u8> ) -> Result<Principal, <Principal as TryFrom<Vec<u8>>>::Error>

Performs the conversion.

impl Copy for Principal

impl Eq for Principal

impl StructuralEq for Principal

impl StructuralPartialEq for Principal