quai-network · 0xalank · Nov 22, 2023
diff --git a/qip-0007.md b/qip-0007.md
@@ -0,0 +1,142 @@
+# QIP-0007 : Ristretto Curve25519
+
+```
+ Layer: Consensus (hard fork)
+ Title: Ristretto Curve25519
+ Author: alanorwick <[email protected]>  
+ Comments-Summary: No comments yet.  
+ Comments-URI: [https://github.com/quainetwork/qips/wiki/Comments:QIP-0004](https://github.com/quainetwork/qips/wiki/Comments:QIP-0007)  
+ Status: Draft  
+ Type: Standards Track  
+ Created: 2023-09-15  
+ License: BSD-2-Clause
+```
+
+
+## Abstract
+
+QIP-0007 defines Ristretto Curve25519 as a valid elliptic curve algorithm on Quai Network.
+
+## Motivation
+The integration of Ristretto will enhance the Quai Network’s security, speed, and capability. Further motivations for the selection of Ristretto are as follows:
+- Cofactor Elimination: Ristretto is a prime-order group construction that enables the usage of curves like Curve25519 (which have small cofactors) safely in cryptographic protocols. This eliminates complexities and potential vulnerabilities associated with cofactor-related issues.
+- Versatility and Privacy: The use of Ristretto enhances privacy and versatility, particularly in applications requiring complex cryptographic constructs, such as zero-knowledge proofs, where the prime-order group property is essential.
+- Uniform Encoding and Decoding: Ristretto provides a uniform and non-malleable encoding and decoding mechanism. This feature is essential for systems that require consistent and secure methods to represent and process elliptic curve points, reducing the risk of subtle vulnerabilities in cryptographic applications.
+- Consistent Group Operations: Ristretto ensures consistent group operations, free from edge cases associated with non-prime-order groups. This consistency is key to building more reliable and secure cryptographic protocols, as it standardizes behaviors across different implementations and use cases.
+
+
+## Specification
+### Definitions
+Ristretto is a technique for constructing prime order elliptic curve groups with non-malleable encodings. It is used to build cryptographic primitives that are more secure and easier to implement correctly. The Ristretto Curve25519 is an instance of the Ristretto technique applied to the Curve25519.
+
+### Key Derivation and Formats
+
+#### Seed Format
+- **Length:** 32 bytes.
+- **Derivation:** Generated randomly or from a BIP-39 mnemonic phrase.
+
+#### SecretKey Format
+- **Length:** 64 bytes (32-byte scalar, 32-byte nonce).
+- **Derivation:** Directly from the Seed using a key derivation function (e.g., PBKDF2 with HMAC-SHA512).
+
+#### PublicKey Format
+- **Length:** 32 bytes.
+- **Derivation:** Derived from the SecretKey using elliptic curve point multiplication on the Ristretto curve.
+- **Encoding:** 32-byte array, convertible to various formats such as hexadecimal.
+
+#### Keypair Format
+- **Composition:** SecretKey (64 bytes) and PublicKey (32 bytes).
+- **Encoding:** Concatenated byte array of SecretKey and PublicKey.
+
+### Public/Private Key Generation Process
+
+1. **Entropy Acquisition:** 
+   - Source: Obtain entropy from a BIP-39 mnemonic phrase.
+   - Validation: Ensure entropy matches BIP-39 word lengths (12, 15, 18, 21, 24 words).
+
+2. **SecretKey Generation:**
+   - Seed Generation: Convert entropy into a seed using a key derivation function.
+   - SecretKey Creation: Derive the SecretKey from the seed. This key includes a scalar and nonce component.
+
+3. **PublicKey Derivation:**
+   - Process: Derive the public key from the SecretKey using the Ristretto curve's point multiplication.
+
+4. **Keypair Assembly:**
+   - Combine the SecretKey and the derived public key to form the complete keypair, used for cryptographic operations such as digital signing and verification.
+
+For implementation examples, see [go-schnorrkel's key generation code](https://github.com/ChainSafe/go-schnorrkel/blob/master/keys.go).
+
+#### Curve Parameters:
+The parameters of the Curve25519, as specified for sr25519, are derived from the [Ristretto255](https://github.com/gtank/ristretto255/blob/master/ristretto255.go) construction. These parameters are critical in extending a Curve25519 implementation to provide the sr25519 functionality. The field has an order of `p`, the Curve25519 prime `2^255-19`, as specified in [RFC 7748](https://datatracker.ietf.org/doc/html/rfc7748#section-4.1). Below are the essential parameters:
+- D (Edwards d parameter):
+    - 37095705934669439343138083508754565189542113879843219016388785533085940283555
+    - This is the Edwards d parameter for Curve25519, crucial for the curve's structure.
+
+- SQRT_M1 (Square Root of Minus One):
+    - 19681161376707505956807079304988542015446066515923890162744021073123829784752
+    - Represents the square root of -1 within the field.
+
+- SQRT_AD_MINUS_ONE (Square Root of a*d - 1):
+    - 25063068953384623474111414158702152701244531502492656460079210480752610430750235
+    - A pre-calculated square root used in elliptic curve operations.
+
+- INVSQRT_A_MINUS_D (Inverse Square Root of a - d):
+    - 5446930700890931692099581386874514160539359729292745692120531289631721017578
+    - Used in various point operations, representing the inverse square root of a - d.
+
+- ONE_MINUS_D_SQ (One Minus d Squared):
+    - 11598430216687798791937755218555866479373577597154176544398797208761111806838
+    - Represents 1 - d^2, used in elliptic curve point calculations.
+
+- D_MINUS_ONE_SQ (d Minus One Squared):
+    - 40440834346308536858101042469323190826248399146238708352240133220865137265952
+    - Calculated as (d - 1)^2, this parameter is vital for certain mathematical operations on the curve.
+
+## Implementation
+Based on the provided Go code, here is a high-level outline for the implementation of the sr25519 key generation and verification process, suitable for inclusion in a specification:
+
+### Key Components
+- **Keypair**: Combines a public and private Ristretto key.
+- **PublicKey**: Manages the public key operations.
+- **PrivateKey**: Manages the private key operations.
+
+### Key Generation
+- **From Seed**: Generates a keypair using a 32-byte seed, with `NewKeypairFromSeed`.
+- **From Mnemonic**: Generates a keypair using a BIP-39 mnemonic and password, with `NewKeypairFromMnemonic`.
+- **Random Keypair Generation**: Provides functionality to generate a random keypair using `GenerateKeypair`.
+
+### Private Key Operations
+- **Sign**: Signs a message using the Schnorr signature algorithm.
+- **VRF Sign**: Creates a VRF output and proof from a message.
+- **Public**: Retrieves the corresponding public key.
+- **Encode/Decode**: Handles encoding and decoding of private keys.
+
+### Public Key Operations
+- **Verify**: Verifies a signature for a given message.
+- **VRF Verify**: Confirms the validity of VRF output and proof given a message.
+- **Encode/Decode**: Handles encoding and decoding of public keys.
+- **Address**: Returns the Quai address for the public key.
+
+### Signature Verification
+- **VerifySignature**: Verifies a signature given a public key and message.
+
+### Utilities
+- **HexToBytes**: Converts a hex string to a byte slice.
+- **PublicKeyToAddress**: Converts a public key to an ss58 address.
+- **AttachInput**: Wraps `VrfInOut.AttachInput` for attaching input to a VRF output.
+
+### Constants
+- **PublicKeyLength**: Expected length of the public key.
+- **PrivateKeyLength**: Expected length of the private key.
+- **SeedLength**: Expected length of the seed.
+- **SignatureLengthEd25519**: Expected length of the signature for Schnorr signature algorithm.
+
+## References
+* https://github.com/ChainSafe/go-schnorrkel/tree/master
+* https://research.web3.foundation/Polkadot/security/keys/accounts-more
+* https://github.com/gtank/ristretto255
+* https://ristretto.group/what_is_ristretto.html
+
+## Copyright
+
+This QIP is licensed under the BSD 2-clause license.