0053 XLS-53d: Royalties and Brokerage for URITokens

[RichardAH]

XLS-53d - Royalties and Brokerage for URITokens

Title:       Royalties and Brokerage for URITokens
Revision:    1 (2023-11-20)

Author:      Richard Holland

Affiliation: XRPL-Labs, XRPLF

DRAFT

This is currently (2023-11-20) an early release document, and request for comment. It will change (possibly significantly) before it becomes a standard.

Introduction

URITokens (XLS-35) are lightweight non-fungible tokens available on Xahau. However, despite being first class on-ledger objects, URITokens come with many fewer features than XLS-20 tokens. This is a deliberate design choice—the flexibility of Hooks makes complex transactors largely redundant, and sometimes outright counter-productive.

Many users and developers have asked how royalties can be collected and enforced when dealing in URITokens. This document establishes a standardised way to control the conditions of ownership and transfer of URITokens without excessively stripping rights from token holders.

Issuer Hooks

As per XLS-35, a URIToken is always minted by its Issuer back into the Issuer's own account. After minting, it may be subsequently transferred to a new owner, however the Issuer's account remains a transactional stakeholder of the URIToken for the entirety of its life. If the URIToken was minted with the tfBurnable flag then the Issuer is a strong transactional stakeholder, meaning the Issuer's Hooks can block transfers. In all other cases the Issuer is a weak transactional stakeholder, meaning they cannot block transfers. The tfBurnable flag also allows the Issuer's account to unilaterally destroy the URIToken, which is a desirable right in some situations but undesirable in others.

In the case where it is undesirable that the Issuer can unilaterally burn their Issued tokens, the Issuer may install a Hook on their account and subsequently blackhole the account. This means the Issuer's URIToken rights can only be enforced by the logic in the installed Hook. Thus, if the Hook provides no provision to unilaterally burn a token, then burning becomes impossible (and owners are thereby assured that their tokens cannot be unilaterally burned.)

Black-holing the Issuer account works fine if the Issuer no longer needs to mint further tokens, but if they do need to continue issuing further tokens, then delegated issuance may be used.

In delegated issuance the Issuer's Hook will accept an Invoke transaction from one or more preset Artist accounts or according to a signature from a preset public key. The parameters of the Invoke transaction contain the details of the new URIToken to create. Upon receiving the Invoke transaction, the Hook emits a URITokenMint transaction back to the Issuer's own account, creating the new token under blackhole conditions.

Finally, to prevent arbitrary transfer of URITokens between accounts, the Issuer's Hook blocks all transfers unless the following conditions are met:

The transfer is to (or from) an account with the following properties:

1. The account is blackholed.
2. The account has installed on it a HookHash that is in the well known list of audited XLS-53 compliant URIToken Brokerage Hooks.
3. Any other Hooks installed on the account appear on the well known list of XLS-53 allowable co-hooks.

The Issuer Hook has the potential to act maliciously against the Brokerage Hook by blocking transfers that should be allowed under this standard, or by changing the royalty amount to an unreasonable level or arbitrarily. Therefore the Issuer Hook must also be from a well known list of audited XLS-53 compliant URIToken Issuer Hooks, and any other Hooks on the Issuer account must appear on the well known list of XLS-53 allowable co-hooks.

A compliant Issuer Hook must under no circumstances block the transfer of a URIToken out of a compliant Brokerage Hook, but may block the transfer into a compliant Brokerage Hook subject to any conditions it has.

Brokerage Hooks

A compliant brokerage Hook is one which follows this standard. The Hook provides a tamper-proof middleman service, accepting the transfer of the URIToken from the selling party, and the transfer of funds from the purchasing party, and ensuring the royalty and brokerage fees are correctly collected and distributed.

Listing a Token

A compliant Brokerage Hook must automatically accept a URITokenCreateSellOffer that specifies it as the Destination (with an Amount of 0), if the following conditions are met, and reject the transaction if they are not met.

HookParameterKey	Required	Value	Explanation
414D54 ( AMT )	✅	8 byte little endian XFL	The amount to sell for, or the minimum amount to accept at auction (depending on flags)
435552 ( CUR )	❌	20 byte currency code	If the amount above is an Issued Currency, the currency code of that currency
495355 ( ISU )	❌	20 byte Issuer account of the Currency	If the amount above is an Issued Currency, the Issuer for that currency (‼️ NOT the Issuer of the URIToken.)
464C47 ( FLG )	❌	4 byte little endian integer	0 = Buy it now. 1 = Auction. All other flags are reserved for future extensions of the standard. (Absent = 0.)
455850 ( EXP )	❓	4 byte little endian integer	Ripple timestamp indicating the last possible sell date. This must be at least 1 hour ahead of the current time. If this is an auction then this field is required and marks the end of the auction. If this field is present the token may not be unlisted for sale until a ledger with a close time larger than the timestamp has been validated. If absent, the token may be unlisted at any time.

A brokerage Hook may require pre-payment by the seller to use its services. If so the Hook should rollback with a HookReturnString that indicates how much must be first sent to the broker as a payment. The seller should send a Payment that specifies an InvoiceID of 0000000000000000000000000000000000000000000000000000000000000000 to indicate to the Hook that it is not trying to buy a URIToken that is listed, but is trying to prepay for brokerage services. The Brokerage Hook must keep track of users' prepayments in Hook State for top-up transactions and listing transactions.

