defarm-sdk/README.md

DeFarm SDK - On-premise blockchain data processing and tokenization engine for agriculture supply chain

# DeFarm SDK Enterprise

**Complete blockchain infrastructure for agricultural supply chain management**

The DeFarm SDK Enterprise is a comprehensive solution that combines on-premise data processing, blockchain tokenization, and cloud services in a flexible, enterprise-ready package.

## Key Features

### 🏢 Enterprise Ready
- **Multi-Database Support**: PostgreSQL, Oracle, SQL Server, MySQL
- **WASM Protection**: Core logic compiled to WebAssembly for IP protection
- **Flexible Deployment**: On-premise, cloud, or hybrid modes
- **Gas-Free Blockchain**: DeFarm sponsors all blockchain transactions

### 🔐 Security & Compliance
- **Data Sovereignty**: Complete control over sensitive data
- **ICP-Brasil Integration**: Brazilian digital certificate compliance
- **AES-256 Encryption**: Military-grade data protection
- **Audit Trails**: Complete operation logging

### ⛓️ Blockchain Integration
- **Multi-Chain Support**: Stellar (priority), Polygon, Ethereum
- **Zero Gas Fees**: Relay system for sponsored transactions
- **Smart Contracts**: Automated compliance and verification
- **IPFS Storage**: Decentralized metadata storage

### 📊 Data Processing
- **Asset Management**: Livestock, crops, aquaculture, forestry
- **Supply Chain Tracking**: Complete traceability from farm to table
- **Real-time Validation**: Comprehensive quality checks
- **DFID Generation**: Unique global identifiers

## Installation

```bash
npm install @defarm/sdk
```

### Quick Setup

```bash
# Get your API key at https://defarm.io/dashboard
export DEFARM_API_KEY="sk_live_your_api_key_here"

# Setup the SDK
npx defarm setup
```

## Deployment Modes

### 1. On-Premise Mode
Complete data isolation with no cloud dependencies:

```javascript
const { DeFarmSDK } = require('@defarm/sdk');

const sdk = new DeFarmSDK({
  deploymentMode: 'on-premise',
  database: {
    type: 'postgresql',
    host: 'localhost',
    database: 'defarm_local'
  },
  blockchain: {
    enabled: false  // Optional blockchain
  }
});

await sdk.initialize();
```

### 2. Cloud Mode (SaaS)
Full cloud integration with gas-free transactions:

```javascript
const sdk = new DeFarmSDK({
  deploymentMode: 'cloud',
  relay: {
    enabled: true,
    apiKey: 'YOUR_API_KEY'
  },
  enterprise: {
    premiumAPI: true,
    servicesEnabled: true
  }
});
```

### 3. Hybrid Mode
Best of both worlds - local processing with cloud enhancements:

```javascript
const sdk = new DeFarmSDK({
  deploymentMode: 'hybrid',
  database: {
    type: 'oracle',  // Local enterprise DB
    host: 'internal.company.com'
  },
  relay: {
    enabled: true  // Gas-free blockchain
  },
  enterprise: {
    premiumAPI: true  // Cloud analytics
  }
});
```

## Usage Examples

### Process Agricultural Data

```javascript
// Process with WASM protection
const result = await sdk.processAgricultureData({
  type: 'livestock',
  breed: 'Angus',
  weight: 450,
  location: 'Farm A',
  health_status: 'healthy'
});
```

### Authentication & API Keys

```javascript
// Initialize with API key
const sdk = new DeFarmSDK({
  apiKey: process.env.DEFARM_API_KEY, // Required for tokenization
  deploymentMode: 'hybrid'
});

// Check usage limits
const usage = await sdk.getUsage();
console.log(`Tokenizations used: ${usage.usage.tokenizations.used}/${usage.usage.tokenizations.limit}`);
```

### Gas-Free Tokenization

```javascript
// No private keys needed - DeFarm sponsors the transaction
const token = await sdk.createAssetToken(
  {
    asset_type: 'cattle',
    quantity: 100,
    location: 'Brazil',
    certifications: ['organic', 'grass-fed']
  },
  {
    clientWallet: 'GCLIENT...XYZ'  // Just the public address
  }
);

console.log('Token created:', token.tokenId);
console.log('Transaction:', token.explorerUrl);
console.log('Gas paid by DeFarm:', token.gasCost);
```

### Enterprise Database Integration

```javascript
// Use with existing enterprise databases
const sdk = new DeFarmSDK({
  database: {
    type: 'oracle',
    host: 'oracle.company.com',
    user: 'defarm_user',
    password: process.env.ORACLE_PASSWORD
  }
});

// Query using enterprise adapter
const assets = await sdk.queryData({
  type: 'livestock',
  status: 'active',
  location: 'Region-North'
});
```

### Supply Chain Tracking

