From 66d31cf26b4a4f035ccce9e7c245d784c12f5fc2 Mon Sep 17 00:00:00 2001
From: David Whittington <djwhitt@gmail.com>
Date: Mon, 9 Dec 2024 09:44:44 -0600
Subject: [PATCH] WIP ArNS caching ADR

---
 docs/madr/002-arns-cache-timing.md | 59 ++++++++++++++++++++++++++++++
 1 file changed, 59 insertions(+)
 create mode 100644 docs/madr/002-arns-cache-timing.md

diff --git a/docs/madr/002-arns-cache-timing.md b/docs/madr/002-arns-cache-timing.md
new file mode 100644
index 00000000..e085202e
--- /dev/null
+++ b/docs/madr/002-arns-cache-timing.md
@@ -0,0 +1,59 @@
+# ArNS Cache Timing
+
+- Status: proposed
+- Deciders: [David]
+- Date: 2024-12-09
+- Authors: [David]
+
+## Context and Problem Statement
+
+ArNS resolution requires multiple AO process interactions. Caches are used in
+this process to reduce response latency and AO CU load. There is an intrinsic
+trade-off between reducing response latency and AO CU load and the freshness of
+ArNS responses. In order to allow gateway operators to opimtize these
+trade-offs we need to define the levels of caching involved and make them
+configurable. The purpose of this ADR is to show the levels of caching and
+define the relevant timeouts involved.
+
+## Decision Outcome
+
+### Resolution Flow
+
+```mermaid
+%%{init: {'theme': 'dark'}}%%
+flowchart TD
+    Start([Resolution Requested]) --> CDN[CDN]
+    CDN --> CDNStatus{"CDN Cache Status"}
+    CDNStatus -->|Hit| Resolution
+    CDNStatus -->|Miss| NameCache
+
+    subgraph Gateway ["AR.IO Gateway"]
+        NameCache["Name List Cache"]
+
+        NameCache --> ListStatus{"Name List Status"}
+        ListStatus -->|Up-to-date| ANTCache["ANT State Cache"]
+        ListStatus -->|"Stale (name list TTL expired)"| IO["IO AO Process"]
+        ListStatus -->|Not Cached| IO
+
+        ANTCache --> StateStatus{"ANT State Status"}
+        StateStatus -->|"Stale (name TTL expired)"| ANT["ANT AO Process"]
+        StateStatus -->|Not Cached| ANT
+
+        IO -->|"Update Cache &lt;debounced&gt;"| NameCache
+        ANT -->|"Update Cache &lt;debounced and concurrency limited&gt;"| ANTCache
+    end
+
+    StateStatus -->|Up-to-date| Resolution([Resolution Returned])
+
+    style Start fill:#ff69b4,stroke:#333
+    style CDN fill:#4169e1,stroke:#333
+    style NameCache fill:#4169e1,stroke:#333
+    style IO fill:#4169e1,stroke:#333
+    style ANT fill:#4169e1,stroke:#333
+    style ListStatus fill:#ff69b4,stroke:#333
+    style ANTCache fill:#4169e1,stroke:#333
+    style StateStatus fill:#ff69b4,stroke:#333
+    style Resolution fill:#ff69b4,stroke:#333
+    style CDNStatus fill:#ff69b4,stroke:#333
+
+```