Buying a non-Auction Listed Token

A buyer wishing to purchase a URIToken from a Brokerage Hook where the listing is not an auction, sends a payment for the exact amount of the list price and specifies the URITokenID in the InvoiceID of the payment transaction. The Hook must reject any payment that does not match a listing exactly. The URITokenID must exist, it must be currently owned by the Brokerage Hook, it must not be an auction, it must not be expired, and it must have a list price and currency that matches exactly the amount in the Payment transaction. If anything does not match the Payment must be rejected.

Upon successful Payment, the Hook checks the foreign state of the Issuer's account for a HookState entry in namespace 0000000000000000000000000000000000000000000000000000000000000000 with a key of 524F59414C5459 ( ROYALTY ). If the state entry is not present or is malformed, the value is assumed to be zero. If it is present the value is interpreted as an 8 byte little endian XFL indicating the percentage (a number between 0 and 1) of the sale price that goes back to the Issuer.

The Hook will then emit three transactions:

• A Payment containing the proceeds to the seller
• A URITokenSellOffer to the buyer with Amount = 0
• A Payment containing royalties to the Issuer (if any are due).

The Hook must use a callback to determine if these were successfully actioned. If any transaction fails, the account it was destined for may retry by sending an Invoke transaction to the Brokerage Hook. The Hook should evaluate what is owed to that account across all in-progress brokerages occurring in its Hook state, and attempt to pay out anything owed to that account. It is only obligated to send each user one transaction at a time. If the user is owed multiple tokens or payouts they may call Invoke multiple times. If the destination account no longer exists the broker may keep those funds or tokens.

Bidding on an Auction Listed Token

A buyer wishing to bid on a URIToken that is for sale at auction performs the same process as above, however each Payment does not action the end of the auction and multiple bidders may bid. Each Payment increases the total amount the Brokerage Hook holds on behalf of that bidder against that URIToken in the Auction. When the Auction passes the end time, the highest bidder is locked in, unless the reserve price is not met. Subsequent payments for this auction must then be rejected, as it is closed. Each party to the auction may withdraw their funds using an Invoke transaction. The first Invoke transaction causes the Hook to attempt to emit the same transactions as above, even if the Invoke is otherwise invalid (the Invoking account is not owed a balance). If the reserve price is not met, the same withdrawal process occurs but the URIToken is returned to the seller.

Well-known Lists

An XLS-53 whitelisting service will be run by the XRPLF or such other organisation or entity as the community deems fit (to be updated in this standard.) The service will allow its administrators to add and remove HookHashes from the three lists:

List Name	HookState Namespace
Compliant Brokerage Hooks	0000000000000000000000000000000000000000000000000000000000000001
Compliant Issuer Hooks	0000000000000000000000000000000000000000000000000000000000000002
Compliant co-Hooks	0000000000000000000000000000000000000000000000000000000000000003

To appear on one of the lists, the HookHash becomes a HookStateKey in the appropriate namespace, with a value consisting of the transaction ID that actioned its addition to the list. If the HookState entry is removed, or it never existed, that Hook is deemed non-compliant.

Administering Hooks

From time to time it may become necessary for the black-holed accounts to upgrade their compliant Issuer Hook or Brokerage Hook. To facilitate this at the time each Hook is installed it appoints an administrator account using the:

• 41444D494E (ADMIN) HookParameterKey
• whose corresponding HookParameterValue is the 20 byte AccountID of the administrator.

An Invoke transaction sent from this administrator specifies an action using the:

• 414354494F4E (ACTION) HookParameterKey.

The value is either:

• 55504752414445 (UPGRADE) or
• 41444D494E (ADMIN).

The HookParameterKey:

• 44415441 (DATA)

holds the respective value for the action, either:

• The 32 byte HookHash in the case of upgrade, or
• The new administrator’s 20 byte AccountID (in the case of changing the administrator.)

When upgrading an Issuer or Brokerage Hook, the HookHash must appear on the well-known list for that Hook type. Since this list is actively maintained, this provides a viable upgrade path for black-holed accounts.

Security considerations

• A minimum bid to broker accounts help prevent an account reserve lock ‘attack vector’ where a lot of accounts could spam with bids to increase the broker’s account reserve in Hook Storage to track total bid per sending account.
• This only works in a self custodial context. A market place cannot use one account to make bids on behalf of multiple users from the same account as they wouldn’t be distinguishable. To make this possible, bids should be made with a Source Tag matching the Destination Tag for refund claims, and bid bookkeeping in the broker hook would have to be on Sending Account + Source Tag combination.

FAQ

Q: Why not just include a native royalty function in XLS-35?
A: Because this would be trivially easy to bypass with a non-XLS-53 brokerage Hook. If the royalty is based on the transfer price from URITokenBuy and the token is only ever transferred with a 0 in the Amount field then any % of 0 is 0.

[TammyFYEO]

Our NFT creators on the Cosmic xahau platform need this!
🚀🚀🚀