Auctioneer

Intro

Many ecosystems within the blockchain contain their own ownership model for unique or non-fungible assets. This contract implements auction functionality for such assets using ERC20-compliant tokens for bidding.
This contract is meant to be instantiated once for each different class of asset, so the contract is tied to a particular ownership contract at deploy-time. This has the benefit of simplifying trust in the ownership contract for an auction, while giving up some flexibility: if you create a new class of asset with its own ownership contract it is necessary to deploy a separate instance of the auction contract.
We believe this model matches how auction systems will be used in practice. Individual markets or ecosystems on the blockchain will have their own ownership contracts to implement details specific to their asset type, potentially in addition to their own ERC20-compliant fungible token which can be used for making bids rather than Ether. This property is the basis for our proposed one-to-one relationship between the three sorts of contracts: fungible assets (ERC20), non-fungible assets, and the auction of non-fungible assets.

Goals

• Create a standard interface for ownership of non-fungible assets that can be used in applications beyond this contract.
• Make it easy to incorporate an auction system into any ecosystem where non-fungible assets are owned.

Features

Contract creators should be able to specify a token to use for bids, an ownership contract to use as the source of truth for asset ownership, and an optional fee to apply to each successful auction.
Auction creators should be able to set:

• starting price - all bids must surpass at least this amount
• auction length - how many blocks the auction will be open for
• maximum price - bids at this amount immediately end the auction and the bidder wins (optional)
• bid increment - amount by which bids must surpass the previous bid (optional)

Bidders should be able to:

• make bids on items with a minimal transaction gas fee
• have confidence they will receive the item upon winning (trust the contract rather than trusting the seller)

Installation

npm install auctioneer

Deployment

Auctioneer must be paired with an ownership contract and an ERC20-compliant token contract at deploy-time.
For instance, your Truffle migration script could look like:

var Auctioneer = artifacts.require("Auctioneer");
var ERC20 = artifacts.require("YourERC20Contract");
var Ownership = artifacts.require("YourOwnershipContract");

module.exports = function(deployer) {
  deployer.deploy(Ownership).then(function() {
      return deployer.deploy(ERC20).then(function() {
          return deployer.deploy(Auctioneer, ERC20.address, Ownership.address);
      });
  });
};

Usage

You can call Auctioneer methods from another smart contract in Solidity or directly through web3 in JavaScript.

Reference your deployed contract

Once you have deployed an instance of Auctioneer, you can reference it from web3 with the ABI array and deployment address.

const contract = web3.contract(abi);
const Auctioneer = contract.at(address);

See the web3 documentation for more information.

Create an auction

You can create an auction for any asset you own. You must specify an assset ID, starting price, and length in blocks. You can also optionally a max price and bid increment.

// Retrieve asset ID from your ownership contract
const assetID = getMyAssetID();
// Choose a starting price in the base unit of your token contract
const startingPrice = 100;
// Omit max price for this asset by setting to 0
const maxPrice = 0;
// Set bid increment to 5. A bid of 10 must be followed by a bid of 15 or greater
const bidIncrement = 5;
// Set length to about a week of blocks
const lengthInBlocks = 24192;
Auctioneer.createAuction(assetID, startingPrice, maxPrice, bidIncrement, lengthInBlocks);

Bid on an auction

You can bid on any active auction, so long as you have approved the auction contract to access sufficient funds to place a bid.

// Find an asset ID you would like to bid on
const assetID = getAssetID();
// Choose a amount to bid (must be greater than previous bid)
const amount = 500;
Auctioneer.bid(assetID, amount);

Conclude an auction

Auctions will stop accepting bids once the time limit is exceeded, but must be explicitly concluded to transfer the winning bid to the seller and asset ownership to the auction winner. Auctions can be concluded by either the seller or winning bidder.

// Find the ID of the asset auction you would like to conclude
const assetID = getAssetID();
Auctioneer.concludeAuction(assetID);

Viewing active auctions

You can view a list of IDs of all items on auction at a given time. You can view details of auctions individually given the asset ID.

const auctionIDs = Auctioneer.getActiveAuctionIDs();
for (let i = 0; i < activeAuctionIDs.length; i++) {
    const auctionDetail = Auctioneer.getAuctionInfo(auctionIDs[i]);
    // Do something with auction details
}

Withdrawing

When a bid is made, the amount is escrowed by the Auctioneer contract. When a bid is overbid, the losing bid is made available for withdrawal by the bidder. Additionally, pending withdrawals are used toward new bids before using additional funds are taken from our allowance in the bidder's account.

// First make a bid
Auctioneer.bid(someAssetID, 500);
// ...
// After we make our bid of 500, someone overbids us
// ...
// Now withdrawing will refund the 500 tokens to our account
Auctioneer.withdraw();

Similar Projects

Auctionhouse

Auctionhouse is a contract for creating auctions, but has a one-to-many relationship from the auction contract to ownership contracts and only supports bidding in Ether. One instance of the contract can handle all auctions and each auction can specify its own ownership contract individually.