Method
From a redemption request to an estimated cash day, step by step.
The website and BillraUnlockCalculator implement the steps below in the same order. They are checked against the same 400 generated cases on every test run.
The steps
1. Local time
local = request time (unix seconds) + UTC offset × 60. Request day = floor(local / 86,400); minute of day = floor((local mod 86,400) / 60).
2. Business day
A day is a business day when its weekday is in the terms' weekday set and it is not in the holiday calendar. Weekday 0 = Monday; 1 Jan 1970 was a Thursday.
3. Accepted day
If the request day is a business day and the minute is before the cut-off, the request counts that day. Otherwise it counts from the next business day.
4. Earliest redemption
Accepted day + notice business days.
5. Redemption window
Any business day: the earliest day. Weekly: the first scheduled weekday whose date, moved to the next business day if needed, is on or after the earliest day. Monthly: the same with day N of each month (the last day when the month is shorter).
6. Arrival
Redemption day + settlement business days (T+n).
7. Verdict
Red when arrival is after the due day, or the request alone is above the gate. Amber when on time with fewer business days of slack than asked, or when the window can be gated. Green otherwise.
8. Latest request
Walk back from the due day over business days; the first day whose arrival is on or before the due day is the last day a request can count. Its cut-off, converted back to UTC, is the deadline.
Bounds: any search for a business day or window gives up after 400 days (the contract reverts, the site says it cannot estimate). A calendar holds at most 400 holidays, strictly increasing. Days run from 1970 to 2199.
Rule flags
Each estimate carries a bit set naming every rule that fired. Same numbers on chain and on the site.
- CUTOFF_MISSED = 1request on a business day at or after the cut-off
- NON_BUSINESS_REQUEST = 2request on a weekend day or holiday
- NOTICE = 4a notice period applies
- WINDOW_WAIT = 8the redemption day is later than the earliest day because of the window
- HOLIDAY_IN_PATH = 16a holiday on a business weekday lies between request and arrival
- GATE = 32the terms allow the issuer to gate a window
- GATE_EXCEEDED = 64the request alone is a larger share of supply than the gate
- LATE = 128arrival after the due day
- THIN_MARGIN = 256on time with fewer business days of slack than asked for
Where each number comes from
- Vault tokens
- SGOV, WEEK, SHY on Robinhood Chain: found by name on the explorer on 18 Nov 2026, then proven on every read: runtime code hash 0x6c1fdd4000… (the issuer's beacon proxy), ERC-1967 beacon slot = 0xe10b6f6b275de231345c20d14ab812db62151b00, and supply above zero. Other tokens carry treasury names on the chain; Billra lists none whose issuer it cannot prove.
- Live reads
- Name, supply, balance multiplier, token and oracle pause flags, the terms link (terms()), the global pause and the functions in the shared implementation, through one JSON-RPC batch and one Multicall3 call, cached 30 s. Block time = (head time − time 20,000 blocks earlier) / 20,000.
- Reference price
- Chainlink SGOV / USD feed on Robinhood Chain (latestRoundData). WEEK and SHY have no feed there. ETH / USD feed 0x78f3556b67e17df817d51ef5a990cdaf09e8d3a9.
- Issuer facts
- Quoted from the issuer's pages (https://docs.robinhood.com/rhj/, linked from each token's terms()), read 18 Nov 2026: who may redeem (after the issuer's identity checks), the redemption fee, who may hold. They do not state a cut-off, notice or settlement time.
- Timing terms
- Sample data until someone publishes a revision to BillraTermsRegistry. The checker shows which terms it used next to every result.
- Holidays
- NYSE full-day holidays, computed from the exchange's rules and checked against its published dates in the unit tests: 2026-01-01, 2026-01-19, 2026-02-16, 2026-04-03, 2026-05-25, 2026-06-19, 2026-07-03, 2026-09-07, 2026-11-26, 2026-12-25 for 2026, then 2027 and 2028.
Not modelled
- Daylight saving: the UTC offset is fixed per revision. A New York cut-off published as UTC-05:00 is one hour earlier in UTC during summer time.
- Early closes, ad-hoc closures and bank holidays that are not exchange holidays.
- The time identity checks, a bank transfer or an exchange withdrawal take after the issuer pays out.
- How full a gated window really is: Billra can only say a gate exists, and whether your request alone exceeds it.
- Selling on a market instead of redeeming: a different path with its own price and liquidity.
Contracts
- BillraTermsRegistry
- not deployed yet · append-only terms revisions, calendars and payment plans; no owner, no fee, no upgrade, no ether.
- BillraUnlockCalculator
- not deployed yet · read-only; estimate(), estimateFor(vault, revision, query), latestRequest().
- Tests
- Unit, fuzz and invariant tests, the 400 + 150 parity cases, and fork tests that publish terms for the real SGOV, WEEK and SHY on a copy of Robinhood Chain.