DIDとウォレットユーティリティ

このセクションでは、分散型識別子（DID）および暗号ウォレットに関連するユーティリティ関数の詳細なリファレンスを提供します。これらのヘルパーは、Blockletのアイデンティティを管理し、アプリケーション固有のウォレットを生成し、ユーザーセッションからアイデンティティ情報を抽出するために不可欠です。

Blockletのアイデンティティとウォレットの生成

これらの関数は、Blocklet自体のコアアイデンティティと暗号ウォレットを作成および管理するために使用されます。

toBlockletDid

文字列またはBufferを有効なBlocklet DIDに変換します。入力がすでに有効なDIDである場合は、そのまま返されます。それ以外の場合は、入力からROLE_ANYタイプのDIDを生成します。

パラメータ

name string | Buffer (required) — DIDに変換される文字列またはバッファ。

戻り値

did string — 有効なDID。

例

toBlockletDid Example

import toBlockletDid from '@blocklet/meta/lib/did';

// 文字列名からDIDを生成
const blockletName = 'my-awesome-blocklet';
const did = toBlockletDid(blockletName);

console.log(did); // 例: 'z8ia1m4f5z3a...'

// 既存の有効なDIDでも動作します
const existingDid = 'z8iZge7d4a4s9d5z...';
const result = toBlockletDid(existingDid);

console.log(result === existingDid); // true

getApplicationWallet

Blocklet用のウォレットオブジェクトを生成します。これは、他のサービスとの認証や検証可能な資格情報の作成など、署名が必要なあらゆる操作にとって重要な関数です。ウォレットは、BlockletのDIDとノードの秘密鍵の組み合わせから、または環境変数として提供されるカスタム秘密鍵から直接派生させることができます。

パラメータ

didOrSk string (required) — BlockletのDIDまたはカスタム秘密鍵。有効なDIDでない場合は、秘密鍵として扱われます。
nodeSk string — didOrSkがDIDの場合に必須。基盤となるBlocklet Serverノードの秘密鍵。
type DIDType | 'default' | 'eth' | 'ethereum' — 生成するウォレットのタイプ。Ethereum互換ウォレットには'ethereum'または'eth'をサポートします。デフォルトは標準のArcBlockタイプです。
index number (default: 0) — DIDとノードSKからウォレットを生成する際に使用される派生インデックス。

戻り値

wallet WalletObject — アドレス、publicKey、secretKey、および署名メソッドを持つOCAPウォレットオブジェクト。

例：DIDとノードSKからの生成

Generating from DID

import getApplicationWallet from '@blocklet/meta/lib/wallet';

const blockletDid = 'z8iZ...'; // BlockletのメタデータからのDID
const nodeSk = '...'; // Blocklet Serverノードの秘密鍵

const wallet = getApplicationWallet(blockletDid, nodeSk);

console.log('Wallet Address:', wallet.address);
console.log('Wallet Type:', wallet.type);

例：カスタムSKからの生成

Generating from Custom SK

import getApplicationWallet from '@blocklet/meta/lib/wallet';

// 通常、process.env.BLOCKLET_APP_SKから読み込まれます
const customSk = '...';
const wallet = getApplicationWallet(customSk);

console.log('Wallet Address:', wallet.address);

getBlockletInfo

これは高レベルのユーティリティで、Blockletの状態オブジェクトを解析して包括的なメタデータセットを抽出し、オプションでそのウォレットを生成します。blocklet.yml、環境変数、およびサーバー構成からの情報を統合します。

パラメータ

state BlockletState (required) — Blockletの状態オブジェクト。通常、Blockletのバックエンドフックまたはルートで利用可能です。
nodeSk string — Blocklet Serverノードの秘密鍵。returnWalletがtrueで、カスタムSKが環境に設定されていない場合に必要です。
options object — 設定オプション。
- returnWallet boolean (default: true) — trueの場合、関数はwalletおよびpermanentWalletオブジェクトを生成して含めます。

戻り値

