VC-Token Federation ユーザーマニュアル

はじめに

本書の位置づけ

本書では、発行するNFTと秘匿情報を紐づけて管理し、NFT発行者・保有者の証明が可能になるVC-Token Federationの機能、API仕様、および基本シナリオの実行手順について説明します。本書はVC-Token Federationを利用してアプリケーションやサービスを企画または開発する方を対象にしており、本書を読むにあたっては、インターネットやWeb APIに関する基本的な知識が必要です。

本書の構成

本書は、以下の構成になっています。

章	内容
1. VC-Token Federationの機能	VC-Token Federationの概要、主な機能について説明します。
2. インターフェース仕様	VC-Token FederationのAPI仕様について説明します。
3. 基本シナリオ実行手順	VC-Token FederationのAPIを使用してNFTを発行し秘匿情報と紐づけ管理する基本シナリオを実行する手順を説明します。
4. 注意・制限事項	VC-Token FederationのAPIを利用する際の注意事項・制限事項を記載します。

また、付録には当技術を利用する際に有用な付録情報を記載します。

1. VC-Token Federationの機能

1.1. 機能概要

VC-Token Federationイメージ VC-Token Federationは、発行するNFTと秘匿情報を紐づけて管理し、NFT発行者・保有者の証明が可能な技術です。秘匿情報をVerifiable Credentialsとして証明書化し、NFTを紐づけて管理します。これにより、証明書の発行者＝NFTの発行者、証明書の保有者＝NFTの保有者として検証可能になります。NFTを起点にその保有者に詳細情報(秘匿情報)の開示を要求し、保有者は開示先・開示内容を同意の上、情報を開示することが可能です。VC-Token Federationでは、証明書の発行にData e-TRUSTのデジタル証明書機能を使用し機微情報を安全に管理するとともに、NFTの発行にConnectionChainを使用することで簡単なウォレット管理と多様なBCへの対応、複雑なNFT発行シナリオへの対応を実現します。なお、多様なBCおよび拡張NFT発行シナリオへの対応は現在開発中です。

VC-Token Federationは、以下の機能構成によるAPIサーバーにて提供されます。
次節以降で各機能と関連APIを説明します。 VC-Token Federation機能構成

1.2. 発行者管理機能

発行者管理機能では、NFT発行者のユーザー登録を行い、ウォレットアドレスを作成することが可能です。また、発行者ユーザーのウォレットアドレスを参照することが可能です。

当機能は、下記のAPIによって利用可能です。

API-01 発行者ユーザー登録API
API-02 発行者ユーザー参照API

1.3. 資産情報管理機能

資産情報管理機能では、NFTの発行・移行・失効を行うために必要なコントラクトアドレスなどの情報をまとめた「資産情報」を登録することが可能です。また、登録済みの資産情報を参照および削除することが可能です。

当機能は、下記のAPIによって利用可能です。

API-03 資産情報登録API
API-04 資産情報参照API
API-05 資産情報削除API (未提供)

1.4. 発行者証明書管理機能

発行者証明書管理機能では、発行者ユーザーに対し、NFT発行者証明書を発行・参照することが可能です。発行者証明書により、NFTの発行者がどのような存在であるか(発行者名や説明)を証明書化します。これにより、NFT保有者がNFTを見せる対象者(検証者)が、NFT発行者の情報を検証することが可能です。

当機能は、下記のAPIによって利用可能です。

API-06 発行者証明書発行API
API-07 発行者証明書参照API

1.5. 保有者管理機能

保有者管理機能では、NFT保有者のユーザー登録を行い、ウォレットアドレスを作成することが可能です。また、保有者ユーザーのウォレットアドレスを参照することが可能です。

当機能は、下記のAPIによって利用可能です。

API-08 保有者ユーザー登録API
API-09 保有者ユーザー参照API

1.6. NFT制御機能

NFT制御機能では、NFTの発行を行うことが可能です。NFTの発行時には、保有者ユーザーに対してNFTを発行するとともに、NFT保有者証明書を発行して紐づけを自動で行います。また、NFTの移転を行うことも可能で、保有者の持つNFTを他ウォレットアドレスへ移転し、NFT保有者に対して発行された証明書の移転先への付け替えも自動で行います。但し、移転先ユーザーは事前に登録済である必要があります。その他、保有しているNFTの参照や、発行・移転の履歴を参照することが可能です。

当機能は、下記のAPIによって利用可能です。

