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/SquareY 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.

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_y_choice<Y: YChoice>(
    self
) -> (Point<Y, S, NonZero>, bool)

Converts this point into the point with the same x-coordinate but with the y-coordinate with the desired YChoice property. The point is marked appropriately and is returned with a bool indicating whether the point had to be negated to achieve the constraint on YChoice.

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_y_choice::<EvenY>();
let (point_with_square_y, was_not_square) = point.into_point_with_y_choice::<SquareY>();

impl<Y: YChoice> Point<Y, 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 match the YChoice of the invocant type, then the scalar and point are negated so they comply.

Examples

Ensure a public_key is even is the even version of the point and potentially negate its corresponding secret_key to match.

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);

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());

#[must_use]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<T::YType>

Converts a point to an XOnly (i.e. just its x-coordinate). The resulting XOnly will inherit the point type of the invocant if it is a YChoice. Otherwise it will just be marked with ().

Example

use secp256kfun::{marker::*, Point};
let (point_even_y, _) =
    Point::random(&mut rand::thread_rng()).into_point_with_y_choice::<EvenY>();
let xonly = point_even_y.to_xonly();
assert!(format!("{:?}", xonly).starts_with("XOnly<EvenY>"));

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<S, Z> Debug for Point<Jacobian, S, Z>

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

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

impl<T: Normalized, 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, T: YChoice> Deserialize<'de> for Point<T, S, NonZero>

fn deserialize<Deser: Deserializer<'de>>(
    deserializer: Deser
) -> Result<Point<T, 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, Z> Display for Point<Jacobian, S, Z>

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

Displays as hex.

impl<T: Normalized, S, Z> Display for Point<T, S, Z>

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

Displays as hex.

impl<Y: YChoice> From<XOnly<Y>> for Point<Y, Public, NonZero>

fn from(xonly: XOnly<Y>) -> Self

Performs the conversion.

impl<S, T: YChoice> FromStr for Point<T, S, NonZero>

type Err = HexError

The associated error which can be returned from parsing.

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

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

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

type Err = HexError

The associated error which can be returned from parsing.

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.

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<SquareY>

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

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

#[must_use]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 ==.

#[must_use]fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

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

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

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

#[must_use]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, T: YChoice> Serialize for Point<T, S, NonZero>

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

Serialize this value into the given Serde serializer.