Reading a Roll

One file per month, with every apartment, every cost and the resulting price.

The file

The Roll is a CSV file the operator publishes on the 1st of each month, covering the month before. Its header gives the Roll number (001, 002 and so on), the period in the form YYYY-MM, and the publication date. Six sections follow, always in the same order. The Roll page shows the same figures, and Roll format documents the exact bytes.

Apartments

One row for every apartment in the portfolio, every month, including empty ones. An apartment never drops out of the file because it had a bad month, so you can follow a single unit from one Roll to the next.

The columns are building, unit, beds, lease_rent and status. The status takes one of three values:

paid: the month's rent arrived by the close.
late: the apartment is let, and the month's rent had not arrived by the close.
vacant: no tenant, so no rent was due.

lease_rent is the monthly rent in the lease, whatever was received. A late apartment still shows its full lease rent and adds nothing to rent collected. A vacant apartment shows the rent the portfolio lists for it.

Recovered

Late rent that arrived this month for an earlier period. The columns are building, unit, for_period (the month the rent was owed for) and amount.

Recovered rent is kept apart from the apartments section so that it cannot flatter the month's collection rate: the share of this month's rent that arrived this month counts only this month's paid rows. Recovered rent still counts toward net rent and toward the property manager's 7%. In the sample data, Cleveland 202 (A-202) was late in month 1 and appears here in month 2 with 1,125.000000 USDG for sample-1.

Costs

The seven cost lines, always present, always in the same order, each to six decimals: repairs, capital_works, property_tax, insurance, property_manager, vault_management and vault_performance. A line with nothing to charge prints 0.000000. Rates and bases are on the Fees page.

Token fees

One row for the $RENT token fee settled this month: eth_claimed (the ETH the operator claimed), usdg_received (the USDG the swap produced), claim_tx and swap_tx (the hashes of those two transactions). You can open both transactions on the explorer and compare the amounts. In a month with no token fee, the row reads 0,0.000000,,.

Token fees bypass the cost lines and the shortfall. The USDG goes into the vault whole.

Appraisals

Any change to a building's appraised value this month. The columns are building, change (in USDG, negative for a fall) and reason. Appraisals sit outside the reconciliation. A change alters the base for property tax and insurance from the following month and moves no USDG, so it has no effect on the price. Sample month 6 shows Louisville (building B) appraised 45,000 USDG higher when its insurance renewed.

Balance

Fifteen named values that carry the month from rent to price. Amounts are in USDG with six decimals unless the table says otherwise.

Item	Meaning
`rent_collected`	Lease rent of every apartment with status `paid`.
`rent_recovered`	Total of the recovered section.
`costs`	Total of the seven cost lines.
`net_rent`	Rent collected plus rent recovered, minus costs. Negative when costs exceed rent.
`shortfall_open`	Shortfall carried in from the previous Roll.
`settled`	Net rent transferred into the vault for this month, after any shortfall was repaid.
`shortfall_close`	Shortfall carried out to the next Roll.
`token_fees`	USDG from the $RENT token fee, equal to `usdg_received`.
`flows`	USDG deposited minus USDG cashed out during the month. Negative when cash-outs were larger.
`usdg_prev`	USDG in the vault at the previous close.
`usdg_open`	USDG in the vault before this month's settlement.
`usdg_close`	USDG in the vault after this month's settlement.
`shares_open`	vRENT outstanding at the close, with 18 decimals.
`price_open`	Price before settlement, with 12 decimals.
`price_close`	Price after settlement, with 12 decimals.

Checks you can do by hand

Six identities hold in every Roll. You can check them with a calculator and the file. The same six checks are coded in checkIdentities in site/js/close.js.

costs = the sum of the seven cost lines.
rent_collected = the sum of lease_rent over apartments with status paid.
net_rent = rent_collected + rent_recovered - costs.
settled = max(0, net_rent - shortfall_open).
usdg_close = usdg_open + settled + token_fees.
price_close = usdg_close / shares_open, truncated to 12 decimals.

A few more follow from how the file is built. rent_recovered is the total of the recovered section. usdg_open = usdg_prev + flows, and price_open = usdg_open / shares_open. Between consecutive Rolls, shortfall_open equals the previous Roll's shortfall_close, and usdg_prev equals the previous Roll's usdg_close.

Worked through on sample month 4 (sample data): 39,640.000000 + 0.000000 - 54,148.380450 gives -14,508.380450 of net rent. With no shortfall open, settled is max(0, -14,508.380450), which is 0, and the whole gap becomes shortfall_close. usdg_close is 4,760,262.055797 + 0 + 2,961.350000 = 4,763,223.405797, and dividing by 4,679,023.703779488775338943 vRENT gives 1.017995143292.

Shortfall

shortfall_open is the gap carried in from earlier months: costs that rent has not yet covered. shortfall_close is the gap carried out to the next Roll. Each month, net rent pays down the open shortfall before anything is settled:

If net_rent is at least shortfall_open, the shortfall is cleared, settled is the difference and shortfall_close is 0.
If net_rent is smaller, or negative, nothing is settled and shortfall_close is shortfall_open - net_rent.

In both cases settled - shortfall_close equals net_rent - shortfall_open, and at most one of settled and shortfall_close is above zero. Sample month 5 shows the repayment: shortfall_open of 14,508.380450, net rent of 27,478.790373, and 12,970.409923 settled.