Policies
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.
A policy is a versioned document of objective rules that governs a budget. It can only narrow what the budget's own mandate already allows: the core compiles it into the intersection of the budget's mandate and the rules the document names, and checks it before every stream open, meter and reservation. A dry-run answers what the policy would refuse, and why, without recording anything.
Policies are on owner-api 1.8.0. On the hosted tier, pin Dynamo-Version: 1.8.0 to reach these routes. Status: Live.
Scopes
A document belongs to one scope:
budget: one budget, by its id. It governs that budget directly.organisationorteam: it governs every budget bound to that scope. Organisations and teams come from your deployment's organisation registry; a scope that does not exist is refused (policy_scope).
Budgets opened without a mandate (before mandates existed) take no policy.
A budget is governed by its own policy and by the current policy of every scope it is bound to. Every one of them must admit an action.
Limits count one budget at a time: an organisation policy bound to several budgets applies its per-period, velocity and vendor limits to each budget's own usage, not to their sum.
The document
{
"typ": "dynamo-policy-v1",
"scope": { "kind": "budget", "id": "bdg_…" },
"version": 1,
"rules": {
"categories": ["search", "voice"],
"payees": ["0x…"],
"payeeDeny": ["0x…"],
"maxDepth": 3,
"perTransactionMax": "200",
"perPeriod": { "seconds": 3600, "max": "1000" },
"vendorLimits": [{ "payee": "0x…", "perPeriod": { "seconds": 86400, "max": "500" } }],
"velocity": { "seconds": 60, "maxAdmissions": 30 },
"approval": { "capAbove": "5000", "reserveAbove": "100" },
"killSwitch": false
}
}
Every field of rules is optional, but a document names at least one. Unknown fields refuse (policy_invalid). Amounts are units as decimal digit strings.
| Rule | What it does |
|---|---|
categories | allow-list of stream categories ("*" for any) |
payees, payeeDeny | allow-list and deny-list of service nodes |
maxDepth | the deepest delegation allowed |
validFrom, validUntil | unix seconds; admissions outside the window refuse |
perTransactionMax | the most units in one meter or reservation |
perPeriod | the most units billed or held in any window of seconds, budget-wide |
vendorLimits | per service node: a per-transaction max and/or a per-period max |
velocity | the most meters and reservations in any window of seconds, budget-wide |
approval | opens above capAbove or deeper than depthAbove, and reservations above reserveAbove, wait for an approval (timeoutSeconds sets how long one may wait); a direct meter without a reservation above reserveAbove is refused (approval_required), so callers on an approval-gated stream reserve first; an approval waives only the threshold it was raised for |
killSwitch | true refuses every admission under the scope |
The compiled mandate is never broader than the document or the budget's mandate. Where the two disagree, the narrower wins; if nothing is left (for example disjoint category lists), every admission is refused.
Routes
| Route | What it does |
|---|---|
POST /owner/v1/policies | {document}: set the scope's next version (the current version plus one; policy_version otherwise). A document whose limits fall below a reservation already held on a governed budget refuses amend_floor and writes nothing; so does a binding |
GET /owner/v1/policies?scopeKind=&scopeId= | the current document and the signed history |
POST /owner/v1/policies/dry-run | {budgetId, actions, document?}: each action's verdict (admit, refuse with the rule, or approval with the threshold) |
POST /owner/v1/policies/bindings | {budgetId, scope}: bind a budget to an organisation or team scope |
POST /owner/v1/policies/bindings/remove | remove that binding |
GET /owner/v1/budgets/:id/policies | the policies governing the budget, each compiled, with their signed records |
A dry-run action is {"kind": "open", "serviceNode", "capUnits", "parentStreamId"?, "category"?} or {"kind": "spend", "streamId", "units", "reserve"?}. With document, that document stands in for its scope's current one, so you can try a change before you set it. The dry-run answers the policy layer; the budget's caps and mandates still apply live. Every action the dry-run refuses is also refused live.
Bringing the modes level
A deployment with several funding modes keeps an organisation or team document in each mode's policy book, and each book signs its own record. If a write stops between two books, one book is a version ahead and the next version refuses policy_version. To bring them level, send the current document again, unchanged, to POST /owner/v1/policies. The book that is behind writes it and signs its own record. A book that already has it is left as it is. Sending it again changes nothing. A different document at that version still refuses policy_version.
Refusals
A refused meter or reservation answers halted with reason policy to a client pinned at Dynamo-Version: 1.8.0 or sending Dynamo-Error-Detail: 1 (which adds errorDetail); any other client sees its legacy reason cap. A refused open answers mandate with reason policy. The detail names the rule and the policy version. See policy.
Try it on a local core
With a local core running in Control Mode and DYNAMO_OWNER_TOKEN exported: an organisation with one team, a budget opened for the team, an organisation policy that allows only the research category and at most 200000 units per meter, a dry-run, then the same refusals live.
cd "$DYNAMO_REPO"
pwd
U=http://127.0.0.1:8790
H=(-H "authorization: Bearer $DYNAMO_OWNER_TOKEN" -H "content-type: application/json" -H "Dynamo-Error-Detail: 1")
curl -s -X POST "$U/owner/v1/orgs" "${H[@]}" -d '{"orgId": "acme"}'
curl -s -X POST "$U/owner/v1/orgs/acme/teams" "${H[@]}" -d '{"teamId": "research-team"}'
BUDGET=$(curl -s -X POST "$U/owner/v1/orgs/acme/teams/research-team/budgets" "${H[@]}" \
-d '{"budget": {"funding": "none", "capTotal": "5000000", "mandate": {"categories": ["research", "voice"], "maxDepth": 3}}, "agent": "researcher"}' \
| python3 -c 'import json, sys; print(json.load(sys.stdin)["budgetId"])')
curl -s -X POST "$U/owner/v1/policies" "${H[@]}" \
-d '{"document": {"typ": "dynamo-policy-v1", "scope": {"kind": "organisation", "id": "acme"}, "version": 1, "rules": {"categories": ["research"], "perTransactionMax": "200000"}}}'
curl -s "$U/owner/v1/budgets/$BUDGET/policies" "${H[@]}"
curl -s -X POST "$U/owner/v1/policies/dry-run" "${H[@]}" \
-d "{\"budgetId\": \"$BUDGET\", \"actions\": [{\"kind\": \"open\", \"serviceNode\": \"0x00000000000000000000000000000000000000A1\", \"capUnits\": \"1000000\", \"category\": \"voice\"}]}"
curl -s -X POST "$U/owner/v1/budgets/$BUDGET/streams" "${H[@]}" \
-d '{"serviceNode": "0x00000000000000000000000000000000000000A1", "ratePerSecondUnits": "1000000", "capUnits": "1000000", "category": "voice"}'
STREAM=$(curl -s -X POST "$U/owner/v1/budgets/$BUDGET/streams" "${H[@]}" \
-d '{"serviceNode": "0x00000000000000000000000000000000000000A1", "ratePerSecondUnits": "1000000", "capUnits": "1000000", "category": "research"}' \
| python3 -c 'import json, sys; print(json.load(sys.stdin)["streamId"])')
sleep 1
curl -s -X POST "$U/owner/v1/streams/$STREAM/ticks" "${H[@]}" -d '{"units": "300000"}'
curl -s -X POST "$U/owner/v1/streams/$STREAM/ticks" "${H[@]}" -d '{"units": "100000"}'
Assigning the budget to the team bound it to acme and research-team, so GET …/policies lists the organisation's document with its compiled mandate (the budget's mandate narrowed to research). The dry-run answers refuse with rule category; the voice open is refused live with {"error": "mandate", "reason": "policy"}; the 300000 unit meter is refused with reason policy (rule per_transaction) and bills nothing; the 100000 unit meter is admitted and signed. Organisation ids are 2 to 48 characters [a-z0-9-]: pick another id if acme exists on your core.
Records and evidence
Every new version, binding and removal is a record signed by the core, linked to the previous record of its scope (or of the budget's bindings), and anchored to the budget's signed authority record or to the organisation's or team's own record. Each record names who acted. The budget's evidence export carries the records that govern it, and both offline verifiers check them.