Double-entry plaintext accounting

Both the contract and auth now implement double-entry plain-text-accounting (PTA) to track the movement of value each knows about.

Accounting is tracking the flow of valuable commodities, such as money. It clarifies activity and obligations. Double-entry bookkeeping is a process for keeping accounting records reliably. For every movement of value (a transaction), both the source and destination are recorded. Simple arithmetic invariants help prevent errors.

Value at any point in time is tracked in various accounts, classified as assets (owned), or liability (owed). Two more classifications track changes during some period: income (inflows) and expenses (outflows).

Assets: where money sits
Liabilities: money you owe
Income: where money comes from
Expenses: where money goes

Transactions consist of debits (increases to asset or expense accounts, or decreases to liability) or credits (decreases to asset or expense accounts, or increases to liability). We simplify debits and credits by using signed numbers - positive for inflows to an account, negative for outflows from an account.

Ledger format

The ledger format is used, so any PTA application (CLI, TUI, GUI) can be used to verify, query, browse, slice and dice the ledger.

Attribute	Comment
date	The date of the transaction (`YYYY-MM-DD`)
code	Tracking code of the transaction (`key:value`)
description	Description of the transaction
unixtime	The precise Unix epoch time of the transaction (`@unixtime`)
account	The account to debit or credit
amount	The amount to debit or credit the account
currency	The currency of the amount to debit or credit

date (code) description                                ; @unixtime
    account1                                       amount currency
    account2:subaccount                           -amount currency

Contract ledger example

The example below shows a simple scenario in the context of a service contract, based on the following parameters: $1.00 servicekey, 5% settlement fee, and relays collecting an equal amount of sharetokens.

$ cat transactions.ledger

2020-01-01 (sk:p2bgAvc0...) servicekey activation   ; @1591959182
    expenses:beneficiary                                  0.05 usd
    liabilities:beneficiary                              -0.05 usd
    assets:operator                                       0.05 usd
    assets:settlement                                     0.95 usd
    income:stripe                                        -1.00 usd

2020-01-01 (sk:p2bgAvc0...) settlement window close  ; @1591959217
    expenses:relays                                       0.90 usd
    liabilities:relays:yVlMV0daGddzcgCZgoOd5OOXO...      -0.45 usd
    liabilities:relays:kcUOO4wtmXjKpfCn3nvrsO1qd...      -0.45 usd

2020-01-01 (dest:acct_1032D82e...) relay withdrawal  ; @1591960248
    liabilities:relays:yVlMV0daGddzcgCZgoOd5OOXO...       0.10 usd
    assets:settlement                                    -0.10 usd

$ hledger -f transactions.ledger balances

Balance Sheet

Assets:
            0.90 usd  assets
            0.05 usd    operator:dummy
            0.85 usd    settlement
--------------------
            0.90 usd

Liabilities:
           -0.85 usd  liabilities
           -0.80 usd    relays
           -0.45 usd      kcUOO4wtmXjKpfCn3nvrsO1qd...
           -0.35 usd      yVlMV0daGddzcgCZgoOd5OOXO...
           -0.05 usd    beneficiary
--------------------
           -0.85 usd

Total:
--------------------
            0.05 usd

$ hledger -f transactions.ledger register relays:yV

2020/01/01 settlement window..  ..goOd5OOXO...  -0.45 usd  -0.45 usd
2020/01/01 relay withdrawal     ..goOd5OOXO...   0.10 usd  -0.35 usd

Servicekey activation

Once a user has obtained a proof of funding, it is sent along with the publickey of the user generated servicekey to the contract for activation, resulting in an active servicekey.

The contract generates an entry in the ledger made up of the following transactions: (1) debiting the income:stripe account and crediting both the assets:settlement and assets:operator accounts; and (2) tracking the beneficiary expense and liability.

Settlement window close

When the servicekey expires, relays submit the sharetokens they have accumulated to the service contract within the settlement submission window. When the submission window closes and sharetoken validation is complete, the contract may now perform the proportional share-based compensation calculation.

The contract generates an entry in the ledger made up of one transaction, noting the liabilities it now has to the relays, as well as the total expenses:relays for this transaction.

Relay withdrawal

The relays, having accumulated a balance, may issue a withdrawal request. Once the withdrawal request has been verified and processed, the contract writes a transaction to the ledger reducing the liability it has to the relay and reducing the source asset from which the withdrawal was made.