From 1425533647073bf209c5f0d045fdd50887a8f8c8 Mon Sep 17 00:00:00 2001 From: truthixify Date: Sat, 9 Aug 2025 15:57:17 +0100 Subject: [PATCH] added documentation for core contract --- src/contracts/core.cairo | 72 ++++++++++++++++++++++++++++++++++++++ src/interfaces/icore.cairo | 30 ++++++++++++++++ 2 files changed, 102 insertions(+) diff --git a/src/contracts/core.cairo b/src/contracts/core.cairo index bd9fdc4..602abc9 100644 --- a/src/contracts/core.cairo +++ b/src/contracts/core.cairo @@ -1,3 +1,17 @@ +/// ## A Starknet contract that acts as the central hub for an organization. +/// +/// This core contract integrates multiple components to manage a complete organizational structure. +/// It is responsible for: +/// - Initializing all components with the organization's details. +/// - Coordinating high-level workflows, such as payroll and disbursements. +/// - Acting as the primary entry point for managing the organization. +/// +/// It brings together the following components: +/// - `MemberManagerComponent`: For handling member data and roles. +/// - `OrganizationComponent`: For storing general organization metadata. +/// - `VotingComponent`: For governance and proposals. +/// - `DisbursementComponent`: For managing payment schedules and calculations. +/// - `OwnableComponent` and `UpgradeableComponent`: For access control and contract upgrades. #[starknet::contract] mod Core { use MemberManagerComponent::MemberInternalTrait; @@ -46,37 +60,52 @@ mod Core { impl DisbursementInternalImpl = DisbursementComponent::InternalImpl; + /// Defines the storage layout for the `Core` contract. #[storage] #[allow(starknet::colliding_storage_paths)] struct Storage { + /// The address of the associated vault contract. vault_address: ContractAddress, + /// Substorage for the MemberManager component. #[substorage(v0)] member: MemberManagerComponent::Storage, //my component + /// Substorage for the Ownable component. #[substorage(v0)] ownable: OwnableComponent::Storage, + /// Substorage for the Upgradeable component. #[substorage(v0)] upgradeable: UpgradeableComponent::Storage, + /// Substorage for the Organization component. #[substorage(v0)] organization: OrganizationComponent::Storage, //my component + /// Substorage for the Voting component. #[substorage(v0)] voting: VotingComponent::Storage, //my component + /// Substorage for the Disbursement component. #[substorage(v0)] disbursement: DisbursementComponent::Storage //my component } + /// Events emitted by the `Core` contract, including events from all its components. #[event] #[derive(Drop, starknet::Event)] enum Event { + /// Emits member-related events. #[flat] MemberEvent: MemberManagerComponent::Event, + /// Emits ownable-related events. #[flat] OwnableEvent: OwnableComponent::Event, + /// Emits upgradeable-related events. #[flat] UpgradeableEvent: UpgradeableComponent::Event, + /// Emits organization-related events. #[flat] OrganizationEvent: OrganizationComponent::Event, + /// Emits voting-related events. #[flat] VotingEvent: VotingComponent::Event, + /// Emits disbursement-related events. #[flat] DisbursementEvent: DisbursementComponent::Event, } @@ -88,6 +117,20 @@ mod Core { // pub lastname: felt252, // } + /// Initializes the Core contract and all its integrated components. + /// + /// ### Parameters + /// - `org_id`: A unique identifier for the organization. + /// - `org_name`: The name of the organization. + /// - `owner`: The address of the initial owner and first admin. + /// - `ipfs_url`: A URL pointing to organization metadata (e.g., on IPFS). + /// - `vault_address`: The address of the organization's vault contract. + /// - `first_admin_fname`: First name of the initial admin. + /// - `first_admin_lname`: Last name of the initial admin. + /// - `first_admin_alias`: Alias of the initial admin. + /// - `deployer`: The address of the contract deployer. + /// - `organization_type`: A numerical identifier for the type of organization. + /// - `factory`: The address of the factory contract that deployed this core contract. #[constructor] fn constructor( ref self: ContractState, @@ -138,6 +181,13 @@ mod Core { #[abi(embed_v0)] impl UpgradeableImpl of IUpgradeable { + /// Upgrades the contract to a new class hash. + /// + /// ### Parameters + /// - `new_class_hash`: The class hash of the new contract implementation. + /// + /// ### Panics + /// - If the caller is not the owner. fn upgrade(ref self: ContractState, new_class_hash: ClassHash) { // This might be upgraded from the factory self.ownable.assert_only_owner(); @@ -149,8 +199,19 @@ mod Core { // TODO: DO TRANSFER FROM HERE WHEN YOU WANT TO PAYOUT + /// # CoreImpl + /// + /// Public-facing implementation of the `ICore` interface. #[abi(embed_v0)] impl CoreImpl of ICore { + /// Initializes a new disbursement schedule. This function is a pass-through + /// to the Disbursement component. + /// + /// ### Parameters + /// - `schedule_type`: Type of schedule (e.g., weekly, monthly). + /// - `start`: Unix timestamp for the schedule's start time. + /// - `end`: Unix timestamp for the schedule's end time. + /// - `interval`: Payout interval in seconds. fn initialize_disbursement_schedule( ref self: ContractState, schedule_type: u8, @@ -162,6 +223,17 @@ mod Core { self.disbursement._initialize(schedule_type, start, end, interval) } + /// Executes a scheduled payout to all members. + /// + /// This function calculates the total weight of all members based on their roles, + /// determines each member's share of the available funds and bonus allocation, + /// and instructs the vault to transfer the corresponding amounts. + /// + /// ### Panics + /// - If there is no active disbursement schedule. + /// - If the payout is attempted before the scheduled start time or after the end time. + /// - If the payout is attempted before the required interval has passed since the last + /// execution. fn schedule_payout(ref self: ContractState) { let caller = get_caller_address(); let members = self.member.get_members(); diff --git a/src/interfaces/icore.cairo b/src/interfaces/icore.cairo index bcc8f84..a3ab5f5 100644 --- a/src/interfaces/icore.cairo +++ b/src/interfaces/icore.cairo @@ -1,7 +1,37 @@ +/// # ICore +/// +/// This trait defines the public interface for the central core contract of an organization. +/// It orchestrates high-level functions that involve multiple components, such as scheduling +/// and executing payroll for all members. This interface is designed to be implemented by a +/// contract that acts as the main hub, coordinating the actions of member management, +/// disbursement, and vault components. #[starknet::interface] pub trait ICore { // fn add_admin(ref self: T, member_id: u256); + + /// # schedule_payout + /// + /// Triggers the disbursement process for all eligible members based on the active + /// payment schedule. It calculates each member's share and initiates the payment + /// from the organization's vault. + /// + /// ## Parameters + /// + /// - `ref self: T`: The current state of the contract. fn schedule_payout(ref self: T); + + /// # initialize_disbursement_schedule + /// + /// Sets up a new disbursement schedule for the organization. + /// + /// ## Parameters + /// + /// - `ref self: T`: The current state of the contract. + /// - `schedule_type`: A numerical value representing the type of schedule (e.g., weekly, + /// monthly). + /// - `start`: The Unix timestamp when the schedule becomes active. + /// - `end`: The Unix timestamp when the schedule expires. + /// - `interval`: The duration in seconds between each payout execution. fn initialize_disbursement_schedule( ref self: T, schedule_type: u8, //schedule_id: felt252,