overnight
TS/Cwhat the batch is
The overnight batch is a scheduled process that runs once per calendar day during a fixed window. It reads every open position whose batch window matches the current batch number, checks that its collateral still satisfies the rate sheet, and calls the settle instrument on each one in turn.1 Positions that do not satisfy the rate sheet are not settled. They are marked for review and appear on the incidents page. The batch writes a single memo transaction at the start and one at the end, each carrying the batch number, so that the full run can be reconstructed from the chain alone.
how to read a batch report
| FIELD | MEANING |
|---|---|
| batch | The batch number, monotonically increasing, stored in the config account. |
| opened | Timestamp of the opening memo transaction. |
| closed | Timestamp of the closing memo transaction. Absent if the batch has not closed. |
| eligible | Number of positions whose window matched. |
| settled | Number of settle instructions that reached finality. |
| held | Number of positions held for review. |
| signatures | Every transaction signature in the run, in order. |
the window
The batch window is a number of seconds stored in config and a start time that is fixed by convention, not by the program. The program only knows the window length. The desk runs the batch at the same local time each day and writes the opening memo first so that the start is on record. A batch that opens and does not close inside the window is an incident and is listed as such until it closes.
what the batch will not do
It will not settle a position whose collateral is below ratio. It will not settle a position whose window has not arrived. It will not settle a position twice. It will not move collateral. It will not change rates. It will not skip a position because the desk would prefer to. Every one of these is enforced by the program and would fail with a named error if attempted.
batch reports
No batch has been recorded on chain yet. The first batch report will appear here after the first window closes.
order of operations in the batch
- 1.Read config. Confirm the current batch number and the window length.
- 2.Write the opening batch memo with phase zero and the eligible count.
- 3.Fetch every position account owned by the program.
- 4.Discard positions whose batch window does not match the current batch number.
- 5.For each remaining position, in address order, read its collateral account and compare amount to the rate sheet's ratio.
- 6.Call settle for each that satisfies the ratio. Wait for finality before the next.
- 7.Call hold for each that does not, with the reason code.
- 8.Write the closing batch memo with phase one and the settled and held counts. The program advances the batch number in the same instruction.
- 9.Write a weekly memo if it is the last working day of the week.
why address order
Positions are settled in the order of their addresses, not the order they were opened and not the order of their amounts. Address order is arbitrary and fixed, which is the point. Nobody can arrange to be settled first, and the desk cannot be asked to prefer anyone, because the order is decided by a hash.
waiting for finality between settlements
Each settle is submitted and the batch waits for the cluster to report it finalized before submitting the next.2 This is slow. It is also the only way to be certain that a settlement which failed did not quietly succeed after the batch moved on. A batch is slow by design. Its slowness is the cost of being able to say, of every entry, that it is settled and not probably settled.
what happens if the batch stops halfway
The batch can stop for the same reasons any process stops. If it does, the opening memo exists and the closing memo does not, and the batch number has not advanced. When the batch is rerun, it reads config, finds the same batch number, fetches positions, and finds that some are already closed. It settles the rest. The rerun writes a second opening memo, which is why a batch report may show two opening memos and one closing memo. That is not an error. It is the record of a stop.
the batch does not know what day it is
The program stores a window length in seconds and nothing else about time. It does not store a start time, a day of week, or a timezone. The convention that the batch runs at a fixed local time each day belongs to this desk and is written in the operating policy, not in the program. If the desk ran the batch at a different hour, the program would not object. The memo would.
- 1. The rate sheet is the set of rate parameters held in the config account and printed, unaltered, on the rate sheet page.
- 2. Finality is the point at which the cluster will not reorganise a transaction away, and this desk reports nothing before it.