From 19289547261e6f43da549ae6d176fd4fc59386de Mon Sep 17 00:00:00 2001 From: aritkulova <94910987+aritkulova@users.noreply.github.com> Date: Tue, 27 May 2025 15:07:02 +0300 Subject: [PATCH 1/4] added docs for schnorr signature and ec256 libraries --- docs/getting-started/Overview.md | 4 +- .../guides/libs/crypto/ec256.md | 550 ++++++++++++++++++ .../guides/libs/crypto/schnorr256.md | 90 +++ 3 files changed, 643 insertions(+), 1 deletion(-) create mode 100644 docs/getting-started/guides/libs/crypto/ec256.md create mode 100644 docs/getting-started/guides/libs/crypto/schnorr256.md diff --git a/docs/getting-started/Overview.md b/docs/getting-started/Overview.md index b84e3d6..1bc231b 100644 --- a/docs/getting-started/Overview.md +++ b/docs/getting-started/Overview.md @@ -44,10 +44,12 @@ contracts │ ├── bn │ │ └── U512 — "A hyperoptimized uint512 implementation" │ ├── crypto + ├── EC256 — "Elliptic curve arithmetic over a 256-bit prime field" │ │ ├── ECDSA256 — "ECDSA verification over any 256-bit curves" │ │ ├── ECDSA384 — "ECDSA verification over any 384-bit curves" │ │ ├── ECDSA512 — "ECDSA verification over any 512-bit curves" -│ │ └── RSASSAPSS — "RSASSA-PSS verification with MGF1" +│ │ ├── RSASSAPSS — "RSASSA-PSS verification with MGF1" +│ │ └── Schnorr256 — "Schnorr signature verification over any 256-bit curve" │ ├── data—structures │ │ ├── AvlTree — "AVL tree implementation with an iterator traversal" │ │ ├── CartesianMerkleTree — "CMT reference implementation" diff --git a/docs/getting-started/guides/libs/crypto/ec256.md b/docs/getting-started/guides/libs/crypto/ec256.md new file mode 100644 index 0000000..8dea6ab --- /dev/null +++ b/docs/getting-started/guides/libs/crypto/ec256.md @@ -0,0 +1,550 @@ +# 🧮 EC256 + +## Introduction + +This library provides elliptic curve arithmetic over a 256-bit prime field (Weierstrass curve `y^2 = x^3 + ax + b (mod p)`). + +## Functions + +To use the `EC256` library, you need to import it. + +```solidity +import "@solarity/solidity-lib/libs/crypto/EC256.sol"; +``` + +And optionally bind it to the type with the `using` statement. + +```solidity +using EC256 for *; +``` + +### basepoint + +```solidity +function basepoint( + EC256.Curve memory ec +) internal pure returns (EC256.APoint memory aPoint_); +``` + +#### Description + +Returns the generator (base) point of the curve in affine form. + +##### Parameters: + + + + + + + + + + + + + + + + +
NameTypeDescription
ecstruct EC256.CurveThe curve parameters
+ +### jbasepoint + +```solidity +function jbasepoint( + EC256.Curve memory ec +) internal pure returns (EC256.JPoint memory jPoint_); +``` + +#### Description + +Returns the generator (base) point of the curve in jacobian form. + +##### Parameters: + + + + + + + + + + + + + + + +
NameTypeDescription
ecstruct EC256.CurveThe curve parameters
+ +### toScalar + +```solidity +function toScalar( + EC256.Curve memory ec, + uint256 u256_ +) internal pure returns (uint256 scalar_); +``` + +#### Description + +Reduces an arbitrary uint256 into the scalar field [0, n). + +Returns the result of u256_ mod n. + +##### Parameters: + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
ecstruct EC256.CurveThe curve parameters
u256uint256The integer to reduce
+ +### isOnCurve + +```solidity +function isOnCurve( + EC256.Curve memory ec, + EC256.APoint memory aPoint_ +) internal pure returns (bool result_); +``` + +#### Description + +Checks whether an affine point lies on the curve. + +##### Parameters: + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
ecstruct EC256.CurveThe curve parameters
aPointstruct EC256.APointThe affine point to test
+ +### isValidScalar + +```solidity +function isValidScalar( + EC256.Curve memory ec, + uint256 scalar_ +) internal pure returns (bool result_); +``` + +#### Description + +Checks whether a scalar is in the valid range [0, n). + +##### Parameters: + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
ecstruct EC256.CurveThe curve parameters
scalaruint256The scalar to test
+ +### toAffine + +```solidity +function toAffine( + EC256.Curve memory ec, + EC256.JPoint memory jPoint_ +) internal view returns (EC256.APoint memory aPoint_); +``` + +#### Description + +Converts a point from Jacobian to affine coordinates. + +Returns the equivalent affine point (x, y). + +##### Parameters: + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
ecstruct EC256.CurveThe curve parameters
jPointstruct EC256.JPointThe Jacobian point (X, Y, Z)
+ +### toJacobian + +```solidity +function toJacobian( + EC256.APoint memory aPoint_ +) internal pure returns (EC256.JPoint memory jPoint_); +``` + +#### Description + +Converts an affine point to Jacobian coordinates. + +Returns the point in Jacobian representation (x, y, 1). + +##### Parameters: + + + + + + + + + + + + + + + +
NameTypeDescription
aPointstruct EC256.APointThe affine point (x, y)
+ +### isJacobianInfinity + +```solidity +function isJacobianInfinity( + EC256.JPoint memory jPoint_ +) internal pure returns (bool result_); +``` + +#### Description + +Checks whether a Jacobian point is the point at infinity. + +##### Parameters: + + + + + + + + + + + + + + + +
NameTypeDescription
jPointstruct EC256.JPointThe Jacobian point to test
+ +### jinfinity + +```solidity +function jinfinity() internal pure returns (EC256.JPoint memory jPoint_); +``` + +#### Description + +Returns the Jacobian representation of the point at infinity. + +Returns the point at infinity (0, 0, 0). + +### jEqual + +```solidity +function jEqual( + EC256.Curve memory ec, + EC256.JPoint memory jPoint1_, + EC256.JPoint memory jPoint2_ +) internal view returns (bool result_); +``` + +#### Description + +Compares two Jacobian points for equality in affine coordinates. + +##### Parameters: + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
ecstruct EC256.CurveThe curve parameters
jPoint1struct EC256.JPointThe first Jacobian point
jPoint2struct EC256.JPointThe second Jacobian point
+ +### jMultShamir + +```solidity +function jMultShamir( + EC256.Curve memory ec, + EC256.JPoint memory jPoint_, + uint256 scalar_ +) internal pure returns (EC256.JPoint memory jPoint2_); +``` + +#### Description + +Point multiplication: R = u*P using 4-bit windowed method. + +Returns the Jacobian representation of result point R. + +##### Parameters: + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
ecstruct EC256.CurveThe curve parameters
jPointstruct EC256.JPointTThe Jacobian point P
scalaruint256The scalar u
+ +### jMultShamir2 + +```solidity +function jMultShamir2( + EC256.Curve memory ec, + EC256.JPoint memory jPoint1_, + EC256.JPoint memory jPoint2_, + uint256 scalar1_, + uint256 scalar2_ +) internal pure returns (EC256.JPoint memory jPoint3_); +``` + +#### Description + +Simultaneous double-scalar multiplication: R = u1*P1 + u2*P2 via Strauss–Shamir. + +Returns the Jacobian representation of result point R. + +##### Parameters: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
ecstruct EC256.CurveThe curve parameters
jPoint1struct EC256.JPointThe first Jacobian point P1
jPoint2struct EC256.JPointThe second Jacobian point P2
scalar1uint256The first scalar u1
scalar2uint256The second scalar u2
+ +### jAddPoint + +```solidity +function jAddPoint( + EC256.Curve memory ec, + EC256.JPoint memory jPoint1_, + EC256.JPoint memory jPoint2_ +) internal pure returns (EC256.JPoint memory jPoint3_); +``` + +#### Description + +Adds two Jacobian points: R = P1 + P2. + +Returns the Jacobian representation of result point R. + +##### Parameters: + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
ecstruct EC256.CurveThe curve parameters
jPoint1struct EC256.JPointThe first Jacobian point P1
jPoint2struct EC256.JPointThe second Jacobian point P2
+ +### jDoublePoint + +```solidity +function jDoublePoint( + EC256.Curve memory ec, + EC256.JPoint memory jPoint1_ +) internal pure returns (EC256.JPoint memory jPoint2_); +``` + +#### Description + +Doubles a Jacobian point: R = 2*P. + +Returns the Jacobian representation of result point R. + +##### Parameters: + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
ecstruct EC256.CurveThe curve parameters
jPointstruct EC256.JPointThe Jacobian point P to double
+ +## Example + +```solidity +EC256.Curve public secp256k1CurveParams = + EC256.Curve({ + a: 0x0000000000000000000000000000000000000000000000000000000000000000, + b: 0x0000000000000000000000000000000000000000000000000000000000000007, + gx: 0x79be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798, + gy: 0x483ada7726a3c4655da4fbfc0e1108a8fd17b448a68554199c47d08ffb10d4b8, + p: 0xfffffffffffffffffffffffffffffffffffffffffffffffffffffffefffffc2f, + n: 0xfffffffffffffffffffffffffffffffebaaedce6af48a03bbfd25e8cd0364141 + }); + +function affineInfinity() external view returns (EC256.APoint memory) { + return secp256k1CurveParams.toAffine(EC256.jinfinity()); +} + +function basepoint() external view returns (EC256.APoint memory) { + return secp256k1CurveParams.basepoint(); +} +``` diff --git a/docs/getting-started/guides/libs/crypto/schnorr256.md b/docs/getting-started/guides/libs/crypto/schnorr256.md new file mode 100644 index 0000000..06c1c40 --- /dev/null +++ b/docs/getting-started/guides/libs/crypto/schnorr256.md @@ -0,0 +1,90 @@ +# 𓂃🖊 Schnorr256 + +## Introduction + +This library provides functionality for Schnorr signature verification over any 256-bit curve. + +## Functions + +To use the `Schnorr256` library, you need to import it. + +```solidity +import "@solarity/solidity-lib/libs/crypto/Schnorr256.sol"; +``` + +And optionally bind it to the type with the `using` statement. + +```solidity +using Schnorr256 for *; +``` + +### verify + +```solidity +function verify( + EC256.Curve memory ec, + bytes32 hashedMessage_, + bytes memory signature_, + bytes memory pubKey_ +) internal view returns (bool); +``` + +#### Description + +The function to verify the Schnorr signature. + +##### Parameters: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
ecstruct EC256.CurveThe 256-bit curve parameters
hashedMessagebytes32The already hashed message to be verified
signaturebytesThe Schnorr signature. Equals to bytes(R) + bytes(e)
pubKeybytesThe full public key of a signer. Equals to bytes(x) + bytes(y)
+ +#### Example + +```solidity +function verifySECP256k1( + bytes32 hashedMessage_, + bytes memory signature_, + bytes memory pubKey_ +) external view returns (bool isVerified_) { + EC256.Curve memory _secp256k1CurveParams = + EC256.Curve({ + a: 0x0000000000000000000000000000000000000000000000000000000000000000, + b: 0x0000000000000000000000000000000000000000000000000000000000000007, + gx: 0x79be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798, + gy: 0x483ada7726a3c4655da4fbfc0e1108a8fd17b448a68554199c47d08ffb10d4b8, + p: 0xfffffffffffffffffffffffffffffffffffffffffffffffffffffffefffffc2f, + n: 0xfffffffffffffffffffffffffffffffebaaedce6af48a03bbfd25e8cd0364141 + }); + + return _secp256k1CurveParams.verify(hashedMessage_, signature_, pubKey_); +} +``` From 774fa399c59a30269264789a03901ed93ecc77e8 Mon Sep 17 00:00:00 2001 From: aritkulova <94910987+aritkulova@users.noreply.github.com> Date: Tue, 27 May 2025 15:07:55 +0300 Subject: [PATCH 2/4] updated crypto libs --- .../guides/libs/crypto/ecdsa256.md | 19 +++++++++---------- .../guides/libs/crypto/ecdsa384.md | 9 ++++----- .../guides/libs/crypto/ecdsa512.md | 9 ++++----- .../guides/libs/crypto/rsassapss.md | 6 +++--- 4 files changed, 20 insertions(+), 23 deletions(-) diff --git a/docs/getting-started/guides/libs/crypto/ecdsa256.md b/docs/getting-started/guides/libs/crypto/ecdsa256.md index 94a4e0b..cadaf1a 100644 --- a/docs/getting-started/guides/libs/crypto/ecdsa256.md +++ b/docs/getting-started/guides/libs/crypto/ecdsa256.md @@ -24,16 +24,16 @@ using ECDSA256 for *; ```solidity function verify( - ECDSA256.Parameters memory curveParams_, + EC256.Curve memory ec, bytes32 hashedMessage_, bytes memory signature_, bytes memory pubKey_ -) internal view returns (bool) +) internal view returns (bool); ``` #### Description -The function to verify the ECDSA signature +The function to verify the ECDSA signature. ##### Parameters: @@ -47,9 +47,9 @@ The function to verify the ECDSA signature - curveParams - struct ECDSA256.Parameters - The 256-bit curve parameters. lowSmax is n/2 + ec + struct EC256.Curve + The 256-bit curve parameters hashedMessage @@ -77,15 +77,14 @@ function verifySECP256r1( bytes memory signature_, bytes memory pubKey_ ) external view returns (bool) { - ECDSA256.Parameters memory curveParams_ = - ECDSA256.Parameters({ + EC256.Curve memory curveParams_ = + EC256.Curve({ a: 0xFFFFFFFF00000001000000000000000000000000FFFFFFFFFFFFFFFFFFFFFFFC, b: 0x5AC635D8AA3A93E7B3EBBD55769886BC651D06B0CC53B0F63BCE3C3E27D2604B, gx: 0x6B17D1F2E12C4247F8BCE6E563A440F277037D812DEB33A0F4A13945D898C296, gy: 0x4FE342E2FE1A7F9B8EE7EB4A7C0F9E162BCE33576B315ECECBB6406837BF51F5, p: 0xFFFFFFFF00000001000000000000000000000000FFFFFFFFFFFFFFFFFFFFFFFF, - n: 0xFFFFFFFF00000000FFFFFFFFFFFFFFFFBCE6FAADA7179E84F3B9CAC2FC632551, - lowSmax: 0x7fffffff800000007fffffffffffffffde737d56d38bcf4279dce5617e3192a8 + n: 0xFFFFFFFF00000000FFFFFFFFFFFFFFFFBCE6FAADA7179E84F3B9CAC2FC632551 }); return curveParams_.verify(sha256(message_), signature_, pubKey_); diff --git a/docs/getting-started/guides/libs/crypto/ecdsa384.md b/docs/getting-started/guides/libs/crypto/ecdsa384.md index b271bc1..0af04b9 100644 --- a/docs/getting-started/guides/libs/crypto/ecdsa384.md +++ b/docs/getting-started/guides/libs/crypto/ecdsa384.md @@ -32,12 +32,12 @@ function verify( bytes memory hashedMessage_, bytes memory signature_, bytes memory pubKey_ -) internal view returns (bool) +) internal view returns (bool); ``` #### Description -The function to verify the ECDSA signature +The function to verify the ECDSA signature. ##### Parameters: @@ -53,7 +53,7 @@ The function to verify the ECDSA signature curveParams struct ECDSA384.Parameters - The 384-bit curve parameters. lowSmax is n/2 + The 384-bit curve parameters hashedMessage @@ -87,8 +87,7 @@ function verifySECP384r1( gx: hex"aa87ca22be8b05378eb1c71ef320ad746e1d3b628ba79b9859f741e082542a385502f25dbf55296c3a545e3872760ab7", gy: hex"3617de4a96262c6f5d9e98bf9292dc29f8f41dbd289a147ce9da3113b5f0b8c00a60b1ce1d7e819d7a431d7c90ea0e5f", p: hex"fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffeffffffff0000000000000000ffffffff", - n: hex"ffffffffffffffffffffffffffffffffffffffffffffffffc7634d81f4372ddf581a0db248b0a77aecec196accc52973", - lowSmax: hex"7fffffffffffffffffffffffffffffffffffffffffffffffe3b1a6c0fa1b96efac0d06d9245853bd76760cb5666294b9" + n: hex"ffffffffffffffffffffffffffffffffffffffffffffffffc7634d81f4372ddf581a0db248b0a77aecec196accc52973" }); return curveParams_.verify(abi.encodePacked(sha256(message_)), signature_, pubKey_); diff --git a/docs/getting-started/guides/libs/crypto/ecdsa512.md b/docs/getting-started/guides/libs/crypto/ecdsa512.md index 1acb211..37fd946 100644 --- a/docs/getting-started/guides/libs/crypto/ecdsa512.md +++ b/docs/getting-started/guides/libs/crypto/ecdsa512.md @@ -29,12 +29,12 @@ function verify( bytes memory hashedMessage_, bytes memory signature_, bytes memory pubKey_ -) internal view returns (bool) +) internal view returns (bool); ``` #### Description -The function to verify the ECDSA signature +The function to verify the ECDSA signature. ##### Parameters: @@ -50,7 +50,7 @@ The function to verify the ECDSA signature curveParams struct ECDSA512.Parameters - The 512-bit curve parameters. lowSmax is n/2 + The 512-bit curve parameters hashedMessage @@ -85,8 +85,7 @@ function verifyBrainpoolP512r1( gx: hex"81aee4bdd82ed9645a21322e9c4c6a9385ed9f70b5d916c1b43b62eef4d0098eff3b1f78e2d0d48d50d1687b93b97d5f7c6d5047406a5e688b352209bcb9f822", gy: hex"7dde385d566332ecc0eabfa9cf7822fdf209f70024a57b1aa000c55b881f8111b2dcde494a5f485e5bca4bd88a2763aed1ca2b2fa8f0540678cd1e0f3ad80892", p: hex"aadd9db8dbe9c48b3fd4e6ae33c9fc07cb308db3b3c9d20ed6639cca703308717d4d9b009bc66842aecda12ae6a380e62881ff2f2d82c68528aa6056583a48f3", - n: hex"aadd9db8dbe9c48b3fd4e6ae33c9fc07cb308db3b3c9d20ed6639cca70330870553e5c414ca92619418661197fac10471db1d381085ddaddb58796829ca90069", - lowSmax: hex"556ecedc6df4e2459fea735719e4fe03e59846d9d9e4e9076b31ce65381984382a9f2e20a654930ca0c3308cbfd608238ed8e9c0842eed6edac3cb414e548034" + n: hex"aadd9db8dbe9c48b3fd4e6ae33c9fc07cb308db3b3c9d20ed6639cca70330870553e5c414ca92619418661197fac10471db1d381085ddaddb58796829ca90069" }); return curveParams_.verify(abi.encodePacked(sha256(message_)), signature_, pubKey_); diff --git a/docs/getting-started/guides/libs/crypto/rsassapss.md b/docs/getting-started/guides/libs/crypto/rsassapss.md index 4593a41..7f0e11d 100644 --- a/docs/getting-started/guides/libs/crypto/rsassapss.md +++ b/docs/getting-started/guides/libs/crypto/rsassapss.md @@ -1,4 +1,4 @@ -# 👨🏻‍💻 RSASSAPSS +# 𓍯𓂃 RSASSAPSS ## Introduction @@ -31,7 +31,7 @@ function verifySha256( bytes memory s_, bytes memory e_, bytes memory n_ -) internal view returns (bool) +) internal view returns (bool); ``` #### Description @@ -47,7 +47,7 @@ function verify( bytes memory s_, bytes memory e_, bytes memory n_ -) internal view returns (bool) +) internal view returns (bool); ``` #### Description From 20f82905501655d12e73909d767ad791b50a2fbf Mon Sep 17 00:00:00 2001 From: aritkulova <94910987+aritkulova@users.noreply.github.com> Date: Tue, 27 May 2025 15:26:58 +0300 Subject: [PATCH 3/4] added RSASSAPSS example for consistency --- .../getting-started/guides/libs/crypto/rsassapss.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/docs/getting-started/guides/libs/crypto/rsassapss.md b/docs/getting-started/guides/libs/crypto/rsassapss.md index 7f0e11d..7fecabb 100644 --- a/docs/getting-started/guides/libs/crypto/rsassapss.md +++ b/docs/getting-started/guides/libs/crypto/rsassapss.md @@ -121,3 +121,16 @@ Verifies RSAPSS-SSA signature with custom parameters. + +#### Example + +```solidity +function verifySha256( + bytes calldata message_, + bytes calldata s_, + bytes calldata e_, + bytes calldata n_ +) external view returns (bool) { + return message_.verifySha256(s_, e_, n_); +} +``` From d283afa1cebaa0a6bbcb6a76d33f485a5c21cbb7 Mon Sep 17 00:00:00 2001 From: aritkulova <94910987+aritkulova@users.noreply.github.com> Date: Wed, 28 May 2025 13:21:02 +0300 Subject: [PATCH 4/4] expanded example for ec256 --- docs/getting-started/guides/libs/crypto/ec256.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/getting-started/guides/libs/crypto/ec256.md b/docs/getting-started/guides/libs/crypto/ec256.md index 8dea6ab..4950063 100644 --- a/docs/getting-started/guides/libs/crypto/ec256.md +++ b/docs/getting-started/guides/libs/crypto/ec256.md @@ -547,4 +547,13 @@ function affineInfinity() external view returns (EC256.APoint memory) { function basepoint() external view returns (EC256.APoint memory) { return secp256k1CurveParams.basepoint(); } + +function checkBasepointAddition() external view returns (bool) { + EC256.JPoint memory G_ = secp256k1CurveParams.jbasepoint(); + + EC256.JPoint memory doubledG_ = secp256k1CurveParams.jDoublePoint(G_); + EC256.JPoint memory scalarMultipliedG_ = secp256k1CurveParams.jMultShamir(G_, 2); + + return secp256k1CurveParams.jEqual(scalarMultipliedG_, doubledG_); +} ```