================================================================================
                     CARBONCORE DEVELOPER GUIDE #02
                    COMPLETE TERRITORY LIFECYCLE
================================================================================

OVERVIEW: Territory to Token in 17 Steps

================================================================================
STAGE 1: REGISTRATION
================================================================================

Step 1: Create UID Profile
    Contract: UserUID
    Function: createUserProfile()
    Parameters:
        - walletAddress
        - firstName, lastName
        - email, phoneNumber
        - physicalAddress
        - metadataURI
    Result: UID minted, LANDOWNER_ROLE assigned

Step 2: Register Territory
    Contract: TerritoryRegistry
    Function: registerTerritory()
    Parameters:
        - name
        - territoryType
        - boundaryGeoJson (polygon coordinates)
        - area (in hectares)
        - blockchainReference
    Result: Territory ID, Status = Pending

Step 3: Create Onboarding Request
    Contract: RequestManager
    Function: createTerritoryOnboardingRequest()
    Parameters:
        - territoryId
        - requestDetails (JSON)
    Result: Request ID, Status = PENDING
    Status Code: PENDING + Pending (Category 1)

================================================================================
STAGE 2: ONBOARDING & PAYMENT
================================================================================

Step 4: Admin Generates Invoice
    Action: Admin creates invoice
    Result: Status = COMPLETED + UnderExpertise (Category 2)
    Note: Territory awaiting payment

Step 5: Landowner Submits Payment
    Action: User pays invoice
    Result: Status = COMPLETED + Pending (Category 3)
    Note: Payment verification pending

Step 6: Admin Confirms Payment
    Action: Admin validates payment
    Result: Status = REVISION + Pending (Category 4)
    Note: Ready for expert assignment

================================================================================
STAGE 3: EXPERT VERIFICATION
================================================================================

Step 7: Expert Claims Territory
    Contract: TerritoryRegistry
    Function: claimForVerification()
    Requirements: EXPERT_ROLE
    Result: Status = REVISION + UnderExpertise (Category 5)

Step 8: Expert Submits Verification
    Contract: TerritoryRegistry
    Function: submitVerification()
    Parameters:
        - territoryId
        - reportUri
        - oxygenProduction
        - co2Absorption (KEY PARAMETER)
        - approved (boolean)
        - notes
    Result: Status = REVISION + ExpertVerified (Category 6)
    Note: CO2 data determines daily token rate

================================================================================
STAGE 4: GOVERNMENT VALIDATION
================================================================================

Step 9: Admin Confirms Expertise
    Action: Admin reviews expert report
    Result: Status = APPROVED + ExpertVerified (Category 7)

Step 10: VVB Validation
    Contract: TerritoryRegistry
    Function: submitGovernmentVerification()
    Requirements: GOVERNMENT_ROLE
    Parameters:
        - territoryId
        - reportUri
        - approved (boolean)
        - validityPeriod (in seconds)
        - notes
    Result: Status = APPROVED + GovernmentVerified (Category 8)

Step 11: Admin Final Approval
    Action: Admin authorizes tokenization
    Result: Status = COMPLETED + GovernmentVerified (Category 9)
    Note: Territory now ISSUANCE-READY

================================================================================
STAGE 5: PROJECT CREATION & TOKENIZATION
================================================================================

Step 12: Create Carbon Project
    Contract: CarbonCreditFactory
    Function: createProject()
    Parameters:
        - territoryId
        - vintageYear
        - locationName
    Requirements:
        - Territory status = GovernmentVerified
        - Valid CO2 absorption data
        - Caller must be territory owner
    Process:
        1. Verify territory readiness
        2. Create ERC-20 token via TerritoryTokenFactory
        3. Calculate dailyRate = (co2Absorption * 1e18) / 365
        4. Register project with token address
        5. Set UID-based beneficiary
    Result: Project ID, Token Address, Status = HAS_ACTIVE_PROJECT (Category 10)

Step 13: Token Deployment
    Contract: TerritoryTokenFactory (automatic)
    Creates: TerritoryToken (ERC-20)
    Name: "CarbonCore Territory {id} - {year}"
    Symbol: "CCT{id}-{year}"
    Decimals: 18
    Metadata:
        - territoryId
        - vintageYear
        - annualAbsorption
        - locationName

================================================================================
STAGE 6: AUTOMATED TOKEN ISSUANCE
================================================================================

Step 14: First Token Issuance (Immediate)
    Time: Project creation timestamp
    Amount: 0 (initial state)
    Note: lastIssuanceTime set to block.timestamp

Step 15: Daily Automatic Issuance
    Contract: CarbonCreditFactory
    Function: issueCredits() (PUBLIC - anyone can call)
    Frequency: Every 24+ hours
    Process:
        1. Check project active status
        2. Verify minimum 24h interval passed
        3. Calculate days elapsed (max 90 days)
        4. Calculate tokens: dailyRate * daysElapsed
        5. Get UID-based beneficiary
        6. Mint tokens to beneficiary address
        7. Update lastIssuanceTime
    Result: Tokens minted to UID owner

Step 16: Token Distribution
    Recipient: Current owner of beneficiary UID
    Note: If UID transferred, new owner receives tokens

Step 17: Ongoing Operation
    Status: HAS_ACTIVE_PROJECT (Category 10)
    Monitoring: Track for renewal (30 days before expiry)
    Renewal Status: NEEDS_RENEWAL (Category 11)

================================================================================
TOKEN CALCULATION EXAMPLE
================================================================================

Territory: 24 (Honduras Forest)
Annual CO2: 94,000,000 kg/year
Daily Rate: 94,000,000 / 365 = 257,534.247 kg/day
Token Rate: 257,534.247 * 1e18 wei/day

After 1 day:   257,534 tokens
After 7 days:  1,802,740 tokens
After 30 days: 7,726,027 tokens
After 90 days: 23,178,082 tokens (max accumulation)
After 365 days: 94,000,000 tokens

================================================================================
STATUS PROGRESSION SUMMARY
================================================================================

1.  PENDING + Pending               - Initial Appraisal
2.  COMPLETED + UnderExpertise      - Awaiting Payment
3.  COMPLETED + Pending             - Payment Verification
4.  REVISION + Pending              - Under Technical Expertise
5.  REVISION + UnderExpertise       - Active Expert Appraisal
6.  REVISION + ExpertVerified       - Pending Expertise Confirmation
7.  APPROVED + ExpertVerified       - Under VVB Validation
8.  APPROVED + GovernmentVerified   - Ready for Credit Issuance
9.  COMPLETED + GovernmentVerified  - Issuance-Ready (CAN CREATE PROJECT)
10. ARCHIVED + GovernmentVerified   - Has Active Project (HAS TOKENS)
11. ARCHIVED + GovernmentVerified   - Needs Renewal (< 30 days)

================================================================================