localgreenchain/docs/TRANSPARENCY.md

LocalGreenChain Transparency System

Overview

The LocalGreenChain Transparency System provides complete visibility into platform operations, ensuring trust, accountability, and compliance for all stakeholders - growers, consumers, certifiers, and regulators.

Key Features

1. Immutable Audit Logging

Every action on the platform is recorded in an immutable, cryptographically-linked audit log.

Tracked Actions:

• Plant registrations and clones
• Transport events and handoffs
• Demand signals and supply commitments
• Farm operations and batch management
• System events and configuration changes
• API calls and user activities

API Endpoints:

GET  /api/transparency/audit          - Query audit entries
POST /api/transparency/audit          - Log custom audit entry

Query Parameters:

• startDate, endDate - Date range filter
• actions - Filter by action types (comma-separated)
• categories - Filter by categories
• severities - Filter by severity levels
• actorId - Filter by actor
• resourceType, resourceId - Filter by resource
• format - Output format (json, csv, summary)

2. Real-Time Event Stream

Server-Sent Events (SSE) for real-time notifications and webhook support for integrations.

Event Types:

• plant.* - Plant lifecycle events
• transport.* - Transport events
• demand.* - Demand and supply events
• farm.* - Farm operation events
• agent.* - Agent task and alert events
• blockchain.* - Blockchain events
• system.* - System health events
• audit.* - Audit events

API Endpoints:

GET  /api/transparency/events         - Get recent events
GET  /api/transparency/events?stream=true  - SSE connection
POST /api/transparency/events         - Emit custom event

Webhook Management:

GET    /api/transparency/webhooks     - List webhooks
POST   /api/transparency/webhooks     - Register webhook
DELETE /api/transparency/webhooks     - Remove webhook
PATCH  /api/transparency/webhooks     - Update webhook

3. Transparency Dashboard

Comprehensive metrics aggregation across all platform components.

API Endpoint:

GET /api/transparency/dashboard

Returns:

• System health status
• Plant registry metrics
• Transport statistics
• Environmental impact metrics
• Blockchain status
• Agent activity
• Active alerts

Public Portal: Visit /transparency for the public-facing dashboard.

4. Digital Signatures

Cryptographic verification for transport handoffs, ownership transfers, and certifications.

Features:

• ECDSA/RSA key pair generation
• Identity registration and verification
• Single and multi-party signatures
• Transport handoff signing
• Certificate of Authenticity generation

API Endpoints:

GET  /api/transparency/signatures          - Get signature stats
POST /api/transparency/signatures          - Various signature actions
GET  /api/transparency/certificate/[plantId] - Generate plant certificate

Signature Actions:

• register_identity - Register a new signing identity
• generate_keypair - Generate a key pair
• sign - Create a signature
• verify_data - Verify a signature
• transport_handoff - Sign transport handoff

5. Data Export & Reporting

Export transparency data in multiple formats for compliance and analysis.

API Endpoint:

GET /api/transparency/export

Export Types:

• dashboard - Dashboard metrics
• audit - Audit log entries
• events - Event stream data
• plants - Plant registry
• transport - Transport history
• signatures - Digital signatures
• full - Complete export

Formats:

• json - Structured JSON data
• csv - Spreadsheet-compatible
• summary - Human-readable text

Report Generation:

GET /api/transparency/report

6. System Health Monitoring

Real-time health status of all platform components.

API Endpoint:

GET /api/transparency/health

Components Monitored:

• Blockchain storage
• Agent system
• API layer
• Data storage

Usage Examples

Query Audit Log

// Get last 24 hours of plant registrations
const response = await fetch('/api/transparency/audit?' + new URLSearchParams({
  startDate: new Date(Date.now() - 86400000).toISOString(),
  actions: 'PLANT_REGISTER,PLANT_CLONE',
  format: 'json'
}));
const data = await response.json();

Subscribe to Events (SSE)

const eventSource = new EventSource('/api/transparency/events?stream=true');

eventSource.addEventListener('plant.registered', (event) => {
  const data = JSON.parse(event.data);
  console.log('New plant registered:', data);
});

eventSource.addEventListener('transport.completed', (event) => {
  const data = JSON.parse(event.data);
  console.log('Transport completed:', data);
});

Register a Webhook

const response = await fetch('/api/transparency/webhooks', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    url: 'https://your-server.com/webhook',
    types: ['plant.registered', 'transport.completed']
  })
});
const { data } = await response.json();
// Store data.secret securely for verifying webhooks

Generate Plant Certificate

const response = await fetch('/api/transparency/certificate/plant_123?format=json');
const { data } = await response.json();
console.log('Certificate:', data.certificate);
console.log('Verification:', data.verification);

Sign Transport Handoff

const response = await fetch('/api/transparency/signatures', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    action: 'transport_handoff',
    plantId: 'plant_123',
    fromParty: 'grower_001',
    toParty: 'transporter_001',
    location: { lat: 40.7128, lng: -74.0060 },
    privateKey: '-----BEGIN PRIVATE KEY-----...'
  })
});

Export Data

// Export audit log as CSV
window.location.href = '/api/transparency/export?type=audit&format=csv';

// Generate full report
const response = await fetch('/api/transparency/report?format=summary');
const report = await response.text();

Security Considerations

1. Audit Integrity: Audit entries are cryptographically linked; tampering is detectable
2. Signature Security: Private keys are never stored on the server
3. Webhook Security: Webhooks include HMAC signatures for verification
4. Data Privacy: Personal data can be anonymized in exports
5. Rate Limiting: Consider implementing rate limiting for production

Integration with Existing Systems

The transparency system integrates with:

• PlantChain: Plant registration events are automatically logged
• TransportChain: Transport events trigger audit entries and notifications
• AgentOrchestrator: Agent activities are tracked and monitored
• DemandForecaster: Demand signals are logged for transparency

Best Practices

1. Subscribe to Critical Events: Set up webhooks for important events
2. Regular Exports: Schedule regular data exports for compliance
3. Monitor Health: Check /api/transparency/health in monitoring systems
4. Verify Certificates: Always verify plant certificates before transactions
5. Sign Handoffs: Use digital signatures for all transport handoffs

Public Transparency Portal

Access the public transparency portal at /transparency to view:

• Real-time system health
• Platform metrics
• Environmental impact
• Blockchain status
• Active alerts

The portal auto-refreshes every 30 seconds and provides export links for all data.