Skip to content

Oasis Contract Kit

The Oasis Contract Kit can be used to build, test, and deploy smart contracts written in Solidity or Rust. The Contract Kit is a Docker image with a pre-configured set of tools meant to improve your productivity as a developer. We recommend using this development environment. While contract development remains a rapidly evolving ecosystem, there is a tough balance to maintain between taking advantage of the features provided by recent changes, and the instability and incompatibilities introduced by them. This Docker environment allows us to select recent and compatible versions of relevant tools.

To use the Contract Kit, you'll need Docker. If you don't already have Docker installed, you can find instructions for your preferred operating system here:

Getting Contract Kit

The latest version of the toolkit can be downloaded by running docker pull oasislabs/contract-kit

Starting Contract Kit

The development environment can be started by running the contract-kit Docker image and developing within the container. For many developers, you may not want to keep your development sources within a Docker environment, since it can add complexity to version control and working with a local editor. For these reasons, we recommend using a volume mount to expose a local directory with your source code into the container.

To launch Contract Kit, run

docker run -ti --rm -v "$PWD":/project oasislabs/contract-kit bash

This runs a Docker container using the specified contract-kit image and opens a bash shell within the running container. It mounts the current directory at /project in the container.

It is often useful to forward ports, for example, if you want to run a web server for your DApp from within docker. To do so, simply add the following arguments to the above command

-p HOST_PORT:CONTAINER_PORT

For example, -p 3000:3000 would ensure all requests to localhost:3000 are forwarded to the docker image's own port 3000.

It's also useful to have multiple shells open for development. To find the name and identifier of the running container, run

docker ps

Using either the container name or container identifier, you can launch additional shells by running

docker exec -ti <container-name or container-id> bash

Note

Exiting the initial Docker shell will terminate the container instance, and close subsequently opened shells.

Launching a Local Blockchain

The Docker image contains a version of Parity that provides useful debugging information such as gas profiling and log messages. You can use this tool to test your smart contracts locally before deploying them to Oasis Devnet.

Note

The local blockchain currently does not have support for Oasis-specific features, such as Web3c, confidential smart contracts, Rust bulk storage (owasm_ethereum::get_bytes and owasm_ethereum::set_bytes), or contract storage expiry. Please use the Devnet when testing smart contracts using these features as in the secret ballot tutorial.

To launch the local chain from within the Docker container:

parity --chain oasis

While this command is running, you can issue web3 calls to http://127.0.0.1:8545 within the Docker container.

Accounts on Local Blockchain

When launched, Parity prints a list of 10 accounts available for testing on the local blockchain, each with 100 DEV initial balance.

Address
0xb8b3666d8fea887d97ab54f571b8e5020c5c8b58
0xff8c7955506c8f6ae9df7efbc3a26cc9105e1797
0x0056b9346d9a64dcdd9d7be4ee3f5cf65940167d
...

The accounts are derived from the following mnemonic:

range drive remove bleak mule satisfy mandate east lion minimum unfold ready

If you are developing with Truffle, follow these instructions to ensure Truffle uses these accounts when deploying to the local blockchain with command truffle migrate --network development.

Available tools

As part of the Contract Kit, we have assembled the following tools:

  • truffle - development and testing framework
  • parity - for running a local testing chain via parity --chain oasis
  • rustc/cargo - to compile Rust contracts to a WASM target
  • git
  • vim

For more details, refer to the page on Docker Hub or the Dockerfile

Video tutorial

Check out our video tutorial for step-by-step instructions on how to set up and use Contract Kit.

Next steps

  • The Rust contract tutorial is a great resource for learning how to write smart contracts in Rust.
  • The Using Truffle guide shows how to use Truffle to develop Rust and Solidity contracts, and deploy confidential smart contracts, using the Contract Kit.