PrivatePool

Git Source

Inherits: ERC721TokenReceiver

Author: out.eth (@outdoteth)

A private pool is a an NFT AMM controlled by a single owner with concentrated liquidity, custom fee rates, stolen NFT filtering, custom NFT weightings, royalty support, and flash loans. You can create a pool and change these parameters to your liking. Deposit NFTs and base tokens (or ETH) into the pool to enable trading. Earn fees on each trade.

State Variables

baseToken

The address of the base ERC20 token.

address public baseToken;

nft

The address of the nft.

address public nft;

changeFee

The change/flash fee to 4 decimals of precision. For example, 0.0025 ETH = 25. 500 USDC = 5_000_000.

uint56 public changeFee;

feeRate

The buy/sell fee rate (in basis points) 200 = 2%

uint16 public feeRate;

initialized

Whether or not the pool has been initialized.

bool public initialized;

payRoyalties

Whether or not the pool pays royalties to the NFT creator on each trade.

bool public payRoyalties;

useStolenNftOracle

Whether or not the pool uses the stolen NFT oracle to check if an NFT is stolen.

bool public useStolenNftOracle;

virtualBaseTokenReserves

The virtual base token reserves used in the xy=k invariant. Changing this will change the liquidity depth and price of the pool.

uint128 public virtualBaseTokenReserves;

virtualNftReserves

The virtual nft reserves used in the xy=k invariant. Changing this will change the liquidity depth and price of the pool.

The virtual NFT reserves that a user sets. If it's desired to set the reserves to match 16 NFTs then the virtual reserves should be set to 16e18. If weights are enabled by setting the merkle root to be non-zero then the virtual reserves should be set to the sum of the weights of the NFTs; where floor NFTs all have a weight of 1e18. A rarer NFT may have a weight of 2.3e18 if it's 2.3x more valuable than a floor.

uint128 public virtualNftReserves;

merkleRoot

The merkle root of all the token weights in the pool. If the merkle root is set to bytes32(0) then all NFTs are set to have a weight of 1e18.

bytes32 public merkleRoot;

stolenNftOracle

The NFT oracle to check if an NFT is stolen.

address public immutable stolenNftOracle;

factory

The factory contract that created this pool.

address payable public immutable factory;

royaltyRegistry

The royalty registry from manifold.xyz.

address public immutable royaltyRegistry;

Functions

onlyOwner

modifier onlyOwner() virtual;

receive

receive() external payable;

constructor

*This is only called when the base implementation contract is deployed. The following immutable parameters are set:

• factory: The address of the factory contract

• royaltyRegistry: The address of the royalty registry from manifold.xyz

• stolenNftOracle: The address of the stolen NFT oracle These are all stored in immutable storage, which enables all minimal proxy contracts to read them without incurring additional deployment costs and re-initializing them at point of creation in the factory contract.*

constructor(address _factory, address _royaltyRegistry, address _stolenNftOracle);

initialize

Initializes the private pool and sets the initial parameters. Should only be called once by the factory.

function initialize(
    address _baseToken,
    address _nft,
    uint128 _virtualBaseTokenReserves,
    uint128 _virtualNftReserves,
    uint56 _changeFee,
    uint16 _feeRate,
    bytes32 _merkleRoot,
    bool _useStolenNftOracle,
    bool _payRoyalties
) public;

Parameters

Name	Type	Description
_baseToken	address	The address of the base token
_nft	address	The address of the NFT
_virtualBaseTokenReserves	uint128	The virtual base token reserves
_virtualNftReserves	uint128	The virtual NFT reserves
_changeFee	uint56
_feeRate	uint16	The fee rate (in basis points) 200 = 2%
_merkleRoot	bytes32	The merkle root
_useStolenNftOracle	bool	Whether or not the pool uses the stolen NFT oracle to check if an NFT is stolen
_payRoyalties	bool

buy

Buys NFTs from the pool, paying with base tokens from the caller. Then transfers the bought NFTs to the caller. The net cost depends on the current price, fee rate and assigned NFT weights.

DO NOT call this function directly unless you know what you are doing. Instead, use a wrapper contract that will check the max input amount and revert if the slippage is too high.

function buy(uint256[] calldata tokenIds, uint256[] calldata tokenWeights, MerkleMultiProof calldata proof)
    public
    payable
    returns (uint256 netInputAmount, uint256 feeAmount, uint256 protocolFeeAmount);

Parameters

Name	Type	Description
tokenIds	uint256[]	The token IDs of the NFTs to buy.
tokenWeights	uint256[]	The weights of the NFTs to buy.
proof	MerkleMultiProof	The merkle proof for the weights of each NFT to buy.

