Amendment XLS: NFToken Collection Offers

[PuppyGamingDev]

NFToken Collection Offers (Issuer + Taxon Offers)

• Author(s): Shiffed / Moonkie / xrpl_Adam
• Category: Amendment
• Requires: XLS-20 (NFTokenMint, NFTokenCreateOffer, NFTokenAcceptOffer, NFTokenCancelOffer)

Abstract

This proposal introduces Collection Offers: a new mode for NFTokenCreateOffer that lets an account make a buy offer against an entire NFT collection - identified by Issuer + Taxon - instead of a single NFTokenID. Any account holding an NFT that matches the specified issuer and taxon can accept the offer with the specific token they own, transferring that token in exchange for the offered amount.

Today, a buyer who wants "any punk from collection X" must either poll the ledger for individual NFTs and create one offer per token (expensive, and offers expire/go stale as tokens move) or rely on a centralized marketplace to fake this behavior off-chain. This amendment brings that behavior on-ledger and trustless.

1. Motivation

• Collection-level demand is common. Most NFT marketplaces (on other chains and off-chain XRPL marketplaces) support "collection bids" - a single standing offer that any holder of a matching item can fill. XRPL currently has no native way to express this.
• Efficiency. Without this feature, expressing a collection-wide bid for a 10,000-item collection requires up to 10,000 individual NFTokenCreateOffer transactions, one per existing NFTokenID, each of which becomes stale the moment that specific token changes hands or a new token is minted into the taxon.
• Liquidity and price discovery. A native collection offer gives holders of any token in a taxon a guaranteed floor bid they can hit immediately, improving liquidity for thin collections and giving marketplaces a canonical on-ledger primitive instead of proprietary off-ledger order books.
• Consistency with the ledger's design philosophy. XRPL already natively supports the equivalent primitive for fungible tokens (Offers in the DEX are for a currency/issuer pair, not a specific unit). This proposal extends the same "trade against a class of asset" concept to NFTs.

2. Specification

2.1 New transaction flag: tfCollectionOffer

A new flag is added to NFTokenCreateOffer:

Flag Name	Flag Value	Description
tfCollectionOffer	0x00000004	Indicates this offer is a Collection Offer: it applies to any NFToken matching Issuer + NFTokenTaxon rather than a specific NFTokenID.

This is in addition to the existing tfSellNFToken (0x00000001) flag.

Restriction: tfCollectionOffer MUST NOT be combined with tfSellNFToken. Collection Offers are buy-side only - a sell offer inherently transfers one specific, already-owned token, so there is nothing ambiguous to generalize on the sell side. (See §3.2 for discussion of why sell-side collection offers are out of scope.)

2.2 NFTokenCreateOffer field changes

Field	Required?	Description
NFTokenID	Conditionally required	Required for normal offers. Must be omitted when tfCollectionOffer is set.
Issuer	Conditionally required	Must be present when tfCollectionOffer is set; specifies the issuer of the collection. Must be omitted otherwise (it can be derived from NFTokenID).
NFTokenTaxon	Conditionally required	Must be present when tfCollectionOffer is set. Must be omitted otherwise.
Amount	Required	Unchanged - the offered amount, in XRP or IOU.
Owner	N/A	Not applicable to Collection Offers (no single owner exists at creation time - see §2.3). Continues to be used as-is for normal single-token offers.
Destination	Optional	Unchanged. Restricts who may accept.
Expiration	Optional	Unchanged.

Validation rules:

• If tfCollectionOffer is set:
  • tfSellNFToken MUST NOT be set → temMALFORMED.
  • NFTokenID MUST NOT be present → temMALFORMED.
  • Issuer and NFTokenTaxon MUST both be present → temMALFORMED if either is missing.
  • Amount MUST be a non-zero XRP or IOU amount; the account MUST have sufficient balance/trust line headroom the same way any buy offer is checked today.
  • The transaction submitter becomes the prospective buyer, exactly as with a normal NFTokenID-scoped buy offer.

