Phase 3 - Auction Pallet

[ipapandinas]

Auction Pallet

This document specifies the design choices took for the Auction pallet implementation in the Indexer and SDK.
Feel free to comment on certain misunderstandings and new suggestions are warm welcomed.

Sections:

• Events: list of the incoming events from the chain. (7 events)
• Extrinsics: SDK extrinsics to implement on the SDK. (7 helpers)
• Constants: SDK constants to implement on the SDK. (7 getters)
• Storage: SDK storage to implement on the SDK. (3 getters)
• Indexer Schema: The AuctionEntity entity schema for Indexer and the links it creates on other existing entities.

Events

In order to make the returned events datas usefull, we provide both the native format and a friendly ready to use format design format :

• a string as an AccountId32 correspond to a classic user valid address.
• a string as u128 is a BN value as string natively used under the hood by the chain.
• a rounded data (ex: amoutRounded) is the "human" version of a data, (usually a BN) that can be directly used.

7 events are triggered by the chain in the module auction

/// A new auction was created.
AuctionCreated {
    nft_id: NFTId,
    marketplace_id: MarketplaceId,
    creator: T::AccountId,
    start_price: BalanceOf<T>,
    buy_it_price: Option<BalanceOf<T>>,
    start_block: T::BlockNumber,
    end_block: T::BlockNumber,
},

/// An existing auction was cancelled.
AuctionCancelled { nft_id: NFTId },

/// An auction has completed and no more bids can be placed.
AuctionCompleted { nft_id: NFTId, new_owner: Option<T::AccountId>, amount: Option<BalanceOf<T>> },

/// A new bid was created.
BidAdded { nft_id: NFTId, bidder: T::AccountId, amount: BalanceOf<T> },

/// An exising bid was removed.
BidRemoved { nft_id: NFTId, bidder: T::AccountId, amount: BalanceOf<T> },

/// An exising bid was updated.
BidUpdated { nft_id: NFTId, bidder: T::AccountId, amount: BalanceOf<T> },

/// Balance claimed.
BalanceClaimed { account: T::AccountId, amount: BalanceOf<T> },

SDK events

Additional events will be added to the EventType enum in src > events.ts in the SDK:

export enum EventType {
  ...
  
  // Auctions
  AuctionCreated = "auction.AuctionCreated",
  AuctionCancelled = "auction.AuctionCancelled",
  AuctionCompleted = "auction.AuctionCompleted",
  BidAdded = "auction.BidAdded",
  BidRemoved = "auction.BidRemoved",
  BidUpdated = "auction.BidUpdated",
  BalanceClaimed = "auction.BalanceClaimed",
}

static fromEvent(event: Event): BlockchainEvent {
    ...
    
    switch (name) {
      ...
      // Auctions
      case EventType.AuctionCreated:
        return new AuctionCreatedEvent(event)
      case EventType.AuctionCancelled:
        return new AuctionCancelledEvent(event)
      case EventType.AuctionCompleted:
        return new AuctionCompletedEvent(event)
      case EventType.BidAdded:
        return new BidAddedEvent(event)
      case EventType.BidRemoved:
        return new BidRemovedEvent(event)
      case EventType.BidUpdated:
        return new BidUpdatedEvent(event)
      case EventType.BalanceClaimed:
        return new BalanceClaimedEvent(event)
    }

    ...
  }
}

/**
 * This class represents the on-chain AuctionCreatedEvent event.
 */
export class AuctionCreatedEvent extends BlockchainEvent {
  nftId: number
  marketplaceId: number
  creator: string // AccountId32
  startPrice: string // u128
  startPriceRounded: number
  buyItPrice: string // u128
  buyItPriceRounded: number
  startBlockId: number
  endBlockId: number
  timestampStart: Date
  timestampEnd: Date

