The Bazaar

An order book decentralized exchange (DEX)

Introduction

The Bazaar is a decentralized exchange (DEX) that uses an order book instead of liquidity pools to manage trades. Players can create buy and sell orders for any ERC-20 or ERC-1155 token at the price point of their choosing, which will be filled immediately when able, or placed on the order book for fulfillment later.

All items or tokens traded in the Bazaar use JEWEL as the base currency on all realms.

Orders

Orders are the center of the Bazaar contract, created using the makeOrders function and stored on the contract while they are open. Orders can be created on the buy or sell side of the contract, and are executed when an order on the other side meets an existing order's price. Orders at the same price point are executed on a first-in-first-out basis. Completed orders are deleted from the contract, and must be viewed either as OrderExecuted events or as BazaarTransactions in the API.

Quantity

The Bazaar is token agnostic, and is built to work with tokens of any decimal amount. The quantity of an order is entered and stored in wei. For DFK's many zero-decimal tokens, a single token will be a single digit. For 18-decimal tokens, all digits must be entered.

Examples

• 1 Greater Might Stone: 1

• 123.456 DFK Gold: 123456

• 10.5 CRYSTAL: 10500000000000000000

Price

The price of an order is entered and stored in different ways. Since all orders are placed in JEWEL, the price per unit must be expressed in wei (18 digits).

The makeOrders function requires an input of totalPrice, calculated as follows:

• unitPrice (in wei) * quantity (in wei) / 10^(tokenDecimals)

Once stored on the contract and in the API, the token price (per unit, not total) is multiplied by the contract's PRICE_FACTOR, expressed as:

• unitPrice (in wei) * 10^12

Examples

• 1 Greater Might Stone @ 250 JEWEL

  • Order Input: 250000000000000000000 * 1 / 10^0 = 250000000000000000000

  • Held in Contract as: 250000000000000000000 * 10^12 = 250000000000000000000000000000000

• 123.456 DFK Gold @ 0.001 JEWEL / each

  • Order Input: 1000000000000000 * 123456 / 10^3 = 123456000000000000

  • Held in Contract as: 1000000000000000 * 10^12 = 1000000000000000000000000000

• 10.5 CRYSTAL @ 0.16 JEWEL / each

  • Order Input: 160000000000000000 * 10500000000000000000 / 10^18 = 1680000000000000000

  • Held in Contract as: 160000000000000000 * 10^12 = 160000000000000000000000000000

Restrictions

There are a number of restrictions on how orders can be placed:

Precision

By default, the price per unit of an order is limited to 4 digits of precision. Exceeding this limit will cause the transaction to revert.

Examples

• ✅ 123.4 JEWEL

• ✅ 0.000001234 JEWEL

• ✅ 1234000 JEWEL

• ❌ 123.04 JEWEL

• ❌ 1.000000001 JEWEL

• ❌ 123402 JEWEL

Some tokens with larger prices relative to JEWEL have a precisionOverride set. Currently these tokens include Bitcoin and Ethereum, which are set to 6 digits of precision.

Minimum & Maximum Order Value

Each Order has a minimum and maximum limit to the total value of the order, that is, the pricePerUnit * quantity + fee. Exceeding these limits will cause the transaction to revert.

• Minimum Order Value: 0.0001 JEWEL (100000000000000 wei)

• Maximum Order Value: 50,000,000 JEWEL (50000000000000000000000000 wei)

Contract

Addresses

Name	Mainnet	Testnet
DFK Chain	0x902F2b740bC158e16170d57528405d7f2a793Ca2	0x767A9114B61fb14732Cfca1ccA2d9FD309c74E93
Metis	0x4cB622C886c89c0472C0056A7C4c929c98c35D14	0xa678d193fEcC677e137a00FEFb43a9ccffA53210

Interface

interface IBazaarDiamond {

    // Events
    event DefaultFeeSet(uint8 side, uint256 fee);
    event FeeAddressAdded(address indexed feeAddress, uint256 indexed feePercent);
    event FeeDeferred(address indexed source, address indexed from, address indexed to, address token, uint256 amount, uint64 timestamp);
    event FeeDisbursed(address indexed source, address indexed from, address indexed to, address token, uint256 amount, uint64 timestamp);
    event FeeLockedBurned(address indexed source, address indexed from, address indexed to, address token, uint256 amount, uint64 timestamp);
    event MarketFeeSet(address token, uint8 side, uint256 fee);
    event OrderAdded(uint256 indexed orderId, address indexed token, address baseToken, uint256 tokenId, bool isERC20, uint8 side, address indexed sender, uint256 price, uint256 quantity);
    event OrderCancelled(uint256 orderId, tuple(uint256 orderId, address token, uint256 tokenId, bool isERC20, uint8 side, address owner, uint256 price, uint256 quantity, uint256 feePercent) order);
    event OrderExecuted(uint256 indexed orderId, address indexed initiator, uint256 quantity, uint256 remainingQuantity, uint256 price);

