Dapp

Build, test, deploy and transact with Ethereum contracts from the comfort of the command-line.

The dapp command is the basic user-facing tool in our development toolkit.

It is opinionated and designed to support a simple and robust workflow while being fast, predictable, and a good citizen of the Unix command line.

You can get started with dapp development very easily:

$ mkdir example
$ cd example
$ dapp init
$ vi src/example.sol
$ dapp test
$ dapp debug

Here is a little teaser movie:

The DappHub Collective

We build infrastructure for the next generation of the internet

DappHub is a self-organizing network of logicians, researchers, designers and developers spread out across the globe.

Our network is always growing. If you want to join, just come to our chat room and introduce yourself.

Join the DappHub chat

Reference

$ dapp init                    bootstrap a new dapp

$ dapp build                   compile the source code
$ dapp test <options>          run the test suite

$ dapp install <component>     install a dappsys component
$ dapp update <options>        update component(s)
$ dapp upgrade <options>       upgrade component(s)
$ dapp uninstall <component>   uninstall a component

$ dapp create <args>           deploy a contract

dapp init

The init command bootstraps a new project with some of our conventions—it will

  1. initialize a Git repository with a .gitignore;
  2. create a simple Makefile;
  3. install ds-test as a submodule in the lib directory;
  4. create sample files in the src directory;
  5. run dapp test as a sanity check;
  6. and finally make an initial Git commit.
$ mkdir my-dapp
$ cd my-dapp
$ dapp init
[output omitted]

2 tests passed, 0 failed
Took 0.131s

Compiled contracts are stored in the out directory, which is ignored by Git.

dapp build

The build command invokes solc to compile all code in src and lib to out.

$ dapp build

running build ....................

$ ls -l out

MyDapp.abi
MyDapp.bin
MyDapp.bin-runtime
MyDapp.sol.json

MyDappTest.abi
MyDappTest.bin
MyDappTest.bin-runtime
MyDapp.t.sol.json

DSTest.abi
DSTest.bin
DSTest.bin-runtime

The build command outputs .abi files - the JSON representation of a contract's Application Binary Interface as well as bytecode representations .bin and .bin-runtime. The *.bin-runtime is the return value of the contstructor function and represents the bytecode that would end up being stored on the blockchain whilst *.bin files also include constructor calldata.

dapp test

The test command uses ethrun and ds-test to compile the source and run any accompanying unit tests defined in src. The ds-test library makes it easy to write native unit tests in Solidity. See the ds-test docs for a detailed guide.

$ dapp test
+ dapp clean
+ rm -rf out
Running 2 tests for src/MyDapp.t.sol:MyDappTest
..
+ solc --link --libraries '' out/DSTest.bin out/MyDapp.bin out/MyDappTest.bin
+ dapp quicktest out
Trying MyDappTest...
..

2 tests passed, 0 failed
Took 0.083s

dapp install

Dapp provides for the publishing and re-use of smart contract components like those provided by the dappsys library. In the near future we expect to see the development of more sophisticated package managers for Ethereum but for the time being dapp simply faciliates the submoduling of components published to github.

When a github user is not specified, dapp will assume that the component is from the dappsys library.

$ dapp install ds-auth

Providing a github username allows components to be installed from any shared github repo:

$ dapp install apmilen/my-cool-component

Components are submoduled to the lib directory and can be imported into a project using the submodule name.

pragma solidity ^0.4.0;

import "ds-auth/auth.sol";

contract TestContract is DSAuth {}

dapp update

Will run against all installed components in the lib directory when run without any arguments, or target a specific component when a name is specified:

Recursively fetch all upstream changes without commiting.

$ dapp update ds-auth

dapp upgrade

Will run against all installed components in the lib directory when run without any arguments, or target a specific component when a name is specified:

Recursively pull all upstream changes and save to the project repo via git commit.

$ dapp upgrade ds-auth

dapp uninstall

Remove an installed component:

$ dapp uninstall ds-auth

dapp create

The create command takes the name of the contract, and any constructor parameters as arguments and deploys the contract. Dapp will read the correct bytecode file from the out directory, bundle it up into a transaction with encoded constructor parameters, and broadcast it to the network.

Lets assume that MyDapp is a trivial token contract that takes an inital supply and a name as constructor parameters:

pragma solidity ^0.4.0;

contract MyDapp {

  mapping( address => uint ) _balances;
  string public name;

  function MyDapp(uint initial_balance, string name_) {
    _balances[msg.sender] = initial_balance;
    _supply = initial_balance;

    name = name_;
  }
}

Ensure that an Ethereum client is running and invoke create with the contract name and constructor parameters

$ dapp create MyDapp 10000 "MyCoolToken"
+ seth send --create out/MyDapp.bin 'MyDapp(uint256,string)' 10000 MyCoolToken
seth-send: Published transaction with 1688 bytes of calldata.
seth-send: 0x4df5fdad614a88702439b10dd3002adb7869b339413011ba8ac69b4f07d9f10d
seth-send: Waiting for transaction receipt...
seth-send: Transaction included in block .

See the dapp developer docs for a more detailed guide.

Installation

We recommend using the Nix package manager. It works on Linux and OS X and is self-contained and unobtrusive.

$ curl https://nixos.org/nix/install | sh
$ nix-channel --add https://nix.dapphub.com/pkgs/dapphub
$ nix-channel --update
$ nix-env -iA dapphub.{dapp,seth,hevm,evmdis}

Contributing

Tools for dapps

We believe that the free software movement is the most important cultural predecessor to the modern-day renaissance in decentralized technologies.

To catalyze the growth of this ecosystem, and to empower hackers to participate, we’re building a comprehensive suite of blockchain-oriented developer tools in the spirit of the Unix philosophy.

Dapp is all you need to start developing for Ethereum. It creates new dapps, runs Solidity unit tests, debugs, deploys, launches testnets, and more.

Seth is a handy tool for slicing and dicing transactions, querying the blockchain, converting between data formats, performing remote calls, and other everyday tasks.

Hevm is our own EVM implementation with a nimble terminal-based Solidity debugger. It’s used for dapp test and dapp debug.

Evmdis is an EVM disassembler written and maintained by Nick Johnson. It’s useful to make sense of EVM bytecode, especially when developing contracts at the assembly or raw bytecode level.

Dappsys - smart contract building blocks

We also maintain Dappsys, an audited collection of smart contract building blocks designed to complement each other. They include;

Using these proven parts lets us focus on the novel features of the systems we develop. We share Dappsys to benefit the smart contract ecosystem.