  /**
   * Construct the data object from the AuctionCreatedEvent event
   * @param event The AuctionCreatedEvent event
   */
  constructor(event: Event) {
    super(event, EventType.AuctionCreatedEvent)
    const [nftId, marketplaceId, creator, startPrice, buyItPrice, startBlockId, endBlockId] = event.data
    
    this.nftId = Number.parseInt(nftId.toString())
    this.marketplaceId = Number.parseInt(marketplaceId.toString())
    this.creator = creator.toString()
    this.startPrice = startPrice.toString()
    this.startPriceRounded = roundBalance(this.startPrice)
    this.buyItPrice = buyItPrice.toString()
    this.buyItPriceRounded = roundBalance(this.buyItPrice)
    this.startBlockId = startBlockId.toString()
    this.endBlockId = endBlockId.toString()
    this.timestampStart = blockNumberToDate(Number(this.startBlockId))
    this.endBlockId = blockNumberToDate(Number(this.endBlockId))
  }
}

/**
 * This class represents the on-chain AuctionCancelledEvent event.
 */
export class AuctionCancelledEvent extends BlockchainEvent {
  nftId: number

  /**
   * Construct the data object from the AuctionCancelledEvent event
   * @param event The AuctionCancelledEvent event
   */
  constructor(event: Event) {
    super(event, EventType.AuctionCancelledEvent)
    const [nftId] = event.data
    
    this.nftId = Number.parseInt(nftId.toString())
  }
}

/**
 * This class represents the on-chain AuctionCompleted event.
 */
export class AuctionCompleted extends BlockchainEvent {
  nftId: number
  newOwner: string // AccountId32
  amount: string // u128
  amountRounded: number
  marketplaceCut: string // u128
  marketplaceCutRounded: number
  royaltyCut: string // u128
  royaltyCutRounded: number

  /**
   * Construct the data object from the AuctionCompleted event
   * @param event The AuctionCompleted event
   */
  constructor(event: Event) {
    super(event, EventType.AuctionCompleted)
    const [nftId, newOwner, amount, marketplaceCut, royaltyCut] = event.data
    
    this.nftId = Number.parseInt(nftId.toString())
    this.newOwner = newOwner.toString()
    this.amount = amount.toString()
    this.amountRounded = roundBalance(this.amount)
    this.marketplaceCut = marketplaceCut.toString()
    this.marketplaceCutRounded = roundBalance(this.marketplaceCut)
    this.royaltyCut = royaltyCut.toString()
    this.royaltyCutRounded = roundBalance(this.royaltyCut)
  }
}

/**
 * This class represents the on-chain BidAdded event.
 */
export class BidAdded extends BlockchainEvent {
  nftId: number
  bidder: string // AccountId32
  amount: string // u128
  amountRounded: number

  /**
   * Construct the data object from the BidAdded event
   * @param event The BidAdded event
   */
  constructor(event: Event) {
    super(event, EventType.BidAdded)
    const [nftId, bidder, amount] = event.data
    
    this.nftId = Number.parseInt(nftId.toString())
    this.bidder = bidder.toString()
    this.amount = amount.toString()
    this.amountRounded = roundBalance(this.amount)
  }
}

/**
 * This class represents the on-chain BidRemoved event.
 */
export class BidRemoved extends BlockchainEvent {
  nftId: number
  bidder: string // AccountId32
  amount: string // u128
  amountRounded: number

  /**
   * Construct the data object from the BidRemoved event
   * @param event The BidRemoved event
   */
  constructor(event: Event) {
    super(event, EventType.BidRemoved)
    const [nftId, bidder, amount] = event.data
    
    this.nftId = Number.parseInt(nftId.toString())
    this.bidder = bidder.toString()
    this.amount = amount.toString()
    this.amountRounded = roundBalance(this.amount)
  }
}

/**
 * This class represents the on-chain BidUpdated event.
 */
export class BidUpdated extends BlockchainEvent {
  nftId: number
  bidder: string // AccountId32
  amount: string // u128
  amountRounded: number

