Server for ink! source code verification.
Features:
- Reproducible builds for ink! source code verification
- Uploading of verifiable source code packages
- Tracking the status of the verification build process
- Metadata is generated by the build
- Signed upload of contract metadata
- Access to the verified artifacts
For a high-level explanation of the ink! Verifier Server and how it integrates with the Explorer UI and ink! Verifier Image, please check out the ink! Verifier Explainer
For instructions on how to generate a verifiable source code package, please check out the ink! Verifier Image documentation.
For instructions on how to carry out a full end-to-end test, please check out our tutorial.
Table of Contents
- Configuration
- Running Locally
- Testing
- Linting
- Running in Production
- Reproducible Builds Verification
- Unverified Metadata Upload
- Web API
- Technical Notes
- Additional Developer Tools
The configuration uses the environment variables described in the table below.
| Name | Description | Defaults |
|---|---|---|
| SERVER_HOST | The server host address. e.g. 0.0.0.0 | 127.0.0.1 |
| SERVER_PORT | The server port to listen to | 3001 |
| OAS_URL | The external URL of the server for the Opean Api docs | http://${SERVER_HOST}:${SERVER_PORT} |
| BASE_DIR | Base directory for verification pipeline stages | :project_root_dir/.tmp |
| CACHES_DIR | The base directory for caches | :project_root_dir/.tmp/caches |
| PUBLISH_DIR | Base directory for long-term access to successfully verified artefacts | :project_root_dir/.tmp/publish |
| MAX_CONTAINERS | Maximum number of running containers | 5 |
| VERIFIER_IMAGE | The ink-verifier container image to be used for verification | ink-verifier:develop |
| CONTAINER_ENGINE | The container engine executable | docker |
| CONTAINER_RUN_PARAMS | Additional parameters for the conainter engine | n/a |
The server has support for .env files.
After installing the project dependencies, only for the first time, using
npm iyou can start a development server
npm run start:devTo run the unit tests, use the command
npm testTo generate a test coverage report, execute
npm run test:coverageTo apply the code linter and automatically fix issues
npm run lintThe ink! Verification Server is meant to be run as a standalone OS process since it spawns container processes for the reproducible builds and we want to avoid the nuances of Docker in Docker or similar solutions.
We recommend the usage of PM2 process manager, an ecosystem.config.js is provided for this purpose.
Example:
pm2 start ecosystem.config.js --env productionSee PM2 documentation.
This section describes the source code verification process based on ink! reproducible builds.
- Requestor: The user uploading the source code for verification
- Server: The verification server implemented in this repository
- Verifier Image: The container image with the verification logic for ink! source codes
- Staging:
$BASE_DIR/staging/:network/:code-hash - Processing:
$BASE_DIR/processing/:network/:code-hash - Errors:
$BASE_DIR/errors/:network/:code-hash - Publish:
$PUBLISH_DIR/:code-hash
- A requestor uploads the source packge archive for a network and code hash
- The server checks that:
- The source code for the network and code hash is not already verified or being verified
- There is enough host resources to start a new verification
Staging steps below happen in the staging directory
- The server downloads the pristine WASM byte code correspondening to the provided network and code hash
- The server streams the archive if is a compressed archive
Processing in the processing directory
- The server moves the staging files to the processing directory
- The server runs a container process for the verifier image to verify the package in processing. See source code verification workflow for details
- On the event of container exit the server moves the verified artificats to the publish directory if the verification was successful, otherwise keeps a log in the errors directory
For verified source code and metadata use the Reproducible Builds Verification mechanism.
The service supports uploading signed contract metadata as an additional alternative to reproducible builds generated metadata. Please note that the signed metadata is not verified and the owner of the code hash is trusted.
This feature responds to (1) the support for build_info data is only available from cargo-contract 2.0.0-alpha.4,
(2) there is no official image or procedure regarding reproducible builds yet, (3) we want to expand the service utility in the meantime.
Although it is a far from ideal way to bind the metadata to a given code hash it prevents trivial exploitation by:
- Verifying that the signature is from the owner account of the code hash.
- Verifying that the signed message matches the sha256 of the uploaded
metadata.json+ thecode hashof the uploaded contract bytecode.
For instructions on how to upload and sign metadata from the Explorer UI, please check out our tutorial
OpenAPI schemas are automatically generated from the server route schemas. If you are running the server locally, you can find the schema at http://127.0.0.1:3001/oas.json.
For the public instance that we are running, the OpenAPI schema can be found at https://ink-verifier.sirato.xyz/api/oas.json.
We also serve a Swagger interface at https://ink-verifier.sirato.xyz/api/api-docs/
You can import the API collection and environments found here into Postman for easy testing of the API.
The publish directory is not segmented by network name because the code hashes are content-addressable, i.e. the same for all networks. For source code verification the network name is required to download the uploaded pristine bytecode.
We are using @polkadot/apps-config to resolve the network endpoints by name. You can find the available endpoints in the endpoints directory.
To make the verification process easier for ink! smart contract developers, we provide a command line tool to help with building smart contracts with ink! Verifier Image so that the contract can later be verified. At the same time, the tool does the packaging and compression of the source code and resulting .contract file in the directory structure that ink! Verifier Image expects during verification.
The tool can be installed from the github repository
❯ cargo install --git https://github.com/web3labs/ink-verifier-image.git
or built from source
❯ git clone [email protected]:web3labs/ink-verifier-image.git
❯ cd cli/
❯ cargo install --path .
The CLI can then be used as follows
❯ cd </path/to/contract>
❯ build-verifiable-ink -t develop .
The source code for the tool can be found at https://github.com/web3labs/ink-verifier-image/tree/main/cli