Draft for Standard trait definition for extending tokens

[314159265359879]

I gave this a preliminary SIP number (not sure if I am allowed or the CAB determines it) but we can change it, I like to have something here asap because it makes it easy to refer to the document. I choose 029 (because they do not have be in order (paraphrasing Jude) and to signal the relationship to SIP009.

I have texted briefly about how to write this draft with Friedger and dant before structuring it this way. It could have also been four separate traits/standards but they belong together and Friedger and Dan thought this would be the better way.

This is the first time I share my draft, feedback is needed and I will also need help from a dev to handle the technical feedback.

I have also included some questions myself starting with "werner:" feel free to comment here if you know more.

I would like to get this standard ratified so it can also be integrated into BNSv2

See my draft here (I am not sure how to send it properly as a PR):
https://github.com/no314/stx-fan/blob/main/sips-ip/sip-029_extending-tokens.md

[314159265359879]

Mentioning the sources used. Extension for asset traits (transferable and operable) #52 Marketplace function #51 Generalized marketplace function (list-in-token vs. list-in-ustx) #51 (comment) Optional send-many trait (from SIP013 semi-fungible token) https://github.com/stacksgov/sips/pull/42/files

Additionally used the SIP009 trait as a template for the draft.

[314159265359879]

adding this here to keep it all in one place

[mijoco-btc]

Can this also support SFT (e.g. via SIP-013) and list/buy in token as per @LNow suggestion #60 ?

There is an example in Clarity Lab of doing SFT with generalised token.

I don't know if both SFT and NFT can be supported by the same trait functions but it would be interesting if there is a general solution for it?

For generalised tokens the solution involves wrapping the STX transfer in a SIP-010 as in this contract.

[mijoco-btc]

Re-read the other thread and see there may be a problem with list-in-token with the commission ?

[314159265359879]

Can this also support SFT (e.g. via SIP-013) and list/buy in token as per @LNow suggestion #60 ?

There is an example in Clarity Lab of doing SFT with generalised token.

I don't know if both SFT and NFT can be supported by the same trait functions but it would be interesting if there is a general solution for it?

For generalised tokens the solution involves wrapping the STX transfer in a SIP-010 as in this contract.

I would not know how to adapt the code from the repo's I have used to support SFT and NFT in the same trait. Perhaps something like this can work:
Now we use a uint to either represent the NFT's token id or the FT's token amount. What if we add an optional uint and whenever that is used we have a token id and the optional is used for the amount (perhaps only if more than 1) for semi-fungible tokens (SFT).

Re-read the other thread and see there may be a problem with list-in-token with the commission ?

I do not understand this part. Not sure what to do here. Should commission always be in uSTX?

I have send some updates based on the feedback thus far.
no314/stx-fan@6efd0dd

[whoabuddy]

After the call today I was thinking about how this would fit into the SIP process, and I see two distinct things that we're asking for here:

1. A standard for extending tokens, such that by taking steps X, Y, Z you could create a new "add-on" to an existing token standard. By defining it this way, it would outline what it takes to create an extension to an existing token, and part of that could be listing which tokens are supported. This would be a static definition, and updating it would require a new SIP.
2. A collection of extensions that use the standard, which would be the implementations that smart contract developers can use to extend their tokens. If I want this type of feature, the first place I would look are the supported items in this registry. If I want to create something new, I'd submit a SIP that describes how it implements (1) and the extension details.

That would hopefully create a flywheel effect where items are created for (2) based on criteria laid out in (1), and if a feature doesn't exist yet, this would be the official framework for adding it.

If (1) were upgraded, then all contracts in (2) would need to consider the changes and upgrade or implement something new. That'd be a big change, and existing creators of contracts in (2) would be good candidates on feedback for an update proposal.

If (2) were upgraded, it can simply be versioned and added to the registry. Say that initially the marketplace standard doesn't support SIP-013, but this was added in a future version, or if there was one version for SIP-009/010 and a second one for SIP-013. That would hopefully allow for iterative and flexible development of the extensions.

One way to manage the list could be to implement a trait for (1) that all contracts in (2) follow - which could be queried and listed pretty easily with the API.

Overall I'm supportive of getting people on the same page!

[314159265359879]

After the call today I was thinking about how this would fit into the SIP process, and I see two distinct things that we're asking for here:

1. A standard for extending tokens, such that by taking steps X, Y, Z you could create a new "add-on" to an existing token standard. By defining it this way, it would outline what it takes to create an extension to an existing token, and part of that could be listing which tokens are supported. This would be a static definition, and updating it would require a new SIP.
2. A collection of extensions that use the standard, which would be the implementations that smart contract developers can use to extend their tokens. If I want this type of feature, the first place I would look are the supported items in this registry. If I want to create something new, I'd submit a SIP that describes how it implements (1) and the extension details.

That would hopefully create a flywheel effect where items are created for (2) based on criteria laid out in (1), and if a feature doesn't exist yet, this would be the official framework for adding it.

If (1) were upgraded, then all contracts in (2) would need to consider the changes and upgrade or implement something new. That'd be a big change, and existing creators of contracts in (2) would be good candidates on feedback for an update proposal.

If (2) were upgraded, it can simply be versioned and added to the registry. Say that initially the marketplace standard doesn't support SIP-013, but this was added in a future version, or if there was one version for SIP-009/010 and a second one for SIP-013. That would hopefully allow for iterative and flexible development of the extensions.

One way to manage the list could be to implement a trait for (1) that all contracts in (2) follow - which could be queried and listed pretty easily with the API.

Overall I'm supportive of getting people on the same page!

Thinking through this I do think the two step approach can make sense I am just not sure what I would want X, Y, Z, to look like. We'd have to make sure not to be restrictive in any way as to not restrict development of new extensions.

With your remarks in the meeting I was thinking more along the line of splitting this SIP up. One that holds all the traits that are beneficial to the marketplace trait (transferable, operable, marketplace and commission trait) but have the bulk-send trait in a different SIP. I guess if we move to a model of hierarchy (1. and 2. as you suggest) this could cover that too.
SIP029 general standard for extending tokens
SIP029.1 marketplace extension standard
SIP029.2 bulk-send extension standard

The reason I am not sure this is the best solution for the marketplace trait though is because: IF we want to achieve maximum generalizability (which I assumed from the previous conversations leading to the code currently in this standard). Then we would prefer a standard that takes a bit more time to get right and include compatibility with SIP013 SFT's rather than having 1 standard now for NFT/FT and another later just for SFT's.

[314159265359879]

For anyone checking this topic and who wants to contribute, the open questions:

1. Is it possible and advantageous to generalize the traits to be compatible with semi-fungible tokens (SFT per SIP013), how?
   post 1, post 2

2. What is the exact issue with commission trait and list-in-token, and how to solve it?
   Post 1

3. Additionally I'd love more input on splitting up the SIP and how? (or reasons not to do so)
   Suggestion by Jason here, and mine above this post.

[friedger]

1. Is it possible and advantageous to generalize the traits to be compatible with semi-fungible tokens (SFT per SIP013), how?

I don't see a good solution. A generalized trait would come at a cost. Users would need to be informed why there are more "unused" parameters. I am not a fan of the optional for transfer, instead just another uint parameter that is ignored for NFTs and FTs.

2. What is the exact issue with commission trait and list-in-token, and how to solve it?

I heard that users might get confused that the listed price does not include the additional fees from the commission trait.

3. ..splitting up the SIP..

I like a SIP that just focuses on marketplace functions

[Jamil]

In favor of splitting this up as well.

For example, I’d love to have the marketplace functions as a SIP (they basically are a de facto standard right now).

However, things like operable I’m less sure about. I used to be in favor of it in principle, but it opens up a lot of doors for issues as well, and I think the lack of an approve pattern is something that differentiates Stacks NFTs in a positive way from Ethereum ones. The attack surface is dramatically reduced without it, and with an approval pattern, post-conditions become far less secure as a protection against NFT asset theft/exploits. Even if adopted as a SIP, I would probably still lean against incorporating it in Portal contracts — in the end, SIPs should be developed in tandem with developer adoption and sentiment and not as some kind of higher-level dictum.

Either way, we could probably debate the operable trait to no end, but the main principle is that each extension to SIP-9 should be adopted independently, especially for such a varied set of functionality. Some (like the marketplace functions) are already adopted as de facto standards, and others are completely new. Treating them as the same will just result in fragmentation and likely a bunch of “partially SIP-29 conformant” NFTs as developers choose which to adapt to their needs and requirements.

[Jamil]

I heard that users might get confused that the listed price does not include the additional fees from the commission trait.

Is there a proposed solution for this? Intuitively seems like it’d be difficult to get around this without changing the way commissions are done (e.g., by setting a commission percent or structure rather than an open-ended function call)

[friedger]

I like the commission solution we have right now. Maybe we should add recommendations for how to present this on the market places and wallets. Currently, the user might get confused by the different numbers.

[Jamil]

Yeah, right now we "abstract away" the commission and treat everything as all-in prices on Gamma. For example, if you list something at 1 STX, we don't send 1000000 to list-in-ustx, but rather 1000000/(1+comm) as the price argument. This seems to work quite well, though indexing and keeping track of commission amounts is difficult without a standard around it, and we often have to manually add commission traits and figure out what the % is by just looking at the contract.

[314159265359879]

Thanks for the input @friedger and @Jamil this is exactly what I needed.

1. Alright so I can design a more generalized trait with an additional uint parameter that is ignored for NFT's and FTs.
   And we can let the CAB help determine if the cost (an unused parameter for sending NFTs and FTs) is worth it if that means we have one trait to extend SFT's, NFTs and FTs.
   The alternative would be two traits (1) for NFT's and FT's and (2) just for SFT's

2. I am not sure if that is what @radicleart was referring to when he said "there is an issue with list-in-token with the commission", I will ping him here to make sure.

As far as confusion about listed price not including the additional fees: I believe the argumentation landed on that it can be resolved by the UI. I think gamma.io and tradeport.xyz prove this by showing very clearly to the user what the effect is of setting a price, and how the money flows on a sale:

Example 1 tradeport.xyz

Example 2 gamma.io

3. Jason, Jamil and Friedger in favor of splitting this up. The reason I started this process was to get a SIP for the Marketplace functions so I am in favor of making this the marketplace SIP too.

As for @whoabuddy comment about a general SIP for "token extensions" it may look to much like rewriting/extending SIP000, I am not convinced that is needed/convenient.
I think we may help developers understand the structure and how SIPS extend others if we make a page that organizes the SIPs in such a way that we show which SIP's extend which token trait: something like this:

[314159265359879]

Trying to write a marketplace SIP that is compatible with SIP013 on the selling side (listing a SIP013 (SFT), SIP009 (NFT) or SIP010 (FT) token(s) for sale) and buying side (buying the listed token with SIP013, SIP009 or SIP010) is not something I can find in existing repo's I have come to the conclusion that more work is needed before I can draft a generalized SIP to cover such a trait. Namely: clarity contract of a reference trait and tests. I think that SIP should take into account the discussion that lead to this thread and hence I will set out what I think is needed for such a SIP (lets call it the "Generalized marketplace standard", SIP22?)

Circling back to what I can do is get the defacto standard in a SIP and that is list-in-ustx lets call it the "uSTX marketplace standard" (SIP11?). I think there is still value in getting this ratified as a standard because of its widespread use.
I think that SIP could look something like this:
https://github.com/no314/stx-fan/blob/main/sips-ip/sip-011_ustx-marketplace-standard.md

TODO:
Make a standard interface for the marketplace operations you see in the SIP above yet making it compatible with all the standard tokens and STX with a single set of functions.
with
A: list-in-token, buy-in-token etc..
B: support for token-id (NFT's and SFT's) and amount (FT's and SFT's) an argument ignored for tokens it does not apply to (i.e. FT's do not have a token id). both buy side and sell side.
C: STX used as a SIP010 compatible token

Work in progress here, requires help from Clarity dev to finish:
https://github.com/no314/stx-fan/blob/main/sips-ip/sip-022_Generalized_marketplace_standard.md

Here is a mockup to allow A, B, C, C is explained in the paragraph "Recommendation for using STX as SIP010 token" as proposed by lNow

(use-trait commission-trait .commissions.trait)
(define-trait marketplace
    (
        ;; announce listing to global marketplace
        ;; must return `(ok true)` on success, never `(ok false)`
        ;; must send a list event
        ;; @param; token-trait-sell (of token(s) to list)
        ;; @param id (to list); identifier of NFT or SFT (ignored if <token-trait-sell> = FT)
        ;; @param amount (to list); amount of FT or SFT (ignored if <token-trait-sell> = NFT)
        ;; @param; token-trait-buy (to buy with)
        ;; @param token-id; identifier of NFT or SFT to list for (ignored if <token-trait-buy> = FT)
        ;; @param price(amount): of sale in smallest denomination of the token defined by <token-trait-buy> (ignored if <token-trait-buy> = NFT)
        ;; @param commission: action to happen after sale
        (list-in-token (<token-trait-sell> uint uint <token-trait-buy> uint uint <commission-trait>) (response bool uint))

        ;; announce delisting to global marketplace
        ;; must return `(ok true)` on success, never `(ok false)`
        ;; must send a delist event
        ;; @param id; identifier of NFT or SFT (ignored if <token-trait-sell> = FT)
        ;; @param amount; amount of FT or SFT (ignored if <token-trait-sell> = NFT) (note: you can also list FT's on a global marketplace)
        (unlist-in-token (uint uint) (response bool uint))

        ;; buy and announce delisting to global marketplace
        ;; must return `(ok true)` on success, never `(ok false)`
        ;; commission must match the one set during listing
        ;; must send a delist event
        ;; @param; token-trait-buy (token to buy with)
        ;; @param id; identifier of NFT or SFT (ignored if FT)
        ;; @param amount; amount of FT or SFT (ignored if NFT)
        ;; @param commission: action to happen after sale        
        (buy-in-token (<token-trait-buy> uint uint '<commission-trait>') (response bool uint))

        ;; read-only function defining the asset
        (get-asset () (response {fq-contract: string, asset-class: string} uint))
    )
)

(define-trait commission
    (
        ;; additional action after a sale happened, usually a fee transfer for marketplaces
        ;; must return `(ok true)` on success, never `(ok false)`
        ;; @param id; identifier of NFT or SFT (ignored if FT)
        ;; @param amount; amount of FT or SFT (ignored if NFT)
        ;; @param; token-trait-buy
        ;; @param token-id; identifier of NFT or SFT sold for (ignored if <token-trait-buy> = FT)
        ;; @param price(amount): of sale in smallest denomination of the token defined by <token-trait-buy> (ignored if <token-trait-buy> = NFT)
        (pay (uint uint <token-trait-buy> uint uint) (response bool uint)) (Note: when buying with SFT's or an NFT, how to fractonalise for commissions if at all? standard rounding down to whole tokens? commissions in STX or no commissions, subscriptions instead?)
    )
)