documentation & readme & rm try-catch

README.md

@@ -0,0 +1,43 @@
+# NEAR Contract Parser
+
+Collection of utilities for parsing base64-encoded WASM smart contracts on [NEAR Protocol](https://near.org), extracting exported members, and detecting likely candidates for [standard contract interface implementation](https://nomicon.io/Standards/README.html).
+
+# Usage
+
+## Installation
+
+```txt
+$ npm install --save near-contract-parser
+```
+
+## Example
+
+```js
+const { Near, keyStores } = require('near-api-js');
+const { parseContract } = require('near-contract-parser');
+
+const near = new Near({
+  networkId: 'mainnet',
+  keyStore: new keyStores.InMemoryKeyStore(),
+  nodeUrl: 'https://rpc.mainnet.near.org',
+  archivalUrl: 'https://archival-rpc.mainnet.near.org',
+  walletUrl: 'https://wallet.mainnet.near.org',
+  helperUrl: 'https://helper.mainnet.near.org',
+  explorerUrl: 'https://explorer.mainnet.near.org',
+});
+
+(async () => {
+  const account_id = 'CONTRACT_ACCOUNT_ID.near';
+  const { code_base64 } = await near.connection.provider.query({
+    account_id,
+    finality: 'final',
+    request_type: 'view_code',
+  });
+
+  console.log(parseContract(code_base64));
+})();
+```
+
+# Authors
+
+- Jacob Lindahl <[email protected]> [@sudo_build](https://twitter.com/sudo_build)

src/JsonType.ts

@@ -1,3 +1,6 @@
+/**
+ * Data types supported by JSON format
+ */
 export type JsonType =
   | 'string'
   | 'number'

src/ParsedContract.ts

@@ -1,7 +1,16 @@
 import { StandardInterfaceId } from './interfaces';
 
 export interface ParsedContract {
+  /**
+   * Standard interfaces the original contract is likely to support
+   */
   probableInterfaces: StandardInterfaceId[];
+  /**
+   * Maps method names to the ID of the interface they are likey to constitute
+   */
   byMethod: Record<string, StandardInterfaceId[]>;
+  /**
+   * Names of functions exported from the original contract
+   */
   methodNames: string[];
 }

src/getProbableInterfaces.ts

@@ -1,5 +1,13 @@
 import { StandardInterfaceId, interfaces } from './interfaces';
 
+/**
+ * Guesses which standards a contract _probably_ implements based on exported
+ * method names.
+ *
+ * @param methodNames Exported method names
+ * @returns Interfaces the contract probably implements, as well as which
+ *  methods likely constitute which interfaces
+ */
 export function getProbableInterfaces(methodNames: string[]): {
   probableInterfaces: StandardInterfaceId[];
   byMethod: Record<string, StandardInterfaceId[]>;

src/interfaces.ts

@@ -1,21 +1,31 @@
 import { JsonType } from './JsonType';
 
-export const enum StandardInterfaceId {
+export enum StandardInterfaceId {
   NEP141 = 'nep141',
   NEP148 = 'nep148',
   NEP171 = 'nep171',
   NEP177 = 'nep177',
   NEP178 = 'nep178',
 }
 
+/**
+ * Well-known smart contract interface specification
+ */
 export interface StandardInterface {
+  /** Unique interface ID */
   id: StandardInterfaceId;
+  /** Human-readable interface name */
   name: string;
+  /** Methods provided by interface */
   methods: StandardInterfaceMethod[];
 }
 
 export interface StandardInterfaceArgument {
   name: string;
+  /**
+   * An argument can support one or multiple types
+   * (e.g. Rust's `Option<String>` becomes `['string', 'null']`)
+   */
   type: JsonType | JsonType[];
 }
 
@@ -24,6 +34,9 @@ export interface StandardInterfaceMethod {
   args: StandardInterfaceArgument[];
 }
 
+/**
+ * Mapping interface ID to interface specification
+ */
 export const interfaces: Readonly<
   Record<StandardInterfaceId, StandardInterface>
 > = Object.freeze({

src/methods.ts

@@ -1,15 +1,17 @@
 import { parseWasm } from './parseWasm';
 
+/**
+ * Extracts exported functions from smart contract
+ *
+ * @param code_base64 Base64-encoded WASM binary (e.g. obtained from
+ *  `near-api-js`)
+ * @returns List of exported function names
+ */
 export function getMethodNames(code_base64: string): string[] {
-  try {
-    const ast = parseWasm(code_base64);
-    return ast.body[0].fields
-      .filter(
-        (x: any) => x.type === 'ModuleExport' && x.descr.exportType === 'Func',
-      )
-      .map((x: any) => x.name) as string[];
-  } catch (e) {
-    console.error('Could not parse WASM', e);
-    return [];
-  }
+  const ast = parseWasm(code_base64);
+  return ast.body[0].fields
+    .filter(
+      (x: any) => x.type === 'ModuleExport' && x.descr.exportType === 'Func',
+    )
+    .map((x: any) => x.name) as string[];
 }

src/parseContract.ts

@@ -2,12 +2,6 @@ import { getProbableInterfaces } from './getProbableInterfaces';
 import { ParsedContract } from './ParsedContract';
 import { getMethodNames } from './methods';
 
-const emptyContract: ParsedContract = {
-  probableInterfaces: [],
-  byMethod: {},
-  methodNames: [],
-};
-
 export function parseContract(code_base64: string): ParsedContract {
   const methodNames = getMethodNames(code_base64);
   const probableInterfaces = getProbableInterfaces(methodNames);

src/parseWasm.ts

@@ -1,19 +1,32 @@
 import { decode } from '@webassemblyjs/wasm-parser';
 
-function base64StringToUint8Array(str: string): Uint8Array {
+/**
+ * Converts a base64-encoded string to a byte array. Works in browser and Node
+ * environments.
+ *
+ * @param strb64 base64 string
+ * @returns Decoded byte array
+ */
+function base64StringToUint8Array(strb64: string): Uint8Array {
   if (typeof Buffer !== 'undefined') {
     // Node
-    return Buffer.from(str, 'base64');
+    return Buffer.from(strb64, 'base64');
   } else {
     // Browser
     return new Uint8Array(
-      atob(str.toString().trim())
+      atob(strb64.toString().trim())
         .split('')
         .map(c => c.charCodeAt(0)),
     );
   }
 }
 
+/**
+ * Parse base64-encoded WASM into AST
+ *
+ * @param wasmb64 base64-encoded WASM binary
+ * @returns WASM abstract syntax tree
+ */
 export function parseWasm(wasmb64: string): any {
   return decode(base64StringToUint8Array(wasmb64));
 }