@agoric/network 0.1.1-dev-91a9ad7.0.91a9ad7 → 0.1.1-dev-c35956d.0.c35956d

package/README.md

@@ -48,7 +48,7 @@ You must also prepare a `ConnectionHandler` object to manage the connection you'
 Then you will call the `connect()` method on your local `Port`. This will return a `Promise` that will fire with a new `Connection` object, on which you can send data. Your `ConnectionHandler` will be notified about the new channel, and will receive inbound data from the other side.
 
 ```js
-import { encodeIbcEndpoint } from '@agoric/vats/tools/ibc-utils.js';
+import { encodeIbcEndpoint } from '@agoric/network/ibc/utils.js';
 const remoteEndpoint = encodeIbcEndpoint({
   hops: [connectionID],
   portID,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agoric/network",
-  "version": "0.1.1-dev-91a9ad7.0.91a9ad7",
+  "version": "0.1.1-dev-c35956d.0.c35956d",
   "description": "Agoric's network protocol API",
   "type": "module",
   "main": "./src/index.js",
@@ -21,9 +21,9 @@
   "author": "Agoric",
   "license": "Apache-2.0",
   "dependencies": {
-    "@agoric/internal": "0.3.3-dev-91a9ad7.0.91a9ad7",
-    "@agoric/store": "0.9.3-dev-91a9ad7.0.91a9ad7",
-    "@agoric/vat-data": "0.5.3-dev-91a9ad7.0.91a9ad7",
+    "@agoric/internal": "0.3.3-dev-c35956d.0.c35956d",
+    "@agoric/store": "0.9.3-dev-c35956d.0.c35956d",
+    "@agoric/vat-data": "0.5.3-dev-c35956d.0.c35956d",
     "@endo/base64": "^1.0.12",
     "@endo/errors": "^1.2.13",
     "@endo/far": "^1.1.14",
@@ -32,16 +32,19 @@
     "@endo/promise-kit": "^1.1.13"
   },
   "devDependencies": {
-    "@agoric/swingset-liveslots": "0.10.3-dev-91a9ad7.0.91a9ad7",
-    "@agoric/swingset-vat": "0.32.3-dev-91a9ad7.0.91a9ad7",
-    "@agoric/vow": "0.1.1-dev-91a9ad7.0.91a9ad7",
-    "@agoric/zone": "0.2.3-dev-91a9ad7.0.91a9ad7",
+    "@agoric/cosmic-proto": "0.4.1-dev-c35956d.0.c35956d",
+    "@agoric/swingset-liveslots": "0.10.3-dev-c35956d.0.c35956d",
+    "@agoric/swingset-vat": "0.32.3-dev-c35956d.0.c35956d",
+    "@agoric/vow": "0.1.1-dev-c35956d.0.c35956d",
+    "@agoric/zone": "0.2.3-dev-c35956d.0.c35956d",
     "@endo/bundle-source": "^4.1.2",
     "ava": "^6.4.1",
     "c8": "^10.1.3"
   },
   "exports": {
-    ".": "./src/index.js"
+    ".": "./src/index.js",
+    "./ibc": "./src/ibc/index.js",
+    "./ibc/utils.js": "./src/ibc/utils.js"
   },
   "files": [
     "CHANGELOG.md",
@@ -67,5 +70,5 @@
   "typeCoverage": {
     "atLeast": 91.16
   },
-  "gitHead": "91a9ad7ba5458194cd2e3f952738997cbcc55a38"
+  "gitHead": "c35956dcf414e6cc7f24db886cb647f36cb1eb90"
 }

package/src/ibc/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/src/ibc/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["index.js"],"names":[],"mappings":""}

package/src/ibc/index.js

@@ -0,0 +1 @@
+export * from './types.js';

package/src/ibc/types.d.ts

@@ -0,0 +1,36 @@
+import type { State as IBCChannelState, Order } from '@agoric/cosmic-proto/ibc/core/channel/v1/channel.js';
+import type { State as IBCConnectionState } from '@agoric/cosmic-proto/ibc/core/connection/v1/connection.js';
+export type RemoteIbcAddress = `/${string}ibc-port/${string}/${'ordered' | 'unordered'}/${string}`;
+export type LocalIbcAddress = `/ibc-port/${string}`;
+export type IBCConnectionID = `connection-${number}`;
+export type IBCChannelOrdering = 'ORDERED' | 'UNORDERED';
+export type IBCPortID = string;
+export type IBCChannelID = `channel-${number}`;
+export interface IBCEndpoint {
+    hops: IBCConnectionID[];
+    portID: IBCPortID;
+    order?: IBCChannelOrdering;
+    version?: string;
+    channelID?: IBCChannelID;
+}
+export interface IBCTransferChannelInfo {
+    portId: string;
+    channelId: IBCChannelID;
+    counterPartyPortId: string;
+    counterPartyChannelId: IBCChannelID;
+    ordering: Order;
+    state: IBCChannelState;
+    version: string;
+}
+/** Represents an IBC Connection between two chains, which can contain multiple Channels. */
+export interface IBCConnectionInfo {
+    id: IBCConnectionID;
+    client_id: string;
+    state: IBCConnectionState;
+    counterparty: {
+        client_id: string;
+        connection_id: IBCConnectionID;
+    };
+    transferChannel: IBCTransferChannelInfo;
+}
+//# sourceMappingURL=types.d.ts.map

package/src/ibc/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,KAAK,IAAI,eAAe,EACxB,KAAK,EACN,MAAM,qDAAqD,CAAC;AAC7D,OAAO,KAAK,EAAE,KAAK,IAAI,kBAAkB,EAAE,MAAM,2DAA2D,CAAC;AAE7G,MAAM,MAAM,gBAAgB,GAC1B,IAAI,MAAM,YAAY,MAAM,IAAI,SAAS,GAAG,WAAW,IAAI,MAAM,EAAE,CAAC;AACtE,MAAM,MAAM,eAAe,GAAG,aAAa,MAAM,EAAE,CAAC;AAEpD,MAAM,MAAM,eAAe,GAAG,cAAc,MAAM,EAAE,CAAC;AACrD,MAAM,MAAM,kBAAkB,GAAG,SAAS,GAAG,WAAW,CAAC;AACzD,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC;AAC/B,MAAM,MAAM,YAAY,GAAG,WAAW,MAAM,EAAE,CAAC;AAE/C,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,eAAe,EAAE,CAAC;IACxB,MAAM,EAAE,SAAS,CAAC;IAClB,KAAK,CAAC,EAAE,kBAAkB,CAAC;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,YAAY,CAAC;CAC1B;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,YAAY,CAAC;IACxB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,qBAAqB,EAAE,YAAY,CAAC;IACpC,QAAQ,EAAE,KAAK,CAAC;IAChB,KAAK,EAAE,eAAe,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,4FAA4F;AAC5F,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,eAAe,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,kBAAkB,CAAC;IAC1B,YAAY,EAAE;QACZ,SAAS,EAAE,MAAM,CAAC;QAClB,aAAa,EAAE,eAAe,CAAC;KAChC,CAAC;IACF,eAAe,EAAE,sBAAsB,CAAC;CACzC"}

package/src/ibc/types.js

@@ -0,0 +1,44 @@
+             
+                           
+        
+                                                             
+                                                                                                             
+
+                              
+                                                                      
+                                                    
+
+                                                     
+                                                         
+                               
+                                               
+
+                              
+                          
+                    
+                             
+                   
+                           
+ 
+
+                                         
+                 
+                          
+                             
+                                      
+                  
+                         
+                                     
+ 
+
+/** Represents an IBC Connection between two chains, which can contain multiple Channels. */
+                                    
+                                           
+                                         
+                            
+                 
+                      
+                                   
+    
+                                          
+ 

package/src/ibc/utils.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @file Conversion from IBC endpoints to Agoric Network API Endpoints
+ * @summary Utilities for constructing and parsing Agoric Network API IBC addresses, which
+ *   are used to identify IBC ports and channels in a Cosmos-participating
+ *   blockchain.
+ *
+ *   Agoric Network API addresses are roughly akin to Multiaddrs (@ref
+ *   https://github.com/multiformats/js-multiaddr) but with a less rigid
+ *   structure. Both share a similar textual representation, which is
+ *   encapsulated protocols and values separated by slashes.
+ */
+/**
+ * @import {Endpoint} from '../types.js';
+ * @import {
+ *   IBCChannelID,
+ *   IBCChannelOrdering,
+ *   IBCConnectionID,
+ *   IBCEndpoint,
+ *   IBCPortID,
+ *   LocalIbcAddress,
+ *   RemoteIbcAddress,
+ * } from './types.js';
+ */
+export const IBC_ADDR_RE: RegExp;
+export const VALID_ORDERS: readonly ["ordered", "unordered", "ORDERED", "UNORDERED"];
+export function encodeSlashes(raw: string): string;
+export function decodeSlashes(encoded: string): string;
+export function validateIbcAddress(addr: any): any;
+export function decodeIbcHops(h: string): IBCConnectionID[];
+export function decodeIbcEndpoint(addr: string): IBCEndpoint;
+export function encodeIbcEndpoint({ hops, portID, order: rawOrder, version, channelID, }: {
+    hops?: string[] | undefined;
+    portID: string;
+    order: "ordered" | "unordered" | "ORDERED" | "UNORDERED";
+    version: string;
+    channelID?: string | undefined;
+}): Endpoint;
+/**
+ * @overload
+ * @param {string} remoteAddr
+ * @param {undefined | false} [returnMatch]
+ * @returns {boolean}
+ */
+export function validateRemoteIbcAddress(remoteAddr: string, returnMatch?: undefined | false): boolean;
+/**
+ * @overload
+ * @param {string} remoteAddr
+ * @param {true} returnMatch
+ * @returns {RegExpMatchArray}
+ */
+export function validateRemoteIbcAddress(remoteAddr: string, returnMatch: true): RegExpMatchArray;
+export function decodeRemoteIbcAddress(remoteAddr: string): {
+    rPortID: string;
+    order: IBCChannelOrdering;
+    version: string;
+    hops: `connection-${number}`[];
+};
+export function localAddrToPortID(localAddr: LocalIbcAddress): string;
+export function encodeRemoteIbcAddress(hops: string[], portID: string, order: "ordered" | "unordered" | "ORDERED" | "UNORDERED", version: string, channelID?: string): RemoteIbcAddress;
+export function encodeLocalIbcAddress(portID: string, order: "ordered" | "unordered" | "ORDERED" | "UNORDERED", version: string): string;
+import type { IBCConnectionID } from './types.js';
+import type { IBCEndpoint } from './types.js';
+import type { Endpoint } from '../types.js';
+import type { IBCChannelOrdering } from './types.js';
+import type { LocalIbcAddress } from './types.js';
+import type { RemoteIbcAddress } from './types.js';
+//# sourceMappingURL=utils.d.ts.map

package/src/ibc/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["utils.js"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;;;;;;;;;GAWG;AAEH,iCACsJ;AAGtJ,qFAKG;AAII,mCADK,MAAM,UAC8C;AAIzD,uCADK,MAAM,UACsD;AAGjE,mDASN;AAQM,iCAHI,MAAM,GACJ,eAAe,EAAE,CAsB7B;AAOM,wCAHI,MAAM,GACJ,WAAW,CAkBvB;AAYM,0FAPJ;IAAwB,IAAI;IACP,MAAM,EAAnB,MAAM;IACkD,KAAK,EAA7D,SAAS,GAAG,WAAW,GAAG,SAAS,GAAG,WAAW;IACpC,OAAO,EAApB,MAAM;IACQ,SAAS;CAC/B,GAAU,QAAQ,CAwCpB;;;;;;;AAIE,qDACQ,MAAM,gBACN,SAAS,GAAG,KAAK,GACf,OAAO,CACnB;;;;;;;AAEE,qDACQ,MAAM,eACN,IAAI,GACF,gBAAgB,CAC5B;AA0BM,mDADK,MAAM;;;;;EAYjB;AAOM,6CAHI,eAAe,GACb,MAAM,CAqBlB;AAWM,6CAPI,MAAM,EAAE,UACR,MAAM,SACN,SAAS,GAAG,WAAW,GAAG,SAAS,GAAG,WAAW,WACjD,MAAM,cACN,MAAM,GACJ,gBAAgB,CAiB5B;AAQM,8CAJI,MAAM,SACN,SAAS,GAAG,WAAW,GAAG,SAAS,GAAG,WAAW,WACjD,MAAM,UAIhB;qCAtPS,YAAY;iCAAZ,YAAY;8BATK,aAAa;wCAS9B,YAAY;qCAAZ,YAAY;sCAAZ,YAAY"}

package/src/ibc/utils.js

@@ -0,0 +1,270 @@
+/**
+ * @file Conversion from IBC endpoints to Agoric Network API Endpoints
+ * @summary Utilities for constructing and parsing Agoric Network API IBC addresses, which
+ *   are used to identify IBC ports and channels in a Cosmos-participating
+ *   blockchain.
+ *
+ *   Agoric Network API addresses are roughly akin to Multiaddrs (@ref
+ *   https://github.com/multiformats/js-multiaddr) but with a less rigid
+ *   structure. Both share a similar textual representation, which is
+ *   encapsulated protocols and values separated by slashes.
+ */
+
+/**
+ * @import {Endpoint} from '../types.js';
+ * @import {
+ *   IBCChannelID,
+ *   IBCChannelOrdering,
+ *   IBCConnectionID,
+ *   IBCEndpoint,
+ *   IBCPortID,
+ *   LocalIbcAddress,
+ *   RemoteIbcAddress,
+ * } from './types.js';
+ */
+
+export const IBC_ADDR_RE =
+  /^(?<hops>\/ibc-hop\/[^/]+)*\/ibc-port\/(?<portID>[^/]+)(\/(?<order>ordered|unordered)\/(?<version>[^/]+)(\/ibc-channel\/(?<channelID>[^/]+))?)?$/s;
+harden(IBC_ADDR_RE);
+
+export const VALID_ORDERS = /** @type {const} */ ([
+  'ordered',
+  'unordered',
+  'ORDERED',
+  'UNORDERED',
+]);
+harden(VALID_ORDERS);
+
+/** @param {string} raw */
+export const encodeSlashes = raw => raw.replaceAll('/', '\\x2f');
+harden(encodeSlashes);
+
+/** @param {string} encoded */
+export const decodeSlashes = encoded => encoded.replaceAll('\\x2f', '/');
+harden(decodeSlashes);
+
+export const validateIbcAddress = addr => {
+  const match = addr.match(IBC_ADDR_RE);
+  // .groups is to inform TS
+  if (!(match && match.groups)) {
+    throw TypeError(
+      `IBC address ${addr} must be '(/ibc-hop/CONNECTION)*/ibc-port/PORT/(ordered|unordered)/VERSION(/ibc-channel/CHANNEL_ID)?'`,
+    );
+  }
+  return match;
+};
+
+/**
+ * Decode the /ibc-hop/CONNECTION segments of an IBC address.
+ *
+ * @param {string} h
+ * @returns {IBCConnectionID[]}
+ */
+export const decodeIbcHops = h => {
+  /** @type {IBCConnectionID[]} */
+  const hops = [];
+
+  /** @type {string} */
+  while (h) {
+    const m = h.match(/^\/ibc-hop\/(?<hop>[^/]+)/);
+    if (!m || !m.groups) {
+      throw Error(
+        `internal: ${JSON.stringify(h)} did not begin with "/ibc-hop/XXX"`,
+      );
+    }
+    h = h.slice(m[0].length);
+
+    const hop = /** @type {IBCConnectionID} */ (m.groups.hop);
+    assert(typeof hop === 'string' && hop.startsWith('connection-'));
+    hops.push(hop);
+  }
+
+  return hops;
+};
+harden(decodeIbcHops);
+
+/**
+ * @param {string} addr
+ * @returns {IBCEndpoint}
+ */
+export const decodeIbcEndpoint = addr => {
+  const match = validateIbcAddress(addr);
+  if (!match.groups)
+    throw Error('Unexpected error, validateRemoteIbcAddress should throw.');
+
+  const hops = decodeIbcHops(match.groups.hops);
+
+  // Generate a circuit.
+  const { portID, version, channelID, order } = match.groups;
+  return {
+    hops,
+    portID,
+    ...(order && { order: order.toUpperCase() }),
+    ...(version && { version: decodeSlashes(version) }),
+    ...(channelID && { channelID }),
+  };
+};
+harden(decodeIbcEndpoint);
+
+/**
+ * @param {object} spec
+ * @param {string[]} [spec.hops]
+ * @param {string} spec.portID
+ * @param {'ordered' | 'unordered' | 'ORDERED' | 'UNORDERED'} spec.order
+ * @param {string} spec.version
+ * @param {string} [spec.channelID]
+ * @returns {Endpoint}
+ */
+export const encodeIbcEndpoint = ({
+  hops = [],
+  portID,
+  order: rawOrder,
+  version,
+  channelID,
+}) => {
+  const isLegitString = str =>
+    typeof str === 'string' && str && !str.includes('/');
+  let addr = '';
+  assert(Array.isArray(hops), 'hops must be an array');
+  for (const hop of hops) {
+    assert(isLegitString(hop), `invalid hop ${hop}`);
+    addr += `/ibc-hop/${hop}`;
+  }
+  assert(isLegitString(portID), `invalid portID ${portID}`);
+  addr += `/ibc-port/${portID}`;
+
+  if (rawOrder !== undefined) {
+    assert(isLegitString(rawOrder), `invalid order ${rawOrder}`);
+
+    assert(
+      VALID_ORDERS.includes(rawOrder),
+      `invalid order ${rawOrder}; ${rawOrder} not found in ${JSON.stringify(VALID_ORDERS)}`,
+    );
+
+    const order = rawOrder.toLowerCase();
+
+    assert(typeof version === 'string' && version, 'missing version');
+    addr += `/${order}/${encodeSlashes(version)}`;
+
+    if (channelID !== undefined) {
+      assert(isLegitString(channelID), `invalid channelID ${channelID}`);
+      addr += `/ibc-channel/${channelID}`;
+    }
+  }
+
+  return addr;
+};
+harden(encodeIbcEndpoint);
+
+/**
+ * @overload
+ * @param {string} remoteAddr
+ * @param {undefined | false} [returnMatch]
+ * @returns {boolean}
+ */
+/**
+ * @overload
+ * @param {string} remoteAddr
+ * @param {true} returnMatch
+ * @returns {RegExpMatchArray}
+ */
+/**
+ * Validates a remote IBC address format and returns true if the address is
+ * valid.
+ *
+ * @param {string} remoteAddr
+ * @param {boolean} [returnMatch]
+ */
+export const validateRemoteIbcAddress = (remoteAddr, returnMatch = false) => {
+  const match = validateIbcAddress(remoteAddr);
+  // .groups is to inform TS https://github.com/microsoft/TypeScript/issues/32098
+  if (!(match && match.groups)) {
+    throw TypeError(
+      `Remote address ${remoteAddr} must be '(/ibc-hop/CONNECTION)*/ibc-port/PORT/(ordered|unordered)/VERSION'`,
+    );
+  }
+  if (match.groups.channelID) {
+    throw TypeError(
+      `Remote address ${remoteAddr} must not include channelID; found ${match.groups.channelID}`,
+    );
+  }
+  return returnMatch ? match : true;
+};
+harden(validateRemoteIbcAddress);
+
+/** @param {string} remoteAddr */
+export const decodeRemoteIbcAddress = remoteAddr => {
+  validateRemoteIbcAddress(remoteAddr);
+  const {
+    hops,
+    portID: rPortID,
+    order,
+    version,
+  } = decodeIbcEndpoint(remoteAddr);
+  assert(order !== undefined, 'missing order');
+  assert(version !== undefined, 'missing version');
+  return { rPortID, order, version, hops };
+};
+harden(decodeRemoteIbcAddress);
+
+/**
+ * @param {LocalIbcAddress} localAddr
+ * @returns {string}
+ */
+export const localAddrToPortID = localAddr => {
+  const m = localAddr.match(IBC_ADDR_RE);
+  // .groups is to inform TS https://github.com/microsoft/TypeScript/issues/32098
+  if (!(m && m.groups)) {
+    throw TypeError(
+      `Invalid port specification ${localAddr}; expected "/ibc-port/PORT"`,
+    );
+  }
+  for (const group of Object.keys(m.groups)) {
+    if (group === 'portID') {
+      continue;
+    }
+    if (m.groups[group] !== undefined) {
+      throw TypeError(
+        `Invalid port specification ${localAddr}; unexpected ${group}=${m.groups[group]}`,
+      );
+    }
+  }
+  return m.groups.portID;
+};
+harden(localAddrToPortID);
+
+/**
+ * @param {string[]} hops
+ * @param {string} portID
+ * @param {'ordered' | 'unordered' | 'ORDERED' | 'UNORDERED'} order
+ * @param {string} version
+ * @param {string} [channelID]
+ * @returns {RemoteIbcAddress}
+ */
+export const encodeRemoteIbcAddress = (
+  hops,
+  portID,
+  order,
+  version,
+  channelID,
+) => {
+  const ep = encodeIbcEndpoint({
+    hops,
+    portID,
+    order,
+    version,
+    ...(channelID && { channelID }),
+  });
+  return /** @type {RemoteIbcAddress} */ (ep);
+};
+harden(encodeRemoteIbcAddress);
+
+/**
+ * @param {string} portID
+ * @param {'ordered' | 'unordered' | 'ORDERED' | 'UNORDERED'} order
+ * @param {string} version
+ */
+export const encodeLocalIbcAddress = (portID, order, version) => {
+  return encodeIbcEndpoint({ portID, order, version });
+};
+harden(encodeLocalIbcAddress);