The PublicLock Interface
Methods​ DEFAULT_ADMIN_ROLE​ function DEFAULT_ADMIN_ROLE() external pure returns (bytes32 role) Copy Returns​ Name Type Description role bytes32 undefined
KEY_GRANTER_ROLE​ function KEY_GRANTER_ROLE() external pure returns (bytes32 role) Copy Returns​ Name Type Description role bytes32 undefined
LOCK_MANAGER_ROLE​ function LOCK_MANAGER_ROLE() external pure returns (bytes32 role) Copy Returns​ Name Type Description role bytes32 undefined
addKeyGranter​ function addKeyGranter(address account) external nonpayable Copy Parameters​ Name Type Description account address undefined
addLockManager​ function addLockManager(address account) external nonpayable Copy Parameters​ Name Type Description account address undefined
approve​ function approve(address to, uint256 tokenId) external nonpayable Copy Parameters​ Name Type Description to address undefined tokenId uint256 undefined
approveBeneficiary​ function approveBeneficiary(address _spender, uint256 _amount) external nonpayable returns (bool) Copy An ERC-20 style approval, allowing the spender to transfer funds directly from this lock.
Parameters​ Name Type Description _spender address address that can spend tokens belonging to the lock _amount uint256 amount of tokens that can be spent by the spender
Returns​ Name Type Description _0 bool undefined
balanceOf​ function balanceOf(address _owner) external view returns (uint256 balance) Copy Returns the number of NFTs in owner's account.
Parameters​ Name Type Description _owner address undefined
Returns​ Name Type Description balance uint256 undefined
beneficiary​ function beneficiary() external view returns (address) Copy =================================================================== Auto-generated getter functions from public state variables
Returns​ Name Type Description _0 address undefined
function burn(uint256 _tokenId) external nonpayable Copy Deactivate an existing keythe key will be expired and ownership records will be destroyed
Parameters​ Name Type Description _tokenId uint256 the id of token to burn
cancelAndRefund​ function cancelAndRefund(uint256 _tokenId) external nonpayable Copy allows the key manager to expire a given tokenId and send a refund to the keyOwner based on the amount of time remaining.
Parameters​ Name Type Description _tokenId uint256 The id of the key to cancel.
expirationDuration​ function expirationDuration() external view returns (uint256) Copy Returns​ Name Type Description _0 uint256 undefined
expireAndRefundFor​ function expireAndRefundFor(uint256 _tokenId, uint256 _amount) external nonpayable Copy Invoked by a Lock manager to expire the user's key and perform a refund and cancellation of the keyThrows if called by other than a Lock managerThrows if _keyOwner does not have a valid key
Parameters​ Name Type Description _tokenId uint256 The key id we wish to refund to _amount uint256 The amount to refund to the key-owner
function extend(uint256 _value, uint256 _tokenId, address _referrer, bytes _data) external payable Copy Extend functionThrows if lock is disabled or key does not exist for _recipient. Throws if _recipient == address(0).
Parameters​ Name Type Description _value uint256 the number of tokens to pay for this purchase >= the current keyPrice - any applicable discount (_value is ignored when using ETH) _tokenId uint256 the id of the key to extend _referrer address address of the user making the referral _data bytes arbitrary data populated by the front-end which initiated the sale
freeTrialLength​ function freeTrialLength() external view returns (uint256) Copy Returns​ Name Type Description _0 uint256 undefined
gasRefundValue​ function gasRefundValue() external view returns (uint256 _gasRefundValue) Copy _gasRefundValue price in wei or token in smallest price unit
Returns the value/rpice to be refunded to the sender on purchase
Returns​ Name Type Description _gasRefundValue uint256 undefined
getApproved​ function getApproved(uint256 _tokenId) external view returns (address operator) Copy Get the approved address for a single NFT
Throws if _tokenId is not a valid NFT.
Parameters​ Name Type Description _tokenId uint256 The NFT to find the approved address for
Returns​ Name Type Description operator address The approved address for this NFT, or the zero address if there is none
getCancelAndRefundValue​ function getCancelAndRefundValue(address _keyOwner) external view returns (uint256 refund) Copy Determines how much of a refund a key owner would receive if they issued
Parameters​ Name Type Description _keyOwner address The key owner to get the refund value for. a cancelAndRefund block.timestamp. Note that due to the time required to mine a tx, the actual refund amount will be lower than what the user reads from this call.
Returns​ Name Type Description refund uint256 undefined
getHasValidKey​ function getHasValidKey(address _user) external view returns (bool) Copy Checks if the user has a non-expired key.
Parameters​ Name Type Description _user address The address of the key owner
Returns​ Name Type Description _0 bool undefined
getRoleAdmin​ function getRoleAdmin(bytes32 role) external view returns (bytes32) Copy Innherited from Open Zeppelin AccessControl.sol
Parameters​ Name Type Description role bytes32 undefined
Returns​ Name Type Description _0 bytes32 undefined
getTransferFee​ function getTransferFee(uint256 _tokenId, uint256 _time) external view returns (uint256) Copy Determines how much of a fee would need to be paid in order to transfer to another account. This is pro-rated so the fee goes down overtime.
Throws if _tokenId does not have a valid key
Parameters​ Name Type Description _tokenId uint256 The id of the key check the transfer fee for. _time uint256 The amount of time to calculate the fee for.
Returns​ Name Type Description _0 uint256 The transfer fee in seconds.
grantKeys​ function grantKeys(address[] _recipients, uint256[] _expirationTimestamps, address[] _keyManagers) external nonpayable Copy Allows a Lock manager to give a collection of users a key with no charge. Each key may be assigned a different expiration date.
Throws if called by other than a Lock manager
Parameters​ Name Type Description _recipients address[] An array of receiving addresses _expirationTimestamps uint256[] An array of expiration Timestamps for the keys being granted _keyManagers address[] undefined
grantRole​ function grantRole(bytes32 role, address account) external nonpayable Copy Parameters​ Name Type Description role bytes32 undefined account address undefined
hasRole​ function hasRole(bytes32 role, address account) external view returns (bool) Copy Parameters​ Name Type Description role bytes32 undefined account address undefined
Returns​ Name Type Description _0 bool undefined
initialize​ function initialize(address _lockCreator, uint256 _expirationDuration, address _tokenAddress, uint256 _keyPrice, uint256 _maxNumberOfKeys, string _lockName) external nonpayable Copy Functions
Parameters​ Name Type Description _lockCreator address undefined _expirationDuration uint256 undefined _tokenAddress address undefined _keyPrice uint256 undefined _maxNumberOfKeys uint256 undefined _lockName string undefined
isApprovedForAll​ function isApprovedForAll(address _owner, address _operator) external view returns (bool) Copy Tells whether an operator is approved by a given keyManager
Parameters​ Name Type Description _owner address owner address which you want to query the approval of _operator address operator address which you want to query the approval of
Returns​ Name Type Description _0 bool bool whether the given operator is approved by the given owner
isKeyGranter​ function isKeyGranter(address account) external view returns (bool) Copy Parameters​ Name Type Description account address undefined
Returns​ Name Type Description _0 bool undefined
isLockManager​ function isLockManager(address account) external view returns (bool) Copy Parameters​ Name Type Description account address undefined
Returns​ Name Type Description _0 bool undefined
isOwner​ function isOwner(address account) external nonpayable returns (bool) Copy Parameters​ Name Type Description account address undefined
Returns​ Name Type Description _0 bool undefined
isValidKey​ function isValidKey(uint256 _tokenId) external view returns (bool) Copy Check if a certain key is validthis makes use of the onValidKeyHook if it is set
Parameters​ Name Type Description _tokenId uint256 the id of the key to check validity
Returns​ Name Type Description _0 bool undefined
keyExpirationTimestampFor​ function keyExpirationTimestampFor(uint256 _tokenId) external view returns (uint256 timestamp) Copy Returns the key's ExpirationTimestamp field for a given owner.Returns 0 if the owner has never owned a key for this lock
Parameters​ Name Type Description _tokenId uint256 the id of the key
Returns​ Name Type Description timestamp uint256 undefined
keyManagerOf​ function keyManagerOf(uint256) external view returns (address) Copy Parameters​ Name Type Description _0 uint256 undefined
Returns​ Name Type Description _0 address undefined
keyPrice​ function keyPrice() external view returns (uint256) Copy Returns​ Name Type Description _0 uint256 undefined
maxKeysPerAddress​ function maxKeysPerAddress() external view returns (uint256) Copy Returns​ Name Type Description _0 uint256 the maximum number of key allowed for a single address
maxNumberOfKeys​ function maxNumberOfKeys() external view returns (uint256) Copy Returns​ Name Type Description _0 uint256 undefined
mergeKeys​ function mergeKeys(uint256 _tokenIdFrom, uint256 _tokenIdTo, uint256 _amount) external nonpayable Copy Merge existing keys
Parameters​ Name Type Description _tokenIdFrom uint256 the id of the token to substract time from _tokenIdTo uint256 the id of the destination token to add time _amount uint256 the amount of time to transfer (in seconds)
migrate​ function migrate(bytes _calldata) external nonpayable Copy Migrate data from the previous single owner => key mapping to the new data structure w multiple tokens.
when all record schemas are sucessfully upgraded, this function will update the schemaVersion variable to the latest/current lock version
Parameters​ Name Type Description _calldata bytes an ABI-encoded representation of the params (v10: the number of records to migrate as uint)
function name() external view returns (string _name) Copy A descriptive name for a collection of NFTs in this contract
Returns​ Name Type Description _name string undefined
numberOfOwners​ function numberOfOwners() external view returns (uint256) Copy Public function which returns the total number of unique owners (both expired and valid). This may be larger than totalSupply.
Returns​ Name Type Description _0 uint256 undefined
onKeyCancelHook​ function onKeyCancelHook() external view returns (address) Copy Returns​ Name Type Description _0 address undefined
onKeyPurchaseHook​ function onKeyPurchaseHook() external view returns (address) Copy Returns​ Name Type Description _0 address undefined
onTokenURIHook​ function onTokenURIHook() external view returns (string) Copy Returns​ Name Type Description _0 string undefined
onValidKeyHook​ function onValidKeyHook() external view returns (bool) Copy Returns​ Name Type Description _0 bool undefined
function owner() external view returns (address) Copy owner() is provided as an helper to mimick the Ownable contract ABI. The Ownable logic is used by many 3rd party services to determine contract ownership - e.g. who is allowed to edit metadata on Opensea. This logic is NOT used internally by the Unlock Protocol and is made available only as a convenience helper.
Returns​ Name Type Description _0 address undefined
ownerOf​ function ownerOf(uint256 tokenId) external view returns (address _owner) Copy Returns the owner of the NFT specified by tokenId.
Parameters​ Name Type Description tokenId uint256 undefined
Returns​ Name Type Description _owner address undefined
publicLockVersion​ function publicLockVersion() external pure returns (uint16) Copy The version number of the current implementation on this network.
Returns​ Name Type Description _0 uint16 The current version number.
purchase​ function purchase(uint256[] _values, address[] _recipients, address[] _referrers, address[] _keyManagers, bytes[] _data) external payable Copy when called for an existing and non-expired key, the _keyManager param will be ignored
Purchase functionSetting _value to keyPrice exactly doubles as a security feature. That way if the lock owner increases the price while my transaction is pending I can't be charged more than I expected (only applicable to ERC-20 when more than keyPrice is approved for spending).
Parameters​ Name Type Description _values uint256[] array of tokens amount to pay for this purchase >= the current keyPrice - any applicable discount (_values is ignored when using ETH) _recipients address[] array of addresses of the recipients of the purchased key _referrers address[] array of addresses of the users making the referral _keyManagers address[] optional array of addresses to grant managing rights to a specific address on creation _data bytes[] array of arbitrary data populated by the front-end which initiated the sale
purchasePriceFor​ function purchasePriceFor(address _recipient, address _referrer, bytes _data) external view returns (uint256) Copy returns the minimum price paid for a purchase with these params.
this considers any discount from Unlock or the OnKeyPurchase hook.
Parameters​ Name Type Description _recipient address undefined _referrer address undefined _data bytes undefined
Returns​ Name Type Description _0 uint256 undefined
refundPenaltyBasisPoints​ function refundPenaltyBasisPoints() external view returns (uint256) Copy Returns​ Name Type Description _0 uint256 undefined
renewMembershipFor​ function renewMembershipFor(uint256 _tokenId, address _referrer) external nonpayable Copy Renew a given tokenonly works for non-free, expiring, ERC20 locks
Parameters​ Name Type Description _tokenId uint256 the ID fo the token to renew _referrer address the address of the person to be granted UDT
renounceLockManager​ function renounceLockManager() external nonpayable Copy renounceRole​ function renounceRole(bytes32 role, address account) external nonpayable Copy Parameters​ Name Type Description role bytes32 undefined account address undefined
revokeKeyGranter​ function revokeKeyGranter(address _granter) external nonpayable Copy Parameters​ Name Type Description _granter address undefined
revokeRole​ function revokeRole(bytes32 role, address account) external nonpayable Copy Parameters​ Name Type Description role bytes32 undefined account address undefined
safeTransferFrom​ function safeTransferFrom(address from, address to, uint256 tokenId) external nonpayable Copy Transfers a specific NFT (tokenId) from one account (from) to another (to). Requirements: - from, to cannot be zero. - tokenId must be owned by from. - If the caller is not from, it must be have been allowed to move this NFT by either {approve} or {setApprovalForAll}.
Parameters​ Name Type Description from address undefined to address undefined tokenId uint256 undefined
safeTransferFrom​ function safeTransferFrom(address from, address to, uint256 tokenId, bytes data) external nonpayable Copy Parameters​ Name Type Description from address undefined to address undefined tokenId uint256 undefined data bytes undefined
schemaVersion​ function schemaVersion() external view returns (uint256) Copy Returns the version number of the data schema currently used by the lockif this is different from publicLockVersion, then the ability to purchase, grant or extend keys is disabled.
will return 0 if no ;igration has ever been run
Returns​ Name Type Description _0 uint256 undefined
setApprovalForAll​ function setApprovalForAll(address _operator, bool _approved) external nonpayable Copy disabled when transfers are disabled
Sets or unsets the approval of a given operator An operator is allowed to transfer all tokens of the sender on their behalf
Parameters​ Name Type Description _operator address operator address to set the approval _approved bool representing the status of the approval to be set
setBaseTokenURI​ function setBaseTokenURI(string _baseTokenURI) external nonpayable Copy Allows a Lock manager to update the baseTokenURI for this Lock.
Throws if called by other than a Lock manager
Parameters​ Name Type Description _baseTokenURI string String representing the base of the URI for this lock.
setEventHooks​ function setEventHooks(address _onKeyPurchaseHook, address _onKeyCancelHook, address _onValidKeyHook, address _onTokenURIHook) external nonpayable Copy Allows a Lock manager to add or remove an event hook
Parameters​ Name Type Description _onKeyPurchaseHook address Hook called when the purchase function is called _onKeyCancelHook address Hook called when the internal _cancelAndRefund function is called _onValidKeyHook address undefined _onTokenURIHook address undefined
setExpirationDuration​ function setExpirationDuration(uint256 _newExpirationDuration) external nonpayable Copy A function to change the default duration of each key in the lockkeys previously bought are unaffected by this change (i.e. existing keys timestamps are not recalculated/updated)
Parameters​ Name Type Description _newExpirationDuration uint256 the new amount of time for each key purchased or type(uint).max for a non-expiring key
setGasRefundValue​ function setGasRefundValue(uint256 _gasRefundValue) external nonpayable Copy Set the value to be refunded to the sender on purchase
Parameters​ Name Type Description _gasRefundValue uint256 price in wei or token in smallest price unit
setKeyManagerOf​ function setKeyManagerOf(uint256 _tokenId, address _keyManager) external nonpayable Copy Update transfer and cancel rights for a given key
Parameters​ Name Type Description _tokenId uint256 The id of the key to assign rights for _keyManager address The address to assign the rights to for the given key
setMaxKeysPerAddress​ function setMaxKeysPerAddress(uint256 _maxKeysPerAddress) external nonpayable Copy Set the maximum number of keys a specific address can use
Parameters​ Name Type Description _maxKeysPerAddress uint256 the maximum amount of key a user can own
setMaxNumberOfKeys​ function setMaxNumberOfKeys(uint256 _maxNumberOfKeys) external nonpayable Copy Change the maximum number of keys the lock can edit
Parameters​ Name Type Description _maxNumberOfKeys uint256 uint the maximum number of keys
setOwner​ function setOwner(address account) external nonpayable Copy Parameters​ Name Type Description account address undefined
shareKey​ function shareKey(address _to, uint256 _tokenId, uint256 _timeShared) external nonpayable Copy Allows the key owner to safely share their key (parent key) by transferring a portion of the remaining time to a new key (child key).
Throws if key is not valid.Throws if _to is the zero addressEmit Transfer event
Parameters​ Name Type Description _to address The recipient of the shared key _tokenId uint256 the key to share _timeShared uint256 The amount of time shared checks if _to is a smart contract (code size > 0). If so, it calls onERC721Received on _to and throws if the return value is not bytes4(keccak256('onERC721Received(address,address,uint,bytes)')).
supportsInterface​ function supportsInterface(bytes4 interfaceId) external view returns (bool) Copy From ERC165.sol
Parameters​ Name Type Description interfaceId bytes4 undefined
Returns​ Name Type Description _0 bool undefined
function symbol() external view returns (string) Copy Gets the token symbol
Returns​ Name Type Description _0 string string representing the token symbol
tokenAddress​ function tokenAddress() external view returns (address) Copy Returns​ Name Type Description _0 address undefined
tokenByIndex​ function tokenByIndex(uint256 index) external view returns (uint256) Copy Parameters​ Name Type Description index uint256 undefined
Returns​ Name Type Description _0 uint256 undefined
tokenOfOwnerByIndex​ function tokenOfOwnerByIndex(address _owner, uint256 index) external view returns (uint256 tokenId) Copy Parameters​ Name Type Description _owner address undefined index uint256 undefined
Returns​ Name Type Description tokenId uint256 undefined
tokenURI​ function tokenURI(uint256 _tokenId) external view returns (string) Copy A distinct Uniform Resource Identifier (URI) for a given asset.
Throws if _tokenId is not a valid NFT. URIs are defined in RFC 3986. The URI may point to a JSON file that conforms to the "ERC721 Metadata JSON Schema". https://github.com/ethereum/EIPs/blob/master/EIPS/eip-721.md
Parameters​ Name Type Description _tokenId uint256 The tokenID we're inquiring about
Returns​ Name Type Description _0 string String representing the URI for the requested token
totalSupply​ function totalSupply() external view returns (uint256) Copy Returns​ Name Type Description _0 uint256 undefined
transfer​ function transfer(address _to, uint256 _value) external nonpayable returns (bool success) Copy An ERC-20 style transfer.
The typical use case would be to call this with _value 1, which is on par with calling transferFrom. If the user has more than expirationDuration time remaining this may use the shareKey function to send some but not all of the token.
Parameters​ Name Type Description _to address undefined _value uint256 sends a token with _value * expirationDuration (the amount of time remaining on a standard purchase).
Returns​ Name Type Description success bool undefined
transferFeeBasisPoints​ function transferFeeBasisPoints() external view returns (uint256) Copy Returns​ Name Type Description _0 uint256 undefined
transferFrom​ function transferFrom(address from, address to, uint256 tokenId) external nonpayable Copy Transfers a specific NFT (tokenId) from one account (from) to another (to). Requirements: - If the caller is not from, it must be approved to move this NFT by either {approve} or {setApprovalForAll}.
Parameters​ Name Type Description from address undefined to address undefined tokenId uint256 undefined
unlockProtocol​ function unlockProtocol() external view returns (address) Copy Returns​ Name Type Description _0 address undefined
updateBeneficiary​ function updateBeneficiary(address _beneficiary) external nonpayable Copy A function which lets a Lock manager update the beneficiary account, which receives funds on withdrawal.
Throws if called by other than a Lock manager or beneficiaryThrows if _beneficiary is address(0)
Parameters​ Name Type Description _beneficiary address The new address to set as the beneficiary
updateKeyPricing​ function updateKeyPricing(uint256 _keyPrice, address _tokenAddress) external nonpayable Copy A function which lets a Lock manager of the lock to change the price for future purchases.
Throws if called by other than a Lock managerThrows if lock has been disabledThrows if _tokenAddress is not a valid token
Parameters​ Name Type Description _keyPrice uint256 The new price to set for keys _tokenAddress address The address of the erc20 token to use for pricing the keys, or 0 to use ETH
updateLockName​ function updateLockName(string _lockName) external nonpayable Copy Allows a Lock manager to assign a descriptive name for this Lock.
Throws if called by other than a Lock manager
Parameters​ Name Type Description _lockName string The new name for the lock
updateLockSymbol​ function updateLockSymbol(string _lockSymbol) external nonpayable Copy Allows a Lock manager to assign a Symbol for this Lock.
Throws if called by other than a Lock manager
Parameters​ Name Type Description _lockSymbol string The new Symbol for the lock
updateRefundPenalty​ function updateRefundPenalty(uint256 _freeTrialLength, uint256 _refundPenaltyBasisPoints) external nonpayable Copy Allow a Lock manager to change the refund penalty.
Throws if called by other than a Lock manager
Parameters​ Name Type Description _freeTrialLength uint256 The new duration of free trials for this lock _refundPenaltyBasisPoints uint256 The new refund penaly in basis-points(bps)
updateSchemaVersion​ function updateSchemaVersion() external nonpayable Copy Set the schema version to the latestonly lock manager call call this
updateTransferFee​ function updateTransferFee(uint256 _transferFeeBasisPoints) external nonpayable Copy Allow a Lock manager to change the transfer fee.
Throws if called by other than a Lock manager
Parameters​ Name Type Description _transferFeeBasisPoints uint256 The new transfer fee in basis-points(bps). Ex: 200 bps = 2%
withdraw​ function withdraw(address _tokenAddress, uint256 _amount) external nonpayable Copy Called by a lock manager or beneficiary to withdraw all funds from the lock and send them to the beneficiary.Throws if called by other than a lock manager or beneficiary
Parameters​ Name Type Description _tokenAddress address specifies the token address to withdraw or 0 for ETH. This is usually the same as tokenAddress in MixinFunds. _amount uint256 specifies the max amount to withdraw, which may be reduced when considering the available balance. Set to 0 or MAX_UINT to withdraw everything. -- however be wary of draining funds as it breaks the cancelAndRefund and expireAndRefundFor use cases.