    // Static Functions
    function MIN_ORDER_VALUE() view returns (uint256);
    function PRICE_FACTOR() view returns (uint256);
    function defaultPrecision() view returns (uint256);
    function maxTotalPrice() view returns (uint256);
    function nextOrderId() view returns (uint256);
    function paused() view returns (bool);
    function powerUpManagerAddress() view returns (address);
    function precisionOverride(address) view returns (uint256);
    function useWeth() view returns (bool);

    // Read-Only Functions
    function calcFee(address _token, uint8 _side, uint256 _quantity) view returns (uint256);
    function calcFeePercent(address _user, address _token, uint8 _side) view returns (uint256);
    function getBestOrder(address _token, uint256 _tokenId, uint8 _side) view returns (tuple(uint256 orderId, address token, uint256 tokenId, bool isERC20, uint8 side, address owner, uint256 price, uint256 quantity, uint256 feePercent));
    function getBestOrderId(address _token, uint256 _tokenId, uint8 _side) view returns (uint256, uint256);
    function getBestOrders(address _token, uint256 _tokenId) view returns (tuple(uint256 orderId, address token, uint256 tokenId, bool isERC20, uint8 side, address owner, uint256 price, uint256 quantity, uint256 feePercent) buyOrder, tuple(uint256 orderId, address token, uint256 tokenId, bool isERC20, uint8 side, address owner, uint256 price, uint256 quantity, uint256 feePercent) sellOrder);
    function getCostForQuantity(address _token, uint256 _tokenId, uint8 _side, uint256 _quantity) view returns (uint256, uint256);
    function getNumPrices(address _token, uint256 _tokenId, uint8 _side) view returns (uint256);
    function getOrderIdsAtPrice(address _token, uint256 _tokenId, uint8 _side, uint256 _price) view returns (uint256[], uint256[]);
    function getOrders(uint256[] _orderIds) view returns (tuple(uint256 orderId, address token, uint256 tokenId, bool isERC20, uint8 side, address owner, uint256 price, uint256 quantity, uint256 feePercent)[]);
    function getPrices(address _token, uint256 _tokenId, uint8 _side) view returns (uint256[]);
    function getQuantityUpToPrice(address _token, uint256 _tokenId, uint8 _side, uint256 _price) view returns (uint256);
    function getUserOpenOrderIds(address _user) view returns (uint256[]);

    // State-Changing Functions
    function cancelOrders(uint256[] _orderIds);
    function editOrders(tuple(uint256 orderId, uint256 newTotalPrice, uint256 newQuantity)[] _inputs) payable;
    function makeOrders(tuple(address token, uint256 tokenId, uint8 side, uint256 totalPrice, uint256 quantity, bool addUnfilledOrderToOrderbook, bool isERC20)[] _inputs) payable;

}

ABI

39KB

BazaarDiamond.json

Types

Order

An open order book order stored on the blockchain in the Bazaar contract.

struct Order {
    uint256 orderId;
    address token;
    uint256 tokenId;
    bool isERC20;
    Side side;
    address owner;
    uint256 price;
    uint256 quantity;
    uint256 feePercent;
}

Name	Type	Description
orderId	uint256	The unique ID of the Order
token	address	The contract address of the transacted token
tokenId	uint256	The id of an ERC-1155 token, or 0 for an ERC-20 token
isERC20	bool	Whether the token is an ERC-20 (true), as opposed to ERC-1155 (false)
side	Side	The side of the order - 0 for buy; 1 for sell
owner	address	The 0x address of the wallet that created the order
price	uint256	The price per unit of the token stored as unitPrice (in wei) * 10^12
quantity	uint256	The quantity of token to be transacted, expressed in wei
feePercent	uint256	The fee percent paid/to be paid by the order owner, expressed as decimalPercent * 10000 (e.g. 1500 for 1.5%, 1400 for 1.4%, and 1000 for 1%)

OrderInput

The input struct to the makeOrders function to create one or more new Orders.

struct OrderInput {
    address token;
    uint256 tokenId;
    Side side;
    uint256 totalPrice;
    uint256 quantity;
    bool addUnfilledOrderToOrderbook;
    bool isERC20;
}

