Skip to main content

ExchangeHandlerFacet

View Source: contracts/protocol/facets/ExchangeHandlerFacet.sol

↗ Extends: IBosonExchangeHandler, BuyerBase, DisputeBase

ExchangeHandlerFacet

Handles exchanges associated with offers within the protocol.

Functions​

initialize​

Initializes facet.
This function is callable only once.

function initialize() 
public
onlyUnInitialized

commitToOffer​

Commits to an offer (first step of an exchange).
Emits a BuyerCommitted event if successful.
Issues a voucher to the buyer address.
Reverts if:
- The exchanges region of protocol is paused
- The buyers region of protocol is paused
- OfferId is invalid
- Offer has been voided
- Offer has expired
- Offer is not yet available for commits
- Offer's quantity available is zero
- Buyer address is zero
- Buyer account is inactive
- Buyer is token-gated (conditional commit requirements not met or already used)
- Offer price is in native token and caller does not send enough
- Offer price is in some ERC20 token and caller also sends native currency
- Contract at token address does not support ERC20 function transferFrom
- Calling transferFrom on token fails for some reason (e.g. protocol is not approved to transfer)
- Received ERC20 token amount differs from the expected value
- Seller has less funds available than sellerDeposit

function commitToOffer(address payable _buyer,
 uint256 _offerId) 
external
payableexchangesNotPaused buyersNotPaused nonReentrant

Arguments

NameTypeDescription
_buyeraddress payablethe buyer's address (caller can commit on behalf of a buyer)
_offerIduint256the id of the offer to commit to

completeExchange​

Completes an exchange.
Emits an ExchangeCompleted event if successful.
Reverts if
- The exchanges region of protocol is paused
- Exchange does not exist
- Exchange is not in Redeemed state
- Caller is not buyer and offer dispute period has not elapsed

function completeExchange(uint256 _exchangeId) 
public
exchangesNotPaused nonReentrant

Arguments

NameTypeDescription
_exchangeIduint256the id of the exchange to complete

completeExchangeBatch​

Completes a batch of exchanges.
Emits an ExchangeCompleted event for every exchange if finalized to the Complete state.
Reverts if:
- The exchanges region of protocol is paused
- Number of exchanges exceeds maximum allowed number per batch
- For any exchange:
- Exchange does not exist
- Exchange is not in Redeemed state
- Caller is not buyer and offer dispute period has not elapsed

function completeExchangeBatch(uint256[] _exchangeIds) 
external
exchangesNotPaused

Arguments

NameTypeDescription
_exchangeIdsuint256[]the array of exchanges ids

revokeVoucher​

Revokes a voucher.
Emits a VoucherRevoked event if successful.
Reverts if
- The exchanges region of protocol is paused
- Exchange does not exist
- Exchange is not in Committed state
- Caller is not seller's operator

function revokeVoucher(uint256 _exchangeId) 
external
exchangesNotPaused nonReentrant

Arguments

NameTypeDescription
_exchangeIduint256the id of the exchange

cancelVoucher​

Cancels a voucher.
Emits a VoucherCanceled event if successful.
Reverts if
- The exchanges region of protocol is paused
- Exchange does not exist
- Exchange is not in Committed state
- Caller does not own voucher

function cancelVoucher(uint256 _exchangeId) 
external
exchangesNotPaused nonReentrant

Arguments

NameTypeDescription
_exchangeIduint256the id of the exchange

expireVoucher​

Expires a voucher.
Emits a VoucherExpired event if successful.
Reverts if
- The exchanges region of protocol is paused
- Exchange does not exist
- Exchange is not in Committed state
- Redemption period has not yet elapsed

function expireVoucher(uint256 _exchangeId) 
external
exchangesNotPaused nonReentrant

Arguments

NameTypeDescription
_exchangeIduint256the id of the exchange

extendVoucher​

Extends a Voucher's validity period.
Emits a VoucherExtended event if successful.
Reverts if
- The exchanges region of protocol is paused
- Exchange does not exist
- Exchange is not in Committed state
- Caller is not seller's operator
- New date is not later than the current one

function extendVoucher(uint256 _exchangeId,
 uint256 _validUntilDate) 
external
exchangesNotPaused nonReentrant

Arguments

NameTypeDescription
_exchangeIduint256the id of the exchange
_validUntilDateuint256the new voucher expiry date

redeemVoucher​

Redeems a voucher.
Emits a VoucherRedeemed event if successful.
Reverts if
- The exchanges region of protocol is paused
- Exchange does not exist
- Exchange is not in committed state
- Caller does not own voucher
- Current time is prior to offer.voucherRedeemableFromDate
- Current time is after voucher.validUntilDate

function redeemVoucher(uint256 _exchangeId) 
external
exchangesNotPaused nonReentrant

Arguments

NameTypeDescription
_exchangeIduint256the id of the exchange

onVoucherTransferred​

Informs protocol of new buyer associated with an exchange.
Emits a VoucherTransferred event if successful.
Reverts if
- The buyers region of protocol is paused
- Caller is not a clone address associated with the seller
- Exchange does not exist
- Exchange is not in Committed state
- Voucher has expired
- New buyer's existing account is deactivated

function onVoucherTransferred(uint256 _exchangeId,
 address payable _newBuyer) 
external
buyersNotPaused nonReentrant

Arguments

NameTypeDescription
_exchangeIduint256the id of the exchange
_newBuyeraddress payablethe address of the new buyer

isExchangeFinalized​

Checks if the given exchange in a finalized state.
Returns true if
- Exchange state is Revoked, Canceled, or Completed
- Exchange is disputed and dispute state is Retracted, Resolved, Decided or Refused

