From 79a3c7a2066f8c010e2a6abab8411cd71ef49b59 Mon Sep 17 00:00:00 2001
From: Jacek Sieka <jacek@status.im>
Date: Tue, 3 Dec 2024 14:29:03 +0100
Subject: [PATCH] Initial release (v0.8.0)

First versioned release to celebrate the increased capabilities of
`nimble` to work with versions ;)

This release is "nearly" feature-complete but still has some open
API/ABI questions, in particular around endians, bitops and other
convenience features.

Ideally, a 1.0 release would also not carry a stew dependency but rather
see that part of stew exported to its own
[intops](https://github.com/status-im/nim-stew/pull/187) library that
would gather all the low-level stuff and define a common minimally
supported API for all kinds of integers, native or not.
---
 README.md    | 65 +++++++++++++++++++++++++++++++++++++---------------
 stint.nimble |  2 +-
 2 files changed, 47 insertions(+), 20 deletions(-)

diff --git a/README.md b/README.md
index 76b4191..55982cc 100644
--- a/README.md
+++ b/README.md
@@ -1,28 +1,55 @@
-# Stint (Stack-based multiprecision integers)
+# Stint (Stack-based arbitrary precision integers)
 
 [![License: Apache](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 ![Stability: experimental](https://img.shields.io/badge/stability-experimental-orange.svg)
 ![Github action](https://github.com/status-im/nim-stint/workflows/CI/badge.svg)
 
-A fast and portable stack-based multi-precision integer library in pure Nim
-
-Main focus:
-  - Portability
-    - 32 and 64 bit arch
-    - ARM for usage on mobile phones
-    - Additionally RISC-V and MIPS for open hardware and low power IoT devices.
-  - Speed, library is carefully tuned to produce the best assembly given the current compilers.
-    However, the library itself does not resort to assembly for portability.
-  - No heap/dynamic allocation
-  - Ethereum applications
-    - Uint256/Int256 for Ethereum Virtual Machine usage.
-    - Uint2048 for Ethereum Bloom filters
-  - Ease of use:
-    - Use traditional `+`, `-`, `+=`, etc operators like on native types
-    - converting to and from raw byte BigInts (also called octet string in IETF specs)
-    - converting to and from Hex
-    - converting to and from decimal strings
+`stint` provides efficient and convenient N-bit integers for Nim, for arbitrary
+sizes of `N` decided at compile time with an interface similar to to
+`int64`/`uint64`.
+
+In addition to basic integer operations, `stint` also contains primtives for
+modular arithmetic, endian conversion, basic I/O, bit twiddling etc.
+
+`stint` integers, like their `intXX`/`uintXX` counterpart in Nim are stack-based
+values, meaning that they are naturally allocation-free and have value-based
+semantics.
+
+```nim
+import stint
+
+func addmul(a, b, c: UInt256): UInt256 =
+  a * b + c
+
+echo addmul(u256"100000000000000000000000000000", u256"1", u256"2")
+```
+
+## Priorities
+
+- Portability
+  - 32 and 64 bit
+  - ARM/x86/x86_64 extensively tested
+  - Additionally RISC-V and MIPS for open hardware and low power IoT devices.
+- Speed, library is carefully tuned to produce the best assembly given the current compilers.
+  However, the library itself does not require assembly for portability.
+- No heap/dynamic allocation
+- Ease of use:
+  - Use traditional `+`, `-`, `+=`, etc operators like on native types
+  - converting to and from raw byte BigInts (also called octet string in IETF specs)
+  - converting to and from Hex
+  - converting to and from decimal strings
+
+Non-priorities include:
+
+* constant-time operation (not suitable for certain kinds of cryptography out of the box)
+* runtime precision
+
+## See also
+
+* [constantine](https://github.com/mratsim/constantine) - modular arithmetic and elliptic curve operations focusing on cryptography and constant-time implementation
+* [N2472](https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2472.pdf) - `_ExtInt(N)` - native arbitrary precision integers for C
+* [stew](https://github.com/status-im/nim-stew/) - helpers and utilities for ordinary Nim integers (`endians2`, `bitops2` etc)
 
 ## License
 
diff --git a/stint.nimble b/stint.nimble
index 9d0a492..6e4858d 100644
--- a/stint.nimble
+++ b/stint.nimble
@@ -1,7 +1,7 @@
 mode = ScriptMode.Verbose
 
 packageName   = "stint"
-version       = "2.0.0"
+version       = "0.8.0"
 author        = "Status Research & Development GmbH"
 description   = "Efficient stack-based multiprecision int in Nim"
 license       = "Apache License 2.0 or MIT"