About your Locks and Smart Contracts
Overview
The Lock Smart Contract has multiple capabilities:
Administrative: these are the functions which change rights associated to the lock or individual parameters for the lock a such as its name or of course its price. 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.
Upgrades
All locks deployed prior to version 10 (to be released by year end 2022) are NOT upgradable, which means their core logic will remain unchanged. Starting with version 10, locks are upgradable by their lock manager, through the Unlock contract.
Functions
initialize
initialize
This function is the initializer and called when the lock is deployed. You don't need to call this function (and calling it will fail).
NB: To create non-expiring memberships, just set the _expirationDuration
to 0.
Once minted, the address deploying it becomes its first Lock manager. The Unlock contract also keeps track of each locks' address.
purchase
purchase
This function can be invoked to purchase a key (NFT membership). To purchase a membership, the caller should pass the number of tokens to be transfered (an ERC20 approval should have been initiated earlier), and this amount can be larger than the actual keyPrice
. It is possible to purchase a membership on behalf of another user by setting a different recipient address. The referrer address is the address that will receive some UDT governance tokens as part of this transaction (if applicable). A key manager can also be set directly during the purchase, allowing a different account to manage the key while the recipient still benefit from a full membership - see Access Control for more. Finally an arbitrary data object can be passed and is propagated to hooks and/or emitted as part of events.
This function will throw when the lock has been disabled, or if it is sold out.
grantKeys
grantKeys
Allows a Lock manager to give a collection of users a key with no charge. This is the mechanism used to "airdrop" memberships. Each key may be assigned a different expiration date and a different key manager.
shareKey
shareKey
This function can be called to transfer some of the time on a membership and do a "partial" transfer.
transfer
transfer
We implemented an ERC20 style transfer so that keys can be sent directly from wallets that usually support ERC20 transfers but have lower coverage for ERC721 functions
getTokenIdFor
getTokenIdFor
A function that returns the token id for an address (or the Zero address if the address does not own any).
keyExpirationTimestampFor
keyExpirationTimestampFor
A function that returns the expiration timestamp for the token owned by one address. It returns 0 if the user does not own a key and a timestamp from the past if the membership has expired.
purchasePriceFor
purchasePriceFor
This function can be used to retrieve the actual price for a specific user as the hook can alter the price and the front-end application might want to show the actual specific price for the user.
getTransferFee
getTransferFee
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 overtime. It returns the transfer in seconds.
expireAndRefundFor
expireAndRefundFor
A lock manager can invoke this function to expire a key and perform and refund based on the amount specified.
cancelAndRefund
cancelAndRefund
Allows a key manager to expire and get a refund for their key, based on the cancellation terms.
updateRefundPenalty
updateRefundPenalty
Allow a Lock manager to change the refund penalty. The first param is the duration of the free trial in seconds, and the second is the penalty in basis-points.
getCancelAndRefundValueFor
getCancelAndRefundValueFor
Determines how much of a refund a key owner would receive if they issued a cancelAndRefund
transaction. 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.
disableLock
disableLock
This function can only be called by the lock manager and is used to completely disable a lock and prevents any key purchase and transfer. This cannot be reversed.
updateKeyPricing
updateKeyPricing
This function can be called by any lock manager to change the pricing on the lock, including both the amount of currency. For locks priced in the chain's native currency, use the Zero address.
withdraw
withdraw
This function can be called by a lock manager or the beneficiary
to transfer all or some of the funds on the lock to the beneficiary
address. The tokenAddress
can be specified to transfer funds from an ERC20 when the currency has been changed. Note: consider avoiding full withdrawals as it breaks the cancelAndRefund
and expireAndRefundFor
methods.
approveBeneficiary
approveBeneficiary
This function can only be called by a lock manager to approve a 3rd party address to withdraw funds from the lock.
updateBeneficiary
updateBeneficiary
A function that can be called by any lock manager to change the address of the beneficiary address. The beneficiary can be either ad user's address or a contract's address.
setKeyManagerOf
setKeyManagerOf
This function can be called by a lock manager or the corresponding key manager to set the key manager for a key. This can be used to "loan" a key or collateralize it.
setMaxNumberOfKeys
setMaxNumberOfKeys
This function allows any lock manager to change the maximum number of keys a lock can edit.
ERC721 functions
The lock implements the ERC721 specification as described there.
balanceOf
balanceOf
This function is an ERC721 (and ERC20 function) that will return 1 if the user has a valid membership, but 0 if not (either no membership or expired).
Other methods
Setters
Allows a Lock manager to assign a descriptive name for this Lock.
Allows a Lock manager to assign a Symbol for this Lock.
Allows a Lock manager to update the baseTokenURI for this Lock.
Lets a lock manager set event hooks to be triggered on key purchases and on cancellation.
Allow a Lock manager to change the transfer fee. The transfer fee is expressed in basis-points. For example: 200bps = 2% and means that 2% of the time transfered is "burnt" during the transfer.
These functions are used to set, unset and check roles on the lock. Note that Lock Manager can only "renounce" their role and cannot be revoked.
Getters
Returns the lock version number:
Returns the name of a lock:
Returns the current number of owners (including expired keys):
Returns the token symbol
Yields the tokenURI as a string for a specific tokenId. This is part of the ERC721 spec: https://github.com/ethereum/EIPs/blob/master/EIPS/eip-721.md
This yields the address of the onKeyPurchaseHook
.
This yields the address of the onKeyCancelHook
.
This yields the beneficiary who will receive the lock's funds.
This yields the duration of each key.
This yields the duration of the free trial during which keys can cancelled at no cost.
This returns true if the lock is still alive.
This returns the currency used to charge for keys. If this is the Zero address, the lock uses the chains's native currency.
This returns the price of keys.
This returns the maximum number of keys that can be purchased on that lock.
This retrns the owner of a key (NFT) based on its id. This is an ERC721 method.
This returns the key manager of a key based on its id.
This returns the refund penalty in basis points.
This returns the transfer fee in basis points.
Last updated