Struct secp256kfun::Point

pub struct Point<T = Normal, S = Public, Z = NonZero>(_, _, _);

A point on the secp256k1 elliptic curve.

A Point<T,S,Z> marked with Z = NonZero is any two integers modulo p (x,y) that satisfy:

y^2 = 3*x + 7 mod p

where p = 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEFFFFFC2F. For every valid x-coordinate, there will be exactly two valid y-coordinates which will be the negation modulo p of each other.

If the point is marked Z = Zero then it may also be point at infinity which is the identity element of the group.

Markers

A Point<T,S,Z> has three types parameters.

• T: A PointType used to reason about what the point can do and to specialize point operations.
• S: A Secrecy to determine whether operations on this point should be done in constant-time or not. By default points are Public so operations run in variable time.
• Z: A ZeroChoice to keep track of whether the point might be zero (the point at infinity) or is guaranteed to be non-zero.

Serialization

Only points that are marked with Z = NonZero and T ≠ Jacobian can be serialized. A Point that is EvenY serializes to and from the 32-byte x-only representation like the XOnly type. Normal points serialize to and from the standard 33-byte representation specified in Standards for Efficient Cryptography (the same as Point::to/from_bytes)

Implementations

impl Point<Normal, Public, NonZero>

pub fn from_bytes(bytes: [u8; 33]) -> Option<Self>

Creates a Point the compressed encoding specified in Standards for Efficient Cryptography. This is the typical encoding used in Bitcoin. The first byte must be 0x02 or 0x03 to indicate that the y-coordinate is even or odd respectively. The remaining 32 bytes must encode an x-coordinate on the curve. If these conditions are not then it will return None.

Examples

use secp256kfun::{Point, G};
let bytes = [
    2, 121, 190, 102, 126, 249, 220, 187, 172, 85, 160, 98, 149, 206, 135, 11, 7, 2, 155, 252,
    219, 45, 206, 40, 217, 89, 242, 129, 91, 22, 248, 23, 152,
];
let point = Point::from_bytes(bytes).unwrap();
assert_eq!(point, *G);

pub fn from_slice(slice: &[u8]) -> Option<Self>

Convenience method for calling from_bytes wth a slice. Returns None if from_bytes would or if slice is not 33 bytes long.

pub fn from_bytes_uncompressed(bytes: [u8; 65]) -> Option<Self>

Creates a Point from a 65-byte uncompressed encoding specified in Standards for Efficient Cryptography. The first byte must be 0x04. The remaining 64 bytes must encode a valid x and y coordinate on the curve. If the conditions are not met then it will return None.

pub fn random(rng: &mut impl RngCore + CryptoRng) -> Self

Samples a point uniformly from the group.

Examples

Generate a random point from thread_rng.

let random_point = Point::random(&mut rand::thread_rng());

impl<T, S> Point<T, S, NonZero>

pub fn into_point_with_even_y(self) -> (Point<EvenY, S, NonZero>, bool)

Converts this point into the point with the same x-coordinate but with an even y-coordinate. Returns a Point marked EvenY with a bool indicating whether the point had to be negated to make its y-coordinate even.

Examples

use secp256kfun::{marker::*, Point};
let point = Point::random(&mut rand::thread_rng());
let (point_with_even_y, was_odd) = point.clone().into_point_with_even_y();

impl Point<EvenY, Public, NonZero>

pub fn from_scalar_mul(
    base: &Point<impl PointType, impl Secrecy>,
    scalar: &mut Scalar<impl Secrecy>
) -> Self

Multiplies base by scalar and returns the resulting point. If the resulting point does not have an even y-coordinate then the scalar and point are negated so the point has an even y-coordinate and the scalar matches it.

Examples

use secp256kfun::{marker::*, Point, Scalar, G};
let mut secret_key = Scalar::random(&mut rand::thread_rng());
let public_key = Point::<EvenY>::from_scalar_mul(G, &mut secret_key);
assert!(public_key.is_y_even());

impl<T, S, Z> Point<T, S, Z>

pub fn is_zero(&self) -> bool

Returns true if this point the [identity element] of the group A.K.A. the point at infinity.

Examples

