Implement new NFT endpoints

[zone117x]

We've aligned on the need for more NFT related endpoints that revolve around ownership. These new endpoints have come out of research and discussion started from NFT metadata support. It's not currently practical for the API to implement metadata support for NFTs akin to a large scale OpenSea-like backend to power NFT marketplaces. However, something more reasonable and also useful we can implement are endpoints that can enumerate NFTs by their asset class, or get a list of NFTs owned by a given address, or show the history of ownership for a given NFT, etc.

These endpoints will only include the type of data that is available in the db, e.g. contract addresses, NFT (Clarity) values, owner addresses, etc. They will not include metadata that must be resolved via contract calls or resolving off-chain resources such as off-chain names/descriptions, images, arbitrary attributes, etc.

For more context on out-of-scope features see Individual NFT (SIP-009) token metadata support, and Complete NFT class metadata support.

Endpoints to implement:

• Get all NFTs minted by a given asset class (smart contract principal + class name)
• Get all NFTs owned by a given principal, can be filtered by asset class
• Get ownership history of a given fully-qualified NFT asset class + NFT (Clarity) value

As mentioned above, the responses for these endpoints can include things like the asset class / address, txid, block height, NFT Clarity value.

The API can include/parse information specific to a ratified SIP, however, only if it's possible with the data currently provided via the Stacks Node event observer interface. E.g. SIP-specific contract call function signatures that the API can parse out of a tx, or contract log events.

For example, SIP-009 specifies a contract trait function:

    ;; URI for metadata associated with the token 
    (get-token-uri (uint) (response (optional (string-ascii 256)) uint))

However, token-uri for a given NFT is not something we'd implement as part of the endpoints in this PR because it would require resolving the data via contract-calls. If a contract log event for this data was also specified as part of a SIP, then it would be candidate for inclusion within these API endpoints.

[zone117x]

@rafaelcr @agraebe @markmhx @kyranjamie let me know if I've missed any endpoints, I'll add them to the list.

[rafaelcr]

Nice... I think the ownership history endpoint should include any associated STX transactions so marketplaces can display the sell price

[markmhendrickson]

This looks theoretically useful to me, though @agraebe was closer to the user research and might know of specific developers who'd want to review and verify that this plan would satisfy their present needs. Perhaps we can @ mention them here to take a look.

Separately, do we want this to be an extension of the API after all rather than a separate service?

[rafaelcr]

@markmhx The idea right now is to add these endpoints to the API as it is today. We'd revisit the endpoint distribution once we follow up with the microservices project we've been planning.

[aulneau]

Hi there -- curious if there is any time estimate for this line item:

Get all NFTs owned by a given principal, can be filtered by asset class

Working on a project now that would greatly benefit from this being implemented.

Thanks!

[asimm241]

@zone117x are the specifications finalized so that Tintash can take this on?

[rafaelcr]

@aulneau @asimm241 I've already started working on this, stay tuned for updates

[rafaelcr]

All new endpoints are now merged and will be available in the next release