Initial release (v0.8.0) (#161)

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

@@ -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
+`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`.
 
-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
+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
 

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"
@@ -10,7 +10,7 @@ skipDirs      = @["tests", "benchmarks"]
 
 # TODO test only requirements don't work: https://github.com/nim-lang/nimble/issues/482
 requires "nim >= 1.6.12",
-         "stew",
+         "stew >= 0.2.0",
          "unittest2 >= 0.2.3"
 
 let nimc = getEnv("NIMC", "nim") # Which nim compiler to use