some timing diagrams in the olm spec would be helpful

[richvdh]

showing how a session is established with prekey and normal messages

[penguin42]

Some things to think about including:
a) note the lifetime of the olm session - for me I hadn't realised it lasted for longer than one run of a client
b) What to do with a type !=0 m.room.encrypted - it's not that clear to me how you're supposed to find the session for that
c) Is there exactly one olm session between a pair of devices? Is it bidirectional?

[richvdh]

technically they aren't really olm things; they are about how matrix uses olm. The matrix spec needs a whole chapter on that, which is covered under the rather loose bug matrix-org/matrix-spec-proposals#501.

[pik]

b) What to do with a type !=0 m.room.encrypted - it's not that clear to me how you're supposed to find the session for that

I suppose there should be a specification for re-establishing a session between devices if it is orphaned on one side. Not sure if any such strategy exists currently?

c) Is there exactly one olm session between a pair of devices? Is it bidirectional?

(https://whispersystems.org/docs/specifications/doubleratchet/#diffie-hellman-ratchet).

Was actually looking for an excuse to try Drakon, (btw is there a preferred format / tool for doing diagrams for inclusion in the docs?)

[richvdh]

btw is there a preferred format / tool for doing diagrams for inclusion in the docs?

er, ascii art? Otherwise I don't really think so.