Extensive additions to KDoc comments

lib/src/main/kotlin/me/tb/cashuclient/Wallet.kt

@@ -65,7 +65,7 @@ public typealias MintInfo = InfoResponse
  *
  * @param activeKeyset The [Keyset] that is currently active for the mint.
  * @param mintUrl      The URL of the mint.
- * @param unit         The underlying unit used with the ecash tokens for this wallet.
+ * @param unit         The underlying unit used for the ecash tokens for this wallet.
  * @param db           The implementation of [CashuDB] used for this wallet (by default, a [SQLiteDB]).
  */
 public class Wallet(

lib/src/main/kotlin/me/tb/cashuclient/mint/MintMessages.kt

@@ -14,11 +14,7 @@ import me.tb.cashuclient.types.BlindedSignaturesResponse
 /**
  * This is the object sent to the mint endpoint and consists of a list of blinded messages to sign.
  *
- * NOTE: These are called PostMintRequest in the specification (NUT-04). The reason why I changed the name is that
- *       PostMintRequest describes the object in terms of _when_ it is sent (after the "mint request" described in
- *       NUT-03 has been sent) rather than what it is. `MintRequest` is, IMO, a better name, and conveys its purpose,
- *       particularly when coupled with its sibling object, `MintResponse`.
- *
+ * @property quoteId The quote ID received from the mint in response to a [MintQuoteRequest].
  * @property outputs List of blinded messages to be signed.
  */
 @Serializable

lib/src/main/kotlin/me/tb/cashuclient/mint/MintQuoteMessages.kt

@@ -5,21 +5,60 @@
 
 package me.tb.cashuclient.mint
 
+import fr.acinq.bitcoin.Satoshi
 import fr.acinq.lightning.payment.PaymentRequest
 import kotlinx.serialization.SerialName
 import kotlinx.serialization.Serializable
 import me.tb.cashuclient.types.PaymentRequestSerializer
 
+/**
+ * In order to proceed with a mint, Alice must request a quote for a given bolt11 invoice she would like paid. This is
+ * the object sent to the mint for this purpose.
+ *
+ * @property amount The amount to be minted.
+ * @property unit   The unit the wallet is requesting tokens for.
+ */
 @Serializable
 public data class MintQuoteRequest(
     public val amount: ULong,
     public val unit: String,
 )
 
+/**
+ * The mint's response to a [MintQuoteRequest].
+ *
+ * @property quoteId The unique identifier for this quote.
+ * @property request The bolt11 payment request for the quote.
+ * @property paid    Whether the payment has been paid.
+ * @property expiry  The expiry time of the quote.
+ */
 @Serializable
 public data class MintQuoteResponse(
     @SerialName("quote") public val quoteId: String,
     @Serializable(with = PaymentRequestSerializer::class) public val request: PaymentRequest,
     public val paid: Boolean,
     public val expiry: Int
-)
+)
+
+public data class MintQuoteData(
+    val paymentAmount: Satoshi,
+    val fee: Satoshi,
+    val feeRate: Double,
+    val quote: MintQuoteResponse
+) {
+    public companion object {
+        public fun fromMintQuoteResponse(initialPaymentAmount: Satoshi, mintQuoteResponse: MintQuoteResponse): MintQuoteData {
+            val paymentRequest: PaymentRequest = mintQuoteResponse.request
+            val totalPayment: Satoshi = paymentRequest.amount?.truncateToSatoshi() ?: throw IllegalStateException("Payment request has no amount")
+            val fee = totalPayment.sat - initialPaymentAmount.sat
+            val feeRate = fee.toDouble() / initialPaymentAmount.sat.toDouble()
+
+            return MintQuoteData(
+                paymentAmount = initialPaymentAmount,
+                fee = Satoshi(fee),
+                feeRate = feeRate,
+                quote = mintQuoteResponse
+            )
+        }
+    }
+}

lib/src/main/kotlin/me/tb/cashuclient/mint/PreMintBundle.kt

