Decentralized Exchange

Introduction

The Biblepay Decentralized Exchange (DEX) was created with various goals in mind:

• The ability to trade your BBP coins against another currency (such as DOGE), directly with other QT wallet users, without relying on a centralized exchange (CEX).
• The ability to add other currencies, which are compatible with the base58 wallet, into the exchange. This may allow other communities to list their coins inside BBP's DEX.

Terminology

Native Coin: The BBP built in currency, or a standard BBP Base58/WIF keypair and its value in the BBP wallet.

Colored Coin: A special coin, with a Base58 address that ends in a 4 digit alphanumeric code that designates value on another network, but stored in the wallet.

Note that Colored coins cannot be sent out to native addresses (therefore preventing colored coins from going to BBP address on CEXs etc) or diluting their value.Colored coins can only be sent to other like colored addresses, using an RPC command.

One example of a colored address is "COLORED-DOGE", which ends in dgzz. Another is colored "COLORED-XLM" ending in lmzz.

Colored coins cannot be sent from unlike colored addresses, XLM cannot be sent to DOGE or vice versa.

You cannot see colored coins in coin-control; their balances can only be queried with RPC commands.

The function the colored coin provides to BBP is:

• Convert Value from a foreign network native UTXO to a BBP colored UTXO
• Seamlessly trade the colored coins in the DEX with other users
• Convert Colored coin value back to native value

Coin Control: From the QT left menu, click Send | Inputs. This page allows you to pick specific coins that are used in a transaction.

BBP Native Receive Addresses: From the QT menu, click Window | Receiving addresses. You will see a list of BBP receive addresses.

TRADING-PUBLIC-KEY: This address is the only BBP native address the DEX will spend from (for security reasons). You must deposit BBP into this address in order to place trades where you Buy foreign currency.

TRADING-ASSET-DOGE: Your wallet will automatically mine a colored DOGE address. This is your colored BBP DOGE address that will hold native doge.

TRADING-ASSET-XLM: Your wallet will also mine a colored XLM address. This is the address that will hold native XLM.

Portfolio Builder: A satellite program that allows you to earn staking rewards for holding an equal amount of native BBP + foreign (see Extensions).

Exchange Flags:Exchange Room | Trading Grid | Flags: The Flag "T" means theirs, "M" means Mine. This way you can see your orders are M.

Usage

To demonstrate the usage of the exchange we will go through some examples in using the exchange to buy BBP (while selling DOGE) and selling BBP (to Buy DOGE).

Prerequisites:

If we want to sell DOGE and buy BBP we will need to fund our TRADING-PUBLIC-KEY. In this example, we will send 100,000 BBP from our core wallet to the TRADING-PUBLIC-KEY.

Click on Exchange from the left menu.

Copy BBP Trading Address to clipboard (that is equivalent to your "TRADING-PUBLIC-KEY" mentioned above).

Go to Send.

Paste the address in the TO.

Send 100,000 BBP to yourself. Now the exchange has funds to trade with. In this demo we also want to sell some DOGE for BBP. Therefore we need to receive some Native DOGE into the BBP colored address.

Click Exchange. Copy the Native DOGE address to the clipboard.

Go to your favorite DOGE wallet, and send 10 DOGE to this native address.

Wait 2 blocks on the DOGE network, then click the Get button (which means get balance). Once you see the coins exist in your DOGE native address, now they need to be wrapped, or converted to colored DOGE in order to be tradeable.

Now click Wrap. Choose the amount (Lets go with 9.9 to ensure there are no transaction fee errors).

Look for the result, it should say "Successfully Wrapped" etc. Now you will have .10 Native doge and 9.9 Colored Doge in the "TRADING-ASSET-DOGE" address; and you can see the balances adjust on the top right.

Placing a SELL Trade

First let us place a trade to Sell BBP while buying with DOGE.

Populate 10000 into the Quantity box.

Populate 0.00011001 into the Price box.

Click SELL.

This will place an order to sell 2.70 DOGE for 10,000 BBP. The order will appear in the Sell grid.

Note that if your wallet is locked you will receive an error and will have to unlock the wallet for this tx to be created.

Placing a BUY Trade

Next let us place a trade to Buy BBP while selling DOGE.

Populate 10000 into the Quantity box.

Populate 0.00010999 into the Price box.

Click BUY.

This will place an order to buy 2.69 DOGE for 10,000 BBP. The order will appear in the Buy grid.

NOTE: You cannot trade with yourself as our atomic tx rejects wash trades with duplicate keys; however you can trade with yourself as long as you use two QT wallets with different key sets.

Once another buyer enters the market to place an opposing trade with the same quantity and an at or better price than yours, your order will fill atomically.

Partial Fills

If your order is bigger in size than their order, a partial fill will occur as long as the partial fill results in a leftover quantity greater than the room minimum.

As of April 2025, the DOGE-BBP room minimum is .10 DOGE per trade.

Atomic Matching

The matching engine is constantly scanning for trades in the orderbook, where the quantities match and the price is at or better than the limit price; when this pair is found, an atomic transaction is created with two legs in one transaction: Colored coin going from Buyer to Seller AND Native BBP coin going from Seller to Buyer AND the network minimum transaction fee (.00100) paid in Native BBP all built in the single transaction. This means that if anything goes wrong with this transaction (not enough funds on either end, tx fee deficiency, network error, chain is out of sync, chainlocks down) etc, then this transaction will FAIL atomically. This is good, because now the trading board has not changed, and neither buyer or seller is harmed. However, if the transaction goes through, both buyer and seller are satisfied atomically. Meaning that both colored balances and both native BBP balances are instantly updated with no possibility of error on either end.

