commit c54c56ab41a6492d152135876179fcce8505ad80
parent 4ca60c282d2f913eb1eabae2d5fc1f0fdbda7f88
Author: lash <dev@holbrook.no>
Date: Sat, 14 Feb 2026 12:31:34 +0000
Draft new unit index store protocol
Diffstat:
7 files changed, 99 insertions(+), 20 deletions(-)
diff --git a/dummy/doc/entry.texi b/dummy/doc/entry.texi
@@ -0,0 +1,19 @@
+@anchor{entry}
+@chapter Ledger entry
+
+The ledger entry represents a double-entry accounting item placed in an immutable and signed chain.
+
+
+@section Accounting items
+
+An entry consists of @emph{debit} and @emph{credit} items, at least one of each.
+
+The sum of all debit and credit items must be zero. A @emph{debit} item used here to define a @emph{spend}, where the @emph{credit} item is used to define @emph{receipt}.
+
+Please @xref{accounts,Accounts} for details on how to interpret the values for each item.
+
+
+@anchor{entry_timing}
+@section Timing in ledger entries
+
+
diff --git a/dummy/doc/internals.texi b/dummy/doc/internals.texi
@@ -9,6 +9,8 @@ Signatures are calculated and embedded on three elements individually, while at
The following describes any transformation applied to the XML. Also, any @code{sig} elements are removed before .
+Where expendient, @url{https://dwarfstd.org/doc/Dwarf3.pdf,LEB128s} encoding is used for variable-length integer encoding.
+
@anchor{serialize_attachment}
@subsection Attachment
@@ -114,7 +116,7 @@ The list elements for both have identical structure, and are generated as follow
@anchor{serialize_asset}
-@section Entry attachment assets
+@subsection Entry attachment assets
The lookup key for the entry cache item is:
@@ -146,24 +148,65 @@ A collection of units of account, defining their value precision level aswell as
Serialization uses the rencode format, and all individual elements are elements in a list.
-The list elements are generated as follows:
+The unit index cache items have a number of lookup key variations, all of which have the prefix @code{0x08}.
+
+The values format for each variation differs.
+
+@anchor{baseunit}
+@subsubsection Base unit
+
+Defines the base unit used for the ledger.
+
+Lookup key:
@enumerate
-@item The base unit symbol, UTF-8 byte value.
-@item List of unit definitions, see below
+@item @code{0x08}
+@item The @emph{legder index} @strong{reference number}.
@end enumerate
+The value is the @emph{UTF-8 encoded} @strong{base symbol name}.
-@subsubsection Serialization of unit definitions
-The list elements are generated as follows:
+@anchor{ledgerunit}
+@subsubsection Ledger unit
+
+Defines the default metadata for a unit.
+
+Lookup key:
@enumerate
-@item The unit symbol to define.
-@item The unit precision level, as an 8-bit unsigned integer value.
-@item Exchange rate, as a 64 bit unsigned integer value.
+@item @code{0x08}
+@item The @emph{legder index} @strong{reference number}.
+@item The unit index symbol, as stored in the @emph{baseunit,Base Unit} item.
@end enumerate
+Value:
+
+@enumerate
+@item Type of unit. @xref{realvirt,Real vs virtual}.
+@item Precision, as a single-byte numeric value.
+@item Exchange rate vs base unit, @emph{LEB128s encoded integer}. @xref{data_unit_index,Unit Index data structure}.
+@end enumerate
+
+The exchange rate defined in this item is the default exchange rate, and/or the exchange rate at the moment of ledger creation (before the first entry).
+
+
+@subsubsection Ledger unit momentary exchange rate
+
+Defines the exchange rate for a unit at a specific moment in time.
+
+Lookup key:
+
+@enumerate
+@item @code{0x08}
+@item The @emph{legder index} @strong{reference number}.
+@item The unit index symbol, as stored in the @emph{baseunit,Base Unit} item.
+@item The @strong{datetime} of the exchange rate snapshot as a @emph{32-bit big-endian numeric value}.
+@end enumerate
+
+The value is the @emph{LEB128s encoded integer} of the exchange rate. @xref{data_unit_index,Unit Index data structure}, as used in @ref{ledgerunit,Ledger unit} above.
+
+
@subsection Access Control List
diff --git a/dummy/doc/intro.texi b/dummy/doc/intro.texi
@@ -50,12 +50,14 @@ Signatures and encryption use the @url{https://nacl.cr.yp.to/,NaCl} library. For
The signature algorithm is the @strong{ed25519} implementation of the @url{eddsa,https://www.rfc-editor.org/rfc/rfc8032} recommendation.
-@section State of this document
+@section Development state.
This is the documentation for version @code{0.1.0}.
-For each release (i.e. in git, a semver tag), the document @emph{should} cover the current state of the implementation.
+The software is currently considered to be in @emph{alpha state}.
+
+Breaking changes may be introduced on every minor version number increase.
-It @emph{may} cover features not yet implemented.
+For each release (i.e. in git, a semver tag), the document @emph{should} cover the current state of the implementation.
-The @emph{inline code documentation} should be kept up to date before each merge to the @emph{master} branch. It should be consulted when in doubt about state of features.
+This documentation @emph{may} cover features not yet implemented. The @emph{inline code documentation} should be kept up to date before each merge to the @emph{master} branch. It should be consulted when in doubt about state of features.
diff --git a/dummy/doc/store.texi b/dummy/doc/store.texi
@@ -11,13 +11,17 @@ The prefixes are:
@table @code
@item 0x00
-Key information, currently in this early development only contains private key, unencrypted.
+@emph{Cryptographic key information}, currently in this early development only contains private key, unencrypted.
@item 0x01
-Reserved for Ledger metadata, currently unimplemented, as ledger state also can be loaded from XML.
-@item 0x02
-Reserved for Ledger lock, currently inimplemented, to be used in aiding atomic inserts if needed.
+Reserved for @emph{ledger metadata}, currently unimplemented, as ledger state also can be loaded from XML.
+@item 0x02
+Reserved for @emph{ledger index}, currently inimplemented, to be used to refer to a ledger with a numeric value in the index, to save space by avoiding using topic as reference every time.
+@item 0x03
+Reserved for @emph{ledger lock}, currently inimplemented, to be used in aiding atomic inserts if needed.
@item 0x04
-Entry data, everything needed to reconstruct a full entry element.
+@emph{Entry data}, everything needed to reconstruct a full entry element.
+@item 0x08
+Reserved for per-ledger @emph{unit index}.
@item 0x10
Asset (entry attachment) data, everything needed to reconstruct a full entry element @emph{except} the actual asset data (@ref{method, Lookup methods}).
@end table
diff --git a/dummy/doc/unit.texi b/dummy/doc/unit.texi
@@ -8,11 +8,12 @@ For each known unit, it defines the level of decimal precision a currency denomi
Additionally, it defines conversion rates between different units and the base unit of account. These conversion rates may be defined statically, fixed to dates, or fixed to dates and time. This approach accommodates both pegged and floating unit conversions.
-@section Structure
+@section Semantic structure
A unit index defines a base unit of account, to which all conversion rates relates to. The base unit of account will have an effective conversion rate of 1.0.
+@anchor{realvirt}
@subsection Real vs virtual
The XML representation of the unit index defines two different elements; @code{real} and @code{virt}.
diff --git a/dummy/doc/xml.texi b/dummy/doc/xml.texi
@@ -62,3 +62,11 @@ The entry representation also defines data necessary for the immutability chain
@item The datetime when the transaction was registered in the ledger.
@item A free-text description for the entry.
@end itemize
+
+
+@anchor{data_unit_index}
+@section Unit Index
+
+The unit index exchange rate is represented as an integer with 9 decimal precision.
+
+For example, a value of @code{1.0} is represented as the integer @code{1000000000}.
diff --git a/dummy/usawa/store.py b/dummy/usawa/store.py
@@ -11,8 +11,10 @@ from .asset import Asset
PFX_KEY = b'\x00'
PFX_LEDGER = b'\x01'
-PFX_LEDGER_LOCK = b'\x02'
+PFX_LEDGER_INDEX = b'\x02'
+PFX_LEDGER_LOCK = b'\x03'
PFX_ENTRY = b'\x04'
+PFX_UNIT_INDEX = b'\x08'
PFX_ASSET = b'\x10'
logg = logging.getLogger('usawa.store')
