Using the Compiler

py-solc-x-ir provides several functions that you can use to interact with the solc compiler.

Compiling a Source String

solcxir.compile_source(source, **kwargs)

Compile a Solidity contract.

Compilation is handled via the --combined-json flag. Depending on the Solidity version used, some keyword arguments may not be available.

Returns a dict, where each top-level key is a contract. The filename will be <stdin>.

>>> import solcxir
>>> solcxir.compile_source(
...     "contract Foo { function bar() public { return; } }",
...     output_values=["abi", "bin-runtime"],
...     solc_version="0.7.0"
... )
{
    '<stdin>:Foo': {
        'abi': [{'inputs': [], 'name': 'bar', 'outputs': [], 'stateMutability': 'nonpayable', 'type': 'function'}],
        'bin-runtime': '6080604052348015600f57600080fd5b506004361060285760003560e01c8063febb0f7e14602d575b600080fd5b60336035565b005b56fea26469706673582212203cfdbce82ee8eab351107edac2ebb9dbe5c1aa8bd26609b0eedaa105ed3d4dce64736f6c63430007000033'
    }
}

Required Arguments

source str
Solidity contract to be compiled.

Optional py-solc-x-ir Arguments

solc_binary str | Path
Path of the solc binary to use. May be given as a string or Path object. If not given, the currently active version is used (as set by solcxir.set_solc_version)

solc_version str | Version
solc version to use. May be given as a string or Version object. If not given, the currently active version is used. Ignored if solc_binary is also given.

allow_empty bool
If True, do not raise when no compiled contracts are returned. Defaults to False.

Optional Compiler Arguments

Depending on the Solidity version used, using some of these arguments may raise UnknownOption. See the documentation for your target Solidity version for more information.

output_values List
Compiler outputs to return. Valid options depend on the version of solc. If not given, all possible outputs for the active version are returned.

import_remappings Dict | List | str
Path remappings. May be given as a string or list of strings formatted as "prefix=path", or a dict of {"prefix": "path"}.

base_path Path | str
Use the given path as the root of the source tree instead of the root of the filesystem.

allow_paths List | Path | str
A path, or list of paths, to allow for imports.

output_dir str
Creates one file per component and contract/file at the specified directory.

overwrite bool
Overwrite existing files (used in combination with output_dir)

evm_version str
Select the desired EVM version. Valid options depend on the solc version.

revert_strings List | str
Strip revert (and require) reason strings or add additional debugging information.

metadata_hash str
Choose hash method for the bytecode metadata or disable it.

metadata_literal bool
Store referenced sources as literal data in the metadata output.

optimize bool
Enable bytecode optimizer.

optimize_runs int
Set for how many contract runs to optimize. Lower values will optimize more for initial deployment cost, higher values will optimize more for high-frequency usage.

optimize_yul bool
Enable the yul optimizer.

no_optimize_yul bool
Disable the yul optimizer.

yul_optimizations int
Force yul optimizer to use the specified sequence of optimization steps instead of the built-in one.

Compiling Files

solcxir.compile_files(source, **kwargs)

Compile one or more Solidity source files.

Compilation is handled via the --combined-json flag. Depending on the Solidity version used, some keyword arguments may not be available.

Returns a dict, where each top-level key is a contract.

>>> import solcxir
>>> solcxir.compile_files(
...     ["Foo.sol"],
...     output_values=["abi", "bin-runtime"],
...     solc_version="0.7.0"
... )
{
    '<stdin>:Foo': {
        'abi': [{'inputs': [], 'name': 'bar', 'outputs': [], 'stateMutability': 'nonpayable', 'type': 'function'}],
        'bin-runtime': '6080604052348015600f57600080fd5b506004361060285760003560e01c8063febb0f7e14602d575b600080fd5b60336035565b005b56fea26469706673582212203cfdbce82ee8eab351107edac2ebb9dbe5c1aa8bd26609b0eedaa105ed3d4dce64736f6c63430007000033'
    }
}

Required Arguments

source_files List | Path | str
Solidity source file, or list of source files, to be compiled. Files may be given as strings or Path objects.

Optional py-solc-x-ir Arguments

solc_binary str | Path
Path of the solc binary to use. May be given as a string or Path object. If not given, the currently active version is used (as set by solcxir.set_solc_version)

