Gemforce Administrator Guide

Table of Contents

System Overview

Architecture Components

The Gemforce platform consists of the following major components:

  1. Blockchain Smart Contracts
  2. Diamond contracts (EIP-2535 implementation)
  3. Identity management contracts
  4. Token management contracts

  5. Carbon credit contracts

  6. Cloud Services

  7. Parse Server backend
  8. Database (MongoDB)
  9. File storage

  10. Cloud functions

  11. External Service Integrations

  12. DFNS wallet-as-a-service
  13. Bridge API
  14. SendGrid email service

  15. Blockchain RPC providers

  16. Client Applications

  17. Web applications
  18. Mobile applications
  19. API integrations

Component Relationships

The Gemforce system follows a layered architecture:

Client Applications
        ↓↑
Cloud Services (Parse Server)
        ↓↑
External Services ⟷ Blockchain Contracts
  • Client applications interact with the Parse Server via REST API
  • Parse Server executes cloud functions that interact with blockchain contracts and external services
  • External services provide specialized functionality (wallet management, financial operations, etc.)
  • Blockchain contracts store and manage on-chain data and logic

Infrastructure Requirements

  • Blockchain Nodes: Access to Ethereum-compatible blockchain nodes
  • Server Hardware:
  • Minimum: 4 CPU cores, 8GB RAM, 100GB SSD
  • Recommended: 8 CPU cores, 16GB RAM, 250GB SSD
  • Database: MongoDB 4.4+
  • Network: Reliable internet connection with low latency to blockchain nodes
  • SSL Certificate: Valid SSL certificate for secure API access

Security Model Overview

Gemforce implements a multi-layered security approach:

  1. Authentication and Authorization
  2. User authentication via Parse Server
  3. Role-based access control
  4. API key authentication for B2B integrations

  5. DFNS WebAuthn for wallet operations

  6. Smart Contract Security

  7. Role-based access control
  8. Function-level permissions

  9. Upgradeability via Diamond pattern

  10. Data Protection

  11. Encrypted data at rest
  12. TLS for data in transit

  13. Private key management via DFNS

  14. Monitoring and Auditing

  15. Comprehensive logging
  16. Activity tracking
  17. Alert systems

Installation and Configuration

Prerequisites

Before installing Gemforce, ensure you have:

  • Node.js 16.x or higher
  • MongoDB 4.4 or higher
  • Access to blockchain nodes (RPC endpoints)
  • API keys for external services
  • Domain name with SSL certificate
  • Git access to the Gemforce repositories

Environment Variables

The Gemforce system requires several environment variables to be set. Create a .env file with the following variables:

# Parse Server Configuration
APP_ID=your_app_id
MASTER_KEY=your_master_key
DATABASE_URI=mongodb://username:password@host:port/database
SERVER_URL=https://your-server-url.com/parse
PROJECT_WIZARD_URL=https://your-server-url.com

# Blockchain Configuration
ETH_NODE_URI_MAINNET=https://mainnet.infura.io/v3/your-key
ETH_NODE_URI_BASESEP=https://sepolia.base.org
CHAIN_ID=base-sepolia
METADATA_BASE_URI=https://your-metadata-url.com/

# DFNS Configuration
DFNS_APP_ID=your_dfns_app_id
DFNS_API_URL=https://api.dfns.io
DFNS_CRED_ID=your_dfns_credential_id
DFNS_AUTH_TOKEN=your_dfns_auth_token

# Bridge API Configuration
BASE_BRIDGE_URL=https://api.bridge-api.com
BRIDGE_API_KEY=your_bridge_api_key

# Email Configuration
SENDGRID_API_KEY=your_sendgrid_key
FROM_EMAIL=noreply@your-domain.com

# Security Configuration
AUTH_SECRET_KEY=your_auth_secret_key