API-10 NFT発行API
API-11 NFT参照API
API-12 NFT移転API
API-13 NFT失効API (未提供)
API-14 NFT履歴参照API

1.7. NFT証明書管理機能

NFT証明書管理機能では、保有者ユーザーが保有するNFTに紐づいた個々の証明書の情報を取得することが可能です。

当機能は、下記のAPIによって利用可能です。

API-15 NFT証明書参照API
API-16 NFT証明書更新API (未提供)

1.8. NFT証明書開示制御機能

NFT証明書開示制御機能では、保有者ユーザーの情報を検証可能な形で開示するためのNFT証明書を生成します。保有者ユーザーは、自身が保有するNFT保有者証明書のうちどの属性を開示するかの選択が可能です。また、自己申告の付加属性情報も設定可能です。NFT証明書には、NFT保有者に関する情報の他、NFT発行者証明書の情報に基づいたNFT発行者の情報も含まれるため、検証者はNFT保有者とNFT発行者の情報を併せて検証可能です。

当機能は、下記のAPIによって利用可能です。

API-17 NFT証明書開示API
API-18 NFT証明書検証API

2. API仕様説明

2.1. 共通仕様

2.1.1 APIヘッダの設定

本APIを発行するには、Fujitsu Research Portalにて、サブスクリプションキーを発行し、ヘッダに付与する必要があります。
APIの、x-app-idヘッダにサブスクリプションキー名、Ocp-Apim-Subscription-Keyヘッダにサブスクリプションキーを付与し、APIを発行します。
また、各ユーザー権限で発行するAPIについては、x-app-user-idヘッダにユーザー名を設定し、APIを発行します。
ユーザー名については、接頭辞にサブスクリプションキー名を付与する必要があります。（<サブスクリプションキー名>_<ユーザー名>の形式）
管理者権限で発行するAPIについては、x-app-user-idヘッダの設定は不要です。

2.2. API一覧・API仕様

APIリファレンスを参照

3. 基本シナリオ実行手順

3.1. 前提条件

本基本シナリオでは、事前に作成済のテスト用スマートコントラクトを使用してNFTを発行するシナリオについて説明します。

3.2. 基本シナリオ全体像

ここでは、基本シナリオとして最もシンプルなシナリオでVC-Token Federationを使ったNFT発行、および、NFT証明書の開示方法を説明します。前提として、NFT発行に使用するスマートコントラクトのデプロイが完了している前提でのシナリオとなります。

基本シナリオ

本基本シナリオでは、事前準備、NFT発行、証明書開示の3つのフェーズに分けて説明します。

3.2.1 事前準備フェーズ

1つ目の事前準備のフェーズは、主にサービスを提供する管理者、または、サービスシステムが、本APIサービスを利用するために行う準備フェーズです。

まず最初に、システム管理者、またはサービスは、NFTを発行するためのユーザーを、発行者ユーザー登録APIを使用して登録します。次に、事前にデプロイしたスマートコントラクトの情報を元に、資産情報登録APIを使用してNFTを発行するための資産情報を登録します。その後、登録した発行者ユーザー情報に対して、NFT証明書に発行者情報として付与する発行者証明書情報を、発行者証明書発行APIを使用して設定します。最後に、NFTの発行先となる保有者ユーザーの登録を、保有者ユーザー登録APIを使用して行いますが、これは、ユーザー登録等必要なタイミングに応じて、随時NFT発行先ユーザーが追加された場合に行ってください。

3.2.2 NFT発行フェーズ

NFT発行フェーズは、実際に発行者が保有者ユーザーに対してNFTを発行するフェーズです。
NFT発行APIを使用して、発行するNFTで扱う資産情報、NFT画像・メタデータ等やNFT証明書に付与する情報の設定、および発行先ユーザーの指定を行い、NFTを発行を行います。 NFTの発行には、ブロックチェーン上に反映されるまでしばらく時間がかかる場合があります。

3.2.3 証明書開示フェーズ

証明書開示フェーズでは、NFT発行フェーズで発行されたNFTとそれに紐づくNFT証明書を、第3者に開示・証明するための手順を行うフェーズです。
該当のNFTとNFTに紐づいた属性情報を開示するには、NFT証明書開示APIを使用して、保有者自身が該当のNFT管理IDと開示する属性名を指定して、開示情報を取得し、確認者へ開示します。この際、発行者によって発行されたNFT証明書に加え、保有者自身が自己申告属性として属性を付与することも可能です。開示された情報を受け取った確認者は、その内容を確認するとともに、NFT証明書検証APIを用いて、渡されたその内容が改ざんや変更がされていないことを確認します。

