From 35e62c45dc09717457426033a1283e681d961e21 Mon Sep 17 00:00:00 2001
From: Dan Connolly <connolly@agoric.com>
Date: Fri, 23 Feb 2024 17:14:01 -0600
Subject: [PATCH 1/2] docs(network): scrub TODOs

---
 packages/network/src/network.js | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/packages/network/src/network.js b/packages/network/src/network.js
index 9061aa235be..6bfca90bd7b 100644
--- a/packages/network/src/network.js
+++ b/packages/network/src/network.js
@@ -484,7 +484,7 @@ const preparePort = (zone, { when }) => {
           listening.init(localAddr, harden([this.self, listenHandler]));
         }
 
-        // TODO: Check that the listener defines onAccept.
+        // ASSUME: that the listener defines onAccept.
 
         await when(
           E(protocolHandler).onListen(
@@ -945,14 +945,14 @@ export function prepareLoopbackProtocolHandler(zone, { when }) {
     },
     {
       async onCreate(_impl, _protocolHandler) {
-        // TODO
+        // noop
       },
       async generatePortID(_localAddr, _protocolHandler) {
         this.state.portNonce += 1n;
         return `port${this.state.portNonce}`;
       },
       async onBind(_port, _localAddr, _protocolHandler) {
-        // TODO: Maybe handle a bind?
+        // noop, for now; Maybe handle a bind?
       },
       async onConnect(
         _port,
@@ -988,11 +988,11 @@ export function prepareLoopbackProtocolHandler(zone, { when }) {
       async onListen(port, localAddr, listenHandler, _protocolHandler) {
         const { listeners } = this.state;
 
-        // TODO: Implement other listener replacement policies.
+        // This implementation has a simple last-one-wins replacement policy.
+        // Other handlers might use different policies.
         if (listeners.has(localAddr)) {
           const lhandler = listeners.get(localAddr)[1];
           if (lhandler !== listenHandler) {
-            // Last-one-wins.
             listeners.set(localAddr, [port, listenHandler]);
           }
         } else {
@@ -1014,7 +1014,7 @@ export function prepareLoopbackProtocolHandler(zone, { when }) {
         listeners.delete(localAddr);
       },
       async onRevoke(_port, _localAddr, _protocolHandler) {
-        // TODO: maybe clean up?
+        // This is an opportunity to clean up resources.
       },
     },
   );

From 6136a641d47453b71ef94ff5baba88e72564868d Mon Sep 17 00:00:00 2001
From: Dan Connolly <connolly@agoric.com>
Date: Fri, 23 Feb 2024 17:24:42 -0600
Subject: [PATCH 2/2] docs(network): networkVat powers are to be shared via
 Ports

---
 .../vats/src/proposals/network-proposal.js    | 22 +++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/packages/vats/src/proposals/network-proposal.js b/packages/vats/src/proposals/network-proposal.js
index 729abbf033d..817d785d6ca 100644
--- a/packages/vats/src/proposals/network-proposal.js
+++ b/packages/vats/src/proposals/network-proposal.js
@@ -1,3 +1,7 @@
+/**
+ * @file CoreEval module to set up network, IBC vats.
+ * @see {setupNetworkProtocols}
+ */
 import { E } from '@endo/far';
 import { BridgeId as BRIDGE_ID } from '@agoric/internal';
 import { prepareVowTools } from '@agoric/vat-data/vow.js';
@@ -47,6 +51,24 @@ export const registerNetworkProtocols = async (vats, dibcBridgeManager) => {
 };
 
 /**
+ * Create the network and IBC vats; produce `networkVat` in the core / bootstrap
+ * space.
+ *
+ * The `networkVat` is CLOSELY HELD in the core space, where later, we claim
+ * ports using `E(networkVat).bind(_path_)`. As discussed in `ProtocolHandler`
+ * docs, _path_ is:
+ *
+ * - /ibc-port/NAME for an IBC port with a known name or,
+ * - /ibc-port/ for an IBC port with a fresh name.
+ *
+ * Contracts are expected to use the services of the network and IBC vats by way
+ * of such ports.
+ *
+ * Testing facilities include:
+ *
+ * - loopback ports: `E(networkVat).bind('/local/')`
+ * - an echo port: `E(vats.network).bind('/ibc-port/echo')`
+ *
  * @param {BootstrapPowers & {
  *   consume: { loadCriticalVat: VatLoader<any> };
  *   produce: { networkVat: Producer<any> };