  /**
   * Construct the data object from the BidUpdated event
   * @param event The BidUpdated event
   */
  constructor(event: Event) {
    super(event, EventType.BidUpdated)
    const [nftId, bidder, amount] = event.data
    
    this.nftId = Number.parseInt(nftId.toString())
    this.bidder = bidder.toString()
    this.amount = amount.toString()
    this.amountRounded = roundBalance(this.amount)
  }
}

/**
 * This class represents the on-chain BalanceClaimed event.
 */
export class BalanceClaimed extends BlockchainEvent {
  account: string // AccountId32
  amount: string // u128
  amountRounded: number

  /**
   * Construct the data object from the BalanceClaimed event
   * @param event The BalanceClaimed event
   */
  constructor(event: Event) {
    super(event, EventType.BalanceClaimed)
    const [account, amount] = event.data
    
    this.account = account.toString()
    this.amount = amount.toString()
    this.amountRounded = roundBalance(this.amount)
  }
}

Extrinsics

7 extrinsics will be implemented from the auction pallet.

Each helperTx will be duplicated by another helper version with 2 additional parameters: the keyring that will be used to sign and submit the transaction, and a waitUntil callback parameter, to define at which point we want to get the results of the transaction execution.

/**
 * @name createAuctionTx
 * @summary               Creates an auction for an NFT.
 * @param nftId           The ID of the NFT.
 * @param marketplaceId   The ID of the marketplace where the auction will take place.
 * @param startBlock      The ID of the block at which the auction starts.
 * @param endBlock        The ID of the block at which the auction ends.
 * @param startPrice      The price at which the auction starts.
 * @param buyItPrice      The price to directly buy the NFT before the auction starts. Optional Parameter.
 * @returns               Unsigned unsubmitted Create-Auction Transaction Hash. The Hash is only valid for 5 minutes.
 */
 createAuctionTx(
    nftId: number,
    marketplaceId: number,
    startBlock: number,
    endBlock: number,
    startPrice: number | BN,
    buyItPrice?: number | BN = undefined,
)

/**
 * @name cancelAuctionTx
 * @summary       Cancels an auction for an NFT. This transaction can only be submitted if the auction has not started yet.
 * @param nftId   The ID of the NFT.
 * @returns       Unsigned unsubmitted Cancel-Auction Transaction Hash. The Hash is only valid for 5 minutes.
 */
 cancelAuctionTx(nftId: number)
 
/**
 * @name endAuctionTx
 * @summary       Ends an auction for an NFT. This transaction can only be submitted if the auction has entered the ending period.
 * @param nftId   The ID of the NFT.
 * @returns       Unsigned unsubmitted End-Auction Transaction Hash. The Hash is only valid for 5 minutes.
 */
endAuctionTx(nftId: number)

/**
 * @name addBidTx
 * @summary       The bidder adds a new bid offer.
 * @param nftId   The ID of the NFT.
 * @param amount  The new bid added.
 * @returns       Unsigned unsubmitted Add-Bid Transaction Hash. The Hash is only valid for 5 minutes.
 */
addBidTx(nftId: number, amount: number | BN)

/**
 * @name removeBidTx
 * @summary       The bidder removes his bid offer.
 * @param nftId   The ID of the NFT.
 * @returns       Unsigned unsubmitted Remove-Bid Transaction Hash. The Hash is only valid for 5 minutes.
 */
removeBidTx(nftId: number)

/**
 * @name buyItNowTx
 * @summary       The NFT can be directly buy if a buyItPrice was defined and the auction has not started yet.
 * @param nftId   The ID of the NFT.
 * @returns       Unsigned unsubmitted Buy-It-Now Transaction Hash. The Hash is only valid for 5 minutes.
 */
buyItNowTx(nftId: number)

/**
 * @name claimTx
 * @summary   Bidders that did not win the auction have to claim back their bids balance after an auction ends.
 * @returns   Unsigned unsubmitted Buy-It-Now Transaction Hash. The Hash is only valid for 5 minutes.
 */
