Merge pull request #8979 from Agoric/dc-net-power-docs

docs(network): networkVat core eval usage; scrub TODOs
Agoric · Mar 2, 2024 · fd864a4 · fd864a4
2 parents de159f2 + 6136a64
commit fd864a4
Show file tree

Hide file tree

Showing 2 changed files with 28 additions and 6 deletions.
diff --git 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.
       },
     },
   );

diff --git 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> };