pib

pib is a command-line utility for quickly configuring and deploying small Ethereum-style Proof of Authority blockchains using parity and docker.

Note: This project is experimental and subject to breaking changes. Feel free to get in touch with ideas for features or improvements that would make it more useful for you.

About

The name pib is a recursive acronym for "Pib Isn't Basil" (basil, not basil).

pib facilitates a fast design-build-test cycle for purpose-specific blockchain deployments by managing details such as account-generation, node configuration, and contract deployment.

Say, for example, that we have a contract named FriendsList which expects the constructor arguments (address owner, address[] friends). An example configuration might look like this:

[[contract]]
name = "FriendsList"
addr = "0x00000000000000000000000000000000000a11ce"
args = [
    "account-addr::alice",
    "match-addrs::alice-friend",
]

The above configuration tells pib to find and compile the contract named FriendsList, and to deploy it at the address 0x00000000000000000000000000000000000a11ce with the address of the account named alice as the first constructor argument, and an array of all addresses tagged with alice-friend as the second constructor argument.

Installation

To get the most out of pib, make sure you have recent versions of docker, docker-compose, and solc installed. Building pib will also require rustc and cargo (latest stable).

Once you've met the above requirements, run cargo install --path . from the repository root.

You can run pib --help to confirm that the install was successful and see a list of the available commands.

Usage

Run pib new <project-name> to initialize a new project directory with reasonable default options:

$ pib new my-project
$ cd my-project
$ tree
.
├── config
│   ├── contracts
│   │   └── EchoContract.sol
│   └── templates
│       ├── authority-config.toml
│       ├── chain.json
│       ├── Dockerfile
│       ├── init.sh
│       └── interface-config.toml
├── include
│   └── example
│       └── include.md
└── pib.toml

5 directories, 8 files

The only required file is the pib.toml which describes the core project configuration. By default, the new subcommand creates examples which demonstrate usage of basic features like contract deployment and file replication. This behavior can be disabled with the --no-examples flag.

The config/contracts directory contains contract source-code which is used to build contracts specified in the pib.toml. If no contracts are specified in pib.toml, then the config/contracts directory may be safely omitted. The above example includes one deployment of EchoContract, specified within the pib.toml like so:

[[contract]]
name = "EchoContract"
addr = "0x0000000000000000000000000000000000003c40"
args = []
tags = []

By default, pib will invoke solc to compile contracts. If you would prefer to use a pre-compiled contract, place the binary at config/contracts/<contract-name>.bin and use the --no-solc flag when building your project.

The default values of various files generated by pib may be overridden by changing the contents of config/templates. The chain.json file, for example, is used by pib as the basis for generating a chain specification. This file can be modified to supply custom values for more advanced configuration options such as the genesis gasLimit, or a custom networkID.

The include directory allows the user to replicate arbitrary files to one or more nodes. The include/example directory contains a single file, include.md, which can be replicated to one or more nodes via the include parameter. Ex:

# ...
include = ["example/:include-example/"]

Paths ending in / are treated as directories to be recursively copied, and paths not ending in / are treated as individual files. Arguments may be a single path with no : if the desired destination is the same as the source (e.g. foo/bar.txt:foo/bar.txt may simply be written as foo/bar.txt).

Projects may be built with the build subcommand, and launched with docker-compose:

$ pib build
...
$ cd output
$ sudo docker-compose up --build
... 

Development

Current iteration:

• Separate setup and build processes into context object and module trait
• Export cli option structs from main crate
• Finish implementing arbitrary (and recursive) include arguments
• Clarify ConfigModule's operational contract
  • Practical to require idempotence?
• Support "export" operations for internal entities
  • Should export include contracts/templates/etc?
• Add config module for network topology contract
• Add config module for parity Secret Store functionality
• Add dry-run cli option for builds
  • Mostly useful for ensuring that all ConfigModule ops succeed
• Raise error on duplicates for named entities (e.g. nodes)
• Raise error on duplicate file insertions
• Build/rebuild contracts by default (add cli option to override)
• Add cli option to export contract ABIs
• Allow toggling of active modules from command-line
• Use temfile::TempDir for contract compilation & tests
• Improve node IP address handling
  • Non-empty list instead of one-to-one?
  • One primary and zero or more alternate?