Core Concepts — Developers

Understanding these core ideas will help you write better jobs and debug issues faster. Don’t worry—they’re simpler than they sound.

Tasks

A task is a single unit of work: “generate Python code that implements quicksort” or “summarize this document using GPT-4.”

Every task has:

An ID — Unique identifier within your job (e.g., task-generate-code)
A prompt — What you want the miner to do (a string)
A timeout — Maximum time allowed (in milliseconds)
Dependencies — Which other tasks must finish first (optional)
Resource hints — Whether the miner needs GPU, lots of memory, etc. (optional)

Example:

{
  "id": "generate-api",
  "prompt": "Write a REST API in Go for a Todo app using gin framework",
  "timeout_ms": 60000,
  "depends_on": []
}

Tasks are simple: you describe what you want, miners do it. You don’t need to write code—just tell miners what to generate.

Jobs

A job is a collection of tasks. The simplest job has one task. More complex jobs have many tasks that depend on each other, forming a directed acyclic graph (DAG).

Example single-task job:

{
  "name": "generate-quicksort",
  "tasks": [
    {
      "id": "task-1",
      "prompt": "Write Python code that implements quicksort",
      "timeout_ms": 30000
    }
  ]
}

When you submit a job, Swarmient:

Validates the job structure
Checks you have enough credits
Assigns each task to a miner (possibly different miners)
Streams back results as tasks complete
Settles payment automatically

Directed Acyclic Graphs (DAGs)

A DAG lets you express complex workflows where some tasks depend on others.

Why this matters:

Task B can’t start until Task A finishes
Task C can wait for Task A, Task B can start immediately
Swarmient parallelizes what it can and sequences what it must

Example: Multi-step workflow

{
  "name": "build-api",
  "tasks": [
    {
      "id": "schema",
      "prompt": "Design a database schema for a blog platform",
      "timeout_ms": 30000,
      "depends_on": []
    },
    {
      "id": "api",
      "prompt": "Write a REST API in Node.js for the schema defined in task 'schema'",
      "timeout_ms": 60000,
      "depends_on": ["schema"]
    },
    {
      "id": "tests",
      "prompt": "Write Jest tests for the API defined in task 'api'",
      "timeout_ms": 45000,
      "depends_on": ["api"]
    }
  ]
}

In this flow:

schema runs first
api waits for schema to complete, then runs
tests waits for api to complete, then runs

If you have 10 miners available, Swarmient might:

Assign schema to miner 1
While miner 1 works, assign other jobs’ tasks to miners 2–10
Once schema completes, immediately assign api to the next available miner
Once api completes, assign tests

This parallelization happens automatically—you just describe the dependencies.

Proofs & Verification

Every result comes with a proof: a cryptographic signature that proves a miner actually executed your job.

You don’t have to understand the math, but here’s the idea:

You submit a task to a miner
Miner executes it in a sandbox and generates a result
Miner signs the result with their private key (mathematically unforgeable)
You receive the result + signature
You can verify the signature without trusting the miner

Why this matters:

No vendor lock-in—you can audit miners independently
Results are auditable—prove to regulators or colleagues that the work was done
Reproducibility—same input always produces the same output

You’ll never need to generate proofs yourself—Swarmient handles it. But when you see proof in a result, know that it’s your mathematical guarantee of correctness.

Credits & Payments

Credits are how you pay for computation. You buy credits, submit jobs, and credits are deducted automatically when tasks complete.

Pricing is:

Cost = (Execution Time in Seconds) × (Miner's Hourly Rate)

For example, if a task takes 2 seconds and the miner charges $10/hour:

Cost = 2 sec × ($10 / 3600 sec) = $0.0056

Key points:

Pricing is transparent—you see the estimated cost before submitting
Payment is atomic—the moment a miner submits a valid proof, credits settle
No escrow delays, no disputes, no hidden fees
If a job fails, you’re not charged (or only charged for work that completed)

Timeouts

A timeout is the maximum time you’ll let a task run. If it takes longer, the task fails and you’re not charged for it.

Good timeouts:

Simple task (generate a function): 30 seconds
Medium task (write an API): 60 seconds
Complex task (write a full service with tests): 120 seconds

Miners can’t force a timeout:

If a task hangs, Swarmient kills it after the timeout
You’re not charged if the miner’s execution exceeds your timeout
A task that times out is retried on another miner (if you have retries enabled)

Retries

By default, if a task fails, it’s not retried. You can configure retries:

{
  "id": "api-generation",
  "prompt": "...",
  "timeout_ms": 60000,
  "max_retries": 3
}

If api-generation fails, Swarmient will try again up to 3 times (on different miners) before giving up.

When to use retries:

Tasks that might be flaky (network-dependent, random)
Tasks where a miner might be underspecced (wrong hardware)
Tasks that are worth the extra cost if they fail

When not to use retries:

Tasks you’re confident will pass the first time
Tasks where cost is more important than success rate

Resource Hints

By default, Swarmient assumes every task is CPU-only. If your task needs GPU or lots of memory, tell Swarmient:

{
  "id": "train-model",
  "prompt": "Fine-tune a GPT model on this dataset",
  "timeout_ms": 300000,
  "resources": {
    "gpu": "required",
    "memory_gb": 16
  }
}

Swarmient will only assign your task to miners who have the resources you need.

Available resource hints:

gpu — “optional” or “required”
memory_gb — Minimum GB of RAM (1–1024)
cpu_cores — Minimum CPU cores (1–128)

If you don’t specify resources, your task can run on any miner with at least 4GB RAM and 2 CPU cores.

Next Steps

Now that you understand the concepts, you’re ready to:

Submit Jobs — Write your first complex job
Monitor & Debug — Track jobs and optimize
Examples — See real-world patterns