2.3 NFTokenOffer ledger object changes

The NFTokenOffer object gains two new optional fields, populated only for Collection Offers:

Field	Type	Description
Issuer	AccountID	Present only on Collection Offers.
NFTokenTaxon	UInt32	Present only on Collection Offers.
NFTokenID	Hash256	Omitted on Collection Offers (previously always present).

Indexing: Today, NFTokenOffers are linked into a directory keyed off the specific NFTokenID (the "buy offer directory" / "sell offer directory" for that token) as well as the owner's offer directory. A Collection Offer has no single NFTokenID to key off of at creation time, so it cannot use that directory.

This proposal introduces a new directory type, the NFTokenCollectionOfferDirectory, keyed by SHA512Half(Issuer || NFTokenTaxon). All outstanding Collection Offers for a given issuer/taxon pair are linked into this directory, in addition to the offering account's own owner directory (for reserve accounting and NFTokenCancelOffer/enumeration purposes, unchanged from today).

This keeps the change additive: existing NFTokenID-keyed offer directories and their traversal logic are untouched.

2.4 NFTokenAcceptOffer changes

NFTokenAcceptOffer gains one new optional field:

Field	Required?	Description
NFTokenID	Conditionally required	Already exists for the direct offer case. When accepting a Collection Offer, the acceptor (who must be the current owner of some matching token) supplies the specific NFTokenID they wish to sell into the offer.

Validation and execution, when the referenced offer is a Collection Offer:

1. The NFTokenID supplied by the acceptor MUST exist and MUST be owned by the acceptor.
2. The issuer and taxon encoded in that NFTokenID MUST match the Issuer / NFTokenTaxon stored on the NFTokenOffer → otherwise tecNFTOKEN_OFFER_TYPE_MISMATCH (new ledger result code).
3. If the token has lsfTransferable unset and the acceptor is not the issuer, reject as with normal offers today.
4. Transfer fee handling is unchanged: the fee is read from the flags/fee embedded in the specific NFTokenID being sold, exactly as today, since by acceptance time we have a concrete token.
5. On success, the token moves from the acceptor to the original Collection Offer creator, funds move in the opposite direction, and the NFTokenOffer is deleted from both the owner directory and the NFTokenCollectionOfferDirectory (a Collection Offer is consumed fully on first acceptance - it is not a standing multi-fill offer; see §3.3 for the open question on multi-fill).

2.5 Brokered mode (NFTokenAcceptOffer with both NFTokenSellOffer and NFTokenBrokerOffer)

When brokering, if the buy-side offer is a Collection Offer, the broker-supplied sell offer's NFTokenID is used to determine the concrete token, and the same issuer/taxon match check from §2.4 is applied before the trade is executed. NFTokenBrokerFee accounting is otherwise unchanged.

2.6 NFTokenCancelOffer

Unchanged in interface. Internally, cancellation of a Collection Offer removes the entry from the NFTokenCollectionOfferDirectory instead of an NFTokenID-keyed directory.

2.7 Amendment

This behavior is gated behind a new amendment, tentatively named NFTokenCollectionOffers.

3. Rationale and Alternatives Considered

3.1 Why a flag + optional fields instead of a new transaction type?

Reusing NFTokenCreateOffer/NFTokenAcceptOffer minimizes surface area and lets existing tooling, indexers, and wallets add support incrementally (unknown flag → ignore or reject, rather than an entirely unrecognized transaction type). A dedicated NFTokenCreateCollectionOffer type was considered but rejected as introducing duplicate logic for something that is fundamentally "the same offer object with a different scope."

3.2 Why buy-side only?

A sell-side "generic" offer would mean "I offer some NFT, unspecified, from this taxon, for this price" - but sell offers exist specifically because a particular token is already owned and escrow-able by a particular account. There is no natural way to make a binding sell commitment without pointing at a concrete, already-owned asset. If the intent is instead "the issuer will mint-and-sell on demand," that is more naturally addressed by a separate future proposal (e.g., issuer-side lazy-minting), not by generalizing NFTokenCreateOffer.

