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..8ace764 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" @@ -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