Returns

Name	Type	Description
netInputAmount	uint256	The amount of base tokens spent inclusive of fees.
feeAmount	uint256	The amount of base tokens spent on fees.
protocolFeeAmount	uint256

sell

Sells NFTs into the pool and transfers base tokens to the caller. NFTs are transferred from the caller to the pool. The net sale amount depends on the current price, fee rate and assigned NFT weights.

DO NOT call this function directly unless you know what you are doing. Instead, use a wrapper contract that will check the min output amount and revert if the slippage is too high.

function sell(
    uint256[] calldata tokenIds,
    uint256[] calldata tokenWeights,
    MerkleMultiProof calldata proof,
    IStolenNftOracle.Message[] memory stolenNftProofs
) public returns (uint256 netOutputAmount, uint256 feeAmount, uint256 protocolFeeAmount);

Parameters

Name	Type	Description
tokenIds	uint256[]	The token IDs of the NFTs to sell.
tokenWeights	uint256[]	The weights of the NFTs to sell.
proof	MerkleMultiProof	The merkle proof for the weights of each NFT to sell.
stolenNftProofs	Message.IStolenNftOracle[]	The proofs that show each NFT is not stolen.

Returns

Name	Type	Description
netOutputAmount	uint256	The amount of base tokens received inclusive of fees.
feeAmount	uint256	The amount of base tokens to pay in fees.
protocolFeeAmount	uint256

change

Changes a set of NFTs that the caller owns for another set of NFTs in the pool. The caller must approve the pool to transfer the NFTs. The sum of the caller's NFT weights must be less than or equal to the sum of the output pool NFTs weights. The caller must also pay a fee depending the net input weight and change fee amount.

function change(
    uint256[] memory inputTokenIds,
    uint256[] memory inputTokenWeights,
    MerkleMultiProof memory inputProof,
    IStolenNftOracle.Message[] memory stolenNftProofs,
    uint256[] memory outputTokenIds,
    uint256[] memory outputTokenWeights,
    MerkleMultiProof memory outputProof
) public payable returns (uint256 feeAmount, uint256 protocolFeeAmount);

Parameters

Name	Type	Description
inputTokenIds	uint256[]	The token IDs of the NFTs to change.
inputTokenWeights	uint256[]	The weights of the NFTs to change.
inputProof	MerkleMultiProof	The merkle proof for the weights of each NFT to change.
stolenNftProofs	Message.IStolenNftOracle[]	The proofs that show each input NFT is not stolen.
outputTokenIds	uint256[]	The token IDs of the NFTs to receive.
outputTokenWeights	uint256[]	The weights of the NFTs to receive.
outputProof	MerkleMultiProof	The merkle proof for the weights of each NFT to receive.

execute

Executes a transaction from the pool account to a target contract. The caller must be the owner of the pool. This allows for use cases such as claiming airdrops.

function execute(address target, bytes memory data) public payable onlyOwner returns (bytes memory);

Parameters

Name	Type	Description
target	address	The address of the target contract.
data	bytes	The data to send to the target contract.

Returns

Name	Type	Description
<none>	bytes	returnData The return data of the transaction.

deposit

Deposits base tokens and NFTs into the pool. The caller must approve the pool to transfer their NFTs and base tokens.

DO NOT call this function directly unless you know what you are doing. Instead, use a wrapper contract that will check the current price is within the desired bounds.

function deposit(uint256[] calldata tokenIds, uint256 baseTokenAmount) public payable;

Parameters

Name	Type	Description
tokenIds	uint256[]	The token IDs of the NFTs to deposit.
baseTokenAmount	uint256	The amount of base tokens to deposit.

withdraw

Withdraws NFTs and tokens from the pool. Can only be called by the owner of the pool.

function withdraw(address _nft, uint256[] calldata tokenIds, address token, uint256 tokenAmount) public onlyOwner;

Parameters

Name	Type	Description
_nft	address	The address of the NFT.
tokenIds	uint256[]	The token IDs of the NFTs to withdraw.
token	address	The address of the token to withdraw.
tokenAmount	uint256	The amount of tokens to withdraw.

setVirtualReserves

Sets the virtual base token reserves and virtual NFT reserves. Can only be called by the owner of the pool. These parameters affect the price and liquidity depth of the pool.

function setVirtualReserves(uint128 newVirtualBaseTokenReserves, uint128 newVirtualNftReserves) public onlyOwner;

Parameters

Name	Type	Description
newVirtualBaseTokenReserves	uint128	The new virtual base token reserves.
newVirtualNftReserves	uint128	The new virtual NFT reserves.