3.3. 基本シナリオ実行手順

実際に基本シナリオを実行する手順をAPI単位で説明します。

発行者ユーザー登録API
- 管理者ユーザー権限で実行します。登録するユーザーIDを指定して登録します。登録した発行者ユーザーは、発行者ユーザー参照APIで参照することが可能です。
資産情報登録API
- 管理者ユーザー権限で実行します。事前にデプロイしたコントラクトアドレスと、NFT証明書発行フラグをtrueにして登録します。応答に含まれる資産IDは、NFT発行API時に使用します。登録した資産情報は、資産情報参照APIで参照することが可能です。
発行者証明書発行API
- 管理者ユーザー権限で実行します。発行者ユーザーIDを指定し、発行者証明書として設定する各パラメータを設定して発行します。資産IDには資産情報登録で登録した資産IDの中から発行者が使用する資産IDを指定してください。発行した発行者証明書は、発行者証明書参照APIで参照することが可能です。
保有者ユーザー登録API
- 保有者ユーザー権限で実行します。保有者のユーザーIDを指定して保有者のウォレットアドレスを作成、登録します。登録されたウォレットアドレスは、保有者ユーザー参照APIで参照が可能です。
NFT発行API
- 発行者ユーザー権限で実行します。発行先ユーザーIDと資産ID、NFTトークンのイメージ画像(PNGのBase64形式)、メタデータ、トークンID、トークン発行量、付加するNFT証明書属性値を指定してNFTを発行します。発行されたNFTは、保有者ユーザー権限にて、NFT参照APIで参照することが可能です。また、NFT発行・移転の履歴は、NFT履歴参照APIで参照することが可能です。NFTに紐づいた証明書を確認する場合は、NFT証明書参照APIを使用してください。
- 発行されたNFTには、一意のNFT管理IDが付与されます。NFT証明書参照APIやNFT証明書開示API等では、発行時に発行されたNFT管理IDを指定してください。
- 保有者が、本APIサーバーにて発行されたNFTを他ウォレットアドレスに移転する場合は、保有者権限にて、NFT移転APIを使用してください。
- NFT発行・NFT移転には、API応答後しばらく時間がかかる場合があります。
NFT証明書開示API
- 保有者ユーザー権限で実行します。証明したいNFTのNFT管理IDと対象の属性名を指定し実行します。応答データに検証IDと含む該当NFTの属性値を含む開示情報が返却されますので、そのデータを開示先へ提示します。
- 開示情報には、付加情報としてNFT証明書に含まれていない保有者ユーザーの自己申告情報も付与することができます。
NFT証明書検証API
- 管理者ユーザー権限で実行します。開示元のユーザーからNFT証明書開示APIの応答データを受け取り、NFT証明書検証APIの入力として実行します。応答データに検証結果が返却されますので、検証結果を確認することで、開示情報が改ざんされたデータではなく、発行者により保証されたデータであることが確認できます。

4. 注意・制限事項

4.1. 注意事項

同一コントラクトID、同一tokenIdで発行の場合、OpenSea上では後から発行したものが表示されます

4.2. 制限事項

なし

付録

付録A. Sepolia ETH入手手順

VC-Token Federationは現在、Ethereum Sepoliaテストネットを使用しています。NFTの発行などを行う場合はガス代として使用するSepolia ETHが必要です。したがってNFT発行APIを実行する前に、発行者ユーザー登録APIを実行した際に生成されるウォレットアドレスに対して、Sepolia ETHを入手する必要があります。現時点ではSepolia ETHを購入する手段はないため、本手順を参考に無料配布のSepolia ETHを入手してください。

SepoliaFaucet(Alchemy) での入手手順は以下の通りです。（24時間ごとに0.5Sepolia ETHを入手可能）

SepoliaFaucet(Alchemy) にアクセス
「Please signup or login」をクリックしアカウント登録・ログインする
入力フォームにウォレットアドレスを入力、reCAPTCHAにもチェックし「Send Me ETH」をクリック
演出とともに画面上部に「Now you can donate your new Ethereum Sepolia ETH to the ape wildlife fund.」が表示されれば入手完了（反映までは少し時間がかかることがある）

なお、faucetlink に掲載されている各サービスからも入手可能です。ただし、サービスによってはSepolia ETHの入手に達成条件が設定されている場合があります。