info object — Blockletの情報を含むオブジェクト。
- did string — meta.didからのBlockletのDID。
- name string — Blockletの表示名。
- version string — Blockletのバージョン。
- description string — Blockletの説明。
- appUrl string — 設定されたアプリケーションURL。
- secret string — セッション管理のための派生秘密ハッシュ。
- wallet WalletObject | null — プライマリアプリケーションウォレット（returnWalletがfalseの場合はnull）。
- permanentWallet WalletObject | null — BLOCKLET_APP_PSKが設定されている場合のパーマネントウォレット。それ以外の場合はwalletと同じ。
- passportColor string — パスポートのカラースキーム。
- tenantMode string — アプリケーションのテナントモード。

例

getBlockletInfo Example

import getBlockletInfo from '@blocklet/meta/lib/info';

// 'blockletState'と'nodeSk'がコンテキストで利用可能であると仮定

try {
  const info = getBlockletInfo(blockletState, nodeSk);

  console.log(`Blocklet Name: ${info.name}`);
  console.log(`Blocklet DID: ${info.did}`);
  console.log(`App Wallet Address: ${info.wallet.address}`);

  // ウォレットが不要な場合
  const infoWithoutWallet = getBlockletInfo(blockletState, nodeSk, { returnWallet: false });
  console.log(infoWithoutWallet.wallet); // null
} catch (error) {
  console.error('Failed to get Blocklet info:', error.message);
}

ユーザーアイデンティティとアカウントヘルパー

これらのユーティリティ関数は、Blockletの認証済みルート内で通常req.userで利用可能なUserInfoオブジェクトから、DIDおよびアカウント情報を簡単に抽出できるように設計されています。

ユーザー情報ユーティリティ関数

ユーザーのアイデンティティプロファイルのさまざまな部分にアクセスするためのヘルパーのコレクション。

関数	説明
`getPermanentDid(user)`	ユーザーのプライマリでパーマネントなDIDを返します。
`getConnectedAccounts(user)`	ユーザーのプロファイルに接続されているすべてのアカウントの配列を返します。
`getConnectedDids(user)`	接続されているすべてのアカウントからのDIDの配列を返します。
`getWallet(user)`	ユーザーの接続されたウォレットアカウントオブジェクトを検索して返します。
`getWalletDid(user)`	ユーザーの接続されたウォレットのDIDを取得するための便利な関数。
`getSourceProvider(user)`	ユーザーが現在のセッションで使用したプロバイダー（例：`wallet`）を返します。
`getSourceProviders(user)`	ユーザーが接続したすべてのプロバイダーの配列を返します。

例

User Info Helpers

import {
  getPermanentDid,
  getConnectedDids,
  getWalletDid,
  getSourceProvider,
} from '@blocklet/meta/lib/did-utils';

// UserInfoオブジェクトのモック（実際のアプリでは、これはreq.userになります）
const mockUser = {
  did: 'z...userPermanentDid',
  sourceProvider: 'wallet',
  connectedAccounts: [
    {
      provider: 'wallet',
      did: 'z...userWalletDid',
      // ... その他のウォレットアカウント詳細
    },
    {
      provider: 'github',
      did: 'z...userGithubDid',
      // ... その他のgithubアカウント詳細
    },
  ],
  // ... その他のUserInfoプロパティ
};

const permanentDid = getPermanentDid(mockUser);
console.log('Permanent DID:', permanentDid); // 'z...userPermanentDid'

const walletDid = getWalletDid(mockUser);
console.log('Wallet DID:', walletDid); // 'z...userWalletDid'

const allDids = getConnectedDids(mockUser);
console.log('All Connected DIDs:', allDids); // ['z...userWalletDid', 'z...userGithubDid']

const loginProvider = getSourceProvider(mockUser);
console.log('Logged in with:', loginProvider); // 'wallet'

これらのユーティリティは、Blocklet内でアイデンティティとセキュリティを管理するための基本的な構成要素を提供します。これらのウォレットを使用してデータを署名および検証する方法については、セキュリティユーティリティセクションに進んでください。