Skip to content
SineraDocs

Atoms and lifecycle

The five Atom states, every allowed transition, and the deadline rules that decide who can act and when.

Every Commercial Atom follows a fixed state machine. This page lists the states, the transitions between them, and the timing rules. Only the transitions shown here exist.

Implementation candidate

States and outcomes

An Atom is in exactly one of five coarse states.

StateMeaning
PENDING_ACCEPTANCEFunds are escrowed. The Seller has not yet accepted the terms
PENDING_REACCEPTANCEThe Seller proposed a revision. The Buyer has not yet accepted it
ACTIVEBoth sides agreed. The work is running or waiting to be confirmed
DISPUTEDA root opened a dispute. A case is in progress
FINALIZEDThe Atom has a terminal outcome. Nothing can change it

CANCELLED and EXPIRED are outcomes, not extra states. FINALIZED is absorbing: once an Atom reaches it, no transition leaves it.

The terminal outcomes are:

OutcomeSeller shareWhen it happens
RELEASE10,000 BPS (all)Buyer confirms, or the challenge window ends with no dispute, or a dispute resolves for the Seller
REFUND0 BPSA dispute resolves for the Buyer
SPLIT1 to 9,999 BPSA dispute resolves with a shared result
CANCELLED0 BPSA root cancels while the Atom is pending
EXPIRED0 BPSA pending deadline passes

A basis point (BPS) is one hundredth of a percent, so 10,000 BPS is 100%.

Transitions

FromTriggerTo
PENDING_ACCEPTANCESeller acceptsACTIVE
PENDING_ACCEPTANCESeller proposes a revisionPENDING_REACCEPTANCE
PENDING_ACCEPTANCEEither root cancels before the deadlineFINALIZED (CANCELLED)
PENDING_ACCEPTANCEAnyone calls the timeout at the deadlineFINALIZED (EXPIRED)
PENDING_REACCEPTANCEBuyer accepts the revisionACTIVE
PENDING_REACCEPTANCEEither root cancels before the deadlineFINALIZED (CANCELLED)
PENDING_REACCEPTANCEAnyone calls the timeout at the deadlineFINALIZED (EXPIRED)
ACTIVEValid Buyer completionFINALIZED (RELEASE)
ACTIVEAnyone calls the challenge timeoutFINALIZED (RELEASE)
ACTIVEA root opens a dispute (only if the Atom allows it)DISPUTED
DISPUTEDEligible agreement or awardFINALIZED (RELEASE, REFUND or SPLIT)

An Atom starts in PENDING_ACCEPTANCE when the Seller must accept on-chain. If the Atom is created with no acceptance step, the Seller signs at creation and the Atom starts in ACTIVE.

Timing rules

All timing uses the block timestamp. Time alone never moves an Atom: a timeout only becomes callable, and someone must send a transaction.

  • Pending deadline. The acceptance deadline is the creation time plus the acceptance window. Actions are allowed while now is before the deadline. At the deadline, the permissionless timeout takes over.
  • Revision. A revision can change only the completion mode, the execution duration and the challenge window. It must keep a positive challenge window. The Buyer then has a reacceptance window that never extends past the proposal deadline.
  • Active deadlines. After activation, executionDeadline is the activation time plus the execution duration. challengeDeadline is the execution deadline plus the challenge window. The challenge window must be positive. The execution duration may be zero.

The Buyer can confirm completion at any time before challengeDeadline, including before the execution deadline.

Completion modeRoot Buyer can confirmBuyer delegate can confirmChallenge timeout releases
ROOT_ONLYYesNoYes
ROOT_OR_DELEGATEYesYes, with a matching session actionYes
TIMEOUT_ONLYNoNoYes

An action uses "before T" and its paired timeout uses "at or after T", so exactly one of them owns each moment. When two valid transactions compete, such as a completion and a dispute opening, the first one included on chain wins. A signature or mempool arrival reserves nothing.

Disputes

A dispute is possible only if the Atom was created with the EITHER_ROOT dispute preset. With the DISABLED preset, no dispute can ever open and the Atom exits through completion or the challenge timeout.

Either root, and only a root, can open a dispute in the window from executionDeadline up to but not including challengeDeadline. Opening starts a procedure. It does not choose a payout and does not move funds.

A case has two live phases:

  1. Negotiation. Starts when the dispute opens and lasts for the Atom's negotiation window.
  2. Arbitration. Anyone can advance the case here once negotiation ends. Arbitration has no end time.

The ways out of a dispute depend on the time:

PeriodBuyer and Seller agreeSinera approval plus one rootIndependent award
During negotiationAvailableAvailableNot available
After negotiation, first 14 daysAvailableClosedNot available
After those 14 daysAvailableClosedAvailable

A dispute never times out into a payout. If neither side agrees and no award is signed, funds stay in escrow. See Fees and settlement for what each route costs and Security model for who signs an award.

Next