Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Added Some Documentation to Entity.sol, Fragment.sol, RezProxy.sol, RoyaltiesReceiver.sol, UnstructuredStorage.sol and Vault.sol #5

Open
wants to merge 4 commits into
base: clamor
Choose a base branch
from
Open

Added Some Documentation to Entity.sol, Fragment.sol, RezProxy.sol, RoyaltiesReceiver.sol, UnstructuredStorage.sol and Vault.sol #5

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
3a23253
Added Some Documentation to Entity.sol, Fragment.sol, RezProxy.sol, R…
Feb 21, 2022
c498ebd
Added More Documentation to Fragment.sol and RoyaltiesReceiver.sol
Feb 21, 2022
8b87500
Added More Documentation to Entity.sol, Fragment.sol and Vault.sol
Feb 22, 2022
6b1cb18
Added More Documentation to Entity.sol, Fragment.sol, Vault.sol, Util…
Feb 23, 2022
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
72 changes: 71 additions & 1 deletion contracts/Entity.sol
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,18 +15,25 @@ import "./IUtility.sol";
import "./RoyaltiesReceiver.sol";

struct FragmentInitData {
// The Proto-Fragment ID
uint256 fragmentId;
uint256 maxSupply;
// The address of the `Fragment` Contract
address fragmentsLibrary;
// The address of RezProxy Contract that delegates all its calls to a Vault Contract
address payable vault;
bool unique;
/// If `updatable` is false, the Fragment cannot be updated
bool updateable;
}

struct EntityData {
uint64 blockNum;
}


