Skip to content
SineraDocs

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:

RoleWhat it is
RootThe Buyer or Seller principal of an Atom. Fixed for that Atom
PayerThe address that funds escrow. It does not become a root and cannot redirect a refund
DelegateThe exact address a root authorized in one session
OperatorAn 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.

ActionRoot sideWhat it doesNew spend charged
BUY_CREATE_AND_ESCROWBuyerCreate an Atom and fund escrowThe gross value
SELL_ACCEPT_ORIGINALSellerAccept the original termsNone
SELL_PROPOSE_REVISIONSellerPropose a revisionNone
BUY_REACCEPT_TERMSBuyerAccept a revisionNone
BUY_CONFIRM_COMPLETIONBuyerConfirm completionNone

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_ESCROW counts as new spend. Spend is never restored after a refund.
  • If the surrounding transaction reverts, the session consumption rolls back with it.

Lifetime

LifetimeBehavior
ONE_SHOTThe first successful delegated action uses up the session, even a zero-spend action
UNTIL_TIMESTAMPActive only while the current time is before validUntil
NO_EXPIRYNo 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:

  1. gives the escrow vault an exact, temporary allowance;
  2. checks that the spend matches exactly;
  3. clears the allowance; and
  4. 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.

Next