localgreenchain/docs/architecture/user-blockchain.md

# User Blockchain Architecture

Every user in LocalGreenChain operates their own blockchain, creating a decentralized network of plant lineage and transport records that collectively form a global agricultural tracking system.

## Why Per-User Blockchains?

### Traditional Centralized Approach
```
All Data → Central Database → Single Point of Failure
                ↓
        Trust the operator
        Data can be modified
        Privacy concerns
```

### LocalGreenChain Distributed Approach
```
User A Chain ←→ User B Chain ←→ User C Chain
      ↓              ↓              ↓
   Own data      Own data       Own data
   Own history   Own history    Own history
      ↓              ↓              ↓
         Cross-referenced via Master Ledger
```

## Architecture

```
┌─────────────────────────────────────────────────────────────────────┐
│                     USER BLOCKCHAIN NETWORK                         │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  ┌─────────────────────────────────────────────────────────────┐  │
│  │                      MASTER LEDGER                           │  │
│  │  ┌─────────────────────────────────────────────────────┐   │  │
│  │  │ Plant Index: plantId → [userA:block5, userB:block12] │   │  │
│  │  │ Lineage Index: parentId → [childId1, childId2...]    │   │  │
│  │  │ Transport Index: batchId → [events...]               │   │  │
│  │  │ User Directory: userId → publicKey, chainHash        │   │  │
│  │  └─────────────────────────────────────────────────────┘   │  │
│  └─────────────────────────────────────────────────────────────┘  │
│                              ↑                                      │
│              ┌───────────────┼───────────────┐                     │
│              ▼               ▼               ▼                     │
│  ┌───────────────┐  ┌───────────────┐  ┌───────────────┐         │
│  │  USER A CHAIN │  │  USER B CHAIN │  │  USER C CHAIN │         │
│  ├───────────────┤  ├───────────────┤  ├───────────────┤         │
│  │ Block 0: Gen  │  │ Block 0: Gen  │  │ Block 0: Gen  │         │
│  │ Block 1: Reg  │  │ Block 1: Acq  │  │ Block 1: Reg  │         │
│  │ Block 2: Grow │  │ Block 2: Plant│  │ Block 2: Clone│         │
│  │ Block 3: Harv │  │ Block 3: Grow │  │ Block 3: Trans│         │
│  │ Block 4: Send │  │ Block 4: Recv │  │ Block 4: ...  │         │
│  │ ...           │  │ ...           │  │ ...           │         │
│  └───────────────┘  └───────────────┘  └───────────────┘         │
│        ↓                   ↓                   ↓                   │
│        └───────────────────┼───────────────────┘                   │
│                            ▼                                        │
│                  ┌───────────────────┐                             │
│                  │ CROSS-CHAIN REFS  │                             │
│                  │ Plant P in A:3    │                             │
│                  │ received by B:4   │                             │
│                  │ cloned to C:2     │                             │
│                  └───────────────────┘                             │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘
```

## Block Types

### Plant Registration Block
```typescript
interface PlantBlock {
  index: number;
  timestamp: string;
  blockType: 'plant_registration';

  plant: {
    id: string;
    commonName: string;
    scientificName: string;
    propagationType: 'original' | 'seed' | 'clone' | 'cutting';
    generation: number;
    parentPlantId?: string;  // Cross-chain reference
    location: PlantLocation;
    owner: PlantOwner;
    childPlants: string[];
  };

  previousHash: string;
  hash: string;
  nonce: number;
}
```

### Transport Event Block
```typescript
interface TransportBlock {
  index: number;
  timestamp: string;
  blockType: 'transport_event';

  transportEvent: {
    eventType: TransportEventType;
    fromLocation: TransportLocation;
    toLocation: TransportLocation;
    plantIds?: string[];
    batchIds?: string[];
    carbonFootprintKg: number;
    senderId: string;  // Cross-chain reference
    receiverId: string;  // Cross-chain reference
  };

  previousHash: string;
  hash: string;
  nonce: number;
}
```

### Environment Update Block
```typescript
interface EnvironmentBlock {
  index: number;
  timestamp: string;
  blockType: 'environment_update';

  environment: {
    plantId: string;
    readings: GrowingEnvironment;
    healthScore: number;
    alerts: EnvironmentAlert[];
  };

  previousHash: string;
  hash: string;
  nonce: number;
}
```

## Cross-Chain References

When plants move between users, cross-chain references maintain lineage:

```
User A's Chain:                    User B's Chain:
┌────────────────────┐             ┌────────────────────┐
│ Block 5            │             │ Block 12           │
│ Type: Send Plant   │────────────→│ Type: Receive Plant│
│ PlantId: tomato-1  │             │ PlantId: tomato-1  │
│ To: UserB          │             │ From: UserA        │
│ ToBlock: pending   │←────────────│ FromBlock: A:5     │
└────────────────────┘             └────────────────────┘

After confirmation:
Block 5.ToBlock = "B:12"  // Updated with cross-reference
```

