diff --git a/packages/rs-dpp/src/data_contract/associated_token/token_configuration/v0/mod.rs b/packages/rs-dpp/src/data_contract/associated_token/token_configuration/v0/mod.rs index 7c17df6d973..3aec2664734 100644 --- a/packages/rs-dpp/src/data_contract/associated_token/token_configuration/v0/mod.rs +++ b/packages/rs-dpp/src/data_contract/associated_token/token_configuration/v0/mod.rs @@ -17,51 +17,92 @@ use bincode::{Decode, Encode}; use serde::{Deserialize, Serialize}; use std::fmt; +/// Defines the complete configuration for a version 0 token contract. +/// +/// `TokenConfigurationV0` encapsulates all metadata, control rules, supply settings, +/// and governance constraints used to initialize and manage a token instance on Platform. +/// This structure serves as the core representation of a token's logic, permissions, +/// and capabilities. +/// +/// This configuration is designed to be deterministic and versioned for compatibility +/// across protocol upgrades and validation environments. #[derive(Serialize, Deserialize, Decode, Encode, Debug, Clone, PartialEq, Eq)] #[serde(rename_all = "camelCase")] pub struct TokenConfigurationV0 { + /// Metadata conventions, including decimals and localizations. pub conventions: TokenConfigurationConvention, - /// Who can change the conventions + + /// Change control rules governing who can modify the conventions field. #[serde(default = "default_change_control_rules")] pub conventions_change_rules: ChangeControlRules, - /// The supply at the creation of the token + + /// The initial token supply minted at creation. #[serde(default)] pub base_supply: TokenAmount, - /// The maximum supply the token can ever have + + /// The maximum allowable supply of the token. + /// + /// If `None`, the supply is unbounded unless otherwise constrained by minting logic. #[serde(default)] pub max_supply: Option, - /// The rules for keeping history. + + /// Configuration governing which historical actions are recorded for this token. #[serde(default = "default_token_keeps_history_rules")] pub keeps_history: TokenKeepsHistoryRules, - /// True if we start off as paused, meaning that we can not transfer till we unpause. + + /// Indicates whether the token should start in a paused state. + /// + /// When `true`, transfers are disallowed until explicitly unpaused via an emergency action. #[serde(default = "default_starts_as_paused")] pub start_as_paused: bool, - /// Allow to transfer and mint tokens to frozen identity token balances + + /// Allows minting and transferring to frozen token balances if enabled. #[serde(default = "default_allow_transfer_to_frozen_balance")] pub allow_transfer_to_frozen_balance: bool, - /// Who can change the max supply - /// Even if set no one can ever change this under the base supply + + /// Change control rules for updating the `max_supply`. + /// + /// Note: The `max_supply` can never be reduced below the `base_supply`. #[serde(default = "default_change_control_rules")] pub max_supply_change_rules: ChangeControlRules, - /// The distribution rules for the token + + /// Defines the token's distribution logic, including perpetual and pre-programmed distributions. #[serde(default = "default_token_distribution_rules")] pub distribution_rules: TokenDistributionRules, + + /// Rules controlling who is authorized to perform manual minting of tokens. #[serde(default = "default_contract_owner_change_control_rules")] pub manual_minting_rules: ChangeControlRules, + + /// Rules controlling who is authorized to perform manual burning of tokens. #[serde(default = "default_contract_owner_change_control_rules")] pub manual_burning_rules: ChangeControlRules, + + /// Rules governing who may freeze token balances. #[serde(default = "default_change_control_rules")] pub freeze_rules: ChangeControlRules, + + /// Rules governing who may unfreeze token balances. #[serde(default = "default_change_control_rules")] pub unfreeze_rules: ChangeControlRules, + + /// Rules governing who may destroy frozen funds. #[serde(default = "default_change_control_rules")] pub destroy_frozen_funds_rules: ChangeControlRules, + + /// Rules governing who may invoke emergency actions, such as pausing transfers. #[serde(default = "default_change_control_rules")] pub emergency_action_rules: ChangeControlRules, + + /// Optional reference to the group assigned as the token's main control group. #[serde(default)] pub main_control_group: Option, + + /// Defines whether and how the main control group assignment may be modified. #[serde(default)] pub main_control_group_can_be_modified: AuthorizedActionTakers, + + /// Optional textual description of the token's purpose, behavior, or metadata. #[serde(default)] pub description: Option, } @@ -175,26 +216,73 @@ impl fmt::Display for TokenConfigurationV0 { } } +/// Represents predefined capability levels for token control presets. +/// +/// `TokenConfigurationPresetFeatures` defines a hierarchy of governance capabilities +/// that can be used to initialize rule sets for a token. Each variant enables a specific +/// scope of permitted actions, allowing for simple selection of common governance models. +/// +/// These presets are intended to be used in conjunction with `TokenConfigurationPreset` +/// to simplify token setup and enforce governance constraints consistently. #[derive(Serialize, Deserialize, Decode, Encode, Debug, Clone, Copy, PartialEq, Eq, PartialOrd)] pub enum TokenConfigurationPresetFeatures { - /// Nothing can be changed once it is set + /// No actions are permitted after initialization. All governance and control + /// settings are immutable. + /// + /// Suitable for tokens that should remain fixed and tamper-proof. MostRestrictive, - /// The action taker can not mint or burn tokens, or any advanced action. - /// They can pause the token if needed. + + /// Only emergency actions (e.g., pausing the token) are permitted. + /// + /// Minting, burning, and advanced operations (such as freezing) are disallowed. + /// This preset allows minimal control for critical situations without risking + /// token supply or ownership manipulation. WithOnlyEmergencyAction, + + /// Allows minting and burning operations, but not advanced features such as freezing. + /// + /// Enables supply management without enabling full administrative capabilities. WithMintingAndBurningActions, - /// The action taker can do advanced actions like freezing + + /// Grants the ability to perform advanced actions, including freezing and unfreezing balances. + /// + /// Minting and burning are also permitted. Suitable for tokens that require + /// moderate administrative control without total override capabilities. WithAllAdvancedActions, + /// The action taker is a god, he can do everything, even taking away his own power. + /// This grants unrestricted control to the action taker, including the ability to revoke + /// their own permissions or transfer all governance. + /// + /// This includes minting, burning, freezing, emergency actions, and full rule modification. + /// Should only be used with trusted or self-destructible authorities. WithExtremeActions, } +/// A high-level preset representing common configurations for token governance and control. +/// +/// `TokenConfigurationPreset` provides a simplified way to initialize a set of +/// predefined token rules (e.g., minting, burning, freezing, emergency actions) +/// by selecting a feature set (`features`) and defining the authorized actor (`action_taker`) +/// responsible for performing allowed actions. +/// +/// This abstraction allows users to choose between common control configurations +/// ranging from immutable tokens to fully administrator-controlled assets. #[derive(Serialize, Deserialize, Decode, Encode, Debug, Clone, PartialEq, Eq, PartialOrd)] pub struct TokenConfigurationPreset { - features: TokenConfigurationPresetFeatures, - action_taker: AuthorizedActionTakers, -} + /// Defines the set of capabilities enabled in this preset (e.g., whether minting, + /// burning, freezing, or emergency actions are permitted). + /// + /// The selected feature set determines the default rule behavior for all change control + /// and governance actions within the token configuration. + pub features: TokenConfigurationPresetFeatures, + /// The identity or group authorized to perform actions defined by the preset. + /// + /// This includes acting as the admin for various rule changes, executing allowed token + /// operations, or performing emergency control (depending on the selected feature set). + pub action_taker: AuthorizedActionTakers, +} impl TokenConfigurationPreset { pub fn default_main_control_group_can_be_modified(&self) -> AuthorizedActionTakers { match self.features { diff --git a/packages/rs-dpp/src/data_contract/associated_token/token_configuration_convention/mod.rs b/packages/rs-dpp/src/data_contract/associated_token/token_configuration_convention/mod.rs index fb4a4a98128..9c0d02ca4f1 100644 --- a/packages/rs-dpp/src/data_contract/associated_token/token_configuration_convention/mod.rs +++ b/packages/rs-dpp/src/data_contract/associated_token/token_configuration_convention/mod.rs @@ -8,9 +8,21 @@ pub mod accessors; pub mod methods; pub mod v0; +/// Versioned wrapper for token display conventions. +/// +/// `TokenConfigurationConvention` provides a flexible, forward-compatible structure +/// for representing human-readable metadata about a token, such as localized names +/// and decimal formatting standards. +/// +/// This enum enables evolution of the convention schema over time without breaking +/// compatibility with older tokens. Each variant defines a specific format version. #[derive(Serialize, Deserialize, Encode, Decode, Debug, Clone, PartialEq, Eq, PartialOrd, From)] #[serde(tag = "$format_version")] pub enum TokenConfigurationConvention { + /// Version 0 of the token convention schema. + /// + /// Defines localized names (by ISO 639 language codes) and the number of decimal places + /// used for displaying token amounts. #[serde(rename = "0")] V0(TokenConfigurationConventionV0), } diff --git a/packages/rs-dpp/src/data_contract/associated_token/token_configuration_convention/v0/mod.rs b/packages/rs-dpp/src/data_contract/associated_token/token_configuration_convention/v0/mod.rs index aa497f3561d..d571572679e 100644 --- a/packages/rs-dpp/src/data_contract/associated_token/token_configuration_convention/v0/mod.rs +++ b/packages/rs-dpp/src/data_contract/associated_token/token_configuration_convention/v0/mod.rs @@ -9,15 +9,30 @@ use std::fmt; pub const ENGLISH_ISO_639: &str = "en"; +/// Defines display conventions for a token, including name localization and decimal precision. +/// +/// `TokenConfigurationConventionV0` provides human-readable metadata to guide client applications +/// in rendering token names and formatting token values. This structure is purely informative +/// and does not affect consensus-critical logic or supply calculations. #[derive( Serialize, Deserialize, Decode, Encode, Debug, Clone, PartialEq, Eq, PartialOrd, Default, )] #[serde(rename_all = "camelCase")] pub struct TokenConfigurationConventionV0 { - /// Localizations for the token name. - /// The key must be a ISO 639 2-chars language code + /// A mapping of ISO 639-1 language codes (2-letter lowercase strings) to localized + /// token names and metadata. + /// + /// These localizations enable wallets and dApps to display token information in the + /// user's preferred language. At least one localization (e.g., English) is strongly recommended. #[serde(default)] pub localizations: BTreeMap, + + /// The number of decimal places used to represent the token. + /// + /// For example, a value of `8` means that one full token is represented as `10^8` base units + /// (similar to Bitcoin's satoshis or Dash's duffs). + /// + /// This value is used by clients to determine formatting and user interface display. #[serde(default = "default_decimals")] pub decimals: u16, } diff --git a/packages/rs-dpp/src/data_contract/associated_token/token_configuration_localization/mod.rs b/packages/rs-dpp/src/data_contract/associated_token/token_configuration_localization/mod.rs index 424d64b0115..66dd6785ab2 100644 --- a/packages/rs-dpp/src/data_contract/associated_token/token_configuration_localization/mod.rs +++ b/packages/rs-dpp/src/data_contract/associated_token/token_configuration_localization/mod.rs @@ -8,9 +8,21 @@ use std::fmt; pub mod accessors; pub mod v0; +/// Versioned wrapper for token name localization data. +/// +/// `TokenConfigurationLocalization` allows extensibility for future schema upgrades +/// while preserving backward compatibility. Each variant represents a specific format +/// version for localization information. +/// +/// This structure is used to map language codes to localized token names in a flexible, +/// forward-compatible manner. #[derive(Serialize, Deserialize, Encode, Decode, Debug, Clone, PartialEq, Eq, PartialOrd, From)] #[serde(tag = "$format_version")] pub enum TokenConfigurationLocalization { + /// Version 0 of the token localization schema. + /// + /// Defines basic capitalization preference, singular form, and plural form + /// for displaying token names. #[serde(rename = "0")] V0(TokenConfigurationLocalizationV0), } diff --git a/packages/rs-dpp/src/data_contract/associated_token/token_configuration_localization/v0/mod.rs b/packages/rs-dpp/src/data_contract/associated_token/token_configuration_localization/v0/mod.rs index 86521c1bc73..dae3dae9baa 100644 --- a/packages/rs-dpp/src/data_contract/associated_token/token_configuration_localization/v0/mod.rs +++ b/packages/rs-dpp/src/data_contract/associated_token/token_configuration_localization/v0/mod.rs @@ -4,11 +4,28 @@ use bincode::{Decode, Encode}; use serde::{Deserialize, Serialize}; use std::fmt; +/// Defines the localized naming format for a token in a specific language. +/// +/// `TokenConfigurationLocalizationV0` enables tokens to present user-friendly names +/// across different locales. This information is not used for validation or consensus +/// but enhances UX by allowing consistent display in multilingual interfaces. #[derive(Serialize, Deserialize, Decode, Encode, Debug, Clone, PartialEq, Eq, PartialOrd)] #[serde(rename_all = "camelCase")] pub struct TokenConfigurationLocalizationV0 { + /// Indicates whether the token name should be capitalized when displayed. + /// + /// This is a stylistic hint for clients (e.g., "Dash" vs. "dash") and is typically + /// applied to both singular and plural forms unless overridden. pub should_capitalize: bool, + + /// The singular form of the token name in the target language. + /// + /// Example: "Dash", "Dollar", or "Token". pub singular_form: String, + + /// The plural form of the token name in the target language. + /// + /// Example: "Dash", "Dollars", or "Tokens". pub plural_form: String, }