Skip to content
This repository has been archived by the owner on Aug 1, 2023. It is now read-only.

Contract API docs generated from @unlock-protocol/contracts-0-0-19 #321

Merged
merged 3 commits into from
Apr 14, 2023
Merged

Contract API docs generated from @unlock-protocol/contracts-0-0-19 #321

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
e2a4c0b
Contract API docs generated from @unlock-protocol/contracts-0-0-19
clemsos Apr 13, 2023
d26076c
Contract API docs generated from @unlock-protocol/contracts-0-0-19
clemsos Apr 13, 2023
c5e43a9
Contract API docs generated from @unlock-protocol/contracts-0-0-19
clemsos Apr 13, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
156 changes: 34 additions & 122 deletions docs/core-protocol/smart-contracts-api/PublicLock.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# PublicLock (v12)
# PublicLock (v13)



Expand Down Expand Up @@ -27,56 +27,6 @@ function DEFAULT_ADMIN_ROLE() external view returns (bytes32 role)
|---|---|---|
| role | bytes32 | undefined |

### KEY_GRANTER_ROLE

```solidity
function KEY_GRANTER_ROLE() external view returns (bytes32 role)
```






#### Returns

| Name | Type | Description |
|---|---|---|
| role | bytes32 | undefined |

### LOCK_MANAGER_ROLE

```solidity
function LOCK_MANAGER_ROLE() external view returns (bytes32 role)
```






#### Returns

| Name | Type | Description |
|---|---|---|
| role | bytes32 | undefined |

### addKeyGranter

```solidity
function addKeyGranter(address account) external nonpayable
```





#### Parameters

| Name | Type | Description |
|---|---|---|
| account | address | undefined |

### addLockManager

```solidity
Expand Down Expand Up @@ -153,9 +103,10 @@ Deactivate an existing keythe key will be expired and ownership records will be
```solidity
function cancelAndRefund(uint256 _tokenId) external nonpayable
```
*Allows the key manager to expire a given tokenId and send a refund to the keyOwner based on the amount of time remaining.*

> Note: _Cancel is enabled with a 10% penalty by default on all Locks._
cancel is enabled with a 10% penalty by default on all Locks.

*allows the key manager to expire a given tokenId and send a refund to the keyOwner based on the amount of time remaining.*

#### Parameters

Expand Down Expand Up @@ -188,7 +139,7 @@ function expireAndRefundFor(uint256 _tokenId, uint256 _amount) external nonpayab



*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*
*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

Expand Down Expand Up @@ -344,7 +295,7 @@ Innherited from Open Zeppelin AccessControl.sol
function getTransferFee(uint256 _tokenId, uint256 _time) external view returns (uint256)
```

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.
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*

Expand Down Expand Up @@ -486,10 +437,10 @@ function isApprovedForAll(address _owner, address _operator) external view retur
|---|---|---|
| _0 | bool | bool whether the given operator is approved by the given owner |

### isKeyGranter
### isLockManager

```solidity
function isKeyGranter(address account) external view returns (bool)
function isLockManager(address account) external view returns (bool)
```


Expand All @@ -508,10 +459,10 @@ function isKeyGranter(address account) external view returns (bool)
|---|---|---|
| _0 | bool | undefined |

### isLockManager
### isOwner

```solidity
function isLockManager(address account) external view returns (bool)
function isOwner(address account) external view returns (bool isOwner)
```


Expand All @@ -528,29 +479,30 @@ function isLockManager(address account) external view returns (bool)

| Name | Type | Description |
|---|---|---|
| _0 | bool | undefined |
| isOwner | bool | undefined |

### isOwner
### isRenewable

```solidity
function isOwner(address account) external view returns (bool isOwner)
function isRenewable(uint256 tokenId, address referrer) external view returns (bool)
```




*helper to check if a key is currently renewable it will revert if the pricing or duration of the lock have been modified unfavorably since the key was bought(price increase or duration decrease). It will also revert if a lock is not renewable or if the key is not ready for renewal yet (at least 90% expired).*

#### Parameters

| Name | Type | Description |
|---|---|---|
| account | address | undefined |
| tokenId | uint256 | the id of the token to check |
| referrer | address | the address where to send the referrer fee |

#### Returns

| Name | Type | Description |
|---|---|---|
| isOwner | bool | undefined |
| _0 | bool | true if the terms has changed |

### isValidKey

Expand Down Expand Up @@ -641,7 +593,7 @@ function keyPrice() external view returns (uint256)
function lendKey(address from, address to, uint256 tokenId) external nonpayable
```

Lending a key allows you to transfer the token while retaining the ownerships right by setting yourself as a key manager first. This function can only be called by 1) the key owner when no key manager is set or 2) the key manager. After calling the function, the `_recipent` will be the new owner, and the sender of the tx will become the key manager.
Lending a key allows you to transfer the token while retaining the ownerships right by setting yourself as a key manager first.This function can only be called by 1) the key owner when no key manager is set or 2) the key manager. After calling the function, the `_recipent` will be the new owner, and the sender of the tx will become the key manager.



Expand Down Expand Up @@ -711,7 +663,7 @@ Merge existing keys
function migrate(bytes _calldata) external nonpayable
```

