Core Concepts

Understanding the fundamental building blocks of the Kova network.

Deployments vs Jobs

Bidding and Marketplace

Kova operates as an open marketplace where providers compete for work.

Order Creation

When you create a deployment, the orchestrator breaks it into "orders" - one per service/replica. Each order represents a request for specific resources at a maximum price.

# This deployment creates 1 order
deployment:
  web:
    anywhere:
      profile: web
      count: 1

# This would create 3 orders (3 replicas)
deployment:
  web:
    anywhere:
      profile: web
      count: 3

Provider Bidding

Providers run auto-bidder software that:

1. Polls orchestrator every 15 seconds for new orders
2. Checks if they have sufficient resources available
3. Submits bid at competitive price (currently fixed at $1/block)
4. Waits for user to accept their bid

Bid Acceptance

You review bids and choose based on:

• Price per block: Lower is cheaper
• Provider reputation: Completed vs failed jobs
• Response time: How quickly they bid indicates availability

Once accepted, a "lease" is created and provider starts executing immediately.

Resource Allocation

| Resource | Allocation | Enforcement | Persistence | |----------|------------|-------------|-------------| | CPU | Fractional cores (0.5, 1, 2) | Docker CPU limits | N/A | | Memory | Megabytes or gigabytes | Docker memory limits | N/A | | Storage | Gigabytes | Docker volume size | Persists across restarts | | Bandwidth | Unlimited (current) | None | N/A |

Leases and Lifecycle

What is a Lease?

A lease is the active contract between you and a provider. It's created when you accept a bid and contains:

• Deployment ID and provider node ID
• Agreed price per block
• Payment tracking (blocks paid, total paid)
• Lease state (active, insufficient_funds, closed)

Lease States

| State | Description | |-------|-------------| | active | Deployment running, payments streaming to provider | | insufficient_funds | Escrow depleted, container paused, add funds to resume | | closed | Deployment terminated, lease ended, resources released |

Blocks and Settlement

Billing on Kova uses a "block" system similar to blockchain.

Settlement Process

Every 60 seconds, orchestrator runs settlement:

1. Calculates blocks elapsed since last payment (usually 60 blocks)
2. Amount owed = blocks_elapsed × price_per_block
3. Checks if escrow has sufficient balance
4. If yes: transfers from escrow to provider, lease stays active
5. If no: pauses deployment, sets lease to insufficient_funds

Networking and Ingress

How your deployments become accessible on the internet:

Ingress Controller

Orchestrator runs an ingress controller that manages routing. When deployment starts, it generates a subdomain (e.g. web-17628738.deployments.kovanetwork.com) and registers route to provider's container.

Reverse Proxy

Apache acts as reverse proxy. Requests to *.deployments.kovanetwork.com hit Apache, which forwards to orchestrator ingress controller, which proxies to provider's local container.

SSL Termination

Apache handles SSL/TLS termination. Certificates managed via Let's Encrypt. Traffic between components is HTTP internally but HTTPS externally.

State Management

Where different types of data are stored:

| Data Type | Storage Location | Persistence | |-----------|-----------------|-------------| | Deployments | PostgreSQL | Permanent | | Uploaded files | Local filesystem | Permanent | | Container volumes | Docker volumes on provider | Until manually deleted | | Logs | PostgreSQL | 24 hours then deleted | | Transactions | PostgreSQL | Permanent | | Ingress routes | PostgreSQL + in-memory cache | Survives restart | | Job queue | Redis (BullMQ) | Until processed |