Merge branch 'master' into con-79-prepare-contracts-for-audit

docs/architecture.md

@@ -0,0 +1,37 @@
+# Architecture
+
+For every chain, we deploy a total of 8 contracts to power the coprocessor:
+
+1. `RouterProxy` - The main, immutable entrypoint for the system. Clients send requests and receive responses from this contract.
+1. `Router` - The implementation contract for the `RouterProxy`.
+1. `RouterProxyAdmin` - The admin contract for the `RouterProxy`.
+1. `DatabaseManager` - The contract that reflects the state of the database that the LPN is indexing offchain. This is where new queries are registered.
+1. `DatabaseManagerProxy` - The proxy contract for the `DatabaseManager`.
+1. `DatabaseManagerProxyAdmin` - The admin contract for the `DatabaseManagerProxy`.
+1. `QueryExecutor` - The contract that validates query requests and groth16 response proofs.
+1. `FeeCollector` - A generic, central contract for collecting fees.
+
+```mermaid
+---
+title: Architecture
+---
+graph TD
+    %% Router Components
+    RPA[Router Proxy Admin] <--> RP[Router Proxy] --> RI[Router Impl]
+    
+
+    %% Database Components
+    DBPA[DB Proxy Admin] <--> DMP[Database Manager Proxy] --> DRI[Database Manager Impl]
+
+    %% Query Execution Components
+    QE[Query Executor]
+
+    %% Fee Collection
+    FC[Fee Collector]
+
+    %% Connections
+    RP <--> QE
+    QE --> FC
+    QE --> DMP
+
+```

docs/request-flow.md

@@ -0,0 +1,28 @@
+# Request Flow
+
+1. A client sends a request to the `LagrangeQueryRouter`
+2. The `LagrangeQueryRouter` forwards the request to the default `QueryExecutor`
+3. The `QueryExecutor` does the following:
+    * Validates the request
+    * Confirms with the `DatabaseManager` that the query and table are active
+    * Confirms the fee paid is sufficient
+    * Forwards the fee to the `FeeCollector`
+
+```mermaid
+---
+title: Request Flow
+---
+graph TD
+    %% Components
+    R[Router]
+    DBM[Database Manager]
+    QE[Query Executor]
+    FC[Fee Collector]
+
+    %% Request Flow
+    RQ((Request)) --> R
+    R --> QE
+    QE --> FC
+    QE --> DBM
+    DBM --> QE
+```

docs/response-flow.md

@@ -0,0 +1,25 @@
+# Response Flow
+
+1. The Lagrange Relayer (offchain component) sends a response to the `LagrangeQueryRouter`
+2. The `LagrangeQueryRouter` forwards the request to the same `QueryExecutor` that the original request was sent to
+3. The `QueryExecutor` does the following:
+    * Validates the Groth16 proof
+    * Returns back to the `LagrangeQueryRouter`
+4. The `LagrangeQueryRouter` calls the client contract with the response data
+
+```mermaid
+---
+title: Response Flow
+---
+graph TD
+    %% Components
+    R[Router]
+    CL[Client Contract]
+    QE[Query Executor]
+
+    %% Response Flow
+    RS((Response)) --> R
+    R --> QE
+    QE --> R
+    R --> CL
+```