claimTx()

Constants

7 constants getters will be implemented from the auction pallet.

export enum txPallets {
  ...
  auction = "auction",
}

export enum chainConstants {
  ...
  // auction
  auctionEndingPeriod = "auctionEndingPeriod"
  auctionGracePeriod = "auctionGracePeriod"
  biddersListLengthLimit = "biddersListLengthLimit"
  maxAuctionDelay = "maxAuctionDelay"
  minAuctionDuration = "minAuctionDuration"
  maxAuctionDuration = "maxAuctionDuration"
  parallelAuctionLimit = "parallelAuctionLimit"
}

/**
 * @name getAuctionEndingPeriod
 * @summary Period (in blocks) before the end of the auction during which an auction can be extended if new bids are added.
 * @returns Number.
 */
getAuctionEndingPeriod(): number => consts(txPallets.auction, chainConstants.auctionEndingPeriod)

/**
 * @name getAuctionGracePeriod
 * @summary Period (in blocks) to extend an auction by if a new bid is received during the ending period.
 * @returns Number.
 */
getAuctionGracePeriod(): number => consts(txPallets.auction, chainConstants.auctionGracePeriod)

/**
 * @name getBidderListLengthLimit
 * @summary Total amount of accounts that can be in the bidder list for an auction.
 * @returns Number.
 */
getBidderListLengthLimit(): number => consts(txPallets.auction, chainConstants.biddersListLengthLimit)

/**
 * @name getMaxAuctionDelay
 * @summary Maximum amount of blocks between the current one and the start block of an auction.
 * @returns Number.
 */
getMaxAuctionDelay(): number => consts(txPallets.auction, chainConstants.maxAuctionDelay)

/**
 * @name getMinAuctionDuration
 * @summary Minimum amount of blocks permitted for an auction's length.
 * @returns Number.
 */
getMinAuctionDuration(): number => consts(txPallets.auction, chainConstants.minAuctionDuration)

/**
 * @name getMaxAuctionDuration
 * @summary Maximum amount of blocks permitted for an auction's length.
 * @returns Number.
 */
getMaxAuctionDuration(): number => consts(txPallets.auction, chainConstants.maxAuctionDuration)

/**
 * @name getParallelAuctionLimit
 * @summary Maximum amount of auctions that can be active at the same time.
 * @returns Number.
 */
getParallelAuctionLimit(): number => consts(txPallets.auction, chainConstants.parallelAuctionLimit)

Storage

3 storage getters will be implemented for the auction pallet.

export enum txPallets {
  ...
  auction = "auction",
}

export enum chainQuery {
  ...
  // auction
  auctions = "auctions"
  deadlines = "deadlines"
  claims = "claims"
}

type Bidder = {
  bidder: string
  amount: BalanceType
  amountRounded: number
}

type AuctionDataType = {
  creator: string
  startBlockId: number
  startBlockTimestamp: Date
  endBlockId: number
  endBlockTimestamp: Date
  startPrice: BalanceType
  startPriceRounded: number
  buyItPrice?: BalanceType
  buyItPriceRounded?: number
  bidders: Bidder[]
  marketplaceId: number
  isExtended: boolean
}

type DeadlineDataType = {
  blockId: string
  timestamp: Date
}

type ClaimsDataType = {
  claims: string
  claimsRounded: number
}

/**
 * @name getAuctionData
 * @summary       Provides the data related to an auction.
 * @param nftId   The ID of the auctionned NFT.
 * @returns           A JSON object with the auction data.
 */
getAuctionData(
    nftId: number,
): Promise<AuctionDataType | null> => query(txPallets.auction, chainQuery.auctions, [nftId])

/**
 * @name getAuctionDeadline
 * @summary       Provides the data related to an auction ending date: blockId and timestamp.
 * @param nftId   The ID of the auctionned NFT.
 * @returns Number.
 */
