NFT Unichain API for getNftsForOwners

[brg8]

Motivation

Some developers have expressed that it is annoying to call NFT API endpoints for each network that they are interested in. Some end-users may want to view their NFTs across all networks at once, for instance. This PR attempts to address this feedback for the getNftsForOwner method.

Request Ergonomics

In order to keep requests as ergonomic as possible, I decided to add the unichain api to the existing NFT namespace. That means developers will still initialize an Alchemy class with an initial network. This feels a little strange, as the developer using the unichain API will still be using a config that has a single network in it. However, it felt preferrable to other options, e.g. creating a new Network type called "Unichain".

The unichain API takes one additional parameter to the regular API, which is an array of networks: Network[]. The options dictionary is still supported and will be passed into each call to getNftsForOwner.

Response Format

At first I considered keeping the response object for the unichain call the same as for getNftsForOwner, i.e.

export interface OwnedNftsResponse {
  /** The NFTs owned by the provided address. */
  readonly ownedNfts: OwnedNft[];
  /**
   * Pagination token that can be passed into another request to fetch the next
   * NFTs. If there is no page key, then there are no more NFTs to fetch.
   */
  readonly pageKey?: string;
  /** The total count of NFTs owned by the provided address. */
  readonly totalCount: number;
}

However, a single list of owned NFTs would not be distinguishable by network. I would have to create a new OwnedNft type with a network field.

Another (perhaps larger) reason to create a new response is that pagination and sorting are an open question when it comes to this response format. Since we are making requests to multiple networks we will usually have more than 100 results. How do we decide which 100 to return? How do we sort them? How do we handle pagination? I decided to remove this complexity for now.

Implementation

The concept behind the unichain API is simple -- the developer provides a set of networks and we call getNftsForOwner for each network. The complicated part is managing page keys.

In a single-network API (read: all current APIs), the developer knows they have reached the end of the result set when the API does not return a page key. For a unichain request, however, some networks may be out of pages while others have many more to go. This makes the unichain page key a bit of a sticky wicket. The one behavior I sought to maintain is that if the unichain API does not return a page key that means the developer is done with all pages on all networks.

In any case... happy reviewing!

[github-actions[bot]]

This PR has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs