mina_signer/
pubkey.rs

1//! Public key structures and algorithms
2//!
3//! Definition of public key structure and helpers
4
5extern crate alloc;
6
7use crate::{BaseField, CurvePoint, ScalarField, SecKey};
8use alloc::{string::String, vec, vec::Vec};
9use ark_ec::{short_weierstrass::Affine, AffineRepr, CurveGroup};
10use ark_ff::{BigInteger, PrimeField, Zero};
11use bs58;
12use core::{
13    fmt,
14    ops::{Mul, Neg},
15};
16use o1_utils::FieldHelpers;
17use sha2::{Digest, Sha256};
18use thiserror::Error;
19
20/// Public key errors
21#[derive(Error, Debug, Clone, PartialEq, Eq)]
22pub enum PubKeyError {
23    /// Invalid address length
24    #[error("invalid address length")]
25    AddressLength,
26    /// Invalid address base58
27    #[error("invalid address base58")]
28    AddressBase58,
29    /// Invalid raw address bytes length
30    #[error("invalid raw address bytes length")]
31    AddressRawByteLength,
32    /// Invalid address checksum
33    #[error("invalid address checksum")]
34    AddressChecksum,
35    /// Invalid address version
36    #[error("invalid address version")]
37    AddressVersion,
38    /// Invalid x-coordinate bytes
39    #[error("invalid x-coordinate bytes")]
40    XCoordinateBytes,
41    /// Invalid x-coordinate
42    #[error("invalid x-coordinate")]
43    XCoordinate,
44    /// Point not on curve
45    #[error("point not on curve")]
46    YCoordinateBytes,
47    /// Invalid y-coordinate
48    #[error("invalid y-coordinate bytes")]
49    YCoordinateParityBytes,
50    /// Invalid y-coordinate parity
51    #[error("invalid y-coordinate parity bytes")]
52    YCoordinateParity,
53    /// Invalid y-coordinate parity
54    #[error("invalid y-coordinate parity")]
55    NonCurvePoint,
56    /// Invalid hex
57    #[error("invalid public key hex")]
58    Hex,
59    /// Invalid secret key
60    #[error("invalid secret key")]
61    SecKey,
62}
63/// Public key Result
64pub type Result<T> = core::result::Result<T, PubKeyError>;
65
66/// Length of Mina addresses
67pub const MINA_ADDRESS_LEN: usize = 55;
68const MINA_ADDRESS_RAW_LEN: usize = 40;
69
70/// Public key
71#[derive(Clone, Debug, PartialEq, Eq)]
72pub struct PubKey(CurvePoint);
73
74impl PubKey {
75    /// Create public key from curve point
76    /// Note: Does not check point is on curve
77    #[allow(clippy::needless_pass_by_value)]
78    #[must_use]
79    pub const fn from_point_unsafe(point: CurvePoint) -> Self {
80        Self(point)
81    }
82
83    /// Deserialize public key from bytes
84    /// # Errors
85    ///
86    /// Will give error if `bytes` do not match certain requirements.
87    pub fn from_bytes(bytes: &[u8]) -> Result<Self> {
88        if bytes.len() != BaseField::size_in_bytes() * 2 {
89            return Err(PubKeyError::YCoordinateBytes);
90        }
91        let x = BaseField::from_bytes(&bytes[0..BaseField::size_in_bytes()])
92            .map_err(|_| PubKeyError::XCoordinateBytes)?;
93        let y = BaseField::from_bytes(&bytes[BaseField::size_in_bytes()..])
94            .map_err(|_| PubKeyError::YCoordinateBytes)?;
95        let pt = CurvePoint::get_point_from_x_unchecked(x, y.0.is_odd())
96            .ok_or(PubKeyError::XCoordinate)?;
97        if pt.y != y {
98            return Err(PubKeyError::NonCurvePoint);
99        }
100
101        let public = Affine {
102            x,
103            y,
104            infinity: pt.infinity,
105        };
106        if !public.is_on_curve() {
107            return Err(PubKeyError::NonCurvePoint);
108        }
109
110        // Safe now because we checked point is on the curve
111        Ok(Self::from_point_unsafe(public))
112    }
113
114    /// Deserialize public key from hex
115    ///
116    /// # Errors
117    ///
118    /// Will give error if `hex` string does not match certain requirements.
119    pub fn from_hex(public_hex: &str) -> Result<Self> {
120        let bytes: Vec<u8> = hex::decode(public_hex).map_err(|_| PubKeyError::Hex)?;
121        Self::from_bytes(&bytes)
122    }
123
124    /// Create public key from a secret key
125    ///
126    /// # Errors
127    ///
128    /// Returns [`PubKeyError::SecKey`] if the scalar is zero, or
129    /// [`PubKeyError::NonCurvePoint`] if the derived point is not on the curve.
130    pub fn from_secret_key(secret_key: &SecKey) -> Result<Self> {
131        if *secret_key.scalar() == ScalarField::zero() {
132            return Err(PubKeyError::SecKey);
133        }
134        let pt = CurvePoint::generator()
135            .mul(*secret_key.scalar())
136            .into_affine();
137        if !pt.is_on_curve() {
138            return Err(PubKeyError::NonCurvePoint);
139        }
140        Ok(Self::from_point_unsafe(pt))
141    }
142
143    /// Deserialize Mina address into public key
144    ///
145    /// # Errors
146    ///
147    /// Will give error if `address` string does not match certain requirements.
148    pub fn from_address(address: &str) -> Result<Self> {
149        if address.len() != MINA_ADDRESS_LEN {
150            return Err(PubKeyError::AddressLength);
151        }
152
153        let bytes = bs58::decode(address)
154            .into_vec()
155            .map_err(|_| PubKeyError::AddressBase58)?;
156
157        if bytes.len() != MINA_ADDRESS_RAW_LEN {
158            return Err(PubKeyError::AddressRawByteLength);
159        }
160
161        let (raw, checksum) = (&bytes[..bytes.len() - 4], &bytes[bytes.len() - 4..]);
162        let hash = Sha256::digest(&Sha256::digest(raw)[..]);
163        if checksum != &hash[..4] {
164            return Err(PubKeyError::AddressChecksum);
165        }
166
167        let (version, x_bytes, y_parity) = (
168            &raw[..3],
169            &raw[3..bytes.len() - 5],
170            raw[bytes.len() - 5] == 0x01,
171        );
172        if version != [0xcb, 0x01, 0x01] {
173            return Err(PubKeyError::AddressVersion);
174        }
175
176        let x = BaseField::from_bytes(x_bytes).map_err(|_| PubKeyError::XCoordinateBytes)?;
177        let mut pt =
178            CurvePoint::get_point_from_x_unchecked(x, y_parity).ok_or(PubKeyError::XCoordinate)?;
179
180        if pt.y.into_bigint().is_even() == y_parity {
181            pt.y = pt.y.neg();
182        }
183
184        if !pt.is_on_curve() {
185            return Err(PubKeyError::NonCurvePoint);
186        }
187
188        // Safe now because we checked point pt is on curve
189        Ok(Self::from_point_unsafe(pt))
190    }
191
192    /// Borrow public key as curve point
193    pub const fn point(&self) -> &CurvePoint {
194        &self.0
195    }
196
197    /// Convert public key into curve point
198    pub const fn into_point(self) -> CurvePoint {
199        self.0
200    }
201
202    /// Convert public key into compressed public key
203    #[must_use]
204    pub fn into_compressed(&self) -> CompressedPubKey {
205        let point = self.0;
206        CompressedPubKey {
207            x: point.x,
208            is_odd: point.y.into_bigint().is_odd(),
209        }
210    }
211
212    /// Serialize public key into corresponding Mina address
213    #[must_use]
214    pub fn into_address(&self) -> String {
215        let point = self.point();
216        into_address(&point.x, point.y.into_bigint().is_odd())
217    }
218
219    /// Deserialize public key into bytes
220    ///
221    /// # Panics
222    ///
223    /// Panics if the field element byte conversion fails.
224    #[must_use]
225    pub fn to_bytes(&self) -> Vec<u8> {
226        let point = self.point();
227        [point.x.to_bytes(), point.y.to_bytes()].concat()
228    }
229
230    /// Deserialize public key into hex
231    ///
232    /// # Panics
233    ///
234    /// Panics if the field element byte conversion fails.
235    #[must_use]
236    pub fn to_hex(&self) -> String {
237        let point = self.point();
238        point.x.to_hex() + point.y.to_hex().as_str()
239    }
240}
241
242impl fmt::Display for PubKey {
243    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
244        write!(f, "{}", self.to_hex())
245    }
246}
247
248/// Compressed public keys consist of x-coordinate and y-coordinate parity.
249#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord)]
250pub struct CompressedPubKey {
251    /// X-coordinate
252    pub x: BaseField,
253
254    /// Parity of y-coordinate
255    pub is_odd: bool,
256}
257
258fn into_address(x: &BaseField, is_odd: bool) -> String {
259    let mut raw: Vec<u8> = vec![
260        0xcb, // version for base58 check
261        0x01, // non_zero_curve_point version
262        0x01, // compressed_poly version
263    ];
264
265    // pub key x-coordinate
266    raw.extend(x.to_bytes());
267
268    // pub key y-coordinate parity
269    raw.push(u8::from(is_odd));
270
271    // 4-byte checksum
272    let hash = Sha256::digest(&Sha256::digest(&raw[..])[..]);
273    raw.extend(&hash[..4]);
274
275    // The raw buffer is MINA_ADDRESS_RAW_LEN (= 40) bytes in length
276    bs58::encode(raw).into_string()
277}
278
279impl CompressedPubKey {
280    /// Serialize compressed public key into corresponding Mina address
281    #[must_use]
282    pub fn into_address(&self) -> String {
283        into_address(&self.x, self.is_odd)
284    }
285
286    /// Deserialize compressed public key from bytes
287    /// # Errors
288    ///
289    /// Will give error if `bytes` do not match certain requirements.
290    pub fn from_bytes(bytes: &[u8]) -> Result<Self> {
291        let x = BaseField::from_bytes(&bytes[0..BaseField::size_in_bytes()])
292            .map_err(|_| PubKeyError::XCoordinateBytes)?;
293        let parity_bytes = &bytes[BaseField::size_in_bytes()..];
294        if parity_bytes.len() != 1 {
295            return Err(PubKeyError::YCoordinateParityBytes);
296        }
297        let is_odd = if parity_bytes[0] == 0x01 {
298            true // Odd
299        } else if parity_bytes[0] == 0x00 {
300            false // Even
301        } else {
302            return Err(PubKeyError::YCoordinateParity);
303        };
304        let public =
305            CurvePoint::get_point_from_x_unchecked(x, is_odd).ok_or(PubKeyError::XCoordinate)?;
306        if !public.is_on_curve() {
307            return Err(PubKeyError::NonCurvePoint);
308        }
309
310        // Safe now because we checked point is on the curve
311        Ok(Self { x, is_odd })
312    }
313
314    /// Deserialize compressed public key from hex
315    ///
316    /// # Errors
317    ///
318    /// Will give error if `hex` string does not match certain requirements.
319    pub fn from_hex(public_hex: &str) -> Result<Self> {
320        let bytes: Vec<u8> = hex::decode(public_hex).map_err(|_| PubKeyError::Hex)?;
321        Self::from_bytes(&bytes)
322    }
323
324    /// Create compressed public key from a secret key
325    #[must_use]
326    pub fn from_secret_key(sec_key: SecKey) -> Self {
327        // We do not need to check point is on the curve, since it's derived
328        // directly from the generator point
329        let public = PubKey::from_point_unsafe(
330            CurvePoint::generator()
331                .mul(sec_key.into_scalar())
332                .into_affine(),
333        );
334        public.into_compressed()
335    }
336
337    /// Deserialize Mina address into compressed public key (via an uncompressed
338    /// `PubKey`)
339    ///
340    /// # Errors
341    ///
342    /// Will give error if `PubKey::from_address()` returns error.
343    pub fn from_address(address: &str) -> Result<Self> {
344        Ok(PubKey::from_address(address)?.into_compressed())
345    }
346
347    /// The empty [`CompressedPubKey`] value that is used as `public_key` in
348    /// empty account and `None` value for calculating the hash of
349    /// `Option<CompressedPubKey>`, etc.
350    #[must_use]
351    pub fn empty() -> Self {
352        Self {
353            x: BaseField::zero(),
354            is_odd: false,
355        }
356    }
357
358    /// Deserialize compressed public key into bytes
359    #[must_use]
360    pub fn to_bytes(&self) -> Vec<u8> {
361        let x_bytes = self.x.to_bytes();
362        let is_odd_bytes = vec![u8::from(self.is_odd)];
363        [x_bytes, is_odd_bytes].concat()
364    }
365
366    /// Deserialize compressed public key into hex
367    #[must_use]
368    pub fn to_hex(&self) -> String {
369        hex::encode(self.to_bytes())
370    }
371}
mina_signer/pubkey.rs

mina_signer/
pubkey.rs
