From faf850c2de8a0fbf7115a97242a611ef5b7a2da6 Mon Sep 17 00:00:00 2001
From: Kyle Peacock <kylpeacock@gmail.com>
Date: Thu, 19 May 2022 15:42:44 -0700
Subject: [PATCH] feat: CanisterStatus utility (#572)

---
 .nvmrc                                        |   2 +-
 docs/generated/changelog.html                 |  23 ++
 packages/agent/package.json                   |   2 +-
 .../__snapshots__/index.test.ts.snap          |  87 +++++++
 .../agent/src/canisterStatus/index.test.ts    | 180 ++++++++++++++
 packages/agent/src/canisterStatus/index.ts    | 232 ++++++++++++++++++
 packages/agent/src/index.ts                   |   9 +
 packages/candid/src/index.ts                  |   1 +
 8 files changed, 534 insertions(+), 2 deletions(-)
 create mode 100644 packages/agent/src/canisterStatus/__snapshots__/index.test.ts.snap
 create mode 100644 packages/agent/src/canisterStatus/index.test.ts
 create mode 100644 packages/agent/src/canisterStatus/index.ts

diff --git a/.nvmrc b/.nvmrc
index bc467a161..0d68f8a0e 100644
--- a/.nvmrc
+++ b/.nvmrc
@@ -1 +1 @@
-14.15
\ No newline at end of file
+16.0
diff --git a/docs/generated/changelog.html b/docs/generated/changelog.html
index e42febf40..f212bd2d4 100644
--- a/docs/generated/changelog.html
+++ b/docs/generated/changelog.html
@@ -16,6 +16,29 @@ <h2>Version 0.11.2</h2>
           Adds a default callback to the IdleManager that will refresh the page after clearing the
           storage
         </li>
+        <li>
+          Adds a new utility method,
+          <pre>canisterStatus</pre>
+          , to @agent/js. Canister status now allows you to query paths from the canister
+          certificate with a simple interface, using the API from the<a
+            href="https://smartcontracts.org/docs/current/references/ic-interface-spec#state-tree-canister-information"
+            >interface specification</a
+          ><br />
+          Comes with nicely configured options for
+          <pre>time</pre>
+          ,
+          <pre>controllers</pre>
+          ,
+          <pre>subnet</pre>
+          ,
+          <pre>module_hash</pre>
+          , and
+          <pre>candid</pre>
+          . Additionally, has a utility for reading custom MetaData set using
+          <a href="https://github.com/dfinity/ic-wasm">ic-wasm</a>, as well as generic custom paths
+          in the format of ArrayBuffers.
+        </li>
+        <li>updates to package.json files for metadata in npm</li>
       </ul>
       <h2>Version 0.11.1</h2>
       <ul>
diff --git a/packages/agent/package.json b/packages/agent/package.json
index 979a33652..91ce24e68 100644
--- a/packages/agent/package.json
+++ b/packages/agent/package.json
@@ -11,7 +11,7 @@
     "directory": "packages/agent"
   },
   "bugs": {
-      "url": "https://github.com/dfinity/agent-js/issues"
+    "url": "https://github.com/dfinity/agent-js/issues"
   },
   "keywords": [
     "internet computer",
diff --git a/packages/agent/src/canisterStatus/__snapshots__/index.test.ts.snap b/packages/agent/src/canisterStatus/__snapshots__/index.test.ts.snap
new file mode 100644
index 000000000..098eeaeb6
--- /dev/null
+++ b/packages/agent/src/canisterStatus/__snapshots__/index.test.ts.snap
@@ -0,0 +1,87 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`Canister Status utility should query canister controllers 1`] = `
+Array [
+  Principal {
+    "_arr": Uint8Array [
+      0,
+      0,
+      0,
+      0,
+      0,
+      0,
+      0,
+      0,
+      1,
+      1,
+    ],
+    "_isPrincipal": true,
+  },
+]
+`;
+
+exports[`Canister Status utility should query canister module hash 1`] = `"896f6c079f96bc3cbef782af1ab1b52847f04700ff916eb49425566995a9a064"`;
+
+exports[`Canister Status utility should query the candid interface 1`] = `
+"type Example = text;
+service : {
+  greet: (Example) -> (text) query;
+}
+"
+`;
+
+exports[`Canister Status utility should query the time 1`] = `2022-05-19T20:58:22.596Z`;
+
+exports[`Canister Status utility should support multiple requests 1`] = `2022-05-19T20:58:22.596Z`;
+
+exports[`Canister Status utility should support multiple requests 2`] = `
+Array [
+  Principal {
+    "_arr": Uint8Array [
+      0,
+      0,
+      0,
+      0,
+      0,
+      0,
+      0,
+      0,
+      1,
+      1,
+    ],
+    "_isPrincipal": true,
+  },
+]
+`;
+
+exports[`Canister Status utility should support multiple requests with a failure 1`] = `2022-05-19T20:58:22.596Z`;
+
+exports[`Canister Status utility should support valid custom paths 1`] = `1652993902596160000n`;
+
+exports[`Canister Status utility should support valid custom paths 2`] = `ArrayBuffer []`;
+
+exports[`Canister Status utility should support valid custom paths 3`] = `"80f485e1a4a6a7f816"`;
+
+exports[`Canister Status utility should support valid custom paths 4`] = `
+Array [
+  Uint8Array [
+    4,
+  ],
+  Uint8Array [
+    0,
+    0,
+    0,
+    0,
+    0,
+    0,
+    0,
+    0,
+    1,
+    1,
+  ],
+]
+`;
+
+exports[`Canister Status utility should support valid metadata queries 1`] = `"74797065204578616d706c65203d20746578743b0a73657276696365203a207b0a202067726565743a20284578616d706c6529202d3e202874657874292071756572793b0a7d0a"`;
+
+exports[`Canister Status utility should support valid metadata queries 2`] = `"74797065204578616d706c65203d20746578743b0a73657276696365203a207b0a202067726565743a20284578616d706c6529202d3e202874657874292071756572793b0a7d0a"`;
diff --git a/packages/agent/src/canisterStatus/index.test.ts b/packages/agent/src/canisterStatus/index.test.ts
new file mode 100644
index 000000000..de6a7dc36
--- /dev/null
+++ b/packages/agent/src/canisterStatus/index.test.ts
@@ -0,0 +1,180 @@
+import { request, Path, encodePath } from './index';
+import { Ed25519KeyIdentity } from '@dfinity/identity';
+import { Principal } from '@dfinity/principal';
+import { fromHexString } from '@dfinity/candid';
+import { Identity } from '../auth';
+import fetch from 'node-fetch';
+import { HttpAgent } from '../agent';
+import { fromHex, toHex } from '../utils/buffer';
+
+const testPrincipal = Principal.fromText('rrkah-fqaaa-aaaaa-aaaaq-cai');
+
+// bypass bls verification so that an old certificate is accepted
+jest.mock('../utils/bls', () => {
+  return {
+    blsVerify: jest.fn(() => Promise.resolve(true)),
+  };
+});
+
+// Utils
+const encoder = new TextEncoder();
+const encode = (arg: string): ArrayBuffer => {
+  return new DataView(encoder.encode(arg).buffer).buffer;
+};
+const canisterBuffer = new DataView(testPrincipal.toUint8Array().buffer).buffer;
+
+/* Produced by deploying a dfx new canister and requesting
+  | 'time'
+  | 'controllers'
+  | 'subnet'
+  | 'moduleHash'
+  | 'candid'
+  in dfx 0.10.0
+  */
+const testCases = [
+  {
+    certificate:
+      'd9d9f7a2647472656583018301830183024863616e697374657283018301820458204c805d47bd74dbcd6c8ce23ebd2e8287c453895165db6b81d93f1daf1b12004683024a0000000000000001010183018301820458205a1ee5770842c74b6749f4d72e3c1b8c0dafdaff48e113d19da4fda687df0636830183024b636f6e74726f6c6c657273820351d9d9f78241044a000000000000000001018302486d657461646174618301830182045820e8071e9c904063629f9ab66d4a447b7a881a964d16757762f424d2ef6c6a776b83024e63616e6469643a736572766963658203584774797065204578616d706c65203d20746578743b0a73657276696365203a207b0a202067726565743a20284578616d706c6529202d3e202874657874292071756572793b0a7d0a820458203676da3cc701ead8143596204d845c31a11d483dccffd5f80e5530660322212883024b6d6f64756c655f6861736882035820896f6c079f96bc3cbef782af1ab1b52847f04700ff916eb49425566995a9a064820458202d41b194a0931a274d874a4de945f104fbcf45de1bb201ec2bbdcb036c21fb0f82045820aa2f527164a8e4d898febf2bc0a8a4f95da58c3b62c6e4185e610e7b40dc615082045820fa572fdf7872444dba23377a8a426906c4314a61ef470df0af1b173b13abe949830182045820ec68f8bfb2a3f70cf8d3d427ff595e6ddb5d4230a8c3ca1d3ccb06e7694fd83283024474696d6582034980f485e1a4a6a7f816697369676e61747572655830adbb57f847e2656f248d3eec467af3c89eb5c63fa8d56bd3a3f48e3f3c570e50d0f824502fc69772d0d637190c52e4e4',
+  },
+];
+
+// Used for repopulating the certificate
+const getRealStatus = async () => {
+  const identity = (await Ed25519KeyIdentity.generate(
+    new Uint8Array(
+      fromHexString('foo23342sd-234-234a-asdf-asdf-asdf-4frsefrsdf-weafasdfe-easdfee'),
+    ),
+  )) as unknown as Identity;
+
+  const agent = new HttpAgent({ host: 'http://127.0.0.1:8000', fetch, identity });
+  await agent.fetchRootKey();
+  const canisterBuffer = new DataView(testPrincipal.toUint8Array().buffer).buffer;
+  canisterBuffer;
+  const response = await agent.readState(
+    testPrincipal,
+    // Note: subnet is not currently working due to a bug
+    {
+      paths: [
+        encodePath('time', testPrincipal),
+        [encode('canister'), canisterBuffer, encode('controllers')],
+        [encode('canister'), canisterBuffer, encode('module_hash')],
+        encodePath('candid', testPrincipal),
+      ],
+    },
+    identity,
+  );
+  console.log(toHex(response.certificate));
+};
+
+// Mocked status using precomputed certificate
+const getStatus = async (paths: Path[]) => {
+  const agent = new HttpAgent({ host: 'https://ic0.app' });
+  agent.readState = jest.fn(() =>
+    Promise.resolve({ certificate: fromHex(testCases[0].certificate) }),
+  );
+
+  return await request({
+    canisterId: testPrincipal,
+    // Note: subnet is not currently working due to a bug
+    paths,
+    agent,
+  });
+};
+
+describe('Canister Status utility', () => {
+  it('should query the time', async () => {
+    const status = await getStatus(['time']);
+    expect(status.get('time')).toMatchSnapshot();
+  });
+  it('should query canister controllers', async () => {
+    const status = await getStatus(['controllers']);
+    expect(status.get('controllers')).toMatchSnapshot();
+  });
+  it('should query canister module hash', async () => {
+    const status = await getStatus(['module_hash']);
+    expect(status.get('module_hash')).toMatchSnapshot();
+  });
+  it('should query the candid interface', async () => {
+    const status = await getStatus(['candid']);
+    expect(status.get('candid')).toMatchSnapshot();
+  });
+  it('should support valid custom paths', async () => {
+    const status = await getStatus([
+      {
+        key: 'time',
+        path: [new DataView(new TextEncoder().encode('time').buffer).buffer],
+        decodeStrategy: 'leb128',
+      },
+    ]);
+    const statusRaw = await getStatus([
+      {
+        key: 'time',
+        path: [new DataView(new TextEncoder().encode('time').buffer).buffer],
+        decodeStrategy: 'raw',
+      },
+    ]);
+    const statusHex = await getStatus([
+      {
+        key: 'time',
+        path: [new DataView(new TextEncoder().encode('time').buffer).buffer],
+        decodeStrategy: 'hex',
+      },
+    ]);
+    const statusCBOR = await getStatus([
+      {
+        key: 'Controller',
+        path: [encode('canister'), canisterBuffer, encode('controllers')],
+        decodeStrategy: 'cbor',
+      },
+    ]);
+    expect(status.get('time')).toMatchSnapshot();
+    expect(statusRaw.get('time')).toMatchSnapshot();
+    expect(statusHex.get('time')).toMatchSnapshot();
+    expect(statusCBOR.get('Controller')).toMatchSnapshot();
+  });
+  it('should support valid metadata queries', async () => {
+    const status = await getStatus([
+      {
+        kind: 'medadata',
+        path: 'candid:service',
+        key: 'candid',
+        decodeStrategy: 'hex',
+      },
+    ]);
+    const statusEncoded = await getStatus([
+      {
+        kind: 'medadata',
+        path: encode('candid:service'),
+        key: 'candid',
+        decodeStrategy: 'hex',
+      },
+    ]);
+    expect(status.get('candid')).toMatchSnapshot();
+    expect(statusEncoded.get('candid')).toMatchSnapshot();
+  });
+  it('should support multiple requests', async () => {
+    const status = await getStatus(['time', 'controllers']);
+    expect(status.get('time')).toMatchSnapshot();
+    expect(status.get('controllers')).toMatchSnapshot();
+  });
+  it('should support multiple requests with a failure', async () => {
+    // Deliberately requesting a bad value
+    const consoleSpy = jest.spyOn(console, 'warn');
+    const status = await getStatus([
+      'time',
+      // subnet and this arbitrary path should fail
+      'subnet',
+      {
+        key: 'asdf',
+        path: [new DataView(new TextEncoder().encode('asdf').buffer).buffer],
+        decodeStrategy: 'hex',
+      },
+    ]);
+    expect(status.get('time')).toMatchSnapshot();
+    // Expect null for a failed result
+    expect(status.get('asdf' as unknown as Path)).toBe(null);
+    // Expect undefined for unset value
+    expect(status.get('test123')).toBe(undefined);
+    expect(consoleSpy).toBeCalledTimes(2);
+  });
+});
diff --git a/packages/agent/src/canisterStatus/index.ts b/packages/agent/src/canisterStatus/index.ts
new file mode 100644
index 000000000..10ff779cb
--- /dev/null
+++ b/packages/agent/src/canisterStatus/index.ts
@@ -0,0 +1,232 @@
+/** @module CanisterStatus */
+
+import { lebDecode, PipeArrayBuffer } from '@dfinity/candid';
+import { Principal } from '@dfinity/principal';
+import { HttpAgent, HttpAgentOptions, Cbor, Certificate, toHex } from '..';
+
+/**
+ * Types of an entry on the canisterStatus map.
+ * An entry of null indicates that the request failed, due to lack of permissions or the result being missing.
+ */
+export type Status = string | ArrayBuffer | Date | ArrayBuffer[] | Principal[] | bigint | null;
+
+/**
+ * Interface to define a custom path. Nested paths will be represented as individual buffers, and can be created from text using {@link TextEncoder}
+ */
+export interface CustomPath {
+  key: string;
+  path: ArrayBuffer[];
+  decodeStrategy: 'cbor' | 'hex' | 'leb128' | 'raw';
+}
+
+/**
+ * Interface to request metadata from the icp:public or icp:private sections.
+ * Similar to {@link CustomPath}, but accepts a simple string argument.
+ * Private metadata will require the ${@link Identity} used by the ${@link HttpAgent} will need to be requested using an identity that controlls the canister.
+ */
+export interface MetaData {
+  kind: 'medadata';
+  key: string;
+  path: string | ArrayBuffer;
+  decodeStrategy: 'cbor' | 'hex' | 'leb128' | 'raw';
+}
+
+/**
+ * Pre-configured fields for canister status paths
+ */
+export type Path =
+  | 'time'
+  | 'controllers'
+  | 'subnet'
+  | 'module_hash'
+  | 'candid'
+  | MetaData
+  | CustomPath;
+
+export type StatusMap = Map<Path | string, Status>;
+
+export type CanisterStatusOptions = {
+  canisterId: Principal;
+  agent: HttpAgent;
+  paths?: Path[] | Set<Path>;
+};
+
+/**
+ *
+ * @param {CanisterStatusOptions} options {@link CanisterStatusOptions}
+ * @param {CanisterStatusOptions['canisterId']} options.canisterId {@link Principal}
+ * @param {CanisterStatusOptions['agent']} options.agent {@link HttpAgent} optional authenticated agent to use to make the canister request. Useful for accessing private metadata under icp:private
+ * @param {CanisterStatusOptions['paths']} options.paths {@link Path[]}
+ * @returns {Status} object populated with data from the requested paths
+ * @example
+ * const status = await canisterStatus({
+ *   paths: ['controllers', 'candid'],
+ *   ...options
+ * });
+ *
+ * const controllers = status.get('controllers');
+ */
+export const request = async (options: {
+  canisterId: Principal;
+  agent: HttpAgent;
+  paths?: Path[] | Set<Path>;
+}): Promise<StatusMap> => {
+  const { canisterId, agent, paths } = options;
+
+  const uniquePaths = [...new Set(paths)];
+
+  // Map path options to their correct formats
+  const encodedPaths = uniquePaths.map(path => {
+    return encodePath(path, canisterId);
+  });
+  const status = new Map<string | Path, Status>();
+
+  const promises = uniquePaths.map((path, index) => {
+    return (async () => {
+      try {
+        const response = await agent.readState(canisterId, {
+          paths: [encodedPaths[index]],
+        });
+        const cert = new Certificate(response, agent);
+        const verified = await cert.verify();
+        if (!verified) {
+          throw new Error(
+            'There was a problem certifying the response data. Please verify your connection to the mainnet, or be sure to call fetchRootKey on your agent if you are developing locally',
+          );
+        }
+
+        const data = cert.lookup(encodePath(uniquePaths[index], canisterId));
+        if (!data) {
+          // Typically, the cert lookup will throw
+          console.warn(`Expected to find result for path ${path}, but instead found nothing.`);
+          if (typeof path === 'string') {
+            status.set(path, null);
+          } else {
+            status.set(path.key, null);
+          }
+        } else {
+          switch (path) {
+            case 'time': {
+              status.set(path, decodeTime(data));
+              break;
+            }
+            case 'controllers': {
+              status.set(path, decodeControllers(data));
+              break;
+            }
+            case 'module_hash': {
+              status.set(path, decodeHex(data));
+              break;
+            }
+            case 'candid': {
+              status.set(path, new TextDecoder().decode(data));
+              break;
+            }
+            default: {
+              // Check for CustomPath signature
+              if (typeof path !== 'string' && 'key' in path && 'path' in path) {
+                switch (path.decodeStrategy) {
+                  case 'raw':
+                    status.set(path.key, data);
+                    break;
+                  case 'leb128': {
+                    status.set(path.key, decodeLeb128(data));
+                    break;
+                  }
+                  case 'cbor': {
+                    status.set(path.key, decodeCbor(data));
+                    break;
+                  }
+                  case 'hex': {
+                    status.set(path.key, decodeHex(data));
+                    break;
+                  }
+                }
+              }
+            }
+          }
+        }
+      } catch (error) {
+        error;
+        if (typeof path !== 'string' && 'key' in path && 'path' in path) {
+          status.set(path.key, null);
+        } else {
+          status.set(path, null);
+        }
+        console.warn(`Expected to find result for path ${path}, but instead found nothing.`);
+      }
+    })();
+  });
+
+  // Fetch all values separately, as each option can fail
+  await Promise.all(promises);
+
+  return status;
+};
+
+export const encodePath = (path: Path, canisterId: Principal): ArrayBuffer[] => {
+  const encoder = new TextEncoder();
+
+  const encode = (arg: string): ArrayBuffer => {
+    return new DataView(encoder.encode(arg).buffer).buffer;
+  };
+  const canisterBuffer = new DataView(canisterId.toUint8Array().buffer).buffer;
+  switch (path) {
+    case 'time':
+      return [encode('time')];
+    case 'controllers':
+      return [encode('canister'), canisterBuffer, encode('controllers')];
+    case 'module_hash':
+      return [encode('canister'), canisterBuffer, encode('module_hash')];
+    case 'subnet':
+      return [encode('subnet')];
+    case 'candid':
+      return [encode('canister'), canisterBuffer, encode('metadata'), encode('candid:service')];
+    default: {
+      // Check for CustomPath signature
+      if ('key' in path && 'path' in path) {
+        // For simplified metadata queries
+        if (typeof path['path'] === 'string' || path['path'] instanceof ArrayBuffer) {
+          const metaPath = path.path;
+          const encoded = typeof metaPath === 'string' ? encode(metaPath) : metaPath;
+
+          return [encode('canister'), canisterBuffer, encode('metadata'), encoded];
+
+          // For non-metadata, return the provided custompath
+        } else {
+          return path['path'];
+        }
+      }
+    }
+  }
+  throw new Error(
+    `An unexpeected error was encountered while encoding your path for canister status. Please ensure that your path, ${path} was formatted correctly.`,
+  );
+};
+
+const decodeHex = (buf: ArrayBuffer): string => {
+  return toHex(buf);
+};
+
+const decodeLeb128 = (buf: ArrayBuffer): bigint => {
+  return lebDecode(new PipeArrayBuffer(buf));
+};
+
+const decodeCbor = (buf: ArrayBuffer): ArrayBuffer[] => {
+  return Cbor.decode(buf);
+};
+
+// time is a LEB128-encoded Nat
+const decodeTime = (buf: ArrayBuffer): Date => {
+  const decoded = decodeLeb128(buf);
+  return new Date(Number(decoded / BigInt(1_000_000)));
+};
+
+// Controllers are CBOR-encoded buffers, starting with a Tag we don't need
+const decodeControllers = (buf: ArrayBuffer): Principal[] => {
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  const [tag, ...controllersRaw] = decodeCbor(buf);
+  return controllersRaw.map((buf: ArrayBuffer) => {
+    return Principal.fromUint8Array(new Uint8Array(buf));
+  });
+};
diff --git a/packages/agent/src/index.ts b/packages/agent/src/index.ts
index e04da29cc..35bfa4770 100644
--- a/packages/agent/src/index.ts
+++ b/packages/agent/src/index.ts
@@ -10,7 +10,16 @@ export * from './canisters/asset';
 export * from './canisters/management';
 export * from './request_id';
 export * from './utils/bls';
+export * from './utils/buffer';
 export * as polling from './polling';
+/**
+ * The CanisterStatus utility is used to request structured data directly from the IC public API. This data can be accessed using agent.readState, but CanisterStatus provides a helpful abstraction with some known paths.
+ *
+ * You can request a canisters Controllers, ModuleHash, Candid interface, Subnet, or Time, or provide a custom path {@link CanisterStatus.CustomPath} and pass arbitrary buffers for valid paths identified in https://smartcontracts.org/docs/current/references/ic-interface-spec/.
+ *
+ * The primary method for this namespace is {@link CanisterStatus.request}
+ */
+export * as CanisterStatus from './canisterStatus';
 
 import { Agent, HttpAgent } from './agent';
 import { IDL } from '@dfinity/candid';
diff --git a/packages/candid/src/index.ts b/packages/candid/src/index.ts
index 14cf574e0..8d386676c 100644
--- a/packages/candid/src/index.ts
+++ b/packages/candid/src/index.ts
@@ -3,4 +3,5 @@ export * from './candid-core';
 export * as IDL from './idl';
 export * from './utils/hash';
 export * from './utils/leb128';
+export * from './utils/buffer';
 export * from './types';