1 package btcec
2 3 import (
4 "smesh.lol/pkg/nostr/ec/secp256k1"
5 )
6 7 // FieldVal implements optimized fixed-precision arithmetic over the secp256k1
8 // finite field. This means all arithmetic is performed modulo
9 // '0xfffffffffffffffffffffffffffffffffffffffffffffffffffffffefffffc2f'.
10 //
11 // WARNING: Since it is so important for the field arithmetic to be extremely
12 // fast for high performance crypto, this type does not perform any validation
13 // of documented preconditions where it ordinarily would. As a result, it is
14 // IMPERATIVE for callers to understand some key concepts that are described
15 // below and ensure the methods are called with the necessary preconditions
16 // that each method is documented with. For example, some methods only give the
17 // correct result if the field value is normalized and others require the field
18 // values involved to have a maximum magnitude and THERE ARE NO EXPLICIT CHECKS
19 // TO ENSURE THOSE PRECONDITIONS ARE SATISFIED. This does, unfortunately, make
20 // the type more difficult to use correctly and while I typically prefer to
21 // ensure all state and input is valid for most code, this is a bit of an
22 // exception because those extra checks really add up in what ends up being
23 // critical hot paths.
24 //
25 // The first key concept when working with this type is normalization. In order
26 // to avoid the need to propagate a ton of carries, the internal representation
27 // provides additional overflow bits for each word of the overall 256-bit
28 // value. This means that there are multiple internal representations for the
29 // same value and, as a result, any methods that rely on comparison of the
30 // value, such as equality and oddness determination, require the caller to
31 // provide a normalized value.
32 //
33 // The second key concept when working with this type is magnitude. As
34 // previously mentioned, the internal representation provides additional
35 // overflow bits which means that the more math operations that are performed
36 // on the field value between normalizations, the more those overflow bits
37 // accumulate. The magnitude is effectively that maximum possible number of
38 // those overflow bits that could possibly be required as a result of a given
39 // operation. Since there are only a limited number of overflow bits available,
40 // this implies that the max possible magnitude MUST be tracked by the caller
41 // and the caller MUST normalize the field value if a given operation would
42 // cause the magnitude of the result to exceed the max allowed value.
43 //
44 // IMPORTANT: The max allowed magnitude of a field value is 64.
45 type FieldVal = secp256k1.FieldVal
46