From 76bb8f592226213b428597fce64437647530a282 Mon Sep 17 00:00:00 2001
From: bhartnett <51288821+bhartnett@users.noreply.github.com>
Date: Fri, 18 Oct 2024 09:47:40 +0800
Subject: [PATCH 1/5] Rename portal_*Gossip to portal_*PutContent and update
 method descriptions.

---
 jsonrpc/src/content/results.json |  4 ++--
 jsonrpc/src/methods/beacon.json  | 30 ++++++++++++++++++------------
 jsonrpc/src/methods/history.json |  6 +++---
 jsonrpc/src/methods/state.json   |  6 +++---
 4 files changed, 26 insertions(+), 20 deletions(-)

diff --git a/jsonrpc/src/content/results.json b/jsonrpc/src/content/results.json
index 8e511a3b..6aec591c 100644
--- a/jsonrpc/src/content/results.json
+++ b/jsonrpc/src/content/results.json
@@ -220,8 +220,8 @@
       "$ref": "#/components/schemas/hexString"
     }
   },
-  "GossipResult": {
-    "name": "gossipResult",
+  "PutContentResult": {
+    "name": "PutContentResult",
     "description": "Returns the number of peers that the content was gossiped to",
     "schema": {
       "title": "number of peers",
diff --git a/jsonrpc/src/methods/beacon.json b/jsonrpc/src/methods/beacon.json
index f423f2d9..b5ae6426 100644
--- a/jsonrpc/src/methods/beacon.json
+++ b/jsonrpc/src/methods/beacon.json
@@ -143,9 +143,11 @@
     "result": {
       "$ref": "#/components/contentDescriptors/GetContentResult"
     },
-    "errors":[{
-      "$ref": "#/components/errors/ContentNotFoundError"
-    }]
+    "errors": [
+      {
+        "$ref": "#/components/errors/ContentNotFoundError"
+      }
+    ]
   },
   {
     "name": "portal_beaconTraceGetContent",
@@ -158,9 +160,11 @@
     "result": {
       "$ref": "#/components/contentDescriptors/TraceGetContentResult"
     },
-    "errors":[{
-      "$ref": "#/components/errors/ContentNotFoundErrorWithTrace"
-    }]
+    "errors": [
+      {
+        "$ref": "#/components/errors/ContentNotFoundErrorWithTrace"
+      }
+    ]
   },
   {
     "name": "portal_beaconStore",
@@ -188,13 +192,15 @@
     "result": {
       "$ref": "#/components/contentDescriptors/LocalContentResult"
     },
-    "errors":[{
-      "$ref": "#/components/errors/ContentNotFoundError"
-    }]
+    "errors": [
+      {
+        "$ref": "#/components/errors/ContentNotFoundError"
+      }
+    ]
   },
   {
-    "name": "portal_beaconGossip",
-    "summary": "Send the provided content item to interested peers. Clients may choose to send to some or all peers.",
+    "name": "portal_beaconPutContent",
+    "summary": "Validate and store the provided content in the local database if storage criteria is met, then send the content to interested peers. Clients may choose to send to some or all peers.",
     "params": [
       {
         "$ref": "#/components/contentDescriptors/ContentKey"
@@ -204,7 +210,7 @@
       }
     ],
     "result": {
-      "$ref": "#/components/contentDescriptors/GossipResult"
+      "$ref": "#/components/contentDescriptors/PutContentResult"
     }
   }
 ]
diff --git a/jsonrpc/src/methods/history.json b/jsonrpc/src/methods/history.json
index 165d6743..e983c3d5 100644
--- a/jsonrpc/src/methods/history.json
+++ b/jsonrpc/src/methods/history.json
@@ -185,8 +185,8 @@
     }]
   },
   {
-    "name": "portal_historyGossip",
-    "summary": "Send the provided content item to interested peers. Clients may choose to send to some or all peers.",
+    "name": "portal_historyPutContent",
+    "summary": "Validate and store the provided content in the local database if storage criteria is met, then send the content to interested peers. Clients may choose to send to some or all peers.",
     "params": [
       {
         "$ref": "#/components/contentDescriptors/ContentKey"
@@ -196,7 +196,7 @@
       }
     ],
     "result": {
-      "$ref": "#/components/contentDescriptors/GossipResult"
+      "$ref": "#/components/contentDescriptors/PutContentResult"
     }
   }
 ]
