---
name: sup-delegation-design
description: >-
  DESIGN a safe Sup Wallet delegation policy by composing rules — decide who may
  spend (auth rules, OR-gated) and under what conditions (caveat rules,
  AND-gated), pick a revocation strategy, and avoid the foot-guns. Use when
  someone wants to let an AI agent / address / contract / sub-team spend from a
  vault under limits, set up sub-delegation or inheritance, or reason about
  whether a delegation setup is safe. For WRITING a new rule package in Move use
  `sup-policy-rule-dev`; for wrapping a protocol use `sup-adaptor-dev`.
license: MIT
---

# Sup Delegation — Design Skill

You help someone **design a delegation policy** for a Sup Wallet: choose and
compose rules so a delegate can spend exactly as much as intended and no more.
You are not writing Move here — you are selecting building blocks and wiring them
through the SDK. (If a needed condition doesn't exist yet, hand off to
`sup-policy-rule-dev` to author it.)

## The model in 6 lines

- A delegated spend emits a `SpendRequest` hot potato; `policy::confirm_spend`
  releases funds only if rules approve it.
- **Auth rules are OR-gated**: ≥1 must stamp. They answer *who is the principal*.
- **Caveat rules are AND-gated**: every one must stamp. They answer *is this spend allowed*.
- A rule can only **read** the request (amount / recipient / coin) and **stamp or abort** — it can never change where money goes.
- Funds leave the wallet **only at `confirm_spend`**, after all checks pass.
- `policy::revoke_all` bumps a version that **instantly invalidates every outstanding cap / sub-delegation**.

## Design in three questions

**1 · Who is the delegate? → choose auth rule(s).**

| The delegate is… | Use |
| :--- | :--- |
| an AI agent / a person / a machine (one key) | `CapAuth` — mint a `DelegateCap` to their address |
| a contract that should spend autonomously | `CapAuth` — the cap lives inside the contract's field |
| a sub-team / sub-agent with its own budget | `ScopedAuth` — a budgeted `ScopedCap` (see Q2) |
| several independent principals | add several auth rules (OR) — **any** one can then spend |
| a ZK proof / an 8183 job assessor | a custom auth rule (`sup-policy-rule-dev`) |

> ⚠️ Auth is OR. Every auth rule you add is an *independent* way in. Only add auth
> rules you trust; one weak auth rule weakens the whole wallet.

**2 · What are the limits? → choose caveat rule(s).**

| You want to cap… | Use |
| :--- | :--- |
| total amount per delegate / per coin | a budgeted `ScopedCap` (`ScopedBudget`) — the budget lives in the cap |
| who can receive funds | `RecipientAllowlist` (reference rule) |
| time window / rate / oracle price / KYC … | a custom caveat rule (`sup-policy-rule-dev`) |

> ⚠️ Caveat is AND. More caveats = stricter. An **empty** caveat set means *only*
> auth gates the spend — fine for a fully-trusted cap, dangerous otherwise.

**3 · How do you revoke? → strategy.**

- Global kill-switch: `revokeAllPolicies` (version bump) — instantly voids every
  cap and sub-delegation. The default.
- Narrowing: `removeAuthRule` / `removeCaveatRule` to change the policy shape.
- Per-cap selective revoke is not built yet — if you need it, note it as a
  requirement (custom rule with a revocation set).

## Recipes (compose these)

**Managed AI agent, capped, fixed payees**
- auth: `CapAuth` → mint a `DelegateCap` to the agent.
- caveat: `RecipientAllowlist` (only your payees) + a budget. For a hard budget,
  issue a **scoped** cap instead (next recipe) so the amount is enforced on-chain.

**Spending limit that actually decrements**
- Use a `ScopedCap` (`mintScopedRoot`, one coin + budget). It stamps `ScopedAuth`
  + `ScopedBudget` and debits itself each spend. Add `RecipientAllowlist` too if
  you also want to bound the destination.

**Sub-delegation tree (org / sub-agents)**
- `mintScopedRoot(budget, maxDepth)` to a team lead; they `subdelegate(amount)` to
  members. Each child ≤ parent, `depth + 1`, parent debited. `maxDepth` bounds the
  tree. `revokeAll` kills the whole tree.

**Inheritance / dead-man switch**
- Today: the `SupInheritance` module (time-lock + member caps, Mode-C payout).
- In the policy model: a custom liveness caveat + a member auth rule
  (`sup-policy-rule-dev`).

**Escrow / agent-to-agent commerce (ERC-8183)**
- Roadmap: a `Job` escrow released by an `assessor` auth rule. The assessor is
  just another rule — design it like any auth rule.

## Wire it (SDK)

```ts
const sup = createSupWalletClient({ network, runtime });
await sign(sup.initializePolicy({ walletId }));
await sign(sup.addAuthRule({ walletId, ruleType: sup.capAuthRuleType() }));
await sign(sup.addCaveatRule({ walletId, ruleType: sup.recipientAllowlistRuleType() }));
await sign(sup.createAllowlist({ walletId }));
await sign(sup.allowlistAllow({ allowlistId, recipient: payee }));
await sign(sup.mintDelegateCap({ walletId, recipient: agent }));
// agent spends, holding the cap:
await sign(sup.capSpendWithAllowlist({ walletId, capId, allowlistId, coinType, amount, recipient: payee }));
```

Scoped / sub-delegation: `mintScopedRoot`, `subdelegate`, `scopedSpend`.
Revoke: `revokeAllPolicies`.

## Safety review checklist (run on any design)

- [ ] Every **auth** rule is one you'd trust alone (OR — they don't combine, they each suffice).
- [ ] The **caveat** set actually bounds the risk you care about (amount? recipient? time?). Empty caveats ⇒ auth-only.
- [ ] If a cap must respect a hard amount, it's a **scoped** cap (budget on-chain), not a bearer cap + an off-chain promise.
- [ ] Sub-delegation `maxDepth` and root budget are sized deliberately.
- [ ] There is a revocation plan (`revokeAll` at minimum).
- [ ] You tested the **deny** paths (over-budget, wrong recipient, revoked), not just the happy path.
- [ ] No rule is expected to *move* funds — a rule's only power is to allow or block.

## Pointers

- Concepts + SDK quickstart: `/docs/delegation`. Write a rule: `/docs/build-a-rule`.
- Full design + APIs: historical [`DELEGATION_POLICY.md`](https://github.com/ZzyzxLabs/zzyzx-full-repo/blob/16fceb6d1de5bc13a1cfe580034abd7efc9a4538/ZZYZX-Contract/Sup_Contract/sup_wallet/DELEGATION_POLICY.md).
- One-page architecture: historical [`ARCHITECTURE.md`](https://github.com/ZzyzxLabs/zzyzx-full-repo/blob/16fceb6d1de5bc13a1cfe580034abd7efc9a4538/ZZYZX-Contract/Sup_Contract/sup_wallet/ARCHITECTURE.md).
- Author a missing rule: the `sup-policy-rule-dev` skill.

> Design rule of thumb: **start from the smallest authority that does the job.**
> One scoped cap with a tight budget and an allowlist beats an unlimited bearer
> cap plus good intentions. Add caveats until a malicious delegate can do nothing
> worse than waste their own allowance on an allowed recipient.