Crate librotenado

Expand description

Reference library of librotenado, the open protocol for accounting data.

Version 0.1 covers the base every other part builds on: amounts as exact counts of a currency’s smallest unit, calendar dates, bookings that must balance, and events – immutable, ordered by a hybrid logical clock, chained per device and identified by the hash of their canonical encoding – that a set of books is made of. Two sets of events merge by union; what cannot be merged silently is reported, never guessed. Around them: the harmonised chart of accounts with translations of national charts, documents with their originals, and the organisations and persons the books belong to.

Structs§

Account: An account: of the harmonised chart, or opened in a set of books to refine one (spec parts 0002, 0004).
AccountId: The identity of an account: a UUID (RFC 9562) in its one form, lower case 8-4-4-4-12 hexadecimal digits, e.g. 0192f1e4-7a3c-7b1e-9c2d-5e8f0a1b2c3d. It carries no meaning – what an account is follows from its kind, parent and attributes, its name from translation data – so it never has to change. Version 7 is recommended.
Balances: Balances: per owner, account and currency, the sum of the base units of the postings. Positive is a debit balance, negative a credit balance.
Booking: A booking: a business transaction on a date, as postings that balance for every owner in every currency. One booking may concern several owners – an invoice split between a business and its owner’s private books.
Chart: A chart of accounts: a hierarchy of accounts with attributes, under a name and version.
ChartTranslation: How a national chart of accounts translates into the harmonised one: each national account onto exactly one harmonised account.
Clock: The hybrid logical clock of one device.
ContentHash: The SHA-256 hash of a file’s bytes: sha256: and 64 lower-case hexadecimal digits. The bytes themselves are stored outside the events, in any store addressed by this hash.
Country: A country by its ISO 3166-1 alpha-2 code, e.g. DE, FR.
Currency: A currency by its code: three upper-case letters for an ISO 4217 currency (EUR, CHF), x- and 1–62 characters of a-z, 0-9 and - for a currency defined outside ISO 4217 (x-btc, x-galleon).
CurrencyDefinition: How a currency divides into its base unit – reference data, published in versions with the protocol.
CurrencyTable: A published table of currency definitions – reference data, versioned with the protocol (spec part 0001).
Date: A day of the Gregorian calendar, written YYYY-MM-DD (years 0001 to 9999).
Decimal: An exact decimal number units · 10^−scale – a price per unit, a quantity, a rate. Money is crate::Money.
DeviceId: The name of a device that writes events, unique within a set of books: 1–64 characters of a-z, 0-9, -.
Document: A document: what a booking is based on, as a record of its own. There is no document without its original.
DocumentId: The identity of a document: a UUID in its one form (spec part 0001), like an account’s. It carries no meaning.
Event: One event: who wrote it when, its place in the device’s chain, and what happened. An event is always a root object: {"type": "event", "kind": …, "time": …, "seq": …, "prev": …, …}.
EventHash: The SHA-256 hash of an event’s canonical encoding – its identity. Written as sha256: and 64 lower-case hexadecimal digits, like every hash in the protocol.
EventSet: A set of events – the books as they are known on one device. Merging is set union, in any order, any number of times, with the same result.
Hlc: A timestamp of a hybrid logical clock.
Money: An amount in a currency, counted in the currency’s smallest unit: {"currency": "EUR", "base_units": "-1240"} is −12.40 euros.
Organisation: An organisation: a company, an association, a foundation, a partnership.
Original: The file a document came as – an artefact: the document’s data never depends on reading it.
PartyId: The identity of an organisation or a person: a UUID in its one form (spec part 0001). It carries no meaning.
Person: A natural person.
Posting: One line of a booking: an amount on an account. Positive is debit, negative is credit.
Registration: An entry in a public register, e.g. a commercial register.
Role: A person’s role in an organisation.
Shares: A number of shares of one nominal amount: {"count": 512, "nominal": 2 EUR} – a share capital of 1,024 euros in 512 shares of 2 euros. Shares are counted in whole numbers; fractions of the capital follow from the counts.
TaxId: A number under which a tax authority knows a party.

Enums§

AccountKind: What an account is, in the sense of double-entry bookkeeping.
AccountProblem: Something about the accounts of a set of books that needs review (spec part 0002): never resolved silently.
BalanceError: Why balances cannot be computed.
BookingError: Why a booking is not valid.
CanonicalError: Why a value cannot be encoded canonically.
ChainProblem: Something in a set of events that does not fit a clean chain per device.
ChartError: Why a chart is not valid.
DefinitionError: Why a currency definition is not valid.
DocumentKind: What kind of document it is.
DocumentProblem: Something about the documents of a set of books that needs review: never resolved silently.
ObjectError: Why JSON is not the expected root object.
ParseError: A value in the protocol that could not be read.
PartyProblem: Something about the parties of a set of books that needs review: never resolved silently.
Payload: What happened – the event’s kind and the members that come with it, written at the level of the event.
RoleKind: What a person is to an organisation.
TranslationError: Why a translation does not fit its chart.

Constants§

MAX_SAFE_INTEGER: The largest integer every JSON implementation represents exactly (2^53 − 1).

Traits§

Object: An object of the protocol with its type, e.g. event or account.

Functions§

canonicalize: The canonical bytes of JSON text as received: every member is kept, also those the reader does not understand. Rejects text that is not JSON, objects with two members of the same name, and numbers that are not safe integers.
from_root: Reads a root object of type T from JSON in any formatting.
to_canonical_vec: The canonical bytes of a value: UTF-8, no whitespace, object members sorted by their names’ UTF-16 code units, strings escaped only where JSON requires it.
to_root: The canonical encoding of value as a root object: its members and its type.