================================================================================ CARBONCORE DEVELOPER GUIDE #05 14-STAGE PROJECT STATUS SYSTEM ================================================================================ PRINCIPLE: Combined RequestManager + TerritoryRegistry status matrix ================================================================================ STATUS MATRIX OVERVIEW ================================================================================ Categories: 14 distinct project states Source: RequestManagerStatus + TerritoryRegistryStatus Purpose: Precise lifecycle tracking from submission to production Phase Distribution: Onboarding (1-3): Initial submission and payment Verification (4-6): Expert technical assessment Validation (7-8): VVB and government approval Ready (9): Prepared for tokenization Production (10-11): Active token generation Final (12-14): Terminated or modified states ================================================================================ CATEGORY 1: INITIAL APPRAISAL ================================================================================ Status Combination: PENDING + Pending Code: initial-appraisal Phase: Onboarding Description: New territory parcel submitted for initial administrative review and baseline assessment, pending invoice generation. Conditions: - RequestManager status = PENDING (0) - Territory status = Pending (0) Actions Available: - Admin: Generate invoice - User: Wait for admin review Next State: Category 2 (after invoice generation) ================================================================================ CATEGORY 2: AWAITING PROPONENT PAYMENT ================================================================================ Status Combination: COMPLETED + UnderExpertise Code: awaiting-payment Phase: Onboarding Description: Invoice generated by Admin; request is pending payment settlement by the territory proponent. Conditions: - RequestManager status = COMPLETED (5) - Territory status = UnderExpertise (1) - Invoice exists Actions Available: - User: Submit payment - Admin: Cancel invoice UI Indicators: - Payment amount displayed - Payment instructions - Invoice download link Next State: Category 3 (after payment submission) ================================================================================ CATEGORY 3: PAYMENT VERIFICATION ================================================================================ Status Combination: COMPLETED + Pending Code: payment-verification Phase: Onboarding Description: Payment submitted by the proponent, now awaiting confirmation and clearance from the Administrator. Conditions: - RequestManager status = COMPLETED (5) - Territory status = Pending (0) - Payment proof submitted Actions Available: - Admin: Confirm payment - Admin: Reject payment (back to Category 2) UI Indicators: - "Payment under review" badge - Estimated review time Next State: Category 4 (after payment confirmation) ================================================================================ CATEGORY 4: UNDER TECHNICAL EXPERTISE ================================================================================ Status Combination: REVISION + Pending Code: under-technical-expertise Phase: Verification Description: Payment confirmed. Territory parcel is now undergoing technical assessment by a designated expert. Conditions: - RequestManager status = REVISION (3) - Territory status = Pending (0) - Payment confirmed Actions Available: - Expert: Claim for verification - User: Wait for expert assignment UI Indicators: - "Awaiting expert assignment" status - Expected assignment timeframe Next State: Category 5 (after expert claims) ================================================================================ CATEGORY 5: ACTIVE EXPERT APPRAISAL ================================================================================ Status Combination: REVISION + UnderExpertise Code: active-expert-appraisal Phase: Verification Description: The expert has engaged the territory parcel, and the technical due diligence is actively in progress. Conditions: - RequestManager status = REVISION (3) - Territory status = UnderExpertise (1) - Expert assigned Actions Available: - Expert: Submit verification report - Expert: Request additional information - User: Provide requested documents UI Indicators: - Expert name/contact - Progress indicator - Time elapsed since claim Next State: Category 6 (after expert submits report) ================================================================================ CATEGORY 6: PENDING EXPERTISE CONFIRMATION ================================================================================ Status Combination: REVISION + ExpertVerified Code: pending-expertise-confirmation Phase: Verification Description: Expert appraisal is complete, awaiting final review and sign-off from the Administrator. Conditions: - RequestManager status = REVISION (3) - Territory status = ExpertVerified (2) - Expert report submitted - CO2 data present Actions Available: - Admin: Confirm expertise - Admin: Request revisions UI Indicators: - "Admin review pending" badge - Expert report summary - CO2 absorption data preview Next State: Category 7 (after admin confirms) ================================================================================ CATEGORY 7: UNDER VVB VALIDATION ================================================================================ Status Combination: APPROVED + ExpertVerified Code: under-vvb-validation Phase: Validation Description: Territory submitted to an accredited Validation and Verification Body (VVB) for independent audit. Conditions: - RequestManager status = APPROVED (1) - Territory status = ExpertVerified (2) - Admin confirmed expertise Actions Available: - VVB: Submit validation - User: Provide additional documents UI Indicators: - VVB entity name - Validation progress - Expected completion date Next State: Category 8 (after VVB validation) ================================================================================ CATEGORY 8: READY FOR CREDIT ISSUANCE ================================================================================ Status Combination: APPROVED + GovernmentVerified Code: ready-for-credit-issuance Phase: Validation Description: VVB validation confirmed. Awaiting final administrative approval to proceed with automated credit generation. Conditions: - RequestManager status = APPROVED (1) - Territory status = GovernmentVerified (3) - VVB validation complete - Validity period set Actions Available: - Admin: Final approval for tokenization - User: Wait for approval UI Indicators: - "Final approval pending" status - Validation certificate preview - Validity period display Next State: Category 9 (after admin final approval) ================================================================================ CATEGORY 9: ISSUANCE-READY (ACTIVE) ================================================================================ Status Combination: COMPLETED + GovernmentVerified Code: issuance-ready Phase: Ready Special Flag: canCreateProject = true Description: Fully validated. Territory is active for the proponent to initiate a credit minting contract. Conditions: - RequestManager status = COMPLETED (5) - Territory status = GovernmentVerified (3) - All validations complete - No project created yet Actions Available: - User: Create carbon project (⭐ KEY ACTION) - User: View all validation documents UI Indicators: - "CREATE PROJECT" button (prominent) - Green success badge - Ready status icon Next State: Category 10 (after project creation) Implementation: if (status.canCreateProject) { showCreateProjectButton(); } ================================================================================ CATEGORY 10: ACTIVE CARBON PROJECT ================================================================================ Status Combination: ARCHIVED + GovernmentVerified + hasProject Code: has-active-project Phase: Production Special Flag: hasTokens = true Description: Territory has active carbon credit project with automatic token issuance every 24 hours. Conditions: - RequestManager status = ARCHIVED (6) - Territory status = GovernmentVerified (3) - Project created - Token contract deployed Actions Available: - Anyone: Trigger token issuance (issueCredits) - User: Manage tokens - User: View analytics - User: List tokens for sale UI Indicators: - Active project badge - Token symbol display - Next issuance countdown - Total tokens issued Next State: Category 11 (if verification expiring) Implementation: if (territory.tokens && territory.tokens.length > 0) { status = PROJECT_STATUSES.HAS_ACTIVE_PROJECT; } ================================================================================ CATEGORY 11: RENEWAL REQUIRED ================================================================================ Status Combination: ARCHIVED + GovernmentVerified + hasProject + expiring Code: needs-renewal Phase: Maintenance Special Flag: requiresAction = true Description: Project validation expires within 30 days, renewal process required to continue token issuance. Conditions: - RequestManager status = ARCHIVED (6) - Territory status = GovernmentVerified (3) - Project active - verificationExpiresAt < 30 days Actions Available: - User: Initiate renewal process - User: Continue token claims - Admin: Process renewal UI Indicators: - Orange warning badge - Days until expiry - "RENEW NOW" button - Renewal instructions Calculation: const now = Math.floor(Date.now() / 1000); const expirationTime = territory.verificationExpiresAt; const daysUntilExpiration = (expirationTime - now) / (24 * 60 * 60); if (daysUntilExpiration > 0 && daysUntilExpiration <= 30) { return PROJECT_STATUSES.NEEDS_RENEWAL; } ================================================================================ CATEGORY 12: REJECTED ================================================================================ Status Combination: REJECTED + Rejected Code: rejected Phase: Final Special Flag: final = true Description: Territory or validation rejected during review process. No further progression possible. Conditions: - RequestManager status = REJECTED (2) OR Territory status = Rejected (4) Actions Available: - User: View rejection reasons - User: Submit new territory (fresh start) UI Indicators: - Red rejection badge - Rejection reason display - Appeal process info (if applicable) Next State: None (terminal state) ================================================================================ CATEGORY 13: INACTIVE ================================================================================ Status Combination: ARCHIVED + Inactive Code: inactive Phase: Final Special Flag: final = true Description: Territory deactivated or suspended. Token issuance stopped. Conditions: - RequestManager status = ARCHIVED (6) - Territory status = Inactive (5) Reasons for Inactivity: - User-requested deactivation - Compliance violation - Verification expired (no renewal) - Administrative suspension Actions Available: - User: View deactivation reason - User: Request reactivation (if eligible) UI Indicators: - Gray inactive badge - Deactivation reason - Reactivation eligibility status ================================================================================ CATEGORY 14: TERRITORY MODIFIED ================================================================================ Status Combination: ARCHIVED + Split/Merged/Extended Code: territory-modified Phase: Final Special Flag: final = true Description: Territory has been split, merged, or extended into new territories. Original territory retired. Conditions: - RequestManager status = ARCHIVED (6) - Territory status in [Split (6), Merged (7), Extended (8)] Modification Types: Split: One territory → Multiple child territories Merge: Multiple territories → One combined territory Extend: Original territory + New area → New extended territory Actions Available: - User: View modification history - User: Navigate to child/parent territories - User: View relationship tree UI Indicators: - Modification type badge - Link to new territory IDs - Modification date - Historical data preserved ================================================================================ STATUS DETERMINATION FUNCTION ================================================================================ Function: determineProjectStatus(territory, onboardingRequest, hasTokens) Logic Flow: 1. Check for tokens (Category 10-11) IF hasTokens OR territory.tokens.length > 0: IF verificationExpiring: RETURN NEEDS_RENEWAL ELSE: RETURN HAS_ACTIVE_PROJECT 2. Check for rejection (Category 12) IF territory.status === 'Rejected' OR request.status === 'REJECTED': RETURN REJECTED 3. Check for inactivity (Category 13) IF territory.status === 'Inactive': RETURN INACTIVE 4. Check for modification (Category 14) IF territory.status IN ['Split', 'Merged', 'Extended']: RETURN TERRITORY_MODIFIED 5. Status matrix lookup (Category 1-9) requestStatus = request.status OR 'PENDING' territoryStatus = territory.status OR 'Pending' statusKey = `${requestStatus}+${territoryStatus}` SWITCH statusKey: 'PENDING+Pending': RETURN INITIAL_APPRAISAL 'COMPLETED+UnderExpertise': RETURN AWAITING_PAYMENT 'COMPLETED+Pending': RETURN PAYMENT_VERIFICATION 'REVISION+Pending': RETURN UNDER_TECHNICAL_EXPERTISE 'REVISION+UnderExpertise': RETURN ACTIVE_EXPERT_APPRAISAL 'REVISION+ExpertVerified': RETURN PENDING_EXPERTISE_CONFIRMATION 'APPROVED+ExpertVerified': RETURN UNDER_VVB_VALIDATION 'APPROVED+GovernmentVerified': RETURN READY_FOR_CREDIT_ISSUANCE 'COMPLETED+GovernmentVerified': RETURN ISSUANCE_READY ================================================================================ UI INTEGRATION ================================================================================ Status Badge Display:
{label}
CSS Classes: .status-initial-appraisal { background: #ff9800; } .status-awaiting-payment { background: #f44336; } .status-payment-verification { background: #ff5722; } .status-under-technical-expertise { background: #2196f3; } .status-active-expert-appraisal { background: #03a9f4; } .status-pending-expertise-confirmation { background: #00bcd4; } .status-under-vvb-validation { background: #009688; } .status-ready-for-credit-issuance { background: #4caf50; } .status-issuance-ready { background: #8bc34a; } .status-has-active-project { background: #cddc39; color: black; } .status-needs-renewal { background: #ffeb3b; color: black; } .status-rejected { background: #f44336; } .status-inactive { background: #9e9e9e; } .status-territory-modified { background: #795548; } Territory Grouping: function groupTerritoriesByCategory(territories) { const groups = { onboarding: [], // categories 1-3 verification: [], // categories 4-6 validation: [], // categories 7-8 ready: [], // category 9 production: [], // categories 10-11 final: [] // categories 12-14 }; territories.forEach(territory => { const status = determineProjectStatus(...); if (status.category <= 3) { groups.onboarding.push(territory); } else if (status.category <= 6) { groups.verification.push(territory); } // ... etc }); return groups; } Available Actions: function getAvailableActions(territory) { const status = determineProjectStatus(...); const actions = []; switch (status.code) { case 'awaiting-payment': actions.push({ type: 'payment', label: 'Pay Invoice', icon: 'credit-card' }); break; case 'issuance-ready': if (status.canCreateProject) { actions.push({ type: 'mint', label: 'Create Project', icon: 'coins', primary: true }); } break; case 'has-active-project': actions.push({ type: 'manage-tokens', label: 'Manage Tokens', icon: 'coins' }); actions.push({ type: 'view-analytics', label: 'Analytics', icon: 'chart-line' }); break; case 'needs-renewal': actions.push({ type: 'renew', label: 'Renew Validation', icon: 'refresh', urgent: true }); break; } // Universal action actions.push({ type: 'details', label: 'View Details', icon: 'eye' }); return actions; } ================================================================================