Core Types

Overview

The Internet Computer protocol defines a comprehensive set of base types that form the foundation of the system. These types are defined in rs/types/base_types/ and handle identity, versioning, resource management, and memory addressing.

Principal Types

PrincipalId

The fundamental identity type representing principals as described in the IC interface specification.

PrincipalId

struct

A principal is a blob with variable length (bounded by 29 bytes) that uniquely identifies entities in the IC.

Show properties

MAX_LENGTH_IN_BYTES

usize

default:"29"

Maximum length of a principal in bytes

HASH_LEN_IN_BYTES

usize

default:"28"

Length of hash used in principal generation

Rust Signature:

pub struct PrincipalId(pub Principal)

Key Methods:

as_slice()

fn(&self) -> &[u8]

Returns the principal as a byte slice

to_vec()

fn(&self) -> Vec<u8>

Converts the principal to a byte vector

class()

fn(&self) -> Result<PrincipalIdClass, String>

Returns the class of this principal (Opaque, SelfAuthenticating, Derived, or Anonymous)

PrincipalIdClass

Defines the different classes of principals in the IC:

PrincipalIdClass

enum

Show variants

Opaque

System-generated or internal IDs (e.g., canister IDs, node IDs)

SelfAuthenticating

Derived from a public key using SHA-224 hash

Derived

Derived from another principal and a seed

Anonymous

The anonymous principal

Rust Signature:

pub enum PrincipalIdClass {
    Opaque = 1,
    SelfAuthenticating = 2,
    Derived = 3,
    Anonymous = 4,
}

CanisterId

A specialized principal type representing canister identities.

CanisterId

struct

Represents a canister’s PrincipalId with additional validation constraints.

Show constraints

class

Opaque

Must be of class Opaque

length

10 bytes

Must be exactly 10 bytes long

byte_8

0x01

Byte at index 8 (penultimate) must be 0x01

Rust Signature:

pub struct CanisterId(PrincipalId)

Construction Methods:

from_u64(val: u64)

const fn

Creates a CanisterId from a u64 value using big-endian encoding. The generated principal maintains ordering.

ic_00()

const fn

Returns the management canister ID (aaaaa-aa)

try_from_principal_id(principal_id: PrincipalId)

Validates and converts a PrincipalId to CanisterId with proper validation checks

Registry and Network Types

RegistryVersion

type alias

Represents the registry’s version number as a monotonically increasing counter.

Rust Signature:

pub type RegistryVersion = AmountOf<RegistryVersionTag, u64>

NodeId

type alias

Represents a node’s PrincipalId in the network.

Rust Signature:

pub type NodeId = Id<NodeTag, PrincipalId>

SubnetId

type alias

Represents a subnet’s PrincipalId in the network.

Rust Signature:

pub type SubnetId = Id<SubnetTag, PrincipalId>

Resource Management Types

NumBytes

type alias

Models a non-negative number of bytes, primarily used for tracking memory usage and allocation in canisters.

Rust Signature:

pub type NumBytes = AmountOf<NumBytesTag, u64>

Display Format:

Automatically formats using appropriate binary power units (KiB, MiB, GiB, etc.)
Shows up to 2 decimal places (e.g., “123.45 MiB”)
No decimals for byte-level precision

NumSeconds

type alias

Models a non-negative number of seconds.

Rust Signature:

pub type NumSeconds = AmountOf<NumSecondsTag, u64>

NumOsPages

type alias

Represents a number of OS-sized memory pages.

Rust Signature:

pub type NumOsPages = AmountOf<NumOsPagesTag, u64>

Memory Management Types

InternalAddress

struct

Represents an internal memory address used for pointer arithmetic in canister memory management.

Rust Signature:

pub struct InternalAddress(usize)

Key Methods:

new(value: usize)

Creates a new InternalAddress

get()

fn(&self) -> usize

Returns the underlying address value

checked_add(self, rhs: Self)

Safely adds two addresses with overflow checking

checked_sub(self, rhs: Self)

Safely subtracts addresses with underflow checking

