0
# Version Management
1

2
Load specific compiler versions remotely and manage compiler instances with feature detection capabilities.
3

4
## Capabilities
5

6
### Remote Version Loading
7

8
Load specific Solidity compiler versions from the official solc-bin repository on GitHub.
9

10
```typescript { .api }
11
/**
12
 * Load a specific compiler version from GitHub
13
 * @param versionString - Full version string with commit hash (e.g., "v0.8.17+commit.8df45f5f")
14
 * @param callback - Function called with error or compiler instance
15
 */
16
function loadRemoteVersion(
17
  versionString: string,
18
  callback: (error: Error | null, solc?: CompilerInstance) => void
19
): void;
20
```
21

22
**Usage Examples:**
23

24
```typescript
25
import solc from "solc";
26

27
// Load specific version
28
solc.loadRemoteVersion('v0.8.17+commit.8df45f5f', (err, solcSnapshot) => {
29
  if (err) {
30
    console.error('Failed to load compiler:', err);
31
    return;
32
  }
33
  
34
  // Use the loaded compiler instance
35
  const input = {
36
    language: 'Solidity',
37
    sources: {
38
      'test.sol': {
39
        content: 'contract Test { uint public value = 42; }'
40
      }
41
    },
42
    settings: {
43
      outputSelection: { '*': { '*': ['*'] } }
44
    }
45
  };
46
  
47
  const output = solcSnapshot.compile(JSON.stringify(input));
48
  console.log('Compiled with version:', solcSnapshot.version());
49
});
50

51
// Load latest development snapshot
52
solc.loadRemoteVersion('latest', (err, solcSnapshot) => {
53
  if (err) {
54
    console.error('Failed to load latest:', err);
55
    return;
56
  }
57
  
58
  console.log('Loaded latest version:', solcSnapshot.version());
59
});
60
```
61

62
### Version Format Requirements
63

64
The version string must be in the long format with commit hash. You can find available versions at the [publicly available release list](https://binaries.soliditylang.org/bin/list.json).
65

66
**Correct formats:**
67
- `v0.8.17+commit.8df45f5f` (specific release)
68
- `latest` (latest development snapshot)
69

70
**Incorrect formats:**
71
- `v0.8.17` (missing commit hash)
72
- `0.8.17` (missing 'v' prefix)
73

74
### Setup Methods
75

76
Create wrapper functions around raw compiler modules for consistent API access.
77

78
```typescript { .api }
79
/**
80
 * Create wrapper functions around a raw compiler module
81
 * @param soljson - Raw compiler module (e.g., from require('./soljson.js'))
82
 * @returns Wrapped compiler instance with standard API
83
 */
84
function setupMethods(soljson: any): CompilerInstance;
85
```
86

87
**Usage Examples:**
88

89
```typescript
90
import solc from "solc";
91

92
// Load local soljson binary and wrap it
93
const soljson = require('./path/to/soljson.js');
94
const wrappedSolc = solc.setupMethods(soljson);
95

96
console.log('Local compiler version:', wrappedSolc.version());
97
```
98

99
### Feature Detection
100

101
Each compiler instance provides feature detection to determine available capabilities.
102

103
```typescript { .api }
104
interface CompilerFeatures {
105
  /** Support for legacy single input compilation */
106
  legacySingleInput: boolean;
107
  /** Support for multiple input files */
108
  multipleInputs: boolean;
109
  /** Support for import callback functions */
110
  importCallback: boolean;
111
  /** Native Standard JSON I/O support */
112
  nativeStandardJSON: boolean;
113
}
114
```
115

116
**Usage Examples:**
117

118
```typescript
119
import solc from "solc";
120

121
// Check what features are available
122
if (solc.features.nativeStandardJSON) {
123
  console.log('Supports native Standard JSON');
124
} else {
125
  console.log('Using legacy compatibility layer');
126
}
127

128
if (solc.features.importCallback) {
129
  // Can use import callbacks
130
  const callbacks = { import: findImports };
131
  const output = solc.compile(input, callbacks);
132
} else {
133
  // Must inline all dependencies
134
  const output = solc.compile(input);
135
}
136
```
137

138
### Browser Compatibility
139

140
When using in browsers, compiler loading must be done through web workers due to size and performance constraints.
141

142
**Web Worker Example:**
143

144
```javascript
145
// worker.js
146
importScripts('https://binaries.soliditylang.org/bin/soljson-v0.8.19+commit.7dd6d404.js');
147
import wrapper from 'solc/wrapper';
148

149
self.addEventListener('message', () => {
150
  const compiler = wrapper(self.Module);
151
  self.postMessage({
152
    version: compiler.version()
153
  });
154
}, false);
155
```
156

157
```html
158
<!-- index.html -->
159
<script>
160
var worker = new Worker('./worker.js');
161
worker.addEventListener('message', function (e) {
162
  console.log('Compiler version:', e.data.version);
163
}, false);
164

165
worker.postMessage({});
166
</script>
167
```
168

169
### Version Translation
170

171
Convert between different version string formats for compatibility.
172

173
```typescript { .api }
174
/**
175
 * Convert old-style version strings to semver-compatible format
176
 * @param version - Version string in any format
177
 * @returns Semver-compatible version string
178
 */
179
function versionToSemver(version: string): string;
180
```
181

182
**Usage Examples:**
183

184
```typescript
185
import translate from "solc/translate";
186

187
// Convert old-style versions
188
const oldVersion = "0.3.6-3fc68da5/Release-Emscripten/clang";
189
const semverVersion = translate.versionToSemver(oldVersion);
190
console.log(semverVersion); // "0.3.6+commit.3fc68da5"
191

192
// Handle special cases
193
console.log(translate.versionToSemver("0.1.3-0")); // "0.1.3"
194
console.log(translate.versionToSemver("0.4.5+commit.b318366e.Emscripten.clang")); // "0.4.5+commit.b318366e.Emscripten.clang"
195
```
196

197
### Electron Integration
198

199
When using with Electron, disable node integration to avoid conflicts with the require method.
200

201
```javascript
202
new BrowserWindow({
203
  webPreferences: {
204
    nodeIntegration: false
205
  }
206
});
207
```