Struct secp256kfun::Point

pub struct Point<T = Normal, S = Public, Z = NonZero>(/* private fields */);

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 normalized (i.e. T ≠ NonNormal) can be serialized. A Point that is EvenY points serialize to and from their 32-byte x-only representation. Normal points serialize to and from the standard 33-byte representation specified in Standards for Efficient Cryptography (the same as Point::to_bytes). Points that are are zero (see is_zero) will serialize to [0u8;33].

Implementations

impl Point<Normal, Public, NonZero>

pub fn random(rng: &mut impl RngCore) -> 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());

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.

impl<Z: ZeroChoice, S> Point<Normal, S, Z>

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::{marker::*, 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::<_, Public, NonZero>::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.

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

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

where T: PointType,

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

pub fn generator() -> Self

where T: Default,

Returns the generator point G defined in Standards for Efficient Cryptography.

This is sometimes more useful than just using secp256kfun::G since it allows the compiler to infer types.

Examples

use secp256kfun::{marker::*, Point, G};
assert_eq!(Point::<Normal, Public, _>::generator(), *G);

impl Point<EvenY, Public, NonZero>

pub fn even_y_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::even_y_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>

Set the Secrecy of the point.

pub fn public(self) -> Point<T, Public, Z>

Set the Secrecy of the point to Public.

Note that points are by default Public.

pub fn secret(self) -> Point<T, Secret, Z>

Set the Secrecy of the point to Secret.

pub fn normalize(self) -> Point<Normal, S, Z>

where T: PointType,

Normalize a point.

This is usually only useful to do if the Point is marked as NonNormal. Otherwise it will be no-op and just set the PointType to Normal.

pub fn non_normal(self) -> Point<NonNormal, S, Z>

Mark the point as being NonNormal.

This is sometimes helpful when you have an accumulater variable where although the first value of the point is normalized the subsequent values will not be so to satisfy the compiler you have to set it to NonNormal before you start.

pub fn mark_zero(self) -> Point<T, S, Zero>

Mark the point as possibly being Zero (even though it isn’t).

This is useful in accumulator variables where although the initial value is non-zero, every sum addition after that might make it zero so it’s necessary to start off with Zero marked point.

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, Z, T: Normalized> Point<T, S, Z>

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

use secp256kfun::{marker::*, Point};
let point = Point::random(&mut rand::thread_rng());
let bytes = point.to_bytes();
assert!(bytes[0] == 0x02 || bytes[0] == 0x03);
assert_eq!(
    Point::<_, Public, NonZero>::from_bytes(bytes).unwrap(),
    point
);

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

pub fn from_xonly_bytes(bytes: [u8; 32]) -> Option<Self>

Creates a point with EvenY from 32 byte x-coordinate

impl<T, S> Point<T, S, Zero>

pub fn non_zero(self) -> Option<Point<T, S, NonZero>>

Convert a point that is marked as Zero to NonZero.

If the point was actually zero (is_zero returns true) it returns None.

pub fn zero() -> Self

where T: Default,

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

Example

use secp256kfun::{g, marker::*, s, Point, G};
let zero = Point::<Normal, Public, _>::zero();
assert!(zero.is_zero());
assert_eq!(g!(zero + G), *G);
assert_eq!(zero, g!(0 * G))

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 is_y_even(&self) -> bool

Returns whether the point has an even y-coordinate

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

Serializes a point with EvenY to its 32-byte x-coordinate

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::{marker::*, Point};
let point = Point::random(&mut rand::thread_rng());
let bytes = point.to_bytes_uncompressed();
assert_eq!(Point::from_bytes_uncompressed(bytes).unwrap(), point);

Trait Implementations

impl<TR, SL, SR, ZR> AddAssign<&Point<TR, SR, ZR>> for Point<NonNormal, SL, Zero>

fn add_assign(&mut self, rhs: &Point<TR, SR, ZR>)

Performs the += operation.

impl<TR, SL, SR, ZR> AddAssign<Point<TR, SR, ZR>> for Point<NonNormal, SL, Zero>

fn add_assign(&mut self, rhs: Point<TR, SR, ZR>)

Performs the += operation.

impl<S: Secrecy> Arbitrary for Point<EvenY, S, NonZero>

type Parameters = ()

The type of parameters that arbitrary_with accepts for configuration of the generated Strategy. Parameters must implement Default.

type Strategy = BoxedStrategy<Point<EvenY, S>>

The type of Strategy used to generate values of type Self.

fn arbitrary_with(_: Self::Parameters) -> Self::Strategy

Generates a Strategy for producing arbitrary values of type the implementing type (Self). The strategy is passed the arguments given in args.

fn arbitrary() -> Self::Strategy

Generates a Strategy for producing arbitrary values of type the implementing type (Self).

impl<S: Secrecy> Arbitrary for Point<NonNormal, S, NonZero>

type Parameters = ()

The type of parameters that arbitrary_with accepts for configuration of the generated Strategy. Parameters must implement Default.

type Strategy = BoxedStrategy<Point<NonNormal, S>>

The type of Strategy used to generate values of type Self.

fn arbitrary_with(_: Self::Parameters) -> Self::Strategy

Generates a Strategy for producing arbitrary values of type the implementing type (Self). The strategy is passed the arguments given in args.

fn arbitrary() -> Self::Strategy

Generates a Strategy for producing arbitrary values of type the implementing type (Self).

impl<S: Secrecy> Arbitrary for Point<NonNormal, S, Zero>

type Parameters = ()

The type of parameters that arbitrary_with accepts for configuration of the generated Strategy. Parameters must implement Default.

type Strategy = BoxedStrategy<Point<NonNormal, S, Zero>>

The type of Strategy used to generate values of type Self.

fn arbitrary_with(_: Self::Parameters) -> Self::Strategy

Generates a Strategy for producing arbitrary values of type the implementing type (Self). The strategy is passed the arguments given in args.

fn arbitrary() -> Self::Strategy

Generates a Strategy for producing arbitrary values of type the implementing type (Self).

impl<S: Secrecy> Arbitrary for Point<Normal, S, NonZero>

type Parameters = ()

The type of parameters that arbitrary_with accepts for configuration of the generated Strategy. Parameters must implement Default.

type Strategy = BoxedStrategy<Point<Normal, S>>

The type of Strategy used to generate values of type Self.

fn arbitrary_with(_: Self::Parameters) -> Self::Strategy

Generates a Strategy for producing arbitrary values of type the implementing type (Self). The strategy is passed the arguments given in args.

fn arbitrary() -> Self::Strategy

Generates a Strategy for producing arbitrary values of type the implementing type (Self).

impl<S: Secrecy> Arbitrary for Point<Normal, S, Zero>

type Parameters = ()

The type of parameters that arbitrary_with accepts for configuration of the generated Strategy. Parameters must implement Default.

type Strategy = BoxedStrategy<Point<Normal, S, Zero>>

The type of Strategy used to generate values of type Self.

fn arbitrary_with(_: Self::Parameters) -> Self::Strategy

Generates a Strategy for producing arbitrary values of type the implementing type (Self). The strategy is passed the arguments given in args.

fn arbitrary() -> Self::Strategy

Generates a Strategy for producing arbitrary values of type the implementing type (Self).

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

Available on crate feature bincode only.

fn borrow_decode<D: BorrowDecoder<'de>>( decoder: &mut D ) -> Result<Self, DecodeError>

Attempt to decode this type with the given BorrowDecode.

impl<'de, S, Z: ZeroChoice> BorrowDecode<'de> for Point<Normal, S, Z>

Available on crate feature bincode only.

fn borrow_decode<D: BorrowDecoder<'de>>( decoder: &mut D ) -> Result<Self, DecodeError>

Attempt to decode this type with the given BorrowDecode.

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, 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<S> Decode for Point<EvenY, S, NonZero>

Available on crate feature bincode only.

fn decode<D: Decoder>(decoder: &mut D) -> Result<Self, DecodeError>

Attempt to decode this type with the given Decode.

impl<S, Z: ZeroChoice> Decode for Point<Normal, S, Z>

Available on crate feature bincode only.

fn decode<D: Decoder>(decoder: &mut D) -> Result<Self, DecodeError>

Attempt to decode this type with the given Decode.

impl<T: Default + PointType, S> Default for Point<T, S, NonZero>

The default for Point<,,Zero> is [Point::generator`].

fn default() -> Self

Returns the “default value” for a type.

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

The default for Point<,,Zero> is [Point::zero`].

fn default() -> Self

Returns the “default value” for a type.

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

Available on crate feature serde only.

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, Z: ZeroChoice> Deserialize<'de> for Point<Normal, S, Z>

Available on crate feature serde only.

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

Deserialize this value from the given Serde deserializer.

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

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

Displays as hex.

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

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

Displays as hex.

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

Available on crate feature bincode only.

fn encode<E: Encoder>(&self, encoder: &mut E) -> Result<(), EncodeError>

Encode a given type.

impl<S, Z> Encode for Point<Normal, S, Z>

Available on crate feature bincode only.

fn encode<E: Encoder>(&self, encoder: &mut E) -> Result<(), EncodeError>

Encode a given type.

impl From<Point<EvenY>> for XOnlyPublicKey

fn from(point: Point<EvenY>) -> Self

Converts to this type from the input type.

impl From<Point<EvenY>> for XOnlyPublicKey

fn from(point: Point<EvenY>) -> Self

Converts to this type from the input type.

impl From<Point> for PublicKey

fn from(pk: Point) -> Self

Converts to this type from the input type.

impl From<Point> for PublicKey

fn from(pk: Point) -> Self

Converts to this type from the input type.

impl From<PublicKey> for Point

fn from(pk: PublicKey) -> Self

Converts to this type from the input type.

impl From<PublicKey> for Point

fn from(pk: PublicKey) -> Self

Converts to this type from the input type.

impl From<XOnlyPublicKey> for Point<EvenY>

fn from(pk: XOnlyPublicKey) -> Self

Converts to this type from the input type.

impl From<XOnlyPublicKey> for Point<EvenY>

fn from(pk: XOnlyPublicKey) -> Self

Converts to this type from the input type.

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, Z: ZeroChoice> FromStr for Point<Normal, S, Z>

fn from_str(hex: &str) -> Result<Point<Normal, S, Z>, 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 Hash for Point<Normal, 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, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Hash for Point<EvenY, 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, Self: Sized,

Feeds a slice of this type into the given Hasher.

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

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

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

impl<S, Z> HashInto for Point<Normal, S, Z>

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 as PointType>::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 as PointType>::NegationType, S, Z>

The resulting type after applying the - operator.

fn neg(self) -> Self::Output

Performs the unary - operation.

impl<T1: Normalized, Z1> Ord for Point<T1, Public, Z1>

fn cmp(&self, other: &Point<T1, Public, Z1>) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized + PartialOrd,

Restrict a value to a certain interval.

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

where T1: PointType, T2: PointType,

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 !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T1: Normalized, Z1, T2: Normalized, Z2> PartialOrd<Point<T2, Public, Z2>> for Point<T1, Public, Z1>

fn partial_cmp(&self, other: &Point<T2, Public, Z2>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

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

This method tests less than (for self and other) and is used by the < operator.

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

This method tests less than or equal to (for self and other) and is used by the <= operator.

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

This method tests greater than (for self and other) and is used by the > operator.

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

This method tests greater than or equal to (for self and other) and is used by the >= operator.

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

Available on crate feature serde only.

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

Serialize this value into the given Serde serializer.

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

Available on crate feature serde only.

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

Serialize this value into the given Serde serializer.

impl<TR, SL, SR, ZR> SubAssign<&Point<TR, SR, ZR>> for Point<NonNormal, SL, Zero>

fn sub_assign(&mut self, rhs: &Point<TR, SR, ZR>)

Performs the -= operation.

impl<TR, SL, SR, ZR> SubAssign<Point<TR, SR, ZR>> for Point<NonNormal, SL, Zero>

fn sub_assign(&mut self, rhs: Point<TR, SR, ZR>)

Performs the -= operation.

impl<S: Secrecy> Sum for Point<NonNormal, S, Zero>

fn sum<I: Iterator<Item = Self>>(iter: I) -> Self

Method which takes an iterator and generates Self from the elements by “summing up” the items.

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

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