Skip to main content

IBosonExchangeHandler

View Source: contracts/interfaces/handlers/IBosonExchangeHandler.sol

↗ Extends: IBosonExchangeEvents, IBosonFundsLibEvents, IBosonTwinEvents

IBosonExchangeHandler

Handles exchanges associated with offers within the protocol.
The ERC-165 identifier for this interface is: 0xf34a48fa

Functions

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
payable

Arguments

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

commitToConditionalOffer

Commits to an conditional 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
- 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
- Condition has a range and the token id is not within the range

function commitToConditionalOffer(address payable _buyer,
uint256 _offerId,
uint256 _tokenId)
external
payable

Arguments

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

commitToPreMintedOffer

Commits to a preminted offer (first step of an exchange).
Emits a BuyerCommitted event if successful.
Reverts if:
- The exchanges region of protocol is paused
- The buyers region of protocol is paused
- Caller is not the voucher contract, owned by the seller
- Exchange exists already
- Offer has been voided
- Offer has expired
- Offer is not yet available for commits
- Buyer account is inactive
- Buyer is token-gated (conditional commit requirements not met or already used)
- Buyer is token-gated and condition has a range.
- Seller has less funds available than sellerDeposit and price

function commitToPreMintedOffer(address payable _buyer,
uint256 _offerId,
uint256 _exchangeId)
external

Arguments

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

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) 
external

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
- 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

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 assistant

function revokeVoucher(uint256 _exchangeId) 
external

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

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

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 assistant
- New date is not later than the current one

function extendVoucher(uint256 _exchangeId,
uint256 _validUntilDate)
external

Arguments

NameTypeDescription
_exchangeIduint256the id of the exchange
_validUntilDateuint256the new voucher expiry date

redeemVoucher

Redeems a voucher.
Emits a VoucherRedeemed event if successful.
Emits TwinTransferred if twin transfer was successfull
Emits TwinTransferFailed if twin transfer failed
Emits TwinTransferSkipped if twin transfer was skipped when the number of twins is too high
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

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

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) 
external
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,
BosonTypes.Exchange memory exchange,
BosonTypes.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

getReceipt

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

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

Arguments

NameTypeDescription
_exchangeIduint256the exchange id

Returns

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

isEligibleToCommit

Tells if buyer is elligible to commit to conditional
Returns the eligibility status, the number of used commits and the maximal number of commits to the conditional offer.
Unconditional offers do not have maximal number of commits, so the returned value will always be 0.
This method does not check if the timestamp is within the offer's validity period or if the quantity available is greater than 0.
N.B. Unmined transaction might affect the eligibility status.
Reverts if:
- The offer does not exist
- The offer is voided
- The external call to condition contract reverts

function isEligibleToCommit(address _buyer,
uint256 _offerId,
uint256 _tokenId)
external
view
returns(bool isEligible,
uint256 commitCount,
uint256 maxCommits)

Arguments

NameTypeDescription
_buyeraddressbuyer address
_offerIduint256the id of the offer
_tokenIduint256the id of conditional token

Returns

NameTypeDescription
isEligiblebooltrue if buyer is eligible to commit
commitCountuint256,the current number of commits to the conditional offer
maxCommitsuint256the maximal number of commits to the conditional offer