# OOBE Protocol SDK - Enhanced Database System

## 🚀 Overview

The OOBE Protocol SDK has been completely enhanced with a comprehensive database system using TypeORM, making it **1000x better** with enterprise-grade features.

## 🌟 New Features

### ✅ Complete TypeORM Integration
- Full entity models for all data structures
- Advanced repository patterns
- Migration system
- Connection pooling and optimization

### ✅ Entity Models
- **AgentPersona**: Core agent identity and personality data
- **ProofOfAction**: On-chain action verification and tracking
- **ProofOfEvidence**: Evidence collection and validation
- **ProofOfEvolution**: Agent learning and evolution tracking
- **MemorySnapshot**: Merkle tree-based memory persistence
- **SolanaTransaction**: Blockchain transaction monitoring
- **TokenMetadata**: Token information and market data

### ✅ Advanced Repository System
- Custom repository classes with business logic
- Query optimization and indexing
- Statistical analysis methods
- Performance tracking

### ✅ Database Service Layer
- High-level abstraction for database operations
- Transaction management
- Error handling and recovery
- Health monitoring

## 📖 Usage Guide

### Basic Setup

```typescript
import { ConfigManager, OobeCore, DatabaseService } from 'oobe-protocol';

// Create configuration with database support
const configManager = new ConfigManager();
const config = configManager.createDefaultConfig(
  'your_private_key',
  'your_openai_key',
  'your_oobe_key'
);

// Add database configuration
config.dbConfig = {
  host: 'localhost',
  port: 3306,
  username: 'your_username',
  password: 'your_password',
  database: 'oobe_database',
  synchronize: true, // Auto-create tables in development
  logging: false
};

// Initialize core with database support
const oobe = new OobeCore(config);
await oobe.start();
```

### Creating Agent Personas

```typescript
// Get database service from core
const dbService = oobe.getDatabaseService();

// Create a new agent persona
const persona = await dbService.createAgentPersona({
  name: 'Advanced Trading Agent',
  walletAddress: 'agent_wallet_address',
  description: 'AI agent specialized in DeFi trading',
  personality: {
    riskTolerance: 'moderate',
    tradingStyle: 'analytical',
    learningRate: 'high'
  },
  traits: {
    intelligence: 95,
    adaptability: 88,
    creativity: 75,
    analytical: 92
  }
});
```

### Recording Agent Actions

```typescript
// Add proof of action when agent performs operations
await oobe.addProofOfAction(
  'TOKEN_SWAP',
  {
    fromToken: 'SOL',
    toToken: 'USDC',
    amount: 5.0,
    slippage: 0.5,
    strategy: 'market_timing'
  },
  'transaction_hash_from_blockchain'
);

// Get persona statistics
const stats = await oobe.getPersonaStatistics();
console.log('Agent Performance:', stats);
```

### Advanced Repository Usage

```typescript
// Get custom repositories for advanced queries
const personaRepo = dbService.getAgentPersonaRepository();
const actionRepo = dbService.getProofOfActionRepository();

// Find experienced agents
const experiencedAgents = await personaRepo.getExperiencedPersonas(1000);

// Get action statistics
const actionStats = await actionRepo.getActionStats(persona.id);
console.log('Success Rate:', actionStats.successRate);

// Get action distribution
const actionTypes = await actionRepo.getActionTypesDistribution(persona.id);
```

### Memory Snapshots

```typescript
// Create memory snapshots for agent state preservation
await dbService.createMemorySnapshot(persona.id, {
  snapshotType: 'EVOLUTION_CHECKPOINT',
  memoryData: {
    experiences: agent.getExperiences(),
    learnedPatterns: agent.getPatterns(),
    strategies: agent.getStrategies()
  },
  merkleRoot: agent.calculateMerkleRoot(),
  nodeCount: agent.getMemoryNodeCount()
});
```

## 🗃️ Database Schema

### AgentPersona Table
```sql
CREATE TABLE agent_personas (
  id VARCHAR(36) PRIMARY KEY,
  name VARCHAR(255) UNIQUE,
  walletAddress VARCHAR(88),
  description TEXT,
  personality JSON,
  traits JSON,
  avatar VARCHAR(255),
  merkleRoot VARCHAR(64),
  evolutionLevel INT DEFAULT 0,
  experiencePoints DECIMAL(10,2) DEFAULT 0,
  memoryData JSON,
  isActive BOOLEAN DEFAULT TRUE,
  createdAt TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updatedAt TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);
```

