Skip to main content

IBosonVoucher

View Source: contracts/interfaces/clients/IBosonVoucher.sol

↗ Extends: IERC721Upgradeable, IERC721MetadataUpgradeable, IERC721ReceiverUpgradeable

IBosonVoucher

This is the interface for the Boson Protocol ERC-721 Voucher contract.
The ERC-165 identifier for this interface is: 0x5235dd2b

Structs​

Range​

struct Range {
  uint256 start,
  uint256 length,
  uint256 minted,
  uint256 lastBurnedTokenId,
  address owner
}

Functions​

issueVoucher​

Issues a voucher to a buyer.
Minted voucher supply is sent to the buyer.
Caller must have PROTOCOL role.

function issueVoucher(uint256 _tokenId,
 address _buyer) 
external

Arguments

NameTypeDescription
_tokenIduint256voucher token id corresponds to <<uint128(offerId)>>.<<uint128(exchangeId)>>
_buyeraddressthe buyer address

burnVoucher​

Burns a voucher.
Caller must have PROTOCOL role.

function burnVoucher(uint256 _tokenId) 
external

Arguments

NameTypeDescription
_tokenIduint256voucher token id corresponds to <<uint128(offerId)>>.<<uint128(exchangeId)>>

getSellerId​

Gets the seller id.

function getSellerId() 
external
view
returns(uint256)

Returns

uint256

transferOwnership​

Transfers ownership of the contract to a new account (newOwner).
Can only be called by the protocol. Change is done by calling updateSeller on the protocol.

function transferOwnership(address newOwner) 
external

Arguments

NameTypeDescription
newOwneraddressthe address to which ownership of the voucher contract will be transferred

contractURI​

Returns storefront-level metadata used by OpenSea.

function contractURI() 
external
view
returns(string)

Returns

string

setContractURI​

Sets new contract URI.
Can only be called by the owner or during the initialization.

function setContractURI(string _newContractURI) 
external

Arguments

NameTypeDescription
_newContractURIstringnew contract metadata URI

royaltyInfo​

Provides royalty info.
Called with the sale price to determine how much royalty is owed and to whom.

function royaltyInfo(uint256 _tokenId,
 uint256 _salePrice) 
external
view
returns(address receiver, uint256 royaltyAmount)

Arguments

NameTypeDescription
_tokenIduint256the voucher queried for royalty information
_salePriceuint256the sale price of the voucher specified by _tokenId

Returns

NameTypeDescription
receiveraddressaddress of who should be sent the royalty payment
royaltyAmountuint256the royalty payment amount for the given sale price

setRoyaltyPercentage​

Sets the royalty percentage.
Can only be called by the owner or during the initialization
Emits RoyaltyPercentageChanged if successful.
Reverts if:
- Caller is not the owner.
- _newRoyaltyPercentage is greater than max royalty percentage defined in the protocol

function setRoyaltyPercentage(uint256 _newRoyaltyPercentage) 
external

Arguments

NameTypeDescription
_newRoyaltyPercentageuint256fee in percentage. e.g. 500 = 5%

getRoyaltyPercentage​

Gets the royalty percentage.

function getRoyaltyPercentage() 
external
view
returns(uint256)

Returns

uint256

reserveRange​

Reserves a range of vouchers to be associated with an offer
Must happen prior to calling preMint
Caller must have PROTOCOL role.
Reverts if:
- Start id is not greater than zero for the first range
- Start id is not greater than the end id of the previous range for subsequent ranges
- Range length is zero
- Range length is too large, i.e., would cause an overflow
- Offer id is already associated with a range
- _to is not the contract address or the contract owner

function reserveRange(uint256 _offerId,
 uint256 _start,
 uint256 _length,
 address _to) 
external

Arguments

NameTypeDescription
_offerIduint256the id of the offer
_startuint256the first id of the token range
_lengthuint256the length of the range
_toaddressthe address to send the pre-minted vouchers to (contract address or contract owner)

preMint​

Pre-mints all or part of an offer's reserved vouchers.
For small offer quantities, this method may only need to be
called once.
But, if the range is large, e.g., 10k vouchers, block gas limit
could cause the transaction to fail. Thus, in order to support
a batched approach to pre-minting an offer's vouchers,
this method can be called multiple times, until the whole
range is minted.
A benefit to the batched approach is that the entire reserved
range for an offer need not be pre-minted at one time. A seller
could just mint batches periodically, controlling the amount
that are available on the market at any given time, e.g.,
creating a pre-minted offer with a validity period of one year,
causing the token range to be reserved, but only pre-minting
a certain amount monthly.
Caller must be contract owner (seller assistant address).
Reverts if:
- Offer id is not associated with a range
- Amount to mint is more than remaining un-minted in range
- Too many to mint in a single transaction, given current block gas limit

function preMint(uint256 _offerId,
 uint256 _amount) 
external

Arguments

NameTypeDescription
_offerIduint256the id of the offer
_amountuint256the amount to mint

burnPremintedVouchers​

Burn all or part of an offer's preminted vouchers.
If offer expires or it's voided, the seller can burn the preminted vouchers that were not transferred yet.
This way they will not show in seller's wallet and marketplaces anymore.
For small offer quantities, this method may only need to be
called once.
But, if the range is large, e.g., 10k vouchers, block gas limit
could cause the transaction to fail. Thus, in order to support
a batched approach to pre-minting an offer's vouchers,
this method can be called multiple times, until the whole
range is burned.
Caller must be contract owner (seller assistant address).
Reverts if:
- Offer id is not associated with a range
- Offer is not expired or voided
- There is nothing to burn

function burnPremintedVouchers(uint256 _offerId,
 uint256 _amount) 
external

Arguments

NameTypeDescription
_offerIduint256the id of the offer
_amountuint256amount to burn

getAvailablePreMints​

Gets the number of vouchers available to be pre-minted for an offer.

function getAvailablePreMints(uint256 _offerId) 
external
view
returns(uint256 count)

Arguments

NameTypeDescription
_offerIduint256the id of the offer

Returns

NameTypeDescription
countuint256the count of vouchers in reserved range available to be pre-minted

getRangeByOfferId​

Gets the range for an offer.

function getRangeByOfferId(uint256 _offerId) 
external
view
returns(Range memory range)

Arguments

NameTypeDescription
_offerIduint256the id of the offer

Returns

NameTypeDescription
rangeIBosonVoucher.Rangerange struct with information about range start, length and already minted tokens

callExternalContract​

Make a call to an external contract.
Reverts if:
- _to is zero address
- call to external contract fails
- caller is not the owner
- _to is a contract that represents some assets (all contracts that implement balanceOf method, including ERC20 and ERC721)

function callExternalContract(address _to,
 bytes _data) 
external
payable
returns(bytes)

Arguments

NameTypeDescription
_toaddressaddress of the contract to call
_databytesdata to pass to the external contract

Returns

bytes

setApprovalForAllToContract​

Set approval for all to the vouchers owned by this contract
Reverts if:
- _operator is zero address
- caller is not the owner
- _operator is this contract

function setApprovalForAllToContract(address _operator,
 bool _approved) 
external

Arguments

NameTypeDescription
_operatoraddressaddress of the operator to set approval for
_approvedbooltrue to approve the operator in question, false to revoke approval

withdrawToProtocol​

Withdraw funds from the contract to the protocol seller pool

function withdrawToProtocol(address[] _tokenList) 
external

Arguments

NameTypeDescription
_tokenListaddress[]list of tokens to withdraw, including native token (address(0))

Events​

ContractURIChanged​

event ContractURIChanged(string  contractURI)

Parameters

NameTypeDescription
contractURIstring

RoyaltyPercentageChanged​

event RoyaltyPercentageChanged(uint256  royaltyPercentage)

Parameters

NameTypeDescription
royaltyPercentageuint256

VoucherInitialized​

event VoucherInitialized(
 uint256 indexed sellerId
 uint256 indexed royaltyPercentage
 string indexed contractURI
)

Parameters

NameTypeDescription
sellerIduint256
royaltyPercentageuint256
contractURIstring

RangeReserved​

event RangeReserved(
 uint256 indexed offerId
 struct IBosonVoucher.Range  range
)

Parameters

NameTypeDescription
offerIduint256
rangeIBosonVoucher.Range

VouchersPreMinted​

event VouchersPreMinted(
 uint256 indexed offerId
 uint256  startId
 uint256  endId
)

Parameters

NameTypeDescription
offerIduint256
startIduint256
endIduint256