tessl/npm-solc

JavaScript bindings for the Solidity compiler with Standard JSON I/O interface

—

Pending

Overview

Eval results

Files

Command Line Interface

Name: tessl/npm-solc
Author: tessl

Command-line interface for Solidity compilation providing standalone compilation capabilities without requiring programmatic API usage.

Capabilities

CLI Installation and Usage

When installed globally, solc provides the solcjs command-line tool.

# Global installation
npm install -g solc

# Basic usage
solcjs --help

Basic Compilation

Compile Solidity files to bytecode and ABI.

# Compile to bytecode
solcjs --bin Contract.sol

# Compile to ABI
solcjs --abi Contract.sol

# Both bytecode and ABI
solcjs --bin --abi Contract.sol

Project Structure Support

Handle complex project layouts with imports and dependencies.

# Compile with base path and include paths
solcjs --bin --include-path node_modules/ --base-path . MainContract.sol

# Multiple include paths
solcjs --bin --include-path ./lib --include-path ./node_modules Contract.sol

Standard JSON Mode

Use Standard JSON input/output format for advanced compilation.

# Standard JSON mode (reads from stdin)
echo '{"language":"Solidity","sources":{"test.sol":{"content":"contract C {}"}}}' | solcjs --standard-json

Standard JSON Input Example:

{
  "language": "Solidity",
  "sources": {
    "Contract.sol": {
      "content": "contract MyContract { uint public value = 42; }"
    }
  },
  "settings": {
    "optimizer": {
      "enabled": true,
      "runs": 200
    },
    "outputSelection": {
      "*": {
        "*": ["abi", "evm.bytecode"]
      }
    }
  }
}

Optimization Options

Control bytecode optimization settings.

# Enable optimizer
solcjs --optimize --bin Contract.sol

# Set optimizer runs
solcjs --optimize --optimize-runs 1000 --bin Contract.sol

Output Management

Control output format and destination.

# Specify output directory
solcjs --bin --output-dir ./build Contract.sol

# Pretty-print JSON output
solcjs --abi --pretty-json Contract.sol

# Verbose output
solcjs --bin --verbose Contract.sol

CLI Options Reference

solcjs [options] <files...>

Options:
  --version                    Show version and exit
  --optimize                   Enable bytecode optimizer (default: false)
  --optimize-runs <runs>       Number of optimizer runs (default: 200)
  --bin                        Output binary bytecode
  --abi                        Output ABI specification
  --standard-json              Use Standard JSON I/O mode
  --base-path <path>           Root of the project source tree
  --include-path <paths...>    Extra source directories for imports
  -o, --output-dir <dir>       Output directory for compiled files
  -p, --pretty-json            Pretty-print JSON output (default: false)
  -v, --verbose                Verbose output (default: false)
  -h, --help                   Display help information

Path Resolution

The CLI uses a sophisticated path resolution system:

Base Path: Root of your source tree (use . for current directory)
Include Paths: Additional directories containing external code
Import Resolution: All imports must be within base path or include paths

# Correct usage
solcjs --bin --base-path . --include-path ./node_modules MyContract.sol

# Files outside paths will cause errors
solcjs --bin --base-path ./src ../external/Library.sol  # Error!

Output Files

The CLI generates files with specific naming conventions:

# Input: Contract.sol containing contracts A and B
solcjs --bin --abi Contract.sol

# Generated files:
# Contract_sol_A.bin - Bytecode for contract A
# Contract_sol_A.abi - ABI for contract A  
# Contract_sol_B.bin - Bytecode for contract B
# Contract_sol_B.abi - ABI for contract B

Error Handling

The CLI provides detailed error reporting:

# Compilation errors
solcjs --bin InvalidContract.sol
# Exit code: 1
# Output includes formatted error messages with line numbers

# Warning handling (warnings don't cause non-zero exit)
solcjs --bin ContractWithWarnings.sol
# Exit code: 0
# Warnings printed to stdout

Integration Examples

Build Script Integration:

#!/bin/bash
set -e  # Exit on any error

echo "Compiling contracts..."
solcjs --bin --abi --optimize --output-dir ./build *.sol

echo "Compilation successful!"
ls -la ./build/

Package.json Scripts:

{
  "scripts": {
    "compile": "solcjs --bin --abi --optimize --output-dir ./build contracts/*.sol",
    "compile:dev": "solcjs --bin --abi --verbose contracts/*.sol",
    "compile:standard": "cat input.json | solcjs --standard-json --pretty-json"
  }
}

CI/CD Pipeline:

# GitHub Actions example
- name: Compile Solidity contracts
  run: |
    npm install -g solc
    solcjs --bin --abi --optimize \
      --base-path . \
      --include-path ./node_modules \
      --output-dir ./dist \
      contracts/*.sol

SMT Solver Integration

The CLI automatically attempts to use SMT solvers for formal verification:

# Compile with SMT checking (requires Z3, Eldarica, or cvc5)
echo '{
  "language": "Solidity",
  "sources": {
    "test.sol": {
      "content": "contract C { function f(uint x) public { assert(x > 0); } }"
    }
  },
  "settings": {
    "modelChecker": {
      "engine": "chc",
      "solvers": ["smtlib2"]
    }
  }
}' | solcjs --standard-json

If SMT solvers are not available:

>>> Cannot retry compilation with SMT because there are no SMT solvers available.

Differences from Native solc

Important limitations compared to the native solc binary:

Not compatible with eth.compile.solidity() RPC method
Fewer command-line features than native solc
Uses JavaScript/Emscripten compilation (slower than native)
Cannot be used as a drop-in replacement for native solc

When to use solcjs CLI:

Node.js-based development workflows
Integration with JavaScript tooling
Cross-platform compatibility requirements
When native solc installation is problematic

When to use native solc:

Maximum performance requirements
Full Ethereum client integration
Advanced command-line features
Production deployment pipelines

Install with Tessl CLI

npx tessl i tessl/npm-solc

docs

version-management.md

tile.json