diff --git a/jsonrpc/src/methods/state.json b/jsonrpc/src/methods/state.json
index 1ffe1585..9d38a33c 100644
--- a/jsonrpc/src/methods/state.json
+++ b/jsonrpc/src/methods/state.json
@@ -185,8 +185,8 @@
     }]
   },
   {
-    "name": "portal_stateGossip",
-    "summary": "Send the provided content item to interested peers. Clients may choose to send to some or all peers.",
+    "name": "portal_statePutContent",
+    "summary": "Validate and store the provided content in the local database if storage criteria is met, then send the content to interested peers. Clients may choose to send to some or all peers.",
     "params": [
       {
         "$ref": "#/components/contentDescriptors/ContentKey"
@@ -196,7 +196,7 @@
       }
     ],
     "result": {
-      "$ref": "#/components/contentDescriptors/GossipResult"
+      "$ref": "#/components/contentDescriptors/PutContentResult"
     }
   }
 ]

From f7befbc642e2acf586fc373fa60b8e0fc14f4b29 Mon Sep 17 00:00:00 2001
From: bhartnett <51288821+bhartnett@users.noreply.github.com>
Date: Fri, 18 Oct 2024 20:58:49 +0800
Subject: [PATCH 2/5] Update validation wording.

---
 jsonrpc/src/methods/state.json | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/jsonrpc/src/methods/state.json b/jsonrpc/src/methods/state.json
