> For the complete documentation index, see [llms.txt](https://docs.uncx.network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.uncx.network/guides/for-developers/liquidity-lockers/lockers-v3/technical-reference/locker-v3.1.md).

# Locker V3.1

## Functions Write <a href="#functions-write" id="functions-write"></a>

### Lock <a href="#lock" id="lock"></a>

```
function lock(LockParams calldata params) external payable   returns (uint256)
```

Converts nft to full range and collects fees and sends them back to collector.

Parameters:

| Type       | Description                                                                                                                                                                                                                                                                     |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| LockParams | An object that contains: `nftPositionManager` (address), `nft_id` (uint256), `dustRecipient` (address), `owner` (address), `additionalCollector` (address), `collectAddress` (address), `unlockDate` (uint256), `countryCode` (string), `r` (bytes\[]), and `feeName` (string). |

Return Values:

| Type    | Description                       |
| ------- | --------------------------------- |
| uint256 | The ID of the newly created lock. |

***

### Collects <a href="#collects" id="collects"></a>

```
function collect(    uint256 _lockId,     address _recipient,     uint128 _amount0Max,     uint128 _amount1Max) external   returns (    uint256 amount0,     uint256 amount1,     uint256 fee0,     uint256 fee1)
```

Collect fees to \_recipient if msg.sender is the owner of \_lockId.

Parameters:

| Name          | Type    | Description                                       |
| ------------- | ------- | ------------------------------------------------- |
| `_lockId`     | uint256 | The ID of the lock from which to collect fees.    |
| `_recipient`  | address | The address to which collected fees will be sent. |
| `_amount0Max` | uint128 | Maximum amount of token0 to collect.              |
| `_amount1Max` | uint128 | Maximum amount of token1 to collect.              |

Return Values:

| Type    | Description                 |
| ------- | --------------------------- |
| uint256 | Amount of token0 collected. |
| uint256 | Amount of token1 collected. |
| uint256 | Fee associated with token0. |
| uint256 | Fee associated with token1. |

***

### IncreaseLiquidity <a href="#increaseliquidity" id="increaseliquidity"></a>

```
function increaseLiquidity(    uint256 _lockId,     INonfungiblePositionManager.IncreaseLiquidityParams calldata params) external payable   returns (    uint128 liquidity,     uint256 amount0,     uint256 amount1)
```

Increases liquidity.

Parameters:

| Name     | Type                                                | Description                                            |
| -------- | --------------------------------------------------- | ------------------------------------------------------ |
| \_lockId | uint256                                             | The ID of the lock.                                    |
| params   | INonfungiblePositionManager.IncreaseLiquidityParams | Object containing parameters for increasing liquidity. |

Return Values:

| Name      | Type    | Description                |
| --------- | ------- | -------------------------- |
| liquidity | uint128 | Amount of liquidity added. |
| amount0   | uint256 | Amount of token0 added.    |
| amount1   | uint256 | Amount of token1 added.    |

***

### DecreaseLiquidity <a href="#decreaseliquidity" id="decreaseliquidity"></a>

```
function decreaseLiquidity(    uint256 _lockId,    INonfungiblePositionManager.DecreaseLiquidityParams calldata params) external payable   returns (uint256 amount0, uint256 amount1)
```

Decrease liquidity if a lock has expired

Parameters:

| Name     | Type                                                | Description                                            |
| -------- | --------------------------------------------------- | ------------------------------------------------------ |
| \_lockId | uint256                                             | The ID of the lock.                                    |
| params   | INonfungiblePositionManager.DecreaseLiquidityParams | Object containing parameters for decreasing liquidity. |

Return Values:

| Name    | Type    | Description                                           |
| ------- | ------- | ----------------------------------------------------- |
| amount0 | uint256 | Amount of token0 returned after decreasing liquidity. |
| amount1 | uint256 | Amount of token1 returned after decreasing liquidity. |

***

### Relock <a href="#relock" id="relock"></a>

```
function relock(    uint256 _lockId,    uint256 _unlockDate) external  
```

Set the unlock date further in the future.

Parameters:

| Name         | Type    | Description                                                                                                     |
| ------------ | ------- | --------------------------------------------------------------------------------------------------------------- |
| \_lockId     | uint256 | The ID of the lock.                                                                                             |
| \_unlockDate | uint256 | The new unlock date timestamp. It must be greater than the current unlock date and the current block timestamp. |

Return Values:

| Name         | Type    | Description                                                                                                     |
| ------------ | ------- | --------------------------------------------------------------------------------------------------------------- |
| \_lockId     | uint256 | The ID of the lock.                                                                                             |
| \_unlockDate | uint256 | The new unlock date timestamp. It must be greater than the current unlock date and the current block timestamp. |

***

### Withdraw <a href="#withdraw" id="withdraw"></a>

```
function withdraw(    uint256 _lockId,    address _receiver) external  
```

Withdraw a UniV3 liquidity NFT and send it to \_receiver.

Parameters:

| Name       | Type    | Description                                                                     |
| ---------- | ------- | ------------------------------------------------------------------------------- |
| \_lockId   | uint256 | The ID of the lock. The caller must be an admin of this lock.                   |
| \_receiver | address | The address to which the UniV3 liquidity NFT will be sent after the withdrawal. |

***

### Migrate <a href="#migrate" id="migrate"></a>

```
function migrate(    uint256 _lockId) external  
```

Migrate a lock to a new amm version (Uniswap V4).

Parameters:

| Name     | Type    | Description                                                   |
| -------- | ------- | ------------------------------------------------------------- |
| \_lockId | uint256 | The ID of the lock. The caller must be an admin of this lock. |

***

### SetAdditionalCollector <a href="#setadditionalcollector" id="setadditionalcollector"></a>

```
function setAdditionalCollector(    uint256 _lockId,    address _additionalCollector) external  
```

Allow a lock owner to add an additional address, usually a contract, to collect fees. Useful for bots.

Parameters:

| Name                  | Type    | Description                                                                   |
| --------------------- | ------- | ----------------------------------------------------------------------------- |
| \_lockId              | uint256 | The ID of the lock. The caller must be an admin of this lock.                 |
| \_additionalCollector | address | The address designated as an additional collector for the fees from the lock. |

***

### SetCollectAddress <a href="#setcollectaddress" id="setcollectaddress"></a>

```
function setCollectAddress(    uint256 _lockId,    address _collectAddress) external  
```

Set the adress to which fees are automatically collected.

Parameters:

| Name             | Type    | Description                                                              |
| ---------------- | ------- | ------------------------------------------------------------------------ |
| \_lockId         | uint256 | The ID of the lock. The caller must be an admin of this lock.            |
| \_collectAddress | address | The address to which the fees from the lock are automatically collected. |

***

### TransferLockOwnership <a href="#transferlockownership" id="transferlockownership"></a>

```
function transferLockOwnership(    uint256 _lockId,    address _newOwner) external  
```

Transfer ownership of a lock to \_newOwner.

Parameters:

| Name       | Type    | Description                                                                     |
| ---------- | ------- | ------------------------------------------------------------------------------- |
| \_lockId   | uint256 | The ID of the lock. The caller must be an admin of this lock.                   |
| \_newOwner | address | The address of the new owner to whom the lock's ownership is being transferred. |

***

### AcceptLockOwnership <a href="#acceptlockownership" id="acceptlockownership"></a>

```
function acceptLockOwnership(    uint256 _lockId) external  
```

Parameters:

| Name     | Type    | Description                                               |
| -------- | ------- | --------------------------------------------------------- |
| \_lockId | uint256 | The ID of the lock for which ownership is being accepted. |

## Functions View <a href="#functions-view" id="functions-view"></a>

### GetFee <a href="#getfee" id="getfee"></a>

```
function getFee(string memory _name) public  view returns (FeeStruct memory)
```

Retrieves the fee details associated with a given name.

Parameters:

| Type   | Description                                           |
| ------ | ----------------------------------------------------- |
| string | The name used to lookup the associated fee structure. |

Return Values:

| Type      | Description                                                                                                                             |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| FeeStruct | An object that contains: `name` (string), `lpFee` (uint256), `collectFee` (uint256), `flatFee` (uint256), and `flatFeeToken` (address). |

***

### GetFeeOptionAtIndex <a href="#getfeeoptionatindex" id="getfeeoptionatindex"></a>

```
function getFeeOptionAtIndex(uint256 _index) external view returns (FeeStruct memory)
```

Fetches the fee details based on its position.

Parameters:

| Type    | Description                              |
| ------- | ---------------------------------------- |
| uint256 | Index of the fee option to be retrieved. |

Return Values:

| Type      | Description                                                                                                                             |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| FeeStruct | An object that contains: `name` (string), `lpFee` (uint256), `collectFee` (uint256), `flatFee` (uint256), and `flatFeeToken` (address). |

***

### GetFeeOptionLength <a href="#getfeeoptionlength" id="getfeeoptionlength"></a>

```
function getFeeOptionLength() external view returns (uint256)
```

Returns the total amount of fee options available.

Return Values:

| Type    | Description                                |
| ------- | ------------------------------------------ |
| uint256 | The total amount of fee options available. |

***

### GetLock <a href="#getlock" id="getlock"></a>

```
function getLock(uint256 _lockId) external view  returns (Lock memory _lock)
```

Returns a Lock struct for \_lockId.

Parameters:

| Name     | Type    | Description                         |
| -------- | ------- | ----------------------------------- |
| \_lockId | uint256 | The ID of the lock to be retrieved. |

Return Values:

| Type | Description                                                                                                                                                                                                                                                                                                            |
| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Lock | An object that contains: `lock_id` (uint256), `nftPositionManager` (INonfungiblePositionManager), `pool` (address), `nft_id` (uint256), `owner` (address), `pendingOwner` (address), `additionalCollector` (address), `collectAddress` (address), `unlockDate` (uint256), `countryCode` (uint16), and `ucf` (uint256). |

***

### GetLocksLength <a href="#getlockslength" id="getlockslength"></a>

```
function getLocksLength() external view  returns (uint256)
```

Return Values:

| Type    | Description                                                        |
| ------- | ------------------------------------------------------------------ |
| uint256 | The unique nonce representing the amount of locks in the contract. |

***

### GetNumUserLocks <a href="#getnumuserlocks" id="getnumuserlocks"></a>

```
function getNumUserLocks(address _user) external view  returns (uint256)
```

Parameters:

| Type    | Description              |
| ------- | ------------------------ |
| address | The address of the user. |

Return Values:

| Type    | Description                                   |
| ------- | --------------------------------------------- |
| uint256 | The number of locks associated with the user. |

***

### GetUserLockAtIndex <a href="#getuserlockatindex" id="getuserlockatindex"></a>

```
function getUserLockAtIndex(    address _user,    uint256 _index) external view  returns (Lock memory)
```

Parameters:

| Type    | Description                               |
| ------- | ----------------------------------------- |
| address | The address of the user.                  |
| uint256 | The index of the lock for the given user. |

Return Values:

| Type | Description                                                                                                                                                                                                       |
| ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Lock | A struct that contains details of the lock including `lock_id`, `nftPositionManager`, `pool`, `nft_id`, `owner`, `pendingOwner`, `additionalCollector`, `collectAddress`, `unlockDate`, `countryCode`, and `ucf`. |

***

### TickSpacingToMaxTick <a href="#tickspacingtomaxtick" id="tickspacingtomaxtick"></a>

```
function tickSpacingToMaxTick(int24 tickSpacing) public pure returns (int24 maxTick)
```

Parameters:

| Type  | Description                                                   |
| ----- | ------------------------------------------------------------- |
| int24 | The tick spacing used to calculate the maximum possible tick. |

Return Values:

| Type  | Description                                        |
| ----- | -------------------------------------------------- |
| int24 | The maximum tick value calculated for the spacing. |

***

### GetAmountsForLiquidity <a href="#getamountsforliquidity" id="getamountsforliquidity"></a>

```
function getAmountsForLiquidity (    int24 currentTick,     int24 tickLower,     int24 tickHigher,     uint128 liquidity) public pure  returns (uint256 amount0, uint256 amount1) {    return LiquidityAmounts.getAmountsForLiquidity(        TickMath.getSqrtRatioAtTick(currentTick),        TickMath.getSqrtRatioAtTick(tickLower),        TickMath.getSqrtRatioAtTick(tickHigher),        liquidity    )}
```

Parameters:

| Type    | Description                                       |
| ------- | ------------------------------------------------- |
| int24   | The current tick of the liquidity range.          |
| int24   | The lower tick boundary of the liquidity range.   |
| int24   | The higher tick boundary of the liquidity range.  |
| uint128 | The liquidity amount to be used for calculations. |

Return Values:

| Type    | Description                                                         |
| ------- | ------------------------------------------------------------------- |
| uint256 | The amount of `token0` calculated based on the provided parameters. |
| uint256 | The amount of `token1` calculated based on the provided parameters. |

***

### OnERC721Received <a href="#onerc721received" id="onerc721received"></a>

```
function onERC721Received(    address operator,    address from,    uint256 tokenId,    bytes calldata data) public pure  returns (bytes4) {    return IERC721Receiver.onERC721Received.selector}
```

Parameters:

| Type    | Description                                                       |
| ------- | ----------------------------------------------------------------- |
| address | The address of the sender invoking this function (the operator).  |
| address | The address from which the ERC721 token originates.               |
| uint256 | The unique identifier (ID) of the ERC721 token being transferred. |
| bytes   | Additional calldata sent with the transfer.                       |

Return Values:

| Type   | Description                                                |
| ------ | ---------------------------------------------------------- |
| bytes4 | The function selector for the `onERC721Received` function. |

## Events <a href="#events" id="events"></a>

### OnAddFee <a href="#onaddfee" id="onaddfee"></a>

```
event onAddFee(    bytes32 nameHash,     string name,     uint256 lpFee,     uint256 collectFee,     uint256 flatFee,     address flatFeeToken)
```

Emitted on addOrEditFee.

Parameters:

| Name         | Type    | Description                                                    |
| ------------ | ------- | -------------------------------------------------------------- |
| nameHash     | bytes32 | The unique hash representing the name of the fee.              |
| name         | string  | The name of the fee.                                           |
| lpFee        | uint256 | The liquidity provider fee amount.                             |
| collectFee   | uint256 | The fee amount to be collected.                                |
| flatFee      | uint256 | The flat fee amount.                                           |
| flatFeeToken | address | The address of the token in which the flat fee is denominated. |

***

### OnEditFee <a href="#oneditfee" id="oneditfee"></a>

```
event onEditFee(    bytes32 nameHash,     string name,     uint256 lpFee,     uint256 collectFee,     uint256 flatFee,     address flatFeeToken)
```

Emitted on addOrEditFee.

Parameters:

| Name         | Type    | Description                                                    |
| ------------ | ------- | -------------------------------------------------------------- |
| nameHash     | bytes32 | The unique hash representing the name of the fee.              |
| name         | string  | The name of the fee.                                           |
| lpFee        | uint256 | The liquidity provider fee amount.                             |
| collectFee   | uint256 | The fee amount to be collected.                                |
| flatFee      | uint256 | The flat fee amount.                                           |
| flatFeeToken | address | The address of the token in which the flat fee is denominated. |

***

### OnRemoveFee <a href="#onremovefee" id="onremovefee"></a>

```
event onRemoveFee(    bytes32 nameHash)
```

Emitted on removeFee.

Parameters:

| Name     | Type    | Description                                       |
| -------- | ------- | ------------------------------------------------- |
| nameHash | bytes32 | The unique hash representing the name of the fee. |

***

### OnLock <a href="#onlock" id="onlock"></a>

```
event onLock(    uint256 lock_id,    address nftPositionManager,    uint256 nft_id,    address owner,    address additionalCollector,    address collectAddress,    uint256 unlockDate,    uint16 countryCode,    uint256 collectFee,    address poolAddress,    INonfungiblePositionManager.Position position)
```

Emitted ont [Lock](https://developers.uncx.network/lockers-v3/technicalReference/UNCX_ProofOfReservesV2_UniV3#lock).

Parameters:

| Name                | Type                        | Description                                                                                       |
| ------------------- | --------------------------- | ------------------------------------------------------------------------------------------------- |
| lock\_id            | uint256                     | The unique nonce per lock.                                                                        |
| nftPositionManager  | INonfungiblePositionManager | The NFT position manager of the Uniswap fork.                                                     |
| nft\_id             | uint256                     | The NFT token ID of the NFT belonging to the nftPositionManager.                                  |
| owner               | address                     | The owner who can collect and withdraw.                                                           |
| additionalCollector | address                     | An additional address allowed to call collect.                                                    |
| collectAddress      | address                     | The address to which automatic collections are sent.                                              |
| unlockDate          | uint256                     | The unlock date of the lock in seconds.                                                           |
| countryCode         | uint16                      | The country code of the locker/business.                                                          |
| collectFee          | uint256                     | The collect fee.                                                                                  |
| poolAddress         | address                     | The pool address.                                                                                 |
| position            | IUniswapV3Pool.Position     | Represents a unique position in a Uniswap V3 Pool. Contains details about the liquidity provided. |

***

### OnIncreaseLiquidity <a href="#onincreaseliquidity" id="onincreaseliquidity"></a>

```
event onIncreaseLiquidity(    uint256 lockId)
```

Emitted on [IncreaseLiquidity](https://developers.uncx.network/lockers-v3/technicalReference/UNCX_ProofOfReservesV2_UniV3#increaseliquidity).

Parameters:

| Name   | Type    | Description                                           |
| ------ | ------- | ----------------------------------------------------- |
| lockId | uint256 | The ID of the lock for which liquidity was increased. |

***

### OnDecreaseLiquidity <a href="#ondecreaseliquidity" id="ondecreaseliquidity"></a>

```
event onDecreaseLiquidity(    uint256 lockId)
```

Emitted on [DecreaseLiquidity](https://developers.uncx.network/lockers-v3/technicalReference/UNCX_ProofOfReservesV2_UniV3#increaseliquidity).

Parameters:

| Name   | Type    | Description                                           |
| ------ | ------- | ----------------------------------------------------- |
| lockId | uint256 | The ID of the lock for which liquidity was decreased. |

***

### OnRelock <a href="#onrelock" id="onrelock"></a>

```
event onRelock(    uint256 lockId,     uint256 unlockDate)
```

Emitted on [Relock](https://developers.uncx.network/lockers-v3/technicalReference/UNCX_ProofOfReservesV2_UniV3#relock).

Parameters:

| Name       | Type    | Description                                |
| ---------- | ------- | ------------------------------------------ |
| lockId     | uint256 | The ID of the lock that is being relocked. |
| unlockDate | uint256 | The new unlock date for the relocked lock. |

***

### OnWithdraw <a href="#onwithdraw" id="onwithdraw"></a>

```
event onWithdraw(    uint256 lock_id,     address owner,     address receiver)
```

Emitted on [Withdraw](https://developers.uncx.network/lockers-v3/technicalReference/UNCX_ProofOfReservesV2_UniV3#withdraw).

Parameters:

| Name     | Type    | Description                           |
| -------- | ------- | ------------------------------------- |
| lock\_id | uint256 | The ID of the lock being withdrawn.   |
| owner    | address | The owner of the lock.                |
| receiver | address | The address receiving the withdrawal. |

***

### OnMigrate <a href="#onmigrate" id="onmigrate"></a>

```
event onMigrate(    uint256 lockId)
```

Emitted on [Migrate](https://developers.uncx.network/lockers-v3/technicalReference/UNCX_ProofOfReservesV2_UniV3#migrate).

Parameters:

| Name   | Type    | Description                                |
| ------ | ------- | ------------------------------------------ |
| lockId | uint256 | The ID of the lock that is being migrated. |

***

### OnSetAdditionalCollector <a href="#onsetadditionalcollector" id="onsetadditionalcollector"></a>

```
event onSetAdditionalCollector(    uint256 lockId,     address additionalCollector)
```

Emitted on [SetAdditionalCollector](https://developers.uncx.network/lockers-v3/technicalReference/UNCX_ProofOfReservesV2_UniV3#setadditionalcollector).

Parameters:

| Name                | Type    | Description                                         |
| ------------------- | ------- | --------------------------------------------------- |
| lockId              | uint256 | The ID of the lock setting an additional collector. |
| additionalCollector | address | The address being set as the additional collector.  |

***

### OnSetCollectAddress <a href="#onsetcollectaddress" id="onsetcollectaddress"></a>

```
event onSetCollectAddress(    uint256 lockId,     address collectAddress)
```

Emitted on [SetCollectAddress](https://developers.uncx.network/lockers-v3/technicalReference/UNCX_ProofOfReservesV2_UniV3#setcollectAddress).

Parameters:

| Name           | Type    | Description                                                   |
| -------------- | ------- | ------------------------------------------------------------- |
| lockId         | uint256 | The ID of the lock where the collection address is being set. |
| collectAddress | address | The new collection address being set.                         |

***

### OnLockOwnershipTransferStarted <a href="#onlockownershiptransferstarted" id="onlockownershiptransferstarted"></a>

```
event onLockOwnershipTransferStarted(    uint256 lockId,     address currentOwner,     address pendingOwner)
```

Emitted on [TransferLockOwnership](https://developers.uncx.network/lockers-v3/technicalReference/UNCX_ProofOfReservesV2_UniV3#transferlockownership).

Parameters:

| Name         | Type    | Description                                       |
| ------------ | ------- | ------------------------------------------------- |
| lockId       | uint256 | The ID of the lock initiating ownership transfer. |
| currentOwner | address | The current owner initiating the transfer.        |
| pendingOwner | address | The proposed new owner.                           |

***

### OnTransferLockOwnership <a href="#ontransferlockownership" id="ontransferlockownership"></a>

```
event onTransferLockOwnership(    uint256 lockId,     address oldOwner,     address newOwner)
```

Emitted on [AcceptLockOwnership](https://developers.uncx.network/lockers-v3/technicalReference/UNCX_ProofOfReservesV2_UniV3#acceptlockownership).

Parameters:

| Name     | Type    | Description                                       |
| -------- | ------- | ------------------------------------------------- |
| lockId   | uint256 | The ID of the lock finalizing ownership transfer. |
| oldOwner | address | The address of the previous owner.                |
| newOwner | address | The address of the new owner.                     |

***

### OnSetMigrator <a href="#onsetmigrator" id="onsetmigrator"></a>

```
event onSetMigrator(    address migrator)
```

Emitted on SetMigrator.

Parameters:

| Name     | Type    | Description                            |
| -------- | ------- | -------------------------------------- |
| migrator | address | The address of the migrator being set. |

***

### OnSetUCF <a href="#onsetucf" id="onsetucf"></a>

```
event onSetUCF(    uint256 lockId,     uint256 ucf)
```

Emitted on setUCF.

Parameters:

| Name   | Type    | Description                                    |
| ------ | ------- | ---------------------------------------------- |
| lockId | uint256 | The ID of the lock where the UCF is being set. |
| ucf    | uint256 | The new UCF value being set.                   |