SnapshotId

struct

Represents a canister snapshot ID, unique across all subnets. Composed of a local snapshot ID (u64) and canister ID.

Show properties

MAX_LENGTH_IN_BYTES

usize

PrincipalId::MAX_LENGTH_IN_BYTES + LOCAL_ID_LENGTH_IN_BYTES

LOCAL_ID_LENGTH_IN_BYTES

usize

default:"8"

Length of the local snapshot ID component

Rust Signature:

pub struct SnapshotId {
    len: usize,
    bytes: [u8; Self::MAX_LENGTH_IN_BYTES],
}

Key Methods:

get_canister_id()

fn(&self) -> CanisterId

Extracts the canister ID from the snapshot ID

get_local_snapshot_id()

fn(&self) -> u64

Extracts the local snapshot counter

from((CanisterId, u64))

impl From

Constructs a SnapshotId from a canister ID and local ID pair

Management Canister Types

For detailed management canister types, see the Management Canister Types Reference.

IC_00 Constant

IC_00

CanisterId

The management canister ID, used for system-level operations.

Rust Signature:

pub const IC_00: CanisterId = CanisterId::ic_00();

Hashing Utilities

hash_of_map

fn<K, V, F>

Computes the hash of a BTreeMap following the IC interface specification’s hash-of-map algorithm.

Show parameters

map

&BTreeMap<K, V>

The map to hash

hash_key_val

F: Fn(&K, &V) -> Vec<u8>

Function to hash individual key-value pairs

Rust Signature:

pub fn hash_of_map<K, V, F>(map: &BTreeMap<K, V>, hash_key_val: F) -> [u8; HASH_LENGTH]
where
    F: Fn(&K, &V) -> Vec<u8>

Algorithm:

Hash each key-value pair using the provided function
Sort the resulting hashes
Concatenate and hash the sorted list with SHA-256

Constant:

pub const HASH_LENGTH: usize = 32;

Serialization

All types implement standard Rust serialization traits:

Candid: CandidType for inter-canister communication
Serde: Serialize and Deserialize for data persistence
Protobuf: Protocol buffer encoding for network transmission

Example Usage

use ic_base_types::{PrincipalId, CanisterId, NumBytes};

// Create a canister ID from a u64
let canister_id = CanisterId::from_u64(12345);

// Convert to principal
let principal: PrincipalId = canister_id.into();

// Parse from text representation
let parsed = PrincipalId::from_str("aaaaa-aa").unwrap();

// Track memory usage
let memory_used = NumBytes::from(1024 * 1024); // 1 MiB
println!("Memory: {}", memory_used); // Displays: "1.00 MiB"

Core APIs

Canisters

Networking

Overview

Principal Types

PrincipalId

PrincipalIdClass

CanisterId

Registry and Network Types

RegistryVersion

NodeId

SubnetId

Resource Management Types

NumBytes

NumSeconds

NumOsPages

Memory Management Types

InternalAddress

SnapshotId

Management Canister Types

IC_00 Constant

Hashing Utilities

hash_of_map

Serialization

Example Usage

See Also

Build docs developers (and LLMs) love

Core APIs

Canisters

Networking

​Overview

​Principal Types

​PrincipalId

​PrincipalIdClass

​CanisterId

​Registry and Network Types

​RegistryVersion

​NodeId

​SubnetId

​Resource Management Types

​NumBytes

​NumSeconds

​NumOsPages

​Memory Management Types

​InternalAddress

​SnapshotId

​Management Canister Types

​IC_00 Constant

​Hashing Utilities

​hash_of_map

​Serialization

​Example Usage

​See Also

Build docs developers (and LLMs) love

Overview

Principal Types

PrincipalId

PrincipalIdClass

CanisterId

Registry and Network Types

RegistryVersion

NodeId

SubnetId

Resource Management Types

NumBytes

NumSeconds

NumOsPages

Memory Management Types

InternalAddress

SnapshotId

Management Canister Types

IC_00 Constant

Hashing Utilities

hash_of_map

Serialization

Example Usage

See Also