Skip to content

Commit

Permalink
Initial release (v0.8.0) (#161)
Browse files Browse the repository at this point in the history
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](status-im/nim-stew#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.
  • Loading branch information
arnetheduck authored Dec 4, 2024
1 parent ae665d6 commit c5a4355
Show file tree
Hide file tree
Showing 2 changed files with 48 additions and 21 deletions.
65 changes: 46 additions & 19 deletions README.md
Original file line number Diff line number Diff line change
@@ -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

Expand Down
4 changes: 2 additions & 2 deletions stint.nimble
Original file line number Diff line number Diff line change
@@ -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"
Expand All @@ -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
Expand Down

0 comments on commit c5a4355

Please sign in to comment.