Name	Type	Description
token	address	The contract address of the transacted token
tokenId	uint256	The id of an ERC-1155 token, or 0 for an ERC-20 token
side	Side	The side of the order - 0 for buy; 1 for sell
totalPrice	uint256	The total price of the order expressed as unitPrice (in wei) * quantity (in wei) / 10^(tokenDecimals)
quantity	uint256	The quantity of token to be transacted, expressed in wei
addUnfilledOrderToOrderbook	bool	Whether any unfilled portion of the order should be placed on the order book (true) or not (false)
isERC20	bool	Whether the token is an ERC-20 (true), as opposed to ERC-1155 (false)

EditOrderInput

The input struct to the editOrders function to edit one or more existing Orders.

struct EditOrderInput {
    uint256 orderId;
    uint256 newTotalPrice;
    uint256 newQuantity;
}

Name	Type	Description
orderId	uint256	The orderId of the Order to be edited
newTotalPrice	uint256	The new total price of the order expressed as unitPrice (in wei) * quantity (in wei) / 10^(tokenDecimals)
newQuantity	uint256	The new quantity of token to be transacted, expressed in wei

Side

The side (buy or sell) of the order book that an Order is created or stored on.

enum Side {
    BUY,
    SELL
}

Name	Value	Description
BUY	0	The buy side of the order book
SELL	1	The sell side of the order book

Events

OrderAdded

event OrderAdded(
    uint256 indexed orderId,
    address indexed token,
    address baseToken,
    uint256 tokenId,
    bool isERC20,
    uint8 side,
    address indexed sender,
    uint256 price,
    uint256 quantity
);

Emitted whenever an Order is added to the order book by the makeOrders or editOrders functions.

Name	Type	Description
orderId	uint256	The unique ID of the Order
token	address	The contract address of the transacted token
baseToken	address	The contract address of the base token (JEWEL)
tokenId	uint256	The id of an ERC-1155 token, or 0 for an ERC-20 token
isERC20	bool	Whether the token is an ERC-20 (true), as opposed to ERC-1155 (false)
side	uint8	The Side of the order - 0 for buy; 1 for sell
sender	address	The 0x address of the wallet creating the order
price	uint256	The price per unit of the token expressed as unitPrice (in wei) * 10^12
quantity	uint256	The quantity of token being transacted, expressed in wei

OrderCancelled

event OrderCancelled(
    uint256 orderId,
    tuple(
        uint256 orderId,
        address token,
        uint256 tokenId,
        bool isERC20,
        uint8 side,
        address owner,
        uint256 price,
        uint256 quantity,
        uint256 feePercent
    ) Order
);

Emitted whenever an Order is cancelled by the cancelOrders or editOrders functions.

Name	Type	Description
orderId	uint256	The unique ID of the Order
order	Order	The full Order struct

OrderExecuted

event OrderExecuted(
    uint256 indexed orderId,
    address indexed initiator,
    uint256 quantity,
    uint256 remainingQuantity,
    uint256 price
);

Emitted whenever an Order is executed by the makeOrders or editOrders function.

Name	Type	Description
orderId	uint256	The unique ID of the Order
initiator	address	The 0x address of the wallet initiating the order execution
quantity	uint256	The quantity of token being transacted, expressed in wei
remainingQuantity	uint256	The remaining quantity of the token left in the order, expressed in wei
price	uint256	The price per unit of the token expressed as unitPrice (in wei) * 10^12

State-Changing Functions

cancelOrders

function cancelOrders(uint256[] _orderIds);

Removes one or more open Orders that are owned by the msg.sender from the order book.

• Emits OrderCancelled

editOrders

function editOrders(
  tuple(
    uint256 orderId,
    uint256 newTotalPrice,
    uint256 newQuantity
  )[] EditOrderInput
) payable;

Given one or more EditOrderInput structs, cancels each Order and creates a new Order with the same token and other parameters, but with a new totalPrice and/or quantity.

• Editing a buy order on DFK Chain must submit the appropriate totalPrice + fee as value with the transaction.

• Editing a sell order must have already approved the appropriate quantity of token to the Bazaar contract.

• Emits OrderAdded, OrderCancelled, OrderExecuted

makeOrders

function makeOrders(
  tuple(
    address token,
    uint256 tokenId,
    uint8 side,
    uint256 totalPrice,
    uint256 quantity,
    bool addUnfilledOrderToOrderbook,
    bool isERC20
  )[] OrderInput
) payable;

Given one or more OrderInput structs, creates an Order for each and executes on it when possible.

• A buy order on DFK Chain must submit the appropriate totalPrice + fee as value with the transaction.

• A sell order must have already approved the appropriate quantity of token to the Bazaar contract.

• Emits OrderAdded, OrderExecuted

Related Pages

Bazaar