Access & membership

Architecture and responsibilities

1. 01

   Member interface

   Handle sign-in and proof of wallet ownership.

   Authentication / Wallet linking
2. 02

   Membership and facility rules

   Store facilities, validity periods, suspensions and pass IDs.

   Application DB
3. 03

   Pass issuance and consumption

   Manage holdings, issuance and transfer rules per ID.

   PrivilegeEditionHelper / ERC-1155
4. 04

   Reception and visit history

   Check eligibility and facility rules, then record admission under a visit ID.

   Reception API / Visit records

Example data model

Map application records to the data managed by the chain or APIs. Field names and values below illustrate the application model for this architecture.

Processing flow

1. 1

   Configure the pass type

   Assign an ID to a facility, validity period and transfer policy. URI, expiry and tier are shared from the first issuance of an ID, so use different IDs for different periods.

   PrivilegeEditionHelper.attach / soulbound
2. 2

   Issue to the verified member wallet

   Complete enrollment and wallet ownership verification, then mint one pass. Keep names and contact details in the application DB and publish only suitable facility and terms metadata.

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

   Check access at reception

   Verify the member with a short-lived challenge, then check balance, validity against server time, facility coverage and suspension status. An entered address or balance alone does not authorize access.

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

   Record or consume the pass

   For a monthly pass, record the visit without reducing the balance. For a single-use ticket, redeem with the holder’s or an approved operator’s signer and record admission after confirmation.

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

   Handle renewals and expiry

   Issue a new period’s ID on renewal. Reject expired passes even if their balance remains, and use sweepExpired when cleanup is needed. Apply membership suspensions in the reception rules.

   New editionId / sweepExpired / application suspension state

Before using the code

• Initialize PrivilegeEdition and grant the issuer MINTER_ROLE. Check the soulbound setting for non-transferable membership passes.
• Save editionId, URI and expiry as issuance settings. Do not use a later mint with different terms to update an existing ID.
• Pass expiresAt in UNIX seconds. Evaluate access using trusted member and facility settings and server time.

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

The TypeScript functions below are called from your application with the appropriate connections, permissions and data. Integrate the UI, persistence and recovery using the architecture above.

Issue a pass or consume a single-use ticket

issueFacilityPass uses the issuer’s signer. consumeFacilityPass is for single-use tickets and uses the holder’s signer; do not call it for monthly-pass admissions.

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 };
}

Implementation considerations

Extending the architecture

Related API and SDK reference