付録B. 独自コントラクトの配備手順

3-基本シナリオ実行手順では、事前に作成済のテスト用スマートコントラクトを使用してNFTを発行していますが、エンドユーザーが独自に作成したスマートコントラクト（独自コントラクト）を使用してNFTを発行することも可能です。以下、コントラクトの作成およびEthereum Sepoliaテストネットへの配備方法について説明します。

前提環境
- Windows, Linux, or macOS（Linux->Ubuntu 22.0.4でのみ動作確認済）
- インターネット環境（プロキシ環境外）
開発環境の準備
今回、コントラクトの開発環境としてHardhatを利用します。
2. Setting up the environmentを参考に、Node.jsをOSにインストールします。
hardhatプロジェクトの作成
3. Creating a new Hardhat projectを参考に、プロジェクトを作成します。
- npm initの実行時にpackage nameやversion等の入力を求められますが、デフォルトで良ければEnterを押下し続けることでプロジェクトの初期化が完了します。
- ページ下部にあるnpm install --save-dev @nomicfoundation/hardhat-toolboxも実行します
以下コマンドを実行し、OpenZeppelinのライブラリをインストールします。

npm install @openzeppelin/contracts
独自コントラクトの作成
前記で作成したプロジェクトフォルダ配下で作業します（参考：4. Writing and compiling smart contracts）。
contractsディレクトリを作成し、作成したディレクトリ配下にPrivateTokens.solファイルを作成します。PrivateTokens.solファイルは、下記にしたがって作成します。
```
pragma solidity ^0.8.0;

import "@openzeppelin/contracts/utils/Strings.sol";
import "@openzeppelin/contracts/token/ERC1155/extensions/ERC1155URIStorage.sol";

contract PrivateTokens is ERC1155URIStorage {
    string public name;
    string public symbol;
    modifier onlySpecific (){
        require(msg.sender == <issue,burnを許可するアカウントのアドレス>);
        _;
    }

    constructor() ERC1155("") {
        name = "FRP Tokens";
        symbol = "FRP";
        _setBaseURI("https://ipfs.io/ipfs/");
    }

    function contractURI() public view returns (string memory) {
        return "<collection設定用メタデータのURL>";
    }

    function issue(
        address receiver,
        uint256 tokenId,
        uint256 amount,
        string memory cid
    ) public onlySpecific {
        _mint(receiver, tokenId, amount, "");
        _setURI(tokenId, cid);
    }

    function burn(
        address owner,
        uint256 tokenId,
        uint256 amount
    ) public onlySpecific {
        _burn(owner, tokenId, amount);
    }
}
```
- 「issue,burnを許可するアカウントのアドレス」について
  - 発行者ユーザー登録APIによって登録されたウォレットアドレス(APIの返却値、もしくは発行者ユーザー参照APIを実行して取得)を記述します。
    - 設定値例：0x4D63eda496da2Fe23EFFB31AcaCe7Fb7c2B68f57
- 「collection設定用メタデータのURL」について
  - OpenseaやRaribleなどで閲覧する際に表示される、コントラクト自体の画像や説明文をメタデータとして追加することができます（参考：Contract-level metadata）。
  - NFT.STORAGEを介してIPFSに画像やメタデータを格納します
    ※以下URL(事前に作成済のテスト用スマートコントラクトと同じ)を記載し、本手順を省略することも出来ます
    
    ipfs://bafyreidsl7ipp6ppddx2tbmg2vd6vskr5tc7zr552vmabhnxolftkouc2y/metadata.json
    1. Uploading your images, assets, and metadataを参考にNFT.STORAGEのアカウントを登録
    2. Get an API Tokenを参考にAPIトークンを取得
    3. NFT Storage API（/store）を実行し、コントラクトcollection用のメタデータをアップロード
      - curlコマンド例
        
        curl --location 'https://api.nft.storage/store'
        --header 'Authorization: Bearer <取得したAPIトークン>'
        --form 'meta="{"name":"","description":"","image":null}"'
        --form 'image=@"<画像ファイルのパス>"'
      - 返却値例 -> "url"値がcollection設定用メタデータのURL
        { "ok": true, "value": { "ipnft": "bafyreig4ylyqwt654lzr7k7l6upvwqwyfzhluz2ci3ib7hbvho6pwwan4a", "url": "ipfs://bafyreig4ylyqwt654lzr7k7l6upvwqwyfzhluz2ci3ib7hbvho6pwwan4a/metadata.json", "data": { "name": "test", "description": "test", "image": "ipfs://bafybeieffiyddns2pjcbz6v3375zjivyjvtfigl5r3uomtyw6fqvfvhyii/test.png" } } }
