Price Discovery

Overview

Price discovery feature in Boson Protocol allows the Sellers to use a preferred price discovery mechanism for dynamic pricing of items. The protocol's price discovery interface is compatible with several well-established mechanisms that are either on-chain or off-chain, such as auctions, Automated Market Makers (AMMs) and order books.

In Boson Protocol, a Seller is offering items either in singular Offers (quantity = 1) or in multi-instance Offers (quantity > 1). Singular offers are the likeliest candidates for auctions and multi-instance offers are suitable for price discovery using bonding curves and such.

To use dynamic pricing, at the Offer creation the Seller chooses "price discovery" (instead of fixed price). The actual price discovery mechanism is chosen afterwards (a single offer can be plugged into multiple external price discovery mechanisms as long as they are not in conflict). Then, the buyer commits to buy the item,i.e. locking up their funds - note that in some cases the seller (or some other account) does it on the buyer's behalf. The options are as follows:

• ask: the Buyer commits or someone else commits on their behalf. The caller must provide the funds.
• bid: the Seller commits on Buyer's behalf. The Buyer must pre-approve the funds transfer, so the Buyer's funds get locked.
• wrapper: anyone can commit on Buyer's behalf. The buyer previously had to transfer the funds to the wrapper, so at the end, the Buyer's funds get locked, regardless of the caller.

See the details below.

In BosonTypes.sol contract, there are two important things to keep in mind with regards to price discovery:

• PriceType, which can be either Static or Discovery, and forms a part of the Offer struct;
• PriceDiscovery struct with the neccessary information about the price discovery, and is used whenever the commit is made to an offer using price discovery or also sequential commit:
  • price: the expected price of an item, denominated in the token of the exchange as per the offer. Note that it can be different than the actual price after discovery, in which case additional checks are made, depending on the particular flow, see below.
  • side: specifies which party is fulfulling the order: Ask (buyer), Bid (seller), Wrapper (anyone - already fulfilled by a wrapper contract).
  • priceDiscoveryContract: the address of the price discovery contract, external to the protocol.
  • conduit: the address of the contract that is approved to transfer funds and/or Boson rNFT voucher, external to the protocol.
  • priceDiscoveryData: additional data needed for the price discovery mechanism, sent to the priceDiscoveryContract.

For security reasons (note that priceDiscoveryContract is an external to the protocol and could in principle be malicious), the price discovery calls are made via a separate contract (see BosonPriceDiscovery client) that is outside of the protocol's diamond and thus has limited impact on Boson Protocol itself.

The support for price discovery was introduced by BPIP-4.

Steps

1. Seller creates an offer with specified pricing mechanism.
2. Seller pre-mints the rNFT vouchers. (3. optional - if Seller's deposit is larger than 0: the Seller must have sufficient funds for all these in the Seller pool at the commit time.) ... then the process depends on the specified mechanism, or rather the Side actually fulfilling the order.

Ask flow (buyer driven)

3. Seller transfers pre-minted vouchers to priceDiscoveryContract, along with corresponding data. Say, to an AMM contract with specified bonding curve.
4. Buyer approves Boson Protocol to transfer the exchange tokens.
5. Seller approves Boson Protocol to transfer the exchange tokens. This is needed to encumber the funds at the end, regardles if the seller has the tokens currently or not.
6. Buyer calls commitToPriceDiscoveryOffer with the data required for price discovery, then:
   • Boson Protocol forwards the call to Boson Price Discovery Client, which:
     • calls the external price discovery contract;
     • checks that the actual price is at most what was provided by the Buyer, and transfers it to Boson Protocol; if Buyer provided more than required, the surplus is returned (e.g. the price from discovery ended up lower than what Buyer estimated or was willing to pay);
     • assumes it received the Boson Voucher and approves Boson Protocol to transfer it.
   • Boson Protocol then:
     • checks that Boson Price Discovery Client owns the Voucher;
     • transfers the price from the Seller and puts it into escrow.

Bid flow (seller driven)

3. There is a bidding system, say, an off-chain auction, that the Seller choses.
4. Buyer approves the external price discovery contract to transfer the exchange tokens. Buyer here is the user who successfully participated in the above bidding.
5. Seller approves Boson Protocol to transfer the voucher.
6. Seller calls commitToPriceDiscoveryOffer with the data required for price discovery, then:
   • Boson Protocol transfers the voucher to itself
   • Boson Protocol forwards the call to Boson Price Discovery Client, which:
     • calls the external price discovery contract;
     • checks that the actual price is non-negative and at least what the Seller expected, and transfers it to Boson Protocol; the price here acts as the minimum of what the Seller is willing to accept.
   • Boson Protocol then puts the price into escrow.

Wrapper (e.g. on-chain auction)

3. There is a bidding system, say, an on-chain auction, that the Seller choses.
4. Seller wraps the rNFT voucher via the wrapper contract. This protects the original voucher by ensuring it can be used (esp. finalized) only via Boson Protocol.
5. Seller deposits the wrapped voucher in the price discovery mechanism (e.g. an on-chain auction).
6. Upon price discovery completion, the wrapped voucher is transferred to the winner (Buyer) and the price is transferred to the wrapper contract..
7. Buyer or Seller then calls commitToPriceDiscoveryOffer with the corresponding data required, in this case the wrapper contract with unwrapping instructions, then:
   • Boson Protocol forwards the call to Boson Price Discovery Client, which:
     • calls the price discovery contract - here, it is the wrapping contract;
     • checks that the actual price is exactly as expected, and transfers it to Boson Protocol.
   • Boson Protocol then puts the price into escrow.