docs(README): building from source

SolarRepublic · Nov 6, 2023 · 469a200 · 469a200
1 parent d59bd58
commit 469a200
Showing 1 changed file with 72 additions and 53 deletions.
diff --git a/README.md b/README.md
@@ -24,6 +24,65 @@ npm install @solar-republic/wasm-secp256k1
 ```
 
 
+## Usage
+
+First, choose which import method suites your needs:
+
+#### Default
+
+Import with the WASM binary preloaded and uncompressed. No need to perform `fetch`, but bundle will be larger (+332 KiB).
+
+```ts
+import {initWasmSecp256k1} from '@solar-republic/wasm-secp256k1'
+const secp256k1 = await initWasmSecp256k1();
+```
+
+#### Compressed
+
+Import with the WASM binary preloaded and gzipped (requires access to `globalThis.DecompressionSteam`). No need to perform `fetch`, but bundle will be still be a bit larger (+175 KiB).
+
+```ts
+import {initWasmSecp256k1} from '@solar-republic/wasm-secp256k1/gzipped'
+const secp256k1 = await initWasmSecp256k1();
+```
+
+#### Headless
+
+Import without the WASM binary. Produces the smallest bundle size but requires fetching the binary yourself.
+
+```ts
+import {WasmSecp256k1} from '@solar-republic/wasm-secp256k1/headless';
+
+// provide the binary (the constructor also accepts raw bytes)
+const secp256k1 = await WasmSecp256k1(await fetch('secp256k1.wasm'));
+```
+
+### Using the instance:
+
+```ts
+// generate a random private key
+const sk = secp256k1.gen_sk()
+
+// get its corresponding public key
+const pk = secp256k1.sk_to_pk(sk);
+
+// sign a message hash (caller is responsible for actually hashing the message and providing entropy)
+const signed = secp256k1.sign(sk, messageHash, entropy);
+
+// verify a given message hash is signed by some public key
+const verified = secp256k1.verify(signed, messageHash, pk);
+
+// derive a shared secret with some other's public key
+const shared = secp256k1.ecdh(sk, otherPk);
+
+
+// zero out private key
+sk.fill(0, 0, 32);
+```
+
+Caller is responsible for zero-ing out private keys in the Typed Arrays it passes. Library only zeroes out the bytes in the copies it makes.
+
+
 ## API
 
 ```ts
@@ -88,67 +147,27 @@ interface Secp256k1 {
 ```
 
 
-## Example
-
-Choose which import method suites your needs:
-
-```ts
-// import with the binary preloaded and uncompressed
-import {initWasmSecp256k1} from '@solar-republic/wasm-secp256k1'
-
-// no need to perform fetch, but bundle will be larger (+332 KiB)
-const secp256k1 = await initWasmSecp256k1();
-
-
-// --- OR ----
-
-
-// import with the binary preloaded and gzipped (requires globalThis.DecompressionSteam)
-import {initWasmSecp256k1} from '@solar-republic/wasm-secp256k1/gzipped'
-
-// no need to perform fetch, but bundle will be still be a bit larger (+175 KiB)
-const secp256k1 = await initWasmSecp256k1();
-
-
-// --- OR ----
-
-
-// import the 'headless' version
-import {WasmSecp256k1} from '@solar-republic/wasm-secp256k1/headless';
-
-// instantiate WASM module by providing the binary yourself (the constructor also accepts raw bytes)
-const secp256k1 = await WasmSecp256k1(await fetch('secp256k1.wasm'));
-
-```
+## Is libsecp256k1 modified?
 
-Using the instance:
-```ts
-// generate a random private key
-const sk = secp256k1.gen_sk()
+No, the library is imported as a git submodule directly from upstream.
 
-// get its corresponding public key
-const pk = secp256k1.sk_to_pk(sk);
 
-// sign a message hash (caller is responsible for actually hashing the message and providing entropy)
-const signed = secp256k1.sign(sk, messageHash, entropy);
+## Building from source
 
-// verify a given message hash is signed by some public key
-const verified = secp256k1.verify(signed, messageHash, pk);
+Prerequisites:
+ - Docker
+ - [Bun](https://bun.sh/) - a drop-in replacement for Node.js with native support for executing TypeScript
 
-// derive a shared secret with some other's public key
-const shared = secp256k1.ecdh(sk, otherPk);
-
-
-// zero out private key
-sk.fill(0, 0, 32);
+```sh
+git clone --recurse-submodules https://github.com/SolarRepublic/wasm-secp256k1
+cd wasm-secp256k1
+bun install
+bun run build
 ```
 
-Caller is responsible for zero-ing out private keys in the Typed Arrays it passes. Library only zeroes out the bytes in the copies it makes.
-
+The WASM binary will be output to `public/out/secp256k1.wasm`.
 
-## Is libsecp256k1 modified?
-
-No, the library is imported as a git submodule directly from upstream.
+The Emscripten-generated js file at `public/out/secp256k1.js` is not needed for production if you are using the provided wrapper.
 
 
 ## See also