[API BREAK] Change initializers of ECDSA signatures and add more documentation. (#28)

Author: Sajjon

README.md

@@ -16,46 +16,45 @@ Just like that K1 vendors these key pairs:
 
 Just like you can convert between e.g. `Curve25519.KeyAgreement.PrivateKey` and  `Curve25519.Signing.PrivateKey` back and forth using any of the initializers and serializer, you can convert between all PrivateKeys and all PublicKeys of all features in K1.
 
-All keys conform to `K1KeyExportable` protocol below to serialize the Private/PubliKey:
+All keys can be serialized using these computed properties:
 
 ```swift
-public protocol K1KeyExportable {
+{
     var rawRepresentation: Data { get }
-    var x963Representation: Data { get }
     var derRepresentation: Data { get }
     var pemRepresentation: String { get }
+    var x963Representation: Data { get }
 }
 ```
 
-All keys conform to `K1KeyImportable` protocol below to deserialize to Private/PubliKey:
+All keys can be deserialize using these initializer:
 
 ```swift
-public protocol K1KeyImportable {
+{
     init(rawRepresentation: some ContiguousBytes) throws
-    init(x963Representation: some ContiguousBytes) throws
     init(derRepresentation: some RandomAccessCollection<UInt8>) throws
     init(pemRepresentation: String) throws
+    init(x963Representation: some ContiguousBytes) throws
 }
 ```
 
-Furthermore, all PrivateKey's conform to this protocol
+Furthermore, all PrivateKey's have these additional APIs:
 
 ```swift
-protocol K1PrivateKeyProtocol: K1KeyPortable {
-    associatedtype PublicKey: K1PublicKeyProtocol
-    var publicKey: PublicKey { get }
+{
     init()
+    associatedtype PublicKey
+    var publicKey: PublicKey { get }
 }
 ```
 
-Furthermore, all PublicKey's conform to this protocol
+Furthermore, all PublicKeys's have these additional APIs:
 
 ```swift
-public protocol K1PublicKeyProtocol: K1KeyPortable {
+{
     init(compressedRepresentation: some ContiguousBytes) throws
     var compressedRepresentation: Data { get }
 }
-
 ```
 
 
@@ -185,8 +184,8 @@ It is worth noting that some Schnorr implementations are incompatible with [BIP3
 # ECDH
 
 This library vendors three different EC Diffie-Hellman (ECDH) key exchange functions:
-1. `ASN1 x9.63` - No hash, return only the `X` coordinate of the point - `sharedSecretFromKeyAgreement -> SharedSecret`
-2. `libsecp256k1` - SHA-256 hash the compressed point - `ecdh -> Data`
+1. `ASN1 x9.63` - No hash, return only the `X` coordinate of the point - `sharedSecretFromKeyAgreement:with -> SharedSecret`
+2. `libsecp256k1` - SHA-256 hash the compressed point - `ecdh:with -> SharedSecret`
 3. Custom - No hash, return point uncompressed - `ecdhPoint -> Data`
 
 ```swift

Sources/K1/K1/ECDSA/ECDSASignatureNonRecoverable.swift

@@ -26,15 +26,25 @@ extension K1.ECDSA.NonRecoverable {
 
 // MARK: Inits
 extension K1.ECDSA.NonRecoverable.Signature {
-	public init(compactRepresentation: some DataProtocol) throws {
+	/// Creates a `secp256k1` ECDSA signature from a Distinguished Encoding Rules (DER) encoded representation.
+	/// - Parameter derRepresentation: A DER-encoded representation of the signature.
+	public init(derRepresentation: some DataProtocol) throws {
 		try self.init(
-			wrapped: FFI.ECDSA.NonRecoverable.from(compactBytes: [UInt8](compactRepresentation))
+			wrapped: FFI.ECDSA.NonRecoverable.from(derRepresentation: [UInt8](derRepresentation))
 		)
 	}
 
-	public init(derRepresentation: some DataProtocol) throws {
+	/// Creates a `secp256k1` ECDSA signature from the raw representation.
+	///
+	/// Expects 64 bytes on format: `R || S`, as defined in [rfc4754][rfc]. In
+	/// `libsecp256k1` this representation is called "compact".
+	///
+	/// - Parameter rawRepresentation: A raw representation of the ECDSA signature as a collection of contiguous bytes.
+	///
+	/// [rfc]: https://tools.ietf.org/html/rfc4754
+	public init(rawRepresentation: some DataProtocol) throws {
 		try self.init(
-			wrapped: FFI.ECDSA.NonRecoverable.from(derRepresentation: [UInt8](derRepresentation))
+			wrapped: FFI.ECDSA.NonRecoverable.from(compactBytes: [UInt8](rawRepresentation))
 		)
 	}
 }
@@ -48,21 +58,43 @@ extension K1.ECDSA.NonRecoverable.Signature {
 
 // MARK: Serialize
 extension K1.ECDSA.NonRecoverable.Signature {
-	internal var rawRepresentation: Data {
+	var internalRepresentation: Data {
 		Data(wrapped.bytes)
 	}
 
-	public func compactRepresentation() throws -> Data {
-		try FFI.ECDSA.NonRecoverable.compact(wrapped)
+	/// A raw data representation of a `secp256k1` ECDSA non recoverable signature.
+	///
+	/// Returns 64 bytes on format: `R || S`, as defined in [rfc4754][rfc]. In
+	/// `libsecp256k1` this representation is called "compact".
+	public var rawRepresentation: Data {
+		do {
+			return try FFI.ECDSA.NonRecoverable.compact(wrapped)
+		} catch {
+			fatalError("Should never fail to convert ECDSA signatures to rawRepresentation.")
+		}
 	}
 
-	public func derRepresentation() throws -> Data {
-		try FFI.ECDSA.NonRecoverable.der(wrapped)
+	/// A Distinguished Encoding Rules (DER) encoded representation of a
+	/// `secp256k1` ECDSA non recoverable signature.
+	public var derRepresentation: Data {
+		do {
+			return try FFI.ECDSA.NonRecoverable.der(wrapped)
+		} catch {
+			fatalError("Should never fail to convert ECDSA signatures to DER representation.")
+		}
 	}
 }
 
 // MARK: Recover
 extension K1.ECDSA.NonRecoverable.Signature {
+	/// Recovers a public key from a `secp256k1` ECDSA signature, the message signed
+	/// and a `recoveryID`.
+	///
+	/// - Parameters:
+	///   - recoveryID: The recoveryID produced when a recoverable signature was produced.
+	///   - message: The message that was signed to produce this ECDSA signature.
+	/// - Returns: The public key which corresponds to the private key which used to produce this
+	/// signature by signing the `message`.
 	public func recoverPublicKey(
 		recoveryID: K1.ECDSA.Recoverable.Signature.RecoveryID,
 		message: some DataProtocol
@@ -83,6 +115,7 @@ extension K1.ECDSA.NonRecoverable.Signature {
 
 // MARK: Equatable
 extension K1.ECDSA.NonRecoverable.Signature {
+	/// Compares two ECDSA signatures.
 	public static func == (lhs: Self, rhs: Self) -> Bool {
 		lhs.wrapped.withUnsafeBytes { lhsBytes in
 			rhs.wrapped.withUnsafeBytes { rhsBytes in

Sources/K1/K1/ECDSA/ECDSASignatureRecoverable.swift

@@ -41,11 +41,11 @@ extension K1.ECDSA.Recoverable.Signature {
 		try self.init(compact: .init(compact: compact, recoveryID: recoveryID))
 	}
 
-	public init(
-		rawRepresentation: some DataProtocol
+	init(
+		internalRepresentation: some DataProtocol
 	) throws {
 		try self.init(
-			wrapped: FFI.ECDSA.Recoverable.deserialize(rawRepresentation: rawRepresentation)
+			wrapped: FFI.ECDSA.Recoverable.deserialize(rawRepresentation: internalRepresentation)
 		)
 	}
 }
@@ -59,7 +59,7 @@ extension K1.ECDSA.Recoverable.Signature {
 
 // MARK: Serialize
 extension K1.ECDSA.Recoverable.Signature {
-	internal var rawRepresentation: Data {
+	internal var internalRepresentation: Data {
 		Data(wrapped.bytes)
 	}
 
@@ -74,6 +74,7 @@ extension K1.ECDSA.Recoverable.Signature {
 		)
 	}
 
+	/// A tuple of `R||S` and `recoveryID` from a recoverable ECDSA signature.
 	public struct Compact: Sendable, Hashable {
 		/// Compact aka `IEEE P1363` aka `R||S`.
 		public let compact: Data
@@ -163,6 +164,12 @@ extension K1.ECDSA.Recoverable.Signature.RecoveryID {
 
 // MARK: Recovery
 extension K1.ECDSA.Recoverable.Signature {
+	/// Recovers a public key from a `secp256k1` this ECDSA signature and the message signed.
+	///
+	/// - Parameters:
+	///   - message: The message that was signed to produce this ECDSA signature.
+	/// - Returns: The public key which corresponds to the private key which used to produce this
+	/// signature by signing the `message`.
 	public func recoverPublicKey(
 		message: some DataProtocol
 	) throws -> K1.ECDSA.Recoverable.PublicKey {
@@ -176,6 +183,7 @@ extension K1.ECDSA.Recoverable.Signature {
 
 // MARK: Conversion
 extension K1.ECDSA.Recoverable.Signature {
+	/// Converts this recoverable ECDSA signature to a non-recoverable version.
 	public func nonRecoverable() throws -> K1.ECDSA.NonRecoverable.Signature {
 		try K1.ECDSA.NonRecoverable.Signature(
 			wrapped: FFI.ECDSA.Recoverable.nonRecoverable(self.wrapped)
@@ -185,6 +193,7 @@ extension K1.ECDSA.Recoverable.Signature {
 
 // MARK: Equatable
 extension K1.ECDSA.Recoverable.Signature {
+	/// Compares two ECDSA signatures.
 	public static func == (lhs: Self, rhs: Self) -> Bool {
 		lhs.wrapped.withUnsafeBytes { lhsBytes in
 			rhs.wrapped.withUnsafeBytes { rhsBytes in

Sources/K1/K1/Keys/Keys.generated.swift

@@ -7,7 +7,7 @@ import Foundation
 extension K1.KeyAgreement {
 	// MARK: KeyAgreement + PrivateKey
 	/// A `secp256k1` private key used for key agreement.
-	public struct PrivateKey: Sendable, Hashable, K1PrivateKeyProtocol {
+	public struct PrivateKey: Sendable, Hashable {
 		typealias Impl = K1._PrivateKeyImplementation
 		public typealias PublicKey = K1.KeyAgreement.PublicKey
 
@@ -109,7 +109,7 @@ extension K1.KeyAgreement {
 
 	// MARK: KeyAgreement + PublicKey
 	/// A `secp256k1` public key used for key agreement.
-	public struct PublicKey: Sendable, Hashable, K1PublicKeyProtocol {
+	public struct PublicKey: Sendable, Hashable {
 		typealias Impl = K1._PublicKeyImplementation
 		internal let impl: Impl
 		internal init(impl: Impl) {
@@ -206,7 +206,7 @@ extension K1.Schnorr {
 	// MARK: Schnorr + PrivateKey
 	/// A `secp256k1` private key used to create cryptographic signatures,
 	/// more specifically Schnorr signatures.
-	public struct PrivateKey: Sendable, Hashable, K1PrivateKeyProtocol {
+	public struct PrivateKey: Sendable, Hashable {
 		typealias Impl = K1._PrivateKeyImplementation
 		public typealias PublicKey = K1.Schnorr.PublicKey
 
@@ -309,7 +309,7 @@ extension K1.Schnorr {
 	// MARK: Schnorr + PublicKey
 	/// A `secp256k1` public key used to verify cryptographic signatures,
 	/// more specifically Schnorr signatures
-	public struct PublicKey: Sendable, Hashable, K1PublicKeyProtocol {
+	public struct PublicKey: Sendable, Hashable {
 		typealias Impl = K1._PublicKeyImplementation
 		internal let impl: Impl
 		internal init(impl: Impl) {
@@ -406,7 +406,7 @@ extension K1.ECDSA.NonRecoverable {
 	// MARK: ECDSA.NonRecoverable + PrivateKey
 	/// A `secp256k1` private key used to create cryptographic signatures,
 	/// more specifically ECDSA signatures, that do not offer recovery of the public key.
-	public struct PrivateKey: Sendable, Hashable, K1PrivateKeyProtocol {
+	public struct PrivateKey: Sendable, Hashable {
 		typealias Impl = K1._PrivateKeyImplementation
 		public typealias PublicKey = K1.ECDSA.NonRecoverable.PublicKey
 
@@ -509,7 +509,7 @@ extension K1.ECDSA.NonRecoverable {
 	// MARK: ECDSA.NonRecoverable + PublicKey
 	/// A `secp256k1` public key used to verify cryptographic signatures,
 	/// more specifically ECDSA signatures, that do not offer recovery of the public key.
-	public struct PublicKey: Sendable, Hashable, K1PublicKeyProtocol {
+	public struct PublicKey: Sendable, Hashable {
 		typealias Impl = K1._PublicKeyImplementation
 		internal let impl: Impl
 		internal init(impl: Impl) {
@@ -606,7 +606,7 @@ extension K1.ECDSA.Recoverable {
 	// MARK: ECDSA.Recoverable + PrivateKey
 	/// A `secp256k1` private key used to create cryptographic signatures,
 	/// more specifically ECDSA signatures that offers recovery of the public key.
-	public struct PrivateKey: Sendable, Hashable, K1PrivateKeyProtocol {
+	public struct PrivateKey: Sendable, Hashable {
 		typealias Impl = K1._PrivateKeyImplementation
 		public typealias PublicKey = K1.ECDSA.Recoverable.PublicKey
 
@@ -709,7 +709,7 @@ extension K1.ECDSA.Recoverable {
 	// MARK: ECDSA.Recoverable + PublicKey
 	/// A `secp256k1` public key used to verify cryptographic signatures.
 	/// more specifically ECDSA signatures that offers recovery of the public key.
-	public struct PublicKey: Sendable, Hashable, K1PublicKeyProtocol {
+	public struct PublicKey: Sendable, Hashable {
 		typealias Impl = K1._PublicKeyImplementation
 		internal let impl: Impl
 		internal init(impl: Impl) {
@@ -801,3 +801,27 @@ extension K1.ECDSA.Recoverable {
 		}
 	}
 }
+
+// MARK: - K1.KeyAgreement.PrivateKey + _K1PrivateKeyProtocol
+extension K1.KeyAgreement.PrivateKey: _K1PrivateKeyProtocol {}
+
+// MARK: - K1.KeyAgreement.PublicKey + _K1PublicKeyProtocol
+extension K1.KeyAgreement.PublicKey: _K1PublicKeyProtocol {}
+
+// MARK: - K1.Schnorr.PrivateKey + _K1PrivateKeyProtocol
+extension K1.Schnorr.PrivateKey: _K1PrivateKeyProtocol {}
+
+// MARK: - K1.Schnorr.PublicKey + _K1PublicKeyProtocol
+extension K1.Schnorr.PublicKey: _K1PublicKeyProtocol {}
+
+// MARK: - K1.ECDSA.NonRecoverable.PrivateKey + _K1PrivateKeyProtocol
+extension K1.ECDSA.NonRecoverable.PrivateKey: _K1PrivateKeyProtocol {}
+
+// MARK: - K1.ECDSA.NonRecoverable.PublicKey + _K1PublicKeyProtocol
+extension K1.ECDSA.NonRecoverable.PublicKey: _K1PublicKeyProtocol {}
+
+// MARK: - K1.ECDSA.Recoverable.PrivateKey + _K1PrivateKeyProtocol
+extension K1.ECDSA.Recoverable.PrivateKey: _K1PrivateKeyProtocol {}
+
+// MARK: - K1.ECDSA.Recoverable.PublicKey + _K1PublicKeyProtocol
+extension K1.ECDSA.Recoverable.PublicKey: _K1PublicKeyProtocol {}

Sources/K1/K1/Keys/Keys.swift.gyb

@@ -47,7 +47,7 @@ import Foundation
 extension K1.${FEATURE} {
 	// MARK: ${FEATURE} + PrivateKey
 	${PRIVATEKEY_TYPE_DOC}
-	public struct PrivateKey: Sendable, Hashable, K1PrivateKeyProtocol {
+	public struct PrivateKey: Sendable, Hashable {
 
 		typealias Impl = K1._PrivateKeyImplementation
 		public typealias PublicKey = K1.${FEATURE}.PublicKey
@@ -151,7 +151,7 @@ extension K1.${FEATURE} {
 
 	// MARK: ${FEATURE} + PublicKey
 	${PUBLICKEY_TYPE_DOC}
-	public struct PublicKey: Sendable, Hashable, K1PublicKeyProtocol {
+	public struct PublicKey: Sendable, Hashable {
 
 		typealias Impl = K1._PublicKeyImplementation
 		internal let impl: Impl
@@ -245,6 +245,15 @@ extension K1.${FEATURE} {
 
 	}
 }
+% end
 
+% for KEY_FOR_FEATURE_WITH_DOCS in LIST_KEY_FOR_FEATURE_WITH_DOCS:
+%{
+	FEATURE = KEY_FOR_FEATURE_WITH_DOCS["feature"]
+}%
+extension K1.${FEATURE}.PrivateKey: _K1PrivateKeyProtocol {}
+extension K1.${FEATURE}.PublicKey: _K1PublicKeyProtocol {}
 % end
+
 % end
+

Sources/K1/K1/Keys/PrivateKeyImplementation.swift

@@ -1,34 +1,34 @@
 import CryptoKit
 import Foundation
 
-// MARK: - K1KeyExportable
-public protocol K1KeyExportable {
+// MARK: - _K1KeyExportable
+protocol _K1KeyExportable {
 	var rawRepresentation: Data { get }
-	var x963Representation: Data { get }
 	var derRepresentation: Data { get }
 	var pemRepresentation: String { get }
+	var x963Representation: Data { get }
 }
 
-// MARK: - K1KeyImportable
-public protocol K1KeyImportable {
+// MARK: - _K1KeyImportable
+protocol _K1KeyImportable {
 	init(rawRepresentation: some ContiguousBytes) throws
-	init(x963Representation: some ContiguousBytes) throws
 	init(derRepresentation: some RandomAccessCollection<UInt8>) throws
 	init(pemRepresentation: String) throws
+	init(x963Representation: some ContiguousBytes) throws
 }
 
-public typealias K1KeyPortable = K1KeyImportable & K1KeyExportable
+typealias _K1KeyPortable = _K1KeyImportable & _K1KeyExportable
 
-// MARK: - K1PrivateKeyProtocol
-public protocol K1PrivateKeyProtocol: K1KeyPortable {
-	associatedtype PublicKey: K1PublicKeyProtocol
+// MARK: - _K1PrivateKeyProtocol
+protocol _K1PrivateKeyProtocol: _K1KeyPortable {
+	associatedtype PublicKey: _K1PublicKeyProtocol
 	var publicKey: PublicKey { get }
 	init()
 }
 
 // MARK: - K1._PrivateKeyImplementation
 extension K1 {
-	struct _PrivateKeyImplementation: Sendable, Hashable, K1PrivateKeyProtocol {
+	struct _PrivateKeyImplementation: Sendable, Hashable, _K1PrivateKeyProtocol {
 		typealias Wrapped = FFI.PrivateKey.Wrapped
 		internal let wrapped: Wrapped