FoldDB Economic Model

What is the Economic Model?

FoldDB's economic model creates a sustainable ecosystem through Lightning Network micropayments, trust-based pricing, and schema-driven access control. This model ensures fair compensation for data providers while maintaining security and privacy.

Key Components

The economic model consists of four primary configuration components:

How the Economic Model Works

Payment Flow

When a user requests data access, the system follows this payment sequence:

1. Calculate required payment based on fields, trust distance, and configuration
2. Generate Lightning Network invoice
3. Wait for payment confirmation
4. Process the data request upon payment settlement
5. Handle payment timeouts, retries, or failures

graph LR
    subgraph Request
        U((User)) -->|Query Request| C[Calculate Payment]
        C -->|Generate| I[Invoice]
        I -->|Send to| U
    end
    subgraph Processing
        U -->|Pay| L[Lightning Network]
        L -->|Confirm| V[Verify Payment]
        V -->|If Settled| P[Process Request]
        V -->|If Failed| R[Retry/Timeout]
    end
    subgraph Response
        P -->|Return Data| U
        R -->|Error| U
    end

Payment Calculation

The system calculates payments using this formula:

Final payment = max(
    Global system base rate,
    sum(
        for each field:
            Market base rate 
            * Schema multiplier 
            * Field multiplier 
            * Trust distance scaling factor
    )
)

Trust distance scaling applies one of these formulas:

1. Linear scaling: scale_factor = max(slope * trust_distance + intercept, min_factor)
2. Exponential scaling: scale_factor = max(base^(scale * trust_distance), min_factor)
3. No scaling: scale_factor = 1.0

Implementation Features

1. Trust-Based Pricing

The system scales pricing based on trust distance:

• Lower trust distance - Lower cost for trusted relationships
• Higher trust distance - Higher cost for less trusted relationships
• Configurable scaling - Linear or exponential scaling options
• Safety bounds - Minimum scaling factors prevent underpricing

graph TD
    subgraph Trust Scaling
        T1[Trust Distance 1] -->|x1.0| Base[Base Cost]
        T2[Trust Distance 2] -->|x1.5| Base
        T3[Trust Distance 3] -->|x2.0| Base
    end
    subgraph Calculation
        Base --> |Calculate| Total[Total Cost]
        Schema[Schema Multiplier] --> |Multiply| Total
        Field[Field Multiplier] --> |Multiply| Total
    end

2. Lightning Network Integration

The system integrates with the Lightning Network through:

• Invoice generation - Creates payment requests with appropriate amounts
• Payment verification - Checks payment status with the Lightning node
• Hold invoices - Supports complex operations with payment holds
• Payment timeouts - Handles expired or timed-out payments
• Retry mechanisms - Supports payment retry attempts

3. Multi-Level Configuration

The system provides configuration at multiple levels:

• System-wide settings - Global minimum rates and timeouts
• Schema-level settings - Schema-specific multipliers and thresholds
• Field-level settings - Field-specific pricing and scaling
• Dynamic market rates - Adjustable base rates with staleness detection

Data Structures

Payment Configuration

The payment configuration includes these structures:

struct GlobalPaymentConfig {
    system_base_rate: u64,        // Minimum fee in satoshis
    payment_timeout: Duration,    // Payment timeout period
    max_invoice_retries: u32,     // Maximum retry attempts
    hold_invoice_timeout: Duration // Hold invoice timeout
}

struct SchemaPaymentConfig {
    base_multiplier: f64,         // Multiplier for schema
    min_payment_threshold: u64    // Minimum payment in satoshis
}

struct FieldPaymentConfig {
    base_multiplier: f64,         // Multiplier for field
    trust_distance_scaling: TrustDistanceScaling,
    min_payment: Option<u64>      // Optional minimum payment
}

enum TrustDistanceScaling {
    Linear {
        slope: f64,
        intercept: f64,
        min_factor: f64           // Minimum scaling factor (>= 1.0)
    },
    Exponential {
        base: f64,
        scale: f64,
        min_factor: f64           // Minimum scaling factor (>= 1.0)
    },
    None                          // No scaling (factor = 1.0)
}

Payment Processing

The payment processing includes these structures:

