Merge pull request #328 from ava-labs/diagrams

Add architecture and sequence diagrams

docs/architecture.md

@@ -0,0 +1,30 @@
+# Architecture
+Partial class diagram illustrating the important classes and functions for processing incoming blocks and relaying the contained Warp messages.
+```mermaid
+classDiagram
+    Listener o-- "per RelayerID" ApplicationRelayer
+    Listener *-- "1" Subscriber
+    Listener *-- "per message protocol" MessageHandlerFactory
+    ApplicationRelayer o-- "singleton" AppRequestNetwork
+    ApplicationRelayer o-- DestinationClient
+    ApplicationRelayer *-- CheckpointManager
+    CheckpointManager o-- RelayerDatabase
+    AppRequestNetwork *-- CanonicalValidatorClient
+    CanonicalValidatorClient --|> PChainClient
+
+    Listener : ProcessLogs()
+    ApplicationRelayer : ProcessHeight()
+    ApplicationRelayer : ProcessMessage()
+    CheckpointManager : StageCommittedHeight()
+    Subscriber : Subscribe()
+    Subscriber : Headers()
+    DestinationClient : SendTx()
+    MessageHandlerFactory : NewMessageHandler() MessageHandler
+    MessageHandler : ShouldSendMessage()
+    MessageHandler : SendMessage()
+    RelayerDatabase : Get()
+    RelayerDatabase : Put()
+    AppRequestNetwork : ConnectPeers()
+    AppRequestNetwork : ConnectToCanonicalValidators()
+    CanonicalValidatorClient : GetCurrentCanonicalValidatorSet()
+```

docs/sequence.md

@@ -0,0 +1,44 @@
+# Processing the Warp messages in a new block
+Illustration of the sequence of events triggered by a new block containing Warp messages to relay.
+```mermaid
+sequenceDiagram
+    participant Subscriber
+    participant Listener
+    participant ApplicationRelayer
+    participant MessageHandler
+    participant AppRequestNetwork
+    participant DestinationClient
+    participant CheckpointManager
+    participant RelayerDatabase
+
+    Subscriber->>Listener : (async) New block
+    activate Listener
+    Listener->>Listener : Collect Warp Logs in block
+    Listener->>Listener : Create handlers for each message
+    Listener-->>ApplicationRelayer : (async) Pass message handlers for block
+    deactivate Listener
+    activate ApplicationRelayer
+    par foreach Warp message in block
+        ApplicationRelayer->>MessageHandler : ShouldSendMessage
+        activate MessageHandler
+        MessageHandler->>ApplicationRelayer : true
+
+        par foreach canonical validator
+            ApplicationRelayer->>AppRequestNetwork : Request signatures
+            activate AppRequestNetwork
+            AppRequestNetwork->>ApplicationRelayer : signature
+        end
+        ApplicationRelayer->>ApplicationRelayer : Aggregate signatures
+
+        ApplicationRelayer->>MessageHandler : SendMessage
+        activate MessageHandler
+        MessageHandler->>DestinationClient : SendTx
+        activate DestinationClient
+        DestinationClient->>MessageHandler : txHash
+        MessageHandler->>MessageHandler : Wait for receipt
+        MessageHandler->>ApplicationRelayer : return
+    end
+    ApplicationRelayer->>CheckpointManager : Stage block height
+    deactivate ApplicationRelayer
+    CheckpointManager-->>RelayerDatabase : (async) Write height
+```