0
# Standard JSON Compilation
1

2
Modern compilation interface providing comprehensive control over compilation settings and outputs, supporting the Solidity standard JSON format. This is the recommended approach for new projects as it provides better error handling and more flexibility.
3

4
## Capabilities
5

6
### Standard JSON Compilation
7

8
Compiles Solidity using the standard JSON interface, which provides comprehensive control over compilation settings and outputs.
9

10
```python { .api }
11
def compile_standard(input_data, allow_empty=False, **kwargs):
12
    """
13
    Compile using Solidity standard JSON interface.
14

15
    Args:
16
        input_data (dict): Standard JSON input data for compilation containing:
17
            - language: Must be 'Solidity'
18
            - sources: Dict mapping filenames to source content or urls
19
            - settings: Compilation settings including outputSelection
20
        allow_empty (bool): Whether to allow compilation with no contracts found
21
        **kwargs: Additional arguments passed to solc wrapper including:
22
            - solc_binary: Path to solc executable
23
            - allow_paths: Allowed import paths
24

25
    Returns:
26
        dict: Standard JSON compilation output containing:
27
            - contracts: Compiled contract data organized by source file and contract name
28
            - sources: Source file metadata and AST information  
29
            - errors: Compilation errors and warnings (if any)
30

31
    Raises:
32
        ContractsNotFound: When no contracts found and allow_empty=False
33
        SolcError: When compilation fails due to syntax errors or other issues
34
    """
35
```
36

37
## Usage Examples
38

39
### Basic Standard JSON Compilation
40

41
```python
42
from solc import compile_standard
43

44
# Basic compilation with content
45
result = compile_standard({
46
    'language': 'Solidity',
47
    'sources': {
48
        'SimpleContract.sol': {
49
            'content': '''
50
                pragma solidity ^0.4.24;
51
                contract SimpleContract {
52
                    uint256 public value;
53
                    
54
                    function setValue(uint256 _value) public {
55
                        value = _value;
56
                    }
57
                    
58
                    function getValue() public view returns (uint256) {
59
                        return value;
60
                    }
61
                }
62
            '''
63
        }
64
    },
65
    'settings': {
66
        'outputSelection': {
67
            '*': {
68
                '*': ['abi', 'evm.bytecode', 'evm.bytecode.sourceMap']
69
            }
70
        }
71
    }
72
})
73

74
# Access compiled contract
75
contract_data = result['contracts']['SimpleContract.sol']['SimpleContract']
76
abi = contract_data['abi']
77
bytecode = contract_data['evm']['bytecode']['object']
78
```
79

80
### Compilation with Multiple Files
81

82
```python
83
from solc import compile_standard
84

85
# Compile multiple contracts
86
result = compile_standard({
87
    'language': 'Solidity',
88
    'sources': {
89
        'Token.sol': {
90
            'content': '''
91
                pragma solidity ^0.4.24;
92
                import "./SafeMath.sol";
93
                contract Token {
94
                    using SafeMath for uint256;
95
                    mapping(address => uint256) public balances;
96
                }
97
            '''
98
        },
99
        'SafeMath.sol': {
100
            'content': '''
101
                pragma solidity ^0.4.24;
102
                library SafeMath {
103
                    function add(uint256 a, uint256 b) internal pure returns (uint256) {
104
                        uint256 c = a + b;
105
                        require(c >= a, "SafeMath: addition overflow");
106
                        return c;
107
                    }
108
                }
109
            '''
110
        }
111
    },
112
    'settings': {
113
        'outputSelection': {
114
            '*': {
115
                '*': ['abi', 'evm.bytecode.object', 'metadata']
116
            }
117
        }
118
    }
119
})
120
```
121

122
### Compilation from File URLs
123

124
```python
125
from solc import compile_standard
126

127
# Compile from file paths
128
result = compile_standard({
129
    'language': 'Solidity',
130
    'sources': {
131
        'MyContract.sol': {
132
            'urls': ['/path/to/contracts/MyContract.sol']
133
        }
134
    },
135
    'settings': {
136
        'outputSelection': {
137
            '*': {
138
                '*': ['abi', 'evm.bytecode']
139
            }
140
        }
141
    }
142
}, allow_paths="/path/to/contracts")
143
```
144

