From 9fd637a6869e521ac3b605d2619934949637642b Mon Sep 17 00:00:00 2001 From: M Glasgow Date: Fri, 24 Nov 2023 13:56:31 +0000 Subject: [PATCH] improving tokens/mining/wallet sections --- docs/dev/data-model/box/tokens.md | 65 ++++++++++++++++++++++++++----- docs/dev/tokens/issue.md | 33 ---------------- docs/dev/tokens/nfts/create.md | 20 +++++++--- docs/dev/tokens/nfts/index.md | 31 +++++++++++---- docs/dev/tokens/nfts/on-chain.md | 12 +++--- docs/dev/tokens/nfts/royalties.md | 11 ++++-- docs/dev/wallets.md | 9 ++++- docs/fud-faq.md | 2 +- docs/node/install.md | 50 +++++++++++++++--------- docs/node/install/manual.md | 4 +- mkdocs.yml | 1 - 11 files changed, 149 insertions(+), 89 deletions(-) delete mode 100644 docs/dev/tokens/issue.md diff --git a/docs/dev/data-model/box/tokens.md b/docs/dev/data-model/box/tokens.md index 2ea69924..d6439fa6 100644 --- a/docs/dev/data-model/box/tokens.md +++ b/docs/dev/data-model/box/tokens.md @@ -1,22 +1,69 @@ --- tags: - Data Model + - Storage Rent + - Registers --- -# Ergo Tokens +# Tokens on Ergo -Ergo tokens are incredibly versatile and can represent a wide range of assets, including shares, complementary currency units, and various tangible or intangible items. The infrastructure of Ergo is designed to seamlessly handle the representation and transfer of these diverse assets, integrating them into the blockchain as *first-class citizens*. +Ergo's native tokens are incredibly versatile and can represent a wide range of assets, including shares, complementary currency units, and various tangible or intangible items. The infrastructure of Ergo is designed to seamlessly handle the representation and transfer of these diverse assets, integrating them into the blockchain as *first-class citizens*. -It is crucial to understand that ERG, the native token of Ergo, possesses two unique characteristics: - -- ERGs are non-destructible; the total input and output amounts in any transaction must be equal. +//// details | What are **first-class citizens**? + {type: info, open: false} +This means that tokens in Ergo are not just metadata attached to transactions, but they are deeply integrated into the Ergo protocol. They can be manipulated and managed with the same level of support and functionality as the native Ergo token (see [EIP-0004](eip4.md)). +/// details | It is crucial to understand that ERG, the native token of Ergo, possesses two unique characteristics: + {type: warning, open: false} +- ERGs **cannot be burned**; the total input and output amounts in any transaction must be equal. - [Storage rent](rent.md) can only be paid in ERGs. +/// +//// + +/// details | How do I mint a token? + {type: info, open: false} +- Use [ergoutils](https://ergoutils.org/#/token) to mint a token directly from your web browser. ([Video Tutorial](https://www.youtube.com/watch?v=I3R6_PceM1k) +)) +- For programmatic token minting, refer to this guide: [Minting a Token with Fleet SDK](https://fleet-sdk.github.io/docs/transaction-building#step-4-2-mint-a-token) +/// + +## Token Storage + +- Tokens are stored in a special [register](registers.md) `R2` of a [box](box.md) in the form of (tokenId -> amount) pairs. +- A single box can hold **up to 255 secondary tokens**. + + +## Register Usage + +The Ergo reference implementation wallet uses specific [registers](registers.md) in a unique way, although the protocol doesn't enforce this: + +* `R4` - verbose name +* `R5` - description +* `R6` - number of decimal places +* Additional registers (`R7`, `R8`, `R9`) can store asset-specific information + + +## Limitations + +There are certain indirect limitations to consider: + +- The size of a box should not exceed 4 kilobytes. +- The presence of tokens increases the computational cost of the transaction. + +## Asset Creation + +An exception to the rule of weak preservation *(the total amount in inputs should be no less than the total amount in outputs)* is that a transaction can generate tokens from thin air in its outputs if the asset identifier matches the identifier of the transaction's first input box. Given that the box identifier is cryptographically unique, it's impossible to have a second asset with the same identifier, assuming the hash function used is collision-resistant (which it indeed is). This rule also implies that **only one new asset can be created per transaction.** + +## Examples + +- [How to mint a token with Fleet SDK](https://fleet-sdk.github.io/docs/transaction-building#step-4-2-mint-a-token) +- Creating a [perpetual token](perpetual.md) (designed to exist indefinitely, unless it is removed by garbage collection.) -Tokens in Ergo are stored in the `R2` [register](registers.md) of a [box](box.md). Each box holds pairs of `tokenId` and `amount`. allowing for the representation of multiple tokens within a single box. A single box has the capacity to hold up to 255 secondary tokens. -However, there are some indirect constraints to consider when working with tokens in Ergo: +## Resources -- The size of a box cannot exceed 4 kilobytes, ensuring efficient storage and processing of token-related data. -- The presence of tokens increases the computational cost of a transaction, as additional calculations are required to handle the token-related operations. +- [Token category on sigmaverse.io](https://sigmaverse.io/all-projects/?category=Tokens) +- [Ergo Token Minter](https://thierrym1212.github.io/tokenminter/index.html) or [CYTI](https://thierrym1212.github.io/cyti/index.html) which uses a Use CYTI minable smart contract to choose your token ID. +- [ergoutils.org](https://ergoutils.org/#/token) +- [Video Tutorial](https://www.youtube.com/watch?v=I3R6_PceM1k) diff --git a/docs/dev/tokens/issue.md b/docs/dev/tokens/issue.md deleted file mode 100644 index 87bebd18..00000000 --- a/docs/dev/tokens/issue.md +++ /dev/null @@ -1,33 +0,0 @@ -# Standards for Asset Issuance - -Ergo supports custom tokens as **first-class citizens** as outlined in [EIP-0004](eip4.md). - -- A special [register](registers.md) `R2` of a [box](box.md) contains (tokenId -> amount) pairs. -- A box can contain **at most 255 secondary tokens**. -- However, there are also some indirect limits: - - A box can be no more than 4 kilobytes - - Tokens add to the computational cost of the transaction. - -There is an exception to the rule of weak preservation *(the total amount in inputs is no less than the total amount in outputs)* a transaction can create tokens from thin air in its outputs if the asset identifier matches the identifier of the transaction's first input box. Since the box identifier is cryptographically unique, it's impossible to have a second asset with the same identifier, assuming the hash function used is collision-resistant (which it indeed is). This rule also implies that **only one new asset can be created per transaction.** - -The Ergo reference implementation wallet employs specific [registers](registers.md) in a particular manner, though the protocol doesn't mandate this: - -* `R4` - verbose name -* `R5` - description -* `R6` - number of decimal places -* Additional registers (`R7`, `R8`, `R9`) can hold asset-specific information - - -## Examples - -- [Mint a token with Fleet SDK](https://fleet-sdk.github.io/docs/transaction-building#step-4-2-mint-a-token) - -## Resources - -- [Token category on sigmaverse.io](https://sigmaverse.io/all-projects/?category=Tokens) -- [Ergo Token Minter](https://thierrym1212.github.io/tokenminter/index.html) or [CYTI](https://thierrym1212.github.io/cyti/index.html) which uses a Use CYTI minable smart contract to choose your token ID. -- [ergoutils.org](https://ergoutils.org/#/token) -- [Video Tutorial](https://www.youtube.com/watch?v=I3R6_PceM1k) - - - diff --git a/docs/dev/tokens/nfts/create.md b/docs/dev/tokens/nfts/create.md index 8810d9d3..08eafe9e 100644 --- a/docs/dev/tokens/nfts/create.md +++ b/docs/dev/tokens/nfts/create.md @@ -1,22 +1,30 @@ # Creating an NFT -> The quickest way to create an NFT is to use the [resources](#Resources) listed at the bottom of this page. +/// details | How do I mint a NFT? + {type: tip, open: true} +The quickest way to create an NFT is to follow [this visual guide](https://ergoplatform.org/en/blog/2022-03-08-how-to-minting-a-non-fungible-token-nft-on-the-ergo-blockchain/) that'll show you how to mint your NFT through [ergoauctions.org](https://ergoauctions.org/) +/// -## Standard - -The standard for artwork issuance on Ergo is [EIP-0024: Artwork Contract](eip24.md). This standard outlines the process of issuing NFTs, including the two different design versions, [V1 and V2](v1v2.md), and the importance of artist identity. V2 offers more flexibility and features, such as handling multiple royalty recipients, detailed artwork traits, and additional information. ## Creating an NFT programmatically See [this page](nft-examples.md) for some simple examples that demonstrate how to programmatically mint a NFT on the Ergo Blockchain. +## Standard + +The standard for artwork issuance on Ergo is [EIP-0024: Artwork Contract](eip24.md). This standard outlines the process of issuing NFTs, including the two different design versions, [V1 and V2](v1v2.md), and the importance of artist identity. V2 offers more flexibility and features, such as handling multiple royalty recipients, detailed artwork traits, and additional information. ## Resources +### Minting your NFT online + - [ergoauctions.org](https://ergoauctions.org/#/auction/active?type=all) Allows NFT minting. ([HowTo](https://ergoplatform.org/en/blog/2022-03-08-how-to-minting-a-non-fungible-token-nft-on-the-ergo-blockchain/)) -- [Lilium](lilium.md) seeks to create decentralised NFT minting, distribution, and sales infrastructure capable of being seamlessly integrated into business applications and programs. +- [Lilium](lilium.md) is a tool for artists to mint and sell their collections. + +### Developer Resources + - [ergpy](https://github.com/mgpai22/ergpy) has bulk-minting (with royalties!) - [ergo-nft-bulk-minter](https://github.com/mgpai22/ergo-nft-bulk-minter) -- [ergonfts.org/](https://ergonfts.org/) \ No newline at end of file +- [ergonfts.org](https://ergonfts.org/) \ No newline at end of file diff --git a/docs/dev/tokens/nfts/index.md b/docs/dev/tokens/nfts/index.md index 284f00ca..a1ac8279 100644 --- a/docs/dev/tokens/nfts/index.md +++ b/docs/dev/tokens/nfts/index.md @@ -1,16 +1,33 @@ # Non-Fungible Tokens on Ergo -NFTs *(Non-Fungible Tokens)* are unique and indivisible blockchain tokens. They can be used to represent and prove ownership of digital products such as works of art, in-game items or characters, virtual trading cards and much, much more. Because an NFT can be used to represent ultimate ownership, they allow users to trade digital items and cryptographically guarantee provenance. -- [How do I mint a NFT?](create.md) -- [How do royalties work?](royalties.md) +## Overview -## UTXO NFTs +*Non-Fungible Tokens* (NFTs) are unique and indivisible blockchain tokens. They can be used to represent and prove ownership of digital products such as works of art, in-game items or characters, virtual trading cards and much, much more. -One interesting feature is that Ergo can be used to create [PoW-backed NFTs](PoW_tokens.md). For most NFTs, a user simply generates a UTXO with the token contract attached. But it’s also possible for miners to create special NFTs, where the id of the newly minted token is the id of a coinbase transaction. This has all kinds of potential use cases, but the core idea is that a miner has the opportunity to create a special NFT when they mine a block. While any number of NFTs can be created via a regular smart contract, a finite number of these PoW-backed NFTs can exist. +## Frequently Asked Questions -There are other applications of NFTs that use the extended UTXO model, including facilitating a new generation of complex dApps. For example, a dApp creator can generate an NFT associated with an address and smart contract. While anyone can use that contract, and even create a transaction using the private key of that address, the NFT owner can still maintain administrative rights or other privileges. +//// details | Frequently Asked Questions + {type: note, open: true} +/// details | How do I mint a NFT? + {type: note, open: false} +Minting a NFT on Ergo is a straightforward process that can be done programmatically or using resources listed in our guide. Learn more about it [here](create.md). +/// +/// details | How do royalties work? + {type: note, open: false} +Royalties in Ergo are integrated into the minting metadata and can be accessed via smart contracts, allowing marketplaces to include royalties in their sale contracts. Find out more [here](royalties.md). +/// +//// + +## Use cases -## Unforgeable identity +### Unforgeable identity Let’s say you create a phenomenally successful exchange dApp, which pays a small percentage of trading fees to the owner – designated by ownership of that NFT. That token, and future revenues, can now be transferred and sold. The token can also be managed by a secondary smart contract, which could divide revenues among 100 tokens representing shareholders. The NFT could be used to update the dApp, or shut it down, if necessary – whatever conditions were coded into it. The point is that the NFT provides guaranteed, unforgeable proof of identity. + + +### UTXO NFTs + +One interesting feature is that Ergo can be used to create [PoW-backed NFTs](PoW_tokens.md). For most NFTs, a user simply generates a UTXO with the token contract attached. But it’s also possible for miners to create special NFTs, where the id of the newly minted token is the id of a coinbase transaction. This has all kinds of potential use cases, but the core idea is that a miner has the opportunity to create a special NFT when they mine a block. While any number of NFTs can be created via a regular smart contract, a finite number of these PoW-backed NFTs can exist. + +There are other applications of NFTs that use the extended UTXO model, including facilitating a new generation of complex dApps. For example, a dApp creator can generate an NFT associated with an address and smart contract. While anyone can use that contract, and even create a transaction using the private key of that address, the NFT owner can still maintain administrative rights or other privileges. diff --git a/docs/dev/tokens/nfts/on-chain.md b/docs/dev/tokens/nfts/on-chain.md index 78b05e3f..e4f89d5a 100644 --- a/docs/dev/tokens/nfts/on-chain.md +++ b/docs/dev/tokens/nfts/on-chain.md @@ -20,13 +20,11 @@ On-chain NFTs on Ergo differ from [regular NFTs](#the-technical-aspects-of-regul **Steps to create an on-chain SVG:** -1. Draw a relatively simple image in SVG vector format. -2. Manually optimize your art: smooth lines, remove minor details, reduce the number of colors, etc. -2. Further optimize using svg-optimizers. -4. Convert your *.svg file to [**Data URI format**](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URLs) (_there are many online/offline converters available_): -5. Check if your data fits within the **4 kb** box limit (<3.5 Kb). If not, return to the first step. -6. Place this data in the `R9` register. -7. **Most challenging part**: [Mint](https://docs.ergoplatform.com/dev/tokens/nfts/nft-examples/) the NFT using a tool that allows you to manipulate the `R9` register. +1. Draw a relatively simple image in SVG vector format and manually optimize your art: smooth lines, remove minor details, reduce the number of colors, etc. Further optimize using svg-optimizers. +2. Convert your *.svg file to [**Data URI format**](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URLs) (_there are many online/offline converters available_). +3. Check if your data fits within the **4 kb** box limit (<3.5 Kb). If not, return to the first step. +4. Place this data in the `R9` register. +5. **Most challenging part**: [Mint](https://docs.ergoplatform.com/dev/tokens/nfts/nft-examples/) the NFT using a tool that allows you to manipulate the `R9` register. /// admonition | Textual Data type: tip diff --git a/docs/dev/tokens/nfts/royalties.md b/docs/dev/tokens/nfts/royalties.md index 20c19df8..545f4b95 100644 --- a/docs/dev/tokens/nfts/royalties.md +++ b/docs/dev/tokens/nfts/royalties.md @@ -1,10 +1,15 @@ # Royalties -Royalties on Ergo are part of the minting `metadata` and are accessible through smart contracts. This means marketplaces have the option of including this in their sale contracts (which both sky harbor and auction house do). Any listing on a marketplace which respects royalties cannot have the royalties bypassed since it is part of their smart contract. +Ergo's royalty system is integrated into the minting `metadata` and can be accessed via smart contracts. This integration allows marketplaces to include royalties in their sale contracts, a feature utilized by both Sky Harbor and Auction House. Consequently, any listings on a marketplace that respects royalties will have the royalties embedded in their smart contract, preventing them from being bypassed. -That said, NFTs can clearly just be sent p2p to each other (just like when you transfer across addresses) and in these situations or in private sales it's up to the discretion of the involved parties whether to honour the royalties. +/// admonition | Not enforced by the protocol + type: warning -AuctionHouse V3 will support multiple recipients for royalties which enables artists to collaborate together. +However, it's important to note that NFTs can be transferred directly from one party to another, similar to transferring across addresses. In these cases, or in private sales, the decision to honor the royalties lies with the involved parties. +/// + + +The upcoming AuctionHouse V3 will introduce the ability to support multiple recipients for royalties. This feature will facilitate collaborations among artists. ## Resources diff --git a/docs/dev/wallets.md b/docs/dev/wallets.md index 5122f27b..27489157 100644 --- a/docs/dev/wallets.md +++ b/docs/dev/wallets.md @@ -1,7 +1,14 @@ # Wallets -Note that wallets are supported by third parties, we only provide the information below as a courtesy. +/// details | Disclaimer + {type: warning, open: true} +Note that wallets are supported by third parties, we only provide the information below as a courtesy. +/// +/// details | Funds stuck in Yoroi? + {type: warning, open: false} +If you have your Ergo wallet open in Yoroi and know the password for it, you can use [this tool](https://github.com/satsen/yoroi-ergo-wallet-recover) to decrypt the wallet and send all funds to a new wallet of yours. +/// | Wallet | Type | dApp-C | Node | Cold Wallet | [E-Pay](https://github.com/ergoplatform/eips/blob/master/eip-0020.md) | [Mixer](https://docs.ergoplatform.com/uses/mixer/#ergomixer) | |---|---|---|---|---|---|---| | [Nautilus](https://chrome.google.com/webstore/detail/nautilus-wallet/gjlmehlldlphhljhpnlddaodbjjcchai) | Web | ✅ | | ✅ | | 🔜 | diff --git a/docs/fud-faq.md b/docs/fud-faq.md index ee4c17f9..2981f5cd 100644 --- a/docs/fud-faq.md +++ b/docs/fud-faq.md @@ -1,6 +1,6 @@ # Common Misconceptions -/// admonition | title +/// details | title type: tip This page aims to provide some clarity around some common misconceptions that have cropped up about Ergo. diff --git a/docs/node/install.md b/docs/node/install.md index 23db57dd..c777b2c8 100644 --- a/docs/node/install.md +++ b/docs/node/install.md @@ -2,29 +2,41 @@ The Ergo Node is a critical component of Ergo's peer-to-peer network, responsible for hosting and synchronizing a copy of the entire blockchain. This page provides an overview of the Ergo Node, its installation options, and additional resources for developers. -To get an overview of live nodes on the Ergo network, you can visit [ergonodes.net](http://ergonodes.net). - -/// admonition | Other wallets with full node security. - type: tip - +//// details | Installation + {type: tip, open: true} +/// details | Other wallets with full node security. + {type: tip, open: false} The Ergo Node is a crucial infrastructure piece that developers use to interact with the Ergo blockchain. If you're looking for a place to store your ERG tokens, you can explore the [wallets](wallets.md) page. Some wallets, such as [Satergo](https://satergo.com/), even offer the option to install a full node alongside their wallet application. /// +/// details | Set up a full archival node + {type: tip, open: false} +To install the Ergo Node from scratch, you can refer to the [manual install](manual.md) page for detailed instructions. +/// +/// details | Get setup on Testnet + {type: tip, open: false} +Alternatively, if you want to get started on the testnet, there is a dedicated [testnet](testnet.md) setup guide available. +/// +/// details | Use Docker + {type: tip, open: false} +For more convenience, Docker provides a streamlined way to install and run the Ergo Node. Refer to the [Docker](docker.md) guide for instructions on setting up the node using Docker. +/// +/// details | Run a node on a Raspberry Pi! + {type: tip, open: false} +Even a [Raspberry Pi](pi.md) with a fast SSD attached is sufficient to sync and run a full node. +/// +/// details | Check out the developer toolkits and bundles + {type: notes, open: false} +- [Explorer & Node Bundles](explorer.md#toolkits): Access pre-packaged bundles that include an Ergo Node and an explorer for easy setup. +- [Ergosphere](https://ergosphere.cloud/): Ergosphere is an Umbrel-like solution that simplifies the setup of self-hosted Ergo services. Please note that it is currently in the BETA stage. +- [Ergode](https://github.com/ross-weir/ergode) (ergo-node) is an Ergo node implementation in TypeScript, targeting web and native runtimes. +/// +//// -To install the Ergo Node from scratch, you can refer to the [manual install](manual.md) page for detailed instructions. Alternatively, if you want to get started on the testnet, there is a dedicated [testnet](testnet.md) setup guide available. - -For more convenience, Docker provides a streamlined way to install and run the Ergo Node. Refer to the [Docker](docker.md) guide for instructions on setting up the node using Docker. Even a [Raspberry Pi](pi.md) with a fast SSD attached is sufficient to sync and run a full node. - -## Resources - +/// details | Resources + {type: notes, open: true} +- To get an overview of live nodes on the Ergo network, you can visit [ergonodes.net](http://ergonodes.net). - [Frequently Asked Questions](faq.md): Find answers to common questions about the Ergo Node. - [Modes of Operation](modes.md): Learn about the different modes of operation available for the Ergo Node. - [APIs](api.md): Explore the APIs provided by the Ergo Node for interacting with the blockchain. - -### Toolkits - -- [Explorer & Node Bundles](explorer.md#toolkits): Access pre-packaged bundles that include an Ergo Node and an explorer for easy setup. -- [Ergosphere](https://ergosphere.cloud/): Ergosphere is an Umbrel-like solution that simplifies the setup of self-hosted Ergo services. Please note that it is currently in the BETA stage. -- [Ergode](https://github.com/ross-weir/ergode): Ergode (ergo-node) is an Ergo node implementation in TypeScript, targeting web and native runtimes. - -By utilizing the Ergo Node and the available resources, developers can interact with the Ergo blockchain efficiently and explore the full potential of the Ergo ecosystem. \ No newline at end of file +/// diff --git a/docs/node/install/manual.md b/docs/node/install/manual.md index fbadb792..fd7e5dbe 100644 --- a/docs/node/install/manual.md +++ b/docs/node/install/manual.md @@ -35,8 +35,8 @@ java -jar -Xmx4G ergo-*.jar --mainnet -c ergo.conf See [this page](node-faq.md#java) for getting setup with java. -/// admonition | Xmx Flag - type: tip +/// details | -Xmx Flag + {type: tip, open: false} * The `-Xmx4G` flag determines the JVM's max heap size; recommended setting is `4-6G` based on available memory. * During the initial syncing process, allocate more memory using `-Xmx4g`. Upon completion of the syncing process, reduce this to `-Xmx1g`. diff --git a/mkdocs.yml b/mkdocs.yml index 840cbcb9..a93844cd 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -331,7 +331,6 @@ nav: - Assets: - Tokens: - dev/data-model/box/tokens.md - - Minting a token: dev/tokens/issue.md - Creating a perpetual token: dev/tokens/perpetual.md - Burning a token: dev/tokens/burn.md - Non-Fungible Tokens: