CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-py-solc-x

Python wrapper and version management tool for the solc Solidity compiler.

77

1.05x

Evaluation — 77%

↑ 1.05x

Agent success when using this tile

Overview
Eval results
Files

compilation.mddocs/

Solidity Compilation

Comprehensive compilation functions for converting Solidity source code into bytecode, ABI, and other compilation artifacts. Supports all major compilation workflows including string-based compilation, file-based compilation, and the standard JSON interface.

Capabilities

Source Code Compilation

Compile Solidity source code directly from a string. Ideal for dynamic compilation scenarios or when working with programmatically generated contracts.

def compile_source(
    source: str,
    output_values: Optional[List] = None,
    import_remappings: Optional[Union[Dict, List, str]] = None,
    base_path: Optional[Union[Path, str]] = None,
    allow_paths: Optional[Union[List, Path, str]] = None,
    output_dir: Optional[Union[Path, str]] = None,
    overwrite: bool = False,
    evm_version: Optional[str] = None,
    revert_strings: Optional[Union[List, str]] = None,
    metadata_hash: Optional[str] = None,
    metadata_literal: bool = False,
    optimize: bool = False,
    optimize_runs: Optional[int] = None,
    optimize_yul: Optional[bool] = None,
    no_optimize_yul: Optional[bool] = None,
    yul_optimizations: Optional[int] = None,
    solc_binary: Optional[Union[str, Path]] = None,
    solc_version: Optional[Union[str, Version]] = None,
    allow_empty: bool = False,
    **kwargs: Any,
) -> Dict:
    """
    Compile Solidity contract from source string.

    Parameters:
    - source: Solidity source code as string
    - output_values: List of compiler outputs to return (e.g., ['abi', 'bin'])
    - import_remappings: Path remappings for imports as dict, list, or string
    - base_path: Root path for source tree instead of filesystem root
    - allow_paths: Paths allowed for imports
    - output_dir: Directory for output files
    - overwrite: Whether to overwrite existing output files
    - evm_version: Target EVM version (e.g., 'london', 'berlin')
    - revert_strings: Revert string handling ('default', 'strip', 'debug')
    - metadata_hash: Metadata hash method ('ipfs', 'bzzr1', 'none')
    - metadata_literal: Store sources as literal data in metadata
    - optimize: Enable bytecode optimizer
    - optimize_runs: Optimization runs (lower = cheaper deployment, higher = cheaper execution)
    - optimize_yul: Enable Yul optimizer
    - no_optimize_yul: Disable Yul optimizer
    - yul_optimizations: Custom Yul optimization sequence
    - solc_binary: Path to specific solc binary
    - solc_version: Specific solc version to use
    - allow_empty: Don't raise exception if no contracts compiled

    Returns:
    Dict mapping contract names to compilation artifacts
    
    Raises:
    ContractsNotFound: No contracts found in source
    SolcError: Compilation failed
    """

Usage example:

import solcx

# Simple compilation
source = '''
pragma solidity ^0.8.0;
contract Example {
    uint256 public value = 42;
}
'''

compiled = solcx.compile_source(source)
contract = compiled['<stdin>:Example']
print("ABI:", contract['abi'])
print("Bytecode:", contract['bin'])

# With optimization
compiled_optimized = solcx.compile_source(
    source,
    optimize=True,
    optimize_runs=200
)

# Custom output values
compiled_custom = solcx.compile_source(
    source,
    output_values=['abi', 'bin', 'bin-runtime', 'opcodes']
)

File-Based Compilation

Compile one or more Solidity source files. Supports complex project structures with imports and dependencies.

def compile_files(
    source_files: Union[List, Path, str],
    output_values: Optional[List] = None,
    import_remappings: Optional[Union[Dict, List, str]] = None,
    base_path: Optional[Union[Path, str]] = None,
    allow_paths: Optional[Union[List, Path, str]] = None,
    output_dir: Optional[Union[Path, str]] = None,
    overwrite: bool = False,
    evm_version: Optional[str] = None,
    revert_strings: Optional[Union[List, str]] = None,
    metadata_hash: Optional[str] = None,
    metadata_literal: bool = False,
    optimize: bool = False,
    optimize_runs: Optional[int] = None,
    optimize_yul: Optional[bool] = None,
    no_optimize_yul: Optional[bool] = None,
    yul_optimizations: Optional[int] = None,
    solc_binary: Optional[Union[str, Path]] = None,
    solc_version: Optional[Union[str, Version]] = None,
    allow_empty: bool = False,
    **kwargs: Any,
) -> Dict:
    """
    Compile one or more Solidity source files.

    Parameters:
    - source_files: Path or list of paths to Solidity files
    - Other parameters same as compile_source()

    Returns:
    Dict mapping contract names to compilation artifacts
    
    Raises:
    ContractsNotFound: No contracts found in files
    SolcError: Compilation failed
    FileNotFoundError: Source file not found
    """

Usage example:

import solcx

# Compile single file
compiled = solcx.compile_files('contracts/Token.sol')

# Compile multiple files
compiled = solcx.compile_files([
    'contracts/Token.sol',
    'contracts/TokenSale.sol'
])

# With import remappings
compiled = solcx.compile_files(
    'contracts/Token.sol',
    import_remappings={
        '@openzeppelin': 'node_modules/@openzeppelin'
    }
)

# Output to directory
solcx.compile_files(
    'contracts/Token.sol',
    output_dir='build/contracts',
    overwrite=True
)

Standard JSON Interface

Compile using Solidity's standard JSON input/output interface. Provides the most flexibility and control over the compilation process.

def compile_standard(
    input_data: Dict,
    base_path: Optional[Union[str, Path]] = None,
    allow_paths: Optional[Union[List, Path, str]] = None,
    output_dir: Optional[str] = None,
    overwrite: bool = False,
    solc_binary: Optional[Union[str, Path]] = None,
    solc_version: Optional[Union[str, Version]] = None,
    allow_empty: bool = False,
) -> Dict:
    """
    Compile using standard JSON input/output interface.

    Parameters:
    - input_data: Standard JSON input specification
    - base_path: Root path for source tree
    - allow_paths: Paths allowed for imports
    - output_dir: Directory for output files
    - overwrite: Whether to overwrite existing files
    - solc_binary: Path to specific solc binary
    - solc_version: Specific solc version to use
    - allow_empty: Don't raise exception if no contracts compiled

    Returns:
    Standard JSON output specification
    
    Raises:
    ContractsNotFound: No sources in input JSON
    SolcError: Compilation failed with errors
    """

Usage example:

import solcx
import json

# Standard JSON input
input_json = {
    "language": "Solidity",
    "sources": {
        "Token.sol": {
            "content": "pragma solidity ^0.8.0; contract Token { uint256 public totalSupply = 1000000; }"
        }
    },
    "settings": {
        "optimizer": {
            "enabled": True,
            "runs": 200
        },
        "outputSelection": {
            "*": {
                "*": ["abi", "evm.bytecode", "evm.deployedBytecode"]
            }
        }
    }
}

# Compile with standard JSON
output = solcx.compile_standard(input_json)
contracts = output['contracts']['Token.sol']['Token']
print("ABI:", contracts['abi'])
print("Bytecode:", contracts['evm']['bytecode']['object'])

Bytecode Linking

Link library addresses into unlinked bytecode that contains library placeholders.

def link_code(
    unlinked_bytecode: str,
    libraries: Dict,
    solc_binary: Optional[Union[str, Path]] = None,
    solc_version: Optional[Version] = None,
) -> str:
    """
    Add library addresses into unlinked bytecode.

    Parameters:
    - unlinked_bytecode: Bytecode containing library placeholders
    - libraries: Library addresses as {"library_name": "address"}
    - solc_binary: Path to specific solc binary
    - solc_version: Specific solc version to use

    Returns:
    Linked bytecode string
    
    Raises:
    SolcError: Linking failed
    """

Usage example:

import solcx

# Unlinked bytecode with library placeholders
unlinked_bytecode = "608060405234801561001057600080fd5b50__$library_placeholder$__..."

# Library addresses
libraries = {
    "MyLibrary": "0x1234567890123456789012345678901234567890",
    "MathLib": "0x0987654321098765432109876543210987654321"
}

# Link the bytecode
linked_bytecode = solcx.link_code(unlinked_bytecode, libraries)
print("Linked bytecode:", linked_bytecode)

Version Information

Get version information about the currently active or specified Solidity compiler.

def get_solc_version(with_commit_hash: bool = False) -> Version:
    """
    Get version of the active solc binary.

    Parameters:
    - with_commit_hash: Include commit hash in version

    Returns:
    Version object of active solc
    
    Raises:
    SolcNotInstalled: No solc version is active
    SolcError: Cannot determine version
    """

Usage example:

import solcx

# Set a specific version
solcx.set_solc_version('0.8.19')

# Get version info
version = solcx.get_solc_version()
print(f"Active solc version: {version}")

# Get version with commit hash
version_with_commit = solcx.get_solc_version(with_commit_hash=True)
print(f"Full version: {version_with_commit}")

Error Handling

Compilation functions raise specific exceptions for different error conditions:

import solcx
from solcx import ContractsNotFound, SolcError

try:
    # This might fail
    compiled = solcx.compile_source("invalid solidity code")
except ContractsNotFound:
    print("No contracts found in source")
except SolcError as e:
    print(f"Compilation failed: {e}")
    print(f"Command: {' '.join(e.command)}")
    print(f"Return code: {e.return_code}")
    print(f"Stderr: {e.stderr_data}")

Install with Tessl CLI

npx tessl i tessl/pypi-py-solc-x

docs

compilation.md

exceptions.md

index.md

version-management.md

tile.json