Support for retention challenges

impl/internal/did/pow.go

@@ -29,10 +29,10 @@ func hasLeadingZeros(hash string, difficulty int) bool {
 	return strings.HasPrefix(binaryHash, target)
 }
 
-// computeRetentionProof generates the Retention Proof Hash and checks if it meets the criteria.
-func computeRetentionProof(didIdentifier, bitcoinBlockHash string, difficulty, nonce int) (string, bool) {
+// solveRetentionChallenge generates the Retention Challenge Hash and checks if it meets the criteria.
+func solveRetentionChallenge(didIdentifier, inputHash string, difficulty, nonce int) (string, bool) {
 	// Concatenating the DID identifier with the retention value
-	retentionValue := didIdentifier + (bitcoinBlockHash + fmt.Sprintf("%d", nonce))
+	retentionValue := didIdentifier + (inputHash + fmt.Sprintf("%d", nonce))
 
 	// Computing the SHA-256 hash
 	hash := computeSHA256Hash(retentionValue)

impl/internal/did/pow_test.go

@@ -8,22 +8,23 @@ import (
 )
 
 func TestPOW(t *testing.T) {
-	// Example usage of computeRetentionProof
+	// Example usage of solveRetentionChallenge
 	didIdentifier := "did:dht:test"
-	bitcoinBlockHash := "000000000000000000022be0c55caae4152d023dd57e8d63dc1a55c1f6de46e7"
+	inputHash := "000000000000000000022be0c55caae4152d023dd57e8d63dc1a55c1f6de46e7"
 
 	// 26 leading zeros
 	difficulty := 26
 
 	timer := time.Now()
 	for nonce := 0; nonce < math.MaxInt; nonce++ {
-		hash, isValid := computeRetentionProof(didIdentifier, bitcoinBlockHash, difficulty, nonce)
+		hash, isValid := solveRetentionChallenge(didIdentifier, inputHash, difficulty, nonce)
 		if isValid {
 			fmt.Printf("Hash: %s\n", hash)
-			fmt.Printf("Valid Retention Proof: %v\n", isValid)
+			fmt.Printf("Valid Retention Challenge: %v\n", isValid)
 			fmt.Printf("Nonce: %d\n", nonce)
 			break
 		}
 	}
+
 	fmt.Printf("Time taken: %s\n", time.Since(timer))
 }

spec/api.yaml

@@ -50,7 +50,7 @@ paths:
     put:
       tags:
         - DHT
-      summary: Put DNS-encoded BEP44 records into the DHT
+      summary: Put a DNS-encoded BEP44 record set into the DHT
       description: Put a DNS-encoded BEP44 record set into the DHT
       parameters:
         - name: id
@@ -112,25 +112,28 @@ paths:
                 v:
                   type: string
                   description: A base64URL-encoded bencoded DNS packet containing the DID Document.
-                retention_proof:
+                retention_solution:
                   type: string
-                  description: A retention proof calculated according to the spec-defined retention proof algorithm.
+                  description: A retention solution calculated according to the spec-defined retention solution algorithm.
               required: [ did, sig, seq, v ]
       responses:
         "202":
           description: Accepted. The server has accepted the request as valid and will publish it to the
           content:
             application/json:
               schema:
-                type: string
+                type: object
+                properties:
+                  expiry:
+                    type: number
         "400":
           description: Invalid request.
           content:
             application/json:
               schema:
                 type: string
         "401":
-          description: Invalid signature.
+          description: Invalid signature or retention solution.
           content:
             application/json:
               schema:
@@ -183,6 +186,9 @@ paths:
                     items:
                       type: integer
                     description: "The sequence numbers available for querying for this node."
+                  expiry:
+                    type: number
+                    description: "The Unix Timestamp in seconds indicating when the DID will be evicted from the Gateway's Retained DID Set."
                 required: [ did, dht ]
         "400":
           description: Invalid request.
@@ -261,28 +267,33 @@ paths:
             application/json:
               schema:
                 type: string
-  /difficulty:
+  /challenge:
     get:
       tags:
         - DID
-      summary: Get information about the current difficulty.
-      description: Get information needed to calculate a retention proof for DID PUT operations.
+      summary: Get information necessary for responding to retention challenges.
+      description: Get information needed to calculate a retention solution for DID PUT operations.
       responses:
         "200":
-          description: The current hash and difficulty to calculate a retention proof against.
+          description: The current hash and difficulty to calculate a retention solution against, along with an estimated retention guarantee represented by the expiry property.
           content:
             application/json:
               schema:
                 type: object
                 properties:
                   hash:
                     type: string
+                    description: "The current hash which is to be used as input for computing a retention solution."
                   difficulty:
                     type: integer
-                required: [ hash, difficulty ]
+                    description: "The current difficulty of the challenge representing the number of bits of leading zeros the resulting hash must contain."
+                  expiry:
+                    type: integer
+                    description: "An approximate expiry date-time value, if a valid Retention Solution is submitted against this challenge, represented as a Unix Timestamp in seconds. The precise expiry date-time value is returned as a part of a PUT operation."
+                required: [ hash, difficult, expiry ]
         "404":
-          description: Retention proofs not supported by this gateway.
+          description: Retention challenges are not supported by this gateway.
           content:
             application/json:
               schema:
-                type: string     
+                type: string