From 67e4b37bccd2eaed662d2736edd380ec2cb8d383 Mon Sep 17 00:00:00 2001
From: Yorke Rhodes <yorke@hyperlane.xyz>
Date: Mon, 7 Oct 2024 16:19:14 -0400
Subject: [PATCH] Add READMEs to hook and ism folders

---
 solidity/contracts/hooks/README.md | 58 ++++++++++++++++++++++++++++++
 solidity/contracts/isms/README.md  | 20 +++++++++++
 2 files changed, 78 insertions(+)
 create mode 100644 solidity/contracts/hooks/README.md
 create mode 100644 solidity/contracts/isms/README.md

diff --git a/solidity/contracts/hooks/README.md b/solidity/contracts/hooks/README.md
new file mode 100644
index 000000000..6c538dfd4
--- /dev/null
+++ b/solidity/contracts/hooks/README.md
@@ -0,0 +1,58 @@
+# Post-Dispatch Hooks
+
+Post-dispatch hooks allow developers to configure additional origin chain behavior with message content dispatched via the Mailbox.
+
+```mermaid
+flowchart TB
+    subgraph Origin
+      Sender
+      M_O[(Mailbox)]
+      Hook[IPostDispatchHook]
+
+      Sender -- "dispatch(..., metadata, hook)\n{value}" --> M_O
+      M_O -- "postDispatch(message, metadata)\n{value}" --> Hook
+    end
+```
+
+If the `postDispatch` function receives insufficient payment, it may revert.
+
+> [!WARNING]
+> Post-Dispatch Hooks may be replayable. Developers creating custom hooks should implement safe checks to prevent this behavior. [Here](./warp-route/RateLimitedHook.sol#L16) is an example implementation.
+
+### Quote Dispatch (Fees)
+
+Fees are often charged in `postDispatch` to cover costs such as destination chain transaction submission and security provisioning. To receive a quote for a corresponding `postDispatch` call, you can query the `quoteDispatch` function.
+
+The Mailbox has a `quoteDispatch` function that returns the aggregate fee required for a `dispatch` call to be successful.
+
+```mermaid
+flowchart TB
+    subgraph Origin
+      Sender
+      M_O[(Mailbox)]
+      R_H[RequiredHook]
+      Hook[Hook]
+
+      Sender -- "quoteDispatch(..., metadata, hook)" --> M_O
+      M_O -- "required = quoteDispatch(message, metadata)" --> R_H
+      M_O -- "fee = hook.quoteDispatch(message, metadata)" --> Hook
+      M_O -- "required + fee" --> Sender
+    end
+```
+
+The custom `metadata` will be passed to the required hook's `quoteDispatch` and `postDispatch` functions, before being passed to the default hook's `postDispatch` function.
+
+```mermaid
+flowchart LR
+    subgraph Origin Chain
+      Sender
+      M_O[(Mailbox)]
+      R_H[RequiredHook]
+      D_H[DefaultHook]
+      Sender -- "dispatch(..., metadata){value}" --> M_O
+
+      M_O -. "fee = quoteDispatch(...)" .- R_H
+      M_O -- "postDispatch(metadata, ...)\n{fee}" --> R_H
+      M_O -. "postDispatch(metadata, ...)\n{value - fee}" ..-> D_H
+    end
+```
diff --git a/solidity/contracts/isms/README.md b/solidity/contracts/isms/README.md
new file mode 100644
index 000000000..d9f74f397
--- /dev/null
+++ b/solidity/contracts/isms/README.md
@@ -0,0 +1,20 @@
+# Interchain Security Modules
+
+Interchain security modules allow developers to configure additional security checks for message content dispatched via the Mailbox.
+
+```mermaid
+flowchart LR
+    subgraph Destination Chain
+      ISM[InterchainSecurityModule]
+      Recipient[Recipient]
+      M_D[(Mailbox)]
+
+      M_D -- "verify(metadata, message)" --> ISM
+      ISM -. "interchainSecurityModule()" .- Recipient
+      M_D -- "handle(origin, sender, body)" --> Recipient
+
+    end
+```
+
+> [!WARNING]
+> Interchain security modules may be replayable. Developers creating custom modules should include replay protection if necessary. [Here](./warp-route/RateLimitedIsm.sol#L23) is an example implementation.