Callbook docs
v1.0.0
Get help
● Use

How receipts work
seal, co-sign, check, record.

The rules, in plain words and in exact form. They come from contract/CONTRACT.md and app/lib/src/core. A checked receipt is a statement about what happened to the prices, never advice.

SHA-256 chainEd255191 / 7 / 30 daysWilson 95 %

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, shown in the app as UP or DOWN), entry, target, stop (decimal strings, empty when not given). These are the contract's field names. In the app entry is the price then ("Price when said"), target is the level the claim should reach ("Reaches") and stop is the level at which it is wrong ("Wrong at"), 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.

Honest limit

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 receiptMeaning
Co-signed by the serverThe signature checks out.
Co-signed ... after sealingThe 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 checkedA record exists but no public key is available to check it.
Co-signature does not check outThe record does not match the receipt or the key.
Sealed on this device onlyNo 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.

03How claims are checked

These rules are fixed and the same for every receipt; the app prints them under Track record, How calls are scored. Nothing in them is a prediction or advice.

  1. Closed days only. Only daily candles (UTC) that finished after the day of the call are used. A call logged at 14:00 is scored from the next day on.
  2. First level touched. A claim that something goes up comes true when the day's high is at or above the level it should reach, and does not happen when the low is at or below the wrong-at level. A claim that it goes down is the mirror image. The first level touched decides.
  3. Same day, both levels. If one day touched both, the claim is counted as not happened. That is the cautious reading, and the receipt says so.
  4. Neither by the horizon. The claim is marked Not reached.
  5. Stamps. At 1, 7 and 30 days the close of that day is compared with the price then and marked as said, against or level. A stamp appears once that day has closed.
  6. A source's record. Counts resolved calls only. The share is claims that came true, with a 95 % Wilson range. Below the minimum number of resolved claims (default 10, set in the console) no share is shown.
  7. Nothing is removed. Receipts cannot be edited or deleted. Hiding one only removes it from the list; it still counts in every record.
  8. Settled by hand. Calls on things without a price feed are marked Came true, Did not happen or Not reached by you, and are labelled that way.

The deadline day is the UTC day of the call plus the horizon in days. If the candle of the deadline has not closed the claim stays Pending, and if price data is missing it stays Pending with a data-gap note; nothing is guessed. 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.

In the stored data and in the CSV export the outcomes keep their internal names (target, stop, expired, open); the app shows them as CAME TRUE, DID NOT HAPPEN, NOT REACHED and PENDING.

04Per-source record

A source is the text the user typed in Where it came from, compared without regard to case and surrounding spaces. The rows are Came true, Did not happen, Not reached and Pending. A source with 10 or more resolved claims shows "N of M resolved claims came true (X %)"; with fewer it shows "Too few resolved claims: N of 10 needed before a share is shown". Wording in your store listing should keep to what is counted: claims that came true out of resolved claims. The record says nothing about future claims.

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).