Network Settings

  1. Firewall Configuration:
  2. Allow inbound connections on ports 80 (HTTP), 443 (HTTPS), and your Parse Server port

  3. Allow outbound connections to MongoDB, blockchain nodes, and external APIs

  4. Load Balancer Configuration (if applicable):

  5. Configure health checks to the Parse Server health endpoint
  6. Set appropriate timeouts (at least 30 seconds for blockchain operations)

  7. Enable SSL termination

  8. DNS Configuration:

  9. Set up A records for your domain
  10. Configure CNAME records for subdomains if needed

Database Configuration

  1. MongoDB Setup:

bash # Create a MongoDB user for the Gemforce database mongo admin -u admin -p admin use gemforce db.createUser({ user: "gemforce_user", pwd: "secure_password", roles: [{ role: "readWrite", db: "gemforce" }] })

  1. Indexes:

Ensure the following indexes are created for optimal performance:

```javascript // User collection indexes db.User.createIndex({ email: 1 }, { unique: true }) db.User.createIndex({ username: 1 }, { unique: true }) db.User.createIndex({ walletAddress: 1 })

// Identity collection indexes db.Identity.createIndex({ walletAddress: 1 }, { unique: true })

// Transaction collection indexes db.Transaction.createIndex({ hash: 1 }, { unique: true }) db.Transaction.createIndex({ user: 1 }) db.Transaction.createIndex({ createdAt: 1 }) ```

External Service Connections

  1. DFNS Setup:
  2. Create a DFNS account at https://dashboard.dfns.io
  3. Create an application and credential
  4. Copy the App ID and Credential ID to your environment variables

  5. Store the private key in dfns_private.key

  6. Bridge API Setup:

  7. Obtain API credentials from Bridge API
  8. Configure webhooks for notifications (if needed)

  9. Set rate limiting based on expected traffic

  10. SendGrid Setup:

  11. Create a SendGrid account
  12. Set up sender authentication for your domain
  13. Create email templates for verification, password reset, etc.
  14. Generate API key and add to environment variables

Security Settings

  1. API Key Management:
  2. Rotate API keys periodically (recommended every 90 days)
  3. Store API keys securely using environment variables

  4. Never expose API keys in client-side code

  5. Cross-Origin Resource Sharing (CORS):

Configure CORS settings in the Parse Server configuration:

