Asset Claim

The Asset Claim is used to request that a user present proof of ownership for a specific on-chain digital asset, such as a Non-Fungible Token (NFT). This is particularly useful for scenarios like NFT-gated access, where entry to a service or content is restricted to owners of a particular asset.

This claim allows your application to verify asset ownership by specifying various criteria, including the asset's address, its issuer, or its parent collection.

For more general requests that can accept either an asset or a Verifiable Credential, see the Asset or VC Claim.

How It Works#

When you request an Asset Claim, DID Connect prompts the user to select a qualifying asset from their wallet. The wallet filters the user's assets based on the criteria you define in the claim request. Once the user selects and presents a valid asset, your application receives its details for verification.

Parameters#

The asset claim is configured using an object with the following properties. The core of the request is the filters array, which allows you to define one or more sets of criteria.

Parameter	Type	Description
description	string	Required. A message displayed to the user explaining why they need to present the asset.
optional	boolean	If true, the user can skip this claim. Defaults to false.
filters	Array<Object>	An array of filter objects. The wallet will find assets that match any of the filters (OR logic).
acquireUrl	string	An optional URL where the user can go to obtain the required asset if they don't already own one.

Filter Object Properties#

Each object within the filters array can contain the following properties. All properties within a single filter are combined with AND logic.

Property	Type	Description
address	string	The specific DID address of the asset.
trustedIssuers	Array<string | Object>	A list of DIDs of trusted asset issuers. An issuer can be a simple DID string or an object { did: string, endpoint: string }.
trustedParents	Array<string>	A list of DIDs of trusted parent assets. This is commonly used to verify if an NFT belongs to a specific collection.
tag	string	A specific tag that must be associated with the asset.
ownerDid	Array<string>	An array of DIDs. The asset's owner must be one of the DIDs in this list.
consumed	boolean	Specifies whether the asset must be in a consumed (true) or unconsumed (false) state.

Requesting an Asset#

Here are some examples of how to structure an asset claim request within the claims object passed to the authenticator.

Example 1: Gating Access with an NFT Collection#

This example requests any asset whose parent is a specific NFT collection DID. This is a common way to grant access to holders of a particular NFT project.

const claims = {
  asset: {
    description: 'Please present your Membership NFT to access the private community.',
    filters: [
      {
        // The parent DID of the NFT collection
        trustedParents: ['zNKjDm4Xsoaffb19UE6QxVeevuaTaLCS1n1S'],
      },
    ],
    acquireUrl: 'https://example.com/mint-nft',
  },
};

// In your route handler
const { authInfo } = await authenticator.sign({ context, claims });

Example 2: Requesting a Specific Asset by Address#

If you need the user to present a very specific asset, you can filter by its unique address.

const claims = {
  asset: {
    description: 'Please present your Golden Ticket NFT to proceed.',
    filters: [
      {
        // The unique DID address of the Golden Ticket NFT
        address: 'zjddPDAK5rm1E4syjTkgoiskGBAfve5YYN2s',
      },
    ],
  },
};

Example 3: Using Multiple Filters#

You can provide multiple filter objects to give the user more options. In this example, the user can present either an asset from a trusted issuer OR an asset from a trusted collection.

const claims = {
  asset: {
    description: 'Present an asset from our official issuer or a partner collection.',
    optional: true, // Making this optional
    filters: [
      {
        // Option 1: Asset from a trusted issuer
        trustedIssuers: ['zNKjDm4Xsoaffb19UE6QxVeevuaTaLCS1n1S'],
        tag: 'official-badge',
      },
      {
        // Option 2: Asset from a partner NFT collection
        trustedParents: ['z9f9aE3E6d4c4b2A1c8f8b6e2d0F0g2H2i4j6k8m'],
      },
    ],
  },
};

Wallet Response#

If the user successfully presents a valid asset, the onAuth or onConnect callback in your handler will receive the asset details. The presented asset will be included in the claims array of the session context.

You can access it like this:

const handlers = new WalletHandlers({
  authenticator,
  // ...other handlers
  onAuth: async (req, res) => {
    const { userDid, claims } = req.context.did_connect;

    // Find the presented asset claim in the response
    const presentedAsset = claims.find(x => x.type === 'asset');

    if (presentedAsset) {
      console.log(`User ${userDid} presented asset:`, presentedAsset.asset);
      // The `presentedAsset.asset` will contain the full details of the presented NFT
      // e.g., its address, issuer, owner, etc.
    } else {
      console.log('User did not present the required asset.');
    }

    res.redirect('/profile');
  },
});

Next, explore how to request a Verifiable Credential, another powerful way to verify user attributes.