commit 6d49f6267dab5e223b53e5d4cbe89e9e150552d2
parent 03ef1626d39f8bced8eb79ee82a2b9041b0d8c52
Author: lash <dev@holbrook.no>
Date: Sat, 17 Jan 2026 14:10:17 +0000
Elaborate xml docs
Diffstat:
13 files changed, 60 insertions(+), 4 deletions(-)
diff --git a/dummy/doc/accounts.texi b/dummy/doc/accounts.texi
@@ -0,0 +1,4 @@
+@chapter Accounts
+
+@anchor{account_type}
+@anchor{account_path}
diff --git a/dummy/doc/appendix.texi b/dummy/doc/appendix.texi
@@ -1,4 +1,4 @@
-@anchor xml_schema
+@anchor{xml_schema}
@appendix XML schema
@example
diff --git a/dummy/doc/assets.texi b/dummy/doc/assets.texi
@@ -0,0 +1 @@
+@anchor{assets}
diff --git a/dummy/doc/elements.texi b/dummy/doc/elements.texi
diff --git a/dummy/doc/identity.texi b/dummy/doc/identity.texi
@@ -0,0 +1 @@
+@anchor{identity}
diff --git a/dummy/doc/index.texi b/dummy/doc/index.texi
@@ -20,5 +20,12 @@ Documentation released 2026 under CC-BY-SA
@include intro.texi
@include xml.texi
+@include ledger.texi
+@include accounts.texi
+@include unit.texi
+@include identity.texi
+@include time.texi
+@include resolver.texi
+@include assets.texi
@include internals.texi
@include appendix.texi
diff --git a/dummy/doc/ledger.texi b/dummy/doc/ledger.texi
@@ -0,0 +1 @@
+@anchor{incoming}
diff --git a/dummy/doc/resolver.texi b/dummy/doc/resolver.texi
@@ -0,0 +1 @@
+@anchor{resolver}
diff --git a/dummy/doc/time.texi b/dummy/doc/time.texi
@@ -0,0 +1 @@
+@anchor{entry_timing}
diff --git a/dummy/doc/unit.texi b/dummy/doc/unit.texi
@@ -0,0 +1 @@
+@anchor{unit_index}
diff --git a/dummy/doc/xml.texi b/dummy/doc/xml.texi
@@ -1,4 +1,4 @@
-@chapter Data format
+@chapter Data representation
The canonical ledger data format is XML.
@@ -23,3 +23,43 @@ It includes:
@item Ledger state, under the element @code{incoming}, defining the digest of the position of the entry chain the ledger document starts at. @ref{incoming, Ledger State}.
@item Signatures that may authenticate the ledger state.
@end itemize
+
+
+@subsection Truncated header
+
+An important feature of the header is to allow only a portion of the ledger's entries to appear in the document.
+
+This is accomplished by populating the @code{digest} and @code{serial} values in the ledger state with those of the parent of the first entry listed. @ref{xml_example_trunc, Truncated XML example} for more details.
+
+In order to list all entries in a ledger, the @code{digest} value should be the zero-digest (64 zero-value bytes), and with a @code{serial} of @code{0}.
+
+
+@section Entry
+
+Every entry is comprised of two or more parts, where there is at least one debit and one credit part. All the parts should add up to 0.
+
+The parts represents instantaneous changes in the ledger within a single entry. E.g. at the same time an expense account and a sales tax credit.
+
+Each part may have different units of account. In this case, conversion rates for each part must be provided in order to verify the zero sum of the parts.
+
+The debit and credit entry part elements have identical stucture, and include:
+
+@itemize
+@item The unit of account.
+@item The account specifier, which is a combination of @ref{account_type, account type}, and @ref{account_path, account path}.
+@item The amount in the unit of account, as decimal integer to the level of precision defined for the unit.
+@end itemize
+
+The entry representation also defines data necessary for the immutability chain to be verified:
+
+@itemize
+@item The digest of the parent.
+@item The serial number of this entry in the ledger.
+@item The external reference of the entry, e.g. a blockchain transaction specificer or tax invoice uuid.
+@item The date or datetime when the transaction took place. @ref{entry_timing, Entry timing}.
+@item The datetime when the transaction was registered in the ledger.
+@item A free-text description for the entry.
+@end itemize
+
+
+@anchor{xml_example_trunc}
diff --git a/dummy/usawa/entry.py b/dummy/usawa/entry.py
@@ -296,7 +296,7 @@ class Entry:
o.add_part(src, debit=True)
for v in dst_data:
- dst = EntryPart(v[0].decode('utf-8'), v[1].decode('utf-8'), v[2].decode('utf-8'), v[3], debit=True)
+ dst = EntryPart(v[0].decode('utf-8'), v[1].decode('utf-8'), v[2].decode('utf-8'), v[3])
o.add_part(dst)
return o
diff --git a/dummy/usawa/ledger.py b/dummy/usawa/ledger.py
@@ -305,7 +305,6 @@ class Ledger:
if acl != None:
for v in acl.pubkeys(binary=False):
- #v = wallet.address()
if v not in identities:
identities.append(v)
identity = lxml.etree.SubElement(tree, NSPREFIX + 'identity', nsmap=nsmap())
