The Lock Smart Contract has multiple capabilities:
Administrative: these are the functions which change ownership of the lock or change the address of the Unlock Protocol smart contract, as well as the maximum number of keys, their release mechanism (public, pre-validated, private) or their expiration (period, date or interval) and of course their price (including the mechanism used to set the price: fixed or variable). Finally, there is a method to withdraw funds from the lock contract itself.
Transferring key ownership: keys can be purchased from the lock smart contract itself or from another user who purchased one previously. Another element is that keys can be purchased on behalf of somebody else (this is important because this lets somebody pay gas fees on behalf of somebody else)
Changing key attributes: the keys have an expiration date which can be changed (for an earlier date by the lock owner) as well as data attributes which can be changed to something else.
The key is a struct which encapsulate data relative to an individual key. It has the following fields:
tokenId
( uint ): A unique identifier for each key on a given lock.
expirationTimestamp
( uint ): the timestamp at which the key is not considered valid anymore. The lock owner only can change this value, effectively expiring individual keys.
​
This is the address of the Unlock Protocol Contract. It is set upon creation of the Lock and will be used to invoke the Lock when recording key purchases and more.
The owner of the lock contract.
Addresses of key owners are stored in an array.
The account which will receive funds on withdrawal.
The denominator component for values specified in basis points.
Duration in seconds for which the keys are valid after creation.
price in wei of the next key.
Max number of keys sold.
The token-type that this Lock is priced in. If 0, then use ETH, else this is an ERC20 token address.
Used to disable payable functions when deprecating an old lock
keccak256("IUnlockEventHooks_keySold")
keccak256("IUnlockEventHooks_keyCancel")
A descriptive name for a collection of NFTs in this contract. Defaults to "Unlock-Protocol" but is settable by lock owner.
A mapping of type address => uint
which stores a nonce per user to use for signed messages.
CancelAndRefund will return funds based on time remaining minus this penalty. // This is calculated as proRatedRefund * refundPenaltyBasisPoints / BASIS_POINTS_DEN
.
The typehash per the EIP-712 standard (keccak256('cancelAndRefundFor(address _keyOwner)'))
The fee relative to keyPrice to charge when transfering a Key to another account. This is calculated as keyPrice * transferFeeBasisPoints / BASIS_POINTS_DEN
.
​
Only allows a function to be called once.
Throws if called by any account other than the lock owner.
Only allow usage when contract is Alive.
Only allows usage by a caller with the LockManager role.
Ensure that the Lock has not sold all of its keys.
Throws if called by any account other than the owner
or the beneficiary
.
Ensures that an owner currently owns or has owned a key in the past.
Ensures that an owner has a valid key.
Ensures that a key has an owner..
Ensure that the caller owns the key.
Ensure that the caller has a key or that the caller has been approved for ownership of that key
Validates an off-chain approval signature. If valid the nonce is consumed, else revert.
The version number of the current implementation on this network
Called by owner to withdraw all funds from the lock and send them to the beneficiary
Parameters: address _tokenAddress
, uint _amount
A function which lets the owner of the lock change the pricing for future purchases. This consists of 2 parts: The token address and the price in the given token. In order to set the token to ETH, use 0 for the token Address.
Parameters: uint _keyPrice
, address _tokenAddress
A function which lets the owner of the lock update the beneficiary account, which receives funds on withdrawal.
Parameters: address _beneficiary
Determines how much of a fee a key owner would need to pay in order to transfer the key to another account. This is pro-rated so the fee goes down over time
Parameters: address owner
, uint _time
Allow the Lock owner to change the transfer fee.
Parameters: uint _transferFeeBasisPoints
Returns the _totalSupply
data field
The number of NFTs owned by _owner
, either 0 or 1..
Parameters: address _owner
Returns the owner of the NFT specified by tokenId
.
Parameters: uint256 tokenId
This approves _approved to get ownership of _tokenId.
Parameters: address _approved
, uint256 tokenId
Will return the approved recipient for a key, if any.
Parameters: uint256 tokenId
Sets or unsets the approval of a given operator. An operator is allowed to transfer all tokens of the sender on their behalf
Parameters: address _to
, bool _approved
Tells whether an operator is approved by a given owner
Parameters: address owner
, address operator
Parameters: address from
, address to
, uint256 tokenId
Transfers the ownership of an NFT from one address to another address. This works identically to the other function with an extra data parameter, except this function just sets data to ''.
Parameters: address from
, address to
, uint256 tokenId
Parameters: address _from
, address _to
, uint256 _tokenId,
bytes memory _data
Transfers the ownership of an NFT from one address to another address. When transfer is complete, this functions checks if _to
is a smart contract (code size > 0). If so, it calls onERC721Received
on _to
and throws if the return value is notbytes4(keccak256('onERC721Received(address,address,uint,bytes)'))
.
Enumerate NFTs assigned to an owner
Parameters: address _owner
, uint256 _index
Enumerate valid NFTs
Parameters: uint _index
returns the total number of unique owners (both expired and valid). This may be larger than totalSupply
.
Returns the address of the current lock owner.
Returns true if the caller is the current owner.
Leaves the contract without owner. It will not be possible to call onlyOwner
functions anymore. Can only be called by the current owner.
Transfers ownership of the contract to a new account. Can only be called by the current owner.
Parameters: address newOwner
See https://github.com/ethereum/EIPs/blob/master/EIPS/eip-165.md​
Parameters: bytes4 interfaceId
Gets the current balance of the account provided.
Parameters: address tokenAddress
, address _account
Used by the lock owner to disable lock before migrating keys and/or destroying contract.
Query whether the given account has the LockManager role.
Parameters: address account
Add the LockManager role to the given account.
Parameters: address account
Remove the LockManager role from the calling account.
Parameters: address _publicLockAddress
, string _symbol
, string _URI
A function which lets the owner of the lock expire a users' key.
Parameters: address _owner
Checks if the user has a non-expired key.
Parameters: address _owner
Find the tokenId for a given user
Parameters: address _account
A function which returns a subset of the keys for this Lock as an array
Parameters: uint page
, uint _pageSize
Checks if the given address owns the given tokenId.
Parameters: uint tokenId
, address _owner
Returns the hash to sign in order to allow another user to cancel on your behalf. This can be computed in JS instead of read from the contract.
Parameters: address keyOwner
, address keySender
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).
Parameters: address _to
, uint _tokenId
, uint _timeShared
Parameters: address indexed from
, address indexed to
, uint256 indexed tokenId
Parameters: address indexed owner
, address indexed approved
, uint256 indexed tokenId
Parameters: address indexed owner
, address indexed operator
, bool approved
Parameters: uint balance
, address indexed owner
Parameters: address indexed sender
, address indexed tokenAddress
, address indexed beneficiary
, uint amount
Parameters: uint indexed tokenId
, address indexed owner
, address indexed sendTo
, uint refund
Parameters: uint freeTrialLength
, uint refundPenaltyBasisPoints
Parameters: uint oldKeyPrice
, uint keyPrice
, address oldTokenAddress
, address tokenAddress
Parameters: uint indexed tokenId
Parameters: string symbol
Parameters: uint transferFeeBasisPoints
Parameters: uint indexed _tokenId
, uint _amount
, bool _timeAdded
Parameters: address indexed keyOwner
, uint nextAvailableNonce
Parameters: address indexed previousOwner
, address indexed newOwner
Parameters: address indexed account
Parameters: address indexed account
Parameters: address indexed lockOwner
, address indexed newLockAddress
Parameters: address publicLockAddress
, string globalTokenSymbol
, string globalTokenURI
Returns the key's ExpirationTimestamp field for a given owner.
Parameters: address _owner
​