📘

Use console.enjin.io to use the user interface referenced in this document.

Overview

The marketplace is used for trading assets on pallet-multi-tokens.

Terminology

Listing

Represents an asset being put up for sale. It contains additional information that determines the behavior of the sale.

Auction

A listing with an end time that accepts bids.

Royalty

A percentage of a sale is given to an account when an asset is sold.

Salt

Bytes used to differentiate listings that have the same values.

Make Asset

The asset being sold.

Take Asset

The asset requested.

Fee side

The side that is charged the protocol fee (the make or take side).

Currency

This concept is used by the marketplace to determine what assets are allowed to be listed, and which side of the listing is charged fees.

Config Values

• maxRoundingError: Balance = 1000
  • The max amount that can be lost due to rounding before failing.
• maxSaltLength: u32 = 32
  • Max length of salt used in listings and bids
• minimumBidIncreasePercentage: Perbill = 5%
  • The percentage of the minimum bid in an auction must increase by.
• listingActiveDelay: BlockNumber = 5
  • The minimum number of blocks that must pass before a listing is active.

Types

• ListingId = H256 ([u8;32])
• AssetId - a CollectionId and TokenId

See pallet-multi-tokens for additional types, including CollectionId, TokenId, and Balance.

Listings

Listings are created with the create_listing extrinsic. There are two types of listings:

• Fixed Price listings allow assets to be purchased for a specific price and have no time limit. Assets are purchased using the fill_lisitng extrinsic. Partial fills are supported.
• Timed Auctions operate like an auction. The listing is created with an initial bid price and a time limit. Bids are placed with the place_bid extrinsic and must start at the initial price or more, and then each bid must increase by a fixed percentage (currently 5%). When the time limit is over, the finalize_auction must be called to officially end the auction and transfer the funds.

ListingId Generation

The listing id is generated by encoding the following values to a vector of bytes with the scale codec. Then the result is hashed using BlakeTwo256.

• seller
• make_asset_collection_id
• make_asset_token_id
• take_asset_collection_id
• take_asset_token_id
• amount
• price
• min_take_value
• fee_side
• creation_block
• salt
• data

If it's an auction, the start_block and end_block are included.

Protocol Fee

A protocol fee (currently 2.5%) is taken from all sales.

Royalties

Royalties are currently limited to between 0.1% and 50%. If a royalty is changed after an asset is listed and the seller would get less than they expect, the sale does not go through. This is stored in the minimum_take_value field of the listing.

A collection can only allow certain currencies to be accepted as royalties by adding them to its explicit_royalty_currencies field. If a listing is created that will pay royalties in an unaccepted currency, the listing creation will fail.

Fee Side

The fee side determines which side of the listing, the make side or take side, will be charged the protocol fee. The royalty is determined by the opposite side of the fee side, and it is paid in the currency of the fee side.

The fee side is determined with the following checks:

1. If the make side is a currency, it pays the fee.
2. If the make side is not a currency, but the take side is a currency, the take side pays the fee.
3. If neither side is a currency, there is no fee. However, this is not currently allowed, and the listing cannot be created.

State

Stores information about the marketplace. See MarketplaceInfo for the specific fields.

listings

• Key: ListingId - The id of the listing
• Value: Listing
• Stores all listings.

listingIdsByMakeAsset

• Key: (CollectionId, TokenId) - The collection id and token id of the make asset.
• Value: ListingId - The id of the listing
• Allows querying listings by make asset.

listingIdsByTakeAsset

• Key: (CollectionId, TokenId) - The collection id and token id of the take asset.
• Value: ListingId - The id of the listing
• Allows querying listings by take asset.

listingIdsByAccountId

• Key: AccountId - The account id of the seller
• Value: ListingId - The id of the listing
• Allows querying listings by the seller.

Extrinsics

create_listing - Places a sell order.

The id for the listing is generated as explained above.

The listing does not become active until after the listingActiveDelay (5 blocks) has passed. If it's an auction, it starts when its start_block is reached.

A Token cannot be listed on the marketplace if its listing_forbidden field is set to true.

cancel_listing - Cancels the listing. Only callable by the seller.

fill_listing - Fills a fixed price listing. This will execute immediately.

place_bid -Places a bid on a listing. The listing must be an auction, and it must be currently active. An auction is considered active if the current block is between the start and end blocks of the auction.

Only the latest bid is stored on an auction. All bids must increase by the minimumBidIncreasePercentage, and the first bid must be higher than the price set when the listing was created.

finalize_auction - This will end the auction and transfer funds. It fails if the auction is not over. It can be called by anyone.

set_protocol_fee - Change the protocol fee. Can only be called by the ProtocolFeeOrigin set in the config.