solc_version str | Version
solc version to use. May be given as a string or Version object. If not given, the currently active version is used. Ignored if solc_binary is also given.

allow_empty bool
If True, do not raise when no compiled contracts are returned. Defaults to False.

Optional Compiler Arguments

Depending on the Solidity version used, using some of these arguments may raise UnknownOption. See the documentation for your target Solidity version for more information.

output_values List
Compiler outputs to return. Valid options depend on the version of solc. If not given, all possible outputs for the active version are returned.

import_remappings Dict | List | str
Path remappings. May be given as a string or list of strings formatted as "prefix=path", or a dict of {"prefix": "path"}.

base_path Path | str
Use the given path as the root of the source tree instead of the root of the filesystem.

allow_paths List | Path | str
A path, or list of paths, to allow for imports.

output_dir str
Creates one file per component and contract/file at the specified directory.

overwrite bool
Overwrite existing files (used in combination with output_dir)

evm_version str
Select the desired EVM version. Valid options depend on the solc version.

revert_strings List | str
Strip revert (and require) reason strings or add additional debugging information.

metadata_hash str
Choose hash method for the bytecode metadata or disable it.

metadata_literal bool
Store referenced sources as literal data in the metadata output.

optimize bool
Enable bytecode optimizer.

optimize_runs int
Set for how many contract runs to optimize. Lower values will optimize more for initial deployment cost, higher values will optimize more for high-frequency usage.

optimize_yul bool
Enable the yul optimizer.

no_optimize_yul bool
Disable the yul optimizer.

yul_optimizations int
Force yul optimizer to use the specified sequence of optimization steps instead of the built-in one.

Compiling with the Standard JSON Format

solcxir.compile_standard(input_data, **kwargs)

Compile Solidity contracts using the JSON-input-output interface.

See the Solidity documentation on the compiler input-output JSON for details on the expected JSON input and output formats.

Required Arguments

input_data Dict
Compiler JSON input.

Optional py-solc-x-ir Arguments

solc_binary str | Path
Path of the solc binary to use. May be given as a string or Path object. If not given, the currently active version is used (as set by solcxir.set_solc_version)

solc_version str | Version
solc version to use. May be given as a string or Version object. If not given, the currently active version is used. Ignored if solc_binary is also given.

allow_empty bool
If True, do not raise when no compiled contracts are returned. Defaults to False.

Optional Compiler Arguments

Depending on the Solidity version used, using some of these arguments may raise UnknownOption. See the documentation for your target Solidity version for more information.

base_path Path | str
Use the given path as the root of the source tree instead of the root of the filesystem.

allow_paths List | Path | str
A path, or list of paths, to allow for imports.

output_dir str
Creates one file per component and contract/file at the specified directory.

overwrite bool
Overwrite existing files (used in combination with output_dir)

Linking Libraries

solcxir.link_code(unlinked_bytecode, libraries, solc_binary=None, solc_version=None)

Add library addresses into unlinked bytecode.

See the Solidity documentation on using the commandline compiler for more information on linking libraries.

Returns the linked bytecode as a string.

>>> import solcxir
>>> unlinked_bytecode = "606060405260768060106000396000f3606060405260e060020a6000350463e7f09e058114601a575b005b60187f0c55699c00000000000000000000000000000000000000000000000000000000606090815273__TestA_________________________________90630c55699c906064906000906004818660325a03f41560025750505056"

>>> solcxir.link_code(
...     unlinked_bytecode,
...     {'TestA': "0xd3cda913deb6f67967b99d67acdfa1712c293601"}
... )
"606060405260768060106000396000f3606060405260e060020a6000350463e7f09e058114601a575b005b60187f0c55699c00000000000000000000000000000000000000000000000000000000606090815273d3cda913deb6f67967b99d67acdfa1712c29360190630c55699c906064906000906004818660325a03f41560025750505056"

Required Arguments

unlinked_bytecode str
Compiled bytecode containing one or more library placeholders.

libraries Dict
Library addresses given as {"library name": "address"}

Optional py-solc-x-ir Arguments

solc_binary str | Path
Path of the solc binary to use. May be given as a string or Path object. If not given, the currently active version is used (as set by solcxir.set_solc_version)

solc_version str | Version
solc version to use. May be given as a string or Version object. If not given, the currently active version is used. Ignored if solc_binary is also given.