## Chain Synchronization

### Local-First Operation
```
1. User creates block locally
2. Block is mined (proof-of-work)
3. Block added to local chain
4. Sync to master ledger index
5. Cross-references updated
```

### Conflict Resolution
```
If chain fork detected:
1. Longer chain wins (most work)
2. Orphaned blocks flagged
3. Cross-references updated
4. Users notified of conflicts
```

## Privacy Model

### Default Privacy
- Location can be fuzzy (city-level)
- Owner name can be pseudonymous
- Wallet addresses are pseudonymous

### Enhanced Privacy (Tor)
- Onion routing for chain sync
- Hidden service for API access
- No IP logging
- Anonymous registration

### Public Data
- Plant species/variety
- Lineage relationships
- Transport events (anonymized)
- Environmental data (aggregated)

## Verification

### Single Chain Verification
```typescript
function verifyChain(chain: Block[]): boolean {
  for (let i = 1; i < chain.length; i++) {
    const current = chain[i];
    const previous = chain[i - 1];

    // Verify hash
    if (current.hash !== calculateHash(current)) {
      return false;
    }

    // Verify chain link
    if (current.previousHash !== previous.hash) {
      return false;
    }

    // Verify proof-of-work
    if (!current.hash.startsWith('0'.repeat(difficulty))) {
      return false;
    }
  }
  return true;
}
```

### Cross-Chain Verification
```typescript
function verifyCrossReference(
  senderChain: Block[],
  receiverChain: Block[],
  reference: CrossReference
): boolean {
  const senderBlock = senderChain[reference.senderBlockIndex];
  const receiverBlock = receiverChain[reference.receiverBlockIndex];

  // Verify matching plant/batch IDs
  if (senderBlock.plantId !== receiverBlock.plantId) {
    return false;
  }

  // Verify timestamps (receiver after sender)
  if (new Date(receiverBlock.timestamp) < new Date(senderBlock.timestamp)) {
    return false;
  }

  // Verify signatures
  if (!verifySignature(senderBlock, senderPublicKey)) {
    return false;
  }

  return true;
}
```

## Querying the Network

### Find Plant History
```typescript
// Query across all user chains
const history = masterLedger.queryPlantHistory(plantId);

// Returns:
{
  plantId: 'tomato-123',
  currentOwner: 'userC',
  registeredBy: 'userA',
  generation: 2,
  history: [
    { user: 'userA', block: 1, event: 'registered', date: '2025-01-01' },
    { user: 'userA', block: 5, event: 'cloned', date: '2025-02-15' },
    { user: 'userB', block: 12, event: 'received', date: '2025-02-16' },
    { user: 'userB', block: 20, event: 'grew', date: '2025-03-01' },
    { user: 'userC', block: 8, event: 'received', date: '2025-03-15' },
  ]
}
```

### Find Lineage
```typescript
const lineage = masterLedger.queryLineage(plantId, generations: 5);

// Returns tree structure
{
  plant: 'tomato-123',
  generation: 2,
  ancestors: [
    { plant: 'tomato-orig', generation: 0, owner: 'userA' },
    { plant: 'tomato-clone1', generation: 1, owner: 'userA' }
  ],
  descendants: [
    { plant: 'tomato-123-seed1', generation: 3, owner: 'userD' },
    { plant: 'tomato-123-seed2', generation: 3, owner: 'userE' }
  ],
  siblings: [
    { plant: 'tomato-clone2', generation: 2, owner: 'userF' }
  ]
}
```

## Data Storage

### Local Storage
Each user stores their chain locally:
```
~/.localgreenchain/
├── chain.json           # Main blockchain
├── transport-chain.json # Transport events
├── keys/
│   ├── private.key      # User's private key
│   └── public.key       # User's public key
└── cache/
    └── master-index.json # Cached master ledger
```

### Cloud Sync (Optional)
```
User Chain → Encrypted → Cloud Backup
              ↓
         Only user can decrypt
         Master ledger has index only
```

## Performance Considerations

### Block Size
- Target: < 10KB per block
- Compression for large data
- Images stored as references

### Mining Difficulty
- Adjustable per chain
- Lower for personal use (difficulty: 2)
- Higher for shared chains (difficulty: 4)

### Sync Frequency
- Real-time for active users
- Batch sync for inactive users
- Prioritize cross-references

## Security Measures

### Against Tampering
- Hash chains prevent modification
- Cross-references create witnesses
- Master ledger provides redundancy

### Against Sybil Attacks
- Proof-of-work makes spam expensive
- Reputation system for users
- Rate limiting on registrations

### Against Privacy Leaks
- Minimal data in master ledger
- Tor integration optional
- User controls visibility