```javascript
// Track events across the supply chain
await sdk.trackSupplyChainEvent({
  type: 'transfer',
  asset_id: 'ASSET-123',
  from: 'Farm A',
  to: 'Processing Plant B',
  transport: 'Truck-789',
  temperature: 4.5,
  timestamp: Date.now()
});

// Get complete history
const history = await sdk.getAssetHistory('ASSET-123');
```

### Compliance & Validation

```javascript
// Generate compliance reports
const report = await sdk.generateComplianceReport({
  standards: ['ISO-22000', 'GLOBALG.A.P'],
  period: 'Q4-2024',
  regions: ['Brazil', 'Argentina']
});

// Validate with schemas
const validation = await sdk.validateWithSchema(
  productData,
  'organic-certification-v2'
);
```

### ICP-Brasil Digital Signature

```javascript
// Sign documents with Brazilian digital certificate
const signed = await sdk.signWithICPBrasil({
  document: invoiceData,
  certificate: '/path/to/cert.pfx'
});
```

## Business Models

### SaaS Pricing Plans

| Plan | Monthly | Tokenizations | Features |
|------|---------|--------------|----------|
| **Starter** | R$ 2,900 | 1,000/month | Basic features, email support |
| **Professional** | R$ 9,900 | 10,000/month | All features, priority support |
| **Enterprise** | R$ 29,900 | 100,000/month | White-label, SLA, dedicated support |
| **Government** | Custom | Unlimited | Full customization, on-premise |

### On-Premise Licensing

- **Perpetual License**: One-time payment + annual maintenance
- **Annual Subscription**: Full support and updates included
- **Custom Development**: Tailored solutions for specific needs

## Architecture

```
┌─────────────────────────────────────────────┐
│              Client Application              │
└─────────────────┬───────────────────────────┘
                  │
┌─────────────────▼───────────────────────────┐
│            DeFarm SDK Enterprise            │
├──────────────────────────────────────────────┤
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  │
│  │   WASM   │  │   Core   │  │ Services │  │
│  │Processor │  │  Engine  │  │  Client  │  │
│  └──────────┘  └──────────┘  └──────────┘  │
├──────────────────────────────────────────────┤
│  ┌──────────────────────────────────────┐   │
│  │        Database Adapters             │   │
│  │  PostgreSQL | Oracle | SQL Server    │   │
│  └──────────────────────────────────────┘   │
├──────────────────────────────────────────────┤
│  ┌──────────────────────────────────────┐   │
│  │     Blockchain Integration           │   │
│  │  Stellar | Polygon | Ethereum        │   │
│  └──────────────────────────────────────┘   │
└──────────────────────────────────────────────┘
                  │
┌─────────────────▼───────────────────────────┐
│          DeFarm Relay Server                │
│        (Gas Sponsorship Service)            │
└─────────────────────────────────────────────┘
```

## API Reference

### Core Methods

- `initialize(config)` - Initialize the SDK
- `processAgricultureData(data, options)` - Process agricultural data
- `createAssetToken(assetData, options)` - Create blockchain token
- `trackSupplyChainEvent(event, options)` - Track supply chain events
- `queryData(query, options)` - Query stored data
- `getAssetHistory(assetId)` - Get asset history

### Enterprise Methods

- `processWithProcessor(type, data)` - Use specific processor (livestock, crops)
- `validateWithSchema(data, schema)` - Validate with enterprise schemas
- `checkDuplicates(data)` - Check for duplicate entries
- `signWithICPBrasil(data)` - Sign with ICP-Brasil certificate
- `getAnalytics(query)` - Get premium analytics
- `setDeploymentMode(mode)` - Switch deployment mode

## Docker Deployment

```bash
# Build Docker image
docker build -t defarm-sdk .

# Run with environment variables
docker run -d \
  -e DEFARM_ENV=production \
  -e DEFARM_DB_HOST=postgres.local \
  -e DEFARM_API_KEY=your-api-key \
  -p 3000:3000 \
  defarm-sdk
```

## Environment Variables

```env
# Database
DEFARM_DB_TYPE=postgresql
DEFARM_DB_HOST=localhost
DEFARM_DB_PORT=5432
DEFARM_DB_NAME=defarm
DEFARM_DB_USER=defarm_user
DEFARM_DB_PASSWORD=secure_password

# Blockchain
DEFARM_BLOCKCHAIN_ENABLED=true
DEFARM_BLOCKCHAIN_NETWORK=stellar
DEFARM_RELAY_URL=https://relay.defarm.io

# Enterprise
DEFARM_API_KEY=your-api-key
DEFARM_DEPLOYMENT_MODE=hybrid
```

## Support

- **Documentation**: [docs.defarm.io](https://docs.defarm.io)
- **Enterprise Sales**: enterprise@defarm.io
- **Technical Support**: support@defarm.io
- **GitHub**: [github.com/defarm/sdk](https://github.com/defarm/sdk)

## License

MIT License for open-source components.
Enterprise features require a commercial license.

---

**Built with ❤️ by the DeFarm Team**