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