0
# Core Compilation
1

2
Primary compilation interface supporting Standard JSON I/O format with import callbacks and SMT solver integration. Provides both high-level unified API and low-level version-specific access.
3

4
## Capabilities
5

6
### High-Level Compilation
7

8
Standard JSON compilation interface that works uniformly across all compiler versions.
9

10
```typescript { .api }
11
/**
12
 * Compile Solidity source code using Standard JSON I/O format
13
 * @param input - Standard JSON input as string
14
 * @param callbacks - Optional callbacks for import resolution and SMT solving
15
 * @returns Standard JSON output as string
16
 */
17
function compile(input: string, callbacks?: CompilationCallbacks): string;
18

19
interface CompilationCallbacks {
20
  /** Callback to resolve import statements */
21
  import?: (path: string) => { contents: string } | { error: string };
22
  /** Callback to solve SMT queries for formal verification */
23
  smtSolver?: (query: string) => { contents: string } | { error: string };
24
}
25
```
26

27
**Usage Examples:**
28

29
```typescript
30
import solc from "solc";
31

32
// Basic compilation without callbacks
33
const input = {
34
  language: 'Solidity',
35
  sources: {
36
    'Contract.sol': {
37
      content: 'contract Test { uint public value = 42; }'
38
    }
39
  },
40
  settings: {
41
    outputSelection: {
42
      '*': {
43
        '*': ['abi', 'evm.bytecode']
44
      }
45
    }
46
  }
47
};
48

49
const output = JSON.parse(solc.compile(JSON.stringify(input)));
50
console.log(output.contracts['Contract.sol']['Test'].evm.bytecode.object);
51
```
52

53
### Compilation with Import Callback
54

55
Handle contract dependencies and imports through callback resolution.
56

57
```typescript
58
import solc from "solc";
59
import fs from "fs";
60

61
const input = {
62
  language: 'Solidity',
63
  sources: {
64
    'Main.sol': {
65
      content: 'import "./Library.sol"; contract Main { Library lib; }'
66
    }
67
  },
68
  settings: {
69
    outputSelection: {
70
      '*': { '*': ['*'] }
71
    }
72
  }
73
};
74

75
function findImports(path) {
76
  try {
77
    return {
78
      contents: fs.readFileSync(path, 'utf8')
79
    };
80
  } catch (e) {
81
    return { error: 'File not found' };
82
  }
83
}
84

85
const output = JSON.parse(
86
  solc.compile(JSON.stringify(input), { import: findImports })
87
);
88
```
89

90
### Low-Level Compilation API
91

92
Direct access to compiler-specific interfaces for advanced use cases and older compiler versions.
93

94
```typescript { .api }
95
interface LowLevelAPI {
96
  /** Legacy single file compilation (may be null for newer versions) */
97
  compileSingle: ((input: string, optimize: boolean) => string) | null;
98
  /** Legacy multi-file compilation (may be null for newer versions) */
99
  compileMulti: ((input: string, optimize: boolean) => string) | null;
100
  /** Legacy callback-based compilation (may be null for newer versions) */
101
  compileCallback: ((input: string, optimize: boolean, callback: any) => string) | null;
102
  /** Standard JSON compilation for newer versions */
103
  compileStandard: ((input: string, callback?: any) => string) | null;
104
}
105
```
106

107
**Usage Examples:**
108

109
```typescript
110
import solc from "solc";
111

112
// Check feature availability
113
if (solc.lowlevel.compileStandard) {
114
  // Use standard JSON interface directly
115
  const result = solc.lowlevel.compileStandard(JSON.stringify(input));
116
} else if (solc.lowlevel.compileMulti) {
117
  // Fallback to legacy multi-file interface
118
  const result = solc.lowlevel.compileMulti(JSON.stringify({sources: {...}}), false);
119
}
120
```
121

122
### Compiler Features Detection
123

124
Detect available features and capabilities of the current compiler instance.
125

126
```typescript { .api }
127
interface CompilerFeatures {
128
  /** Support for legacy single input compilation */
129
  legacySingleInput: boolean;
130
  /** Support for multiple input files */
131
  multipleInputs: boolean;
132
  /** Support for import callback functions */
133
  importCallback: boolean;
134
  /** Native Standard JSON I/O support */
135
  nativeStandardJSON: boolean;
136
}
137
```
138

139
### Compiler Information
140

141
Access version and license information from the compiler instance.
142

143
```typescript { .api }
144
/**
145
 * Get the full version string of the compiler
146
 * @returns Version string (e.g., "0.8.30+commit.12345678.Emscripten.clang")
147
 */
148
function version(): string;
149

150
/**
151
 * Get semver-compatible version string
152
 * @returns Semantic version string (e.g., "0.8.30+commit.12345678")
153
 */
154
function semver(): string;
155

156
/**
157
 * Get compiler license information
158
 * @returns License string
159
 */
160
function license(): string;
161
```
162

163
## Standard JSON Format
164

165
### Input Format
166

167
```typescript { .api }
168
interface StandardJSONInput {
169
  language: "Solidity";
170
  sources: {
171
    [filename: string]: {
172
      content: string;
173
    };
174
  };
175
  settings?: {
176
    optimizer?: {
177
      enabled: boolean;
178
      runs?: number;
179
    };
180
    outputSelection: {
181
      [file: string]: {
182
        [contract: string]: string[];
183
      };
184
    };
185
    libraries?: {
186
      [file: string]: {
187
        [library: string]: string;
188
      };
189
    };
190
    modelChecker?: {
191
      engine: "chc" | "bmc";
192
      solvers?: string[];
193
      timeout?: number;
194
    };
195
  };
196
}
197
```
198

199
### Output Format
200

201
```typescript { .api }
202
interface StandardJSONOutput {
203
  contracts?: {
204
    [filename: string]: {
205
      [contractName: string]: {
206
        abi: any[];
207
        metadata: string;
208
        evm: {
209
          bytecode: {
210
            object: string;
211
            opcodes: string;
212
            sourceMap: string;
213
            linkReferences: LinkReferences;
214
          };
215
          deployedBytecode: {
216
            object: string;
217
            sourceMap: string;
218
            linkReferences: LinkReferences;
219
          };
220
          methodIdentifiers: { [signature: string]: string };
221
          gasEstimates: {
222
            creation: {
223
              codeDepositCost: string;
224
              executionCost: string;
225
            };
226
            external: { [method: string]: string };
227
            internal: { [method: string]: string };
228
          };
229
        };
230
      };
231
    };
232
  };
233
  sources?: {
234
    [filename: string]: {
235
      id: number;
236
      legacyAST: any;
237
    };
238
  };
239
  errors?: Array<{
240
    type: string;
241
    component: string;
242
    severity: "error" | "warning";
243
    message: string;
244
    formattedMessage: string;
245
    sourceLocation?: {
246
      file: string;
247
      start: number;
248
      end: number;
249
    };
250
  }>;
251
}
252
```