CredaCash Crosschain Exchange Overview
Introduction
CredaCash includes an integrated, peer-to-peer, crosschain exchange. This exchange allows users to trade CredaCash for bitcoin across blockchains, instantly providing liquidity to every user and reducing barriers to entry.
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 is 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. When two requests match, the buyer pays the seller in bitcoin on the bitcoin blockchain, and the seller pays the buyer in CredaCash on the CredaCash blockchain.
This guide provides an overview of the crosschain exchange design and operation. A companion document, the Crosschain Exchange Quick Start Guide, outlines the basic steps to quickly experiment with the exchange.
Exchange Price Discovery
In addition to liquidity, an important goal of the exchange is price discovery. Price discovery allows users to determine the amounts and rates of trade requests and matches, both current and historic. To accomplish this in the CredaCash integrated exchange, all buy and sell requests are public, including the requested amounts and rates. Trade requests that participate in matching, and the resulting matches and trade settlements, are also permanently recorded in the CredaCash blockchain and stored in an SQL database where they can be queried and analyzed to determine trade price and volume at any point in time.
Due to the information that is intentionally made public, the CredaCash exchange is only semi-private. The amounts traded are public, but the sources and destinations of CredaCash used in trade remain private, so that trades and other CredaCash transactions cannot be linked together or associated with a particular wallet. Bitcoin payments inherit the privacy of the bitcoin blockchain, which means that the the amounts, sources, and destinations of all bitcoin payments are public. The bitcoin payments can be linked to past bitcoin payments and potentially linked to particular wallets using blockchain forensics.
Another important consideration in price discovery is to ensure trades and trade requests are genuine. In any trading market, there are always persons who will attempt to manipulate prices through self-trading (also known as wash trading) or collusion. This is an especially difficult problem to address in a distributed, peer-to-peer, online market.
CredaCash attempts to mitigate this problem through request hold times. During the hold time, any matches are provisional, and if another better matching request is made, then the request will rematch to the better matching request. This effectively opens requests to competitive bidding during the hold time.
As a result, if a user makes wash trade requests in an effort to push the trading price up or down, another user could obtain a favorable trade by submitting a competing request that matches the abnormally high buy request or the abnormally low sell request. As a result, trading requests have to be genuine because users can’t guarantee they will be able to match their own orders, and if they do submit wash trading requests, then other users can take advantage of the liquidity provided to obtain favorable trades for themselves.
For some types of trading requests, a hold time is optional, and for others, it is mandatory. The hold time may not completely eliminate price manipulation, but it does go a long way toward ensuring genuine trade requests and therefore more accurate price discovery.
Exchange Currency Support
The CredaCash crosschain exchange currently supports two “foreign” currencies: Bitcoin (BTC), and Bitcoin Cash (BCH). Bitcoin Cash was chosen because it has much lower transaction fees than Bitcoin, enabling lower cost trading.
Bitcoin and Bitcoin Cash each function as a “quote” currency for buying and selling CredaCash, the “base” currency. The supported trading pairs are therefore CredaCash/BTC and CredaCash/BCH.
Exchange Rates and Net Rates
In the CredaCash crosschain exchange, the exchange rate is defined as the amount of quote currency (BTC or BCH) received by the seller, divided by the amount of CredaCash (the base currency) paid by the seller to the buyer:
exchange rate = BTC or BCH received by seller / CredaCash paid by seller
Buyers of CredaCash would therefore prefer a lower exchange rate, while sellers of CredaCash would prefer a higher exchange rate.
The CredaCash exchange is mostly concerned with each party’s net exchange rate, which is the exchange rate after all costs are accounted for. When creating exchange requests, buyers and sellers can include their estimated costs. These costs are determined by each user, and might include transaction fees, computational costs, accounting costs, overhead costs, etc. — whatever each user wishes to include. These costs are all estimated and accounted for in the quote currency (BTC or BCH).
For a buyer, the net exchange rate is the amount of bitcoin received by the seller plus the buyer’s estimated costs in BTC or BCH, divided by the amount of CredaCash paid by seller:
buyer_net_rate = (BTC or BCH received by seller + buyer’s estimated costs) / CredaCash paid by seller
For a seller, the net exchange rate is the amount of bitcoin received minus the seller’s estimated costs in BTC, divided by the amount of CredaCash paid:
seller_net_rate = (BTC or BCH received by seller – seller’s estimated costs) / CredaCash paid by seller
The exchange attempts to provide buyers with the lowest net rate (most CredaCash), and sellers with the highest net rate (most BTC or BCH). The net effect is that, for equal exchange rates, larger matches are favored over smaller matches, since this spreads the costs over a larger trade amount. When potential exchange rates are not equal however, the match amounts and costs both factor into the net exchange rate.
Exchange Request Matching
Requests to buy and sell on the CredaCash exchange are similar to “limit orders” in that each request includes an amount and a limiting net exchange rate. For buy requests, this limit is the maximum net rate the buyer will accept, and for sell requests, the minimum net rate the seller will accept. To be fair to both parties, when two requests match, the consensus match rate is the midpoint between the maximum rate that satisfies the buy request and the minimum rate that satisfies the sell request.
Exchange requests are matched one-to-one, i.e., a single sell request only matches a single buy request. If, after matching, a buy request still has an open balance, it can then match another sell request. A crosschain sell request however is always closed after its first and only match. This is necessary to ensure that the bitcoin payment address for each match is unique.
The design of the exchange poses the question: “What would the matching result be if each user made their own matching decisions?” The consensus matching process attempts to duplicate what individual users themselves would do. This process is guided by the decisional parameters that each user includes with their exchange requests, including the request amount, net rate required, expiration, etc.
Conceptually, the implementation is fairly straightforward. Each buy request is compared to every sell request to determine which sell request would provide the buyer with the best (lowest) net rate, and each sell request is compared to every buy request to determine which buy request would provide the seller with the best (highest) net rate. If the best rates are mutual, i.e., a buy request and sell request each provide the other with the best net rate, then a consensus mutual match occurs.
When a consensus mutual match occurs, the sell request is closed, and the buy request is updated by subtracting the match amount from the open amount. The entire matching process is then repeated until all consensus mutual matches are found.
The result of this matching process is exactly what would happen if users did the matching themselves. The buyer and seller offering each other the best rate would of course trade with each other, thereby taking themselves out of the trading pool. The remaining buyer and seller that offer each other the best rate would also trade with each other, thereby again taking themselves out of the trading pool. This process would continue until all matches were found.
In order to promote a form of competitive bidding, requests can include a hold time. In fact, buy and sell requests on the CredaCash testnet both automatically have a hold time of 60 seconds.
During the hold time, any matches are provisional. If another better matching request is added to the blockchain during the hold time, then the request will rematch to the better matching request. This effectively opens the request to competitive bids during the hold time. It also goes both ways— either request, the buy request or the sell request, can be outbid while a match is only provisional.
However, under the principal that “a bird in the hand is worth two in the bush,” a request may not want to wait for a match that is on hold. To account for this, each request includes the parameters min_wait and wait_discount. The min_wait is the minimum amount of time that a request will wait for a match that is on hold. If the request would have to wait beyond that time, then the wait_discount is applied to the net rate before comparing it to other potential matches. Specifically, the buyer’s net rate is divided by (1 – wait_discount) for each additional minute that it would have to wait, while the seller’s net rate is multiplied by (1 – wait_discount) for each additional minute that it would have to wait. A wait_discount of zero therefore has no effect, while a wait_discount > 0 discounts matches on hold so they become less attractive, with larger values of wait_discount applying a larger discount. If the discounted match net rate is not as favorable as an immediate match net rate, then the request will prefer the immediate match. This allows requests to hold for future matches, while allowing the value of future matches to be discounted, in the same way that a user might discount the value of a future match compared to an immediate match.
Exchange Request Types
There are currently two types of buy and sell requests implemented on the exchange: “naked” requests and “simple” requests.
A naked buy request is a request to buy CredaCash that does not require any advance payment, deposit, consideration, or even a transaction fee, and it is therefore completely “naked”. Prospective users who do not hold any CredaCash can therefore use a naked buy request to obtain CredaCash in exchange for bitcoin. Because it requires no deposit or fee, it can also be abandoned and a trade not completed by the buyer without penalty. For this reason, a naked buy request should be considered an expression of interest, rather than binding trade commitment. In order to prevent network spam, this request must contain a relatively large proof of work, which might require a full minute or more to generate, depending on the host computer.
The naked sell can be used to sell CredaCash in exchange for bitcoin. This request is called “naked” because it does not require that a matching buy request include any deposit or consideration. This allows a naked sell request to match a naked buy request. The naked sell request however must include a contingent payment of the maximum amount of CredaCash offered for sale, and the wallet balance must therefore be sufficient to cover this amount plus the transaction donation.
A simple buy request includes a pledge of CredaCash equal to 50% of the amount of CredaCash requested to purchase. A user must therefore already hold some amount of CredaCash in order to buy more CredaCash using a simple buy request. If a simple buy request matches and the buyer completes the trade by making payment in bitcoin on the bitcoin blockchain, 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.
A simple sell request is the same as a naked sell request, except that it requires a pledge from the buyer, and will therefore only match a simple buy request.
In summary:
Naked Buy
No Pledge
Can match only naked sell requests
Simple Buy
Includes 50% Pledge
Can match both naked and simple sell requests
Naked Sell
Includes contingent payment of maximum amount to be sold
Requires no pledge from buyer
Can match both naked and simple buy requests
Simple Sell
Includes contingent payment of maximum amount to be sold
Requires 50% pledge from buyer
Can match only simple buy requests
Exchange Request Lifecycle
Exchange requests go through a progression of possible states during their lifetimes:
1. Request is created by the wallet. A sell request includes a contingent payment of CredaCash to a potential buyer, while a simple buy request includes a 50% pledge, and a naked request includes no pledge or fee.
2. Request is transmitted to the CredaCash network.
3. Request is added to a block in the CredaCash blockchain.
4. The block containing the request becomes indelible. At this point, the request enters the matching process.
5. Request optionally enters a hold period. During the hold period, any matches are only provisional, and if a better matching request is added to the blockchain, then the request will rematch to the better matching request.
6. Following the optional hold period, if the request has a match, it is a permanent match. For a permanent match, the match amount is deducted from the request’s open amount. A buy request can continue matching until the open amount reaches zero. Crosschain sell requests however can only match one time, and are closed after their first permanent match. If the amount of this match is smaller than the seller’s contingent payment, then any excess reverts to the seller at this time.
7. The buyer pays the seller in bitcoin on the bitcoin blockchain.
8. The buyer’s bitcoin payment is added to the bitcoin blockchain.
9. The buyer’s bitcoin payment reaches the required number of confirmations on the bitcoin blockchain.
10. The buyer claims the seller’s contingent CredaCash payment on the CredaCash blockchain.
11. For a simple buy request, the buyer’s pledge amount reverts to thr buyer.
There are a few events that can interrupt the normal progression:
A. A request can expire without matching, or for a buy request, having only matched in part. Once it has expired, a request no longer participates in future matching. When a sell request expires without a match, the seller’s contingent payment reverts to the seller, and when a simple buy request expires, any remaining pledge amount reverts to the buyer.
B. A request can be pruned if the pool of requests becomes too large. When a request is pruned, it is equivalent to expiring early, and it no longer participates in future matching.
C. The buyer may fail to make payment on the bitcoin blockchain, or claim the seller’s payment on the CredaCash blockchain prior to the payment expiration time. In both cases, once the payment time expires, the full amount of the seller’s contingent payment reverts to the seller, and in the case of a simple buy request, the buyer’s pledge amount transfers to the seller.
Exchange Request Parameters
The exchange is designed to support a rich set of parameters that allow users to control the matching process and achieve their desired outcomes. The following exchange request parameters are currently supported by both the blockchain and the wallet. These parameter values can be set when using the wallet command “cc_crosschain_request_create”:
min_amount – The minimum amount of CredaCash to trade. Any match for this request will have a match amount >= min_amount. Therefore, to get a match, this request’s min_amount must be <= the other request’s max_amount and open amount.
max_amount – The maximum amount of CredaCash to trade. For a sell request, this is also the amount of the contingent payment that will be made to a prospective buyer, and therefore this amount must be available in the wallet before creating the sell request. For a simple buy request, the buyer pledge is half the max_amount, which must also be available in the wallet before making the request. A sell request will match only once, and the match amount will be >= min_amount and <= max_amount. A buy request may have multiple matches before it expires. Each match amount will be >= min_amount, and the total of all of the buy request’s match amounts will be <= max_amount.
rate – The net exchange rate required for a match. For a buy request, this is the maximum net rate the buyer will accept, and for a sell request, it is the minimum net rate the seller will accept. The net exchange rate of a trade incorporates the user’s estimated costs. For a buy request, the net rate is ((BTC + buyer’s estimated costs) / CredaCash), and for a sell request, the net rate is ((BTC – seller’s estimated costs) / CredaCash).
costs – The user’s total estimated costs of an exchange trade based on this request, in units of the quote currency (BTC or BCH). This value is used to compute the net rates of potential matches, and can include any amounts considered relevant, including transaction fees, computational costs, accounting costs, overhead costs, etc.
cryptoasset – The quote currency. Currently supported values are “btc” and “bch”.
unique_foreign_address – For a sell request, this value must be set to a unique address to which the buyer may make payment on the quote currency blockchain (Bitcoin or Bitcoin Cash). For a buy request, this value is left blank. While using completely unique addresses is recommended, this address may be reused after the request’s expiration plus payment_time have elapsed.
expiration – The elapsed time in seconds after which the request will expire. Upon expiration, the request no longer participates in matching, and the contingent payment included with an unmatched sell request reverts to the seller. For the CredaCash testnet, the default expiration is 5 minutes.
hold_time – After exchange requests are added to the blockchain, they may be placed on “hold” to allow time for other users to create competitive matching requests. This parameter determines the length of that hold time, in seconds. During the hold time, requests will match, but the matches will be provisional until the hold time expires. If a better matching request is added to the blockchain during the hold time, then the request will rematch to the better matching request. For naked buy and sell requests on the CredaCash testnet, the hold_time is fixed at 60 seconds.
hold_time_required – Again, to promote competitive bidding, a request can require that a matching request have a minimum hold time. If this parameter is non-zero, then this request will only match requests that (a) were added to the blockchain at least hold_time_required seconds ago, and (b) for which the matching request also has a hold_time_required of at least this same value. For naked buy and sell requests on the CredaCash testnet, the hold_time_required is fixed at 60 seconds.
min_wait – The minimum amount of time in seconds to wait for a provisional match to become permanent. During the min_wait period, the net rate of a provisional match is not discounted. The default min_wait is zero.
wait_discount – The discount factor to apply to the net rate of provisional matches that will not become permanent until more than min_wait seconds have elapsed. A wait_discount of zero, which is the default, results in no discount. For other values, the discount factor is (1 – wait_discount) for each minute beyond min_wait seconds that the match would remain provisional. Higher values of wait_discount therefore result in a larger discount factor. When comparing net rates for a buy request, the provisional match’s net rate is divided by the discount factor, and when comparing net rates for a sell request, the provisional match’s net rate is multiplied by the discount factor.
confirmations – This parameter relates to the number of confirmations the buyer’s payment must have on the bitcoin blockchain before the buyer can claim the seller’s CredaCash payment on the CredaCash blockchain. Specifically, this parameter is the number of confirmations required by the seller (for a sell request), or offered by the buyer (for a buy request). Two requests match only if the seller’s confirmations required <= buyer’s confirmations offered. For the testnet, the confirmations value is fixed at 2.
payment_time – This parameter relates to the total amount of time after a match that the buyer has to make payment in bitcoin, wait for the payment to reach the required number of confirmations, and then claim the payment on the CredaCash blockchain. Specifically, this parameter is the payment time required by the seller (for a sell request), or offered by the buyer (for a buy request). Two requests match only if the seller’s payment_time required <= buyer’s payment_time offered. For the testnet, the value of this parameter is fixed at 90 minutes.
Additional parameters and options will be documented when they are supported.