145
### Advanced Compilation Settings
146

147
```python
148
from solc import compile_standard
149

150
# Compilation with optimization and custom EVM version
151
result = compile_standard({
152
    'language': 'Solidity',
153
    'sources': {
154
        'OptimizedContract.sol': {
155
            'content': '''
156
                pragma solidity ^0.4.24;
157
                contract OptimizedContract {
158
                    function complexCalculation(uint256 x) public pure returns (uint256) {
159
                        return (x * x * x) + (x * x) + x + 1;
160
                    }
161
                }
162
            '''
163
        }
164
    },
165
    'settings': {
166
        'optimizer': {
167
            'enabled': True,
168
            'runs': 200
169
        },
170
        'evmVersion': 'byzantium',
171
        'outputSelection': {
172
            '*': {
173
                '*': ['abi', 'evm.bytecode', 'evm.deployedBytecode', 'evm.gasEstimates']
174
            }
175
        }
176
    }
177
})
178
```
179

180
### Error Handling
181

182
```python
183
from solc import compile_standard, SolcError
184

185
try:
186
    result = compile_standard({
187
        'language': 'Solidity',
188
        'sources': {
189
            'BrokenContract.sol': {
190
                'content': '''
191
                    pragma solidity ^0.4.24;
192
                    contract BrokenContract {
193
                        // Syntax error: missing semicolon
194
                        uint256 public value = 42
195
                    }
196
                '''
197
            }
198
        },
199
        'settings': {
200
            'outputSelection': {
201
                '*': {
202
                    '*': ['abi', 'evm.bytecode']
203
                }
204
            }
205
        }
206
    })
207
except SolcError as e:
208
    print(f"Compilation failed: {e}")
209
    # Error details are available in the exception
210
    if hasattr(e, 'stdout_data'):
211
        import json
212
        error_output = json.loads(e.stdout_data)
213
        for error in error_output.get('errors', []):
214
            print(f"Error: {error['formattedMessage']}")
215
```
216

217
## Input Format Specification
218

219
### Required Fields
220

221
- **language**: Must be 'Solidity'
222
- **sources**: Dictionary mapping source file names to source definitions
223

224
### Source Definitions
225

226
Each source can be defined with either:
227
- **content**: Inline source code as string
228
- **urls**: Array of file paths or URLs to source files
229

230
### Settings Object
231

232
Optional compilation settings:
233

234
```python
235
'settings': {
236
    'optimizer': {
237
        'enabled': bool,
238
        'runs': int
239
    },
240
    'evmVersion': str,  # 'homestead', 'tangerineWhistle', 'spuriousDragon', 'byzantium', etc.
241
    'outputSelection': {
242
        'file.sol': {
243
            'ContractName': ['abi', 'evm.bytecode', 'metadata', ...]
244
        }
245
    }
246
}
247
```
248

249
### Output Selection Options
250

251
Available output values for `outputSelection`:
252
- `'abi'`: Application Binary Interface
253
- `'metadata'`: Contract metadata
254
- `'evm.bytecode'`: Creation bytecode
255
- `'evm.deployedBytecode'`: Runtime bytecode  
256
- `'evm.gasEstimates'`: Gas usage estimates
257
- `'evm.methodIdentifiers'`: Method signature hashes
258
- `'evm.assembly'`: Assembly output
259
- `'devdoc'`: Developer documentation
260
- `'userdoc'`: User documentation
261

262
## Output Format
263

264
The standard JSON output contains:
265

266
```python
267
{
268
    'contracts': {
269
        'source_file.sol': {
270
            'ContractName': {
271
                'abi': [...],
272
                'metadata': '...',
273
                'evm': {
274
                    'bytecode': {
275
                        'object': '0x...',
276
                        'sourceMap': '...'
277
                    },
278
                    'deployedBytecode': {...},
279
                    'gasEstimates': {...}
280
                }
281
            }
282
        }
283
    },
284
    'sources': {
285
        'source_file.sol': {
286
            'id': 0,
287
            'ast': {...}
288
        }
289
    },
290
    'errors': [
291
        {
292
            'type': 'Warning',
293
            'component': 'general',
294
            'severity': 'warning',
295
            'message': '...',
296
            'formattedMessage': '...'
297
        }
298
    ]
299
}
300
```