d402-http-task-v1

Protocol spec

d402 is a distributed task execution protocol with an HTTP buyer boundary and a peer-to-peer worker network behind it. The core invariant: work must be bounded by capability manifests, validated by a declared model, and settled to the wallets that earned payment.

1. Roles

Role	Responsibility	Keys
User client	Buys work from gateways and handles wallet/payment challenges.	Buyer wallet only.
Capability author	Defines a versioned capability manifest and optional signed implementation/commission terms.	Publisher identity plus optional creator payout wallets.
Gateway / ingress	Exposes HTTP, enforces policy, verifies payment, discovers workers, coordinates tasks, persists records.	Optional fallback payout, payment verifier config.
Worker / seller	Advertises capabilities, bids on tasks, executes leases, signs result claims.	Node identity and payout wallet.
Bootstrap / discovery	Introduces peers and improves reachability without defining the application API.	Node identity.
Validator	Signs validation and settlement decisions.	Validator signing key, ideally not colocated with public ingress.
Maintainer / finalizer	Publishes channel roots, retries withdrawals, finalizes escrows, refunds expired tasks, reclaims rent.	Fee-payer and authorized validator keys for specific actions.

2. Capability boundary

d402 does not try to make arbitrary code execution trustless. A capability manifest defines what work means, how it can run, what it may access, how outputs are validated, and how workers are paid.

capability manifest shape

{
  "id": "web.page_to_markdown",
  "version": "1",
  "capabilityId": "web.page_to_markdown@1",
  "description": "Fetch a public web page and return canonical markdown.",
  "inputSchema": {
    "type": "object",
    "required": ["url"],
    "properties": {
      "url": { "type": "string", "format": "uri" },
      "timeoutMs": { "type": "integer", "maximum": 20000 }
    }
  },
  "outputSchema": {
    "required": ["markdown", "contentHash", "snapshotCid", "evidence"]
  },
  "runtime": {
    "type": "external-runner",
    "command": "node runner.js"
  },
  "permissions": {
    "network": "public-http-only",
    "browser": "optional",
    "maxInputBytes": 128000,
    "maxOutputBytes": 1000000
  },
  "determinism": "canonicalizable-after-snapshot",
  "validator": "web.markdown.canonical@1",
  "pricing": { "unit": "request", "amount": "0.01", "currency": "USDC" },
  "evidence": ["sourceUrl", "contentHash", "snapshotCid", "converter"],
  "supports": ["single", "race", "quorum"]
}

A signed capability registration publishes the manifest into directories and gateways. The registration, not the manifest body, carries namespace proof, source pointers, deprecation state, and optional creator commission terms.

registration commission shape

{
  "schemaVersion": "d402.capability.registration@1",
  "type": "capability.registration",
  "capabilityId": "web.page_to_markdown@1",
  "manifestCid": "sha256:...",
  "publisher": "node:...",
  "namespace": "example",
  "status": "active",
  "creatorCommission": {
    "schemaVersion": "d402.creator_commission@1",
    "pricingMode": "included",
    "scope": "exact-manifest",
    "rateBps": 1000,
    "recipients": {
      "solana": "CreatorSolanaWallet...",
      "evm": "0xCreatorEvmWallet..."
    }
  }
}

3. Task lifecycle

A client posts a structured task to a gateway.
The gateway returns 402 when payment is required.
The client completes the payment challenge and retries idempotently.
The gateway discovers capable workers and broadcasts a task intent.
Workers return signed bids with price, ETA, capacity, and bond terms.
The coordinator selects workers by cost, reputation, stake, latency, and diversity.
Workers receive work leases, run the capability, and return signed result claims.
Validators accept, reject, compare, or score claims according to the capability validator.
Settlement pays valid workers net of any signed creator commission, aggregates creator commission payouts, refunds unused budget, releases or slashes bonds, and emits reputation events.

Status	Meaning
`payment_required`	The gateway has issued a challenge and has not yet accepted payment proof.
`queued`	The task is paid or authorized and waiting for worker selection.
`running`	Workers have been leased and claims are pending.
`accepted`	A valid result was accepted and settlement can complete.
`rejected`	Claims failed validation or quorum. Refund rules apply.
`expired`	The task missed its deadline. Refund or timeout settlement applies.

4. HTTP gateway API

The gateway API is the stable boundary for external software. Clients should not depend on peer discovery or worker internals.

Endpoint	Purpose
`GET /health`	Gateway liveness and policy summary.
`GET /.well-known/d402-gateway.json`	Machine-readable task API, capabilities, endpoints, and payment metadata.
`POST /tasks`	Create or retry a paid task.
`GET /tasks/{taskId}`	Fetch task status.
`GET /tasks/{taskId}/result`	Fetch accepted result or `202` while running.
`GET /tasks/{taskId}/receipt`	Fetch validation and settlement receipt.

5. Payment challenge model

d402 supports both standard x402-style payment challenges and low-cost Solana-specific rails. The gateway must bind each payment to task input, price, rail, destination, expiry, and refund policy.

Known worker before work: direct provider payTo can point to the selected worker payout wallet.
Unknown worker until validation: payTo must point to a deterministic task escrow or channel vault controlled by rules, not by gateway custody.
High-frequency traffic: channel debits avoid one on-chain payment per task and let workers withdraw cumulative claims later.
Creator commission: if a selected manifest has creator commission terms, direct provider payTo is not eligible because it cannot split funds between worker and creator.

6. Creator commission settlement

Creator commissions are signed economic terms on a capability registration. They are included in the buyer-facing price and scoped to the exact manifestCid; they are not global anti-fork rights.

Schema version: d402.creator_commission@1.
Rate: integer basis points, where 1000 means 10%.
Gateway policy: reject rates above D402_MAX_CREATOR_COMMISSION_BPS, default 2000.
Rail policy: reject paid execution if the selected payout rail lacks a creator recipient wallet.
Settlement: for each accepted worker payout, worker receives gross - commission; creator receives an aggregated payout with reason creator-commission.
No commission is paid on failed, rejected, refunded, missed-deadline, or race-canceled work.

7. Validation classes

Class	Validation strategy	Reliability
Deterministic and exactly verifiable	Check output exactly or verify a proof.	Strongest.
Deterministic and canonicalizable	Normalize and compare outputs.	Strong for frozen inputs.
Scoreable but not exact	Use comparator, oracle, benchmark, or model judge.	Depends on validator quality.
Non-verifiable	Use reputation, stake, redundancy, and dispute windows.	Weakest.

8. Discovery and resilience

The current implementation uses bootstrap TCP peers and peer exchange. The production target is multiple independent bootstrap paths, signed peer records, DHT provider records by capability, gossipsub topics for task events, NAT traversal, relay support, peer scoring, and eclipse/Sybil defenses.

Critical resilience requirement: if the original ingress node disappears after receiving a paid task, another committee member should be able to resume from replicated signed task events and finish settlement.