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
- The payee quotes. It signs a
dynamo-task-quote-v1with 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).
- 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>"} ``
- The payee delivers.
POST /payee/v1/tasks/{id}/deliverieswith its
signed dynamo-task-delivery-v1 (milestone, units, the SHA-256 of the work). The acceptance window starts.
- Acceptance.
POST /owner/v1/tasks/{id}/acceptwith a decision signed by the
evaluator or the funder pays the milestone at once;
POST /owner/v1/tasks/{id}/reject, signed by the evaluator only,
before the window ends and naming a declared standard, leaves the claim unpaid;
- otherwise the always-on scheduler accepts the claim when the window
ends and pays it.
- 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.
| Payload | Fields | Sent as |
|---|---|---|
dynamo-task-quote-v1 | typ, 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, expiresAt | quote: {quote, signature} at create, with accept = the quote's hash |
dynamo-task-delivery-v1 | typ, taskId, milestoneId, units, deliverable (0x + the SHA-256 of the work, lowercase), issuedAt | {delivery, signature} |
dynamo-task-decision-v1 | typ, 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
| Route | Who |
|---|---|
POST /owner/v1/tasks | owner |
GET /owner/v1/tasks (?budgetId=, ?limit=&cursor=) | owner |
GET /owner/v1/tasks/{id} | owner |
GET /owner/v1/tasks/{id}/records | owner |
POST /owner/v1/tasks/{id}/accept | owner, carrying the evaluator's or funder's signature |
POST /owner/v1/tasks/{id}/reject | owner, carrying the evaluator's signature |
GET /payee/v1/tasks/{id} | the task's payee |
POST /payee/v1/tasks/{id}/deliveries | the task's payee |
POST /payee/v1/tasks/{id}/units | the 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
- Delivered work that is accepted, explicitly or by silence, is paid, once.
- Only unaccepted value goes back to the budget (
refundedUnits): rejected claims, expired
milestones, units never claimed. That value was never paid, so it is unspent budget returning, not a refund. Units already streamed stay paid.
- A task whose window could end after its funding does (the credit card
authorization's expiry, or the contract v2 budget's expiry) is refused at create: task_beyond_funded_horizon.
- Every step is a signed record (
dynamo-task-record-v1) that verifies
offline, and an event (task.*, events 1.6.0).
- A stream that funds a task is paid only through the task: an owner tick,
a reservation or a child open on it is refused (task_stream_bound).
Halts
- Revoke. Accepted work is paid first; while it cannot be signed yet the
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.
- Freeze and emergency stop are never refused. A freeze, and an
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).
- A claim still open at an emergency stop in revoke mode stays unpaid
(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.