zbxcat/README.md

# ZBXCAT

**NOTE: Experimental software, use at your own risk, PR's welcome :)**

A work-in-progress for Zcash Bitcoin Cross-Chain Atomic Transactions

Bitcoin scripts use python-bitcoinlib, and Zcash scripts use python-zcashlib (a Zcash fork of python-bitcoinlib).

Currently defaults to using testnet.

## Setup

To successfully run this code, you'll need python3, the dependencies installed, and a bitcoin and zcash daemon synced on whichever chain you want to trade on.

It's recommended that you install python3 in a virtualenv. Run this command from the top level of the directory:
```
virtualenv -p python3 venv
source venv/bin/activate
```

To install this code, clone the repo and install as a python package.
```
git clone https://github.com/zcash/zbxcat.git
pip install zbxcat
```

Install the dependencies. Note that this package depends on the experimental [python-zcashlib package](https://github.com/arcalinea/python-zcashlib).
```
pip install -r requirements.txt
```


Run Zcash and Bitcoin daemons locally, on whichever network you want to trade on (recommended: testnet, regtest).

Make sure the rpcuser and rpcpassword values are set in your zcash.conf or bitcoin.conf files.

Example `~/.zcash/zcash.conf` file:
```
rpcuser=user
rpcpassword=password
```

## Example trade

You can try this on regtest on one computer, or on testnet across two computers.

Since this is still under active development, we recommend that you do not trade more than you can afford to lose on mainnet.

We use the term "seller" for whoever initiates the trade, and "buyer" for whoever fulfills the other end.

### Seller Setup:

To start a trade using default addresses, edit the buyer and seller addresses for the chosen network in `xcatconf.py`. You will initiate the trade using these default addresses by passing in the variable through a `-conf` flag.

### Seller:

To initiate a new trade, the seller enters all the necessary trade data and saves it under a tradeid. We will use the tradeid "testtrade" for this example. The amounts being traded will have to be agreed upon in advance, and the seller will need the buyer's destination addresses on both chains. The `-c` field will pass in the name of the network addresses set in `xcatconf.py`. (If addresses are not set, initiator addresses are generated on your computer, and you can enter the buyer's addresses on the command line.)

`xcat -c=regtest newtrade testtrade`

After creating, the seller exports the trade data encoded as a hex string to transfer the terms of the trade to the buyer. They can send this hex string to the buyer through email or any other channel.

A standard export. Returns a long hex string which the seller sends to the buyer.

`xcat exporttrade testtrade`

There is also built-in support to transfer the data directly between two computers through [magic-wormhole](https://github.com/warner/magic-wormhole), which you will have to have installed locally on your computer. Available for download through pip or the apt repository.

An export using magic-wormhole, which uses a short passphrase the seller must communicate to the buyer.

`xcat -w exporttrade testtrade`

### Buyer:

To examine trade, buyer imports it. A standard import requires the full hex string.

`xcat importttrade testtrade <hexstring>`

An import using magic-wormhole, which prompts the user for the short passphrase generated by the seller.

`xcat -w importtrade`

If it looks ok, inform seller to proceed.

### Seller:

Funds sell p2sh. They can use the checktrade command to automatically take the next step in this trade.

`xcat checktrade testtrade`

### Buyer:

Funds buy p2sh, also by using checktrade command to automatically proceed.

`xcat checktrade testtrade`

### Seller:

Redeems buyer p2sh.

`xcat checktrade testtrade`

### Buyer:

Redeems seller p2sh. The secret they need to redeem will be automatically parsed from the seller's redeemtx on the blockchain.

`xcat checktrade testtrade`

Trade is done! Buyer or seller can check the status again, but it will indicate that it is complete.


# Testing and Development

You can install modules locally in editable mode through pip, so that you can make changes to the code and they will be applied immediately.

To use pip to install a package in editable mode, use the `-e` flag to pass in the path on your local filesystem:

`pip install -e <path-to-package-repo>`

To install our code as a python package in editable mode, passing in the directory containing `setup.py` should work.

`pip install -e <directory that setup.py for xcat is in>`