Task Allowance

Not in the preview yet. This feature is built in the repository but is off in the v2.2.6 preview (test mode). Do not treat this page as available on a preview core. See ../preview.md and the release notes.

Pay a payee for delivered work from a funded cap, once the work is accepted: by the evaluator named in the quote, by the funder, or by silence when the acceptance window ends. Owner-api 1.8.0; on the hosted tier only clients pinned at Dynamo-Version: 1.8.0 see these routes. It runs on Control Mode, the credit card rail and contract v2; a stablecoin budget on contract v1 is refused at create (task_rail_unsupported). Status: Live in Control Mode, with the credit card rail in Stripe TEST mode and with contract v2 on a local chain; real money is Release-gated. In a money mode the funder's stream open needs a signed hop, because own hops are required by default. The lifecycle and its ERC-8183 mapping are in docs/spec/drafts/task-allowance.md.

The flow

  1. The payee quotes. It signs a dynamo-task-quote-v1 with its own

key: milestones (units each), an optional streamed allowance, the evaluator, the acceptance window (1 hour to 30 days, default 72 hours), the delivery deadline, and the objective standards a rejection may name (catalogue terms from GET /payee/v1/terms/catalogue).

  1. The funder funds. Open a stream to the payee with

POST /owner/v1/budgets/{id}/streams, cap equal to the quote's total and a rate that reaches it within the window, then bind it:

``http POST /owner/v1/tasks {"budgetId": "…", "streamId": "…", "quote": {"quote": {…}, "signature": "0x…"}, "accept": "0x<quote hash>"} ``

  1. The payee delivers. POST /payee/v1/tasks/{id}/deliveries with its

signed dynamo-task-delivery-v1 (milestone, units, the SHA-256 of the work). The acceptance window starts.

  1. Acceptance.

evaluator or the funder pays the milestone at once;

before the window ends and naming a declared standard, leaves the claim unpaid;

ends and pays it.

  1. Close. When every milestone is completed, rejected or expired, the

stream is settled and revoked; what was not billed goes back to the budget. GET /owner/v1/tasks/{id} shows billedUnits and refundedUnits.

Streamed pay: POST /payee/v1/tasks/{id}/units {units, requestRef} up to the quote's streamed allowance, answered only once a voucher covering it is signed.

The signed payloads

Each payload is a JSON object with exactly the fields below; unknown or missing fields are refused. Each signature is EIP-191 (personal sign) over the 32-byte keccak-256 of the payload's canonical JSON (keys sorted, no spaces), from the key that the payload names: the quote and every delivery by the payee, a decision by the evaluator (or, to accept, the funder). Addresses are EIP-55 checksummed before hashing.

