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.

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
PreviousThe TraderNextSales & Rentals

Last updated