setMerkleRoot

Sets the merkle root. Can only be called by the owner of the pool. The merkle root is used to validate the NFT weights.

function setMerkleRoot(bytes32 newMerkleRoot) public onlyOwner;

Parameters

Name	Type	Description
newMerkleRoot	bytes32	The new merkle root.

setFeeRate

Sets the fee rate. Can only be called by the owner of the pool. The fee rate is used to calculate the fee amount when swapping or changing NFTs. The fee rate is in basis points (1/100th of a percent). For example, 10_000 == 100%, 200 == 2%, 1 == 0.01%.

function setFeeRate(uint16 newFeeRate) public onlyOwner;

Parameters

Name	Type	Description
newFeeRate	uint16	The new fee rate (in basis points)

setUseStolenNftOracle

Sets the whether or not to use the stolen NFT oracle. Can only be called by the owner of the pool. The stolen NFT oracle is used to check if an NFT is stolen.

function setUseStolenNftOracle(bool newUseStolenNftOracle) public onlyOwner;

Parameters

Name	Type	Description
newUseStolenNftOracle	bool	The new use stolen NFT oracle flag.

setPayRoyalties

Sets the pay royalties flag. Can only be called by the owner of the pool. If royalties are enabled then the pool will pay royalties when buying or selling NFTs.

function setPayRoyalties(bool newPayRoyalties) public onlyOwner;

Parameters

Name	Type	Description
newPayRoyalties	bool	The new pay royalties flag.

setAllParameters

Updates all parameter settings in one go.

function setAllParameters(
    uint128 newVirtualBaseTokenReserves,
    uint128 newVirtualNftReserves,
    bytes32 newMerkleRoot,
    uint16 newFeeRate,
    bool newUseStolenNftOracle,
    bool newPayRoyalties
) public;

Parameters

Name	Type	Description
newVirtualBaseTokenReserves	uint128	The new virtual base token reserves.
newVirtualNftReserves	uint128	The new virtual NFT reserves.
newMerkleRoot	bytes32	The new merkle root.
newFeeRate	uint16	The new fee rate (in basis points)
newUseStolenNftOracle	bool	The new use stolen NFT oracle flag.
newPayRoyalties	bool	The new pay royalties flag.

flashLoan

Executes a flash loan.

function flashLoan(IERC3156FlashBorrower receiver, address token, uint256 tokenId, bytes calldata data)
    external
    payable
    returns (bool);

Parameters

Name	Type	Description
receiver	IERC3156FlashBorrower	The receiver of the flash loan.
token	address	The address of the NFT contract.
tokenId	uint256	The ID of the NFT.
data	bytes	The data to pass to the receiver.

Returns

Name	Type	Description
<none>	bool	success Whether or not the flash loan was successful.

sumWeightsAndValidateProof

Sums the weights of each NFT and validates that the weights are correct by verifying the merkle proof.

function sumWeightsAndValidateProof(
    uint256[] memory tokenIds,
    uint256[] memory tokenWeights,
    MerkleMultiProof memory proof
) public view returns (uint256);

Parameters

Name	Type	Description
tokenIds	uint256[]	The token IDs of the NFTs to sum the weights for.
tokenWeights	uint256[]	The weights of each NFT in the token IDs array.
proof	MerkleMultiProof	The merkle proof for the weights of each NFT.

Returns

Name	Type	Description
<none>	uint256	sum The sum of the weights of each NFT.

_getRoyalty

Gets the royalty and recipient for a given NFT and sale price. Looks up the royalty info from the manifold registry.

function _getRoyalty(uint256 tokenId, uint256 salePrice)
    internal
    view
    returns (uint256 royaltyFee, address recipient);

Parameters

Name	Type	Description
tokenId	uint256	The token ID of the NFT.
salePrice	uint256	The sale price of the NFT.

Returns

Name	Type	Description
royaltyFee	uint256	The royalty fee to pay.
recipient	address	The address to pay the royalty fee to.

buyQuote

Returns the required input of buying a given amount of NFTs inclusive of the fee which is dependent on the currently set fee rate.

function buyQuote(uint256 outputAmount)
    public
    view
    returns (uint256 netInputAmount, uint256 feeAmount, uint256 protocolFeeAmount);

Parameters

Name	Type	Description
outputAmount	uint256	The amount of NFTs to buy multiplied by 1e18.

Returns

Name	Type	Description
netInputAmount	uint256	The required input amount of base tokens inclusive of the fee.
feeAmount	uint256	The fee amount.
protocolFeeAmount	uint256

