Delegation sessions
How a root wallet grants a delegate bounded authority to act on an Atom, and how to revoke it.
A root is the Buyer or Seller wallet that an Atom binds permanently. A root can let another address act for it by creating a session. A session is a bounded, on-chain grant: it names the delegate, the actions allowed and the limits. It never turns the delegate into a root.
Implementation candidate
Roles
Sinera keeps these identities separate:
| Role | What it is |
|---|---|
| Root | The Buyer or Seller principal of an Atom. Fixed for that Atom |
| Payer | The address that funds escrow. It does not become a root and cannot redirect a refund |
| Delegate | The exact address a root authorized in one session |
| Operator | An off-chain trigger for a SessionExecutor. It holds no on-chain authority of its own |
A login account, a funding record or a webhook is application state. None of them is an ATP authority. Refunds always go to the root Buyer.
What a session can do
A session grants one or more of five action bits. These are the only actions a delegate can ever take.
| Action | Root side | What it does | New spend charged |
|---|---|---|---|
BUY_CREATE_AND_ESCROW | Buyer | Create an Atom and fund escrow | The gross value |
SELL_ACCEPT_ORIGINAL | Seller | Accept the original terms | None |
SELL_PROPOSE_REVISION | Seller | Propose a revision | None |
BUY_REACCEPT_TERMS | Buyer | Accept a revision | None |
BUY_CONFIRM_COMPLETION | Buyer | Confirm completion | None |
No action bit covers opening or answering a dispute. A delegate can never touch a dispute, and a purchase grant does not imply completion authority. A session belongs to one root, so a Buyer and a Seller each create their own.
Bounds
A root creates a session on-chain. The session binds one root, one delegate, one configuration, one settlement token, an action mask and a lifetime. It can also bound:
- the counterparty, object, asset and policy;
- the completion modes and time ranges;
- value, quantity and unit price per action;
- spend per Atom, per period and over the whole lifetime.
Some rules are mandatory:
- A Seller session needs a minimum gross value. An asset-scoped Seller session needs a minimum unit price, and any Seller action with a nonzero quantity enforces it.
- An asset-scoped Buyer session needs a maximum unit price.
- Actions that form terms need an exact resolution-policy scope.
- Only
BUY_CREATE_AND_ESCROWcounts as new spend. Spend is never restored after a refund. - If the surrounding transaction reverts, the session consumption rolls back with it.
Lifetime
| Lifetime | Behavior |
|---|---|
ONE_SHOT | The first successful delegated action uses up the session, even a zero-spend action |
UNTIL_TIMESTAMP | Active only while the current time is before validUntil |
NO_EXPIRY | No time limit. Requires positive per-Atom and per-period caps, a positive period, and a bounded profile and scope |
Period spend uses fixed periods, not a sliding window:
periodIndex(now) = floor((now - session.createdAt) / periodSeconds)The exact boundary starts the next period. Lifetime spend never resets.
Session executor
A SessionExecutor is an optional, prefunded payer for automated purchases. It can call only the create-and-escrow path for its own session, root and token. For each purchase it:
- gives the escrow vault an exact, temporary allowance;
- checks that the spend matches exactly;
- clears the allowance; and
- lets only the root sweep leftover funds.
External funding, such as a card on-ramp, should land in the root wallet first. Funding completion never creates a session and never creates an Atom.
Revoke
The root keeps control at all times:
- Revoke one session. The delegate can no longer act under it.
- Advance the root epoch. Every older session of that root becomes invalid at once.
Changing the default wallet in an application affects only future sessions. Sessions and executor funds that belong to the old root stay with that root, so revoke them and reclaim executor funds separately.
Do not give a service signer direct root entrypoints
Session limits apply only to the *WithSession calls. If a root wallet lets a service signer call the direct root entrypoints, that signer can bypass every session bound.