From 2b7aaf12fc0fa288560072766ad6d8d39e5e37ed Mon Sep 17 00:00:00 2001 From: tv Date: Mon, 9 Nov 2026 15:37:36 +0000 Subject: docs: how signatures travel, as they do now Review 4, appendix: api.md's Signed changes said a node passes on each node's latest signature (true of deltas, not of messages carrying changes) and that every change arrives vouched for. It now says what a message carries (its changes' signatures, each run's latest past 4096 and for a delta), that a node signs each of its runs' latest unvouched change at start and when its document is swapped (1277), and the two cases that still arrive unvouched (a change vouched for only by a refused one, postponed; more than 4096 runs writing in an epoch). --- docs/api.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/api.md b/docs/api.md index 302df5d..078594b 100644 --- a/docs/api.md +++ b/docs/api.md @@ -287,8 +287,16 @@ same paths: a message carries the signatures of the changes it carries, whatever peer was sent before, so changes sent again (a message lost on the way) arrive vouched for as the first time; and a node checks one it receives once it holds the change (a signature costs about 30 µs to check, and one vouches for its node's changes -before it). A message carrying no changes carries no signatures. A node that stopped with changes it never sent, nor -signed, signs them as it starts, before anything leaves. +before it). A message carrying no changes carries no signatures; one carrying more +than 4096 signed changes (a whole document pulled), and a delta, carry each node run's +latest instead. A node signs the latest change of each of its runs that nothing vouches +for as it starts, before anything leaves, and whenever its document is swapped (a drop, +a switch, a rejoin): changes it kept unsigned, never sent. + +Two cases still arrive unvouched, and wait under a policy requiring signatures: a change +vouched for only by a later change of its node that the rules refused (nodes take it, +then can't pass the proof on, [`future-work.md`](future-work.md)); and, in one transfer, +the changes of an epoch with more than 4096 node runs writing. The signatures a node has are kept in its document file (`--document-file`) with the document. -- cgit v1.3.1