javascript const corsConfig = { allowOrigin: ['https://your-domain.com', 'https://app.your-domain.com'], allowHeaders: ['X-Parse-Application-Id', 'X-Parse-REST-API-Key', 'Content-Type'], allowMethods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'] };

  1. Rate Limiting:

Configure rate limiting to prevent abuse:

javascript const rateLimitConfig = { rateLimit: 1000, // requests per minute burstLimit: 50, // concurrent requests expiration: 60 // seconds until reset };

User Management

User Roles and Permissions

Gemforce implements role-based access control with the following default roles:

  1. Admin:
  2. Full access to all functions
  3. Can manage users and roles

  4. Can deploy and update contracts

  5. CentralAuthority:

  6. Can manage trusted issuers
  7. Can add claim topics

  8. Can manage identities

  9. TrustedIssuer:

  10. Can issue claims to identities
  11. Can verify identities

  12. Limited access to identity management

  13. User:

  14. Can manage own wallet
  15. Can view own transactions
  16. Can participate in marketplace

Adding and Removing Users

Adding Users

  1. Via Admin Dashboard:
  2. Navigate to User Management
  3. Click "Add User"
  4. Enter user details (email, name, role)

  5. System will send invitation email

  6. Via API:

```javascript // Example using Parse JavaScript SDK const user = new Parse.User(); user.set("username", "user@example.com"); user.set("password", "securePassword"); user.set("email", "user@example.com"); user.set("firstName", "John"); user.set("lastName", "Doe");

await user.signUp(); ```

  1. Via Cloud Function:

javascript // Using the registerUser cloud function Parse.Cloud.run("registerUser", { username: "user@example.com", password: "securePassword", email: "user@example.com", firstName: "John", lastName: "Doe", company: "Example Inc" });

Removing Users

  1. Via Admin Dashboard:
  2. Navigate to User Management
  3. Select user(s) to remove

  4. Click "Delete" or "Deactivate"

  5. Via API:

javascript // Example using Parse JavaScript SDK const query = new Parse.Query(Parse.User); query.equalTo("email", "user@example.com"); const user = await query.first({ useMasterKey: true }); await user.destroy({ useMasterKey: true });

Role Assignment

  1. Assigning Roles to Users:

```javascript // Example using Parse JavaScript SDK const userQuery = new Parse.Query(Parse.User); userQuery.equalTo("email", "user@example.com"); const user = await userQuery.first({ useMasterKey: true });

const roleQuery = new Parse.Query(Parse.Role); roleQuery.equalTo("name", "TrustedIssuer"); const role = await roleQuery.first({ useMasterKey: true });

role.getUsers().add(user); await role.save(null, { useMasterKey: true }); ```

  1. Creating New Roles:

```javascript // Example using Parse JavaScript SDK const acl = new Parse.ACL(); acl.setPublicReadAccess(true);

const role = new Parse.Role("CustomRole", acl); await role.save(null, { useMasterKey: true }); ```

Identity Verification Processes

  1. KYC Verification:
  2. Initiate via generateKycLink cloud function
  3. User completes KYC via Bridge API
  4. Webhook notification sent back to Gemforce

  5. Identity status updated accordingly

  6. Trusted Issuer Verification:

  7. Trusted Issuer reviews identity information
  8. Issues verification claim to user identity
  9. Claim is written to blockchain
  10. Identity state is updated to "verified"

Managing Trusted Issuers

  1. Adding a Trusted Issuer:

```javascript // Using the dfnsAddTrustedIssuerInit/Complete cloud functions const { challenge, requestBody } = await Parse.Cloud.run("dfnsAddTrustedIssuerInit", { trustedIssuer: "0x1234...", // Issuer wallet address claimTopics: [1, 2, 3], // Claim topics this issuer can verify walletId: "wallet_id", dfns_token: "dfns_token" });

// Sign the challenge client-side const signedChallenge = await signChallenge(challenge);

// Complete the transaction await Parse.Cloud.run("dfnsAddTrustedIssuerComplete", { walletId: "wallet_id", dfns_token: "dfns_token", signedChallenge: signedChallenge, requestBody: requestBody }); ```

  1. Removing a Trusted Issuer:

Use the dfnsRemoveTrustedIssuerInit/Complete cloud functions following the same pattern as above.

  1. Updating Trusted Issuer Claim Topics:

Use the dfnsUpdateIssuerClaimTopicsInit/Complete cloud functions.

Monitoring and Alerts

System Health Checks

  1. Parse Server Health Check:
  2. Endpoint: /parse/health
  3. Expected response: {"status":"ok"}

  4. Monitor response time (should be < 200ms)

  5. Database Health Check:

  6. Query execution time
  7. Connection pool status

  8. Replica set status (if applicable)

  9. Blockchain Connectivity:

  10. RPC endpoint response time
  11. Block height synchronization
  12. Transaction submission success rate

Performance Metrics

Key metrics to monitor:

  1. API Performance:
  2. Request latency (avg, p95, p99)
  3. Request throughput

  4. Error rate

  5. Database Performance:

  6. Query execution time
  7. Index usage

  8. Connection count

  9. Blockchain Performance:

  10. Gas costs per transaction type
  11. Transaction confirmation time
  12. Failed transaction rate

Log Management

  1. Log Aggregation:
  2. Implement centralized logging (e.g., ELK Stack, Splunk)
  3. Include correlation IDs across service boundaries

  4. Implement structured logging for easier querying

  5. Log Levels:

  6. ERROR: Issues requiring immediate attention
  7. WARN: Potential issues to investigate
  8. INFO: Normal operations

  9. DEBUG: Detailed information for troubleshooting

  10. Key Events to Log:

  11. Authentication events
  12. User management operations
  13. Blockchain transactions
  14. External API calls

Alert Configuration

Configure alerts for the following scenarios:

  1. Critical Alerts (immediate action required):
  2. Parse Server unavailability
  3. Database connection failures
  4. High error rates (>5%)

  5. Failed blockchain transactions

  6. Warning Alerts (investigation needed):

  7. Elevated API latency (>500ms)
  8. Increased error rates (>1%)
  9. Low disk space (<20%)

  10. Delayed blockchain confirmations

  11. Notification Channels:

  12. Email
  13. SMS/Text
  14. Slack/Teams
  15. PagerDuty or similar service

Common Warning Signs

Watch for these indicators of potential issues:

  1. Increasing API Latency: May indicate database issues or resource constraints
  2. Growing Database Size: May require indexing or cleanup
  3. Increasing Error Rates: May indicate bugs or external service issues
  4. Blockchain Transaction Failures: May indicate gas price issues or contract bugs
  5. Declining User Activity: May indicate UX issues or service degradation

Dashboards Setup

Implement monitoring dashboards that show:

  1. System Overview:
  2. Overall health status
  3. Current alert status

  4. Key metrics summary

  5. API Performance:

  6. Request volume
  7. Response time by endpoint

  8. Error rate by endpoint

  9. User Activity:

  10. Active users
  11. Registration rate

  12. Transaction volume

  13. Blockchain Activity:

  14. Transaction success rate
  15. Gas costs
  16. Contract interactions

Backup and Recovery

Backup Procedures

  1. Database Backups:

```bash # MongoDB backup command mongodump --uri="mongodb://username:password@host:port/database" --out=/backup/path/$(date +%Y-%m-%d)

# Compress the backup tar -zcvf /backup/path/$(date +%Y-%m-%d).tar.gz /backup/path/$(date +%Y-%m-%d) ```

Schedule: - Full backup: Daily - Incremental backup: Hourly

  1. Configuration Backups:

bash # Back up environment variables and config files cp .env /backup/config/$(date +%Y-%m-%d)-env cp gemforce.config.ts /backup/config/$(date +%Y-%m-%d)-gemforce-config.ts

Schedule: After any configuration change

  1. Contract Deployment Records:

bash # Back up deployment records cp ./deployments /backup/deployments/$(date +%Y-%m-%d) -r cp deployed.json /backup/deployments/$(date +%Y-%m-%d)-deployed.json

Schedule: After any contract deployment

Recovery Procedures

  1. Database Recovery:

bash # Restore MongoDB database mongorestore --uri="mongodb://username:password@host:port/database" --drop /backup/path/YYYY-MM-DD

  1. Configuration Recovery:

bash # Restore configuration files cp /backup/config/YYYY-MM-DD-env .env cp /backup/config/YYYY-MM-DD-gemforce-config.ts gemforce.config.ts

  1. Contract Redeployment:
  2. Restore deployment records
  3. Use the DiamondFactory to recreate diamonds if needed
  4. Verify contract states

Disaster Recovery Planning

  1. Disaster Recovery Scenarios:
  2. Database corruption
  3. Server hardware failure
  4. Cloud provider outage

  5. Security breach

  6. Recovery Time Objectives (RTO):

  7. Critical systems: 4 hours

  8. Non-critical systems: 24 hours

  9. Recovery Point Objectives (RPO):

  10. Database: 1 hour

  11. Configuration: 24 hours

  12. Disaster Recovery Runbook:

  13. Maintain up-to-date documentation
  14. Conduct periodic recovery tests
  15. Automate recovery procedures where possible

Security Management

Access Control

  1. API Key Management:
  2. Generate strong API keys (min 32 characters)
  3. Store securely (environment variables, secret management service)
  4. Implement key rotation (90-day cycle)

  5. Revoke compromised keys immediately

  6. User Authentication Controls:

  7. Enforce strong password policies
  8. Implement account lockout after failed attempts
  9. Consider implementing MFA for admin accounts

  10. Session timeout (default: 24 hours)

  11. Role-Based Access Control:

  12. Limit permissions to minimum required
  13. Regularly audit role assignments
  14. Implement principle of least privilege

API Key Rotation

Implement a process for rotating API keys:

// Example: Rotate Bridge API key
async function rotateBridgeAPIKey() {
  // Generate a new API key (provider-specific)
  const newKey = await generateNewBridgeAPIKey();

  // Update environment variable
  process.env.BRIDGE_API_KEY = newKey;

  // Update configuration in database
  const config = await Config.get("bridgeAPIKey");
  config.set("value", newKey);
  await config.save(null, { useMasterKey: true });

  // Log the rotation
  console.log(`Bridge API key rotated at ${new Date().toISOString()}`);
}

Audit Logging

  1. Security Events to Log:
  2. Authentication attempts (successful and failed)
  3. Authorization changes
  4. User creation/deletion
  5. Role assignment
  6. API key usage

  7. Admin actions

  8. Log Format:

json { "timestamp": "2025-02-25T13:51:49.123Z", "event": "user.login", "success": true, "userId": "user123", "ipAddress": "192.168.1.1", "userAgent": "Mozilla/5.0...", "additionalDetails": {} }

  1. Log Retention:
  2. Security logs: 12 months minimum
  3. Normal operation logs: 3 months

Security Incident Response

  1. Incident Classification:
  2. P1: Critical (data breach, service unavailable)
  3. P2: High (limited breach, partial service degradation)
  4. P3: Medium (minor security issue, limited impact)

  5. P4: Low (potential vulnerability, no active exploitation)

  6. Response Procedure:

  7. Identify and classify the incident
  8. Contain the incident
  9. Eradicate the cause
  10. Recover systems

  11. Conduct post-incident analysis

  12. Contact List:

  13. Security team
  14. IT operations
  15. Legal department
  16. Executive leadership
  17. External security consultants (if applicable)

Compliance Considerations

  1. Data Privacy:
  2. Identify personal data stored in the system
  3. Implement data minimization
  4. Configure data retention policies

  5. Provide data export/deletion capabilities

  6. Regulatory Compliance:

  7. KYC/AML requirements
  8. Financial regulations
  9. Industry-specific regulations
  10. Cross-border data transfer requirements

Troubleshooting

Common Issues and Solutions

  1. API Request Failures:
  2. Symptom: HTTP 400/500 errors
  3. Check: API logs, request parameters

  4. Solution: Verify request format, check server logs for details

  5. Blockchain Transaction Failures:

  6. Symptom: Transaction hash returned but transaction fails
  7. Check: Gas price, contract state, transaction parameters

  8. Solution: Adjust gas price, verify contract accepts the transaction

  9. Database Connection Issues:

  10. Symptom: Cannot connect to database error
  11. Check: MongoDB status, network connectivity

  12. Solution: Restart MongoDB, check firewall rules

  13. DFNS Integration Issues:

  14. Symptom: "Cannot sign transaction" errors
  15. Check: DFNS credentials, WebAuthn support
  16. Solution: Verify DFNS credentials, ensure browser supports WebAuthn

Diagnostic Tools

  1. Log Analysis: ```bash # Search for errors in logs grep "ERROR" /var/log/gemforce/app.log

# Find recent activity for a specific user grep "userId\":\"user123" /var/log/gemforce/app.log ```

  1. Database Queries: ```javascript // Check user status db.User.findOne({ email: "user@example.com" })

// Look for recent errors db.ErrorLog.find().sort({ createdAt: -1 }).limit(10) ```

  1. Blockchain Explorers:
  2. Use block explorers to verify transaction status
  3. Check contract events for expected emissions
  4. Verify contract state after transactions

Error Codes Explanation

  1. HTTP Status Codes:
  2. 400: Bad Request (invalid parameters)
  3. 401: Unauthorized (missing/invalid authentication)
  4. 403: Forbidden (insufficient permissions)
  5. 404: Not Found (resource doesn't exist)
  6. 429: Too Many Requests (rate limit exceeded)

  7. 500: Internal Server Error (server-side issue)

  8. Parse Error Codes:

  9. 101: Object not found
  10. 141: Missing required field

  11. 209: Invalid session token

  12. Blockchain Error Codes:

  13. "gas required exceeds allowance": Insufficient gas
  14. "execution reverted": Contract condition not met
  15. "nonce too low": Transaction nonce issue

Support Escalation Procedures

  1. Tier 1 Support:
  2. Initial triage
  3. Common issue resolution

  4. Escalation timeframe: 30 minutes

  5. Tier 2 Support:

  6. Technical investigation
  7. Complex issue resolution

  8. Escalation timeframe: 2 hours

  9. Tier 3 Support:

  10. Engineering team involvement
  11. Critical issue resolution

  12. Escalation timeframe: 4 hours

  13. Escalation Contact Information:

  14. Tier 1: support@gemforce.com
  15. Tier 2: tech-support@gemforce.com
  16. Tier 3: engineering@gemforce.com
  17. Emergency: +1-555-123-4567

Service Dependencies

Map of service dependencies to check during outages:

  1. Parse Server depends on:
  2. MongoDB
  3. File storage
  4. DFNS API
  5. Bridge API

  6. Blockchain RPC nodes

  7. Blockchain operations depend on:

  8. RPC node availability
  9. Gas price oracle

  10. Contract state

  11. User authentication depends on:

  12. Parse Server
  13. Email service
  14. DFNS (for wallet operations)

Maintenance Procedures

Routine Maintenance Tasks

  1. Daily Tasks:
  2. Review error logs
  3. Check backup status

  4. Monitor system performance

  5. Weekly Tasks:

  6. Analyze API usage patterns
  7. Review security logs

  8. Check disk space usage

  9. Monthly Tasks:

  10. User access review
  11. API key rotation
  12. Performance optimization
  13. Database maintenance

Update Procedures

  1. Parse Server Updates:

```bash # Update Parse Server npm update parse-server

# Restart Parse Server pm2 restart parse-server ```

  1. Node.js Updates:

```bash # Update Node.js using NVM nvm install 16.x nvm use 16.x

# Verify version node -v ```

  1. Cloud Function Updates:

```bash # Pull latest changes git pull origin main

# Install dependencies npm install

# Build the project npm run build

# Restart the server pm2 restart gemforce ```

Database Optimization

  1. Index Optimization:

```javascript // Analyze query performance db.User.find({ walletAddress: { $exists: true } }).explain("executionStats")

// Add missing indexes db.User.createIndex({ walletAddress: 1 }) ```

  1. Data Archiving:

```javascript // Move old logs to archive collection db.SystemLog.aggregate([ { $match: { createdAt: { $lt: new Date(Date.now() - 90 * 24 * 60 * 60 * 1000) } } }, { $out: "SystemLogArchive" } ])

// Remove archived logs db.SystemLog.deleteMany({ createdAt: { $lt: new Date(Date.now() - 90 * 24 * 60 * 60 * 1000) } }) ```

  1. Database Maintenance:

```javascript // Repair database db.repairDatabase()

// Compact collections db.runCommand({ compact: "User" }) ```

Cache Management

  1. Redis Cache Configuration (if applicable):

javascript // Example cache configuration const redisCache = { host: "localhost", port: 6379, ttl: 600 // 10 minutes };

  1. Cache Invalidation:

```javascript // Invalidate specific keys redisClient.del("user_123_profile")

// Invalidate pattern redisClient.keys("user_*_profile", (err, keys) => { if (keys.length > 0) redisClient.del(keys); }) ```

  1. Cache Monitoring:

```bash # Check Redis info redis-cli info

# Monitor cache hit rate redis-cli info stats | grep hit_rate ```

System Scaling Procedures

  1. Horizontal Scaling:
  2. Add more Parse Server instances
  3. Configure load balancer

  4. Update DNS if needed

  5. Vertical Scaling:

  6. Upgrade server resources
  7. Schedule downtime for migration

  8. Verify performance after upgrade

  9. Database Scaling:

  10. Implement MongoDB replica set
  11. Consider sharding for large deployments
  12. Optimize query patterns

Performance Optimization

Database Tuning

  1. Query Optimization:
  2. Use explain plan to analyze queries
  3. Ensure proper indexes are in place
  4. Limit returned fields using projection

  5. Use aggregation pipeline for complex queries

  6. Connection Pooling:

javascript // Example MongoDB connection pool configuration const mongoConfig = { uri: process.env.DATABASE_URI, options: { maxPoolSize: 50, minPoolSize: 10, socketTimeoutMS: 30000, connectTimeoutMS: 30000 } };

  1. Index Analysis:

```javascript // Check index usage db.User.aggregate([ { $indexStats: {} } ])

// Remove unused indexes db.User.dropIndex("unusedIndex") ```

Cache Configuration

  1. Cacheable Data Types:
  2. User profiles
  3. Contract metadata
  4. Configuration settings

  5. Static content

  6. Cache Strategy:

  7. Cache-aside: Application checks cache before database
  8. TTL-based expiration

  9. Event-based invalidation

  10. Example Redis Configuration:

javascript // Redis cache configuration const redisOptions = { host: process.env.REDIS_HOST || "localhost", port: process.env.REDIS_PORT || 6379, password: process.env.REDIS_PASSWORD, db: 0, ttl: 3600 // 1 hour };

Rate Limiting Configuration

  1. API Rate Limits:

javascript // Example rate limiting configuration const rateLimits = { global: { windowMs: 60 * 1000, // 1 minute max: 1000 // limit each IP to 1000 requests per minute }, login: { windowMs: 60 * 1000, // 1 minute max: 10 // limit each IP to 10 login attempts per minute }, createUser: { windowMs: 60 * 60 * 1000, // 1 hour max: 50 // limit each IP to 50 user creations per hour } };

  1. Rate Limit Response:

javascript // Example rate limit exceeded response { "status": "error", "code": 429, "message": "Rate limit exceeded. Try again in X seconds.", "retryAfter": 30 }

  1. Rate Limit Monitoring:
  2. Track rate limit hits
  3. Alert on sustained high rejection rates
  4. Analyze traffic patterns to adjust limits

Resource Allocation Guidelines

  1. Server Resources:

Guidelines for allocating resources based on load:

Load Level Users API Requests/min CPU Cores RAM Disk
Small <1k <100 2 4GB 20GB
Medium <10k <1k 4 8GB 50GB
Large <100k <10k 8 16GB 100GB
X-Large >100k >10k 16+ 32GB+ 200GB+
  1. Database Resources:

Guidelines for MongoDB resources:

Load Level Documents Indexes RAM Disk
Small <1M <20 2GB 10GB
Medium <10M <50 4GB 50GB
Large <100M <100 16GB 200GB
X-Large >100M >100 32GB+ 500GB+
  1. Blockchain Node Resources:

Consider using managed node providers for production environments.

If running your own nodes:

Network Disk RAM Notes
Ethereum >2TB 16GB Full node, growing rapidly
BaseSepolia >100GB 8GB Testnet, moderate growth
  1. Resource Scaling Triggers:
  2. CPU usage consistently >70%
  3. RAM usage consistently >80%
  4. Disk usage >85%
  5. Response time increasing trend
  6. Error rate increasing trend