Crosschain Exchange Quick Start Guide
Introduction
CredaCash includes an integrated, peer-to-peer, crosschain exchange. This exchange allows users to trade CredaCash for bitcoin across blockchains, reducing barriers to entry and instantly providing liquidity to all users.
CredaCash’s integrated exchange is fully non-custodial. Years of experience have shown that funds placed in custodial exchanges are at risk, and some users have lost everything due to theft or mismanagement. More recently, funds placed in swap contracts and crosschain bridges have also been lost. For these reasons, CredaCash’s peer-to-peer exchange was designed to be completely non-custodial. At no time does anyone other than you have any ability to spend your funds.
To use the exchange, buyers and sellers send trade requests to the CredaCash blockchain. The seller’s trade request includes a conditional payment of CredaCash to the buyer. When two requests match, the buyer pays the seller in bitcoin on the bitcoin blockchain, and then claims the seller’s CredaCash payment on the CredaCash blockchain. If no match occurs, or if the buyer fails to make payment in bitcoin, then the seller’s conditional payment reverts to the seller.
CredaCash’s integrated crosschain exchange supports both Bitcoin (BTC) and Bitcoin Cash (BCH). Bitcoin Cash was selected because it has much lower transaction fees (less than USD $0.01), which will allow lower cost trading. Both Bitcoin and Bitcoin Cash are widely available and operate similarly. The minor differences are noted below.
Users are also be able to mine CredaCash based on their use of the exchange. This mining ensures CredaCash currency goes to users who support the project and help grow the community. More details are described in the document CredaCash Mining using the Crosschain Exchange.
This guide describes buying and selling testnet CredaCash in exchange for testnet Bitcoin (tBTC) or testnet Bitcoin Cash (tBCH). This allows you to experiment freely, since no real currency is involved. A companion document, the Crosschain Exchange Overview, provides an overview of the crosschain exchange design and operation.
Installation
Download the Windows executable files at https://CredaCash.com/software/, then extract the contents to any convenient directory.
Setting up a Testnet Bitcoin or Bitcoin Cash Wallet
This Guide uses the Electrum wallet for Bitcoin, or the similar Electron Cash wallet for Bitcoin Cash, which are both popular and relatively easy to use. To set up an Electrum or Electron Cash testnet wallet:
1. If necessary, download the Electrum wallet at https://download.electrum.org/4.1.5/electrum-4.1.5.exe, or the Electron Cash wallet at https://electroncash.org/
2. Right-click on the executable, select “Properties”, click “Unblock” then click “OK”.
3. Right-click on the executable and select “Create shortcut”.
4. Right-click on the shortcut and select “Properties”.
5. In the entry for “Target”, add a space after the end of the program name, then two minus signs, then for Electrum, add the word testnet, adn for Electron Cash, add the word “testnet4”. The Target entry should then look something like “C:\Users\Desktop\electrum-4.1.5.exe −−testnet” or “C:\Users\Desktop\Electron-Cash-4.3.1.exe −−testnet4”. Click OK.
6. You can rename the shortcut to “Electrum Testnet” or “Electron Cash Testnet4” if you like.
7. Double-click on the shortcut to start the wallet.
8. Click through the setup screens, using the default values for each screen. You can set a password for the wallet if you like, but it is not required.
9. When wallet setup is complete, the window title bar should include the word “Testnet”.
10. Click “Receive”. The Electron Cash wallet will immediately display a new unused address, while in the Electrum wallet, a new address will be displayed when “New Address” is clicked. For tBTC, the address value shown should start with the letters “tb”, and for tBCH, the address should start with “bchtest”. Highlight this address and copy it to the clipboard.
11. For Bitcoin, go to https://coinfaucet.eu/en/btc-testnet and request testnet BTC (tBTC) from the Bitcoin testnet3 faucet. For Bitcoin Cash, go to https://tbch.googol.cash/ and request testnet4 BCH (tBCH) from the Bitcoin Cash testnet4 faucet. Your wallet should receive the test currency within a few minutes.
Note: When you are done using the tBTC, please send it to tb1qg2zgkynt0tuyclyq6f6ydrlwm0uyj34n9chhcv where it will be used for further testing. Please send tBCH to bchtest:qp7h7m3uc9l4g24vu79afzulxppf2eclmsk9vfv7tn
Running the CredaCash Wallet
The CredaCash wallet can either connect to a local network node, or to a public network node. Connecting to a public node is faster because you don’t have to wait for the local node to synchronize with the blockchain.
To run the CredaCash wallet connected to a public node:
1. Double-click on either the file “__start_testnet_wallet_via_public_node.bat” or “__start_testnet_wallet_via_tor_and_public_node.bat”. This will open the CredaCash wallet in a new window.
2. In the CredaCash wallet, enter the command “ping”. If the wallet can connect to a node, it will report the ping time. The first ping could take 2 minutes or more if you connect via tor, but subsequent pings should take only a few seconds.
Alternately, to run the CredaCash wallet connected to a local node:
1. Double-click on the file “__start_testnet_local_node.bat”. This will start a local node. After a few minutes, the node should start to receive blocks, which will be logged to the local node window. Wait until the local node is fully synchronized with the blockchain. The local node is synchronized when the “age” values in the last column are less than 400, but if the clock on your local computer is off, the age values may be as large as 3900.
2. Double-click on the file “__start_testnet_wallet_via_local_node.bat”. This will open the CredaCash wallet, connected to the local node.
3. In the CredaCash wallet, enter the command “ping”. If the wallet can connect to the node, it will report the ping time.
4. Again in the wallet, enter the command “getinfo”. If the local node is synchronized to the blockchain, the getinfo command will report a “connections” value of 20.
Note: The scripts above will only run one instance of a wallet at a time. If a second instance is run before closing the first, the second instance will display an error message and terminate.
For more information on running the CredaCash wallet and node software, see the Quick Start Guide.
Running the Exchange Autopay Script
When using the exchange to acquire CredaCash, you must pay the seller in BTC on the Bitcoin blockchain, or in BCH on the Bitcoin Cash blockchain. This involves a number of steps, including monitoring for a match, determining the amount of BTC or BCH to pay, ensuring there is sufficient time for the BTC or BCH payment to be confirmed, then making payment, monitoring for the payment to be confirmed, and claiming the payment on the CredaCash blockchain.
A python script is provided to automate this process. Using this script is highly recommended for ease of use and to minimize the chance of error.
To use the autopay script:
1. The autopay script requires a 64 bit version (x86-64) of Python v2.x, which is available at https://www.python.org/downloads/release/python-2718/
2. Make sure your CredaCash wallet is running and connected to a network node, as described above.
3. For Bitcoin, edit the configuration file exchange-pay-testnet-bitcoin-electrum.conf to match the configuration of your CredaCash and Electrum wallets. The default values may work. For Bitcoin Cash, edit the configuration file exchange-pay-testnet-bitcoincash-electron.conf to match the configuration of your CredaCash and Electron Cash wallets.
4. For Bitcoin, double-click on the file “_start_exchange_autopay_bitcoin_electrum.bat”, and for Bitcoin Cash, “_start_exchange_autopay_bitcoincash_electron.bat”. If you would like to trade using both BTC and BCH at the same time, you must run both of these scripts.
These scripts by default will open the Electrum or Electron Cash wallet in GUI mode, if it is not already open. The output from the script will be shown in the command window. If you see error messages, you may need to edit the configuration file and restart the script. When opening the Electron Cash wallet in GUI mode, you will need to enter the wallet password in the GUI window.
Note that if you wish to buy CredaCash using both BTC and BCH, you must run both autopay scripts.
Using the Exchange to Buy Testnet CredaCash
The CredaCash exchange currently supports two types of buy requests: a naked buy request, and a simple buy request.
Naked buy requests are bare messages that do not include any cryptocurrency. Users who do not own any CredaCash can submit a naked buy request to obtain an initial holding. Naked buy requests are not binding however; the buyer can abandon a trade by simply declining to pay bitcoin to the matching seller.
Simple buy requests require a contingent payment of CredaCash as a pledge to settle any matches. If the buyer completes the trade (using the autopay script), then the pledge amount reverts to the buyer, but if there is a match and the buyer does not make and claim payment, the pledge amount transfers to the seller. This ensures more genuine trading and will therefore likely result a more favorable exchange rate. In order to submit a simple buy request, the user must already hold some amount of CredaCash, which may be acquired using a naked buy request.
To buy CredaCash using the exchange:
1. Make sure your CredaCash wallet is running and connected to a network node, as described above.
2. Make sure the autopay script is running, as decribed above. Note that if you wish to buy CredaCash using both BTC and BCH, you must make sure both autopay scripts are running.
3. To see if the exchange currently has any pending CredaCash sell requests, enter one or more of the following commands into the console of the CredaCash wallet:
cc.crosschain_query_requests nb 10 20 0 4e-5 btc 1
cc.crosschain_query_requests nb 10 20 0 4e-5 bch 1
cc.crosschain_query_requests sb 10 20 0 4e-5 btc 1
cc.crosschain_query_requests sb 10 20 0 4e-5 bch 1
In the above queries, the “10” and the “20” represent the minimum and maximum amounts of CredaCash you would like to buy, “0” represents the minimum rate, “4e-5” represents the estimated total costs in tBTC or tBCH of an exchange buy transaction, and “1” is the maximum number of match sell requests to return. The query results are sorted in order of the best “open-rate-required”, which is the exchange rate required to match the full open amount of the sell request. Returning one request will therefore return the matching sell request with the lowest “open-rate-required”.
In the query results, the “best-match-net-rate” value is the minimum net rate that would need to be offered to match the returned sell request. Even if that rate is offered however, if a competing buy request offers a higher net rate, then it will match first.
4. Submit a request to buy CredaCash. Any one of the following commands in the CredaCash wallet will submit a request to buy from 10 to 20 units of CredaCash, at a maximum net exchange rate of 0.00021 tBTC or tBCH per CredaCash, with estimated total costs of 4e-5 tBTC or tBCH:
cc.crosschain_request_create "" nb 10 20 0.00021 4e-5 btc
cc.crosschain_request_create "" nb 10 20 0.00021 4e-5 bch
cc.crosschain_request_create "" sb 10 20 0.00021 4e-5 btc
cc.crosschain_request_create "" sb 10 20 0.00021 4e-5 bch
Exchange requests on the CredaCash testnet have a “hold time” of 60 seconds, which means they will not match until at least 60 seconds after they are submitted. Approximately 2 to 4 minutes after one of the above buy requests is submitted, if the CredaCash wallet detects a match, and if there is sufficient balance in your Electrum wallet, the autopay script will pay approximately 0.0011 to 0.0022 tBTC or tBCH to the seller. This tBTC or tBCH payment will be logged to the console of the autopay script, and show up in your Electrum or Electron Cash wallet.
For exchange requests submitted to the CredaCash testnet, a default of 2 confirmations are required for tBTC and tBCH payments. After approximately 10 to 30 minutes, the bitcoin payment should obtain 2 confirmations, and then the autopay script will submit a message to the CredaCash blockchain claiming the payment. This claim will also be logged to the console of the autopay script, and shortly after the claim is submitted, the CredaCash bought through the exchange should show up in your CredaCash wallet when the commands “listtransactions” or “getbalance” are used.
If the autopay script reports “Password required”, then edit the autopay configuration file to add your Electrum wallet password, and then restart the autopay script.
A buy request that only matches part of the requested maximum amount remains open for additional matches until either the request expires or the maximum requested amount is reached. Therefore, the above requests can match more than once, in which the case the autopay script will make additional payments of tBTC or tBCH, and the corresponding amounts of CredaCash will show up in your CredaCash wallet.
Using the Exchange to Sell Testnet CredaCash
The CredaCash exchange also currently supports two types of sell requests: a naked sell request, and a simple sell request. For both requests, the CredaCash offered for sale must already be in the wallet, and it is placed into a contingent transaction that is claimed by the buyer when settling the match. A simple sell request will only match a simple buy request that includes a pledge, while a naked sell request can match both naked and simple buy requests, whichever offers a better net rate.
To sell CredaCash using the exchange:
1. Make sure your CredaCash wallet is running and connected to a network node, as described above.
2. The CredaCash you sell must be contained in your wallet. On the CredaCash testnet, you can freely obtain CredaCash using the command:
cc.mint
About 20 seconds after submitting a mint transaction, the command “getbalance” should report a balance of at least 1000.
3. To see if the exchange currently has any pending buy requests, enter one or more of the following commands into the console of the CredaCash wallet:
cc.crosschain_query_requests ns 10 20 0 2e-5 btc 1
cc.crosschain_query_requests ns 10 20 0 2e-5 bch 1
cc.crosschain_query_requests ss 10 20 0 2e-5 btc 1
cc.crosschain_query_requests ss 10 20 0 2e-5 bch 1
In the above queries, the “10” and the “20” represent the minimum and maximum amounts of CredaCash you would like to sell, “0” represents the minimum rate, “2e-5” represents the estimated total costs in tBTC or tBCH of an exchange sell transaction, and “1” is the maximum number of matching buy requests to return. The query results are sorted in order of the best “open-rate-required”, which is the exchange rate required to match the full open amount of the buy request. Returning one request will therefore return the matching buy request with the highest “open-rate-required”.
In the query results, the “best-match-net-rate” value is the maximum net rate that would need to be offered to match the returned buy request. Even if that rate is offered however, if a competing sell request offers a lower net rate, then it will match first.
4. A request to sell CredaCash for BTC or BCH must include a unique address on the BTC or BCH blockchain to which the buyer can make payment. To generate a unique BTC address using the Electrum wallet, open the Electrum application, open the wallet, click on the “Receive” tab, click the “New Address” button, and then highlight and copy the BTC address that appears on the right. To obtain a unique BCH address using the Electron Cash wallet, open the wallet, click on the “Receive” tab, click the “Clear” button, highlight and copy the BCH address that appears on the right, then enter a decription in the description field and click “Save”.
5. Submit a request to sell CredaCash. Any one of the following commands in the CredaCash wallet will submit a request to sell from 10 to 20 units of CredaCash, at a maximum net exchange rate of 0.0002 tBTC or tBCH per CredaCash, with estimated total costs of 2e-5 tBTC or tBCH:
cc.crosschain_request_create "" ns 10 20 0.0002 2e-5 btc <unique_btc_address>
cc.crosschain_request_create "" ns 10 20 0.0002 2e-5 bch "<unique_bch_address>"
cc.crosschain_request_create "" ss 10 20 0.0002 2e-5 btc <unique_btc_address>
cc.crosschain_request_create "" ss 10 20 0.0002 2e-5 bch "<unique_bch_address>"
If the wallet has sufficient balance (which can be minted using “cc.mint”), then any one of these commands will create a transaction that conditionally pays a matching buyer 20 units of CredaCash. If a match is made, and after about 2 to 4 minutes, the buyer may make payment of approximately 0.001 to 0.002 tBTC or tBCH which will show up in your Electrum wallet. There are two other possible outcomes: Your sell request may not match, in which case the CredaCash conditionally paid to a matching buyer will revert to your wallet after your sell request expires (which, when using the testnet, is by default 5 minutes after the sell request is initiated). Another possibility is that your sell request will match, but the buyer will refuse or fail to complete payment, in which case the CredaCash that you conditionally paid to the buyer will revert to your wallet after the payment time expires (which, when using the testnet, is by default 90 minutes after the match is made).
Note that a sell request will only match one buy request. Once a match is made for any amount between the minimum and maximum amount, then the sell request will close and no additional matches will be made.
Cancelling an Exchange Request
An exchange request closes on its own when it fully matches other requests, or when it expires without a match, which by default when using the testnet is 5 minutes after the request is created. There is currently no mechanism to cancel a request prior to that time. The best that can be achieved is to submit a buy or sell request to offset the initial request. Note that the two offsetting requests may match each other, or one or both may match other requests that have been submitted to the blockchain, depending on which requests offer the best rates.
Querying All Open Exchange Requests
As discussed above, the following wallet commands will query all open exchange requests:
cc.crosschain_query_requests nb 0 0 0 0 btc
cc.crosschain_query_requests nb 0 0 0 0 bch
cc.crosschain_query_requests ns 0 0 0 0 btc
cc.crosschain_query_requests ns 0 0 0 0 bch
cc.crosschain_query_requests sb 0 0 0 0 btc
cc.crosschain_query_requests sb 0 0 0 0 bch
cc.crosschain_query_requests ss 0 0 0 0 btc
cc.crosschain_query_requests ss 0 0 0 0 bch
These commands echo the search parameters in the base object, and return an array of results in the exchange-requests-query-results object.
Querying the CredaCash Wallet’s Exchange Requests
The wallet commands “cc.dump_exchange_requests” and “cc.dump_exchange_matches” can currently be used to check the status of the wallet’s own requests. These commands dump the status in an internal debug format.
Querying Historical Exchange Data
The network node stores information on historical exchange requests and matches in an SQLite database. The SQLite command line tool or other interface can be used to query this data. Note that the exchange request database only includes requests that were added to the blockchain. Requests that were sent to the network but never added to the blockchain (possibly because they expired before matching) are simply discarded.
1. Double-click on the file “__start_testnet_local_node.bat” to run a local network node, then wait for it to synchronize, as described above.
2. Download the SQLite command line tool (included with “sqlite_tools_…”) from https://www.sqlite.org/download.html.
3. Open a command prompt window, and at the command prompt, run the SQLite command line tool and open the network node database for the CredaCash testnet using the command:
sqlite3.exe --readonly "%LOCALAPPDATA%/CredaCash/CCNode2-beta2-1019/CCNode.db"
There are many possible queries that can be run on the exchange tables, providing a great deal of flexibility in the data retrieved. Here are a few examples:
4. It can be helpful (although not required) to change the output mode to json before querying the tables:
.mode json
5. To query exchange requests that expired within the last 10 minutes:
select * from Exchange_Match_Reqs where ExpireTime >= strftime('%s', 'now')-10*60 and ExpireTime <= strftime('%s', 'now');
The Type values are:
4 = CC_TYPE_XCX_NAKED_BUY
5 = CC_TYPE_XCX_NAKED_SELL
6 = CC_TYPE_XCX_SIMPLE_BUY
7 = CC_TYPE_XCX_SIMPLE_SELL
The Disposition values are:
3 = XMATCH_REQ_DISPOSITION_EXPIRED_ALL
4 = XMATCH_REQ_DISPOSITION_EXPIRED_REM
5 = XMATCH_REQ_DISPOSITION_OPEN_ALL
6 = XMATCH_REQ_DISPOSITION_OPEN_PART
7 = XMATCH_REQ_DISPOSITION_MATCHED_PART
8 = XMATCH_REQ_DISPOSITION_MATCHED_ALL
6. To query exchange matches that became final (payment in full was claimed, or the time to claim payment expired) in the last 20 minutes:
select * from Exchange_Matches where FinalTimestamp >= strftime('%s', 'now')-20*60 and FinalTimestamp <= strftime('%s', 'now');
A match's Type is the Type of its buy request. The matches' Status values are:
6 = XMATCH_STATUS_ACCEPTED
7 = XMATCH_STATUS_PART_PAID_OPEN
8 = XMATCH_STATUS_PART_PAID_EXPIRED
9 = XMATCH_STATUS_PAID
10 = XMATCH_STATUS_UNPAID_EXPIRED
7. The above query can also be joined to the Exchange_Match_Reqs table to include the matching buy and sell requests:
select * from Exchange_Matches, Exchange_Match_Reqs as BuyReq, Exchange_Match_Reqs as SellReq where BuyReq.Xreqnum = BuyXreqnum and SellReq.Xreqnum = SellXreqnum and FinalTimestamp >= strftime('%s', 'now')-20*60 and FinalTimestamp <= strftime('%s', 'now');
Graphical Interface
It should be noted that while no graphical interface currently exists for the CredaCash integrated exchange, one could be built using a scripting language and the RPC interfaces to the CredaCash and Bitcoin or Bitcoin Cash wallets.