Interaction Overview

This page provides an overview of interacting with the Axis protocol.

Auction House

The Auction House acts as the main integration point across the lifecycle of an auction lot: creation, purchase/bid and settlement.

It is designed to support different combinations of auction modules, derivative modules and callbacks contracts, and so provides mechanisms to pass required data to the respective auction module, derivative module or callbacks contract as necessary.

Auction Creation

• Routing parameters (IAuctionHouse.RoutingParams)

  • The routing parameters define the configuration outside of the core auction logic. This includes quote and base tokens, callbacks and derivatives.
  • Auction Configuration
    • The auction type is defined in the routing parameters, and determines which auction module is assigned to the auction lot.
  • Derivative Configuration
    • When a derivative module is specified for an auction, the derivative module is likely to require certain parameters.
    • The format of the parameters is set by the individual derivative module.
    • The encoded parameters are set on IAuctionHouse.RoutingParams.derivativeParams.
    • The Using Derivative Guide provides an example of this.
  • Callbacks
    • Some callbacks contracts (such as allowlists) will require configuration parameters to be passed at the time of auction creation.
    • The parameters should be encoded as bytes and set on IAuctionHouse.RoutingParams.callbackData.
    • The Using Callbacks Guide provides an example of this.

• Auction parameters (IAuction.AuctionParams)

  • The auction parameters define the configuration of the auction itself, including the start, duration and capacity.

  • Beyond the standard parameters specified by IAuction.AuctionParams, a specific auction module will require the caller to provide certain additional parameters.

  • The format of the additional parameters is set by the individual auction module. For example, Encrypted Marginal Price requires the following struct to be abi-encoded:

      struct AuctionDataParams {
          uint256 minPrice;
          uint24 minFillPercent;
          uint256 minBidSize;
          Point publicKey;
      }

  • The encoded parameters are set on IAuction.AuctionParams.implParams, which is then passed to the auction module.

  • The Create Auction Guide provides an example of this.

• Auction information (string)

  • An IPFS hash is provided as the third argument to the creation function. This IPFS hash is then emitted with the AuctionCreated event, allowing blockchain indexers (such as a subgraph) to link the auction's lot id with the IPFS hash.

Bid

• Bid parameters (IBatchAuctionHouse.BidParams)
  • As with auction creation, there are standard parameters required for all bids.
  • Depending on the auction type specified at the time of creation, there may be additional parameters required by the auction module. The format of the additional parameters is specified by the auction module itself.
  • The encoded parameters are set on IBatchAuctionHouse.BidParams.auctionData, which is then passed to the auction module.
• Callback data (bytes)
  • The second parameter to the bid() function is encoded callback data.
  • If the auction has a callbacks contract that requires additional parameters to process the bid (such as a Merkle proof), they can be encoded in the format specified by the callbacks contract and passed in as this parameter.
  • The Using Callbacks Guide provides an example of this.

Purchase

• Purchase parameters (IAtomicAuctionHouse.PurchaseParams)
  • As with auction creation, there are standard parameters required for all purchases.
  • Depending on the auction type specified at the time of creation, there may be additional parameters required by the auction module. The format of the additional parameters is specified by the auction module itself.
  • The encoded parameters are set on IAtomicAuctionHouse.PurchaseParams.auctionData, which is then passed to the auction module.
• Callback data (bytes)
  • The second parameter to the purchase() function is encoded callback data.
  • If the auction has a callbacks contract that requires additional parameters to process the purchase (such as a Merkle proof), they can be encoded in the format specified by the callbacks contract and passed in as this parameter.
  • The Using Callbacks Guide provides an example of this.

Settlement

• Lot ID
  • The lot id is passed as a parameter to tell the AuctionHouse which auction to settle.
• Number of bids
  • If an auction has a large number of bids, settling the auction may not be possible in a single batch. This parameter allows the caller to settle in smaller batches.
• Callback data
  • If the auction has a callbacks contract that requires additional parameters to settle the auction, they can be encoded in the format specified by the callbacks contract and passed in as this parameter.
  • The Using Callbacks Guide provides an example of this.

Auction Modules

While most interactions with an auction module will be through the AuctionHouse, auction modules are able to define functions that provide additional functionality.

For example, the encrypted marginal price auction module defines a decryptAndSortBids() function that can be called to decrypt and sort bids in a queue - a pre-requisite for settlement.

Derivative Modules

During purchase or settlement (depending on the auction type), the Auction House will be responsible for interacting with the derivative module (if enabled) for deploying and minting derivative tokens.

Following that, the holders of derivative tokens will afterwards interact with the derivative module directly in order to redeem their derivative for the underlying token.

Similar to auction modules, derivative modules can define functions for additional functionality.

Callbacks

The configured callbacks contract for an auction (if enabled) will commonly be called by the Auction House, as covered above.

However, callbacks contract developers are free to implement additional functions. Some examples:

• An allowlist contract may enable the auction seller to set a new Merkle proof after the auction lot has been registered
• A direct-to-liquidity contract may require additional configuration and expose that functionality through a function.