Concepts
Lulls
What a lull is, how the calendar comes from Pyth's market-hours schedule, and the phases each lull goes through.
Sessions and lulls#
A session is the regular trading day of the underlying stock. For AAPL it runs from 09:30 to 16:00 ET, Monday to Friday, except on market holidays and early closes. A lull is the interval from one session's close to the next session's open. Every order placed in a lull crosses at that one open.
Loading the schedule…
Kinds of lull#
| Kind | Starts | Ends |
|---|---|---|
| Overnight | a weekday close | the next weekday's open |
| Weekend | Friday's close | Monday's open |
| Holiday | the close before one or more market holidays | the first open after them |
A lull that spans a market holiday is a holiday lull, even when it also spans a weekend.
On an early close, the session ends before 16:00 ET and the lull starts at that earlier close. The day after Thanksgiving, for example, closes at 13:00 ET. The lull clock marks holidays and early closes.
Where the calendar comes from#
Pyth publishes a market-hours schedule with each equity feed. Lull builds its calendar from the schedule of Equity.US.AAPL/USD, the same feed that supplies Popen. The schedule is one string: a time zone, the weekly hours from Monday to Sunday, and dated overrides. In shortened form it looks like this:
America/New_York;0930-1600,0930-1600,0930-1600,0930-1600,0930-1600,C,C;1126/C,1127/0930-1300
C means closed. An override such as 1126/C closes a holiday, and 1127/0930-1300 sets an early close.
All times are wall-clock times in New York, so the calendar follows daylight saving time. The open is 09:30 ET all year. In UTC it is 13:30 in summer and 14:30 in winter.
Each lull is published on chain with four times: close, reveal start, reveal end and open. The program cannot read Pyth's schedule itself. It enforces close < reveal start < reveal end ≤ open, and it accepts a new lull only before that lull's reveal window starts.
Phases#
Loading the current lull…
| Phase | When | What you can do |
|---|---|---|
| Scheduled | on the calendar, not yet on chain | see the countdown |
| Commit | from publication until the reveal window | seal orders |
| Reveal | open − 30 min to open − 1 min by default | reveal sealed orders |
| Sealed | reveal end to open + delay (30 s by default) | wait; unrevealed tickets are forfeited |
| Pricing | open + delay until Popen is captured | wait |
| Crossing | Popen is known and the book is crossing | wait |
| Settled | the cross is final | see fills, claim, withdraw |
| Cancelled | no valid price in time, or cancelled by the market authority before pricing | claim refunds |
Deposits and withdrawals of free balance work in every phase.
A lull goes on chain shortly before the close that starts it. From then until its reveal window opens, the "Order ticket" accepts sealed orders for it. While the market is open, the lull clock counts down to the next lull.
The program checks every window against Solana's clock, which can differ slightly from your device's clock. Leave a margin at the edges of each window.
See Popen for pricing and cancellation, and Sealed orders for what happens in the commit and reveal phases.