mirror of
https://github.com/XRPLF/xrpl-dev-portal.git
synced 2025-11-20 11:45:50 +00:00
Merge commit 'c58824e43ebfd502949b6a577d7e155d1118900f' into japanese-dactly
This commit is contained in:
develoQ
18
content/concepts/tokens/nft-collections.md
Normal file
18
content/concepts/tokens/nft-collections.md
Normal file
@@ -0,0 +1,18 @@
|
||||
---
|
||||
html: nft-collections.html
|
||||
parent: non-fungible-tokens.html
|
||||
blurb: You can mint NFTs as collections using the NFT Taxon field.
|
||||
labels:
|
||||
- Non-fungible Tokens, NFTs
|
||||
---
|
||||
|
||||
# Minting NFTs into Collections
|
||||
|
||||
You can use the `NFTokenTaxon` field to group NFTs into collections. As the minter, you can choose any numeric value from `0x0` to `0xFFFFFFFF`and assign it to NFTs as you create them. The significance of the taxon is entirely up to you.
|
||||
|
||||
For example, for your first collection, you might set the `NFTokenTaxon` to `1`. You might have a collection of NFTs with taxon values of `316`, `420`, or `911`. You might use taxons that start with a digit to indicate the type of NFT (for example, all Real Estate NFTs have a taxon that starts with `2`).
|
||||
|
||||
While the `NFTokenTaxon` field is required, you can set the value to `0` if you don't intend to create a collection.
|
||||
|
||||
See [NFTokenTaxon](nftoken.html#nftokentaxon).
|
||||
|
||||
23
content/concepts/tokens/nft-fixed-supply.md
Normal file
23
content/concepts/tokens/nft-fixed-supply.md
Normal file
@@ -0,0 +1,23 @@
|
||||
---
|
||||
html: nft-fixed-supply.html
|
||||
parent: non-fungible-tokens.html
|
||||
blurb: Use a new account to mint a fixed number of NFTs, then black hole the account.
|
||||
labels:
|
||||
- Non-fungible Tokens, NFTs
|
||||
---
|
||||
|
||||
# Guaranteeing a Fixed Supply of NFTs
|
||||
|
||||
For some projects, you might want to guarantee that no more than a fixed number of NFTs are minted from an issuing account.
|
||||
|
||||
To guarantee a fixed number of NFTs:
|
||||
|
||||
1. Create and fund a new account, the _Issuer_. This account is the issuer of the tokens within the collection. See [Creating Accounts](accounts.html#creating-accounts).
|
||||
1. Use `AccountSet` to assign your operational wallet as an authorized minter for the issuer. See [Authorizing Another Account to Mint Your NFTs](nftoken-authorized-minting.html).
|
||||
1. Use your operational account to mint the tokens using `NFTokenMint`. The operational wallet holds all of the tokens minted for the Issuer. See [Batch Minting](nftoken-batch-minting.html).
|
||||
1. Use `AccountSet` to remove your operational wallet as an authorized minter for the Issuer.
|
||||
1. “Blackhole” the Issuer account. See [Disable Master Key Pair](disable-master-key-pair.html).
|
||||
|
||||
At this point, it is impossible for any new tokens to be minted with the issuer’s address as the issuing account.
|
||||
|
||||
**Caution** Once you "blackhole" the account, no one, including you, receives transfer fees for future sales of the NFTs.
|
||||
67
content/concepts/tokens/nft-reserve-requirements.md
Normal file
67
content/concepts/tokens/nft-reserve-requirements.md
Normal file
@@ -0,0 +1,67 @@
|
||||
---
|
||||
html: nft-reserve-requirements.html
|
||||
parent: non-fungible-tokens.html
|
||||
blurb: Understand reserve requirements for minting and holding NFTs.
|
||||
labels:
|
||||
- Non-fungible Tokens, NFTs
|
||||
---
|
||||
|
||||
# NFT Reserve Requirements
|
||||
|
||||
Minting, holding, and offering NFTs for sale require XRP held in reserve. The reserve charges can add up quickly. Understanding the reserve requirements can help you choose the best approach for your business case.
|
||||
|
||||
## Base Reserve
|
||||
|
||||
Your account must set aside a base reserve, currently 10 XRP. The base reserve XRP amount is subject to change. See [Base Reserve and Owner Reserve](reserves.html#base-reserve-and-owner-reserve).
|
||||
|
||||
## Owner Reserve
|
||||
|
||||
For each object you own on the XRP Ledger, there is an owner reserve, currently 2 XRP. This is to discourage users from spamming the ledger with unnecessary data, and to encourage them to clean up any data that is no longer necessary. The owner reserve amount is subject to change. See [Base Reserve and Owner Reserve](reserves.html#base-reserve-and-owner-reserve).
|
||||
|
||||
For NFTs, the _object_ does not refer to the individual NFTs, but to the `NFTokenPage` objects owned by the account. `NFTokenPage` objects can store up to 32 NFTs.
|
||||
|
||||
However, NFTs are not packed into pages to minimize space used. If you have 64 NFTs, it's not necessarily true that you have only 2 `NFTokenPage` objects.
|
||||
|
||||
A good rule of thumb is to assume, on average, that each `NFTokenPage` stores 24 NFTs.
|
||||
Therefore, you can estimate the reserve requirements for minting or owning _N_ NFTs as (24N)/2, or 1/12 of one XRP per NFT.
|
||||
|
||||
The following table provides examples of how much the total owner reserve might be, depending on the number of NFTs owned and the number of pages holding them.
|
||||
|
||||
| NFTs Owned | Best Case | Typical Case | Worst Case |
|
||||
|:------------|:----------|:-------------|:-----------|
|
||||
| 32 or fewer | 2 XRP | 2 XRP | 2 XRP |
|
||||
| 50 | 4 XRP | 6 XRP | 8 XRP |
|
||||
| 200 | 14 XRP | 18 XRP | 26 XRP |
|
||||
| 1000 | 64 XRP | 84 XRP | 126 XRP |
|
||||
|
||||
## `NFTokenOffer` Reserve
|
||||
|
||||
Each `NFTokenOffer` object costs the account placing the offer one incremental reserve. As of this writing, the incremental reserve is 2 XRP. The reserve can be recovered by cancelling the offer. The reserve is also recovered if the offer is accepted, which removes the offer from the XRP Ledger.
|
||||
|
||||
## Practical Considerations
|
||||
|
||||
When minting, holding, and offering to buy and sell NFTs, the reserve requirements can add up quickly. This can result in your account going below the reserve requirement during a transaction. Going below the requirement can limit your ability to trade on the XRPL. See [Going Below the Reserve Requirement](reserves.html#going-below-the-reserve-requirement).
|
||||
|
||||
If you create a new account, mint an NFT, and create an `NFTokenSellOffer` on the XRP Ledger, that requires a minimum reserve of 14 XRP.
|
||||
|
||||
| Reserve Type | Amount |
|
||||
|:--------------------|--------:|
|
||||
| Base | 10 XRP |
|
||||
| NFToken Page | 2 XRP |
|
||||
| NFToken Offers | 2 XRP |
|
||||
| Total | 14 XRP |
|
||||
| | |
|
||||
|
||||
**Note** While not a reserve requirement, keep in mind that you would want to have at least 1 XRP above your reserves to cover the trivial fee for each transaction in the mint and sell process (typically 12 drops, or .000012 XRP).
|
||||
|
||||
If you were to mint 200 NFTs and create an `NFTokenSellOffer`for each, that would require as much as 436 XRP held in reserve.
|
||||
|
||||
| Reserve Type | Amount |
|
||||
|:--------------------|--------:|
|
||||
| Base | 10 XRP |
|
||||
| NFToken Pages | 26 XRP |
|
||||
| NFToken Offers | 400 XRP |
|
||||
| Total | 436 XRP |
|
||||
| | |
|
||||
|
||||
If the required reserves exceed the amount you are comfortable setting aside, consider using the mint-on-demand model to reduce the number of NFTs and offers you hold at any one time. See [Mint on Demand](nftoken-batch-minting.html#mint-on-demand-lazy-minting).
|
||||
64
content/concepts/tokens/nftoken-auctions.md
Normal file
64
content/concepts/tokens/nftoken-auctions.md
Normal file
@@ -0,0 +1,64 @@
|
||||
---
|
||||
html: nftoken-auctions.html
|
||||
parent: non-fungible-tokens.html
|
||||
blurb: You can assign another account to mint NFTs in your stead.
|
||||
labels:
|
||||
- Non-fungible Tokens, NFTs
|
||||
---
|
||||
|
||||
# Running an NFT Auction
|
||||
|
||||
There are several ways to run an auction, each with advantages and disadvantages.
|
||||
|
||||
## Run the Auction Off the XRPL, Complete the Purchase on XRPL
|
||||
|
||||
This flow is the most straightforward. Note that the `NFTokenOffer` objects can always be canceled by their creator, so it's not possible to implement a binding offer.
|
||||
|
||||
1. Store your bids in a private database.
|
||||
2. You take a cut of the winning bid.
|
||||
3. Send the buyer/seller the XRPL transaction to complete the purchase.
|
||||
|
||||
## Run the Auction in Brokered Mode, with a Reserve
|
||||
|
||||
Run the auction in brokered mode, as an auction with a reserve.
|
||||
|
||||
|
||||
|
||||
1. The seller creates the NFT, then sets the auction reserve price using `NFTokenCreateOffer`, specifying the broker account as the destination.
|
||||
1. The bidders make offers using `NFTokenCreateOffer`, setting the broker account as the destination.
|
||||
1. The broker selects the winning bid, completes the sale using `NFTokenAcceptOffer`, collecting the broker fee. Then the broker cancels any losing bids using `NFTokenCancelOffer`.
|
||||
|
||||
**Pros:**
|
||||
|
||||
- The entire auction happens on the XRPL, including your broker fee.
|
||||
- The seller represents their reserve price on-chain.
|
||||
- This is _close_ to a binding offer, from the buyside.
|
||||
|
||||
**Cons:**
|
||||
|
||||
- There must be implicit trust between the seller and the broker that the broker will not take more than some previously agreed-upon rate. If the reserve was 1 XRP and the winning bid was 1000 XRP, there is no on-chain mechanism to prevent the broker from taking 999 XRP as profit, leaving only the reserve profits for the seller.
|
||||
|
||||
A major mitigating factor of this downside is that if this behavior were to happen, brokers would lose their entire market share, which sellers should understand.
|
||||
|
||||
## Run the Auction in Brokered Mode, without a Reserve.
|
||||
|
||||
This is the most complex workflow of the three.
|
||||
|
||||
|
||||
|
||||
1. The seller creates an NFT using `NFTokenMint`.
|
||||
1. The bidders make offers using `NFTokenCreateOffer`, setting the broker as the destination.
|
||||
1. The broker selects the winning bid, subtracts the amount to be collected as a fee, then requests the seller sign a sell off for this amount via `NFTokenCreateOffer`.
|
||||
1. The seller signs the requested offer, setting the broker as the destination.
|
||||
1. The broker completes the sale using `NFTokenAcceptOffer`, and receives the broker fee.
|
||||
1. The broker cancels any remaining bids using `NFTokenCancelOffer`.
|
||||
|
||||
**Pros:**
|
||||
|
||||
- This flow requires absolutely no trust among participants, making it the option most people expect on the blockchain.
|
||||
- Sellers know exactly how much the broker takes from them in fees and must agree to it on the chain.
|
||||
|
||||
**Cons:**
|
||||
|
||||
- After the auction is complete, the sale is contingent on the seller agreeing to the final bid amount and broker fee amount. This means that sellers can back out of an otherwise complete auction or that sellers can delay settlement due to being distracted or not seeing some notification.
|
||||
- After the auction is complete, a seller can refuse the winning bid, instead selling to someone else.
|
||||
@@ -12,33 +12,32 @@ You can transfer `NFToken` objects between accounts on the XRP Ledger. You can o
|
||||
|
||||
_(Added by the [NonFungibleTokensV1_1 amendment][].)_
|
||||
|
||||
## Reserve Requirements
|
||||
|
||||
Every NFTokenOffer object requires that your account increase its owner reserve, currently 2 XRP per `NFTokenSellOffer` and 2 XRP per `NFTokenBuyOffer`. This is to prevent accounts from spamming the ledger with offers they don't intend to complete.
|
||||
|
||||
See [NFT Reserve Requirements](nft-reserve-requirements.html).
|
||||
|
||||
## Sell Offers
|
||||
|
||||
|
||||
### Create a Sell Offer
|
||||
|
||||
As the owner of a `NFToken` object, you can create a sell offer using a [NFTokenCreateOffer transaction][] with the `tfSellToken` flag. You provide the `NFTokenID` and the `Amount` you are willing to accept in payment. You can optionally specify an `Expiration` date, after which the offer is no longer valid, and a `Destination` account, which is the only account that is allowed to buy the `NFToken`.
|
||||
|
||||
|
||||
### Accept a Sell Offer
|
||||
|
||||
To buy a `NFToken` that is offered for sale, you use a `NFTokenAcceptOffer` transaction. You provide the owner account and specify the `NFTokenOfferID` of the `NFTokenOffer` object you choose to accept.
|
||||
|
||||
|
||||
## Buy Offers
|
||||
|
||||
|
||||
### Create a Buy Offer
|
||||
|
||||
Any account can offer to buy a `NFToken`. You can create a buy offer using [NFTokenCreateOffer][] _without_ the `tfSellToken` flag. You provide the `Owner` account, `NFTokenID`, and the `Amount` of your offer.
|
||||
|
||||
|
||||
### Accept a Buy Offer
|
||||
|
||||
Use the `NFTokenAcceptOffer` transaction to transfer a `NFToken`. Provide the `NFTokenOfferID` and the owner account to complete the transaction.
|
||||
|
||||
|
||||
## Trading Modes
|
||||
|
||||
When trading a `NFToken`, you can choose between a _direct_ transaction between a buyer and seller or a _brokered_ transaction, where a third party account matches a sell and buy offer to arrange the trade.
|
||||
@@ -47,7 +46,6 @@ Trading in direct mode gives the seller control over the transfer. The seller ca
|
||||
|
||||
In brokered mode, the seller allows a third party account to broker the sale of the `NFToken`. The broker account collects a broker fee for the transfer at an agreed upon rate. This happens as one transaction, paying the broker and seller from the buyer’s funds without requiring an up front investment by the broker.
|
||||
|
||||
|
||||
### When to Use Brokered Mode
|
||||
|
||||
If a `NFToken` creator has the time and patience to seek out the right buyers, the creator keeps all proceeds from the sale. This works fine for a creator who sells few `NFToken` objects at variable prices.
|
||||
@@ -60,24 +58,18 @@ Using a broker offers several advantages. For example:
|
||||
* The broker can act as a curator, organizing `NFToken` objects based on a niche market, price point, or other criteria. This can attract groups of buyers who might not otherwise discover a creator’s work.
|
||||
* The broker can act as a marketplace, similar to Opensea.io, to handle the auction process at the application layer.
|
||||
|
||||
|
||||
### Brokered Sale Workflows
|
||||
|
||||
In the most straightforward workflow, a creator mints a new `NFToken`. The creator initiates a sell offer, entering the minimum acceptable sale price and setting the broker as the destination. Potential buyers make bids for the `NFToken`, setting the broker as the destination for the bid. The broker selects a winning bid and completes the transaction, taking a broker’s fee. As a best practice, the broker then cancels any remaining buy offers for the `NFToken`.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Another potential workflow would give the creator more control over the sale. In this workflow, the creator mints a new `NFToken`. Bidders create their offers, setting the broker as the destination. The broker selects the winning bid, subtracts their broker fee, and uses `NFTokenCreateOffer` to request that the creator sign off on the offer. The creator signs the requested offer, setting the broker as the destination. The broker completes the sale using `NFTokenAcceptOffer`, retaining the broker fee. The broker cancels any remaining bids for the `NFToken` using `NFTokenCancelOffer`.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
The same workflows can be used when an owner resells a `NFToken` created by another account.
|
||||
|
||||
|
||||
<!--{# common link defs #}-->
|
||||
{% include '_snippets/rippled-api-links.md' %}
|
||||
{% include '_snippets/tx-type-links.md' %}
|
||||
|
||||
@@ -61,7 +61,7 @@ A token issuer can submit an [AccountSet transaction][] from its [issuing addres
|
||||
|
||||
Anyone can check an account's `TransferRate` with the [account_info method][]. If the `TransferRate` is omitted, then that indicates no fee.
|
||||
|
||||
**Note:** The [fix1201 amendment](amendments.html), introduced in `rippled` v0.80.0 and enabled on 2017-11-14, lowered the maximum transfer fee to 100% (a `TransferRate` of `2000000000`) from an effective limit of approximately 329% (based on the maximum size of a 32-bit integer). The ledger may still contain accounts with a transfer fee setting higher than 100% because transfer fees that were already set continue to apply at their stated rate.
|
||||
**Note:** The [fix1201](known-amendments.html#fix1201) [amendment](amendments.html), introduced in `rippled` v0.80.0 and enabled on 2017-11-14, lowered the maximum transfer fee to 100% (a `TransferRate` of `2000000000`) from an effective limit of approximately 329% (based on the maximum size of a 32-bit integer). The ledger may still contain accounts with a transfer fee setting higher than 100% because transfer fees that were already set continue to apply at their stated rate.
|
||||
|
||||
## Client Library Support
|
||||
|
||||
|
||||
@@ -40,6 +40,7 @@ In addition to the general fields above, you must specify *exactly 1* of the fol
|
||||
- [`payment_channel`](#get-paychannel-object)
|
||||
- [`deposit_preauth`](#get-depositpreauth-object)
|
||||
- [`ticket`](#get-ticket-object)
|
||||
- [`nft_page`](#get-nft-page)
|
||||
|
||||
**Caution:** If you specify more than 1 of these type-specific fields in a request, the server retrieves results for only 1 of them. It is not defined which one the server chooses, so you should avoid doing this.
|
||||
|
||||
@@ -627,6 +628,48 @@ rippled json ledger_entry '{ "ticket": { "account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJ
|
||||
[Try it! >](websocket-api-tool.html#ledger_entry-ticket)
|
||||
|
||||
|
||||
### Get NFT Page
|
||||
|
||||
Return an NFT Page in its raw ledger format.
|
||||
|
||||
| `Field` | Type | Description |
|
||||
|:------------------------|:---------------------------|:----------------------|
|
||||
| `nft_page` | String | The [object ID](ledger-object-ids.html) of an [NFT Page](nftokenpage.html) to retrieve. |
|
||||
|
||||
<!-- MULTICODE_BLOCK_START -->
|
||||
|
||||
*WebSocket*
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "example_get_nft_page",
|
||||
"command": "ledger_entry",
|
||||
"nft_page": "255DD86DDF59D778081A06D02701E9B2C9F4F01DFFFFFFFFFFFFFFFFFFFFFFFF",
|
||||
"ledger_index": "validated"
|
||||
}
|
||||
```
|
||||
|
||||
*JSON-RPC*
|
||||
|
||||
```json
|
||||
{
|
||||
"method": "ledger_entry",
|
||||
"params": [{
|
||||
"nft_page": "255DD86DDF59D778081A06D02701E9B2C9F4F01DFFFFFFFFFFFFFFFFFFFFFFFF",
|
||||
"ledger_index": "validated"
|
||||
}]
|
||||
}
|
||||
```
|
||||
|
||||
*Commandline*
|
||||
|
||||
```sh
|
||||
rippled json ledger_entry '{ "nft_page": "255DD86DDF59D778081A06D02701E9B2C9F4F01DFFFFFFFFFFFFFFFFFFFFFFFF", "ledger_index": "validated" }'
|
||||
```
|
||||
|
||||
<!-- MULTICODE_BLOCK_END -->
|
||||
|
||||
[Try it! >](websocket-api-tool.html#ledger_entry-nft-page)
|
||||
|
||||
## Response Format
|
||||
|
||||
|
||||
@@ -98,14 +98,15 @@ The fourth section is a `NFTokenTaxon` created by the issuer.
|
||||
|
||||
An issuer might issue several `NFToken` objects with the same `NFTokenTaxon`; to ensure that `NFToken` objects are spread across multiple pages, the `NFTokenTaxon` is scrambled using the fifth section, a sequential number, as the seed for a random number generator. The scrambled value is stored with the `NFToken`, but the unscrambled value is the actual `NFTokenTaxon`.
|
||||
|
||||
|
||||
|
||||
Notice that the scrambled version of the `NFTokenTaxon` is `0xBC8B858E`: the scrambled version of the `NFTokenTaxon` specified by the issuer. But the _actual_ value of the `NFTokenTaxon` is the unscrambled value.
|
||||
Notice that the scrambled version of the `NFTokenTaxon` is `0xBC8B858E`, the scrambled version of the `NFTokenTaxon` specified by the issuer. But the _actual_ value of the `NFTokenTaxon` is the unscrambled value.
|
||||
|
||||
### Token Sequence
|
||||
|
||||
The fifth section is a sequence number that increases with each `NFToken` the issuer creates. The [NFTokenMint transaction][] sets this part of the `NFTokenID` automatically based on the `MintedTokens` field of the `Issuer` account. If the issuer's [AccountRoot object][] does not have a `MintedTokens` field, the field is assumed to have the value 0; the value of the field is then incremented by exactly 1.
|
||||
The fifth section is a sequence number that increases with each `NFToken` the issuer creates.
|
||||
|
||||
|
||||
|
||||
The [NFTokenMint transaction][] sets this part of the `NFTokenID` automatically based on the `MintedTokens` field of the `Issuer` account. If the issuer's [AccountRoot object][] does not have a `MintedTokens` field, the field is assumed to have the value 0; the value of the field is then incremented by exactly 1.
|
||||
|
||||
## URI
|
||||
|
||||
|
||||
@@ -7,9 +7,9 @@ labels:
|
||||
---
|
||||
# tec Codes
|
||||
|
||||
These codes indicate that the transaction failed, but it was applied to a ledger to apply the [transaction cost](transaction-cost.html). They have numerical values in the range 100 to 199. Ripple recommends using the text code, not the numeric value.
|
||||
These codes indicate that the transaction failed, but it was applied to a ledger to apply the [transaction cost](transaction-cost.html). They have numerical values in the range 100 to 199. It is recommended to use the text code, not the numeric value.
|
||||
|
||||
For the most part, transactions with `tec` codes take no action other than to destroy the XRP paid as a [transaction cost](transaction-cost.html), but there are some exceptions. As one such exception, a transaction that results in `tecOVERSIZE` still cleans up some [unfunded offers](offers.html#lifecycle-of-an-offer). Always look at the [transaction metadata](transaction-metadata.html) to see precisely what a transaction did.
|
||||
Transactions with `tec` codes destroy the XRP paid as a [transaction cost](transaction-cost.html), and consume a [sequence number](basic-data-types.html#account-sequence). For the most part, the transactions take no other action, but there are some exceptions. For example, a transaction that results in `tecOVERSIZE` still cleans up some [unfunded offers](offers.html#lifecycle-of-an-offer). Always look at the [transaction metadata](transaction-metadata.html) to see precisely what a transaction did.
|
||||
|
||||
**Caution:** A transaction that provisionally failed with a `tec` code may still succeed or fail with a different code after being reapplied. The result is final when it appears in a validated ledger version. For more information, see [Finality of Results](finality-of-results.html) and [Reliable Transaction Submission](reliable-transaction-submission.html).
|
||||
|
||||
|
||||
Reference in New Issue
Block a user