commit fa5272ccc7c08fc80b90a481e863651ca907d932
parent 90e5ceda512bf28cee2f58a3854c5775eba79cf3
Author: lash <dev@holbrook.no>
Date: Thu, 22 Jan 2026 14:44:04 +0000
Add protocol details for quorum and authentication
Diffstat:
3 files changed, 75 insertions(+), 59 deletions(-)
diff --git a/README b/README
@@ -1,58 +0,0 @@
-Example in folder dummy.
-
-It includes three demo data files:
-
-* empty.xml
-* running.xml
-* present.xsl
-
-running.xml is an example of a fully flattened ledger with signature chains and serial ledger entries. It also includes:
-
-* Descriptions of the account units used
-* How to resolve content hashes (attachments)
-* Reference to more information about identities behind public keys.
-
-present.xsl is a small stylesheet stub just to demonstrate how xsl transformations work.
-
----
-
-To run the python example:
-
-```
-cd dummy
-
-# first time only
-python3 -mvenv .venv
-
-# every time
-. .venv/bin/activate
-
-# first time only
-pip install -r requirements.txt
-
-# demo.py just loads the state of the xml and outputs a bit of the data loaded
-python demo.py
-
-# The makefile has a single stanza that performs xsl transformation on the xml
-make
-```
-
-
-The `create.py` script can add entries starting with the empty.xml:
-
-```
-# create.py adds an entry to the ledger with signature and outputs the updated xml
-python create.py --xml-file empty.xml 124 > one.xml
-python create.py --xml-file two.xml -a foobar -t expense 12 > two.xml
-etc..
-```
-
----
-
-schema.xsd is the schema for the ledger xml object.
-
-Validate the xml with:
-
-```
-xmllint --schema schema.xsd --pretty 1 file.xml
-```
diff --git a/dummy/doc/authentication.texi b/dummy/doc/authentication.texi
@@ -0,0 +1,17 @@
+@anchor{authentication}
+@chapter {Authentication}
+
+Both the ledger state and individual entries are signed by one or more private keys.
+
+A ledger state is kept to ensure sequential serial numbers for each added entries. A serial number out of sequence @emph{must} invalidate the ledger.
+
+Furthermore, entries form a chain. Each entry contains the digest of the entry preceding it.
+
+
+@subsection{Key trust}
+
+@strong{usawa} does not specify any particular trust engine or public key infrastructure to use.
+
+However, the specification does include a mechanism for embedding identity metadata, described in @ref{identity,Identities}.
+
+The corresponding element in the @ref{ledger_header, ledger header} also provides a means to describe what each identity can be trusted to sign for.
diff --git a/dummy/doc/protocol.texi b/dummy/doc/protocol.texi
@@ -19,6 +19,63 @@ All participants could be asked to follow both a @strong{nostr}@footnote{nostr i
Also, all participants would be encouraged to follow an @emph{EVM chain}@footnote{A list of EVM chains: @url{https://chainlist.org/}} that could publish the latest ledger state digest in the data field of a transaction.
-@section Determining trust
+@section Authentication
+In the @strong{usawa} system, signatures are not part of the immutable state.
+Hence, once an entry is created, multiple parties may sign off on the transaction.
+
+Authentication is contingent on the availability of the detached signatures. In other words, it is the responibility of each party wishing to verify the ledger to collect and store the signatures.
+
+
+@subsection Procedure
+
+To authenticate, signatures must be verified @emph{and} the signers must be trusted to make authentication statements.
+
+In principle, a trusted signature on the last entry in a chain could be understood to be a statement of the entire entry chain. However, it is recommended that client software explicitly verifies trusted signatures on every entry.
+
+
+@subsection Quorum
+
+It is up to the client to determine the "weight" of signatures required to be considered authentic.
+
+This weighting can be a number of principles, at discretion of the client:
+
+* A single valid signature.
+* `n` of out `m` signatures.
+* Cumulative score of individually weighted signatures.
+
+
+@subsection Local authentication
+
+It is also recommended that the software adds the client's own signature over the entries. This way, entries can easily be authenticated in the future by merely checking for this signature.
+
+In general, a local signature should always result in successful authentication (locally) of any data item, regardless of quorum.
+
+
+@subsection Seal and deletion
+
+As part of local authentication, entries should be explicitly sealed when considered authentic by the client.
+
+To seal an entry means that the entry may no longer be deleted (or changed). It also means that any consecutive entry needs to have succeeding serial number to be successfully authenticated.
+
+Any unsealed entry may be deleted, but doing so necessarily invalidates any succeeding entries using the digest of the deleted entry as its parent.
+
+
+@subsection Example
+
+Alice wants to know if a entry chain in a ledger is authentic.
+
+Alice trusts any entry that has at least two signatures from either Bob, Carol or Dave.
+
+Alice receives notification about a new entry. She inspects the entry. It has a signature from Carol.
+
+Alice stores the entry, waiting for an additional signature.
+
+Alice receives notification about a new signature. It has a signature from Dave on the same entry. Alice stores the signature.
+
+Alice notices that the entry has quorum. Alice signs the entry. Alice stores her signature.
+
+Alice seals the entry.
+
+When Alices later views the ledger, each entry is authenticated against her signature.
