If you would like to understand how the system components relate to each other, please check out the ink! Verifier Explainer.
Table of Contents
You will need the following software installed in your machine:
- Docker >= 20.10.21
- Docker Compose >= 1.29.2
- Node.js >= 16.5.1
The user namespace remapping is only required in non-rootless Linux hosts. If you are running docker in rootless mode or using macOS it does not apply.
In order to run the source code verification workloads you will need to set up a user namespace remapping configuration for your docker daemon to match the host user that runs the ink verifier server.
Get the uid of the user that will run the ink verifier server process, example for the current user:
❯ id -u
1000
and the name:
❯ id -un
marc
Edit /etc/docker/daemon.json, or create if it does not exist, to add the following content:
{
"userns-remap": "<USER_NAME>"
}Example:
{
"userns-remap": "marc"
}Now configure the remapping range in /etc/subuid, adding a line at the start of the file:
<USER_NAME>:<USER_ID>:1
Example:
marc:1000:1
marc:100000:65536
Restarting the docker daemon will kill your running containers. If you have already built the ink-verifier-image:develop locally, please rebuild it.
Restart the docker daemon:
❯ sudo service docker restart
Clone the epirus-substrate repository
git clone git@github.com:web3labs/epirus-substrate.gitChange directory to local-testnet
cd epirus-substrate/local-testnetℹ️ You can run all the following processes at once by executing the
./run-all.shscript.
Run your substrate test network
docker-compose -f docker-compose.testnet.yml up -dRun a local Squid archive
docker-compose -f docker-compose.squid-archive.yml up -dRun a squid-ink processor
docker-compose -f docker-compose.squid-ink.yml up -dSquid-ink processor connects to http://host.docker.internal:3001/ where expects the local verifier server listening to retrieve metadata
Run the explorer user interface
docker-compose -f docker-compose.explorer-ui.yml up -dClone the ink! Verifier Server repository
git clone git@github.com:web3labs/ink-verifier-server.gitEnter the project directory and install the server dependiencies.
cd ink-verifier-server && npm installRun the server listening in all the network interfaces.
SERVER_HOST=0.0.0.0 npm startThe server is accessed from a container using
host.docker.internal.
In this scenario we will generate a verifiable package, upload the contract to local chain and verify it using the explorer UI.
You can skip directly to the next section Uploading to the Network if you use verifiable packages already generated in this repo directory. Note that in this case you will need to use Polkadot.js UI or Contracts UI for uploading.
Clone the ink-verifier-image repository
git clone git@github.com:web3labs/ink-verifier-image.gitChange the working directory
cd ink-verifier-imageBuild the docker image
docker build . -t ink-verifier:developChange to the command line tool directory
cd cli/Install the command line tool
You will need cargo installed, if it is not the case check rustup
cargo install --path .Check that the tool is installed correctly
❯ build-verifiable-ink -h
A command line interface to generate verifiable source code packages.
Usage: build-verifiable-ink [OPTIONS] <SOURCE>
Arguments:
<SOURCE> Source directory, can be relative; e.g. '.'
Options:
-i, --image <IMAGE> ink! verifier image name [default: ink-verifier]
-t, --tag <TAG> ink! verifier image tag [default: latest]
--engine <ENGINE> Container engine [default: docker]
--env-file <ENV_FILE> Environment file
-h, --help Print help information
-V, --version Print version information
🌟 Now it is time to test out some smart contracts
In another directory, clone the example contracts repository
git clone git@github.com:web3labs/dev-contracts-substrate.gitChange the working directory to the flipper contract source
cd example-contracts/flipper/Generate the verifiable source code package
build-verifiable-ink -t develop .At the end of the build you should see the following output
The contract was built in RELEASE mode.
Your contract artifacts are ready. You can find them in:
/build/package/src/target/ink
- flipper.contract (code + metadata)
- flipper.wasm (the contract's code)
- metadata.json (the contract's metadata)
adding: src/ (stored 0%)
adding: src/lib.rs (deflated 67%)
adding: src/Cargo.toml (deflated 48%)
adding: src/Cargo.lock (deflated 77%)
adding: flipper.contract (deflated 61%)
Verification package in /build/target/ink/package.zip
Archive: /build/target/ink/package.zip
Length Date Time Name
--------- ---------- ----- ----
0 2022-12-01 11:44 src/
1315 2022-12-01 11:32 src/lib.rs
690 2022-12-01 11:32 src/Cargo.toml
17747 2022-12-01 11:43 src/Cargo.lock
4152 2022-12-01 11:44 flipper.contract
--------- -------
23904 5 files
Extract the <name>.contract file frome the package.zip if you plan to use Polkadot.js UI or Contracts UI to upload your contract. If you want to use cargo-contract tool, you will need to extract the metadata.json and flipper.wasm files.
❯ unzip -qq -p target/ink/package.zip "*.contract" > target/ink/flipper.contract
❯ unzip -qq -p target/ink/package.zip "*.contract" | jq "del(.source.wasm)" > target/ink/metadata.json
❯ unzip -qq -p target/ink/package.zip "*.contract" | jq -r ".source.wasm" | xxd -r -p > target/ink/flipper.wasmIf you're using cargo-contract
cargo contract instantiate \
--constructor new \
--args false \
--suri //Alice
Now you can use the explorer UI to find your contract code hash and verify the source code package.
Go to the explorer UI. It should be running on http://127.0.0.1:3000/ and you should see the homepage.
Navigate to the code hash page through the link on the homepage (indicated by yellow arrow in the above image). Alternatively, use the search box to find the code hash. Inside the code hash page, open the Source Code tab.
Upload the generated package.zip and click the Verify Source Code button.
You should see the process logs of the verification being streamed. The verification process will take a while; in the meantime, why not brew a fresh cup of ☕?
Verification success! 🎉 (hopefully)
Click on Browse Verified Files to see your verified source code.
To understand more about this feature and why we are supporting it, check out the veriifier server documentation
In this scenario we will upload only the contract metadata and sign it using the explorer UI.
Since this feature does not carry out verification, you can use any ink! contract built using cargo contract build. Upload your contract as you would normally do and have the metadata.json file ready. If you do not have any contracts already built, follow the steps in Generating the Verifiable Package and Uploading to the Network.
Note:
If you have already verified the source code following the steps in S1 - Verifiable Packages, you won't have the option to test out the metadata upload using the same contract. If you want to avoid compiling and uploading another contract, you can remove the published source code in the ink! Verifier Server publish directory: <root-path>/ink-verifier-server/.tmp/publish/<codehash>/
After your contract is already uploaded, open up the explorer UI and navigate to your contract code hash page. Click on "Signed Metadata" to display the metadata upload interface.
Drag and drop the metadata.json file into the upload box. You will notice that the "Current message to be signed by the owner account" field will be automatically generated. You will need to sign this message using the account that uploaded the contract. You can either use the subkey command suggested in the UI, or use the Sign and Verify tool of Polkadot.js. Paste your signature in the "Owner Signature" textbox and hit "Upload Metadata".
❗ You will need to sign the message using the same account that uploaded the contract code hash, otherwise the upload will fail.
You will now see your contract metadata in the source code tab.
We run a public instance of the Explorer UI that indexes Rococo Contracts and is integrated with our verifier server. You can access the public explorer at https://substrate.sirato.xyz/
If you wish to verify contracts or upload metadata in Rococo Contracts, simply follow the same steps as in S1 - Verifiable Packages and S2 - Owner-signed Metadata using the public Explorer instance. For source code verification, you will need to use the example contracts built with cargo-contract v2.0.0-beta. If you want to build your own contracts, follow these instructions on how to run the verifier image with a different cargo-contract version. The reason for the need to toggle versions is explained here.
At the time of writing, polkadot.js UI still does not support Weights V2 (see this issue). We suggest using either Contracts UI or cargo-contract for interacting with contracts in Rococo Contracts.
If you need some ROC to upload contracts, head to the Rococo Faucet Matrix chatroom #rococo-faucet:matrix.org and post
!drip YOUR_SS_58_ADDRESS:1002