PeerAssets: DEX manual
Make sure you have updated pypeerassets to the last update of the locktime branch (before updating, type in git checkout locktime) and pacli to the last update of the dex branch (type git checkout dex).
-
Get an exchange partner.
-
You need two things from them:
- An UTXO or unspent output. You need the TXID and the output number containing the coins (or more) you want for the tokens. The best way for them to send the UTXO to you is in the format separated by a colon TXID:OUTPUTNUMBER, for example: ca75d9deb71f4d7ec8f5791a33fdcc87f14fcf8a061947a634efb092696cabc3:3 because this is the format it will be taken by pacli.
- The address the exchange partner wants you to send the tokens.
- Negotiate the token amount ($TOKEN_AMOUNT below) you'll sell, the coin amount ($COIN_AMOUNT) you'll buy in exchange, and the locktime you want to use. The locktime is a block height until which the coins will be locked. For small amounts, 10-20 blocks from the current block are enough, for big amounts about 100 from the current block will get you almost 100% safety.
Note to step 1: The current version only accepts p2pkh outputs, which is the standard type for transactions, but not for mining (coinbase) transactions. You can see them in the transaction JSON (i.e. when you use getrawtransaction with the "1" at the end) having type "pubkeyhash".
pacli address set_main $TOKENSELLER_ADDRESS_LABEL
pacli dex create_offer $DECKID $TOKEN_AMOUNT $LOCKTIME $TOKENBUYER_ADDRESS --sign --send
This will create a special PeerAssets transaction locking the tokens. Wait for the transaction to confirm.
INPUT has to be in the format TXID:OUTPUTNUMBER.
pacli dex new_exchange $DECKID $TOKENBUYER_ADDRESS $INPUT $TOKEN_AMOUNT $COIN_AMOUNT --sign
This will output a long hexadecimal number we will call TXHEX.
Note: --send is not needed in this step.
Your exchange partner will now need the TXHEX. Copy it and send it via the communication channel you used to negotiate the terms of the exchange.
Take into account that if you take too long for this step and wait until the locktime ends, your counterparty will probably abandon the exchange because if it's confirmed at or after the locktime you could double spend their funds. If the token buyer abandons, neither the coins nor the tokens will be sent.
Now your counterparty has to sign their outputs and send the transaction. They have an incentive to do this as fast as possible due to the double spending problem mentioned above.
You now should look if the transaction took place with Slimcoin or pacli tools. You'll see it directly as an incoming transaction if you use the Slimcoin-QT app, or you can use command line tools, for example with:
pacli address balance
or
slimcoind getbalance
and to see the new token balances:
pacli card balances $DECKID
(the pacli commands will show the balance only after being confirmed, while slimcoind may show you unconfirmed balances).
Once it confirms - congratulations, the exchange was successful.
You need first to select an UTXO or unspent output containing the coins (or more) you pay for the tokens. You need the TXID and the output number.
The select_coins command in Pacli helps you with that task.
pacli dex select_coins $AMOUNT
$AMOUNT is the amount you want to use to buy the tokens. The command will list all unspent outputs (UTXOs) attached to your current Pacli address which cointain that amount or more. If you want to check other addresses in your wallet without changing to them with the set_main command, you can add --address=$ADDRESS.
You now need to communicate with your exchange partner and send them the following items:
- The unspent output you selected in step 1 (in the format $TXID:$OUTPUTNUMBER, for example: ca75d9deb71f4d7ec8f5791a33fdcc87f14fcf8a061947a634efb092696cabc3:3)
- The address you want the exchange partner to send the tokens.
- Negotiate the token amount ($TOKEN_AMOUNT below) you'll buy, the coin amount ($COIN_AMOUNT) you'll sell in exchange, and the locktime you want to use. The locktime is a block height until which the coins will be locked. For small amounts, 10-20 blocks from the current block are enough, for big amounts about 100 from the current block will get you almost 100% safety.
The token seller will now have to create a CardLock transaction to confirm the offer. This transaction ensures the token seller can't double spend funds, so make sure it was confirmed correctly.
You can see the valid locks and locktimes with the following command:
pacli dex show_locks $DECKID
If everything is correct, then you should see an entry with the token seller's address, followed by the locktime (block height) you negotiated and your address.
The token seller should in short send you now the TXHEX, a hexadecimal version of the raw transaction they signed with their keys. It has now to be signed by you.
Important: If the token seller waits sending the TXHEX until close to the locktime, then it's possible they want to trick you into creating the transaction after the locktime, when they can simply double-spend funds. So if you think your transaction won't get included in the blocks before the locktime ends, don't proceed!
With the following command you finalize the exchange transaction, the TXHEX being the data you got from the seller:
pacli address set_main $TOKENBUYER_LABEL
pacli dex finalize_exchange $TXHEX --send
It is advisable to first do a dry run without --send to see everything works fine.
Once the transaction has confirmed the exchange has taken place and the token should be in your possession.
Check the balance of your token account with:
pacli card balances $DECKID
If you want to sell tokens to yourself to test the DEX feature, here a short cheat sheet (as preparation, define an address for the TOKENSELLER_LABEL and the TOKENBUYER_LABEL)
First we do the steps of the token seller:
pacli address set_main $TOKENSELLER_LABEL
pacli dex create_offer $DECKID $TOKEN_AMOUNT $LOCKTIME $TOKENBUYER_ADDRESS --sign --send
Wait for confirmation before the next step.
pacli dex new_exchange $DECKID $TOKENBUYER_ADDRESS $INPUT $TOKEN_AMOUNT $COIN_AMOUNT --sign
INPUT has to be in the format TXID:OUTPUT_NUMBER, you can get them with slimcoind listunspent; remember you have to use an input going to the address of the token buyer.
Now we change to the steps of the token buyer / coin seller:
pacli address set_main $TOKENBUYER_LABEL
pacli dex finalize_exchange $TXHEX --send
Wait again for a confirmation, then check if everything's ok:
pacli card balances $DECKID
pacli address balance
pacli address set_main $TOKENSELLER_LABEL
pacli address balance