diff --git a/docs/klaytn-contracts/nft-royalty/introduction.md b/docs/klaytn-contracts/nft-royalty/introduction.md new file mode 100644 index 0000000..6b16ec5 --- /dev/null +++ b/docs/klaytn-contracts/nft-royalty/introduction.md @@ -0,0 +1,118 @@ +--- +title: 🎗 NFT Royalty +sidebar_label: Introduction +--- + +## Introduction + +In general, the creators of a unique asset (NFT) profit from the asset's initial sale. However, this unique asset may appreciate in value over time, and the creator may not benefit from this increase in value. NFT Royalties is based on this approach, in which creators are continuously rewarded for the value of their work after a subsequent sale beyond the initial sale. + +## Definition of NFT Royalties +NFT royalties are payments made to the original creator of a digital asset for each time that asset is resold. This means that when this asset is sold, a certain percentage is paid to the creator as a reward for the asset's value. + +For example, a creator may have published an asset on the Marketplace and initially sold it for 10,000 KLAY. Simultaneously, the creator included a 10% NFT royalty percentage for subsequent sales. Thus, if the buyer resells and earns 100,000 KLAY from the resale, the original creator will receive 10% (10,000 KLAY). + +Isn't that cool? NFT royalties let creators passively earn from their work. + +## How does it work? +When creatives use NFT Royalty for subsequent sales, they will continue to earn money from their work. The creator usually specifies the royalty policy at the platform or on-chain level. + +Typically, the procedure is as follows: +* NFT is minted with a royalty percentage added by a creator, either on the platform or on the blockchain. +* When there is a subsequent sale, the creator is paid + +## NFT Marketplaces and NFT Royalties +Marketplaces determine whether the royalty details in a NFT smart contract will be implemented or not. This brings us to the fact that not all marketplaces honor NFT royalties. Further, because of the peculiarities of different NFT platforms, there exist unique royalty payment implementations that are not easily usable by other marketplaces. Thus, making royalty policies from other marketplaces or platforms not automatically transferrable. + +For example, if an NFT with a royalty policy is sold on Rarible and then listed on OpenSea, the original creator will not be paid from subsequent sales because the royalty policy was not transferred. ERC2981 was created in response to the need to standardize royalty payment across all platforms. The ERC2981 standard addresses this issue by allowing accurate royalty payments to be implemented regardless of the marketplace where the NFT is sold or resold. + +This standard is implemented by ensuring that marketplaces and individuals retrieve royalty payment information via royaltyInfo(), which specifies how much to pay to the creator address for a given sale price. To learn more about this standard, check this guide + + +This standard is applicable in the metaverse, where NFT royalties can be attached to in-game items and collectibles, digital accessories, virtual lands, and so on. + +## Code Sample + +```javascript +// SPDX-License-Identifier: MIT +pragma solidity ^0.8.4; + +import "@klaytn/contracts/KIP/token/KIP17/KIP17.sol"; +import "@klaytn/contracts/KIP/token/KIP17/extensions/KIP17URIStorage.sol"; +import "@klaytn/contracts/access/Ownable.sol"; +import "@klaytn/contracts/utils/Counters.sol"; +import "@klaytn/contracts/token/common/ERC2981.sol"; + +contract MyToken is KIP17, KIP17URIStorage, Ownable, ERC2981 { + using Counters for Counters.Counter; + + Counters.Counter private _tokenIdCounter; + + constructor() KIP17("MyToken", "MTK") {} + + function safeMint(address to, string memory uri) public onlyOwner { + uint256 tokenId = _tokenIdCounter.current(); + _tokenIdCounter.increment(); + _safeMint(to, tokenId); + _setTokenURI(tokenId, uri); + } + + function mintNFTWithRoyalty(address recipient, string memory uri, address royaltyReceiver, uint96 feeNumerator) + public + onlyOwner + returns (uint256) + { + uint256 tokenId = _tokenIdCounter.current(); + _tokenIdCounter.increment(); + _safeMint(recipient, tokenId); + _setTokenURI(tokenId, uri); + _setTokenRoyalty(tokenId, royaltyReceiver, feeNumerator); + + return tokenId; + } + + // The following functions are overrides required by Solidity. + + function _burn(uint256 tokenId) internal override(KIP17, KIP17URIStorage) { + super._burn(tokenId); + } + + function tokenURI(uint256 tokenId) + public + view + override(KIP17, KIP17URIStorage) + returns (string memory) + { + return super.tokenURI(tokenId); + } + + function supportsInterface(bytes4 interfaceId) + public + view + override(KIP17, ERC2981) + returns (bool) + { + return super.supportsInterface(interfaceId); + } +} + +``` + +## Important Note + +The code above is a standardized implementation of retrieving royalty payment information from a KIP17 contract. It shows how royalty information can be set for a single token id using the **_setTokenRoyalty** in the **mintNFTWithRoyalty** function. Similarly, royalty information can be specified globally for all tokens using **_setDefaultRoyalty**. + +Further, royalty is specified as a fraction of Sale Price: + +(salePrice * feeNumerator) / _feeDenominator() + +**_feeDenominator()** is specified in basis point by default. This value defaults to 10,000 but is overridable. Also the feeNumerator as specified in **mintNFTWithRoyalty** function is calculated in basis point. Take for instance if you want to set the royalty percentage to 10%, the **feeNumerator** will be 10/100 * 10000 = 1000 + +To get more insight of how it works under the hood, check out this [codebase](https://github.com/klaytn/klaytn-contracts/blob/master/contracts/token/common/ERC2981.sol). + + + + + + + diff --git a/docs/klaytn-contracts/nft-with-operator-filter/introduction.md b/docs/klaytn-contracts/nft-with-operator-filter/introduction.md new file mode 100644 index 0000000..4009adc --- /dev/null +++ b/docs/klaytn-contracts/nft-with-operator-filter/introduction.md @@ -0,0 +1,72 @@ +--- +title: 🎨 NFT with Operator Filter +sidebar_label: Introduction +--- + +## Introduction +Developers and creators need a sustainable means by which they are rewarded for the valuable work they create overtime. However, this has been made possible with the advent of royalties. This piece of innovation - NFT Royalty however faces a major limitation. The number of marketplaces that do not respect creator fees have been rapidly increasing, and creators, in turn, have seen their effective creator fees severely diminished; this stands as one major limitation. + +In order to counter this, an on-chain enforcement tool - [Operator Filter](https://github.com/ProjectOpenSea/operator-filter-registry) was introduced by OpenSea to prevent the sale of your NFTs using marketplaces that do not respect creator earnings. To put things in perspective, this mechanism is built atop of the EIP2981 NFT Royalty Standard to ensure that creators always receive their royalties when their NFTs are sold. And on the other hand, if someone attempts to trade an NFT using an operator filter in a marketplace that does not honor creator earnings, the NFT transfer will be blocked. + +To get more insight of how it works under the hood, check out this codebase. + +## Code Sample + +```javascript +// SPDX-License-Identifier: MIT +pragma solidity ^0.8.4; + +import "@klaytn/contracts/KIP/token/KIP17/KIP17.sol"; +import "@klaytn/contracts/KIP/token/KIP17/extensions/KIP17URIStorage.sol"; +import "@klaytn/contracts/access/Ownable.sol"; +import "@klaytn/contracts/utils/Counters.sol"; +import "operator-filter-registry/src/DefaultOperatorFilterer.sol"; + +contract MyToken is KIP17, KIP17URIStorage, Ownable, DefaultOperatorFilterer { +using Counters for Counters.Counter; +Counters.Counter private _tokenIdCounter; + +constructor() KIP17("MyToken", "MTK") {} + +function safeMint(address to, string memory uri) public onlyOwner { + uint256 tokenId = _tokenIdCounter.current(); + _tokenIdCounter.increment(); + _safeMint(to, tokenId); + _setTokenURI(tokenId, uri); +} + +// The following functions are overrides required by Solidity. + +function _burn(uint256 tokenId) internal override(KIP17, KIP17URIStorage) { + super._burn(tokenId); +} + +function setApprovalForAll(address operator, bool approved) public override onlyAllowedOperatorApproval(operator) { + super.setApprovalForAll(operator, approved); +} + +function approve(address operator, uint256 tokenId) public override onlyAllowedOperatorApproval(operator) { + super.approve(operator, tokenId); +} + +function transferFrom(address from, address to, uint256 tokenId) public override onlyAllowedOperator(from) { + super.transferFrom(from, to, tokenId); +} + +function safeTransferFrom(address from, address to, uint256 tokenId) public override onlyAllowedOperator(from) { + super.safeTransferFrom(from, to, tokenId); +} + +function safeTransferFrom(address from, address to, uint256 tokenId, bytes memory data) public override onlyAllowedOperator(from) { + super.safeTransferFrom(from, to, tokenId, data); +} + +function tokenURI(uint256 tokenId) public view override(KIP17, KIP17URIStorage) returns (string memory) { + return super.tokenURI(tokenId); +} + +} + +``` +From the code above, you can observe that the transfer, transferfrom, approve and setApproval function makes use of the onlyAllowedOperator and onlyAllowedOperatorApproval modifier respectively. This implies that only filtered operators i.e allowed platform smart-contract or delegate can execute transfers from or approvals. + diff --git a/docs/klaytn-contracts/payment-splitter-and-vesting/introduction.md b/docs/klaytn-contracts/payment-splitter-and-vesting/introduction.md deleted file mode 100644 index 254cbb7..0000000 --- a/docs/klaytn-contracts/payment-splitter-and-vesting/introduction.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: Payment -sidebar_label: Introduction ---- - diff --git a/docs/klaytn-contracts/payment-splitter-and-vesting/sdks-and-tutorials.md b/docs/klaytn-contracts/payment-splitter-and-vesting/sdks-and-tutorials.md deleted file mode 100644 index 86da754..0000000 --- a/docs/klaytn-contracts/payment-splitter-and-vesting/sdks-and-tutorials.md +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: payment -sidebar_label: Turotial ---- diff --git a/docs/klaytn-contracts/payment-splitter/introduction.md b/docs/klaytn-contracts/payment-splitter/introduction.md new file mode 100644 index 0000000..fd911ed --- /dev/null +++ b/docs/klaytn-contracts/payment-splitter/introduction.md @@ -0,0 +1,46 @@ +--- +title: 💸 Payment Splitter Contract +sidebar_label: Introduction +--- + +## Introduction + +Revenue sharing has traditionally been done manually, or through intermediaries, etc. in business environments when numerous parties are involved. This procedure has been hampered by delays, ineffectiveness, and even disputes between beneficiaries. Leveraging blockchain and smart contracts, this can be prevented by using the payment splitter contract. Payments can be automated with payment splitter contracts, ensuring that each party receives their just portion in an exact and transparent manner. + +In practice, when you create a project on the blockchain, the need to distribute smart-contract earnings to team members may arise. For example, a metaverse NFT marketplace project. This project may earn fees from trading (sell, buy, transfer, and so on), and each team member or stakeholder has a share. The Payment Splitter contract can be used to distribute each stakeholder's portion. + +The Payment Splitter contract enables a group of people to split payments (native tokens and ERC20 tokens) in a secure and transparent manner. This split is made possible by providing the *payee* and the *share* in the contract. The payee is the person to whom you want to pay a certain amount, and the share is the percentage amount the payee will receive. It should be noted that the shares can be distributed in any random ratio or in equal parts. + +With the use of payment splitter contracts, +* The payee does not have to remind the payer of the amount owed on a regular basis. +* The payee cannot withdraw more than they are owed +* Transparency is promoted among team members. + +## How it works + +From all payments made to the contract, each payee will be able to take away the sum that is payable to them. The payment splitter contract follows the [pull method](https://river.com/learn/pull-system-vs-push-system/), which means that payee can safely pull funds out of the contract by calling the release function. + +This is how a payment splitter contract works on a high level: + +1. Connect with other contracts which accumulates tokens (both ERC20 and native token) itself. +2. Add payee with share point on the contract +3. Contract receives payment +4. Tokens released to payees based on their shares by calling the release function + +To learn more about Payment Splitter, check out the [Payment Splitter Repository](https://github.com/klaytn/klaytn-contracts/blob/master/contracts/finance/PaymentSplitter.sol). + +## Usecase + +If revenue sharing is required, the payment splitter contract can be integrated with other contracts. The following are some examples of how a contract can accumulate tokens for itself before releasing them to payees: + +1. Token Launch contract is getting fee from the transaction(sell, buy, transfer, etc) +2. DeFi contract is getting the fee from the user's deposit and stake. +3. NFT Mint contract has some minting price and the contract is getting tokens from the minting transaction. +4. NFT Marketplace contract is getting fee from the tradings(sell, buy, transfer, etc) +5. Team wants to distribute tokens to team members as monthly pay-check +6. A DEX wants to consolidate and distribute trading fees to certain participants + +For the aforementioned scenarios, the contracts must include functions for withdrawing accumulated tokens or releasing them to payees with shares. Using PaymentSplitter, the above contracts don’t need to have those functions; just connect with PaymentSplitter, add payees with shares and release it to the payees. + + + diff --git a/docs/klaytn-contracts/payment-splitter/sdks-and-tutorials.md b/docs/klaytn-contracts/payment-splitter/sdks-and-tutorials.md new file mode 100644 index 0000000..1500a66 --- /dev/null +++ b/docs/klaytn-contracts/payment-splitter/sdks-and-tutorials.md @@ -0,0 +1,173 @@ +--- +title: 💻 Tutorial +sidebar_label: Tutorial +--- + +In this guide, you will implement a PaymentSplitter into an NFT contract using RemixIDE and caver-js. + +## 1. Prerequisites + +* [Remix IDE](https://docs.klaytn.foundation/content/dapp/tutorials/connecting-remix#connecting-klaytn-remix-using-kaikas) and [Kaikas](https://kaikas.zendesk.com/hc/en-us/articles/6657796272793-How-do-I-install-PC-Kaikas-) +* Enough test KLAY from [faucet](https://baobab.wallet.klaytn.foundation/faucet) +* [Node Js and NPM](https://kinsta.com/blog/how-to-install-node-js/) + +## 2. Deploying NFT - Payment Splitter Smart contract + +This code below defines a KIP17 token and Payment Splitter contract. These contracts were derived from the [Klaytn contracts library](https://github.com/klaytn/klaytn-contracts). + +The contract has a constructor that initializes the KIP17 contract with the name “HappyMonkey“ and symbol “HM”. It also initializes the paymentSplitter contract with the payee and shares arguments respectively. + +The safeMint function allows users to mint new tokens provided that the total supply is less than the maximum limit and the user sends at least the minimum required amount of KLAY. + +KLAY is sent to the contracts when a user mints new tokens, and the payee can now pull money from the contracts by calling the `release` function depending on each payee's shares. + +```javascript title="NFTPaymentSplitter.sol" +// SPDX-License-Identifier: MIT +pragma solidity ^0.8.0; + +import "@klaytn/contracts/KIP/token/KIP17/KIP17.sol"; +import "@klaytn/contracts/KIP/token/KIP17/extensions/KIP17Enumerable.sol"; +import "@klaytn/contracts/utils/Counters.sol"; +import "@klaytn/contracts/finance/PaymentSplitter.sol"; + +contract HappyMonkey is KIP17, KIP17Enumerable, PaymentSplitter { + + using Counters for Counters.Counter; + + Counters.Counter private _tokenIdCounter; + + uint256 public MINT_PRICE = 0.05 * 10**18; + uint public MAX_SUPPLY = 100; + + constructor(address[] memory _payees, uint256[] memory _shares) KIP17("HappyMonkey", "HM") PaymentSplitter(_payees, _shares) { + // Start token ID at 1. By default it starts at 0. + _tokenIdCounter.increment(); + } + + function safeMint(address to) public payable { + require(totalSupply() < MAX_SUPPLY, "Can't mint anymore tokens."); + + require(msg.value >= MINT_PRICE, "Not enough ether sent."); + uint256 tokenId = _tokenIdCounter.current(); + _tokenIdCounter.increment(); + _safeMint(to, tokenId); + } + + function _beforeTokenTransfer(address from, address to, uint256 tokenId) + internal + override(KIP17, KIP17Enumerable) + { + super._beforeTokenTransfer(from, to, tokenId); + } + + // The following function is an override required by Solidity. + function supportsInterface(bytes4 interfaceId) + public + view + override(KIP17, KIP17Enumerable) + returns (bool) + { + return super.supportsInterface(interfaceId); + } +} + +``` + +Refer to this [guide](https://docs.klaytn.foundation/content/dapp/tutorials/connecting-remix#connecting-klaytn-remix-using-kaikas) to deploy the above contract on Klaytn using Remix IDE. + +After you have successfully deployed your token contract, you should be able to copy the contract’s ABI and address. + +## 3. Interacting with Payment Spitter smart contract functions +To successfully interact with the already deployed contract, you'll need to install caver-js like we already did in previous KIP7 tutorial, you can visit this step if you have not installed caver js or skip it if otherwise. + +After installing caver-js, you will need to follow these steps. + +**a. Set up ABI folder** + +Create a new file named paymentSplitter.json in the `abi` folder. + +**b. Create your Scripts** + +Create a new file named `paymentSplitter.js` in the scripts folder. + +**c. Execute Scripts** + +Paste the code below in your newly created `paymentSplitter.js` file. The code illustrates the use of caver.js to interact with the payment splitter contract previously created. + +First, we import caver.js and the contract ABI, which defines the functions and parameters of the payment splitter contract. Then, we initialize caver.js and the KIP17 contract by providing the contract address. + +Next we set the contract address, create and add keyring to enable users sign on using their own Klaytn account. Then, we call a safeMint function to mint tokens to a specified account. Next we call the release function to enable the payee to pull funds from the contract. + +Finally, we checked the amount released to the payee using the `released` function. + +```javascript title="paymentSplitter.js" +// Interact with payment splitter contract using caver-js + +// Import caver.js and the paymentSplitter contract ABI +const Caver = require('caver-js') +const contractABI = require("../abi/paymentSplitter.json") + +// Initialize caver.js and the paymentSplitter contract +const caver = new Caver('https://api.baobab.klaytn.net:8651/') +const contractAddr = "paste contract address" +const contract = caver.contract.create(contractABI, contractAddr); + +const privateKey = "" +const payee = "" +const amount = 10; + +// Create and add keyring +const keyring = caver.wallet.keyring.createFromPrivateKey(privateKey) +caver.wallet.add(keyring) + +// function to mintTokens +// This ensures that KLAY is in the contract +const mintTokens = async () => { + const amountPayable = caver.utils.convertToPeb(amount, 'KLAY'); + contract.send({from: keyring.address, gas: 1500000, value: amountPayable}, 'safeMint', keyring.address) + .then(receipt => { + console.log(receipt); + }) + .catch(err => { + console.log(err); + }) +} + +// function to pull payee's share from the contract +// Note anyone can call this function provided it is the payee's address +const releaseToPayee = async (payeeAddress) => { + contract.send({from: keyring.address, gas: 1500000, value: 0}, 'release', payeeAddress) + .then(receipt => { + console.log(receipt); + }) + .catch(err => { + console.log(err); + }) +} + + +// function to get amount released to payee +const getAmountReleased = async (addr) => { + contract.methods.released(addr).call() + .then(result => { + console.log(result); + }) + } + + +mintTokens(); +// releaseToPayee(payee); +// getAmountReleased(payee); + +``` + +To run this code, open your terminal and paste this command + +```bash +node scripts/paymentSplitter.js +``` + + + + + diff --git a/docs/klaytn-contracts/tools-and-sdks.md b/docs/klaytn-contracts/tools-and-sdks.md index d163418..2626bda 100644 --- a/docs/klaytn-contracts/tools-and-sdks.md +++ b/docs/klaytn-contracts/tools-and-sdks.md @@ -9,7 +9,7 @@ There are a variety of open source tools to help developers utilize Klaytn smart * **[Klaytn Dev-Sandbox](https://github.com/klaytn/klaytn-dev-sandbox)**: This is a boilerplate code for dApps including front-end(UI) and contracts(backend) that are helpful to building blockchain applications on Klaytn. It imports [klaytn-contract library](https://github.com/klaytn/klaytn-contracts/tree/master/contracts) to create a KIP7, KIP17 and KIP37 token. With the front-end code, users can easily interact with already deployed contracts. -* **[Klaytn Online Toolkit](https://toolkit.klaytn.foundation/)**: This provides code samples and pages to help you utilize the Klaytn SDK(caver-js). With the Online Toolkit, you can derive the code to deploy your Klaytn contracts using caver-js. This contract includes [KIP7](https://toolkit.klaytn.foundation/kct/KIP7Deploy), [KIP17](https://toolkit.klaytn.foundation/kct/KIP17Deploy), [KIP37](https://toolkit.klaytn.foundation/kct/KIP37Deploy) and other [Klaytn Cmpatible Tokens(KCT)](https://toolkit.klaytn.foundation/kct/KCTDetection). The online toolkit also gives users the functionality of interacting with deployed contracts given its ABI, contract address. +* **[Klaytn Online Toolkit](https://toolkit.klaytn.foundation/)**: This provides code samples and pages to help you utilize the Klaytn SDK(caver-js). With the Online Toolkit, you can derive the code to deploy your Klaytn contracts using caver-js. This contract includes [KIP7](https://toolkit.klaytn.foundation/kct/KIP7Deploy), [KIP17](https://toolkit.klaytn.foundation/kct/KIP17Deploy), [KIP37](https://toolkit.klaytn.foundation/kct/KIP37Deploy) and other [Klaytn Compatible Tokens(KCT)](https://toolkit.klaytn.foundation/kct/KCTDetection). The online toolkit also gives users the functionality of interacting with deployed contracts given its ABI, contract address. * **[Klaytn Contracts Wizard](https://wizard.klaytn.foundation/)**: This is an interactive generator to bootstrap your smart contract and learn about Klaytn Contracts. This is based on [OpenZeppelin Wizard](https://wizard.openzeppelin.com/). diff --git a/sidebars.js b/sidebars.js index 43411c7..022ff09 100644 --- a/sidebars.js +++ b/sidebars.js @@ -76,6 +76,31 @@ const sidebars = { 'klaytn-contracts/dao-contracts/governance-tools' ] }, + { + type: 'category', + label: 'Payment Splitter Contract', + collapsed: true, + items: [ + 'klaytn-contracts/payment-splitter/introduction', + 'klaytn-contracts/payment-splitter/sdks-and-tutorials', + ] + }, + { + type: 'category', + label: 'NFT Royalty', + collapsed: true, + items: [ + 'klaytn-contracts/nft-royalty/introduction', + ] + }, + { + type: 'category', + label: 'NFT with Operator FIlter', + collapsed: true, + items: [ + 'klaytn-contracts/nft-with-operator-filter/introduction', + ] + }, 'klaytn-contracts/tools-and-sdks', ], },