利用権・会員資格

システム構成と役割

1. 01

   会員画面

   ログインとウォレットの所有確認を行います。

   Authentication / Wallet linking
2. 02

   資格・施設の管理

   利用施設、期間、停止状態、パスIDとの対応を保存します。

   Application DB
3. 03

   パスの発行・消費

   IDごとの保有数、発行数、譲渡条件を扱います。

   PrivilegeEditionHelper / ERC-1155
4. 04

   受付・利用履歴

   資格と施設ルールを確認して入場を許可し、受付IDで記録します。

   Reception API / Visit records

データモデル例

業務DBに保存する情報と、チェーンやAPIで管理する情報を対応づけます。フィールド名とサンプル値は、この構成で使うアプリケーション側の設計例です。

処理の流れ

1. 1

   パスの種類を設定する

   施設・期間・譲渡可否を決め、IDを割り当てます。同じIDでは最初の発行で設定されたURI・期限・tierを共有するため、期間が異なるパスには別のIDを用意します。

   PrivilegeEditionHelper.attach / soulbound
2. 2

   本人のウォレットへ発行する

   会員登録と所有確認を済ませ、会員へ1枚をmintします。氏名や連絡先は業務DBで管理し、公開URIには施設名や利用条件など公開可能な情報を掲載します。

   mint(member, editionId, 1n, uri, 0, expiresAt, 0n)
3. 3

   受付で利用可否を確認する

   短い有効期限を持つチャレンジなどで本人を確認し、保有数・サーバー時刻による有効期間・施設の対象範囲・会員の停止状態を照合します。アドレスの入力や残高だけでは入場を許可しません。

   Wallet ownership check → contract.balanceOf → application access rules
4. 4

   パスの種類に応じて利用を記録する

   月間パスは残高を減らさずvisitIdで利用記録を保存します。1回券は保有者または承認済みoperatorの署名でredeemし、確定を確認してから入場を記録します。

   Monthly: visit record / Single-use: redeem(holder, editionId, 1n)
5. 5

   更新・失効を反映する

   更新時は新しい期間のIDを発行します。期限切れ残高が残っていても受付では拒否し、必要に応じてsweepExpiredによる消込を行います。業務上の会員停止も受付ルールに反映します。

   New editionId / sweepExpired / application suspension state

コードを利用する前の準備

• PrivilegeEditionの初期化と、発行者へのMINTER_ROLE付与を済ませます。譲渡不可の会員パスではsoulboundの設定を確認します。
• editionId・URI・期限を発行設定として保存します。同じIDへ異なる期限を渡して更新する使い方はしません。
• expiresAtはUNIX秒を渡します。利用時の判定は、信頼できる会員・施設の設定とサーバー時刻で行います。

npm install --save-exact @hazbase/kit@0.9.0 ethers@6.16.0

以下はアプリケーションから呼び出すTypeScriptの関数です。接続先・権限・対象データを引数として渡します。UI、DBへの保存、処理の再開は、上記の構成に沿って業務側へ組み込めます。

利用パスを1枚発行する／1回券を消費する

issueFacilityPassは発行者のSignerを使用します。consumeFacilityPassは1回券用で、保有者自身のSignerを使用します。月間パスの入場処理からは消費用関数を呼び出しません。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

import { PrivilegeEditionHelper } from '@hazbase/kit';
type Signer = Parameters<typeof PrivilegeEditionHelper.deploy>[1];

export async function issueFacilityPass(input: {
  editionAddress: string;
  member: string;
  editionId: bigint;
  metadataUri: string;
  expiresAt: bigint;
  issuer: Signer;
}) {
  // One edition ID shares one URI, expiry and tier across all holders.
  const pass = PrivilegeEditionHelper.attach(input.editionAddress, input.issuer);
  const receipt = await pass.mint(
    input.member, input.editionId, 1n,
    input.metadataUri, 0, input.expiresAt, 0n,
  );
  // Standard ERC-1155 balanceOf is available on the underlying contract.
  const balance = BigInt(await pass.contract.balanceOf(input.member, input.editionId));
  return { balance: balance.toString(), transactionHash: receipt.hash };
}

export async function consumeFacilityPass(
  editionAddress: string,
  editionId: bigint,
  holder: Signer,
) {
  // Use for a single-use pass, after the service checks its validity.
  const pass = PrivilegeEditionHelper.attach(editionAddress, holder);
  const receipt = await pass.redeem(await holder.getAddress(), editionId, 1n);
  return { transactionHash: receipt.hash, blockNumber: receipt.blockNumber };
}

実装で押さえておきたい点

用途に合わせた拡張

関連するAPI・SDK仕様