How receipts work
seal, co-sign, score, record.
The rules, in plain words and in exact form. They come from contract/CONTRACT.md and app/lib/src/core. A scored receipt is a statement about what happened to the prices, never advice.
01The hash chain
A receipt has: seq (1, 2, 3, no gaps), createdAt (UTC, ISO-8601 with milliseconds and Z), asset (an id from the server list, or custom:<text>), direction (long or short), entry, target, stop (decimal strings, empty when not given), horizonDays (1 to 365), source (max 80), note (max 280) and prevHash.
The payload is these lines joined with a newline, with no trailing newline, in UTF-8:
callbook/1
<seq>
<createdAt>
<asset>
<direction>
<entry>
<target>
<stop>
<horizonDays>
<source>
<note>
<prevHash>
Newlines inside source and note are replaced by a space first. The hash is the lowercase hex SHA-256 of the payload. The previous hash of receipt 1 is 64 zeros. A chain is intact when every seq is the previous one plus one, every prevHash is the previous receipt's hash, and every stored hash equals the recomputed one. Settings, Check the chain does exactly this on the device.
Receipts cannot be edited or deleted in the app. Hide from the list only removes a receipt from the lists, and a hidden receipt still counts in every record.
A hash chain kept only on one device proves that the receipts are consistent with each other, not when they were made. That is what the co-signature adds. Someone with root access to their own phone can still wipe or rebuild the local database, so Callbook is a personal record, not a court record.
02Co-signing
After sealing, the app sends the receipt hash (and nothing else) to POST /v1/cosign. The server answers a record with hash, signedAt, keyId and an Ed25519 signature over the text callbook-cosign/1, the hash and signedAt, one per line. The first request for a hash fixes signedAt: asking again gives back the same record, so the time cannot be moved later. The server keeps only the hash and that time.
The app checks the signature with the public key from /v1/config. The receipt line then reads one of:
| Line on the receipt | Meaning |
|---|---|
| Co-signed by the server | The signature checks out. |
| Co-signed ... after sealing | The signature checks out but arrived late; the app says how late, so a delayed signature is never presented as an immediate one. |
| Co-signature stored, not checked | A record exists but no public key is available to check it. |
| Co-signature does not check out | The record does not match the receipt or the key. |
| Sealed on this device only | No record: no server, no signing key, or the request failed. |
If you replace the signing key, old receipts verify against the old public key only. Keep the old key safe, or accept that older co-signatures will show as not checking out.
03Scoring rules
These are fixed and the same for every receipt; the app prints them under Track record, How calls are scored.
- Closed days only. Only daily candles (UTC) that finished after the day of the call are used. The deadline day is the UTC day of the call plus the horizon in days. A call logged at 14:00 is scored from the next day on.
- First level touched. For a long call the target is reached when the day's high is at or above it and the stop when the low is at or below it. A short call is the mirror image: target when the low is at or below it, stop when the high is at or above it. The first level touched decides.
- Same day, both levels. If one day touched both, the stop is counted. That is the cautious reading, and the receipt marks it "same-candle".
- Neither by the horizon. The call is Expired, and its result is the close of the deadline day against the entry.
- Not closed yet or no data. If the candle of the deadline has not closed the call stays Open. If data is missing it stays Open with a data-gap note. Nothing is guessed.
- Stamps. At 1, 7 and 30 days the close of that day is compared with the entry; short calls have the sign flipped. A stamp appears once that day has closed.
- A source's record. Counts resolved calls (target, stop and expired). The share is the calls that reached the target before the stop, with a 95 % Wilson interval. Below the minimum number of resolved calls (default 10, set in the console) no share is shown.
- Settled by hand. Calls on a custom asset are marked Target, Stop or Expired by the user and are labelled that way.
Only the closed daily candle is used, so a price that touched a level during a day but is not in the candle high or low cannot be seen, and the data of a provider may differ slightly from another provider's. The prices come from the provider you configured; Callbook does not check them.
04Per-source record
A source is the text the user typed in Where it came from, compared without regard to case and surrounding spaces. A source with fewer than the minimum resolved calls shows "Too few resolved calls: N of M needed before a share is shown". Wording in your store listing should keep to what is counted: calls that reached the target before the stop, out of resolved calls. The record says nothing about future calls.
05Custom assets
When the user picks Something else, the asset is stored as custom:<text>, has no price feed, and is settled by hand. You can switch this off in the console (App config: features, custom assets).