struct LightningPaymentRequest {
    amount: u64,                  // Amount in satoshis
    invoice: String,              // Lightning invoice
    expiry: DateTime<Utc>,        // Expiration timestamp
    payment_hash: String,         // Payment identifier
    hold_invoice: bool            // Whether this is a hold invoice
}

struct PaymentState {
    invoice_id: String,           // Invoice identifier
    status: PaymentStatus,        // Current payment status
    created_at: DateTime<Utc>,    // Creation timestamp
    last_checked: DateTime<Utc>,  // Last check timestamp
    retry_count: u32              // Number of retry attempts
}

enum PaymentStatus {
    Pending,                      // Payment not yet received
    Settled,                      // Payment completed
    Expired,                      // Payment timed out
    Failed,                       // Payment failed
    PartiallyPaid(u64),           // Partial payment received
    Cancelled                     // Payment cancelled
}

Common Operations

Calculating Field Payment

To calculate payment for a single field:

1. Validate trust distance is non-negative
2. Apply base rate and multipliers
3. Calculate trust distance scaling
4. Apply minimum thresholds
5. Validate final payment amount

fn calculate_field_payment(
    global_config: &GlobalPaymentConfig,
    market_rate: &MarketRate,
    schema_payment: &SchemaPaymentConfig,
    field_payment: &FieldPaymentConfig,
    trust_distance: f64
) -> Result<u64, Error> {
    // Validate trust distance
    if trust_distance < 0.0 {
        return Err(Error::InvalidTrustDistance);
    }

    // Apply base rate and multipliers
    let base = market_rate.base_rate;
    let schema_multiplier = schema_payment.base_multiplier;
    let field_multiplier = field_payment.base_multiplier;

    // Calculate trust distance scaling
    let scale_factor = match &field_payment.trust_distance_scaling {
        TrustDistanceScaling::Linear { slope, intercept, min_factor } => {
            (slope * trust_distance + intercept).max(*min_factor)
        },
        TrustDistanceScaling::Exponential { base, scale, min_factor } => {
            base.powf(scale * trust_distance).max(*min_factor)
        },
        TrustDistanceScaling::None => 1.0
    };

    // Calculate payment with all multipliers
    let payment = (base as f64 * schema_multiplier * field_multiplier * scale_factor).round() as u64;

    // Apply minimum thresholds
    let field_min = field_payment.min_payment.unwrap_or(0);
    let schema_min = schema_payment.min_payment_threshold;
    let system_min = global_config.system_base_rate;

    let final_payment = payment.max(field_min).max(schema_min).max(system_min);

    // Validate final payment
    global_config.validate_payment(final_payment)?;

    Ok(final_payment)
}

Processing Payments

To process a payment:

1. Generate an invoice for the required amount
2. Send the invoice to the user
3. Verify payment status periodically
4. Process the request if payment is settled
5. Handle timeouts, retries, or failures

async fn process_payment(
    payment_manager: &PaymentManager,
    amount: u64,
    memo: String,
    hold_invoice: bool
) -> Result<bool, Error> {
    // Generate invoice
    let invoice = payment_manager.generate_invoice(amount, memo, hold_invoice).await?;

    // Wait for payment with periodic checks
    let check_interval = Duration::from_secs(1);
    payment_manager.wait_for_payment(&invoice, check_interval).await
}

Best Practices

Payment Configuration

Follow these practices for payment configuration:

1. Set appropriate base rates for your data value
2. Configure reasonable trust distance scaling
3. Use minimum thresholds to prevent underpricing
4. Set appropriate timeouts for your use case
5. Configure retry limits based on expected payment behavior

Trust Distance Scaling

Follow these practices for trust distance scaling:

1. Use linear scaling for predictable pricing
2. Use exponential scaling for rapidly increasing costs
3. Set appropriate minimum factors to prevent underpricing
4. Test scaling with different trust distances
5. Adjust scaling parameters based on user feedback

Payment Processing

Follow these practices for payment processing:

1. Handle payment timeouts gracefully
2. Implement appropriate retry mechanisms
3. Clean up expired invoices regularly
4. Monitor payment status for anomalies
5. Provide clear payment instructions to users