/// @title An Entity/Fragment Contract. This Contract stores one and only one Entity/Fragment.
/// @dev This contract is an ERC-721 Initializable Contract
contract Entity is ERC721Enumerable, Initializable, RoyaltiesReceiver {
using SafeERC20 for IERC20;
using Counters for Counters.Counter;
Expand All @@ -37,8 +44,11 @@ contract Entity is ERC721Enumerable, Initializable, RoyaltiesReceiver {
Counters.Counter private _tokenIds;

// mapping for fragments storage
// Maps a Fragment ID to an EntityData Struct
mapping(uint256 => EntityData) private _idToBlock;
// Maps a Fragment ID to a Data Hash
mapping(uint256 => bytes32) private _entityRefs;
// Maps a Data Hash To a Set of Fragment IDs
mapping(uint256 => EnumerableSet.UintSet) private _envToId;

IFragment private _fragmentsLibrary;
Expand All @@ -47,12 +57,15 @@ contract Entity is ERC721Enumerable, Initializable, RoyaltiesReceiver {
uint256 private _publicMintingPrice;
uint256 private _dutchStartBlock;
uint256 private _dutchStep;
// The ID of the Proto-Fragment that is linked with this Contract
uint256 private _fragmentId;
uint256 private _maxSupply;
uint256 private _maxPublicAmount;
uint256 private _publicCap;
uint8 private _publicMinting; // 0 no, 1 normal, 2 dutch auction
// ¿All Fragment Tokens must have a unique `environment`?
bool private _uniqueEnv;
// If this is false, the Fragment/Entity assosciated with this Entity Contract cannot be updated
bool private _canUpdate;

uint8 private constant NO_PUB_MINTING = 0;
Expand Down Expand Up @@ -100,6 +113,7 @@ contract Entity is ERC721Enumerable, Initializable, RoyaltiesReceiver {
}
}

/// @notice Returns the address of the owner of this Fragment/Entity
function fragmentOwner() public view returns (address) {
return _fragmentsLibrary.ownerOf(_fragmentId);
}
Expand All @@ -109,6 +123,12 @@ contract Entity is ERC721Enumerable, Initializable, RoyaltiesReceiver {
_;
}


/// @notice The de-facto Constructor of the Entity Smart Contract
/// @param tokenName - The name of the ERC-721 Token of this ERC-721 Contract
/// @param tokenSymbol - The symbol of the ERC-721 Token of this ERC-721 Contract
/// @param params - A Fragment. The fragment represented using the struct `FragmentInitData`
/// @dev The `initializer` modifier ensures this function is only called once
function bootstrap(
string calldata tokenName,
string calldata tokenSymbol,
Expand All @@ -135,6 +155,8 @@ contract Entity is ERC721Enumerable, Initializable, RoyaltiesReceiver {
setupRoyalties(payable(address(_vault)), FRAGMENT_ROYALTIES_BPS);
}

/// @notice Returns the tokenURI of the ERC-721 Token with ID `tokenId`. (Note: Every ERC-721 Contract must have this function)
/// The tokenURI on an NFT is a unique identifier of what the token "looks" like. A URI could be an API call over HTTPS, an IPFS hash, or anything else unique. (https://www.freecodecamp.org/news/how-to-make-an-nft-and-render-on-opensea-marketplace/#:~:text=come%20into%20play.-,TokenURI,hash%2C%20or%20anything%20else%20unique.)
function tokenURI(uint256 tokenId)
public
view
Expand All @@ -155,6 +177,7 @@ contract Entity is ERC721Enumerable, Initializable, RoyaltiesReceiver {
);
}

/// @notice Returns a JSON that represents the storefront-level metadata (for example a Collection in OpenSea) for your contract
function contractURI() public view returns (string memory) {
IUtility ut = IUtility(_fragmentsLibrary.getUtilityLibrary());
return
Expand All @@ -167,6 +190,10 @@ contract Entity is ERC721Enumerable, Initializable, RoyaltiesReceiver {
);
}

/// @notice Set the Contract Information
/// @param contractName - The contract name
/// @param desc - The contract description
/// @param url - The contract URL
function setContractInfo(
string calldata contractName,
string calldata desc,
Expand All @@ -177,18 +204,22 @@ contract Entity is ERC721Enumerable, Initializable, RoyaltiesReceiver {
_url = url;
}

/// @notice Returns the Fragment ID of the Entity Contract
function getFragment() external view returns (uint256) {
return _fragmentId;
}

/// @notice Returns he address of the `Fragment` Contract
function getLibrary() external view returns (address) {
return address(_fragmentsLibrary);
}

/// @notice Get the address of the Assosciated Vault Smart Contract
function getVault() external view returns (address) {
return address(_vault);
}

/// @notice Given a token with ID `tokenID`, return the data hash of the token and the Block Number where the Token Data was last modified
function getData(uint256 tokenId)
external
view
Expand All @@ -197,6 +228,7 @@ contract Entity is ERC721Enumerable, Initializable, RoyaltiesReceiver {
return (_entityRefs[tokenId], _idToBlock[tokenId].blockNum);
}

/// @notice Check if the Data Hash `dataHash` corresponds with the Token with id `id`
function containsId(uint160 dataHash, uint256 id)
external
view
Expand All @@ -205,10 +237,16 @@ contract Entity is ERC721Enumerable, Initializable, RoyaltiesReceiver {
return _envToId[dataHash].contains(id);
}

/// @notice Set the state variable `_delegate`. `_delegate` is in charge of authenticating sigatures on this contract
function setDelegate(address delegate) public onlyOwner {
_delegate = delegate;
}

/// @notice to update the Fragment with id `id` (only the wwner of the Fragment can call this function)
/// @dev Note: The Fragment must have been created with `updateable` set to true - otherwise the update is not allowed
/// @param signature - A signature from the the state variable `_delegate`
/// @param id - ¿The ID of the Fragment?
/// @param environment - ¿The New Data of the Fragment?
function update(
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

well be removed

bytes calldata signature,
uint256 id,
Expand Down Expand Up @@ -238,6 +276,7 @@ contract Entity is ERC721Enumerable, Initializable, RoyaltiesReceiver {
abi.encodePacked(_fragmentId, environment)
);


_envToId[uint256(dataHash)].add(id);

_entityRefs[id] = dataHash;
Expand All @@ -246,6 +285,7 @@ contract Entity is ERC721Enumerable, Initializable, RoyaltiesReceiver {
emit Updated(id);
}

/// @notice Uploads `amount` number of Fragment Tokens into this Contract, all of which have the data hash of `dataHash`. The owner of all these Fragment Tokens is `msg.sender`
function _upload(bytes32 dataHash, uint96 amount) internal {
for (uint256 i = 0; i < amount; i++) {
_tokenIds.increment();
Expand All @@ -255,6 +295,7 @@ contract Entity is ERC721Enumerable, Initializable, RoyaltiesReceiver {
"Max minting limit has been reached"
);

// Ensure either `_uniqueEnv` is false or `_envToId[uint256(dataHash)]` does not exist
require(
!_uniqueEnv || _envToId[uint256(dataHash)].length() == 0,
"Unique token already minted."
Expand All @@ -269,6 +310,9 @@ contract Entity is ERC721Enumerable, Initializable, RoyaltiesReceiver {
}
}

/// Adds `amount` Fragments to this Contract. NOTE: ONLY THE OWNER OF THIS CONTRACT CAN CALL THIS FUNCTION
/// @param environment - ¿
/// @param amount - The amount of Fragments to add to this contract
function upload(bytes calldata environment, uint96 amount)
external
onlyOwner
Expand All @@ -293,6 +337,14 @@ contract Entity is ERC721Enumerable, Initializable, RoyaltiesReceiver {
We use a signature to allow an entity off chain to verify that the content is valid and vouch for it.
If we want to skip that crafted address and random signatures can be used
*/
/// @notice Allows the `msg.sender` to mint `amount` number of Fragment Tokens (which all have the same `environment`)
/// @param `signature` - The signature provided by the `_delegate` state variable. The signature authenticates whether the the caller can mint/purchase these Fragment Tokens
/// @param `environment` - ¿
/// @param `amount` - The amount of Fragments the caller wants to purchase.
/// @dev The caller can only mint if the `_publicCap` is greater than `_tokenIds.current() + (amount - 1)`
/// The caller can only mint a maximum of `_maxPublicAmount` tokens
/// The price of each Token is `_publicMintingPrice`
///
function mint(
bytes calldata signature,
bytes calldata environment,
Expand Down Expand Up @@ -339,6 +391,9 @@ contract Entity is ERC721Enumerable, Initializable, RoyaltiesReceiver {
We use a signature to allow an entity off chain to verify that the content is valid and vouch for it.
If we want to skip that crafted address and random signatures can be used
*/
/// @notice Allows the caller to bid for a Fragment (Note: The Auction Type is a Dutch Action. Therefore, the price of the Fragment will drop after every time-step/block)
/// @param `signature` - The signature provided by the `_delegate` state variable. The signature authenticates whether the the caller can mint/purchase these Fragment Tokens
/// @param `environment` - ¿
function bid(bytes calldata signature, bytes calldata environment)
external
payable
Expand Down Expand Up @@ -391,6 +446,10 @@ contract Entity is ERC721Enumerable, Initializable, RoyaltiesReceiver {
_tokenIds.current() < _publicCap;
}

/// @notice ¿Allow the Fragment(s) in this Contract to be Publicly Minted at price `price`? NOTE: ONLY THE OWNER OF THIS CONTRACT CAN CALL THIS FUNCTION
/// @param price - The Minimum Price a Fragment can be bought for
/// @param maxAmount - The maximum number of Fragments that can be bought in a single function call
/// @param cap - The number of Fragments that are for sale
function setPublicSale(
uint256 price,
uint96 maxAmount,
Expand All @@ -402,7 +461,13 @@ contract Entity is ERC721Enumerable, Initializable, RoyaltiesReceiver {
_publicCap = cap;
assert(_publicCap <= _maxSupply);
}

// A Dutch auction is one of several similar types of auctions for buying or selling goods.
// Most commonly, it means an auction in which the auctioneer begins with a high asking price in the case of selling,
// and lowers it until some participant accepts the price, or it reaches a predetermined reserve price.
/// @notice ¿Allow the Fragment(s) in this Contract to be auctioned to the highest bigger (The exact auction type used is a Dutch Auction) NOTE: ONLY THE OWNER OF THIS CONTRACT CAN CALL THIS FUNCTION
/// @param maxPrice - The starting price
/// @param priceStep - The amount the price decreases at every time step
/// @param slots - The number of Fragments that are for sale
function openDutchAuction(
uint256 maxPrice,
uint256 priceStep,
Expand All @@ -416,10 +481,13 @@ contract Entity is ERC721Enumerable, Initializable, RoyaltiesReceiver {
assert(_publicCap <= _maxSupply);
}

/// @notice Stop public minting (i.e prevent further Fragments from being minted by anyone) NOTE: ONLY THE OWNER OF THIS CONTRACT CAN CALL THIS FUNCTION
function stopMarket() external onlyOwner {
_publicMinting = NO_PUB_MINTING;
}

/// @notice Transfer ERC-20 Token with token contract address `tokenAddress` and amount `tokenAmount` to `fragmentOwner()`.
/// NOTE: ONLY THE CONTRACT OWNER CAN THIS CALL THIS FUNCTION
function recoverERC20(address tokenAddress, uint256 tokenAmount)
external
onlyOwner
Expand All @@ -428,6 +496,8 @@ contract Entity is ERC721Enumerable, Initializable, RoyaltiesReceiver {
IERC20(tokenAddress).safeTransfer(fragmentOwner(), tokenAmount);
}

/// @notice Claim Ether that is held by this contract (i.e by this Vault Contract).
/// NOTE: ONLY THE CONTRACT OWNER CAN THIS CALL THIS FUNCTION
function recoverETH(uint256 amount) external onlyOwner {
// notice: fragmentOwner, not owner due to owner used for opensea workaround...
payable(fragmentOwner()).transfer(amount);
Expand Down
Loading