Physical assets & inventory

Architecture and responsibilities

1. 01

   Asset interface

   Display equipment, agreements, recipients and quantities.

   Web UI
2. 02

   Application API and register

   Map asset IDs to tokens and manage permissions and operation IDs.

   Application API / DB
3. 03

   Issuance and transfers

   Enforce the issuance cap, track balances and execute permitted transfers.

   FlexibleTokenHelper
4. 04

   History synchronization

   Index confirmed transactions and link them to operating and inspection records.

   Transaction receipts / Events

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

   Register the asset and right

   Register A-001 and agreement AGR-2027-001. With one contract per asset, the token balance represents units of the right associated with that equipment.

   Application DB: assetId → agreementId → tokenAddress
2. 2

   Initialize the token

   Prepare FlexibleToken with a cap of 1,000 and zero decimals. Grant the issuer MINTER_ROLE and configure transferability and any required allowlist.

   FlexibleTokenHelper.deploy / attach
3. 3

   Allocate 10 units

   Save the allocation request before minting. Associate the confirmed receipt with the request and read the balance. Use transfer with the holder’s signer when moving existing units.

   mint(recipient, amount) → balanceOf(recipient)
4. 4

   Update the holder view

   Index Transfer events using chainId, transactionHash and logIndex as a unique key. Periodically reconcile the display database with on-chain balances.

   Transfer events / balanceOf
5. 5

   Add operating records

   Link hours, inspections and faults by assetId. Track rights transfers separately from physical delivery, with physical verification handled by the operating system.

   Application DB: operating_records.assetId

Before using the code

• Provide an initialized FlexibleToken address and an issuer signer connected to its chain.
• Use a cap of 1,000 and zero decimals for this example. Pass display quantities as strings in units.
• Check MINTER_ROLE, pause state and any eligibility conditions for the recipient.

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.

Allocate units with the equipment ID

Call allocateAsset with assetId, tokenAddress, recipient, units: "10" and issuer. Use its returned values to persist the result in your application API.

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
33

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

export async function allocateAsset(input: {
  assetId: string;
  tokenAddress: string;
  recipient: string;
  units: string;
  issuer: Signer;
}) {
  if (!input.issuer.provider) throw new Error('A connected signer is required.');
  // Requires an initialized token and a signer with MINTER_ROLE.
  const token = FlexibleTokenHelper.attach(input.tokenAddress, input.issuer);
  const amount = parseUnits(input.units, await token.decimals());
  if (amount <= 0n) throw new Error('Units must be positive.');

  const receipt = await token.mint(input.recipient, amount);
  const balance = await token.balanceOf(input.recipient);
  const network = await input.issuer.provider.getNetwork();

  // Persist this mapping in your asset register after confirmation.
  return {
    assetId: input.assetId,
    chainId: network.chainId.toString(),
    tokenAddress: input.tokenAddress,
    holder: input.recipient,
    allocatedAtomic: amount.toString(),
    balanceAtomic: balance.toString(),
    transactionHash: receipt.hash,
    blockNumber: receipt.blockNumber,
  };
}

Implementation considerations

Extending the architecture

Related API and SDK reference