diff --git a/task-impls/HotShot_event_architecture.drawio b/task-impls/HotShot_event_architecture.drawio
new file mode 100644
index 0000000000..ee5702aa4e
--- /dev/null
+++ b/task-impls/HotShot_event_architecture.drawio
@@ -0,0 +1,294 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/task-impls/HotShot_event_architecture.png b/task-impls/HotShot_event_architecture.png
new file mode 100644
index 0000000000..1c1891624c
Binary files /dev/null and b/task-impls/HotShot_event_architecture.png differ
diff --git a/task-impls/README.md b/task-impls/README.md
new file mode 100644
index 0000000000..9dd0c2ae81
--- /dev/null
+++ b/task-impls/README.md
@@ -0,0 +1,6 @@
+HotShot uses an event-based architecture. This architecture is made of 4 main tasks: Network Task, View Sync Task, Consensus Task, and DA Task. The Network Task handles all incoming and outgoing messages. It forwards incoming messages to the correct task and listens for outgoing messages from the other tasks. The View Sync Task coordinates the view sync protocol. It listens for timeout events from the Consensus Task. Once a certain threshold of timeouts seen has been reached, the View Sync Task starts the View Sync protocol to bring the network back into agreement on which view it should be in. The Consensus Task handles the core HotShot consensus logic. It manages replicas that listen for quourm propsoals and vote on them, leaders who send quorum proposals, and next leaders who listen for quorum votes and form QCs. The DA task handles the data availability protocol of HotShot. It listens for DA proposals, sends DA proposals, and forms a Data Availability Certificate (DAC)
+
+A diagram of how events interact with each task is below:
+
+
+For more information about each event see `./src/events.rs`
\ No newline at end of file
diff --git a/task-impls/src/events.rs b/task-impls/src/events.rs
index 02dac11096..d50e73f60a 100644
--- a/task-impls/src/events.rs
+++ b/task-impls/src/events.rs
@@ -12,32 +12,53 @@ use crate::view_sync::ViewSyncPhase;
#[derive(Eq, Hash, PartialEq, Debug, Clone)]
pub enum SequencingHotShotEvent> {
+ /// Shutdown the task
Shutdown,
+ /// A quorum proposal has been received from the network; handled by the consensus task
QuorumProposalRecv(Proposal>, TYPES::SignatureKey),
+ /// A quorum vote has been received from the network; handled by the consensus task
QuorumVoteRecv(QuorumVote),
+ /// A DA proposal has been received from the network; handled by the DA task
DAProposalRecv(Proposal>, TYPES::SignatureKey),
+ /// A DA vote has been received by the network; handled by the DA task
DAVoteRecv(DAVote),
+ /// A Data Availability Certificate (DAC) has been recieved by the network; handled by the consensus task
DACRecv(DACertificate),
+ /// Send a quorum proposal to the network; emitted by the leader in the consensus task
QuorumProposalSend(Proposal>, TYPES::SignatureKey),
+ /// Send a quorum vote to the next leader; emitted by a replica in the consensus task after seeing a valid quorum proposal
QuorumVoteSend(QuorumVote),
+ /// Send a DA proposal to the DA committee; emitted by the DA leader (which is the same node as the leader of view v + 1) in the DA task
DAProposalSend(Proposal>, TYPES::SignatureKey),
+ /// Send a DA vote to the DA leader; emitted by DA committee members in the DA task after seeing a valid DA proposal
DAVoteSend(DAVote),
+ /// The next leader has collected enough votes to form a QC; emitted by the next leader in the consensus task; an internal event only
QCFormed(QuorumCertificate),
+ /// The DA leader has collected enough votes to form a DAC; emitted by the DA leader in the DA task; sent to the entire network via the networking task
DACSend(DACertificate, TYPES::SignatureKey),
+ /// The current view has changed; emitted by the replica in the consensus task or replica in the view sync task; received by almost all other tasks
ViewChange(ViewNumber),
+ /// Timeout for the view sync protocol; emitted by a replica in the view sync task
ViewSyncTimeout(ViewNumber, u64, ViewSyncPhase),
+ /// Send a view sync vote to the network; emitted by a replica in the view sync task
ViewSyncVoteSend(ViewSyncVote),
+ /// Send a view sync certificate to the network; emitted by a relay in the view sync task
ViewSyncCertificateSend(
Proposal>,
TYPES::SignatureKey,
),
+ /// Receive a view sync vote from the network; received by a relay in the view sync task
ViewSyncVoteRecv(ViewSyncVote),
+ /// Receive a view sync certificate from the network; received by a replica in the view sync task
ViewSyncCertificateRecv(Proposal>),
+ /// Trigger the start of the view sync protocol; emitted by view sync task; internal trigger only
ViewSyncTrigger(ViewNumber),
+ /// A consensus view has timed out; emitted by a replica in the consensus task; received by the view sync task; internal event only
Timeout(ViewNumber),
+ /// Receive transactions from the network
TransactionsRecv(Vec),
+ /// Send transactions to the network
TransactionSend(TYPES::Transaction, TYPES::SignatureKey),
-
- // Event to send DA block data from DA leader to next quorum leader (which should always be the same node)
+ // Event to send DA block data from DA leader to next quorum leader (which should always be the same node); internal event only
SendDABlockData(TYPES::BlockType),
}