From eba27f919b75f2be009c87f52a86226c048cefdf Mon Sep 17 00:00:00 2001
From: oyyblin <4529189+oyyblin@users.noreply.github.com>
Date: Thu, 31 Oct 2024 11:52:06 -0700
Subject: [PATCH] doc: Update README

---
 .github/workflows/ci.yml |  2 --
 README.md                | 23 ++++++++++-----
 contracts/README.md      | 62 ++++++++++++++++++++++++++++++++++++++++
 updater/README.md        |  8 ------
 4 files changed, 78 insertions(+), 17 deletions(-)
 create mode 100644 contracts/README.md

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index a07a614..cf354af 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -40,8 +40,6 @@ jobs:
         uses: docker/metadata-action@9ec57ed1fcdbf14dcef7dfbe97b2010124a938b7
         with:
           images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
-          labels: |
-            org.opencontainers.image.documentation=https://github.com/${{ github.repository }}/blob/main/updater/README.md
 
       # This step uses the `docker/build-push-action` action to build the image, based on your repository's `Dockerfile`. If the build succeeds, it pushes the image to GitHub Packages.
       # It uses the `context` parameter to define the build's context as the set of files located in the specified path. For more information, see "[Usage](https://github.com/docker/build-push-action#usage)" in the README of the `docker/build-push-action` repository.
diff --git a/README.md b/README.md
index 2a65e62..9859c03 100644
--- a/README.md
+++ b/README.md
@@ -1,14 +1,23 @@
-# Drand Oracle
+# 🎲 Drand Oracle
 
 A Solidity smart contract and updater service for bringing randomness from the [drand network](https://drand.love) on-chain.
 
-## Overview
+## 📄 Contract
 
-This project consists of two main components:
+The `DrandOracle` smart contract serves as an on-chain source of randomness by storing values from the drand network.
 
-1. A Solidity smart contract (`DrandOracle.sol`) that stores randomness values along with necessary metadatas and signatures to verify the randomness off chain.
-2. A Go updater service that fetches new randomness from drand and updates the contract.
+For more information, see the [contract README](contracts/README.md).
 
-## Contract
+## 🔄 Updater
 
-The randomness stored in the contract is verifiable off-chain but not on-chain. This is due to BLS signatures used by Drand network are not yet supported on EVM.
+The updater service fetches new randomness from drand and updates the `DrandOracle` contract with its managed signer and sender EOA addresses.
+
+For more information, see the [updater README](updater/README.md).
+
+## 📝 License
+
+This project is licensed under the [MIT License](LICENSE).
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to open an issue or submit a Pull Request.
diff --git a/contracts/README.md b/contracts/README.md
new file mode 100644
index 0000000..5fd0be6
--- /dev/null
+++ b/contracts/README.md
@@ -0,0 +1,62 @@
+# 📄 Drand Oracle Smart Contract
+
+## 🔎 Overview
+
+The `DrandOracle` smart contract serves as an on-chain source of randomness by storing values from the drand network.
+
+## 📚 Core Contracts
+
+### 🎲 DrandOracle.sol
+
+The main contract responsible for storing and managing randomness from the drand network.
+
+#### 🛠️ Usage
+
+- `getRandomnessFromRound(uint64 _round) external view returns (Random memory)`
+  - Retrieves the complete randomness data for a specific round
+  - Parameters:
+    - `_round`: The round number to query
+  - Returns:
+    - `Random memory`: The Random struct containing the round's data
+- `getRandomnessFromTimestamp(uint64 _timestamp) external view returns (Random memory)`
+  - Retrieves the complete randomness data for a specific timestamp, or the latest timestamp prior to the given timestamp if no exact match is found
+  - Parameters:
+    - `_timestamp`: The timestamp to query
+  - Returns:
+    - `Random memory`: The Random struct containing the timestamp's data
+
+### 🔒 Access Control
+
+The contract implements a simple single-updater access control pattern:
+
+- Only the designated updater address can submit new randomness
+- Updater address is set during contract deployment
+- Updater can be updated by the owner
+
+### ⚠️ Limitations
+
+1. The randomness stored in the contract is verifiable off-chain but not on-chain. This is due to BLS signatures used by Drand network are not yet supported on EVM.
+2. Reliance on trusted updater.
+
+### 🧪 Testing
+
+Run tests with:
+
+```bash
+forge test
+```
+
+### 💻 Run Locally
+
+1. Start local anvil chain
+
+```bash
+anvil
+```
+
+2. Deploy the contract
+
+```bash
+forge build
+make deploy-anvil
+```
diff --git a/updater/README.md b/updater/README.md
index bca4454..f370fe3 100644
--- a/updater/README.md
+++ b/updater/README.md
@@ -68,11 +68,3 @@ Go to the `updater` directory and run:
 ```bash
 make local-run-anvil
 ```
-
-## 📄 License
-
-MIT License.
-
-## 🤝 Contributing
-
-Contributions are welcome! Please feel free to submit a Pull Request.