diff --git a/src/components/organization.cairo b/src/components/organization.cairo index a3069d6..e203406 100644 --- a/src/components/organization.cairo +++ b/src/components/organization.cairo @@ -1,3 +1,10 @@ +/// ## A Starknet component responsible for managing the core details of an organization. +/// +/// This component handles: +/// - Storing fundamental organization information (name, ID, owner, etc.). +/// - Managing a committee of privileged addresses. +/// - Handling organization-level configuration. +/// - Ownership transfers. #[starknet::component] pub mod OrganizationComponent { use starknet::storage::{Map, StoragePointerReadAccess, StoragePointerWriteAccess}; @@ -11,18 +18,27 @@ pub mod OrganizationComponent { use super::super::member_manager::MemberManagerComponent; + /// Defines the storage layout for the `OrganizationComponent`. #[storage] pub struct Storage { + /// The address of the contract deployer. pub deployer: ContractAddress, + /// Maps a committee member's address to their power level or rank. pub commitee: Map, // address -> level of power + /// The configuration node for the organization. pub config: OrganizationConfigNode, // refactor to OrganizationConfig + /// Struct containing the core information of the organization. pub org_info: OrganizationInfo, } + /// Events emitted by the `OrganizationComponent`. #[event] #[derive(Drop, starknet::Event)] pub enum Event {} + /// # OrganizationManager + /// + /// Public-facing implementation of the `IOrganization` interface. #[embeddable_as(OrganizationManager)] pub impl Organization< TContractState, @@ -30,9 +46,26 @@ pub mod OrganizationComponent { +Drop, impl Member: MemberManagerComponent::HasComponent, > of IOrganization> { + /// Transfers the claim of the organization to a new address. + /// + /// ### Note + /// This function is not yet implemented. + /// + /// ### Parameters + /// - `to`: The address of the new owner. fn transfer_organization_claim( ref self: ComponentState, to: ContractAddress, ) {} + + /// Adjusts the organization's committee by adding or removing members. + /// + /// ### Note + /// This function is not yet implemented. Any subtracted member would have their power level + /// set to zero. + /// + /// ### Parameters + /// - `add`: An array of addresses to add to the committee. + /// - `subtract`: An array of addresses to remove from the committee. fn adjust_committee( ref self: ComponentState, add: Array, @@ -40,20 +73,47 @@ pub mod OrganizationComponent { ) { // any one subtracted, power would be taken down to zero. } + /// Updates the organization's configuration. + /// + /// ### Note + /// This function is not yet implemented. + /// + /// ### Parameters + /// - `config`: The new organization configuration. fn update_organization_config( ref self: ComponentState, config: OrganizationConfig, ) {} + + /// Retrieves the core details of the organization. + /// + /// ### Returns + /// - `OrganizationInfo`: A struct containing the organization's details. fn get_organization_details(self: @ComponentState) -> OrganizationInfo { self.org_info.read() } } + /// # InternalImpl + /// + /// Internal functions for initialization and privileged operations. #[generate_trait] pub impl InternalImpl< TContractState, +HasComponent, // +Drop, // impl Member: MemberManagerComponent::HasComponent, > of OrganizationInternalTrait { + /// Initializes the organization component with its essential data. + /// + /// ### Parameters + /// - `owner`: An optional address for the organization's owner. If `None`, the caller + /// becomes the owner. + /// - `name`: The name of the organization. + /// - `ipfs_url`: A URL pointing to more detailed organization metadata (e.g., on IPFS). + /// - `vault_address`: The address of the organization's treasury or vault contract. + /// - `org_id`: A unique identifier for the organization. + /// - `deployer`: The address of the account or contract that deployed this component. + /// - `organization_type`: A numeric code for the organization type (0 for Centralized, 1 + /// for Decentralized). fn _init( ref self: ComponentState, owner: Option, diff --git a/src/interfaces/iorganization.cairo b/src/interfaces/iorganization.cairo index 1c8a365..700a413 100644 --- a/src/interfaces/iorganization.cairo +++ b/src/interfaces/iorganization.cairo @@ -2,12 +2,57 @@ use starknet::ContractAddress; use crate::structs::organization::{OrganizationConfig, OrganizationInfo}; // Some functions here might require multiple signing to execute. +/// # IOrganization +/// +/// This trait defines the public interface for an organization component. +/// It outlines functions for managing high-level organizational settings, +/// such as ownership, committee members, and configuration. In a production +/// environment, sensitive functions might be protected by multi-signature checks. #[starknet::interface] pub trait IOrganization { + /// # transfer_organization_claim + /// + /// Transfers ownership of the organization to a new address. + /// + /// ## Parameters + /// + /// - `ref self: TContractState`: The current state of the contract. + /// - `to`: The `ContractAddress` of the new owner. fn transfer_organization_claim(ref self: TContractState, to: ContractAddress); + + /// # adjust_committee + /// + /// Modifies the composition of the organization's governing committee. + /// + /// ## Parameters + /// + /// - `ref self: TContractState`: The current state of the contract. + /// - `add`: An `Array` of `ContractAddress` to be added to the committee. + /// - `subtract`: An `Array` of `ContractAddress` to be removed from the committee. fn adjust_committee( ref self: TContractState, add: Array, subtract: Array, ); + + /// # update_organization_config + /// + /// Updates the general configuration settings for the organization. + /// + /// ## Parameters + /// + /// - `ref self: TContractState`: The current state of the contract. + /// - `config`: An `OrganizationConfig` struct containing the new configuration values. fn update_organization_config(ref self: TContractState, config: OrganizationConfig); + + /// # get_organization_details + /// + /// Retrieves the fundamental information about the organization. + /// + /// ## Parameters + /// + /// - `self: @TContractState`: A snapshot of the contract's state. + /// + /// ## Returns + /// + /// An `OrganizationInfo` struct containing the organization's details. fn get_organization_details(self: @TContractState) -> OrganizationInfo; }