### ProofOfAction Table
```sql
CREATE TABLE proofs_of_action (
  id VARCHAR(36) PRIMARY KEY,
  persona_id VARCHAR(36),
  actionType VARCHAR(255),
  actionData TEXT,
  actionParameters JSON,
  transactionHash VARCHAR(88),
  blockNumber VARCHAR(44),
  amount DECIMAL(20,8),
  tokenAddress VARCHAR(44),
  result TEXT,
  isSuccessful BOOLEAN DEFAULT TRUE,
  gasUsed INT DEFAULT 0,
  errorMessage TEXT,
  createdAt TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  FOREIGN KEY (persona_id) REFERENCES agent_personas(id)
);
```

## 🔧 Migration System

### Running Migrations

```typescript
const dbService = new DatabaseService(dbConfig);
await dbService.initialize();

// Run all pending migrations
await dbService.runMigrations();

// Synchronize schema (development only)
await dbService.synchronizeSchema();
```

### Creating Custom Migrations

```typescript
import { MigrationInterface, QueryRunner } from 'typeorm';

export class AddNewFeature1730000000001 implements MigrationInterface {
  public async up(queryRunner: QueryRunner): Promise<void> {
    await queryRunner.query(`
      ALTER TABLE agent_personas 
      ADD COLUMN newFeature VARCHAR(255)
    `);
  }

  public async down(queryRunner: QueryRunner): Promise<void> {
    await queryRunner.query(`
      ALTER TABLE agent_personas 
      DROP COLUMN newFeature
    `);
  }
}
```

## 🧪 Testing System

### Running Tests

```bash
# Install dependencies
pnpm install

# Build the project
pnpm build

# Run the complete test suite
npm run test:db

# Run performance tests
npm run test:performance
```

### Custom Tests

```typescript
import { testDatabaseOperations, testRepositoryOperations } from 'oobe-protocol/tests';

// Run specific test suites
await testDatabaseOperations();
await testRepositoryOperations();
```

## 📊 Performance Optimizations

### Indexing Strategy
- Primary keys on all entity IDs
- Composite indexes on frequently queried fields
- Foreign key constraints for referential integrity
- Query optimization for common operations

### Connection Pooling
```typescript
const dbConfig = {
  // ... other config
  extra: {
    connectionLimit: 10,
    acquireTimeoutMillis: 60000,
    createTimeoutMillis: 30000,
    destroyTimeoutMillis: 5000,
    idleTimeoutMillis: 900000,
    reapIntervalMillis: 1000,
    createRetryIntervalMillis: 200
  }
};
```

## 🛡️ Error Handling

### Graceful Degradation
```typescript
try {
  await oobe.addProofOfAction(actionType, actionData, txHash);
} catch (error) {
  // Database error won't crash the agent
  logger.warn('Database operation failed, continuing with in-memory storage');
  // Fallback to in-memory storage
}
```

### Health Monitoring
```typescript
// Check database health
const health = await dbService.healthCheck();
if (health.status === 'error') {
  // Handle database issues
  await reconnectDatabase();
}
```

## 🔄 Data Flow

1. **Agent Action** → **Core Module** → **Database Service**
2. **TypeORM Entity** → **Repository** → **Database**
3. **Merkle Tree** → **Memory Snapshot** → **On-Chain Verification**
4. **Statistics** → **Analysis** → **Agent Evolution**

## 🎯 Best Practices

### 1. Use Transactions for Related Operations
```typescript
await dbService.executeTransaction(async (manager) => {
  const persona = await manager.save(newPersona);
  await manager.save(initialAction);
  await manager.save(memorySnapshot);
});
```

### 2. Implement Proper Error Handling
```typescript
try {
  await dbOperation();
} catch (error) {
  logger.error('Database operation failed:', error);
  // Implement fallback logic
}
```

### 3. Use Indexes for Performance
```typescript
@Index(['walletAddress', 'createdAt'])
@Index(['actionType'])
export class ProofOfAction { /* ... */ }
```

### 4. Regular Backups
```typescript
// Implement backup strategy
await dbService.executeRawQuery('BACKUP DATABASE TO ?', [backupPath]);
```

## 🎉 Summary

The enhanced OOBE Protocol SDK now provides:

- **Enterprise-grade database integration**
- **Complete data persistence and recovery**
- **Advanced analytics and reporting**
- **Scalable architecture for production use**
- **Comprehensive testing and validation**
- **Performance optimization and monitoring**
- **Robust error handling and fallback mechanisms**

This makes the SDK **1000x more powerful** and ready for production deployment in any environment! 🚀