Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update documentation #658

Merged
merged 5 commits into from
Dec 8, 2022
Merged

Update documentation #658

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
22a3c69
Fix ES6 import in the documentation
r0qs Sep 12, 2022
0de43fc
Add SRI recommendation
r0qs Sep 12, 2022
01125f1
General readme updates:
r0qs Sep 12, 2022
426df63
Use nodejs one-liner to compute SRI hash
r0qs Oct 31, 2022
3549bf4
Update note about old libsolc API
r0qs Oct 31, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 45 additions & 4 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -204,6 +204,11 @@ The low-level API is as follows:

For examples how to use them, please refer to the README of the above mentioned solc-js releases.

**Note**: These low-level functions remain available for compatibility reasons.
However, they were superseded by the `compile()` function and are no longer required.
Starting from version `0.5.0+commit.1d4f565a`, the functions `compileSingle`, `compileMulti`, and `compileCallback` are always `null` when using newer solc binary versions.
It is recommended to use the latest release of solc-js, but it should also handle all the older solc binaries down to `0.1.x`.

### Using with Electron

**Note:**
Expand Down Expand Up @@ -239,10 +244,20 @@ solc.loadRemoteVersion('latest', function(err, solcSnapshot) {
// An error was encountered, display and quit
} else {
// NOTE: Use `solcSnapshot` here with the same interface `solc` has
// For example:
const output = solcSnapshot.compile(/* ... */)
}
});
```

The version **must** be in the long format.
Thus, if you would like to use version `v0.8.17` you need to include the commit hash of the release.
You can extract the long version string for each version from the [publicly available release list](https://binaries.soliditylang.org/bin/list.json).

```javascript
solc.loadRemoteVersion('v0.8.17+commit.8df45f5f', function(err, solcSnapshot) { /* ... */ });
```

### Linking Bytecode

When using libraries, the resulting bytecode will contain placeholders for the real addresses of the referenced libraries. These have to be updated, via a process called linking, before deploying the contract.
Expand Down Expand Up @@ -308,13 +323,39 @@ Add the version of `solc` you want to use into `index.html`:
```html
<script
type="text/javascript"
src="https://binaries.soliditylang.org/bin/{{ SOLC VERSION }}.js"
src="https://binaries.soliditylang.org/bin/{{ SOLC_VERSION }}.js"
integrity="sha256-{{ BASE64_ENCODED_HASH_OF_SOLC_VERSION }}"
crossorigin="anonymous"
></script>
```

(Alternatively use `https://binaries.soliditylang.org/bin/soljson-latest.js` to get the latests version.)
This will load `solc` into the global variable `window.Module`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Into the global variable or is that a namespace / object? Maybe saying assigning it as a member of window.Module would be more precise?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think global variable is correct. I mean, the Module is a property of window and thus a global variable since window is a global object of a web page that refers to itself. I may be wrong, but solc is not assigned as a member of the window.Module, it is loaded as the Module object in the window. Maybe global object would be correct, too. Like:

This will load solc as the global object window.Module.

But honestly, I'm not sure about the terminology. I usually refer to any window property as global variables, but I may be calling them by the wrong name, haha

Alternatively, use `soljson-latest.js` as `{{ SOLC_VERSION }}.js` in the code snippet above to load the latest version.

It is recommended that you check the integrity of the resource being fetched before using it in your application.
For that, you can use the [Subresource Integrity (SRI)](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity) feature.
Adding SRI configuration to your HTML script tag ensures that the resource will only be loaded by the browser if the cryptographic hashes match.

You can generate the SRI hash yourself based on the base64-encoded version of the sha256 hash of the release.
For example, after downloading version `v0.8.16+commit.07a7930e`, run:
```bash
node -e "console.log(crypto.createHash('sha256').update(fs.readFileSync('./soljson-v0.8.16+commit.07a7930e.js', 'utf8')).digest('base64'))"
```
```
J7KCDvk4BaZcdreUWklDJYLTBv0XoomFcJpR5kA2d8I=
```

And update your `index.html` to:
```html
<script
type="text/javascript"
src="https://binaries.soliditylang.org/bin/soljson-v0.8.16+commit.07a7930e.js"
integrity="sha256-J7KCDvk4BaZcdreUWklDJYLTBv0XoomFcJpR5kA2d8I="
crossorigin="anonymous"
></script>
```

This will load `solc` into the global variable `window.Module`. Then use this inside Javascript as:
Then use this inside JavaScript as:

```javascript
var wrapper = require('solc/wrapper');
Expand All @@ -324,7 +365,7 @@ var solc = wrapper(window.Module);
Or in ES6 syntax:

```javascript
import * as wrapper from 'solc/wrapper';
import wrapper from 'solc/wrapper';
const solc = wrapper(window.Module);
```

Expand Down