PayloadFieldsSent as
dynamo-task-quote-v1typ, serviceNode, evaluator, milestones ([{id, units}], 1 to 16), streamUnits, acceptanceWindowSeconds, deliverWithinSeconds (60 seconds to 30 days), standards (a catalogue terms set or null), proof ("sha256"), issuedAt, expiresAtquote: {quote, signature} at create, with accept = the quote's hash
dynamo-task-delivery-v1typ, taskId, milestoneId, units, deliverable (0x + the SHA-256 of the work, lowercase), issuedAt{delivery, signature}
dynamo-task-decision-v1typ, taskId, milestoneId, decision (accept or reject), deliveryHash (the delivery's hash), standard (null to accept), issuedAt{decision, signer, signature}

Units and times are decimal strings; the two window lengths are numbers. Payee routes authenticate with the payee's own Dynamo-Payee v2 proof for that request (see getting paid as a payee).

The Python SDK builds and signs each one: dynamoprotocol.tasks (task_quote, sign_task_quote, task_quote_cap_units, task_delivery, sign_task_delivery, task_decision, sign_task_decision, task_payload_hash, deliverable_hash), and dynamoprotocol.payee.PayeeClient(...).authorize(method, path, body) gives the Dynamo-Payee v2 header for one request (send that exact body). The agent network example runs the same flow in TypeScript between agents of different owners.

Try it on a local core

With a local core running in Control Mode, DYNAMO_OWNER_TOKEN exported and the Python SDK installed with its verify extra (packages/sdk-python/README.md). The payee and the evaluator are fresh keys in memory; the funder is the owner token.

cd "$DYNAMO_REPO"
pwd
DYNAMO_CORE_URL=http://127.0.0.1:8790 .venv-dynamo/bin/python - <<'PY'
import json, os, time, httpx
from eth_account import Account
from dynamoprotocol.payee import PayeeClient
from dynamoprotocol.tasks import (deliverable_hash, sign_task_decision, sign_task_delivery, sign_task_quote,
                                  task_decision, task_delivery, task_payload_hash, task_quote, task_quote_cap_units)

url = os.environ["DYNAMO_CORE_URL"]
owner = {"authorization": f"Bearer {os.environ['DYNAMO_OWNER_TOKEN']}", "Dynamo-Error-Detail": "1"}
payee, evaluator = Account.create(), Account.create()
http = httpx.Client(base_url=url, timeout=30)

def ok(r):
    assert r.status_code == 200, r.text
    return r.json()

# 1. The payee quotes one milestone of 500000 units (0.50 USD).
quote = task_quote(payee.address, evaluator.address, [("m1", 500_000)], acceptance_window_seconds=3600, deliver_within_seconds=600)
# 2. The funder opens a stream to the payee capped at the quote's total, and binds the task.
cap = str(task_quote_cap_units(quote))
budget = ok(http.post("/owner/v1/budgets", headers=owner, json={"funding": "none", "capTotal": "5000000"}))
stream = ok(http.post(f"/owner/v1/budgets/{budget['budgetId']}/streams", headers=owner,
                      json={"serviceNode": payee.address, "ratePerSecondUnits": cap, "capUnits": cap}))
time.sleep(1.1)
task = ok(http.post("/owner/v1/tasks", headers=owner, json={"budgetId": budget["budgetId"], "streamId": stream["streamId"],
                                                             "quote": sign_task_quote(payee.key, quote), "accept": task_payload_hash(quote)}))
# 3. The payee delivers, signed with its own key; the acceptance window starts.
delivery = task_delivery(task["taskId"], "m1", 500_000, deliverable_hash(b"the delivered report"))
path = f"/payee/v1/tasks/{task['taskId']}/deliveries"
body = json.dumps(sign_task_delivery(payee.key, delivery))  # the proof covers these exact bytes
ok(http.post(path, headers={"authorization": PayeeClient(url, payee).authorize("POST", path, body),
                            "content-type": "application/json"}, content=body))
# 4. The evaluator accepts: the milestone is paid at once.
decision = task_decision(task["taskId"], "m1", "accept", task_payload_hash(delivery))
ok(http.post(f"/owner/v1/tasks/{task['taskId']}/accept", headers=owner, json=sign_task_decision(evaluator.key, decision)))
final = ok(http.get(f"/owner/v1/tasks/{task['taskId']}", headers=owner))
records = ok(http.get(f"/owner/v1/tasks/{task['taskId']}/records", headers=owner))["records"]
print(final["status"], "billed", final["billedUnits"], "refunded", final["refundedUnits"])
print(" -> ".join(r["payload"]["kind"] for r in records))
PY

It prints completed billed 500000 refunded 0 and the signed records created -> submitted -> accepted -> paid -> closed. To see acceptance by silence on a local core, boot it with CORE_TEST_CLOCK=1 and move its clock past the window (the test clock).

Routes

RouteWho
POST /owner/v1/tasksowner
GET /owner/v1/tasks (?budgetId=, ?limit=&cursor=)owner
GET /owner/v1/tasks/{id}owner
GET /owner/v1/tasks/{id}/recordsowner
POST /owner/v1/tasks/{id}/acceptowner, carrying the evaluator's or funder's signature
POST /owner/v1/tasks/{id}/rejectowner, carrying the evaluator's signature
GET /payee/v1/tasks/{id}the task's payee
POST /payee/v1/tasks/{id}/deliveriesthe task's payee
POST /payee/v1/tasks/{id}/unitsthe task's payee

Payee routes take the payee's own Dynamo-Payee v2 proof for that request or a payee credential; a task of another payee answers 404. Every body is strict: unknown fields are refused.

Guarantees

milestones, units never claimed. That value was never paid, so it is unspent budget returning, not a refund. Units already streamed stay paid.

authorization's expiry, or the contract v2 budget's expiry) is refused at create: task_beyond_funded_horizon.

offline, and an event (task.*, events 1.6.0).

a reservation or a child open on it is refused (task_stream_bound).

Halts

revoke is refused (task_payment_pending). A revoke that reaches a claim still inside its window is held: the stream is not revoked yet, every other spend under it is refused, no new claim or streamed pay is taken, and the claim keeps its window. Silence still pays it, the evaluator can still reject it inside the window, and the scheduler completes the revoke once no claim under it is open. revokeHeldAt on the task shows the hold; the hold itself is a signed record.

emergency stop in freeze mode, take effect at once. An emergency stop in revoke mode pays accepted work first; while that payment cannot be signed yet, the stop holds every allowance of the budget instead: only the owed milestones' payments go through, no new milestone is accepted (by the evaluator or by silence) and no new allowance opens. The scheduler completes the revoke as soon as the owed work is paid. Clients pinned at owner-api 1.9.0 see revokePending: true on the stop's answer; after 24 hours still held, the owner and the operator are alerted (settlement.failed with code stop_revoke_pending, and email).

(task_stream_halted). A claim under a freeze, or under a stop in freeze mode, waits: it is accepted by silence after the thaw.

Errors: the task_* codes in all error codes.