From 7bf64b65b7f3ada6a14f36d3c2107e17f59963b5 Mon Sep 17 00:00:00 2001
From: gmega <giuliano.mega@gmail.com>
Date: Mon, 2 Feb 2026 15:50:33 -0300
Subject: [PATCH] docs: update README to reflect current implementation

Add INI config file support, e_storage_spr() usage, nat config field,
uploader/downloader examples, and correct project structure.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 README.md | 77 ++++++++++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 62 insertions(+), 15 deletions(-)

diff --git a/README.md b/README.md
index 1b25aae..469bed3 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # libeasystorage
 
-A simplified, higher level C wrapper around [libstorage](https://github.com/status-im/logos-storage-nim). Includes
+A simplified, higher-level C wrapper around [libstorage](https://github.com/status-im/logos-storage-nim). Includes
 examples showing how to implement simple filesharing apps.
 
 ## Prerequisites
@@ -16,9 +16,10 @@ cmake -B build -DLOGOS_STORAGE_NIM_ROOT=/path/to/logos-storage-nim
 cmake --build build
 ```
 
-This produces:
-- `libeasystorage.so` — the shared library
-- `storageconsole` — an example CLI application
+This produces three example executables:
+- `storageconsole` — interactive CLI for managing a storage node
+- `uploader` — uploads a local file and prints the CID and SPR
+- `downloader` — downloads a file given a bootstrap SPR and CID
 
 ## API
 
@@ -31,11 +32,16 @@ node_config cfg = {
     .disc_port = 9090,
     .data_dir = "./data",
     .log_level = "INFO",
-    .bootstrap_node = "<SPR>"
+    .bootstrap_node = "<SPR>",
+    .nat = "auto"
 };
 STORAGE_NODE node = e_storage_new(cfg);
 e_storage_start(node);
 
+// Get the node's Signed Peer Record
+char *spr = e_storage_spr(node);
+free(spr);
+
 // Upload a file
 char *cid = e_storage_upload(node, "/path/to/file.txt", progress_cb);
 // Download a file
@@ -47,9 +53,30 @@ e_storage_stop(node);
 e_storage_destroy(node);
 ```
 
-## Example: storageconsole
+Configuration can also be loaded from an INI file:
 
-An interactive CLI is included in `examples/storageconsole.c`:
+```ini
+[easystorage]
+api-port=8080
+disc-port=9090
+data-dir=./data
+log-level=INFO
+bootstrap-node=spr:...
+nat=none
+```
+
+```c
+node_config cfg = {0};
+e_storage_read_config("config.ini", &cfg);
+// ... use cfg ...
+e_storage_free_config(&cfg);
+```
+
+## Examples
+
+### storageconsole
+
+An interactive CLI included in `examples/storageconsole.c`:
 
 ```bash
 ./build/storageconsole
@@ -57,25 +84,45 @@ An interactive CLI is included in `examples/storageconsole.c`:
 
 Commands: `help`, `start`, `stop`, `upload`, `download`, `quit`.
 
+### uploader / downloader
+
+Standalone programs that demonstrate file sharing between two nodes. On one machine, start the uploader:
+
+```bash
+./build/uploader ./myfile.txt
+# prints: Run: downloader <SPR> <CID> ./output-file
+```
+
+On another (or the same machine), run the downloader with the printed values:
+
+```bash
+./build/downloader <SPR> <CID> ./output-file
+```
+
 ## Testing
 
 ```bash
 cmake --build build
-./build/test_runner
+ctest --test-dir build
 ```
 
+Tests use a mock libstorage implementation and do not require a running storage node.
+
 ## Project Structure
 
 ```
-easystorage/
-├── easystorage.h         # Public API
-├── easystorage.c         # Implementation
+├── easystorage.h             # Public API
+├── easystorage.c             # Implementation
+├── CMakeLists.txt
 ├── examples/
-│   └── storageconsole.c  # CLI example
+│   ├── storageconsole.c      # Interactive CLI
+│   ├── uploader.c            # File upload example
+│   └── downloader.c          # File download example
 ├── tests/
-│   ├── test_runner.c
-│   └── mock_libstorage.c
-└── CMakeLists.txt
+│   ├── test_runner.c         # Unit tests
+│   └── mock_libstorage.c     # Mock libstorage for testing
+└── vendor/
+    └── inih/                 # Vendored INI file parser
 ```
 
 ## License