3.3 Single-fill by design

This proposal specifies single-fill only: a Collection Offer is consumed entirely the first time it's accepted, exactly like a normal NFTokenOffer today. There is no quantity field and no partial-consumption state.

A multi-fill variant (a standing bid that could be accepted repeatedly, up to some quantity, across many different tokens/holders) was considered and deliberately rejected for this proposal:

• It would require tracking a remaining quantity/remaining amount on the NFTokenOffer object, turning a simple delete-on-accept object into stateful, partially-mutable object - a meaningfully larger change to ledger object semantics than anything else in this proposal.
• It reintroduces DEX Offer-like partial-fill accounting (remaining amount, funding checks against future consumption) for an asset class (NFTs) that has none of that machinery today, and whose 1-of-1 nature makes "partial fill" conceptually different from a fungible-token offer.
• Single-fill keeps this proposal a strict, additive extension of the existing NFTokenOffer object and lifecycle (create → accept-and-delete, or cancel-and-delete), which is easier to review, implement, and reason about for a first amendment.
• Holders who want to establish a series of standing bids can still do so today by submitting multiple single-fill Collection Offers (e.g., three separate offers of the same amount) - at the cost of one transaction per unit of depth, which is an acceptable tradeoff for v1.

If demand emerges for multi-fill collection bids after this amendment ships, it is better addressed as a separate, later XLS building on this one, rather than complicating the initial design.

3.4 Why key the new directory by Issuer + Taxon hash rather than extend the existing directories?

Existing per-NFTokenID offer directories only make sense once a concrete token exists. A collection can have offers made against it before any given token within it is even minted (e.g., "I'll pay 10 XRP for any punk once you mint into taxon 52"), so the new offers must be discoverable independent of any specific token's lifecycle.

4. Backwards Compatibility

This change is purely additive:

• Existing NFTokenCreateOffer/NFTokenAcceptOffer/NFTokenCancelOffer behavior for NFTokenID-scoped offers is completely unchanged.
• Servers/validators without the amendment enabled treat transactions using tfCollectionOffer as malformed, consistent with normal amendment-gating conventions.
• NFTokenOffer objects gain optional fields; parsers that don't understand them can treat a Collection Offer object as they would any object with unfamiliar optional fields (assuming standard forward-compatible parsing).

5. Security Considerations

• Reserve accounting: Collection Offers still consume an owner reserve like any other offer object, preventing spam.
• Front-running / griefing: Because acceptance requires the acceptor to already own a matching token, there's no new griefing vector beyond what exists for ordinary buy offers today.
• Taxon obfuscation: Since NFTokenTaxon in the NFTokenID is already stored in an obfuscated (scrambled) form on the ledger (per XLS-20), implementations must be careful to compare the decoded taxon value stored on the NFTokenOffer object against the decoded taxon extracted from the candidate NFTokenID, not raw bytes.
• Denial of a specific token's offer directory growth: Collection Offers do not add entries to a single token's directory, so they don't contribute to the existing "too many offers on one NFT" directory-depth concerns.

6. Open Questions

1. Should Destination on a Collection Offer restrict acceptance to a specific account, or should there also be an option to restrict to "any of a specific NFT holder list" (out of scope, but worth flagging)?
2. Should there be a companion read-side RPC (e.g., nft_sell_offers/nft_buy_offers equivalent) to list Collection Offers by issuer/taxon efficiently? This would likely need a corresponding account_nfts-style API addition - proposed as a separate, complementary XLS or as an addendum here.
3. Naming: "Collection Offer" vs. "Taxon Offer" vs. "Generic NFT Offer" - feedback welcome before finalizing terminology for the amendment name.

[joshuahamsa]

Big +1 on this proposal — I've wanted native collection offers for a long time, and I'd been sketching essentially the same design (flag on NFTokenCreateOffer, Issuer+Taxon scope, new directory, buy-side only, single-fill) before finding this discussion. A few corrections and gaps worth addressing to get it toward Draft shape, plus some material I'm happy to contribute.

