Solidity API
MerkleProof
_These functions deal with verification of Merkle Tree proofs.
The tree and the proofs can be generated using our https://github.com/OpenZeppelin/merkle-tree[JavaScript library]. You will find a quickstart guide in the readme.
WARNING: You should avoid using leaf values that are 64 bytes long prior to hashing, or use a hash function other than keccak256 for hashing leaves. This is because the concatenation of a sorted pair of internal nodes in the Merkle tree could be reinterpreted as a leaf value. OpenZeppelin's JavaScript library generates Merkle trees that are safe against this attack out of the box._
MerkleProofInvalidMultiproof
error MerkleProofInvalidMultiproof()
The multiproof provided is not valid.
verify
function verify(bytes32[] proof, bytes32 root, bytes32 leaf) internal pure returns (bool)
Returns true if a leaf
can be proved to be a part of a Merkle tree
defined by root
. For this, a proof
must be provided, containing
sibling hashes on the branch from the leaf to the root of the tree. Each
pair of leaves and each pair of pre-images are assumed to be sorted.
verifyCalldata
function verifyCalldata(bytes32[] proof, bytes32 root, bytes32 leaf) internal pure returns (bool)
Calldata version of verify
processProof
function processProof(bytes32[] proof, bytes32 leaf) internal pure returns (bytes32)
Returns the rebuilt hash obtained by traversing a Merkle tree up
from leaf
using proof
. A proof
is valid if and only if the rebuilt
hash matches the root of the tree. When processing the proof, the pairs
of leafs & pre-images are assumed to be sorted.
processProofCalldata
function processProofCalldata(bytes32[] proof, bytes32 leaf) internal pure returns (bytes32)
Calldata version of processProof
multiProofVerify
function multiProofVerify(bytes32[] proof, bool[] proofFlags, bytes32 root, bytes32[] leaves) internal pure returns (bool)
_Returns true if the leaves
can be simultaneously proven to be a part of a Merkle tree defined by
root
, according to proof
and proofFlags
as described in processMultiProof.
CAUTION: Not all Merkle trees admit multiproofs. See processMultiProof for details._
multiProofVerifyCalldata
function multiProofVerifyCalldata(bytes32[] proof, bool[] proofFlags, bytes32 root, bytes32[] leaves) internal pure returns (bool)
_Calldata version of multiProofVerify
CAUTION: Not all Merkle trees admit multiproofs. See processMultiProof for details._
processMultiProof
function processMultiProof(bytes32[] proof, bool[] proofFlags, bytes32[] leaves) internal pure returns (bytes32 merkleRoot)
_Returns the root of a tree reconstructed from leaves
and sibling nodes in proof
. The reconstruction
proceeds by incrementally reconstructing all inner nodes by combining a leaf/inner node with either another
leaf/inner node or a proof sibling node, depending on whether each proofFlags
item is true or false
respectively.
CAUTION: Not all Merkle trees admit multiproofs. To use multiproofs, it is sufficient to ensure that: 1) the tree is complete (but not necessarily perfect), 2) the leaves to be proven are in the opposite order they are in the tree (i.e., as seen from right to left starting at the deepest layer and continuing at the next layer)._
processMultiProofCalldata
function processMultiProofCalldata(bytes32[] proof, bool[] proofFlags, bytes32[] leaves) internal pure returns (bytes32 merkleRoot)
_Calldata version of processMultiProof.
CAUTION: Not all Merkle trees admit multiproofs. See processMultiProof for details._
IPublicLock
PurchaseArgs
PurchaseArgs struct
Parameters
Name | Type | Description |
---|
struct PurchaseArgs {
uint256 value;
address recipient;
address referrer;
address protocolReferrer;
address keyManager;
bytes data;
uint256 additionalPeriods;
}
initialize
function initialize(address _lockCreator, uint256 _expirationDuration, address _tokenAddress, uint256 _keyPrice, uint256 _maxNumberOfKeys, string _lockName) external
Functions
DEFAULT_ADMIN_ROLE
function DEFAULT_ADMIN_ROLE() external view returns (bytes32 role)
publicLockVersion
function publicLockVersion() external pure returns (uint16)
The version number of the current implementation on this network.
Return Values
Name | Type | Description |
---|---|---|
[0] | uint16 | The current version number. |
withdraw
function withdraw(address _tokenAddress, address payable _recipient, uint256 _amount) external
Called by lock manager to withdraw all funds from the lock
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. |
_recipient | address payable | specifies the address that will receive the tokens |
_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. |
updateKeyPricing
function updateKeyPricing(uint256 _keyPrice, address _tokenAddress) external
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 manager Throws if lock has been disabled Throws 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 |
updateLockConfig
function updateLockConfig(uint256 _newExpirationDuration, uint256 _maxNumberOfKeys, uint256 _maxKeysPerAcccount) external
Update the main key properties for the entire lock:
- default duration of each key
- the maximum number of keys the lock can edit
- the maximum number of keys a single address can hold
keys previously bought are unaffected by this changes in expiration duration (i.e. existing keys timestamps are not recalculated/updated)
_maxNumberOfKeys Can't be smaller than the existing supply
Parameters
Name | Type | Description |
---|---|---|
_newExpirationDuration | uint256 | the new amount of time for each key purchased or type(uint).max for a non-expiring key |
_maxNumberOfKeys | uint256 | uint the maximum number of keys |
_maxKeysPerAcccount | uint256 | the maximum amount of key a single user can own |
getHasValidKey
function getHasValidKey(address _user) external view returns (bool)
Checks if the user has a non-expired key.
Parameters
Name | Type | Description |
---|---|---|
_user | address | The address of the key owner |
keyExpirationTimestampFor
function keyExpirationTimestampFor(uint256 _tokenId) external view returns (uint256 timestamp)
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 |
numberOfOwners
function numberOfOwners() external view returns (uint256)
Public function which returns the total number of unique owners (both expired and valid). This may be larger than totalSupply.
setLockMetadata
function setLockMetadata(string _lockName, string _lockSymbol, string _baseTokenURI) external
Allows the Lock owner to assign
Parameters
Name | Type | Description |
---|---|---|
_lockName | string | a descriptive name for this Lock. |
_lockSymbol | string | a Symbol for this Lock (default to KEY). |
_baseTokenURI | string | the baseTokenURI for this Lock |
symbol
function symbol() external view returns (string)
Gets the token symbol
Return Values
Name | Type | Description |
---|---|---|
[0] | string | string representing the token symbol |
tokenURI
function tokenURI(uint256 _tokenId) external view returns (string)
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 |
Return Values
Name | Type | Description |
---|---|---|
[0] | string | String representing the URI for the requested token |
setEventHooks
function setEventHooks(address _onKeyPurchaseHook, address _onKeyCancelHook, address _onValidKeyHook, address _onTokenURIHook, address _onKeyTransferHook, address _onKeyExtendHook, address _onKeyGrantHook, address _onHasRoleHook) external
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 | Hook called to determine if the contract should overide the status for a given address |
_onTokenURIHook | address | Hook called to generate a data URI used for NFT metadata |
_onKeyTransferHook | address | Hook called when a key is transfered |
_onKeyExtendHook | address | Hook called when a key is extended or renewed |
_onKeyGrantHook | address | Hook called when a key is granted |
_onHasRoleHook | address | Hook called when checking if an address as a specific role |
grantKeys
function grantKeys(address[] _recipients, uint256[] _expirationTimestamps, address[] _keyManagers) external returns (uint256[])
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[] |
Return Values
Name | Type | Description |
---|---|---|
[0] | uint256[] | the ids of the granted tokens |
grantKeyExtension
function grantKeyExtension(uint256 _tokenId, uint256 _duration) external
Allows the Lock owner to extend an existing keys with no charge.
set _duration
to 0 to use the default duration of the lock
Parameters
Name | Type | Description |
---|---|---|
_tokenId | uint256 | The id of the token to extend |
_duration | uint256 | The duration in secondes to add ot the key |
purchase
function purchase(struct IPublicLock.PurchaseArgs[] purchaseArgs) external payable returns (uint256[] tokenIds)
Purchase function
Parameters
Name | Type | Description |
---|---|---|
purchaseArgs | struct IPublicLock.PurchaseArgs[] | array of PurchaseArg |
Return Values
Name | Type | Description |
---|---|---|
tokenIds | uint256[] | the ids of the created tokens |
purchase
function purchase(uint256[] _values, address[] _recipients, address[] _referrers, address[] _keyManagers, bytes[] _data) external payable returns (uint256[] tokenIds)
when called for an existing and non-expired key, the _keyManager
param will be ignored
Purchase function (legacy) Setting _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 |
Return Values
Name | Type | Description |
---|---|---|
tokenIds | uint256[] | the ids of the created tokens |