跳到主要內容

資產聲明

「資產聲明」用於要求使用者出示特定鏈上數位資產的所有權證明，例如非同質化代幣（NFT）。這在 NFT 門禁等情境中特別有用，其中服務或內容的存取權限僅限於特定資產的所有者。

此聲明允許您的應用程式透過指定各種標準來驗證資產所有權，包括資產的地址、其發行者或其父集合。

對於可以接受資產或可驗證憑證的更通用請求，請參閱 資產或 VC 聲明。

運作方式

當您請求資產聲明時，DID Connect 會提示使用者從其錢包中選擇一個符合條件的資產。錢包會根據您在聲明請求中定義的標準篩選使用者的資產。一旦使用者選擇並出示有效資產，您的應用程式就會收到其詳細資訊以供驗證。

參數

asset 聲明使用具有以下屬性的物件進行設定。請求的核心是 filters 陣列，它允許您定義一組或多組標準。

ParameterTypeDescription
descriptionstring必填。 向使用者顯示的訊息，解釋他們為什麼需要出示該資產。
optionalboolean若為 true，使用者可以跳過此聲明。預設為 false。
filtersArray<Object>篩選物件的陣列。錢包將找到符合任何一個篩選條件的資產（OR 邏輯）。
acquireUrlstring一個可選的 URL，如果使用者尚未擁有所需資產，可以前往該 URL 獲取。

篩選物件屬性

filters 陣列中的每個物件都可以包含以下屬性。單一篩選條件中的所有屬性都以 AND 邏輯組合。

PropertyTypeDescription
addressstring資產的特定 DID 地址。
trustedIssuersArray<string | Object>受信任資產發行者的 DID 列表。發行者可以是簡單的 DID 字串或物件 { did: string, endpoint: string }。
trustedParentsArray<string>受信任父資產的 DID 列表。這通常用於驗證 NFT 是否屬於特定集合。
tagstring必須與資產關聯的特定標籤。
ownerDidArray<string>一個 DID 陣列。資產的所有者必須是此列表中的 DID 之一。
consumedboolean指定資產必須處於已消耗（true）或未消耗（false）狀態。

請求資產

以下是一些如何在傳遞給驗證器的 claims 物件中建構 asset 聲明請求的範例。

範例 1：使用 NFT 集合進行門禁控制

此範例請求任何父資產為特定 NFT 集合 DID 的資產。這是授予特定 NFT 專案持有者存取權限的常用方法。

Requesting an NFT from a specific collection

javascript
const claims = {
  asset: {
    description: '請出示您的會員 NFT 以進入私密社群。',
    filters: [
      {
        // NFT 集合的父 DID
        trustedParents: ['zNKjDm4Xsoaffb19UE6QxVeevuaTaLCS1n1S'],
      },
    ],
    acquireUrl: 'https://example.com/mint-nft',
  },
};

// 在您的路由處理程序中
const { authInfo } = await authenticator.sign({ context, claims });

範例 2：按地址請求特定資產

如果您需要使用者出示一個非常特定的資產，您可以按其唯一地址進行篩選。

Requesting a specific asset by its address

javascript
const claims = {
  asset: {
    description: '請出示您的黃金票券 NFT 以繼續。',
    filters: [
      {
        // 黃金票券 NFT 的唯一 DID 地址
        address: 'zjddPDAK5rm1E4syjTkgoiskGBAfve5YYN2s',
      },
    ],
  },
};

範例 3：使用多個篩選條件

您可以提供多個篩選物件，為使用者提供更多選擇。在此範例中，使用者可以出示來自受信任發行者的資產，或來自受信任集合的資產。

Using multiple filters for more flexibility

javascript
const claims = {
  asset: {
    description: '請出示來自我們官方發行者或合作夥伴集合的資產。',
    optional: true, // 將此項設為可選
    filters: [
      {
        // 選項 1：來自受信任發行者的資產
        trustedIssuers: ['zNKjDm4Xsoaffb19UE6QxVeevuaTaLCS1n1S'],
        tag: 'official-badge',
      },
      {
        // 選項 2：來自合作夥伴 NFT 集合的資產
        trustedParents: ['z9f9aE3E6d4c4b2A1c8f8b6e2d0F0g2H2i4j6k8m'],
      },
    ],
  },
};

錢包回應

如果使用者成功出示有效資產，您處理程序中的 onAuth 或 onConnect 回呼將收到資產詳細資訊。出示的資產將包含在會話上下文的 claims 陣列中。

您可以像這樣存取它：

Handling the wallet response

javascript
const handlers = new WalletHandlers({
  authenticator,
  // ...其他處理程序
  onAuth: async (req, res) => {
    const { userDid, claims } = req.context.did_connect;

    // 在回應中找到出示的資產聲明
    const presentedAsset = claims.find(x => x.type === 'asset');

    if (presentedAsset) {
      console.log(`使用者 ${userDid} 出示了資產：`, presentedAsset.asset);
      // `presentedAsset.asset` 將包含所出示 NFT 的完整詳細資訊
      // 例如，其地址、發行者、所有者等。
    } else {
      console.log('使用者未出示所需資產。');
    }

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

接下來，探索如何請求可驗證憑證，這是另一種驗證使用者屬性的強大方法。

可驗證憑證聲明

要求使用者出示可驗證憑證（VC）以證明屬性或資格。

閱讀更多