- 実装補足
  - コントラクトのABI(Application Binary Interface)が変わらない範囲内であれば、関数の内部実装を追加・変更することができます
  - コントラクトのテストやデバッグについては、5. Testing contractsや6. Debugging with Hardhat Networkを参照

独自コントラクトの配備
プロジェクトフォルダ配下（contractsディレクトリと同階層）にscriptsディレクトリを作成し、作成したディレクトリ配下にdeploy.jsを作成します

参考：7. Deploying to a live network

async function main() {
  const [deployer] = await ethers.getSigners();
  console.log("Deploying contracts with the account:", deployer.address);
  const token = await ethers.deployContract("PrivateTokens");
  console.log("contract address:", await token.getAddress());
}

main()
  .then(() => process.exit(0))
  .catch((error) => {
    console.error(error);
    process.exit(1);
  });

プロジェクトフォルダ配下に存在する、hardhat.config.jsを以下のように編集します

require("@nomicfoundation/hardhat-toolbox");

// Replace this private key with your Sepolia account private key
// To export your private key from Coinbase Wallet, go to
// Settings > Developer Settings > Show private key
// To export your private key from Metamask, open Metamask and
// go to Account Details > Export Private Key
// Beware: NEVER put real Ether into testing accounts
const SEPOLIA_PRIVATE_KEY = "YOUR SEPOLIA PRIVATE KEY";

module.exports = {
  solidity: "0.8.24",
  networks: {
    sepolia: {
      url: "SEPOLIA URL",
      accounts: [SEPOLIA_PRIVATE_KEY]
    }
  }
};

YOUR SEPOLIA PRIVATE KEYには、MetaMaskなどで準備、もしくは発行者ユーザー登録API実行時に作成されたウォレットアドレスに対応する秘密鍵を設定します（十分なSepolia ETHが補充されていること）
SEPOLIA URLには、https://rpc.info/ethereum-sepolia に記載のRPC URLを記載するか、Infura, Alchemy等にアカウント登録->RPC URLを取得し記載します

最後に、プロジェクトフォルダ配下にて、以下コマンドを実行することでコントラクトをSepolia testnetに配備することができます

$ npx hardhat run scripts/deploy.js --network sepolia

実行例：

・・・省略・・・
Compiled 15 Solidity files successfully (evm target: paris).
Deploying contracts with the account: 0x4D63eda496da2Fe23EFFB31AcaCe7Fb7c2B68f57
contract address: 0xd567e347B7440B1376644D008b5a33f4bF9A6c02

デプロイ完了後、標準出力されているcontract addressをメモします
また、Etherscan(sepoliaネットワーク)等で正常にデプロイできていることを確認出来ます（contract addressを検索ボックスに入力し取引を検索）

独自コントラクト配備後のAPI利用について
- 配備した独自コントラクトのコントラクトアドレス(contract address)を資産情報登録APIにより登録し、返却される資産IDを用いてNFT発行やNFT移転を行うことで、独自コントラクトを利用することができます
- NFT発行API実行時に、コントラクトに記述した<issue,burnを許可するアカウントのアドレス>に対応するユーザーIDをapp-user-idヘッダに指定した場合、NFT発行が成功となります（今回、NFT失効(burn)APIは未提供のため、実質burnは出来ない形となります）

VC-Token Federation ユーザーマニュアル

目次

はじめに

本書の位置づけ

本書の構成

1. VC-Token Federationの機能

1.1. 機能概要

1.2. 発行者管理機能

1.3. 資産情報管理機能

1.4. 発行者証明書管理機能

1.5. 保有者管理機能

1.6. NFT制御機能

1.7. NFT証明書管理機能

1.8. NFT証明書開示制御機能

2. API仕様説明

2.1. 共通仕様

2.1.1 APIヘッダの設定

2.2. API一覧・API仕様

3. 基本シナリオ実行手順

3.1. 前提条件

3.2. 基本シナリオ全体像

3.2.1 事前準備フェーズ

3.2.2 NFT発行フェーズ

3.2.3 証明書開示フェーズ

3.3. 基本シナリオ実行手順

4. 注意・制限事項

4.1. 注意事項

4.2. 制限事項

付録

付録A. Sepolia ETH入手手順

付録B. 独自コントラクトの配備手順