getAuctionDeadline(
    nftId: number,
): Promise<DeadlineDataType | null> => query(txPallets.auction, chainQuery.auctions, [nftId])

/**
 * @name getClaims
 * @summary         Bids balance claimable after an auction ends.
 * @param address   The bidder address.
 * @returns Number.
 */
getClaims(
    address: string,
): Promise<ClaimsDataType | null> => query(txPallets.auction, chainQuery.claims, [address])

Schema

The Indexer schema for the new AuctionEntity is detailed here below. It introduces a new type Bidder type that contains bidder data: address and bid amount.

type Bidder @jsonField {
  bidder: String!
  amount: String!
  amountRounded: Float!
}

type AuctionEntity @entity {
  id: ID!
  nftId: String!
  marketplaceId: String!
  creator: String! @index
  startPrice: String!
  startPriceRounded: Float!
  buyItPrice: String,
  buyItPriceRounded: Float
  startBlockId: String!
  endBlockId: String!
  isCompleted: Boolean!
  isEndingPeriod: Boolean!
  isExtendedPeriod: Boolean!
  bidders: [Bidder]
  nbBids: Int
  nbBidders: Int
  lastBidAmount: String
  lastBidAmountRounded: Float
  timestampCreate: Date! @index
  timestampStart: Date! @index
  timestampEnd: Date! @index
  timestampLastBid: Date
  timestampCancelled: Date
}

Linking upgrades

The integration of the auction pallet introduces new links to existing entities: the NftEntity and the MarketplaceEntity.

type NftEntity @entity {
  ...
  listedForSale: Boolean!   ⚠️ Breaking change: This field is deprecated, it does not exist on the chain anymore
  isListed: Boolean!        👈 The new version of the previous 'listedForSale' field
                            Default value: false
                            On AuctionCreated event: isListed = true
                            On AuctionCancelled event: isListed = false
                            On AuctionCompleted event: isListed = false
                            
  typeOfListing: String     👈 A new field to detailed the listing type: 'sale' or 'auction'
                            Default value: null
                            On AuctionCreated event: typeOfListing = 'auction'
                            On AuctionCancelled event: typeOfListing = null
                            On AuctionCompleted event: typeOfListing = null
                            
  auction: AuctionEntity    On AuctionCreated event: auction is loaded
                            On AuctionCancelled event: auctions = null
                            On AuctionCompleted event: auctions = null

  owner: String @index      👈 This is an already existing field
                            On AuctionCompleted event: owner = new_owner
  
}


type MarketplaceEntity @entity {
  ...        
  auctions: [AuctionEntity]   On AuctionCreated event: push new AuctionEntity
                              On AuctionCancelled event: remove AuctionEntity
                              On AuctionCompleted event: remove AuctionEntity
}

type MarketplaceEntity @entity {
  ...        
  auctions: [AuctionEntity]   On AuctionCreated event: push new AuctionEntity
                              On AuctionCancelled event: remove AuctionEntity
                              On AuctionCompleted event: remove AuctionEntity
}

New NFT operations

The auction pallet introduces 7 new NFT operations. The NftOperationEntity remains the same and the fulfilled fields for each new operation are listed below.

• createAuction
  typeOfTransaction='createAuction', marketplaceId

• cancelAuction
  typeOfTransaction='cancelAuction'

• completeAuction
  typeOfTransaction='completeAuction', marketplaceId, to, price, priceRounded, marketplaceCut, marketplaceCutRounded, royaltyCut, royaltyCutRounded

• addBid
  typeOfTransaction='addBid', price, priceRounded

• removeBid
  typeOfTransaction='removeBid'

• updateBid
  typeOfTransaction='updateBid', price, priceRounded

• auctionBuyItNow
  typeOfTransaction='auctionBuyItNow', marketplaceId, to, price, priceRounded, marketplaceCut, marketplaceCutRounded, royaltyCut, royaltyCutRounded