Canceling a Trade

To cancel a trade, simply highlight the row with the trade you placed (yours have M) and click Cancel.

Insufficient Funds - Orders with no backing collateral

Note that we only allow orders to enter into the orderbook, if, at the time of the trade, the user has enough collateral (IE colored coin balance and BBP balance are sufficient to place the trade).

However, since we have 24 hour atomic matching while users are offline, it is possible for a user to do an offline spend of a coin that is already in the orderbook.

This is not a problem because Atomic trades cannot occur (if coins are spent prior to the atomic tx being created), that part is prevented.

The sanctuary thread constantly looks for trades with no backing collateral.

The sanctuary will cancel these automatically causing them to disappear from the order book.

Converting your Colored DOGE back to NATIVE DOGE

To convert your coins back to Native, click Unwrap. Type in the amount of Native you want to convert back (IE 9 in our example above).

Once this process finishes, you will see the Native DOGE balance increases back to the original amount (IE 9.99~).

Sending DOGE from the biblepay wallet to the DOGE wallet

Now to send DOGE out of your wallet back to your home DOGE wallet, go to the RPC console and type:

exec senddoge doge_to_address amount

Technical Specs

We have three types of Sancs, Altar, Sanc, and Temple. The Temple is required to stake 10* the collateral than the Sanc.

The Temple runs an additional piece of software, called BMS (BiblePay Middleware System) which contains the BBP API. The Temple also runs a decentralized sidechain, which creates blocks on demand. (We are currently at block 21000 on the side chain). Side chain blocks are stored on STORJ. Each temple node syncs the BBP sidechain blocks up the the tip, automatically.

When exchange trades are placed in QT, the AtomicTrade is serialized and opensource, except for the colored private key (or the BBP private key).

The private key is encrypted with RSA, and included in the serialized block hex. 

The trade is forwarded to a temple, and the temple creates a sidechain BLOCK and stores it in STORJ. Note that the Temple cannot read the private key, because it is encrypted.

When QT needs a refreshed trading screen, it queries the order book from the Temple. The Temple aggregates OPEN orders from the sidechain objects.

A trading order book is a collection of AtomicTrades where Status='OPEN' and TradingPair='BBP/DOGE'. Each time the orderbook changes, this feed is sent down from the temple back to the QT client.

Also, the QT client receives a PriceFeed from the Temple which contains the price of USD-DOGE, BTC-USD, BBP-DOGE, etc. The midpoint of the market is assessed by the temple based on the actual orderbook data.

The Matching Engine is running on the Temple, and it is constantly scanning for trades where quantity matches and price is at or better than the ask.

When the Temple needs to create an atomic transaction, it concatenates the seller with the buyer, combining it into one transaction using NBitcoin.

The private keys are Not readable by the Temple in production, or in debug mode.

The AtomicTX then is sent into a proprietary Signing piece of code for the Signing request. The Signer is closed source and is able to decrypt the private key for the atomic tx and place the signature in place and it returns the signed tx to the caller, which broadcasts it to the BBP network.

Note that the Ingate and Outgate run on the temple.

Since it is mission critical to allow a user to receive back the colored coin, we also created a BBP extension, called PortfolioBuilder, that can run on your own machine and do 100% of the Outgate transaction.

This is useful for a scenario where, let us say you have $5,000 of colored coin value and our temple is down but the biblepay network is up and you receive an outgate error.

We want you to *always* be able to receive your native coin.

You can launch PortfolioBuilder and do your own outgate in this case.

Risks

First I want to say at BiblePay, we want you to know your QT keys and your QT wallet is the highest priority and always want every key to be secure. All of the private keys *Other than the Trading Keys*, in your QT wallet are 100% private.

However, the "TRADING-" keys (the 3 mentioned in the beginning) are being used by the DEX to create atomic transactions.

Although they are RSA encrypted, there is always a small chance that something can go wrong that is unintended.

So it is best to treat the DEX in a similar way that you do with other CEXs, trade with limited amounts and do not leave large amounts on the exchange.

Convert the coins back to native BBP when you can. If you do this the potential damage is always limited to the amount "in play" on the exchange.

Future State

The current exchange fulfills many of the desirable qualities that were originally scoped, however there are always tradeoffs with each approach.

In the current approach you have:

Ability to match atomic trades 24H even when users are offline (plus).

Mostly Decentralized (User to user trading, requires one designated temple or temple cluster to be online, the temple API must be working, STORJ must be working).

However, we may eventually want to improve the exchange making it 100% decentralized through various technological advances.

For example, maybe the NBitcoin code can be moved into each online client, allowing matching to occur client side as well.

The tradeoff is the node may need to be online for this to work (at the time the fill occurs).

Also we may want to move the orderbook from the sidechain to the client side.

We may also want to move to a market maker model, where market makers buy-sell colored coins and hold the collateral along with an equal amount of BBP.

We may want to come up with a scheme to change the WIF format of all trading keys so they cannot be under any circumstance, hacked as regular keys.

Another improvement is to make Portfolio Builder use newly generated private keys for staking, rather than the XLM/XRP exchange keys noted at the beginning.