@theqrl/hypc 0.0.2

package/README.md

@@ -0,0 +1,361 @@
+# hypc-js
+
+JavaScript bindings for the [Hyperion compiler](https://github.com/theQRL/hyperion).
+
+Uses the Emscripten compiled Hyperion found in the [hypc-bin repository](https://github.com/theQRL/hypc-bin).
+
+## Node.js Usage
+
+To use the latest stable version of the Hyperion compiler via Node.js you can install it via npm:
+
+```bash
+npm install @theqrl/hypc
+```
+
+### Usage on the Command-Line
+
+If this package is installed globally (`npm install -g @theqrl/hypc`), a command-line tool called `hypcjs` will be available.
+
+To see all the supported features, execute:
+
+```bash
+hypcjs --help
+```
+
+To compile a contract that imports other contracts via relative paths:
+```bash
+hypcjs --bin --include-path node_modules/ --base-path . MainContract.hyp
+```
+Use the ``--base-path`` and ``--include-path`` options to describe the layout of your project.
+``--base-path`` represents the root of your own source tree while ``--include-path`` allows you to
+specify extra locations containing external code (e.g. libraries installed with a package manager).
+
+Note: ensure that all the files you specify on the command line are located inside the base path or
+one of the include paths.
+The compiler refers to files from outside of these directories using absolute paths.
+Having absolute paths in contract metadata will result in your bytecode being reproducible only
+when it's placed in these exact absolute locations.
+
+Note: this commandline interface is not compatible with `hypc` provided by the Hyperion compiler package and thus cannot be
+used in combination with an Zond client via the `zond.compile.hyperion()` RPC method. Please refer to the
+[Hyperion compiler documentation](https://theqrl.org/) for instructions to install `hypc`.
+Furthermore, the commandline interface to hypc-js provides fewer features than the binary release.
+
+### Usage in Projects
+
+There are two ways to use `hypc`:
+
+1. Through a high-level API giving a uniform interface to all compiler versions
+2. Through a low-level API giving access to all the compiler interfaces, which depend on the version of the compiler
+
+#### High-level API
+
+The high-level API consists of a single method, `compile`, which expects the [Compiler Standard Input and Output JSON](https://theqrl.org/).
+
+It also accepts an optional set of callback functions, which include the ``import`` and the ``smtSolver`` callbacks.
+Starting 0.6.0 it only accepts an object in place of the callback to supply the callbacks.
+
+The ``import`` callback function is used to resolve unmet dependencies.
+This callback receives a path and must synchronously return either an error or the content of the dependency
+as a string.  It cannot be used together with callback-based, asynchronous,
+filesystem access. A workaround is to collect the names of dependencies, return
+an error, and keep re-running the compiler until all of them are resolved.
+
+#### Example usage without the import callback
+
+Example:
+
+```javascript
+var hypc = require('@theqrl/hypc');
+
+var input = {
+  language: 'Hyperion',
+  sources: {
+    'test.hyp': {
+      content: 'contract C { function f() public { } }'
+    }
+  },
+  settings: {
+    outputSelection: {
+      '*': {
+        '*': ['*']
+      }
+    }
+  }
+};
+
+var output = JSON.parse(hypc.compile(JSON.stringify(input)));
+
+// `output` here contains the JSON output as specified in the documentation
+for (var contractName in output.contracts['test.hyp']) {
+  console.log(
+    contractName +
+      ': ' +
+      output.contracts['test.hyp'][contractName].evm.bytecode.object
+  );
+}
+```
+
+#### Example usage with import callback
+
+```javascript
+var hypc = require('@theqrl/hypc');
+
+var input = {
+  language: 'Hyperion',
+  sources: {
+    'test.hyp': {
+      content: 'import "lib.hyp"; contract C { function f() public { L.f(); } }'
+    }
+  },
+  settings: {
+    outputSelection: {
+      '*': {
+        '*': ['*']
+      }
+    }
+  }
+};
+
+function findImports(path) {
+  if (path === 'lib.hyp')
+    return {
+      contents:
+        'library L { function f() internal returns (uint) { return 7; } }'
+    };
+  else return { error: 'File not found' };
+}
+
+// New syntax (supported from 0.5.12, mandatory from 0.6.0)
+var output = JSON.parse(
+  hypc.compile(JSON.stringify(input), { import: findImports })
+);
+
+// `output` here contains the JSON output as specified in the documentation
+for (var contractName in output.contracts['test.hyp']) {
+  console.log(
+    contractName +
+      ': ' +
+      output.contracts['test.hyp'][contractName].evm.bytecode.object
+  );
+}
+```
+
+Since version 0.5.1, the ``smtSolver`` callback function is used to solve SMT queries generated by
+Hyperion's SMTChecker.  If you have an SMT solver installed locally, it can
+be used to solve the given queries, where the callback must synchronously
+return either an error or the result from the solver.  A default
+``smtSolver`` callback is included in this package via the module
+``smtchecker.js`` which exports the ``smtCallback`` function that takes 1) a
+function that takes queries and returns the solving result, and 2) a solver
+configuration object. The module ``smtsolver.js`` has a few predefined solver
+configurations, and relies on Z3, Eldarica or cvc5 being installed locally.  It
+exports the list of locally found solvers and a function that invokes a given
+solver.
+
+The API of the SMT callback is **experimental** and can change at any time.
+The last change was in version 0.8.11.
+
+#### Example usage with smtSolver callback
+
+```javascript
+var hypc = require('@theqrl/hypc');
+const smtchecker = require('@theqrl/hypc/smtchecker');
+const smtsolver = require('@theqrl/hypc/smtsolver');
+// Note that this example only works via node and not in the browser.
+
+var input = {
+  language: 'Hyperion',
+  sources: {
+    'test.hyp': {
+      content: 'contract C { function f(uint x) public { assert(x > 0); } }'
+    }
+  },
+  settings: {
+    modelChecker: {
+      engine: "chc",
+      solvers: [ "smtlib2" ]
+    }
+  }
+};
+
+var output = JSON.parse(
+  hypc.compile(
+    JSON.stringify(input),
+    { smtSolver: smtchecker.smtCallback(smtsolver.smtSolver, smtsolver.availableSolvers[0]) }
+  )
+);
+
+```
+The assertion is clearly false, and an ``assertion failure`` warning
+should be returned, together with a counterexample.
+
+#### Low-level API
+
+The low-level API is as follows:
+
+- `hypc.lowlevel.compileSingle`: the original entry point, supports only a single file
+- `hypc.lowlevel.compileMulti`: this supports multiple files, introduced in 0.1.6
+- `hypc.lowlevel.compileCallback`: this supports callbacks, introduced in 0.2.1
+- `hypc.lowlevel.compileStandard`: this works just like `compile` above, but is only present in compilers after (and including) 0.4.11
+
+For examples how to use them, please refer to the README of the above mentioned hypc-js releases.
+
+**Note**: These low-level functions remain available for compatibility reasons.
+However, they were superseded by the `compile()` function and are no longer required.
+Starting from version `0.5.0+commit.1d4f565a`, the functions `compileSingle`, `compileMulti`, and `compileCallback` are always `null` when using newer hypc binary versions.
+It is recommended to use the latest release of hypc-js, but it should also handle all the older hypc binaries down to `0.1.x`.
+
+### Using with Electron
+
+**Note:**
+If you are using Electron, `nodeIntegration` is on for `BrowserWindow` by default. If it is on, Electron will provide a `require` method which will not behave as expected and this may cause calls, such as `require('@theqrl/hypc')`, to fail.
+
+To turn off `nodeIntegration`, use the following:
+
+```javascript
+new BrowserWindow({
+  webPreferences: {
+    nodeIntegration: false
+  }
+});
+```
+
+### Using a Legacy Version
+
+In order to compile contracts using a specific version of Hyperion, the `hypc.loadRemoteVersion(version, callback)` method is available. This returns a new `hypc` object that uses a version of the compiler specified.
+
+You can also load the "binary" manually and use `setupMethods` to create the familiar wrapper functions described above:
+`var hypc = hypc.setupMethods(require("/my/local/hypjson.js"))`.
+
+### Using the Latest Development Snapshot
+
+By default, the npm version is only created for releases. This prevents people from deploying contracts with non-release versions because they are less stable and harder to verify. If you would like to use the latest development snapshot (at your own risk!), you may use the following example code.
+
+```javascript
+var hypc = require('@theqrl/hypc');
+
+// getting the development snapshot
+hypc.loadRemoteVersion('latest', function(err, hypcSnapshot) {
+  if (err) {
+    // An error was encountered, display and quit
+  } else {
+    // NOTE: Use `hypcSnapshot` here with the same interface `hypc` has
+    // For example:
+    const output = hypcSnapshot.compile(/* ... */)
+  }
+});
+```
+
+The version **must** be in the long format.
+Thus, if you would like to use version `v0.8.17` you need to include the commit hash of the release.
+You can extract the long version string for each version from the [publicly available release list](https://binaries.theqrl.org/bin/list.json).
+
+```javascript
+hypc.loadRemoteVersion('v0.8.17+commit.8df45f5f', function(err, hypcSnapshot) { /* ... */ });
+```
+
+### Linking Bytecode
+
+When using libraries, the resulting bytecode will contain placeholders for the real addresses of the referenced libraries. These have to be updated, via a process called linking, before deploying the contract.
+
+The `linker` module (`require('@theqrl/hypc/linker')`) offers helpers to accomplish this.
+
+The `linkBytecode` method provides a simple helper for linking:
+
+```javascript
+var linker = require('@theqrl/hypc/linker');
+
+bytecode = linker.linkBytecode(bytecode, { MyLibrary: '0x123456...' });
+```
+
+As of Hyperion 0.4.11 the compiler supports [standard JSON input and output](https://theqrl.org) which outputs a _link references_ map. This gives a map of library names to offsets in the bytecode to replace the addresses at. It also doesn't have the limitation on library file and contract name lengths.
+
+There is a method available in the `linker` module called `findLinkReferences` which can find such link references in bytecode produced by an older compiler:
+
+```javascript
+var linker = require('@theqrl/hypc/linker');
+
+var linkReferences = linker.findLinkReferences(bytecode);
+```
+
+### Updating the ABI
+
+The ABI generated by Hyperion versions can differ slightly, due to new features introduced. There is a tool included which aims to translate the ABI generated by an older Hyperion version to conform to the latest standard.
+
+It can be used as:
+
+```javascript
+var abi = require('@theqrl/hypc/abi');
+
+var inputABI = [
+  {
+    constant: false,
+    inputs: [],
+    name: 'hello',
+    outputs: [{ name: '', type: 'string' }],
+    payable: false,
+    type: 'function'
+  }
+];
+var outputABI = abi.update('0.3.6', inputABI);
+// Output contains: [{"constant":false,"inputs":[],"name":"hello","outputs":[{"name":"","type":"string"}],"payable":true,"type":"function"},{"type":"fallback","payable":true}]
+```
+
+### Formatting old JSON assembly output
+
+There is a helper available to format old JSON assembly output into a text familiar to earlier users of Remix IDE.
+
+```
+var translate = require('@theqrl/hypc/translate')
+
+// assemblyJSON refers to the JSON of the given assembly and sourceCode is the source of which the assembly was generated from
+var output = translate.prettyPrintLegacyAssemblyJSON(assemblyJSON, sourceCode)
+```
+
+## Browser Usage
+
+Compilation is generally a long-running and resource intensive task that cannot reasonably be performed in the main thread of the browser.
+Some browsers even disallow synchronous compilation on the main thread if the module is larger than 4KB.
+Thus, the only supported way to use `hypc` in a web browser is through a [web worker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers).
+
+### Loading hypc with web workers
+
+Web Workers allow you to run javascript in the background in the browser, letting the browser's main thread free to do whatever it needs to do.
+Please, see the minimal example of how to use `hypc` with web workers below or check out this [repository](https://theqrl.org) for a full demo.
+
+* index.html
+```html
+<!DOCTYPE html>
+<html>
+
+<head>
+	<meta charset="utf-8" />
+</head>
+
+<body>
+	<script>
+		var worker = new Worker('./dist/bundle.js');
+		worker.addEventListener('message', function (e) {
+			console.log(e.data.version)
+		}, false);
+
+		worker.postMessage({})
+	</script>
+</body>
+
+</html>
+```
+
+* worker.js:
+```javascript
+importScripts('https://binaries.theqrl.org/bin/hypjson-v0.0.2+commit.3e18e55.js')
+import wrapper from '@theqrl/hypc/wrapper';
+
+self.addEventListener('message', () => {
+	const compiler = wrapper(self.Module)
+	self.postMessage({
+		version: compiler.version()
+	})
+}, false)
+```

package/abi.js

@@ -0,0 +1,80 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+const semver = __importStar(require("semver"));
+function update(compilerVersion, abi) {
+    let hasConstructor = false;
+    let hasFallback = false;
+    for (let i = 0; i < abi.length; i++) {
+        const item = abi[i];
+        if (item.type === 'constructor') {
+            hasConstructor = true;
+            // <0.4.5 assumed every constructor to be payable
+            if (semver.lt(compilerVersion, '0.4.5')) {
+                item.payable = true;
+            }
+        }
+        else if (item.type === 'fallback') {
+            hasFallback = true;
+        }
+        if (item.type !== 'event') {
+            // add 'payable' to everything, except constant functions
+            if (!item.constant && semver.lt(compilerVersion, '0.4.0')) {
+                item.payable = true;
+            }
+            // add stateMutability field
+            if (semver.lt(compilerVersion, '0.4.16')) {
+                if (item.payable) {
+                    item.stateMutability = 'payable';
+                }
+                else if (item.constant) {
+                    item.stateMutability = 'view';
+                }
+                else {
+                    item.stateMutability = 'nonpayable';
+                }
+            }
+        }
+    }
+    // 0.1.2 from Aug 2015 had it. The code has it since May 2015 (e7931ade)
+    if (!hasConstructor && semver.lt(compilerVersion, '0.1.2')) {
+        abi.push({
+            type: 'constructor',
+            payable: true,
+            stateMutability: 'payable',
+            inputs: []
+        });
+    }
+    if (!hasFallback && semver.lt(compilerVersion, '0.4.0')) {
+        abi.push({
+            type: 'fallback',
+            payable: true,
+            stateMutability: 'payable'
+        });
+    }
+    return abi;
+}
+module.exports = {
+    update
+};

package/bindings/compile.js

@@ -0,0 +1,157 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setupCompile = void 0;
+const assert_1 = __importDefault(require("assert"));
+const helpers_1 = require("../common/helpers");
+const helpers_2 = require("./helpers");
+function setupCompile(hypJson, core) {
+    return {
+        compileJson: bindCompileJson(hypJson),
+        compileJsonCallback: bindCompileJsonCallback(hypJson, core),
+        compileJsonMulti: bindCompileJsonMulti(hypJson),
+        compileStandard: bindCompileStandard(hypJson, core)
+    };
+}
+exports.setupCompile = setupCompile;
+/**********************
+ * COMPILE
+ **********************/
+/**
+ * Returns a binding to the hyperion compileJSON method.
+ * input (text), optimize (bool) -> output (jsontext)
+ *
+ * @param hypJson The Emscripten compiled Hyperion object.
+ */
+function bindCompileJson(hypJson) {
+    return (0, helpers_2.bindHypcMethod)(hypJson, 'compileJSON', 'string', ['string', 'number'], null);
+}
+/**
+ * Returns a binding to the hyperion compileJSONMulti method.
+ * input (jsontext), optimize (bool) -> output (jsontext)
+ *
+ * @param hypJson The Emscripten compiled Hyperion object.
+ */
+function bindCompileJsonMulti(hypJson) {
+    return (0, helpers_2.bindHypcMethod)(hypJson, 'compileJSONMulti', 'string', ['string', 'number'], null);
+}
+/**
+ * Returns a binding to the hyperion compileJSONCallback method.
+ * input (jsontext), optimize (bool), callback (ptr) -> output (jsontext)
+ *
+ * @param hypJson The Emscripten compiled Hyperion object.
+ * @param coreBindings The core bound Hyperion methods.
+ */
+function bindCompileJsonCallback(hypJson, coreBindings) {
+    const compileInternal = (0, helpers_2.bindHypcMethod)(hypJson, 'compileJSONCallback', 'string', ['string', 'number', 'number'], null);
+    if ((0, helpers_1.isNil)(compileInternal))
+        return null;
+    return function (input, optimize, readCallback) {
+        return runWithCallbacks(hypJson, coreBindings, readCallback, compileInternal, [input, optimize]);
+    };
+}
+/**
+ * Returns a binding to the hyperion hyperion_compile method with a fallback to
+ * compileStandard.
+ * input (jsontext), callback (optional >= v6 only - ptr) -> output (jsontext)
+ *
+ * @param hypJson The Emscripten compiled Hyperion object.
+ * @param coreBindings The core bound Hyperion methods.
+ */
+function bindCompileStandard(hypJson, coreBindings) {
+    let boundFunctionStandard = null;
+    let boundFunctionHyperion = null;
+    // input (jsontext), callback (ptr) -> output (jsontext)
+    const compileInternal = (0, helpers_2.bindHypcMethod)(hypJson, 'compileStandard', 'string', ['string', 'number'], null);
+    // input (jsontext), callback (ptr), callback_context (ptr) -> output (jsontext)
+    boundFunctionHyperion = (0, helpers_2.bindHypcMethod)(hypJson, 'hyperion_compile', 'string', ['string', 'number', 'number'], null);
+    if (!(0, helpers_1.isNil)(compileInternal)) {
+        boundFunctionStandard = function (input, readCallback) {
+            return runWithCallbacks(hypJson, coreBindings, readCallback, compileInternal, [input]);
+        };
+    }
+    if (!(0, helpers_1.isNil)(boundFunctionHyperion)) {
+        boundFunctionStandard = function (input, callbacks) {
+            return runWithCallbacks(hypJson, coreBindings, callbacks, boundFunctionHyperion, [input]);
+        };
+    }
+    return boundFunctionStandard;
+}
+/**********************
+ * CALL BACKS
+ **********************/
+function wrapCallbackWithKind(coreBindings, callback) {
+    (0, assert_1.default)(typeof callback === 'function', 'Invalid callback specified.');
+    return function (context, kind, data, contents, error) {
+        // Must be a null pointer.
+        (0, assert_1.default)(context === 0, 'Callback context must be null.');
+        const result = callback(coreBindings.copyFromCString(kind), coreBindings.copyFromCString(data));
+        if (typeof result.contents === 'string') {
+            coreBindings.copyToCString(result.contents, contents);
+        }
+        if (typeof result.error === 'string') {
+            coreBindings.copyToCString(result.error, error);
+        }
+    };
+}
+// calls compile() with args || cb
+function runWithCallbacks(hypJson, coreBindings, callbacks, compile, args) {
+    if (callbacks) {
+        (0, assert_1.default)(typeof callbacks === 'object', 'Invalid callback object specified.');
+    }
+    else {
+        callbacks = {};
+    }
+    let readCallback = callbacks.import;
+    if (readCallback === undefined) {
+        readCallback = function (data) {
+            return {
+                error: 'File import callback not supported'
+            };
+        };
+    }
+    let singleCallback;
+    // After 0.6.x multiple kind of callbacks are supported.
+    let smtSolverCallback = callbacks.smtSolver;
+    if (smtSolverCallback === undefined) {
+        smtSolverCallback = function (data) {
+            return {
+                error: 'SMT solver callback not supported'
+            };
+        };
+    }
+    singleCallback = function (kind, data) {
+        if (kind === 'source') {
+            return readCallback(data);
+        }
+        else if (kind === 'smt-query') {
+            return smtSolverCallback(data);
+        }
+        else {
+            (0, assert_1.default)(false, 'Invalid callback kind specified.');
+        }
+    };
+    singleCallback = wrapCallbackWithKind(coreBindings, singleCallback);
+    const cb = coreBindings.addFunction(singleCallback, 'viiiii');
+    let output;
+    try {
+        args.push(cb);
+        // Callback context.
+        args.push(null);
+        output = compile(...args);
+    }
+    finally {
+        coreBindings.removeFunction(cb);
+    }
+    if (coreBindings.reset) {
+        // Explicitly free memory.
+        //
+        // NOTE: cwrap() of "compile" will copy the returned pointer into a
+        //       Javascript string and it is not possible to call free() on it.
+        //       reset() however will clear up all allocations.
+        coreBindings.reset();
+    }
+    return output;
+}