Corrections / main suggestion

1. §2.4 — suggest dropping the changes to NFTokenAcceptOffer field entirely.

Not to be pedantic, but the table shows NFTokenID "Conditionally required" on NFTokenAcceptOffer with the note

"already exists for the direct offer case,"

but today's NFTokenAcceptOffer has no NFTokenID field at all — only NFTokenSellOffer, NFTokenBuyOffer, and NFTokenBrokerFee. The token is referenced by the NFTokenOffer object. §2.4, as written, introduces a brand-new field, with new validation surface (present against a normal buy offer? present in brokered mode? omitted in direct mode?) that the spec doesn't currently define.

Rather than defining all that, what if we just don't change it; specify that a collection offer is filled only by matching it against a normal sell offer (existing brokered-mode shape — the sell offer supplies the concrete NFTokenID, and the issuer/taxon are decoded from it and checked against the collection offer).

I recognize this would require trading a rule change to permit self-brokering when the buy side is a collection offer: today the accept sender may not own either offer, so a seller filling a collection bid directly would post a sell offer for their chosen token and then match it themselves (NFTokenBrokerFee omitted).

Trade-off vs. the new-field approach: a direct fill takes two transactions (create sell offer, then accept) plus a transient owner-reserve. But:

• Most collection-bid fills happen through marketplaces, which operate via sell offers + brokered matching anyway — for the dominant flow this is zero extra cost.
• XLS-56 Batch is nearing amendment voting; a seller (or wallet) can submit the sell-offer + accept pair as one atomic batch, which restores single-submission UX and closes the window where the intermediate sell offer is independently acceptable by third parties.
• The amendment surface shrinks meaningfully: no new field on NFTokenAcceptOffer, no new malformed cases, one acceptance code path instead of two, and every fill flows through the existing, battle-tested brokered matching logic.

If the discussion prefers the one-transaction direct mode anyway, the spec should at minimum reframe NFTokenID as a new field and define the three malformed cases above.

2. §2.5 — field name. "NFTokenSellOffer and NFTokenBrokerOffer" should be NFTokenSellOffer and NFTokenBuyOffer (with optional NFTokenBrokerFee). Worth also stating how the existing brokered-mode rule "both offers must specify the same NFTokenID" generalizes: the sell offer's token must satisfy the buy offer's scope — NFTokenID equality when the buy offer names a specific token (unchanged), issuer/taxon match against the sell offer's token when the buy offer is a collection offer.

Gaps

3. Security Considerations is missing the main threat: taxon trust. Taxons are free-form and chosen by the issuer at mint time. An issuer (or its authorized minter) can mint arbitrarily many worthless tokens into a taxon that has open collection bids and immediately dump them into those bids. This is inherent to collection bids on any platform, but the XLS should surface it explicitly — XLS-1 requires a security section sufficient for review, and this is the first question a reviewer will ask. Suggested framing: a collection offer is an open bid that trusts the issuer of the collection; mitigations are Expiration, bidding only on issuers whose minting policy you trust (e.g., minter key blackholed or minting complete), and cancelling bids on issuer misbehavior. Third parties cannot inject tokens into a collection, so the trust boundary is exactly the issuer/minter.

4. Directory key needs a keyspace prefix. SHA512Half(Issuer || NFTokenTaxon) has no type-specific namespace constant, which risks identifier collisions with other object types. Per XLS-1 §4.4.3.2.1 this should be tagged hashing: SHA512Half(<CollectionOfferDir space key> || Issuer || NFTokenTaxon), with the 16-bit space key called out in the spec.

5. Owner should be a hard rule, not "N/A". Owner present while tfCollectionOffer is set → temMALFORMED.

6. Missing accept-time checks. The acceptance path should also specify: the issuer's lsfOnlyXRP flag (reject IOU-denominated collection offers at accept, or arguably at create, when set), Destination enforcement, and expiration handling (tecEXPIRED, plus deletion of the expired offer from both the owner directory and the collection offer directory).

