# Territory Management Guide - CarbonCore Documentation

## Overview
Complete guide for territory registration, verification, and lifecycle management on CarbonCore platform.

## Prerequisites
- Connected Web3 wallet (MetaMask, etc.)
- NFT profile created
- LANDOWNER_ROLE (automatically assigned on registration)

## Territory Registration Process

### Step 1: Prepare Territory Data
**Required Information**:
- Territory name
- Territory type (Forest, Wetland, etc.)
- Geographic boundaries (GeoJSON format)
- Total area in hectares
- Supporting documents

**Geographic Data**:
```javascript
// Use Leaflet.js to draw polygon
const boundary = {
  "type": "Feature",
  "geometry": {
    "type": "Polygon",
    "coordinates": [[[lon, lat], [lon, lat], ...]]
  }
};
```

### Step 2: Register Territory
```javascript
const tx = await territoryRegistry.registerTerritory(
    "Amazon Conservation Alpha",  // name
    "Forest",                      // territoryType
    JSON.stringify(boundary),      // boundaryGeoJson
    1000,                          // area in hectares
    "ipfs://QmHash..."            // blockchainReference
);

const receipt = await tx.wait();
const territoryId = extractTerritoryId(receipt);
```

### Step 3: Create Onboarding Request
After registration, create onboarding request through platform UI.

**Request Process**:
1. Submit territory for review
2. Admin generates invoice
3. Pay invoice
4. Wait for payment confirmation

## Territory Status Lifecycle

### Status Flow Chart
```
Pending → UnderExpertise → ExpertVerified → GovernmentVerified → Active
```

### Status Descriptions

**1. Pending (0)**
- Just registered
- Waiting for admin review
- Action: Wait for invoice

**2. UnderExpertise (1)**
- Invoice generated or expert claimed
- Action: Pay invoice OR wait for expert assessment

**3. ExpertVerified (2)**
- Expert completed assessment
- CO2 absorption data submitted
- Action: Wait for government validation

**4. GovernmentVerified (3)**
- Fully validated
- Ready for project creation
- Action: Create carbon credit project

**5. Rejected (4)**
- Verification failed
- Action: Review rejection reason, fix issues, resubmit

**6. Inactive (5)**
- Deactivated or expired
- Action: Renew validation or reactivate

## Payment Process

### Invoice Payment
1. Receive invoice from admin (via email/platform)
2. Navigate to payment section
3. Submit payment proof
4. Wait for confirmation (status: COMPLETED + Pending)

### Payment Methods
- Wire transfer
- Cryptocurrency
- Credit card (if enabled)

## Expert Verification

### Expert Assessment Process
**Expert Actions**:
1. Claims territory for verification
2. Conducts field assessment
3. Analyzes CO2 absorption capacity
4. Submits verification report

**Verification Data**:
- Oxygen production (kg/year)
- **CO2 absorption (kg/year)** ⭐ KEY METRIC
- Report URI (IPFS/Arweave)
- Approval status
- Notes

```javascript
await territoryRegistry.submitVerification(
    territoryId,
    "ipfs://QmReport...",  // reportUri
    50000000,              // oxygenProduction
    94000000,              // co2Absorption
    true,                  // approved
    "All requirements met"
);
```

## Government/VVB Validation

### Validation Process
1. Expert verification reviewed
2. VVB conducts independent audit
3. Government entity validates
4. Validity period set (typically 1 year)

```javascript
await territoryRegistry.submitGovernmentVerification(
    territoryId,
    "ipfs://QmValidation...",  // reportUri
    true,                        // approved
    31536000,                    // validityPeriod (1 year in seconds)
    "Compliant with all standards"
);
```

### Validation Expiration
- Check expiration: `territory.verificationExpiresAt`
- Renewal required 30 days before expiration
- Status indicator shows "Needs Renewal"

## Territory Modifications

### Split Territory
Divide one territory into multiple parcels:
```javascript
await territoryRegistry.splitTerritory(
    originalTerritoryId,
    ["Parcel A", "Parcel B"],          // names
    [boundaryA, boundaryB],            // geometries
    [500, 500],                        // areas
    ["ref A", "ref B"]                 // references
);
```

### Merge Territories
Combine multiple territories:
```javascript
await territoryRegistry.mergeTerritories(
    [territoryId1, territoryId2],      // territories to merge
    "Merged Conservation Area",        // new name
    mergedBoundary,                    // combined geometry
    1000,                              // total area
    "merged reference"
);
```

### Extend Territory
Add adjacent area to existing territory:
```javascript
await territoryRegistry.extendTerritory(
    originalTerritoryId,
    "Extended Conservation Area",
    extendedBoundary,
    1500,                              // new total area
    "extension reference"
);
```

## Territory Updates

### Update Territory Data
```javascript
await territoryRegistry.updateTerritory(
    territoryId,
    newName,
    newType,
    newBoundary,
    newArea,
    newReference
);
```

**Limitations**:
- Cannot change owner
- Cannot modify if project exists
- Some fields locked after verification

## Deactivation

### Deactivate Territory
```javascript
await territoryRegistry.deactivateTerritory(territoryId);
```

**Effects**:
- Status → Inactive
- Cannot create new projects
- Existing projects may continue

## Best Practices

### Geographic Data
1. Use accurate GPS coordinates
2. Verify boundary doesn't overlap others
3. Use appropriate CRS (EPSG:4326)
4. Validate GeoJSON format

### Documentation
1. Upload high-quality documents
2. Use permanent storage (IPFS/Arweave)
3. Include verification reports
4. Keep ownership proof

### Communication
1. Respond to admin requests promptly
2. Provide expert access if needed
3. Monitor status changes
4. Keep contact info updated

### Financial
1. Pay invoices on time
2. Keep payment receipts
3. Understand fee structure
4. Plan for renewal costs

## Troubleshooting

### Common Issues

**Issue**: Transaction fails
**Solution**: Check gas fees, wallet balance, network connection

**Issue**: Territory not appearing
**Solution**: Wait for blockchain confirmation, refresh page

**Issue**: Cannot create project
**Solution**: Verify status is GovernmentVerified

**Issue**: Verification expired
**Solution**: Submit renewal request, wait for re-validation

### Getting Help
- Support: info@carboncore.earth
- Documentation: docs.carboncore.earth
- Discord: discord.gg/carboncore

---

**Document Version**: 2.0
**Last Updated**: January 2025