@@ -62,10 +62,10 @@ public class PreMintBundle private constructor(
  * sign. Upon return, the signed [BlindedSignature]s are unblinded using the blindingFactor and, combined with the
  * secret, stored as [Proof]s in the database.
  *
- * @param amount The amount of the token.
- * @param secret The secret x that is used in hashToCurve(x) to create Y.
- * @param blindedSecret The blinded secret B_ that is sent to the mint.
- * @param blindingFactor The blinding factor r, private key of the point R that is used to blind key Y.
+ * @property amount The amount of the token.
+ * @property secret The secret x that is used in hashToCurve(x) to create Y.
+ * @property blindedSecret The blinded secret B_ that is sent to the mint.
+ * @property blindingFactor The blinding factor r, private key of the point R that is used to blind key Y.
  */
 public class PreMintItem private constructor(
     public override val amount: ULong,

lib/src/main/kotlin/me/tb/cashuclient/swap/PreSwapBundle.kt

@@ -122,10 +122,10 @@ public class PreSwapBundle private constructor(
  * sign. Upon return, the signed [me.tb.cashuclient.types.BlindedSignature]s are unblinded using the blindingFactor and, combined with the
  * secret, stored as [Proof]s in the database.
  *
- * @param amount The amount of the token.
- * @param secret The secret x that is used in hashToCurve(x) to create Y.
- * @param blindedSecret The blinded secret B_ that is sent to the mint.
- * @param blindingFactor The blinding factor r, private key of the point R that is used to blind key Y.
+ * @property amount The amount of the token.
+ * @property secret The secret x that is used in hashToCurve(x) to create Y.
+ * @property blindedSecret The blinded secret B_ that is sent to the mint.
+ * @property blindingFactor The blinding factor r, private key of the point R that is used to blind key Y.
  */
 public class PreSwapItem private constructor(
     public override val amount: ULong,

lib/src/main/kotlin/me/tb/cashuclient/swap/SwapMessages.kt

@@ -11,6 +11,12 @@ import me.tb.cashuclient.types.BlindedSignature
 import me.tb.cashuclient.types.BlindedSignaturesResponse
 import me.tb.cashuclient.types.Proof
 
+/**
+ * This is the object sent to the swap endpoint.
+ *
+ * @property inputs  List of proofs.
+ * @property outputs List of blinded messages.
+ */
 @Serializable
 public data class SwapRequest(
     public val inputs: List<Proof>,
@@ -20,9 +26,9 @@ public data class SwapRequest(
 // TODO: The MintResponse and SwapResponse are the same class. We can clean this up.
 
 /**
- * This is the object returned by the swap endpoint and consists of a list of blinded signatures.
+ * This is the response to the [SwapRequest].
  *
- * @param signatures List of blinded signatures.
+ * @property signatures List of blinded signatures.
  */
 @Serializable
 public data class SwapResponse(

lib/src/main/kotlin/me/tb/cashuclient/types/ActiveKeysetsResponse.kt

@@ -10,7 +10,7 @@ import kotlinx.serialization.Serializable
 /**
  * The data structure the mint returns when we ask for the active keysets.
  *
- * @param keysets A list of serializable [KeysetJson] objects.
+ * @property keysets A list of serializable [KeysetJson] objects.
  */
 @Serializable
 public data class ActiveKeysetsResponse(
@@ -22,6 +22,6 @@ public data class ActiveKeysetsResponse(
 /**
  * The data structure the mint returns when we ask for a specific keyset.
  *
- * @param keysets A list of serializable [KeysetJson] objects.
+ * @property keysets A list of serializable [KeysetJson] objects.
  */
 public typealias SpecificKeysetResponse = ActiveKeysetsResponse

lib/src/main/kotlin/me/tb/cashuclient/types/BlindedMessage.kt

@@ -11,8 +11,9 @@ import kotlinx.serialization.Serializable
 /**
  * The smallest unit of request to the mint endpoint.
  *
- * @param amount The amount of the token.
- * @param blindedSecret The blinded secret, referred to as B_ in the spec (NUT-00).
+ * @property amount The amount of the token.
+ * @property id     The identifier of the keyset from which we expect a signature,
+ * @property blindedSecret The blinded secret, referred to as B_ in the spec (NUT-00).
  */
 @Serializable
 public data class BlindedMessage(

lib/src/main/kotlin/me/tb/cashuclient/types/BlindedSignature.kt

@@ -10,11 +10,12 @@ import kotlinx.serialization.SerialName
 import kotlinx.serialization.Serializable
 
 /**
- * This is the smallest unit of data returned by the mint endpoint. These aggregate into a [me.tb.cashuclient.mint.MintResponse] object.
+ * This is the smallest unit of data returned by the mint endpoint. These aggregate into a
+ * [me.tb.cashuclient.mint.MintResponse] object.
  *
- * @param amount The value of the token.
- * @param id The id of the keyset of the mint that signed the token.
- * @param blindedKey The blinded signature, a point on the curve referred to as C_ in the spec (NUT-00).
+ * @property amount     The value of the token.
+ * @property id         The id of the keyset of the mint that signed the token.
+ * @property blindedKey The blinded signature, a point on the curve referred to as C_ in the spec (NUT-00).
  */
 @Serializable
 public data class BlindedSignature(

lib/src/main/kotlin/me/tb/cashuclient/types/BlindedSignaturesResponse.kt

@@ -3,8 +3,12 @@
  * Use of this source code is governed by the Apache 2.0 license that can be found in the ./LICENSE.txt file.
  */
 
- package me.tb.cashuclient.types
+package me.tb.cashuclient.types
 
+/**
+ * This interface represents the response from the mint and swap endpoints, where the mint returns a list of blinded
+ * signatures ready to be processed and persisted.
+ */
 public interface BlindedSignaturesResponse {
     public val signatures: List<BlindedSignature>
 }

lib/src/main/kotlin/me/tb/cashuclient/types/EcashUnit.kt

@@ -3,9 +3,16 @@
  * Use of this source code is governed by the Apache 2.0 license that can be found in the ./LICENSE.txt file.
  */
 
- package me.tb.cashuclient.types
+package me.tb.cashuclient.types
 
+/**
+ * Represents the possible units of ecash that are represented by the Cashu tokens a wallet holds. This library
+ * currently only supports the satoshi as the underlying unit for the ecash token it handles.
+ */
 public enum class EcashUnit {
+    /**
+     * The satoshi, equivalent to 0.00000001 bitcoin.
+     */
     SAT;
 
     override fun toString(): String {

lib/src/main/kotlin/me/tb/cashuclient/types/PreRequestBundle.kt

@@ -3,7 +3,7 @@
  * Use of this source code is governed by the Apache 2.0 license that can be found in the ./LICENSE.txt file.
  */
 
- package me.tb.cashuclient.types
+package me.tb.cashuclient.types
 
 public interface PreRequestBundle {
     public val blindingDataItems: List<BlindingData>

lib/src/main/kotlin/me/tb/cashuclient/types/Proof.kt

@@ -8,7 +8,7 @@ package me.tb.cashuclient.types
 import kotlinx.serialization.Serializable
 
 /**
- * Cashu token.
+ * A proof as defined in NUT-00, also known as a Cashu note.
  */
 @Suppress("PropertyName")
 @Serializable

lib/src/main/kotlin/me/tb/cashuclient/types/Secret.kt

@@ -8,8 +8,8 @@ package me.tb.cashuclient.types
 import me.tb.cashuclient.randomBytes
 
 /**
- * Secret used to generate a token. This is the x in NUT-00, the bytes we'll use in the [hashToCurve] function
- * to generate key Y.
+ * Secret used to generate a token. This is the x in NUT-00, the bytes we'll use in the [me.tb.cashuclient.hashToCurve]
+ * function to generate key Y.
  *
  * @property value The secret to use. Secrets are always 32 bytes of randomness.
  */