This repo contains a client library for uploading data to NFT.Storage using a signature from a solana private key to authenticate the request.

See SPEC.md for details about the authentication scheme.

Hello from NFT.Storage!

As of June 30, 2024, we have officially decommissioned NFT.Storage Classic uploads. This means that NFT.Storage Classic, including NFTUp, the Classic web app, Classic APIs, Classic SDK, and Pinning API, will no longer accept new uploads/pins.

Service Termination: NFT.Storage Classic will no longer accept new uploads. However, retrieval of existing data remains operational.

Data Access: Don't forget, we're still keeping a copy of your NFT.Storage Classic data available in the NFT.Storage Gateway and in the decentralized Filecoin Network. However, over time, latency and availability may degrade.

Support: We’ll be working with the newly formed NFT.Storage community to determine what changes, if any, will impact NFT.Storage Classic data latency and availability in the future. Join the community Join the community to have your say. We will keep you informed by email and on Twitter/X.

For the new version of NFT.Storage, first mint your NFTs, then send us the NFT data—metadata and imagery CIDs, blockchain(s) minted on, contract address, and token IDs. We will preserve these in long-term Filecoin storage. Note that you need to upload the data to IPFS separately. Your NFTs will also be included in the NFT Token Checker, a tool for block explorers, marketplaces, and wallets to show verification that NFT collections, tokens, and CIDs are preserved by NFT.Storage.

We’re excited to announce our partnerships with Pinata and Lighthouse for hot storage solutions. As an NFT.Storage user, you support our platform when you choose Pinata and Lighthouse and use our referral links, helping to sustain our valuable public goods. Learn more here.

Pinata: Offers flexible plans and powerful, easy-to-use tools for managing your data on IPFS. Use code NFTSTORAGE50 at checkout to enjoy 50% off your first month. Sign up today.

Lighthouse: An IPFS provider with unique payment options for NFT longevity. They offer affordability and flexibility for all your IPFS needs, including a pay-once and store-forever option. Sign up today.

For any questions or assistance, contact us contact us. Together, we look forward to a promising future for NFT.Storage and the broader NFT ecosystem.

Best regards,
The NFT.Storage Team

npm install @nftstorage/metaplex-auth

or

yarn add @nftstorage/metaplex-auth

This package is primarily intended to be used as a library in your JavaScript or TypeScript project.

API reference docs can be found at https://nftstorage.github.io/metaplex-auth/

The main entry point into the API is the NFTStorageMetaplexor class, which provides methods for uploading files to NFT.Storage.

To create an NFTStorageMetaplexor, you'll need either a Solana private signing key or a signMessage function that can return a valid Ed25519 signature for a Solana account (for example, from a wallet adapter).

The methods for creating an NFTStorageMetaplexor also require a mintingAgent string.

The mintingAgent should identify the tool or platform used to prepare the upload.

Projects using this library are free to choose their own value for this tag, however you should avoid changing the name over time, unless the project itself changes names (for example, due to a community fork or re-branding).

For personal projects or individuals creating tools that are not affiliated with a public platform, please set the value to a URL for your code repository. If your code is not yet public, please create a repository containing a description of the project and links to its public-facing interface.

Examples of suitable values:

• "metaplex/candy-machine-cli"
• "metaplex/js-sdk"
• "magiceden/mint-authority"
• "https://github.com/samuelvanderwaal/metaboss"

You may also optionally pass an agentVersion string, to differentiate between different versions of your project.

The NFTStorageMetaplexor.withSecretKey static method accepts a Uint8Array containing a secret Ed25519 signing key.

It also optionally accepts an options object that can be used to set some metadata about the request. Most importantly, you should set the solanaCluster option to the cluster you intend to mint on. If not provided, it will default to devnet.

import { NFTStorageMetaplexor } from '@nftstorage/metaplex-auth'

const key = loadKeyFromSomewhere()
const client = NFTStorageMetaplexor.withSecretKey(key, {
  solanaCluster: 'mainnet-beta',
  mintingAgent: 'my-awesome-tool',
})

If you're using a wallet adapter that supports the signMessage function, you can use it with the NFTStorageMetaplexor.withSigner static method by passing in the signMessage function and the public key.

