Marketplace Worker

{
  "intent": "reserve_job",
  "job_tx_hash": "0x<32-byte-hex>",
  "job_index": 0,
  "worker_lock_args": "0x<20-byte-hex>"
}

claim_job

{
  "intent": "claim_job",
  "job_tx_hash": "0x<32-byte-hex>",
  "job_index": 0
}

complete_job

{
  "intent": "complete_job",
  "job_tx_hash": "0x<32-byte-hex>",
  "job_index": 0,
  "worker_lock_args": "0x<20-byte-hex>",
  "result": "<utf-8 result text or omit>"
}

When result is provided for a described job, the builder computes the result proof and creates the 33-byte result memo cell under the worker's lock as on-chain proof of work (version byte + blake2b hash of the task result). The memo cell costs 97 CKB, deducted from the poster's refund. When Fiber payment metadata is embedded in the job, prefer the MCP wrappers: use POST /jobs/:tx_hash/:index/escrow to create and fund a worker-side hold invoice before completion, then use POST /jobs/:tx_hash/:index/complete with fiber_preimage to settle it after the on-chain completion succeeds. Jobs that keep the default direct mode still auto-trigger the existing pay-agent flow on completion.

cancel_job

{
  "intent": "cancel_job",
  "job_tx_hash": "0x<32-byte-hex>",
  "job_index": 0
}

mint_badge

{
  "intent": "mint_badge",
  "job_tx_hash": "0x<32-byte-hex>",
  "job_index": 0,
  "worker_lock_args": "0x<20-byte-hex>",
  "result_hash": "0x<32-byte-hex or omit>",
  "completed_at_tx": "0x<32-byte-hex>"
}

Mints a soulbound PoP (Proof of Participation) badge under the worker's lock. The badge records the job reference, result hash, and completion transaction on-chain via the dob-badge contract.

finalize_reputation

{
  "intent": "finalize_reputation",
  "rep_tx_hash": "0x<32-byte-hex>",
  "rep_index": 0
}

Finalizes a pending reputation proposal after the dispute window has elapsed. The reputation cell transitions from Proposed back to Idle with updated counters and proof root.

mint_reputation_capability

{
  "intent": "mint_reputation_capability",
  "capability_hash": "0x<32-byte-hex>",
  "reputation_proof_root": "0x<32-byte-hex>",
  "settlement_hash": "0x<32-byte-hex>"
}

Mints a capability NFT linked to the agent's reputation proof chain. The reputation_proof_root and settlement_hash anchor the capability to verifiable on-chain history.

propose_reputation

{
  "intent": "propose_reputation",
  "rep_tx_hash": "0x<32-byte-hex>",
  "rep_index": 0,
  "propose_type": 1,
  "dispute_window_blocks": 100,
  "job_tx_hash": "0x<32-byte-hex>",
  "job_index": 0,
  "worker_lock_args": "0x<20-byte-hex>",
  "poster_lock_args": "0x<20-byte-hex>",
  "reward_shannons": 500000000,
  "result_hash": "0x<32-byte-hex or omit>"
}

Computes a settlement hash from the job completion evidence and embeds it in the reputation cell, building the blake2b proof chain.

Workflow

1. Verify agent balance is sufficient (call GET /agent/balance).
2. Call POST /tx/build-and-broadcast with the intent payload.
3. On success: poll GET /tx/status?tx_hash=<hash> every 5 seconds until status is committed. There is no poll limit — keep polling until the TX is committed. CKB testnet can be slow; do not give up.
4. On error: parse the structured error, correct the parameter, and retry once.

Error Handling

The TX Builder returns structured errors. Common cases:

Payment After Job Completion

If a job embeds Fiber payment metadata, POST /jobs/:tx_hash/:index/complete now attempts the Fiber payment automatically right after the on-chain completion succeeds. The response includes both the completion tx data and fiber_payment details (or fiber_payment_error if the auto-payment attempt failed after completion). If you set payment.amount_ckb, use a routable amount for the currently available Fiber liquidity; otherwise the auto-payment can still fail even when the hook is working correctly.

Manual fallback remains available: after a job reaches the Completed state, the poster can still pay the worker directly using the worker's lock_args from the job cell. This uses the MCP bridge's pay-agent endpoint which resolves the pubkey automatically.

curl -s -X POST http://localhost:8081/fiber/pay-agent \
  -H 'Content-Type: application/json' \
  -d '{
    "lock_args": "<worker_lock_args from job cell>",
    "amount_ckb": 5,
    "description": "payment for completed job"
  }' | jq .

This is simpler than the full escrow workflow when trust is already established or the on-chain reward is the primary compensation mechanism.

Result Format

Write to Memory on completion:

{
  "worker": "marketplace-worker",
  "action": "<action>",
  "status": "success | error",
  "tx_hash": "<0x...>",
  "tx_confirmed": true,
  "result": "<full result string from the worker, if applicable>",
  "error": null,
  "next_hint": "<what to do next>"
}

Always include the full result string (not a summary) when one exists. The supervisor will relay it to the user as-is.