npm package: @qevm/purc
Description: Purity compiler JavaScript bindings
Latest version: 0.1.2

# purc-js

JavaScript bindings for the Purity compiler.

Purity is a fork of [Solidity](https://github.com/ethereum/solidity) with 32-byte native addressing and other modifications targeting next-generation EVM-compatible virtual machines.

`purc-js` is derived from [solc-js](https://github.com/ethereum/solc-js) and provides the same API surface, with naming and defaults updated for Purity.

## Node.js Usage

```bash
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.

```bash
purcjs --help
```

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

```bash
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](https://docs.soliditylang.org/en/latest/using-the-compiler.html#compiler-input-and-output-json-description).

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

#### Example usage without the import callback

```javascript
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

```javascript
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:

```javascript
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:

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

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

You can also find link references in unlinked bytecode:

```javascript
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:

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

### Formatting Assembly Output

```javascript
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](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers):

```javascript
import wrapper from 'purc/wrapper';

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

## License

MIT — see [LICENSE](LICENSE).

This project is derived from [solc-js](https://github.com/ethereum/solc-js), originally created by the Ethereum community.