import { NFTStorageMetaplexor } from '@nftstorage/metaplex-auth'
import { useWallet } from '@solana/wallet-adapter-react'

const MyComponent = () => {
  const { publicKey, signMessage } = useWallet()
  const client = NFTStorageMetaplexor.withSigner(signMessage, publicKey, {
    solanaCluster: 'mainnet-beta',
    mintingAgent: 'my-awesome-tool',
  })
}

To assist with uploading Metaplex NFTs, this package includes support for loading Metaplex NFT metadata and uploading files that are referenced within.

The storeNFT methods will validate the metadata using a JSON schema to catch any formatting errors before upload.

Please note that the schema validation code has not been widely tested yet on real-world NFT data and may be too restrictive. If you believe that it is rejecting valid metadata, please open an issue.

If you're using node.js, you can use the NFTStorageMetaplexor.storeNFTFromFilesystem method to load NFT data from disk and upload it in one operation.

async function uploadNFT(pathToMetadataJson) {
  const key = loadKeyFromSomewhere()
  const client = NFTStorageMetaplexor.withSecretKey(key)

  const result = await client.storeNFTFromFilesystem(pathToMetadataJson)
}

If you're running in a browser, you'll need to use the prepareMetaplexNFT function, which accepts metadata as a JS object and takes File objects containing image and other asset data. The resulting PackagedNFT object can be passed into the storePreparedNFT method.

The prepareMetaplexNFT and storeNFTFromFilesystem methods will upload the image, animation_url and any files contained in properties.files if they contain valid file references.

In the case of prepareMetaplexNFT, the provided imageFile parameter will be uploaded, along with any additionalAssetFiles. The image field in the metadata will be replaced with an HTTP gateway URL to the uploaded image. Likewise, if the animation_url field contains the name of one of the additionalAssetFiles, the field will be replaced with a gateway URL.

All entries in properties.files will likewise be replaced with IPFS links if the uri field contains the filename of any of the uploaded files. Each uploaded file will contain two entries in the final metadata: one containing an HTTP gateway URL with the cdn flag set to true, and one location-independent ipfs:// URI with cdn set to false. This should allow clients to fetch content over HTTP while still preserving a location-independent link that doesn't depend on a single gateway.

When using storeNFTFromFilesystem on node.js, the same rules apply, however you don't need to pass in File objects for each asset. Instead, you can set the image field (and optionally, animation_url) to a file path relative to the metadata JSON file, and the image data will be loaded from disk. Likewise, any entries in properties.files whose uri contains a valid file path will be uploaded, and the entry will be replaced with two IPFS links as with prepareMetaplexNFT.

You can upload arbitrary files using the storeDirectory method. It accepts an Iterable of File objects and bundles them into an IPFS directory listing, returning the root CID of the stored directory.

async function uploadFiles(files) {
  const key = loadKeyFromSomewhere()
  const client = NFTStorageMetaplexor.withSecretKey(key)

  const cid = await client.storeDirectory(files)
  console.log(
    `Stored ${files.length} file(s). Check them out at https://${cid}.ipfs.nftstorage.link`
  )
}

Note that the returned CID links to a directory object containing the files. If you want to link to individual files within the directory, you must append the filename to the result:

async function uploadFiles(files) {
  const key = loadKeyFromSomewhere()
  const client = NFTStorageMetaplexor.withSecretKey(key)

  const cid = await client.storeDirectory(files)

  // make HTTP gateway links using the nftstorage.link gateway
  const gatewayBaseUrl = new URL(`https://${cid}.ipfs.nftstorage.link`)
  const gatewayLinks = files.map((f) => new URL(f.name, gatewayBaseUrl))

  // make gateway-agnostic IPFS uris:
  const uriBase = new URL(`ipfs://${cid}`)
  const ipfsURIs = files.map((f) => new URL(f.name, uriBase))
}

Under the hood, all the upload methods encode data into IPFS Content Archives (CARs) before uploading.

If you already have CAR-formatted data, you can upload it with the storeCar method.

This may be useful if you have already imported your data into IPFS, or if you want to have more control over the object graph, for example, because you want to use IPLD to store structured data.

The storeCar method accepts a CarReader from the @ipld/car package.