From 11597d2448ffa33f23245ec852a2dbed211cac1d Mon Sep 17 00:00:00 2001
From: Vitor Pamplona <vitor@vitorpamplona.com>
Date: Thu, 11 Sep 2025 10:45:35 -0400
Subject: [PATCH] Documents OTS methods

---
 .../quartz/nip03Timestamp/OtsEvent.kt         | 13 ++++++
 .../quartz/nip03Timestamp/OtsResolver.kt      | 42 +++++++++++++++++++
 2 files changed, 55 insertions(+)

diff --git a/quartz/src/androidMain/kotlin/com/vitorpamplona/quartz/nip03Timestamp/OtsEvent.kt b/quartz/src/androidMain/kotlin/com/vitorpamplona/quartz/nip03Timestamp/OtsEvent.kt
index d05879a26..5d3980940 100644
--- a/quartz/src/androidMain/kotlin/com/vitorpamplona/quartz/nip03Timestamp/OtsEvent.kt
+++ b/quartz/src/androidMain/kotlin/com/vitorpamplona/quartz/nip03Timestamp/OtsEvent.kt
@@ -61,17 +61,30 @@ class OtsEvent(
         const val KIND = 1040
         const val ALT = "Opentimestamps Attestation"
 
+        /**
+         * Stamp is used to save OTS requests locally while we want for the bitcoin
+         * blockchain to include the block with the proof.
+         */
         fun stamp(
             eventId: HexKey,
             resolver: OtsResolver,
         ) = resolver.stamp(eventId.hexToByteArray())
 
+        /**
+         * Converts a stamp into an attestation as soon as the bitcoin chain confirms
+         * the block with it. If the return is not null, the attestation can be sent
+         * to Nostr.
+         */
         fun upgrade(
             otsState: ByteArray,
             eventId: HexKey,
             resolver: OtsResolver,
         ) = resolver.upgrade(otsState, eventId.hexToByteArray())
 
+        /**
+         * Verifies if the attestation contained in a Nostr Event is valid by checking
+         * with the blockchain.
+         */
         fun verify(
             otsState: ByteArray,
             eventId: HexKey,
diff --git a/quartz/src/androidMain/kotlin/com/vitorpamplona/quartz/nip03Timestamp/OtsResolver.kt b/quartz/src/androidMain/kotlin/com/vitorpamplona/quartz/nip03Timestamp/OtsResolver.kt
index 169f282e0..8dcb28aca 100644
--- a/quartz/src/androidMain/kotlin/com/vitorpamplona/quartz/nip03Timestamp/OtsResolver.kt
+++ b/quartz/src/androidMain/kotlin/com/vitorpamplona/quartz/nip03Timestamp/OtsResolver.kt
@@ -33,14 +33,35 @@ import com.vitorpamplona.quartz.nip03Timestamp.ots.http.CalendarPureJavaBuilder
 import com.vitorpamplona.quartz.nip03Timestamp.ots.op.OpSHA256
 import kotlinx.coroutines.CancellationException
 
+/**
+ * Resolver class for OpenTimestamps operations.
+ *
+ * This class provides functionality to stamp data with OpenTimestamps,
+ * upgrade existing timestamps, and verify timestamp proofs against data.
+ *
+ * @property explorer The Bitcoin explorer used for verification operations.
+ * @property calendarBuilder The calendar builder used for stamping operations.
+ */
 class OtsResolver(
     explorer: BitcoinExplorer = BlockstreamExplorer(),
     calendarBuilder: CalendarBuilder = CalendarPureJavaBuilder(),
 ) {
     val ots: OpenTimestamps = OpenTimestamps(explorer, calendarBuilder)
 
+    /**
+     * Returns a human-readable information string about the given OTS file.
+     *
+     * @param otsState The serialized OpenTimestamps file data.
+     * @return A string containing information about the timestamp.
+     */
     fun info(otsState: ByteArray): String = ots.info(DetachedTimestampFile.deserialize(otsState))
 
+    /**
+     * Creates a local timestamp proof for the given data.
+     *
+     * @param data The data to be timestamped.
+     * @return A serialized DetachedTimestampFile containing the timestamp proof.
+     */
     fun stamp(data: ByteArray): ByteArray {
         val hash = Hash(data, OpSHA256.TAG)
         val file = DetachedTimestampFile.from(hash)
@@ -49,6 +70,13 @@ class OtsResolver(
         return detachedToSerialize.serialize()
     }
 
+    /**
+     * Attempts to upgrade an existing timestamp to a verified proof.
+     *
+     * @param otsState The serialized OpenTimestamps file data to upgrade.
+     * @param data The original data that was timestamped.
+     * @return A serialized DetachedTimestampFile with upgraded proof if successful, null otherwise.
+     */
     fun upgrade(
         otsState: ByteArray,
         data: ByteArray,
@@ -67,11 +95,25 @@ class OtsResolver(
         }
     }
 
+    /**
+     * Verifies an OpenTimestamps proof against the original data.
+     *
+     * @param otsFile The serialized OpenTimestamps file data.
+     * @param data The original data to verify against.
+     * @return VerificationState indicating the result of the verification.
+     */
     fun verify(
         otsFile: ByteArray,
         data: ByteArray,
     ): VerificationState = verify(DetachedTimestampFile.deserialize(otsFile), data)
 
+    /**
+     * Verifies an OpenTimestamps proof against the original data.
+     *
+     * @param detachedOts The DetachedTimestampFile containing the proof.
+     * @param data The original data to verify against.
+     * @return VerificationState indicating the result of the verification.
+     */
     fun verify(
         detachedOts: DetachedTimestampFile,
         data: ByteArray,