Persistence & Session Event Log Brain Dump

[arminsabouri]

A running brain dump of notes I took while working on #336 and a generalized session event log. Everything in this document is subject to change.

• To satisfy issue There is no documented best practice or API to display historical payjoin activity #336, we need to capture additional states beyond just initializing the typestates. Specifically, we must track whether a Payjoin session is pending, failed (with ephemeral or non-ephemeral failure), or completed. Additionally, we may want to record whether a fallback was invoked, which itself represents a kind of completion.

• First, we introduce a close method to the Persister trait. This method should be invoked whenever the typestate reaches its final "happy path" state.

• To capture the full lifecycle of a Payjoin session, we introduce a session event log. The Persister.save method will now store session events. recv, sender, and their multiparty variants will emit different event types, since their state machines differ.

• Likewise, Persister.load will return an iterator over session events. These events are loosely ordered. For example, the creation event is always at index 0.

• Session events should record the state of the session both before and after operations that have side effects—such as reading from the directory or checking the database to ensure inputs are not owned. If a failure occurs during one of these operations, it should also be captured in the event log.

• We’ve also decided to decouple the session ID from the Persister trait and the API. The session ID will now be opaque to the API and fully generated by the application. This decoupling is important for two reasons: (1) it avoids binding the API design to key generation behavior, and (2) it prevents changes to the API from altering key derivation logic.

• Replaying the event log is not strictly within the scope of There is no documented best practice or API to display historical payjoin activity #336. However, all relevant logs should still be recorded so that replaying becomes feasible later—especially for multiparty sender/recv. For now, resume will work similarly to today: it finds the first session event (which corresponds to the initial typestate), kicks off the typestate (with side effects), and proceeds from there. In this first iteration, replay is only supported from the beginning of the event log.

• This should satisfy the requirements of There is no documented best practice or API to display historical payjoin activity #336 by capturing all critical session states: initialization, failure or completion, and potentially fallback as a distinct type of completion.

• Finally, we may want to revisit the typestate machine itself—specifically, making recv/sender generic over the state they’re in, as described here: https://cliffle.com/blog/rust-typestate/#variation-state-types-that-contain-actual-state. However, this might produce headaches in FFI land.

More updates to come