From 6f64c2d46f17106a6ae998bbda3f98a8d2ea9da7 Mon Sep 17 00:00:00 2001
From: odudex <odudex@proton.me>
Date: Tue, 12 May 2026 17:54:44 -0300
Subject: [PATCH] docs(secp256k1): document local build loading and submodule
 init

---
 secp256k1/README.md | 36 ++++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)

diff --git a/secp256k1/README.md b/secp256k1/README.md
index 502daa47..3097c5d0 100644
--- a/secp256k1/README.md
+++ b/secp256k1/README.md
@@ -13,6 +13,11 @@ git clone --recursive https://github.com/diybitcoinhardware/embit.git
 
 This will automatically pull in the `libsecp256k1-zkp` repo and checkout the correct commit within that repo.
 
+Alternatively, if you already have `embit` cloned, run:
+```sh
+git submodule update --recursive --init
+```
+
 
 ## Building the library
 This directory (`secp256k1/` in the `embit` root) already has a fully-configured Makefile to run the compilation for you.
@@ -22,6 +27,37 @@ On your target platform run:
 make
 ```
 
+This creates a platform-specific shared library under `secp256k1/build/`, for
+example:
+
+```sh
+secp256k1/build/libsecp256k1_linux_x86_64.so
+```
+
+## Loading the local build in Python
+
+`embit` looks for local libsecp256k1 artifacts in
+`secp256k1/secp256k1-zkp/.libs/` before falling back to system library paths.
+After running `make`, expose the helper Makefile output at that lookup path:
+
+```sh
+mkdir -p secp256k1-zkp/.libs
+ln -sf ../../build/libsecp256k1_$(uname -s | tr A-Z a-z)_$(uname -m).so \
+  secp256k1-zkp/.libs/libsecp256k1.so
+```
+
+Run those commands from the `secp256k1/` directory. On macOS, replace the
+`.so` suffix with `.dylib`.
+
+You can verify that Python loaded the native backend from the repository root:
+
+```sh
+PYTHONPATH=src python -c "from embit.ec import secp256k1; print(hasattr(secp256k1, 'ecdh'), hasattr(secp256k1, 'rangeproof_rewind'))"
+```
+
+Both values should print `True`. If they do, the optional ECDH and Liquid/ZKP
+tests can run instead of being skipped.
+
 Install the resulting library into a standard system library location so the dynamic loader can find it (for example `/usr/local/lib` on Unix-like systems), then refresh your linker environment as needed for your platform.
 
 Note: runtime lookup prefers local `secp256k1/secp256k1-zkp/.libs` and system library paths.