function isExchangeFinalized(uint256 _exchangeId) 
public
view
returns(bool exists, bool isFinalized)

Arguments

NameTypeDescription
_exchangeIduint256the id of the exchange to check

Returns

NameTypeDescription
existsbooltrue if the exchange exists
isFinalizedbooltrue if the exchange is finalized

getExchange​

Gets the details about a given exchange.

function getExchange(uint256 _exchangeId) 
external
view
returns(bool exists,
 Exchange memory exchange,
 Voucher memory voucher)

Arguments

NameTypeDescription
_exchangeIduint256the id of the exchange to check

Returns

NameTypeDescription
existsbooltrue if the exchange exists
exchangeBosonTypes.Exchangethe exchange details. See {BosonTypes.Exchange}
voucherBosonTypes.Voucherthe voucher details. See {BosonTypes.Voucher}

getExchangeState​

Gets the state of a given exchange.

function getExchangeState(uint256 _exchangeId) 
external
view
returns(bool exists, enum BosonTypes.ExchangeState state)

Arguments

NameTypeDescription
_exchangeIduint256the id of the exchange to check

Returns

BosonTypes.ExchangeState

getNextExchangeId​

Gets the id that will be assigned to the next exchange.Does not increment the counter.

function getNextExchangeId() 
external
view
returns(uint256 nextExchangeId)

Returns

NameTypeDescription
nextExchangeIduint256the next exchange id

finalizeExchange​

Transitions exchange to a "finalized" state
Target state must be Completed, Revoked, or Canceled.
Sets finalizedDate and releases funds associated with the exchange

function finalizeExchange(struct BosonTypes.Exchange _exchange,
 enum BosonTypes.ExchangeState _targetState) 
internal

Arguments

NameTypeDescription
_exchangeBosonTypes.Exchangethe exchange to finalize
_targetStateenum BosonTypes.ExchangeStatethe target state to which the exchange should be transitioned

revokeVoucherInternal​

Revokes a voucher.
Emits a VoucherRevoked event if successful.
Reverts if
- Exchange is not in Committed state

function revokeVoucherInternal(struct BosonTypes.Exchange exchange) 
internal

Arguments

NameTypeDescription
exchangeBosonTypes.Exchangethe exchange to revoke

burnVoucher​

Burns the voucher associated with a given exchange.
Emits ERC721 Transfer event in call stack if successful.

function burnVoucher(struct BosonTypes.Exchange _exchange) 
internal

Arguments

NameTypeDescription
_exchangeBosonTypes.Exchangethe pointer to the exchange for which voucher should be burned

transferTwins​

Transfers bundled twins associated with an exchange to the buyer.
Emits ERC20 Transfer, ERC721 Transfer, or ERC1155 TransferSingle events in call stack if successful.
Reverts if
- A twin transfer fails

function transferTwins(struct BosonTypes.Exchange _exchange,
 struct BosonTypes.Voucher _voucher) 
internal

returns(bool shouldBurnVoucher)

Arguments

NameTypeDescription
_exchangeBosonTypes.Exchangethe exchange for which twins should be transferred
_voucherBosonTypes.Voucher

Returns

NameTypeDescription
shouldBurnVoucherboolwhether or not the voucher should be burned

getValidBuyer​

Checks if buyer exists for buyer address. If not, account is created for buyer address.
Reverts if buyer exists but is inactive.

function getValidBuyer(address payable _buyer) 
internal

returns(uint256 buyerId)

Arguments

NameTypeDescription
_buyeraddress payablethe buyer address to check

Returns

NameTypeDescription
buyerIduint256the buyer id

authorizeCommit​

Authorizes the potential buyer to commit to an offer
Anyone can commit to an unconditional offer, and no state change occurs here.
However, if the offer is conditional, we must:
- determine if the buyer is allowed to commit
- increment the count of commits to the group made by the buyer address
Conditions are associated with offers via groups. One or more offers can be
placed in a group and a single condition applied to the entire group. Thus:
- If a buyer commits to one offer in a group with a condition, it counts
against the buyer's allowable commits for the whole group.
- If the buyer has already committed the maximum number of times for the
group, the buyer can't commit again to any of its offers.
The buyer is allowed to commit if no group or condition is set for this offer.

function authorizeCommit(address _buyer,
 struct BosonTypes.Offer _offer,
 uint256 exchangeId) 
internal

returns(bool)

Arguments

NameTypeDescription
_buyeraddressbuyer address
_offerBosonTypes.Offerthe offer
exchangeIduint256the exchange id

Returns

bool

holdsThreshold​

Checks if the buyer has the required balance of the conditional token.

function holdsThreshold(address _buyer,
 struct BosonTypes.Condition _condition) 
internal
view
returns(bool)

Arguments

NameTypeDescription
_buyeraddressaddress of potential buyer
_conditionBosonTypes.Conditionthe condition to be evaluated

Returns

bool

holdsSpecificToken​

Checks if the buyer own a specific non-fungible token id.

function holdsSpecificToken(address _buyer,
 struct BosonTypes.Condition _condition) 
internal
view
returns(bool)

Arguments

NameTypeDescription
_buyeraddressaddress of potential buyer
_conditionBosonTypes.Conditionthe condition to be evaluated

Returns

bool

getReceipt​

Gets exchange receipt.
Reverts if:
- Exchange is not in a final state
- Exchange id is invalid

function getReceipt(uint256 _exchangeId) 
external
view
returns(Receipt memory receipt)

Arguments

NameTypeDescription
_exchangeIduint256the exchange id

Returns

NameTypeDescription
receiptBosonTypes.Receiptthe receipt for the exchange. See {BosonTypes.Receipt}