Province
Search
K

Sales

The sales service allows for the sale of new items generated by the game. It also allows for players to sell assets they own and lease their equipment to other players.

Data Model

start (int) - the start time of the sale in milliseconds. See time for more details.
end (int) - the end date of the sale in milliseconds. See time for more details.
item_type (string) - the type of item being sold or leased. can be one of ["land", "equipment"]
plot_int (int): When item_type is "land", this field lists the plot id of the land be sold. Should be null otherwise.
serial (int): When item_type is "equipment", this field lists the serial number of the equipment item. sale_type (string): This describes whether the sale is a "sale" or "lease".
pricing_model (string): Indicates whether the pricing method will be "auction" or "fixed-price".
sale_id (string): a random string to identify the sale (length and structure TBD). This should not be the database id.
price: int Price for fixed price sales only. Decimals not permitted. bids: [{bid}, {bid}, ...] For auctions only.
state (string): One of ["created", "started"]
buyer (string): address of the owner. Must start with 0x and be 42 characters (numbers and letters only). Only present once the sale has ended and a buyer is declared. null if no buyer is declared.

Bid Data Model

bid: Int The amount of the bid. Decimals not permitted data: JSON message signed by the bidder hash (string): the signature from the bidder address (string): c-chain address of the bidder

States

created

Sales by players can only be created if the address sending the request to create a sale owns the item under scope. The request must first be authenticated. Secondly, a check must be done to the Land Data Service (for land sales) and the Equipment Service (for equipment sales) to ensure that the address is listed as the owner for the item. If not, this could be a sign of either a fault or hacking probe and should be logged and investigated.
Requests to create a service must include the following fields: start, end, item_type, [plot_int or serial], sale_type, pricing_model. The sale_id should be automatically generated on the server side. Additional validation rules: start must always be less than end, start cannot be more than 7 days in the future, End must be at least 24 hours or more than start but cannot be more than 30 days after start.

started

If the current epoch time (Date.now()) is greater than start, the state changes to "started". Bids can now be accepted in this state.

ended

For auctions, if the current epoch time (Date.now()) is greater than end, the state changes to "ended". Bids can no longer be accepted in this state. For fixed-price sales, the sale enters the ended state when either a buyer has paid for the full price or the end date has passed.

cancelled

Users have chosen to cancel a fixed-price sale before the end date. Does not apply to auctions.