From de9aab1178365e14f2402bc588fb7954286db375 Mon Sep 17 00:00:00 2001 From: Tomi_Ohl Date: Fri, 19 Apr 2024 17:42:47 +0200 Subject: [PATCH] Update docs --- docs/contracts/BasicGuildRewardNFT.md | 4 +- docs/contracts/ConfigurableGuildRewardNFT.md | 195 +++++++++++++++ docs/contracts/GuildRewardNFTFactory.md | 16 ++ .../interfaces/IBasicGuildRewardNFT.md | 12 +- .../interfaces/IConfigurableGuildRewardNFT.md | 208 ++++++++++++++++ .../interfaces/IGuildRewardNFTFactory.md | 37 ++- .../token/OptionallySoulboundERC721.md | 224 ++++++++++++++++++ 7 files changed, 686 insertions(+), 10 deletions(-) create mode 100644 docs/contracts/ConfigurableGuildRewardNFT.md create mode 100644 docs/contracts/interfaces/IConfigurableGuildRewardNFT.md create mode 100644 docs/contracts/token/OptionallySoulboundERC721.md diff --git a/docs/contracts/BasicGuildRewardNFT.md b/docs/contracts/BasicGuildRewardNFT.md index 22f1f6d..dd9d86f 100644 --- a/docs/contracts/BasicGuildRewardNFT.md +++ b/docs/contracts/BasicGuildRewardNFT.md @@ -150,9 +150,9 @@ function hasTheUserIdClaimed( ) external returns (bool claimed) ``` -Whether a userId has minted a token. +Whether a userId has claimed a token. -Used to prevent double mints in the same block. +Used to prevent double claims in the same block. #### Parameters diff --git a/docs/contracts/ConfigurableGuildRewardNFT.md b/docs/contracts/ConfigurableGuildRewardNFT.md new file mode 100644 index 0000000..9cfecf5 --- /dev/null +++ b/docs/contracts/ConfigurableGuildRewardNFT.md @@ -0,0 +1,195 @@ +# ConfigurableGuildRewardNFT + +An NFT distributed as a reward for Guild.xyz users. + +## Variables + +### factoryProxy + +```solidity +address factoryProxy +``` + +The address of the proxy to be used when interacting with the factory. + +_Used to access the factory's address when interacting through minimal proxies._ + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | + +### mintableAmountPerUser + +```solidity +uint256 mintableAmountPerUser +``` + +The maximum amount of tokens a Guild user can claim from the token. + +_Doesn't matter if they are claimed in the same transaction or separately._ + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | + +### cid + +```solidity +string cid +``` + +The cid for tokenURI. + +### claimedTokens + +```solidity +mapping(uint256 => uint256) claimedTokens +``` + +The number of claimed tokens by userIds. + +## Functions + +### initialize + +```solidity +function initialize( + struct IGuildRewardNFTFactory.ConfigurableNFTConfig nftConfig, + address factoryProxyAddress +) public +``` + +Sets metadata and the associated addresses. + +Initializer function callable only once. + +#### Parameters + +| Name | Type | Description | +| :--- | :--- | :---------- | +| `nftConfig` | struct IGuildRewardNFTFactory.ConfigurableNFTConfig | See struct ConfigurableNFTConfig in IGuildRewardNFTFactory. | +| `factoryProxyAddress` | address | The address of the factory. | + +### claim + +```solidity +function claim( + uint256 amount, + address receiver, + uint256 userId, + bytes signature +) external +``` + +Claims tokens to the given address. + +#### Parameters + +| Name | Type | Description | +| :--- | :--- | :---------- | +| `amount` | uint256 | The amount of tokens to mint. Should be less or equal to mintableAmountPerUser. | +| `receiver` | address | The address that receives the token. | +| `userId` | uint256 | The id of the user on Guild. | +| `signature` | bytes | The following signed by validSigner: amount, receiver, userId, chainId, the contract's address. | + +### burn + +```solidity +function burn( + uint256[] tokenIds, + uint256 userId, + bytes signature +) external +``` + +Burns tokens from the sender. + +#### Parameters + +| Name | Type | Description | +| :--- | :--- | :---------- | +| `tokenIds` | uint256[] | The tokenIds to burn. All of them should belong to userId. | +| `userId` | uint256 | The id of the user on Guild. | +| `signature` | bytes | The following signed by validSigner: amount, receiver, userId, chainId, the contract's address. | + +### updateTokenURI + +```solidity +function updateTokenURI( + string newCid +) external +``` + +Updates the cid for tokenURI. + +Only callable by the owner. + +#### Parameters + +| Name | Type | Description | +| :--- | :--- | :---------- | +| `newCid` | string | The new cid that points to the updated image. | + +### balanceOf + +```solidity +function balanceOf( + uint256 userId +) external returns (uint256 amount) +``` + +Returns the number of tokens the user claimed. + +Analogous to balanceOf(address), but works with Guild user ids. + +#### Parameters + +| Name | Type | Description | +| :--- | :--- | :---------- | +| `userId` | uint256 | The id of the user on Guild. | + +#### Return Values + +| Name | Type | Description | +| :--- | :--- | :---------- | +| `amount` | uint256 | The number of tokens the userId has claimed. | +### tokenURI + +```solidity +function tokenURI( + uint256 tokenId +) public returns (string) +``` + +See {IERC721Metadata-tokenURI}. + +#### Parameters + +| Name | Type | Description | +| :--- | :--- | :---------- | +| `tokenId` | uint256 | | + +### isValidSignature + +```solidity +function isValidSignature( + uint256 amount, + address receiver, + uint256 userId, + bytes signature +) internal returns (bool) +``` + +Checks the validity of the signature for the given params. + +#### Parameters + +| Name | Type | Description | +| :--- | :--- | :---------- | +| `amount` | uint256 | | +| `receiver` | address | | +| `userId` | uint256 | | +| `signature` | bytes | | + diff --git a/docs/contracts/GuildRewardNFTFactory.md b/docs/contracts/GuildRewardNFTFactory.md index d8ba5b2..b70df0e 100644 --- a/docs/contracts/GuildRewardNFTFactory.md +++ b/docs/contracts/GuildRewardNFTFactory.md @@ -89,6 +89,22 @@ Deploys a minimal proxy for a basic NFT. | `tokenTreasury` | address payable | The address that will collect the prices of the minted deployed tokens. | | `tokenFee` | uint256 | The price of every mint in wei. | +### deployConfigurableNFT + +```solidity +function deployConfigurableNFT( + struct IGuildRewardNFTFactory.ConfigurableNFTConfig nftConfig +) external +``` + +Deploys a minimal proxy for a configurable NFT. + +#### Parameters + +| Name | Type | Description | +| :--- | :--- | :---------- | +| `nftConfig` | struct IGuildRewardNFTFactory.ConfigurableNFTConfig | The config to initialize the token to be deployed with. | + ### setNFTImplementation ```solidity diff --git a/docs/contracts/interfaces/IBasicGuildRewardNFT.md b/docs/contracts/interfaces/IBasicGuildRewardNFT.md index c366281..6002f15 100644 --- a/docs/contracts/interfaces/IBasicGuildRewardNFT.md +++ b/docs/contracts/interfaces/IBasicGuildRewardNFT.md @@ -48,9 +48,9 @@ function hasTheUserIdClaimed( ) external returns (bool claimed) ``` -Whether a userId has minted a token. +Whether a userId has claimed a token. -Used to prevent double mints in the same block. +Used to prevent double claims in the same block. #### Parameters @@ -87,10 +87,10 @@ Initializer function callable only once. | :--- | :--- | :---------- | | `name` | string | The name of the token. | | `symbol` | string | The symbol of the token. | -| `cid` | string | The cid used to construct the tokenURI for the token to be minted. | -| `tokenOwner` | address | The address that will be the owner of the deployed token. | +| `cid` | string | The cid used to construct the tokenURI for the token to be deployed. | +| `tokenOwner` | address | The address that will be the owner of the token. | | `treasury` | address payable | The address that will receive the price paid for the token. | -| `tokenFee` | uint256 | The price of every mint in wei. | +| `tokenFee` | uint256 | The price of every claim in wei. | | `factoryProxyAddress` | address | The address of the factory. | ### claim @@ -202,7 +202,7 @@ Error thrown when an incorrect amount of fee is attempted to be paid. | Name | Type | Description | | ---- | ---- | ----------- | | paid | uint256 | The amount of funds received. | -| requiredAmount | uint256 | The amount of fees required for minting. | +| requiredAmount | uint256 | The amount of fees required for claiming. | ### IncorrectSender diff --git a/docs/contracts/interfaces/IConfigurableGuildRewardNFT.md b/docs/contracts/interfaces/IConfigurableGuildRewardNFT.md new file mode 100644 index 0000000..2c69dd7 --- /dev/null +++ b/docs/contracts/interfaces/IConfigurableGuildRewardNFT.md @@ -0,0 +1,208 @@ +# IConfigurableGuildRewardNFT + +An NFT distributed as a reward for Guild.xyz users. + +## Functions + +### factoryProxy + +```solidity +function factoryProxy() external returns (address factoryAddress) +``` + +The address of the proxy to be used when interacting with the factory. + +Used to access the factory's address when interacting through minimal proxies. + +#### Return Values + +| Name | Type | Description | +| :--- | :--- | :---------- | +| `factoryAddress` | address | The address of the factory. | +### mintableAmountPerUser + +```solidity +function mintableAmountPerUser() external returns (uint256 mintableAmountPerUser) +``` + +The maximum amount of tokens a Guild user can claim from the token. + +Doesn't matter if they are claimed in the same transaction or separately. + +#### Return Values + +| Name | Type | Description | +| :--- | :--- | :---------- | +| `mintableAmountPerUser` | uint256 | The amount of tokens. | +### balanceOf + +```solidity +function balanceOf( + uint256 userId +) external returns (uint256 amount) +``` + +Returns the number of tokens the user claimed. + +Analogous to balanceOf(address), but works with Guild user ids. + +#### Parameters + +| Name | Type | Description | +| :--- | :--- | :---------- | +| `userId` | uint256 | The id of the user on Guild. | + +#### Return Values + +| Name | Type | Description | +| :--- | :--- | :---------- | +| `amount` | uint256 | The number of tokens the userId has claimed. | +### initialize + +```solidity +function initialize( + struct IGuildRewardNFTFactory.ConfigurableNFTConfig nftConfig, + address factoryProxyAddress +) external +``` + +Sets metadata and the associated addresses. + +Initializer function callable only once. + +#### Parameters + +| Name | Type | Description | +| :--- | :--- | :---------- | +| `nftConfig` | struct IGuildRewardNFTFactory.ConfigurableNFTConfig | See struct ConfigurableNFTConfig in IGuildRewardNFTFactory. | +| `factoryProxyAddress` | address | The address of the factory. | + +### claim + +```solidity +function claim( + uint256 amount, + address receiver, + uint256 userId, + bytes signature +) external +``` + +Claims tokens to the given address. + +#### Parameters + +| Name | Type | Description | +| :--- | :--- | :---------- | +| `amount` | uint256 | The amount of tokens to mint. Should be less or equal to mintableAmountPerUser. | +| `receiver` | address | The address that receives the token. | +| `userId` | uint256 | The id of the user on Guild. | +| `signature` | bytes | The following signed by validSigner: amount, receiver, userId, chainId, the contract's address. | + +### burn + +```solidity +function burn( + uint256[] tokenIds, + uint256 userId, + bytes signature +) external +``` + +Burns tokens from the sender. + +#### Parameters + +| Name | Type | Description | +| :--- | :--- | :---------- | +| `tokenIds` | uint256[] | The tokenIds to burn. All of them should belong to userId. | +| `userId` | uint256 | The id of the user on Guild. | +| `signature` | bytes | The following signed by validSigner: amount, receiver, userId, chainId, the contract's address. | + +### updateTokenURI + +```solidity +function updateTokenURI( + string newCid +) external +``` + +Updates the cid for tokenURI. + +Only callable by the owner. + +#### Parameters + +| Name | Type | Description | +| :--- | :--- | :---------- | +| `newCid` | string | The new cid that points to the updated image. | + +## Events + +### Claimed + +```solidity +event Claimed( + address receiver, + uint256 tokenId +) +``` + +Event emitted whenever a claim succeeds. + +#### Parameters + +| Name | Type | Description | +| :--- | :--- | :---------- | +| `receiver` | address | The address that received the tokens. | +| `tokenId` | uint256 | The id of the token. | +### MetadataUpdate + +```solidity +event MetadataUpdate( +) +``` + +Event emitted whenever the cid is updated. + +## Custom errors + +### AlreadyClaimed + +```solidity +error AlreadyClaimed() +``` + +Error thrown when the token is already claimed. + +### IncorrectFee + +```solidity +error IncorrectFee(uint256 paid, uint256 requiredAmount) +``` + +Error thrown when an incorrect amount of fee is attempted to be paid. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| paid | uint256 | The amount of funds received. | +| requiredAmount | uint256 | The amount of fees required for claiming a single token. | + +### IncorrectSender + +```solidity +error IncorrectSender() +``` + +Error thrown when the sender is not permitted to do a specific action. + +### IncorrectSignature + +```solidity +error IncorrectSignature() +``` + +Error thrown when the supplied signature is invalid. + diff --git a/docs/contracts/interfaces/IGuildRewardNFTFactory.md b/docs/contracts/interfaces/IGuildRewardNFTFactory.md index e27f03c..885b53f 100644 --- a/docs/contracts/interfaces/IGuildRewardNFTFactory.md +++ b/docs/contracts/interfaces/IGuildRewardNFTFactory.md @@ -84,6 +84,22 @@ Deploys a minimal proxy for a basic NFT. | `tokenTreasury` | address payable | The address that will collect the prices of the minted deployed tokens. | | `tokenFee` | uint256 | The price of every mint in wei. | +### deployConfigurableNFT + +```solidity +function deployConfigurableNFT( + struct IGuildRewardNFTFactory.ConfigurableNFTConfig nftConfig +) external +``` + +Deploys a minimal proxy for a configurable NFT. + +#### Parameters + +| Name | Type | Description | +| :--- | :--- | :---------- | +| `nftConfig` | struct IGuildRewardNFTFactory.ConfigurableNFTConfig | The config to initialize the token to be deployed with. | + ### getDeployedTokenContracts ```solidity @@ -167,7 +183,8 @@ Event emitted when an NFT implementation is changed. ```solidity event RewardNFTDeployed( address deployer, - address tokenAddress + address tokenAddress, + enum IGuildRewardNFTFactory.ContractType contractType ) ``` @@ -179,6 +196,7 @@ Event emitted when a new NFT is deployed. | :--- | :--- | :---------- | | `deployer` | address | The address that deployed the token. | | `tokenAddress` | address | The address of the token. | +| `contractType` | enum IGuildRewardNFTFactory.ContractType | The type of the NFT deployed. | ### ValidSignerChanged ```solidity @@ -201,7 +219,22 @@ Event emitted when the validSigner is changed. ```solidity enum ContractType { - BASIC_NFT + BASIC_NFT, + CONFIGURABLE_NFT +} +``` +### ConfigurableNFTConfig + +```solidity +struct ConfigurableNFTConfig { + string name; + string symbol; + string cid; + address tokenOwner; + address payable treasury; + uint256 tokenFee; + bool soulbound; + uint256 mintableAmountPerUser; } ``` ### Deployment diff --git a/docs/contracts/token/OptionallySoulboundERC721.md b/docs/contracts/token/OptionallySoulboundERC721.md new file mode 100644 index 0000000..5dbe59d --- /dev/null +++ b/docs/contracts/token/OptionallySoulboundERC721.md @@ -0,0 +1,224 @@ +# OptionallySoulboundERC721 + +An enumerable ERC721 that's optionally soulbound. + +Allowance and transfer-related functions are disabled in soulbound mode. + +Inheriting from upgradeable contracts here - even though we're using it in a non-upgradeable way, +we still want it to be initializable + +## Variables + +### soulbound + +```solidity +bool soulbound +``` + +Whether the token is set as soulbound. + +## Functions + +### __OptionallySoulboundERC721_init + +```solidity +function __OptionallySoulboundERC721_init( + string name_, + string symbol_, + bool soulbound_ +) internal +``` + +#### Parameters + +| Name | Type | Description | +| :--- | :--- | :---------- | +| `name_` | string | | +| `symbol_` | string | | +| `soulbound_` | bool | | + +### supportsInterface + +```solidity +function supportsInterface( + bytes4 interfaceId +) public returns (bool) +``` + +See {IERC165-supportsInterface}. + +#### Parameters + +| Name | Type | Description | +| :--- | :--- | :---------- | +| `interfaceId` | bytes4 | | + +### locked + +```solidity +function locked( + uint256 tokenId +) external returns (bool) +``` + +Returns the locking status of an Soulbound Token + +SBTs assigned to zero address are considered invalid, and queries +about them do throw. + +#### Parameters + +| Name | Type | Description | +| :--- | :--- | :---------- | +| `tokenId` | uint256 | The identifier for an SBT. | + +### approve + +```solidity +function approve( + address to, + uint256 tokenId +) public +``` + +#### Parameters + +| Name | Type | Description | +| :--- | :--- | :---------- | +| `to` | address | | +| `tokenId` | uint256 | | + +### setApprovalForAll + +```solidity +function setApprovalForAll( + address operator, + bool approved +) public +``` + +#### Parameters + +| Name | Type | Description | +| :--- | :--- | :---------- | +| `operator` | address | | +| `approved` | bool | | + +### isApprovedForAll + +```solidity +function isApprovedForAll( + address owner, + address operator +) public returns (bool) +``` + +#### Parameters + +| Name | Type | Description | +| :--- | :--- | :---------- | +| `owner` | address | | +| `operator` | address | | + +### transferFrom + +```solidity +function transferFrom( + address from, + address to, + uint256 tokenId +) public +``` + +#### Parameters + +| Name | Type | Description | +| :--- | :--- | :---------- | +| `from` | address | | +| `to` | address | | +| `tokenId` | uint256 | | + +### safeTransferFrom + +```solidity +function safeTransferFrom( + address from, + address to, + uint256 tokenId +) public +``` + +#### Parameters + +| Name | Type | Description | +| :--- | :--- | :---------- | +| `from` | address | | +| `to` | address | | +| `tokenId` | uint256 | | + +### safeTransferFrom + +```solidity +function safeTransferFrom( + address from, + address to, + uint256 tokenId, + bytes data +) public +``` + +#### Parameters + +| Name | Type | Description | +| :--- | :--- | :---------- | +| `from` | address | | +| `to` | address | | +| `tokenId` | uint256 | | +| `data` | bytes | | + +### _beforeTokenTransfer + +```solidity +function _beforeTokenTransfer( + address from, + address to, + uint256 firstTokenId, + uint256 batchSize +) internal +``` + +Used for minting/burning even when soulbound. + +#### Parameters + +| Name | Type | Description | +| :--- | :--- | :---------- | +| `from` | address | | +| `to` | address | | +| `firstTokenId` | uint256 | | +| `batchSize` | uint256 | | + +## Custom errors + +### NonExistentToken + +```solidity +error NonExistentToken(uint256 tokenId) +``` + +Error thrown when trying to query info about a token that's not (yet) minted. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenId | uint256 | The queried id. | + +### Soulbound + +```solidity +error Soulbound() +``` + +Error thrown when a function's execution is not possible, because the soulbound mode is on. +