Spec for new deploy API

# New Deployment API

This document provides a spec for the new deployment API. This document is
primarily targeted at the command line interface for deployment, but should be
1:1 mappable to all python deployment APIS.

## Deployment Basics

In order for populus to deploy a contract it needs the following information.

* `bytecode`
* Mapping of `placeholder => link_value`

Where:

* `bytecode` is the deployment bytecode for the contract.
* `placeholder` is an `offset` into the bytecode which defines a location that needs linking.
* `link_value` is the value to be used for linking.

In addition to this, we need a way to reference previous deployments in order to refer to previous deploy assets. To accomplish this, we'll package every deployment in an ERC190 package. To accomplish this we need a *name* for this package.

# Solution

We will lay out a solution that covers the following use cases.

* A contract defined in a source file within the project.
* A contract from a previous deployment which may no longer exist in the source files for the project.
* A contract from a source file from a project dependency.
* A contract from the compiled assets from a project dependency.

## Deployment Command

The deployment command will be as follows.

```
$ populus deploy --save --link :
```

Alternatively, if you wish to not record this deployment you can use `--no-save`, or if you wish to have populus auto-generate a package name for you you can use `--auto-save`.

> The `--link` portion of this command is optional and can be included multiple
times to specify multiple link values.

### Linking

To link, we need information about where the placeholders are in the source
code and what value should be linked into each placeholder.

All link resolved values for linking *must* be validated as:

* Referencing either existing locations or named placeholders in the list of available link references for the bytecode.
* The proper length for the placeholder.

## Definitions

### Contract Identifier

The `` is interpreted as follows.

#### Contract Name

```
$ populus deploy MyContract
```

If the value conforms to the ERC190 definition of a *Contract Name* populus will check for a contract from the project's local contracts which *exactly* matches the provided name.

* If a single match is found, populus will use that contract.
* If no matches or multiple matches are found populus will raise an exception.

#### Source Path & Contract Name

```
$ populus deploy contracts/MyContract.sol#MyContract
```

If the value conforms to the format `#` where `` is a source file local to the project which contains a contract which exactly matches `` which is an ERC190 *Contract Name*, populus will use that contract.

#### Source Path URI & Contract Name

```
$ populus deploy file:///contracts/MyContract.sol#MyContract
$ populus deploy file://project/contracts/MyContract.sol#MyContract
```

If the value is a valid URI perform the following validation.

* Check that the *scheme* is `file`
* Check that the *netloc* is either empty or `.`
* Check that the *path* is a source file which exists under the defined source file locations for the project.
* Check that the *fragment* is an ERC190 *Contract Name*

Once these checks have passed, populus will use the defined contract from the
compiled source file, or raise an exception if no contract by that name is
produced from that source file during compilation.

#### Asset from a top level installed package

```
$ populus deploy crowdsale-v1:MyCrowdsale
```

> It should be noted that this is simply a special case of the generic form for
> referencing assets from installed dependencies.

If the value conforms to the format `:` where
`` is a valid ERC190 package name and `` is a
valid ERC190 contract name then populus will use the precompiled assets for the
specified contract from the specified contract. If no package by the given
name is found or no contract by the given name is found within the package,
populus will raise an exception.

#### Asset from an installed package

```
$ populus deploy crowdsale-v1.zeppelin-crowdsale:Crowdsale
```

IF the value conforms to the format `(.)+:` where
the `` portion can be repeated many time populus will perform the
following validation which is loosely equivalent to how link references are
specified in ERC190.

Let `p_1, p_2, ..., p_n` be the sequence of package names extracted from `p_1.p_2.p_n`

* All package names must be valide ERC190 package names.
* For each `p_n`, `p_n` must be present in the `build_dependencies` for `p_n-1`.

Populus will validate that `` is a valid ERC190 contract name
and that it is present in the contract types of `p_n` and that it contains a
`bytecode` entry. If all of the validation steps pass, populus will use this
contract. Otherwise it will raise an exception.

#### URI for installed package asset.

```
$ populus deploy package://crowdsale-v1.zeppelin-crowdsale#Crowdsale
```

If the value is a URI populus will check the following.

* The *scheme* is `package`
* The *netloc* is non-empty and when split on `.`, all values are valid ERC190 package names.
* The *fragment* is a valid ERC190 contract name.

The package names extracted from the *netloc* should be validated in the same
manner as the previous case.

Populus will use the precompiled asset for the specified contract from the
package in the dependency tree or raise an exception if it is not present or
any other validation failes.

#### Asset from an installed package source file

```
$ populus deploy crowdsale-v1.zeppelin-crowdsale:contracts/Crowdsale.sol#Crowdsale
```

If the value is in the format
`:#` where
`` is a dot separated list of valid ERC190 package
names and `` exists as a source file in the specified package
and `` is a valid ERC190 contract name, populus will recompile
this source file using the local compilation settings for the project and use
the resulting compiled asset from the specified ``. If no such
compiled asset is produced, populus will throw an error.

### URI for installed package source file

```
populus deploy file://crowdsale-v1.zeppelin-crowdsale/contracts/Crowdsale.sol#Crowdsale
```

> Note this is merely a long form URI version of the previous case.

When the value is a URI the following validation will checked.

* The *scheme* is `file`
* The *netloc* is a dot separated list of valid ERC190 package names.
* The *path* is a valid source file path from the specified package.
* The *fragment* is a valid ERC190 contract name.

Populus will then compile the specified source file using the local compiler
settings and use the specifed contract name as extracted from the URL fragment.
If no contract by that name is produced during compilation and exception will
be raised.

### Placeholder Identifiers

The `` can take one of two forms.

* Exact bytecode location.
* Placeholder name

#### Exact placeholder location

```
$ populus deploy MyContract --link 120:
```

An exact placeholder location can be specified using the numeric index into the
bytes representation of the bytecode.

#### Named placeholders

```
$ populus deploy MyContract --link MyLibrary:
```

The name may be used to link all placeholders of a given name with the provided value.

### Link Value Identifiers

The `` can take one of the following forms.

* Literal value
* Reference to a deployed instance address from one of the installed packages.

#### Link value literals

```
$ populus deploy MyContract --link MyLibrary:0xdf6c53df56f3992fc44195518a2d8b16306af9ff
```

Use of a link value literal is done by providing the hex encoded value (optionally 0x prefixed)

#### Reference to deployed instance

```
$ populus deploy MyContract --link MyLibrary:crowdsale-v1.multisig-v1#MyMultiSig
```

If the value is in the format
`#` then the
`` will be validated as a valid path to an
installed dependency. The available blockchain URIs in this package will then
be filtered down to the ones which validate against the current chain that
deployment is being executed on. If there are no matches or more than one
match, populus will raise an exception. If `` is found
in the deployments for the matching chain, the `address` from that instance
will be used.

#### URI Reference to deployed instance

```
$ populus deploy MyContract --link link://MyLibrary@crowdsale-v1.multisig-v1#MyMultiSig
```

> Note that this is simply an alternate format for the previous case.

When the value is a URI populus will perform the following validation.

* The *scheme* is `link`
* The *username* is a valid ERC190 contract name.
* The *netloc* is a valid dot-separated package path
* The *fragment* is a valid ERC190 contract name.

Populus will perform the same validation as the previous case and use the
resulting contract address if all validation passes.

The issue names the `populus deploy` command and its `--save`, `--no-save`, `--auto-save`, and `--link` forms, but no repository files or tests. Start by locating the deploy command entry point and map the contract, package, URI, placeholder, and link-value cases in the specification; done means the listed validation and resolution behavior is covered.

Written by the indexing model from the issue text.