feat(opentimestamps): updates utils and adds comments

src/utils/opentimestamps.ts

@@ -1,13 +1,8 @@
-import {
-  Timestamp,
-  TimestampUpgradeResponse,
-  TimestampUpgradeVerifyResponse
-} from '../types'
-import { retry, retryAll } from './retry.ts'
+import { OpenTimestamp, OpenTimestampUpgradeVerifyResponse } from '../types'
+import { retry } from './retry.ts'
 import { bytesToHex } from '@noble/hashes/utils'
 import { utf8Encoder } from 'nostr-tools/utils'
 import { hexStringToUint8Array } from './string.ts'
-import { isPromiseFulfilled } from './utils.ts'
 
 /**
  * Generates a timestamp for the provided nostr event ID.
@@ -15,10 +10,10 @@ import { isPromiseFulfilled } from './utils.ts'
  */
 export const generateTimestamp = async (
   nostrId: string
-): Promise<Timestamp | undefined> => {
+): Promise<OpenTimestamp | undefined> => {
   try {
     return {
-      timestamp: await retry(() => timestamp(nostrId)),
+      value: await retry(() => timestamp(nostrId)),
       nostrId: nostrId
     }
   } catch (error) {
@@ -27,37 +22,31 @@ export const generateTimestamp = async (
   }
 }
 
+/**
+ * Attempts to upgrade (i.e. add Bitcoin blockchain attestations) and verify the provided timestamp.
+ * Returns the same timestamp, alongside additional information required to decide if any further
+ * timestamp updates are required.
+ * @param timestamp
+ */
 export const upgradeAndVerifyTimestamp = async (
-  timestamp: Timestamp
-): Promise<TimestampUpgradeVerifyResponse> => {
+  timestamp: OpenTimestamp
+): Promise<OpenTimestampUpgradeVerifyResponse> => {
   const upgradedResult = await retry(() => upgrade(timestamp))
-  const verifiedResult = await verify(upgradedResult)
-
-  console.log('verifiedResult: ', verifiedResult)
-
-  return verifiedResult
-}
-
-export const upgradeTimestamps = async (
-  timestamps: Timestamp[]
-): Promise<TimestampUpgradeResponse[]> => {
-  const resolved = await retryAll(timestamps.map((t) => () => upgrade(t)))
-  return resolved.filter(isPromiseFulfilled).map((res) => res.value)
-}
-
-export const verifyTimestamps = async (timestamps: Timestamp[]) => {
-  const settledResults = await Promise.allSettled(
-    timestamps.map(async (timestamp) => verify(timestamp))
-  )
-  return settledResults.filter(isPromiseFulfilled).map((res) => res.value)
+  return await verify(upgradedResult)
 }
 
+/**
+ * Attempts to upgrade a timestamp. If an upgrade is available,
+ * it will add new data to detachedTimestamp.
+ * The upgraded flag indicates if an upgrade has been performed.
+ * @param t - timestamp
+ */
 const upgrade = async (
-  t: Timestamp
-): Promise<TimestampUpgradeVerifyResponse> => {
-  let detachedTimestamp =
+  t: OpenTimestamp
+): Promise<OpenTimestampUpgradeVerifyResponse> => {
+  const detachedTimestamp =
     window.OpenTimestamps.DetachedTimestampFile.deserialize(
-      hexStringToUint8Array(t.timestamp)
+      hexStringToUint8Array(t.value)
     )
 
   const changed: boolean =
@@ -71,29 +60,32 @@ const upgrade = async (
     }
 
     return {
-      value,
-      upgraded: true,
-      isComplete: detachedTimestamp.timestamp.isTimestampComplete()
+      timestamp: value,
+      upgraded: true
     }
   }
   return {
-    value: t,
-    upgraded: false,
-    isComplete: detachedTimestamp.timestamp.isTimestampComplete()
+    timestamp: t,
+    upgraded: false
   }
 }
 
+/**
+ * Attempts to verify a timestamp. If verification is available,
+ * it will be included in the returned object.
+ * @param t - timestamp
+ */
 export const verify = async (
-  t: TimestampUpgradeVerifyResponse
-): Promise<TimestampUpgradeVerifyResponse> => {
+  t: OpenTimestampUpgradeVerifyResponse
+): Promise<OpenTimestampUpgradeVerifyResponse> => {
   const detachedNostrId = window.OpenTimestamps.DetachedTimestampFile.fromBytes(
     new window.OpenTimestamps.Ops.OpSHA256(),
-    utf8Encoder.encode(t.value.nostrId)
+    utf8Encoder.encode(t.timestamp.nostrId)
   )
 
-  let detachedTimestamp =
+  const detachedTimestamp =
     window.OpenTimestamps.DetachedTimestampFile.deserialize(
-      hexStringToUint8Array(t.value.timestamp)
+      hexStringToUint8Array(t.timestamp.value)
     )
 
   const res = await window.OpenTimestamps.verify(
@@ -108,6 +100,10 @@ export const verify = async (
   }
 }
 
+/**
+ * Timestamps a nostrId.
+ * @param nostrId
+ */
 const timestamp = async (nostrId: string): Promise<string> => {
   const detachedTimestamp =
     window.OpenTimestamps.DetachedTimestampFile.fromBytes(