Roll format

The exact bytes that get hashed, so anyone can rebuild a Roll and get the same hash.

Encoding

• UTF-8 text with no byte order mark.
• Every line ends with a single line feed (\n). There are no carriage returns.
• The file ends with a line feed after the last row.
• A field is wrapped in double quotes only if it contains a comma, a double quote or a line break. A double quote inside a quoted field is written twice.
• Sections are separated by exactly one blank line.
• A section with no rows still prints its name line and its column line.

The reference implementation is toCsv() in site/js/close.js. parseCsv() in the same file reads a Roll back, and refuses any file whose first line is not rentday.roll/2.

Header

Four lines, then a blank line:

rentday.roll/2
roll,<id>
period,<YYYY-MM>
published,<YYYY-MM-DD>

The first line names the format and its version. <id> is the Roll number padded to three digits: 001, 002 and so on. period is the month closed and published is the date the Roll came out. Sample Rolls use the ids S1 to S6 and put placeholder text in the period, published and date fields.

Sections

Each section starts with a line holding # and the section name, followed by a column line. The sections always appear in this order:

Dates sort as text, character by character. Two claims on the same date keep the order the operator entered them in.

The balance rows, in order:

1. usdg_prev
2. flows
3. usdg_open
4. shares_open
5. usdg_close
6. price_open
7. price_close

What each value means is on Reading a Roll.

Numbers

• Every decimal place is printed, trailing zeros included.
• Values are truncated toward zero at the last decimal, never rounded.
• There are no thousands separators. The only field that can be negative is flows, which then starts with a minus sign.
• usdg_per_eth is USDG per one whole ETH.
• Transaction hashes are written as the operator entered them. A transaction field is empty when the month file gave no hash, as in every sample Roll.

A Roll carries ETH amounts as the operator enters them, padded with zeros to 18 decimals. The sample months keep their fees in whole millionths of an ETH, so their amounts end in twelve zeros.

Sample excerpt

The lines below are sample data, produced by running the close engine on the sample fee months. They come from sample month 4, a quiet month. This is not a published Roll. The file opens like this; the #days section has 18 rows in all, and the excerpt trims it to the first three.

rentday.roll/2
roll,S4
period,sample-4
published,rent day 4

#days
date,fee_eth
sample-4-01,0.029010000000000000
sample-4-02,0.022829000000000000
sample-4-06,0.037734000000000000

After the last day, which is sample-4-29,0.036075000000000003, the file runs to its end like this:

#claims
date,eth_claimed,claim_tx
sample-4-07,0.111146000000000000,
sample-4-14,0.195253000000000000,
sample-4-21,0.164427000000000000,
sample-4-28,0.096880000000000000,
sample-4-30,0.036075000000000000,

#conversion
eth_converted,usdg_received,usdg_per_eth,swap_tx
0.603781000000000000,1817.380810,3010.000000,

#settlement
usdg_to_vault,operator_bps,operator_cut,settle_tx
1817.380810,0,0.000000,

#balance
item,value
usdg_prev,1175446.747445
flows,0.000000
usdg_open,1175446.747445
shares_open,1149141.395456140507849994
usdg_close,1177264.128255
price_open,1.022891310062
price_close,1.024472821978

Sample Rolls leave claim_tx, swap_tx and settle_tx empty. A published Roll carries the transaction hashes there.

To print the whole sample file, run this from the project root:

node -e "import('./site/js/close.js').then(async C=>{const S=await import('./site/js/sample-data.js');const {rolls}=C.closeAll(S.SAMPLE_OPENING_USDG,S.SAMPLE_MONTHS,{sample:true});console.log(C.toCsv(rolls[3]))})"

console.log adds a line feed after the file's own trailing newline. To hash the output, write the string to a file with fs.writeFileSync instead of redirecting the printout. The full sample month 4 file is 1,278 bytes, and its SHA-256 is 2af1754aa7a986e79606f4173a0737dda803e9a1785de909812ab9f24822e2f5.