7. Sections XLS-1 requires before this can go to Draft. Ledger-entry subsections (object identifier/keyspace, reserve — presumably one standard owner-reserve unit, deletion conditions incl. whether the entry blocks AccountDelete like other NFToken offers, invariants, example JSON), a transaction fee section, and a test plan (mandatory for rippled-affecting proposals). Suggested invariants:

• An NFTokenOffer has exactly one of { NFTokenID } or { Issuer + NFTokenTaxon }, never both, never neither.
• An offer with Issuer+NFTokenTaxon is never a sell offer.
• Accepting a collection offer never moves a token whose decoded issuer/taxon differ from the offer's fields.

8. On open question #3 (read-side API): I'd include it in this XLS rather than a separate one — the new directory exists precisely to make these offers enumerable, and speccing the RPC here locks in that the directory layout actually supports it. Sketch: nft_collection_offers taking nft_issuer + nft_taxon (+ pagination via marker/limit), returning the offer list in the same shape as nft_buy_offers. Happy to write this section out.

Minor

• 0x00000002 appears to be the next free flag bit on NFTokenCreateOffer (tfSellNFToken is 0x00000001); 0x00000004 works too but editors will likely ask.
• Open Questions numbering skips XLS-1d Standard for inter-contract communication #2.
• On naming (open question XLS-3d Standard for signed transactions #4): "Collection Offer" is the right call — it matches marketplace vocabulary everywhere; "Taxon Offer" describes the mechanism rather than the intent.

I have draft text for the invariants, RPC section, example JSONs, and a test plan outline from my own write-up of this same idea — glad to contribute any of it here or co-author toward the Draft PR if useful.

[EnchStyle]

TL'DR: I support the amendment's idea, but I do not believe it is needed.

Given this amendment comes from people who have a vested interest in the NFTs and have all the information to make a well informed decision, I am missing numbers on how would this impact the ledger for the better. As far as I am concerned, NFTs are very niche and none of artistic NFTs ever broke beyond XRPL ecosystem. The volume is pretty low as well.

XRPL is still positioning itself as "institutional chain", where I could see NFTs being utilised to a wider extent and this could come handy, but I see no such examples here as well. Hence, I am currently not convinced this feature is needed on XRPL. I agree will make life easier, because making a million clicks to buy a few NFTs is annoying, but the financial rational is not there.

If I am wrong on financial rational and you can provide quantitative evidence and projections, I will be happy to support it. This is also one of the reasons I proposed this: #393 <-- data should drive decisions, economic rational. If there is no demand for a feature, then it does not make sense extending the ledger's functionality.

[DpacJones]

Speaking as someone building and running marketplace infrastructure for a live
XRPL NFT collection, I want to add an operator's perspective, because I think the
"NFT volume is low" framing has the causality backwards.

We support collection offers today, but only by synthesizing them off-chain.
Because NFTokenCreateOffer requires a specific NFTokenID, a "bid on any token in
the collection" is impossible to express on-ledger. Our workaround is
buyer-in-the-loop: the bid is stored off-chain as intent, and when a holder
decides to fill it we push the buyer a signing request for a real buy offer
against that specific token, then settle it. It stays non-custodial, which matters
to us, but it carries a real cost: the buyer has to be reachable to confirm every
fill, so a standing "sweep the floor while I sleep" bid simply cannot exist. Most
serious XRPL marketplaces are working around the same gap in some variation of
this way.

That friction is itself part of the answer to the demand question. Collection bids
are the most common form of standing liquidity on mature NFT venues elsewhere, and
on XRPL the reason we see less of it is not lack of interest, it is that the
primitive to express it natively and non-custodially does not exist. Liquidity
primitives tend to precede volume, not follow it.

On the question of routing fills through brokered mode (as @joshuahamsa suggests)
versus a native accept-side path: I want to push back gently here, from the seat
of someone who runs the brokered flow today. Brokered mode is non-custodial, but
it reintroduces a mandatory intermediary. The fill cannot happen unless a specific
broker account is online to submit it, and in practice the sell offer ends up
destination-locked to that one broker. That is a liveness and permission
dependency on a single marketplace, which is much of what a native primitive
should be dissolving.

The real value of doing this at the protocol layer is permissionless direct fill:
any holder of a matching token accepts the collection offer with a plain
NFTokenAcceptOffer, no broker in the loop and no marketplace needing to be online.
I understand the brokered route is a smaller amendment surface, but it preserves
the exact centralization the feature is meant to remove. If the concern is
implementation complexity, I would rather help specify the direct-accept path than
trade away its main benefit.

One genuinely open design question in that direction: how funding availability is
handled when a collection offer is accepted directly, since a buyer's balance can
drift between posting the bid and a holder filling it. Whether that is handled with
reserve locking, a tec-level failure on accept, or something else is worth nailing
down, and it is the kind of detail I am happy to work through. To make that
concrete rather than hand-wave, here is a strawman for the direct-fill flow. Field
names and the flag bit are illustrative, meant as a starting point for discussion,
not a fixed proposal.

1. Create a collection offer (buy-side, no specific token). The scope is the
issuer + taxon instead of an NFTokenID:

{
  "TransactionType": "NFTokenCreateOffer",
  "Account": "rBuyerCollectionBidder00000000000",
  "Amount": "60000000",
  "Flags": 2147483649,
  "Issuer": "rst9Sq8mVxK8b7BbgFs4VmnVtfm7N2qN4j",
  "NFTokenTaxon": 0,
  "Expiration": 793372800
}

Flags here sets a new tfCollectionOffer bit (shown as 0x80000001 for
illustration). There is deliberately no NFTokenID and no Owner. Issuer +
NFTokenTaxon define which tokens may satisfy the offer.

2. Any holder fills it directly (no broker in the loop). The holder names the
specific token they are selling into the collection offer:

{
  "TransactionType": "NFTokenAcceptOffer",
  "Account": "rHolderOfAMatchingToken0000000000",
  "NFTokenBuyOffer": "<collection offer object index>",
  "NFTokenID": "000813881F9C83FE46F4EEC59D5E8C0B017F1791F856B882..."
}

The NFTokenID field on NFTokenAcceptOffer (new for this case) tells the ledger
which token is being transferred. The ledger validates that the token's issuer and
taxon match the collection offer, that the buyer is funded for Amount, applies any
transfer fee/royalty, and then performs the atomic swap. No third party is required
and no marketplace needs to be online.

For contrast, the way we synthesize the same outcome today is a normal per-token buy
offer (NFTokenCreateOffer, Flags: 0, a specific NFTokenID, Destination set to
our broker) settled with a brokered NFTokenAcceptOffer carrying NFTokenBrokerFee.
That works, but it is the exact mandatory-intermediary shape I described above.

A test-plan outline for the direct-fill path:

• Happy path: buyer posts a collection offer; a holder of a matching token accepts;
  NFT and payment swap atomically, offer is consumed.
• Wrong collection: a holder of a different issuer/taxon attempts to accept and is
  rejected (malformed / no-permission).
• Underfunded buyer: buyer's balance drops below Amount before a holder accepts;
  the accept fails cleanly (unfunded) and nothing transfers.
• Expiration: an accept submitted after Expiration is rejected as expired.
• Royalty: matching token carries a transfer fee; issuer receives the fee, seller
  nets the remainder, buyer pays Amount.
• IOU-denominated offer: trust line present/absent, freeze, and tfOnlyXRP
  interactions on the matching token.
• Concurrency: two holders accept near-simultaneously; exactly one settles, the
  other is rejected because the offer is already consumed.
• Brokered-variant parity: the same fill through a brokered NFTokenAcceptOffer, so
  the two paths can be compared directly.

Happy to iterate on any of this and help push it toward Draft.