Migrate data from the previous single owner => key mapping to the new data structure w multiple tokens.
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*

Expand Down Expand Up @@ -880,7 +832,7 @@ Returns the address of the `onValidKeyHook` hook.
function owner() external view returns (address owner)
```

`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.
`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.



Expand Down Expand Up @@ -936,7 +888,7 @@ The version number of the current implementation on this network.
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
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).*

Expand All @@ -954,7 +906,7 @@ when called for an existing and non-expired key, the `_keyManager` param will be

| Name | Type | Description |
|---|---|---|
| tokenIds | uint256[] | the ids of the created tokens |
| tokenIds | uint256[] | the ids of the created tokens |

### purchasePriceFor

Expand Down Expand Up @@ -1064,22 +1016,6 @@ function renounceRole(bytes32 role, address account) external nonpayable
| role | bytes32 | undefined |
| account | address | undefined |

### revokeKeyGranter

```solidity
function revokeKeyGranter(address _granter) external nonpayable
```





#### Parameters

| Name | Type | Description |
|---|---|---|
| _granter | address | undefined |

### revokeRole

```solidity
Expand Down Expand Up @@ -1229,7 +1165,7 @@ Update transfer and cancel rights for a given key
function setLockMetadata(string _lockName, string _lockSymbol, string _baseTokenURI) external nonpayable
```

Allows the Lock owner to assign
Allows the Lock owner to assign



Expand Down Expand Up @@ -1263,7 +1199,7 @@ function setOwner(address account) external nonpayable
function setReferrerFee(address _referrer, uint256 _feeBasisPoint) external nonpayable
```

Set a specific percentage of the keyPrice to be sent to the referrer while purchasing, extending or renewing a key.
Set a specific percentage of the keyPrice to be sent to the referrer while purchasing, extending or renewing a key.

*To send a fixed percentage of the key price to all referrers, sett a percentage to `address(0)`*

Expand All @@ -1272,7 +1208,7 @@ Set a specific percentage of the keyPrice to be sent to the referrer while purch
| Name | Type | Description |
|---|---|---|
| _referrer | address | the address of the referrer |
| _feeBasisPoint | uint256 | the percentage of the price to be used for this specific referrer (in basis points) |
| _feeBasisPoint | uint256 | the percentage of the price to be used for this specific referrer (in basis points) |

### shareKey

Expand Down Expand Up @@ -1440,43 +1376,19 @@ Returns the number of keys owned by `_keyOwner` (expired or not)
### totalSupply

```solidity
function totalSupply() external view returns (uint256)
```






#### Returns

| Name | Type | Description |
|---|---|---|
| _0 | uint256 | undefined |

### transfer

```solidity
function transfer(uint256 _tokenId, address _to, uint256 _value) external nonpayable returns (bool success)
function totalSupply() external view returns (uint256 _totalKeysCreated)
```

Returns the total number of keys, including non-valid ones


*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 |
|---|---|---|
| _tokenId | uint256 | the id of the token to transfer time from |
| _to | address | the recipient of the new token with time |
| _value | uint256 | sends a token with _value * expirationDuration (the amount of time remaining on a standard purchase). |

#### Returns

| Name | Type | Description |
|---|---|---|
| success | bool | the result of the transfer operation |
| _totalKeysCreated | uint256 | the total number of keys, valid or not |

### transferFeeBasisPoints

Expand All @@ -1501,9 +1413,9 @@ function transferFeeBasisPoints() external view returns (uint256)
function transferFrom(address from, address to, uint256 tokenId) external nonpayable
```

an ERC721-like function to transfer a token from one account to another.
an ERC721-like function to transfer a token from one account to another.

*Requirements: if the caller is not `from`, it must be approved to move this token by either {approve} or {setApprovalForAll}. The key manager will be reset to address zero after the transfer*
*Requirements: if the caller is not `from`, it must be approved to move this token by either {approve} or {setApprovalForAll}. The key manager will be reset to address zero after the transfer*

#### Parameters

Expand All @@ -1519,7 +1431,7 @@ an ERC721-like function to transfer a token from one account to another.
function unlendKey(address _recipient, uint256 _tokenId) external nonpayable
```

Unlend is called when you have lent a key and want to claim its full ownership back.
Unlend is called when you have lent a key and want to claim its full ownership back.

*Only the key manager of the token can call this function*

Expand Down Expand Up @@ -1570,9 +1482,9 @@ A function which lets a Lock manager of the lock to change the price for future
function updateLockConfig(uint256 _newExpirationDuration, uint256 _maxNumberOfKeys, uint256 _maxKeysPerAcccount) external nonpayable
```

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 holdkeys previously bought are unaffected by this changes in expiration duration (i.e. existing keys timestamps are not recalculated/updated)
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 holdkeys 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 *
*_maxNumberOfKeys Can't be smaller than the existing supply*

#### Parameters

Expand Down Expand Up @@ -1642,7 +1554,7 @@ function withdraw(address _tokenAddress, address payable _recipient, uint256 _am
|---|---|---|
| _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. |
| _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. |



Expand Down
Loading