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(address payable _buyer, uint256 _offerId)
- commitToConditionalOffer(address payable _buyer, uint256 _offerId, uint256 _tokenId)
- commitToPreMintedOffer(address payable _buyer, uint256 _offerId, uint256 _exchangeId)
- completeExchange(uint256 _exchangeId)
- completeExchangeBatch(uint256[] _exchangeIds)
- revokeVoucher(uint256 _exchangeId)
- cancelVoucher(uint256 _exchangeId)
- expireVoucher(uint256 _exchangeId)
- extendVoucher(uint256 _exchangeId, uint256 _validUntilDate)
- redeemVoucher(uint256 _exchangeId)
- onVoucherTransferred(uint256 _exchangeId, address payable _newBuyer)
- isExchangeFinalized(uint256 _exchangeId)
- getExchange(uint256 _exchangeId)
- getExchangeState(uint256 _exchangeId)
- getNextExchangeId()
- getReceipt(uint256 _exchangeId)
- isEligibleToCommit(address _buyer, uint256 _offerId, uint256 _tokenId)
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
| Name | Type | Description |
|---|---|---|
| _buyer | address payable | the buyer's address (caller can commit on behalf of a buyer) |
| _offerId | uint256 | the 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
| Name | Type | Description |
|---|---|---|
| _buyer | address payable | the buyer's address (caller can commit on behalf of a buyer) |
| _offerId | uint256 | the id of the offer to commit to |
| _tokenId | uint256 | the 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
| Name | Type | Description |
|---|---|---|
| _buyer | address payable | the buyer's address (caller can commit on behalf of a buyer) |
| _offerId | uint256 | the id of the offer to commit to |
| _exchangeId | uint256 | the 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
| Name | Type | Description |
|---|---|---|
| _exchangeId | uint256 | the 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
| Name | Type | Description |
|---|---|---|
| _exchangeIds | uint256[] | 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
| Name | Type | Description |
|---|---|---|
| _exchangeId | uint256 | the 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
| Name | Type | Description |
|---|---|---|
| _exchangeId | uint256 | the 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
| Name | Type | Description |
|---|---|---|
| _exchangeId | uint256 | the 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
| Name | Type | Description |
|---|---|---|
| _exchangeId | uint256 | the id of the exchange |
| _validUntilDate | uint256 | the 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
| Name | Type | Description |
|---|---|---|
| _exchangeId | uint256 | the 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
| Name | Type | Description |
|---|---|---|
| _exchangeId | uint256 | the id of the exchange |
| _newBuyer | address payable | the 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
| Name | Type | Description |
|---|---|---|
| _exchangeId | uint256 | the id of the exchange to check |
Returns
| Name | Type | Description |
|---|---|---|
| exists | bool | true if the exchange exists |
| isFinalized | bool | true 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
| Name | Type | Description |
|---|---|---|
| _exchangeId | uint256 | the id of the exchange to check |
Returns
| Name | Type | Description |
|---|---|---|
| exists | bool | true if the exchange exists |
| exchange | BosonTypes.Exchange | the exchange details. See {BosonTypes.Exchange} |
| voucher | BosonTypes.Voucher | the 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
| Name | Type | Description |
|---|---|---|
| _exchangeId | uint256 | the 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
| Name | Type | Description |
|---|---|---|
| nextExchangeId | uint256 | the 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
| Name | Type | Description |
|---|---|---|
| _exchangeId | uint256 | the exchange id |
Returns
| Name | Type | Description |
|---|---|---|
| receipt | BosonTypes.Receipt | the 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
| Name | Type | Description |
|---|---|---|
| _buyer | address | buyer address |
| _offerId | uint256 | the id of the offer |
| _tokenId | uint256 | the id of conditional token |
Returns
| Name | Type | Description |
|---|---|---|
| isEligible | bool | true if buyer is eligible to commit |
| commitCount | uint256, | the current number of commits to the conditional offer |
| maxCommits | uint256 | the maximal number of commits to the conditional offer |