purc-js

JavaScript bindings for the Purity compiler.

Purity is a fork of Solidity with 32-byte native addressing and other modifications targeting next-generation EVM-compatible virtual machines.

purc-js is derived from solc-js and provides the same API surface, with naming and defaults updated for Purity.

Node.js Usage

npm install purc

Command-Line Usage

If this package is installed globally (npm install -g purc), a command-line tool called purcjs will be available.

purcjs --help

To compile a contract that imports other contracts via relative paths:

purcjs --bin --include-path node_modules/ --base-path . MainContract.sol

Use --base-path to specify the root of your source tree and --include-path for external code directories (e.g. libraries installed with a package manager).

Usage in Projects

There are two ways to use purc:

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

High-level API

The high-level API consists of a single method, compile, which expects the Compiler Standard Input and Output JSON.

It also accepts an optional set of callback functions, including import and smtSolver callbacks.

Example usage without the import callback

var purc = require('purc');

var input = {
  language: 'Purity',
  sources: {
    'test.sol': {
      content: 'pragma purity >=0.1.0; contract C { function f() public pure returns (uint) { return 42; } }'
    }
  },
  settings: {
    outputSelection: {
      '*': {
        '*': ['*']
      }
    }
  }
};

var output = JSON.parse(purc.compile(JSON.stringify(input)));

for (var contractName in output.contracts['test.sol']) {
  console.log(
    contractName +
      ': ' +
      output.contracts['test.sol'][contractName].evm.bytecode.object
  );
}

Note: "Solidity" is also accepted as the language value for backward compatibility.

Example usage with import callback

var purc = require('purc');

var input = {
  language: 'Purity',
  sources: {
    'test.sol': {
      content: 'import "lib.sol"; contract C { function f() public { L.f(); } }'
    }
  },
  settings: {
    outputSelection: {
      '*': {
        '*': ['*']
      }
    }
  }
};

function findImports(path) {
  if (path === 'lib.sol')
    return {
      contents:
        'library L { function f() internal returns (uint) { return 7; } }'
    };
  else return { error: 'File not found' };
}

var output = JSON.parse(
  purc.compile(JSON.stringify(input), { import: findImports })
);

for (var contractName in output.contracts['test.sol']) {
  console.log(
    contractName +
      ': ' +
      output.contracts['test.sol'][contractName].evm.bytecode.object
  );
}

Low-level API

The low-level API is available for compatibility with older compiler binaries:

• purc.lowlevel.compileSingle
• purc.lowlevel.compileMulti
• purc.lowlevel.compileCallback
• purc.lowlevel.compileStandard

Note: These low-level functions remain for compatibility reasons but have been superseded by compile().

Loading a Custom Compiler Binary

You can load the compiler binary manually and use setupMethods to create the wrapper:

var purc = require('purc');
var compiler = purc.setupMethods(require('/path/to/purjson.js'));

Linking Bytecode

The linker module (require('purc/linker')) offers helpers for linking library addresses into bytecode:

var linker = require('purc/linker');

bytecode = linker.linkBytecode(bytecode, { 'lib.sol:MyLibrary': '0x1234...' });

You can also find link references in unlinked bytecode:

var linkReferences = linker.findLinkReferences(bytecode);

Updating the ABI

The abi module (require('purc/abi')) can translate ABI output from older compiler versions to the latest standard:

var abi = require('purc/abi');
var outputABI = abi.update('0.3.6', inputABI);

Formatting Assembly Output

var translate = require('purc/translate');
var output = translate.prettyPrintLegacyAssemblyJSON(assemblyJSON, sourceCode);

Key Differences from solc-js

• Default language in Standard JSON is "Purity" (though "Solidity" is accepted for backward compatibility)
• Package name is purc instead of solc
• CLI binary is purcjs instead of solcjs
• Version numbering starts at 0.1.0

Migration from solc-js

1. Replace require('solc') with require('purc')
2. Update language: 'Solidity' to language: 'Purity' in Standard JSON inputs (optional — both are accepted)
3. Replace solcjs CLI commands with purcjs
4. Update pragma solidity to pragma purity in .sol source files (optional — both are accepted)

Browser Usage

The only supported way to use purc in a web browser is through a web worker:

import wrapper from 'purc/wrapper';

self.addEventListener('message', () => {
  const compiler = wrapper(self.Module);
  self.postMessage({
    version: compiler.version()
  });
}, false);

License

MIT — see LICENSE.

This project is derived from solc-js, originally created by the Ethereum community.