Skip to main content

Technical Specification

This specification provides an overview of key structures and actions within the toolkit project, including configurations, metadata, membership, hotkeys, and proposal management.

Generic Types​

These types are used throughout the project for consistency and readability.

pub type Ballots = u64;  // Represents voting power
pub type Time = u64;     // Represents timestamps in seconds

Core Structures​

Config​

The Config struct represents the main settings for the toolkit project.

pub struct Config {
    pub governance_enabled: bool,                   // Whether governance is enabled
    pub proposal_duration_seconds: u64,             // Duration for proposals in seconds
    pub governance_type: Option<String>,            // Optional governance type (not currently used)
    pub ledger_canister_id: Option<Principal>,      // Ledger canister ID, if any
    pub index_canister_id: Option<Principal>,       // Index canister ID, if any
    pub archive_canister_id: Option<Principal>,     // Index canister ID, if any
    pub installed_version: Version,                 // Installed version of the project
    pub hotkeys_enabled: bool,                      // Whether hotkeys are enabled
    pub canister_status_fetch_interval_seconds: u64,// Frequency of canister status checks
    pub parent_canister_id: Option<Principal>,      // ID of the parent canister
    pub updated_at: u64,                            // Timestamp of the last update
}

Metadata​

The Metadata struct holds general information about the toolkit project.

pub struct Metadata {
    pub url: Option<String>,         // Optional URL for the project
    pub logo: Option<String>,        // Optional logo URL
    pub name: Option<String>,        // Name of the project
    pub description: Option<String>, // Description of the project
    pub created_by: Account,         // Account that created the project
    pub owner: Account,              // Current owner of the project
    pub created_at: Time,            // Timestamp of creation
    pub updated_at: Time,            // Timestamp of last update
}

Member​

The Member struct describes a toolkit project member and their permissions.

pub struct Member {
    pub ballots: Ballots,                 // Voting power of the member
    pub hotkeys: Vec<Hotkey>,             // Hotkeys associated with the member
    pub permissions: Option<Vec<String>>, // Permissions for the member
    pub created_at: Time,                 // Timestamp of member creation
    pub updated_at: Time,                 // Timestamp of last update
}

Hotkey​

The Hotkey struct enables additional governance flexibility by allowing certain accounts to act on behalf of members.

pub struct Hotkey {
    pub name: String,                     // Name of the hotkey
    pub account: Account,                 // Account linked to the hotkey
    pub permissions: Option<Vec<String>>, // Specific permissions for the hotkey
    pub created_at: Time,                 // Timestamp of hotkey creation
}

Governance and Proposals​

Governance is a core feature of toolkit projects, supporting structured decision-making through proposals. Members can create proposals and cast votes, influencing project configurations and actions.

Proposal​

The Proposal struct contains the details of a specific proposal submitted for member voting.

pub struct Proposal {
    pub title: String,                    // Title of the proposal
    pub summary: String,                  // Brief summary of the proposal
    pub url: String,                      // Optional URL for more information
    pub action: ProposalAction,           // Action requested by the proposal
    pub votes: HashMap<Account, Vote>,    // Votes cast by members
    pub executed_at: Option<Time>,        // Execution timestamp (if executed)
    pub execution_status: ExecutionStatus,// Status of the proposal’s execution
    pub expires_at: Time,                 // Expiration timestamp
    pub duration_seconds: Time,           // Duration of the proposal in seconds
    pub created_by: Option<Account>,      // Account that created the proposal
    pub created_at: Time,                 // Creation timestamp
}

ProposalAction​

The ProposalAction enum defines the types of actions members can propose.

pub enum ProposalAction {
    None,
    ManageConfig(ManageConfigActions),
    ManageMember(ManageMemberActions),
    ManageCanister(ManageCanisterActions),
    TransferOwner(Account),
    ManageMetadata(ManageMetadataActions),
    TokenTransfer(TokenTransferActions),
}

ExecutionStatus​

The ExecutionStatus enum represents the possible outcomes of a proposal.

pub enum ExecutionStatus {
    Accepted,
    Pending,
    Rejected,
    Failed,
}

Vote​

The Vote struct holds the details of a vote cast by a member.

pub struct Vote {
    pub ballots: Ballots,    // Voting power applied in the vote
    pub accept: Option<bool>, // Acceptance or rejection of the proposal
    pub time: Option<Time>,   // Timestamp of the vote
}

Proposal Actions​

Members can submit proposals for specific actions, allowing for extensive project management capabilities.

ManageConfigActions​

These actions adjust project configuration settings.

  • EnableGovernance(bool) – Enable or disable governance
  • SetProposalDurationSeconds(u64) – Set duration for proposals
  • SetCanisterStatusFetchIntervalSeconds(u64) – Set the interval for canister status checks

ManageMemberActions​

Actions to modify membership:

  • Add(Account) – Add a new member to the project
  • Remove(Account) – Remove an existing member

ManageCanisterActions​

Actions for managing canister integrations:

  • Register(Principal) – Register a new canister with the project
  • Deregister(DeregisterCanisterArgs) – Remove a canister from the project, assigning a new controller
  • Upgrade(InstallCodeArgument) – Upgrade the code of an existing canister
  • New(NewCanisterArgs) (Not Implemented) – Deploy a new canister with specified cycles

ManageMetadataActions​

Actions to update project metadata:

  • Update(UpdateMetadata) – Modify metadata fields like URL, logo, name, and description

TokenTransferActions​

Actions to handle ICRC token transfers:

  • IcrcTransfer(IcrcTransferArgs) – Execute a token transfer on the ICRC ledger

RootConfig​

Actions specific to the root canister of the toolkit project:

  • Upgrade – Upgrade the root canister to a new version
  • Detach (Not Implemented) – Detach the root canister and assign a new controller