You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/developers/reproducible-contract-builds.md
+21-28Lines changed: 21 additions & 28 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -11,7 +11,7 @@ You will also learn how to reproduce a contract build, given its source code and
11
11
> **Reproducible builds**, also known as **deterministic compilation**, is a process of compiling software which ensures the resulting binary code can be reproduced. Source code compiled using deterministic compilation will always output the same binary [[Wikipedia]](https://en.wikipedia.org/wiki/Reproducible_builds).
12
12
13
13
:::important
14
-
As of September 2022, the Rust toolchain does not support reproducible builds out-of-the-box, thus we recommend smart contract developers to follow this tutorial in order to achieve deterministic compilation.
14
+
As of May 2024, the Rust toolchain does not support reproducible builds out-of-the-box, thus we recommend smart contract developers to follow this tutorial in order to achieve deterministic compilation.
15
15
:::
16
16
17
17
[comment]: #(mx-context-auto)
@@ -22,12 +22,12 @@ Before diving into contract build reproducibility, let's grasp the concept of `c
22
22
23
23
When a smart contract is deployed, the network stores the bytecode, and also computes its `blake2b` checksum (using a digest length of 256 bits). This is called the `codehash`.
24
24
25
-
Assume that we are interested into the following contract, deployed on _devnet_: [erd1qqqqqqqqqqqqqpgqahertgz4020wegswus8m7f2ak8a6d0gv396qw3t2zy](https://devnet-explorer.multiversx.com/accounts/erd1qqqqqqqqqqqqqpgqahertgz4020wegswus8m7f2ak8a6d0gv396qw3t2zy). It's source code is published on [GitHub](https://github.com/multiversx/mx-reproducible-contract-build-example-sc).
25
+
Assume that we are interested into the following contract (a simple on-chain **adder**), deployed on _devnet_: [erd1qqqqqqqqqqqqqpgqws44xjx2t056nn79fn29q0rjwfrd3m43396ql35kxy](https://devnet-explorer.multiversx.com/accounts/erd1qqqqqqqqqqqqqpgqws44xjx2t056nn79fn29q0rjwfrd3m43396ql35kxy). It's source code is published on [GitHub](https://github.com/multiversx/mx-contracts-rs).
26
26
27
27
We can fetch the _codehash_ of the contract from the API:
All in all, in order to verify the bytecode equality of two given builds of a contract we can simply compare the _codehash_ property.
@@ -58,37 +58,30 @@ All in all, in order to verify the bytecode equality of two given builds of a co
58
58
59
59
## Supporting reproducible builds
60
60
61
-
As of October 2022, the recommended approach to support reproducible builds for your smart contract is to use a build script relying on a specially-designed, [publicly-available, tagged Docker image](https://hub.docker.com/r/multiversx/sdk-rust-contract-builder/tags), that includes tagged, explicit versions of the build tools (_Rust_, _wasm-opt_ etc.).
61
+
As of May 2024, the recommended approach to support reproducible builds for your smart contract is to use a build script relying on a specially-designed, [publicly-available, tagged Docker image](https://hub.docker.com/r/multiversx/sdk-rust-contract-builder/tags), that includes tagged, explicit versions of the build tools (_Rust_, _wasm-opt_ etc.).
62
62
63
63
This approach is recommended in order to counteract eventual pieces of non-determinism related to `cargo`'s (essential component of the Rust toolchain) sensibility on the environment.
64
64
65
65
:::important
66
-
If the code source of your smart contract is hosted on GitHub, then it's a good practice to define a GitHub Workflow similar to [this one](https://github.com/multiversx/mx-reproducible-contract-build-example-sc/blob/main/.github/workflows/on_release_build_contracts.yml), which performs the deployment (production-ready) build within the _release_ procedure.
66
+
If the code source of your smart contract is hosted on GitHub, then it's a good practice to define a GitHub Workflow similar to [release.yml](https://github.com/multiversx/mx-contracts-rs/blob/main/.github/workflows/release.yml), which performs the deployment (production-ready) build within the _release_ procedure. Additionally, define a dry-run reproducible build on all your branches. See this workflow as an example: [on_pull_request_build_contracts.yml](https://github.com/multiversx/mx-contracts-rs/blob/main/.github/workflows/on_pull_request_build_contracts.yml).
67
67
:::
68
68
69
69
[comment]: #(mx-context-auto)
70
70
71
71
### Choose an image tag
72
72
73
-
The first step for supporting reproducible builds is to decide on a specific Docker image tag to use. Check the **frozen** tags listed at [multiversx/sdk-rust-contract-builder](https://hub.docker.com/r/multiversx/sdk-rust-contract-builder/tags), and inspect their labels - especially the labels `rust` and `wasm-opt-binaryen`:
74
-
75
-
```
76
-
LABEL rust=nightly-2022-08-23
77
-
LABEL wasm-opt-binaryen=version_105
78
-
```
79
-
80
73
For a new smart contract that isn't released yet (deployed on the network), it's recommended to pick the tag with the **largest index number**, which tipically includes recent versions of `rust` and other necessary dependencies.
81
74
82
75
However, for minor releases or patches, it's wise to stick to the previously chosen image tag, for the same (nuanced) reasons you would not embrace an update of your development tools in the middle of fixing a critical bug (in any development context).
83
76
84
-
The chosen, _frozen_ image tag should accompany the versioned source code (e.g. via _release notes_), in order to inform others on how to reproduce a specific build (of a specific source code version). In this context, _frozen_ image tag refers to a Docker image tag that will never get any updates after its initial publishing.
77
+
The chosen, _frozen_ image tag **should accompany the versioned source code (e.g. via _release notes_), in order to inform others on how to reproduce a specific build** (of a specific source code version). In this context, a_frozen_ image tag refers to a Docker image tag that will never get any updates after its initial publishing.
85
78
86
79
:::tip
87
80
It's perfectly normal to switch to a newer image tag on each (major) release of your contract. Just make sure you spread this information - i.e. using _release notes_.
88
81
:::
89
82
90
83
:::caution
91
-
Never pick the tag called `latest` for production-ready builds.
84
+
Never pick the tag called `latest`or `next`for production-ready builds.
92
85
:::
93
86
94
87
[comment]: #(mx-context-auto)
@@ -101,14 +94,14 @@ In this section, you'll learn how to run a reproducible build, or, to put it dif
101
94
102
95
### Fetch the source code
103
96
104
-
Let's clone the [example source code](https://github.com/multiversx/mx-reproducible-contract-build-example-sc) locally, and switch to [a certain version](https://github.com/multiversx/mx-reproducible-contract-build-example-sc/releases/tag/v0.2.0) that we'd like to build:
97
+
Let's clone [mx-contracts-rs](https://github.com/multiversx/mx-contracts-rs) locally, and switch to [a certain version](https://github.com/multiversx/mx-contracts-rs/releases/tag/v0.45.4) that we'd like to build:
By inspecting the release notes, we see that [`v0.2.0`](https://github.com/multiversx/mx-reproducible-contract-build-example-sc/releases/tag/v0.2.0) was built using the `image:tag = multiversx/sdk-rust-contract-builder:v4.1.0`.
104
+
By inspecting the release notes, we see that [`v0.45.4`](https://github.com/multiversx/mx-contracts-rs/releases/tag/v0.45.4) was built using the `image:tag = multiversx/sdk-rust-contract-builder:v5.4.1`.
This will build all the smart contracts inside the current working directory. If you want to build the smart contracts inside another directory, you can specify an input directory:
Upon a successful build, an output folder named `output-docker` will be generated containing:
192
+
Upon a successful build, an output folder named `output-docker` will be generated. It contains one subfolder for each contract, each holding the following files:
200
193
201
194
-`contract.wasm`: the actual bytecode of the smart contract, to be deployed on the network;
202
195
-`contract.abi.json`: the ABI of the smart contract (a listing of endpoints and types definitions), to be used when developing dApps or simply interacting with the contract (e.g. using _sdk-js_);
203
196
-`contract.codehash.txt`: the computed `codehash` of the contract.
We can see that it matches the previously fetched (or computed) codehash. That is, the contract deployed at [erd1qqqqqqqqqqqqqpgqahertgz4020wegswus8m7f2ak8a6d0gv396qw3t2zy](https://devnet-explorer.multiversx.com/accounts/erd1qqqqqqqqqqqqqpgqahertgz4020wegswus8m7f2ak8a6d0gv396qw3t2zy) is guaranteed to have been built from the same source code version as the one that we've checked out.
215
+
We can see that it matches the previously fetched (or computed) codehash. That is, the contract deployed at [erd1qqqqqqqqqqqqqpgqws44xjx2t056nn79fn29q0rjwfrd3m43396ql35kxy](https://devnet-explorer.multiversx.com/accounts/erd1qqqqqqqqqqqqqpgqws44xjx2t056nn79fn29q0rjwfrd3m43396ql35kxy) is guaranteed to have been built from the same source code version as the one that we've checked out.
223
216
224
217
**Congratulations!** You've achieved a reproducible contract build 🎉
This tutorial will guide you through the process of extending and tailoring certain modules from sdk-js.
10
10
11
+
:::important
12
+
Documentation in this section is preliminary and subject to change.
13
+
:::
14
+
11
15
[comment]: #(mx-context-auto)
12
16
13
17
## Extending the Network Providers
@@ -16,74 +20,9 @@ The default classes from `@multiversx/sdk-network-providers` should **only be us
16
20
17
21
[comment]: #(mx-context-auto)
18
22
19
-
### Performing HTTP requests from scratch
20
-
21
-
One can broadcast transactions and GET resources from the MultiversX API (or Gateway) by performing simple HTTP requests using the `axios` utility. Below are a few examples:
22
-
23
-
Broadcasting a transaction:
24
-
25
-
```
26
-
import axios, { AxiosResponse } from "axios";
27
-
28
-
let tx = new Transaction({ /* provide the fields */ });
29
-
// ... sign the transaction using a dApp / signing provider
30
-
let data = tx.toSendable();
31
-
let url = "https://devnet-api.multiversx.com/transactions";
32
-
let response: AxiosResponse = await axios.post(url, data, {
33
-
headers: {
34
-
"Content-Type": "application/json",
35
-
}
36
-
});
37
-
let txHash = response.data.txHash;
38
-
```
39
-
40
-
Fetching a transaction:
41
-
42
-
```
43
-
let url = `https://devnet-api.multiversx.com/transactions/${txHash}`;
44
-
let response = await axios.get(url);
45
-
let transactionOnNetwork = TransactionOnNetwork.fromApiHttpResponse(txHash, response.data);
46
-
```
47
-
48
-
Querying a smart contract (with parsing the results):
49
-
50
-
```
51
-
let query = contract.createQuery({
52
-
func: new ContractFunction("foobar"),
53
-
args: [new AddressValue(addressOfAlice)],
54
-
caller: new Address("erd1...")
55
-
});
56
-
57
-
let url = "https://devnet-api.multiversx.com/query";
let endpointDefinition = contract.getEndpoint("foobar");
79
-
let { firstValue, secondValue, returnCode } = resultsParser.parseQueryResponse(queryResponse, endpointDefinition);
80
-
```
81
-
82
-
[comment]: #(mx-context-auto)
83
-
84
23
### Extending a default Network Provider
85
24
86
-
You can also derive from the default network providers (`ApiNetworkProvider` and `ProxyNetworkProvider`) and overwrite / add additional methods, making use of `doGetGeneric()` and `doPostGeneric()`.
25
+
You can derive from the default network providers (`ApiNetworkProvider` and `ProxyNetworkProvider`) and overwrite / add additional methods, making use of `doGetGeneric()` and `doPostGeneric()`. For example:
87
26
88
27
```
89
28
export class MyTailoredNetworkProvider extends ApiNetworkProvider {
@@ -103,36 +42,6 @@ export class MyTailoredNetworkProvider extends ApiNetworkProvider {
103
42
If, for some reason, the default transaction completion detection algorithm provided by **sdk-js** does not satisfy your requirements, you may want to use a different strategy for transaction awaiting, such as:
If, for some reason (e.g. a bug), the default `ResultsParser` provided by **sdk-js** does not satisfy your requirements, you may want to extend it and override the method `createBundleWithCustomHeuristics()`:
115
-
116
-
```
117
-
export class MyTailoredResultsParser extends ResultsParser {
let returnMessage: string = "<< extract the message from the input transaction object >>";
120
-
let values: Buffer[] = [
121
-
Buffer.from("<< extract 1st result from the input transaction object >>"),
122
-
Buffer.from("<< extract 2nd result from the input transaction object >>"),
123
-
Buffer.from("<< extract 3rd result from the input transaction object >>"),
124
-
// ...
125
-
]
126
-
127
-
return {
128
-
returnCode: ReturnCode.Ok,
129
-
returnMessage: returnMessage,
130
-
values: values
131
-
};
132
-
}
133
-
}
134
-
```
135
-
136
-
:::important
137
-
When the default `ResultsParser` misbehaves, please open an issue [on GitHub](https://github.com/multiversx/mx-sdk-js-core/issues), and also provide as much details as possible about the unparsable results (e.g. provide a dump of the transaction object if possible - make sure to remove any sensitive information).
Copy file name to clipboardExpand all lines: docs/sdk-and-tools/sdk-py/configuring-mxpy.md
+2-4Lines changed: 2 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -19,8 +19,6 @@ In order to view the current configuration, one can issue the command `mxpy conf
19
19
20
20
```
21
21
{
22
-
"dependencies.llvm.tag": "v...",
23
-
"dependencies.vmtools.tag": "v...",
24
22
"dependencies.rust.tag": ""
25
23
}
26
24
```
@@ -31,6 +29,6 @@ In order to view the current configuration, one can issue the command `mxpy conf
31
29
32
30
One can alter the current configuration using the command `mxpy config set`. For example, in order to set the **_rust version_** to be used, one would do the following:
33
31
34
-
```
35
-
$ mxpy config set dependencies.rust.tag nightly-2023-12-11
Copy file name to clipboardExpand all lines: docs/sdk-and-tools/sdk-py/installing-mxpy.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -78,7 +78,7 @@ pipx upgrade multiversx-sdk-cli
78
78
79
79
Installing **mxpy** using **mxpy-up** is not recommended anymore. We recommend using **pipx** instead.
80
80
81
-
If you've previously installed **mxpy** using **mxpy-up** and you'd like to switch to **pipx**, make sure to remove the old `mxpy` shortcut and virtual Python environment beforehand:
81
+
If you've previously installed **mxpy** using the legacy **mxpy-up**, you should switch to the **pipx** approach. Make sure to remove the old `mxpy` shortcut and virtual Python environment beforehand:
0 commit comments