let point = Point::random(&mut rand::thread_rng());
assert!(!point.is_zero());
assert!(g!(0 * point).is_zero());

pub fn conditional_negate(&self, cond: bool) -> Point<T::NegationType, S, Z> where
    T: PointType, 

Negates a point based on a condition. If cond is true the value returned is the negation of the point, otherwise it will be the point.

pub fn set_secrecy<SNew>(self) -> Point<T, SNew, Z>

A hack that is necessary when writing deserialization code until rust issue #44491 is fixed. Don’t use this method use mark which checks the type is a valid secrecy.

impl Point<Normal, Public, Zero>

pub fn zero() -> Self

Returns the [identity element] of the group A.K.A. the point at infinity.

Example

use secp256kfun::{g, Point, G};
assert!(Point::zero().is_zero());
assert_eq!(g!({ Point::zero() } + G), *G);

impl<Z, T> Point<T, Public, Z>

pub fn x_eq_scalar<Z2>(&self, scalar: &Scalar<Public, Z2>) -> bool

Checks if this point’s x-coordiante is the equal to the scalar mod the curve order. This is only useful for ECDSA implementations.

impl<S, T: Normalized> Point<T, S, NonZero>

pub fn coordinates(&self) -> ([u8; 32], [u8; 32])

Returns the x and y coordinates of the point as two 32-byte arrays containing their big endian encoding.

Example

let point = Point::random(&mut rand::thread_rng());
let (x_coord, y_coord) = point.coordinates();

pub fn to_bytes(&self) -> [u8; 33]

Converts the point to its compressed encoding as specified by Standards for Efficient Cryptography.

Example

Round trip serialization with from_bytes

let point = Point::random(&mut rand::thread_rng());
let bytes = point.to_bytes();
assert!(bytes[0] == 0x02 || bytes[0] == 0x03);
assert_eq!(Point::from_bytes(bytes).unwrap(), point);

pub fn to_bytes_uncompressed(&self) -> [u8; 65]

Encodes a point as its compressed encoding as specified by Standards for Efficient Cryptography.

Example

use secp256kfun::Point;
let point = Point::random(&mut rand::thread_rng());
let bytes = point.to_bytes_uncompressed();
assert_eq!(Point::from_bytes_uncompressed(bytes).unwrap(), point);

pub fn to_xonly(&self) -> XOnly

Converts a point to an XOnly (i.e. just its x-coordinate).

Example

use secp256kfun::{marker::*, Point};
let (point_even_y, _) = Point::random(&mut rand::thread_rng()).into_point_with_even_y();
let xonly = point_even_y.to_xonly();
assert_eq!(xonly.to_point(), point_even_y);

pub fn is_y_even(&self) -> bool

Returns whether the point has an even y-coordinate

Trait Implementations

impl<Z, S, T> ChangeMark<Point<T, S, Z>> for NonZero

type Out = Option<Point<T, S, NonZero>>

The result type of marking T with Self

fn change_mark(point: Point<T, S, Z>) -> Self::Out

Marks item with Self.

impl<T, S, Z> ChangeMark<Point<T, S, Z>> for Normal

type Out = Point<Normal, S, Z>

The result type of marking T with Self

fn change_mark(point: Point<T, S, Z>) -> Self::Out

Marks item with Self.

impl<Z, S, T> ChangeMark<Point<T, S, Z>> for Jacobian

type Out = Point<Jacobian, S, Z>

The result type of marking T with Self

fn change_mark(point: Point<T, S, Z>) -> Self::Out

Marks item with Self.

impl<Z, S, Y> ChangeMark<Point<Y, S, Z>> for Zero

type Out = Point<Y, S, Zero>

The result type of marking T with Self

fn change_mark(point: Point<Y, S, Z>) -> Self::Out

Marks item with Self.

impl<Z, S, Y, SNew: Secrecy> ChangeMark<Point<Y, S, Z>> for SNew

type Out = Point<Y, SNew, Z>

The result type of marking T with Self

fn change_mark(point: Point<Y, S, Z>) -> Self::Out

Marks item with Self.

impl<Z, S, T: Clone> Clone for Point<T, S, Z>

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T: Default, S, Z> ConditionallySelectable for Point<T, S, Z> where
    Self: Copy, 