index 9d38a33c..9a310630 100644
--- a/jsonrpc/src/methods/state.json
+++ b/jsonrpc/src/methods/state.json
@@ -126,7 +126,7 @@
   },
   {
     "name": "portal_stateGetContent",
-    "summary": "Get content from the local database if it exists, otherwise look up the target content key in the network. After fetching from the network the content is validated and stored in the local database if storage criteria is met before being returned.",
+    "summary": "Get content from the local database if it exists, otherwise look up the target content key in the network. After fetching from the network the content is validated for correctness and stored in the local database if storage criteria is met before being returned.",
     "params": [
       {
         "$ref": "#/components/contentDescriptors/ContentKey"
@@ -186,7 +186,7 @@
   },
   {
     "name": "portal_statePutContent",
-    "summary": "Validate and store the provided content in the local database if storage criteria is met, then send the content to interested peers. Clients may choose to send to some or all peers.",
+    "summary": "Validate that the content is well formed and store it in the local database if storage criteria is met, then send the content to interested peers. Clients may choose to send to some or all peers.",
     "params": [
       {
         "$ref": "#/components/contentDescriptors/ContentKey"

From c4aae4f62000dc0d25dfe50579067f5390d7466a Mon Sep 17 00:00:00 2001
From: bhartnett <51288821+bhartnett@users.noreply.github.com>
Date: Fri, 18 Oct 2024 21:06:20 +0800
Subject: [PATCH 3/5] Update validation wording.

---
 jsonrpc/src/methods/beacon.json  |  4 ++--
 jsonrpc/src/methods/history.json | 28 +++++++++++++++++-----------
 2 files changed, 19 insertions(+), 13 deletions(-)

diff --git a/jsonrpc/src/methods/beacon.json b/jsonrpc/src/methods/beacon.json
index b5ae6426..c9a72c50 100644
--- a/jsonrpc/src/methods/beacon.json
+++ b/jsonrpc/src/methods/beacon.json
@@ -134,7 +134,7 @@
   },
   {
     "name": "portal_beaconGetContent",
-    "summary": "Get content from the local database if it exists, otherwise look up the target content key in the network. After fetching from the network the content is validated and stored in the local database if storage criteria is met before being returned.",
+    "summary": "Get content from the local database if it exists, otherwise look up the target content key in the network. After fetching from the network the content is validated for correctness and stored in the local database if storage criteria is met before being returned.",
     "params": [
       {
         "$ref": "#/components/contentDescriptors/ContentKey"
@@ -200,7 +200,7 @@
   },
   {
     "name": "portal_beaconPutContent",
-    "summary": "Validate and store the provided content in the local database if storage criteria is met, then send the content to interested peers. Clients may choose to send to some or all peers.",
+    "summary": "Validate that the content is well formed and store it in the local database if storage criteria is met, then send the content to interested peers. Clients may choose to send to some or all peers.",
     "params": [
       {
         "$ref": "#/components/contentDescriptors/ContentKey"
diff --git a/jsonrpc/src/methods/history.json b/jsonrpc/src/methods/history.json
index e983c3d5..2ee99c11 100644
--- a/jsonrpc/src/methods/history.json
+++ b/jsonrpc/src/methods/history.json
@@ -126,7 +126,7 @@
   },
   {
     "name": "portal_historyGetContent",
-    "summary": "Get content from the local database if it exists, otherwise look up the target content key in the network. After fetching from the network the content is validated and stored in the local database if storage criteria is met before being returned.",
+    "summary": "Get content from the local database if it exists, otherwise look up the target content key in the network. After fetching from the network the content is validated for correctness and stored in the local database if storage criteria is met before being returned.",
     "params": [
       {
         "$ref": "#/components/contentDescriptors/ContentKey"
@@ -135,9 +135,11 @@
     "result": {
       "$ref": "#/components/contentDescriptors/GetContentResult"
     },
-    "errors":[{
-      "$ref": "#/components/errors/ContentNotFoundError"
-    }]
+    "errors": [
+      {
+        "$ref": "#/components/errors/ContentNotFoundError"
+      }
+    ]
   },
   {
     "name": "portal_historyTraceGetContent",
@@ -150,9 +152,11 @@
     "result": {
       "$ref": "#/components/contentDescriptors/TraceGetContentResult"
     },
-    "errors":[{
-      "$ref": "#/components/errors/ContentNotFoundErrorWithTrace"
-    }]
+    "errors": [
+      {
+        "$ref": "#/components/errors/ContentNotFoundErrorWithTrace"
+      }
+    ]
   },
   {
     "name": "portal_historyStore",
@@ -180,13 +184,15 @@
     "result": {
       "$ref": "#/components/contentDescriptors/LocalContentResult"
     },
-    "errors":[{
-      "$ref": "#/components/errors/ContentNotFoundError"
-    }]
+    "errors": [
+      {
+        "$ref": "#/components/errors/ContentNotFoundError"
+      }
+    ]
   },
   {
     "name": "portal_historyPutContent",
-    "summary": "Validate and store the provided content in the local database if storage criteria is met, then send the content to interested peers. Clients may choose to send to some or all peers.",
+    "summary": "Validate that the content is well formed and store it in the local database if storage criteria is met, then send the content to interested peers. Clients may choose to send to some or all peers.",
     "params": [
       {
         "$ref": "#/components/contentDescriptors/ContentKey"

From 64785fa94032253808ed14f10af999c63e6a935e Mon Sep 17 00:00:00 2001
From: bhartnett <51288821+bhartnett@users.noreply.github.com>
Date: Mon, 21 Oct 2024 21:28:58 +0800
Subject: [PATCH 4/5] Remove references to validation from RPC method
 descriptions.

---
 jsonrpc/src/methods/beacon.json  | 4 ++--
 jsonrpc/src/methods/history.json | 4 ++--
 jsonrpc/src/methods/state.json   | 4 ++--
 3 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/jsonrpc/src/methods/beacon.json b/jsonrpc/src/methods/beacon.json
index c9a72c50..70bfa57b 100644
--- a/jsonrpc/src/methods/beacon.json
+++ b/jsonrpc/src/methods/beacon.json
@@ -134,7 +134,7 @@
   },
   {
     "name": "portal_beaconGetContent",
-    "summary": "Get content from the local database if it exists, otherwise look up the target content key in the network. After fetching from the network the content is validated for correctness and stored in the local database if storage criteria is met before being returned.",
+    "summary": "Get content from the local database if it exists, otherwise look up the target content key in the network. After fetching from the network the content is stored in the local database if storage criteria is met before being returned.",
     "params": [
       {
         "$ref": "#/components/contentDescriptors/ContentKey"
@@ -200,7 +200,7 @@
   },
   {
     "name": "portal_beaconPutContent",
-    "summary": "Validate that the content is well formed and store it in the local database if storage criteria is met, then send the content to interested peers. Clients may choose to send to some or all peers.",
+    "summary": "Store the content in the local database if storage criteria is met, then send the content to interested peers. Clients may choose to send to some or all peers.",
     "params": [
       {
         "$ref": "#/components/contentDescriptors/ContentKey"
diff --git a/jsonrpc/src/methods/history.json b/jsonrpc/src/methods/history.json
index 2ee99c11..43cffb2e 100644
--- a/jsonrpc/src/methods/history.json
+++ b/jsonrpc/src/methods/history.json
@@ -126,7 +126,7 @@
   },
   {
     "name": "portal_historyGetContent",
-    "summary": "Get content from the local database if it exists, otherwise look up the target content key in the network. After fetching from the network the content is validated for correctness and stored in the local database if storage criteria is met before being returned.",
+    "summary": "Get content from the local database if it exists, otherwise look up the target content key in the network. After fetching from the network the content is stored in the local database if storage criteria is met before being returned.",
     "params": [
       {
         "$ref": "#/components/contentDescriptors/ContentKey"
@@ -192,7 +192,7 @@
   },
   {
     "name": "portal_historyPutContent",
-    "summary": "Validate that the content is well formed and store it in the local database if storage criteria is met, then send the content to interested peers. Clients may choose to send to some or all peers.",
+    "summary": "Store the content in the local database if storage criteria is met, then send the content to interested peers. Clients may choose to send to some or all peers.",
     "params": [
       {
         "$ref": "#/components/contentDescriptors/ContentKey"
diff --git a/jsonrpc/src/methods/state.json b/jsonrpc/src/methods/state.json
index 9a310630..4d9bd256 100644
--- a/jsonrpc/src/methods/state.json
+++ b/jsonrpc/src/methods/state.json
@@ -126,7 +126,7 @@
   },
   {
     "name": "portal_stateGetContent",
-    "summary": "Get content from the local database if it exists, otherwise look up the target content key in the network. After fetching from the network the content is validated for correctness and stored in the local database if storage criteria is met before being returned.",
+    "summary": "Get content from the local database if it exists, otherwise look up the target content key in the network. After fetching from the network the content is stored in the local database if storage criteria is met before being returned.",
     "params": [
       {
         "$ref": "#/components/contentDescriptors/ContentKey"
@@ -186,7 +186,7 @@
   },
   {
     "name": "portal_statePutContent",
-    "summary": "Validate that the content is well formed and store it in the local database if storage criteria is met, then send the content to interested peers. Clients may choose to send to some or all peers.",
+    "summary": "Store the content in the local database if storage criteria is met, then send the content to interested peers. Clients may choose to send to some or all peers.",
     "params": [
       {
         "$ref": "#/components/contentDescriptors/ContentKey"

From a12e4fcb1c5bcbaeee6d7cb92c4f33356709c3ea Mon Sep 17 00:00:00 2001
From: bhartnett <51288821+bhartnett@users.noreply.github.com>
Date: Tue, 3 Dec 2024 11:36:18 +0800
Subject: [PATCH 5/5] PR comment updates.

---
 jsonrpc/src/content/results.json | 19 ++++++++++++++++---
 jsonrpc/src/methods/beacon.json  |  2 +-
 jsonrpc/src/methods/history.json |  2 +-
 jsonrpc/src/methods/state.json   |  2 +-
 4 files changed, 19 insertions(+), 6 deletions(-)

diff --git a/jsonrpc/src/content/results.json b/jsonrpc/src/content/results.json
index 6aec591c..b991f74b 100644
--- a/jsonrpc/src/content/results.json
+++ b/jsonrpc/src/content/results.json
@@ -222,10 +222,23 @@
   },
   "PutContentResult": {
     "name": "PutContentResult",
-    "description": "Returns the number of peers that the content was gossiped to",
+    "description": "Returns the number of peers that the content was gossiped to and a flag indicating whether the content was stored locally or not.",
     "schema": {
-      "title": "number of peers",
-      "type": "number"
+      "type": "object",
+      "required": [
+        "peerCount",
+        "storedLocally"
+      ],
+      "properties": {
+        "peerCount": {
+          "description": "Indicates how many peers the content was gossiped to.",
+          "type": "number"
+        },
+        "storedLocally": {
+          "description": "Indicates whether the content was stored locally or not.",
+          "type": "boolean"
+        }
+      }
     }
   }
 }
diff --git a/jsonrpc/src/methods/beacon.json b/jsonrpc/src/methods/beacon.json
index 70bfa57b..dd69f364 100644
--- a/jsonrpc/src/methods/beacon.json
+++ b/jsonrpc/src/methods/beacon.json
@@ -200,7 +200,7 @@
   },
   {
     "name": "portal_beaconPutContent",
-    "summary": "Store the content in the local database if storage criteria is met, then send the content to interested peers. Clients may choose to send to some or all peers.",
+    "summary": "Store the content in the local database if storage criteria is met, then send the content to interested peers using the client's default gossip mechanisms.",
     "params": [
       {
         "$ref": "#/components/contentDescriptors/ContentKey"
diff --git a/jsonrpc/src/methods/history.json b/jsonrpc/src/methods/history.json
index 43cffb2e..d0c166d4 100644
--- a/jsonrpc/src/methods/history.json
+++ b/jsonrpc/src/methods/history.json
@@ -192,7 +192,7 @@
   },
   {
     "name": "portal_historyPutContent",
-    "summary": "Store the content in the local database if storage criteria is met, then send the content to interested peers. Clients may choose to send to some or all peers.",
+    "summary": "Store the content in the local database if storage criteria is met, then send the content to interested peers using the client's default gossip mechanisms.",
     "params": [
       {
         "$ref": "#/components/contentDescriptors/ContentKey"
diff --git a/jsonrpc/src/methods/state.json b/jsonrpc/src/methods/state.json
index 4d9bd256..bc16a28f 100644
--- a/jsonrpc/src/methods/state.json
+++ b/jsonrpc/src/methods/state.json
@@ -186,7 +186,7 @@
   },
   {
     "name": "portal_statePutContent",
-    "summary": "Store the content in the local database if storage criteria is met, then send the content to interested peers. Clients may choose to send to some or all peers.",
+    "summary": "Store the content in the local database if storage criteria is met, then send the content to interested peers using the client's default gossip mechanisms.",
     "params": [
       {
         "$ref": "#/components/contentDescriptors/ContentKey"