sellQuote

Returns the output amount of selling a given amount of NFTs inclusive of the fee which is dependent on the currently set fee rate.

function sellQuote(uint256 inputAmount)
    public
    view
    returns (uint256 netOutputAmount, uint256 feeAmount, uint256 protocolFeeAmount);

Parameters

Name	Type	Description
inputAmount	uint256	The amount of NFTs to sell multiplied by 1e18.

Returns

Name	Type	Description
netOutputAmount	uint256	The output amount of base tokens inclusive of the fee.
feeAmount	uint256	The fee amount.
protocolFeeAmount	uint256

changeFeeQuote

Returns the fee required to change a given amount of NFTs. The fee is based on the current changeFee (which contains 4 decimals of precision) multiplied by some exponent depending on the base token decimals.

function changeFeeQuote(uint256 inputAmount) public view returns (uint256 feeAmount, uint256 protocolFeeAmount);

Parameters

Name	Type	Description
inputAmount	uint256	The amount of NFTs to change multiplied by 1e18.

Returns

Name	Type	Description
feeAmount	uint256	The fee amount.
protocolFeeAmount	uint256	The protocol fee amount.

price

Returns the price of the pool to 18 decimals of accuracy.

function price() public view returns (uint256);

Returns

Name	Type	Description
<none>	uint256	price The price of the pool.

flashFee

Returns the fee required to flash swap a given NFT.

function flashFee(address, uint256) public view returns (uint256);

Returns

Name	Type	Description
<none>	uint256	feeAmount The fee amount.

flashFeeToken

Returns the token that is used to pay the flash fee.

function flashFeeToken() public view returns (address);

availableForFlashLoan

Returns whether or not an NFT is available for a flash loan.

function availableForFlashLoan(address token, uint256 tokenId) public view returns (bool);

Parameters

Name	Type	Description
token	address	The address of the NFT contract.
tokenId	uint256	The ID of the NFT.

Returns

Name	Type	Description
<none>	bool	available Whether or not the NFT is available for a flash loan.

Events

Initialize

event Initialize(
    address indexed baseToken,
    address indexed nft,
    uint128 virtualBaseTokenReserves,
    uint128 virtualNftReserves,
    uint56 changeFee,
    uint16 feeRate,
    bytes32 merkleRoot,
    bool useStolenNftOracle,
    bool payRoyalties
);

Buy

event Buy(
    uint256[] tokenIds,
    uint256[] tokenWeights,
    uint256 inputAmount,
    uint256 feeAmount,
    uint256 protocolFeeAmount,
    uint256 royaltyFeeAmount
);

Sell

event Sell(
    uint256[] tokenIds,
    uint256[] tokenWeights,
    uint256 outputAmount,
    uint256 feeAmount,
    uint256 protocolFeeAmount,
    uint256 royaltyFeeAmount
);

Deposit

event Deposit(uint256[] tokenIds, uint256 baseTokenAmount);

Withdraw

event Withdraw(address indexed nft, uint256[] tokenIds, address token, uint256 amount);

Change

event Change(
    uint256[] inputTokenIds,
    uint256[] inputTokenWeights,
    uint256[] outputTokenIds,
    uint256[] outputTokenWeights,
    uint256 feeAmount,
    uint256 protocolFeeAmount
);

SetVirtualReserves

event SetVirtualReserves(uint128 virtualBaseTokenReserves, uint128 virtualNftReserves);

SetMerkleRoot

event SetMerkleRoot(bytes32 merkleRoot);

SetFeeRate

event SetFeeRate(uint16 feeRate);

SetUseStolenNftOracle

event SetUseStolenNftOracle(bool useStolenNftOracle);

SetPayRoyalties

event SetPayRoyalties(bool payRoyalties);

Errors

AlreadyInitialized

error AlreadyInitialized();

Unauthorized

error Unauthorized();

InvalidEthAmount

error InvalidEthAmount();

InvalidMerkleProof

error InvalidMerkleProof();

InsufficientInputWeight

error InsufficientInputWeight();

FeeRateTooHigh

error FeeRateTooHigh();

NotAvailableForFlashLoan

error NotAvailableForFlashLoan();

FlashLoanFailed

error FlashLoanFailed();

InvalidRoyaltyFee

error InvalidRoyaltyFee();

Structs

MerkleMultiProof

Merkle proof input for a sparse merkle multi proof. It can be generated with a library like: https://github.com/OpenZeppelin/merkle-tree#treegetmultiproof

struct MerkleMultiProof {
    bytes32[] proof;
    bool[] flags;
}