fn conditional_select(a: &Self, b: &Self, choice: Choice) -> Self

Select a or b according to choice.

fn conditional_assign(&mut self, other: &Self, choice: Choice)

Conditionally assign other to self, according to choice.

fn conditional_swap(a: &mut Self, b: &mut Self, choice: Choice)

Conditionally swap self and other if choice == 1; otherwise, reassign both unto themselves.

impl<T: PointType, S, Z> Debug for Point<T, S, Z>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the type as hex and any markers on the type.

impl<T: Default, S: Default, Z: Default> Default for Point<T, S, Z>

fn default() -> Point<T, S, Z>

Returns the “default value” for a type.

impl<'de, S> Deserialize<'de> for Point<EvenY, S, NonZero>

fn deserialize<Deser: Deserializer<'de>>(
    deserializer: Deser
) -> Result<Point<EvenY, S, NonZero>, Deser::Error>

Deserialize this value from the given Serde deserializer.

impl<'de, S> Deserialize<'de> for Point<Normal, S, NonZero>

fn deserialize<Deser: Deserializer<'de>>(
    deserializer: Deser
) -> Result<Point<Normal, S, NonZero>, Deser::Error>

Deserialize this value from the given Serde deserializer.

impl<S> Display for Point<Normal, S, NonZero>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Displays as hex.

impl<S> Display for Point<EvenY, S, NonZero>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Displays as hex.

impl<T: Normalized> From<Point<T, Public, NonZero>> for PublicKey

fn from(pk: Point<T>) -> Self

Performs the conversion.

impl From<PublicKey> for Point

fn from(pk: PublicKey) -> Self

Performs the conversion.

impl From<XOnly> for Point<EvenY, Public, NonZero>

fn from(xonly: XOnly) -> Self

Performs the conversion.

impl<S> FromStr for Point<EvenY, S, NonZero>

fn from_str(hex: &str) -> Result<Point<EvenY, S, NonZero>, HexError>

Parses the string as hex and interprets tries to convert the resulting byte array into the desired value.

type Err = HexError

The associated error which can be returned from parsing.

impl<S> FromStr for Point<Normal, S, NonZero>

fn from_str(hex: &str) -> Result<Point<Normal, S, NonZero>, HexError>

Parses the string as hex and interprets tries to convert the resulting byte array into the desired value.

type Err = HexError

The associated error which can be returned from parsing.

impl<T: Normalized> Hash for Point<T, Public, NonZero>

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given Hasher.

impl<T: Normalized, S> HashInto for Point<T, S, NonZero>

fn hash_into(&self, hash: &mut impl Digest)

Asks the item to convert itself to bytes and add itself to hash.

impl<T: PointType, S, Z> Neg for Point<T, S, Z>

type Output = Point<T::NegationType, S, Z>

The resulting type after applying the - operator.

fn neg(self) -> Self::Output

Performs the unary - operation.

impl<T: PointType, S, Z> Neg for &Point<T, S, Z>

type Output = Point<T::NegationType, S, Z>

The resulting type after applying the - operator.

fn neg(self) -> Self::Output

Performs the unary - operation.

impl<T, Z, S> PartialEq<Point<T, S, Z>> for XOnly

fn eq(&self, rhs: &Point<T, S, Z>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<T1, S1, Z1, T2, S2, Z2> PartialEq<Point<T2, S2, Z2>> for Point<T1, S1, Z1>

fn eq(&self, rhs: &Point<T2, S2, Z2>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<T, Z, S> PartialEq<XOnly> for Point<T, S, Z>

fn eq(&self, rhs: &XOnly) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<S> Serialize for Point<Normal, S, NonZero>

fn serialize<Ser: Serializer>(
    &self,
    serializer: Ser
) -> Result<Ser::Ok, Ser::Error>

Serialize this value into the given Serde serializer.

impl<S> Serialize for Point<EvenY, S, NonZero>

fn serialize<Ser: Serializer>(
    &self,
    serializer: Ser
) -> Result<Ser::Ok, Ser::Error>

Serialize this value into the given Serde serializer.

impl<T: Copy, Z: Copy> Copy for Point<T, Public, Z>

impl<T, S, Z> Eq for Point<T, S, Z>