Debt & asset finance

Architecture and responsibilities

1. 01

   Agreements and investors

   Manage agreement originals, investor eligibility and payment schedules.

   Application API / DB
2. 02

   Positions and holdings

   Track issuance and holdings for each classId and nonceId pair.

   BondTokenHelper
3. 03

   Payments and claims

   Reconcile bank transfers or connect token-based claim processing as appropriate.

   Bank integration / DebtManagerHelper
4. 04

   Operations and reporting

   Store holdings at the record date and payment outcomes for reporting.

   Snapshots / Application ledger

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

   Map terms to a class and series

   Map FIN-001 to classId 20 and its series to nonceId 202709. Create both identifiers and include only public metadata on chain.

   createClass(classId, data) → createNonce(classId, nonceId, data)
2. 2

   Issue after eligibility and funding checks

   Check identity, agreement and funding in the application. Configure any required allowlist, then issue 10 units. Token issuance does not itself verify a bank deposit.

   issue(investor, classId, nonceId, 10n)
3. 3

   Fix holdings at the record date

   Associate payment entitlement with holdings at the contractual record date, not the current balance at payment time. BondToken snapshots are created when called; they cannot retroactively create a snapshot for an arbitrary date.

   snapshot() → balanceOfAt(holder, classId, nonceId, snapshotId)
4. 4

   Connect the payment path

   For bank transfers, reconcile amounts and receipts in the application ledger. With DebtManager, configure BondToken, principal and coupon tokens, permissions and schedules, then fund the coupon using payCoupon.

   DebtManager: createTranche → addCouponSchedule → payCoupon → claimCoupon
5. 5

   Reconcile redemption and records

   Reconcile principal repayment with retiring units. BondToken redeem burns units; linking that action to a payout requires a payment workflow such as DebtManager.

   BondToken.redeem / DebtManager.redeemAtMaturity

Before using the code

• Provide an initialized BondToken, an existing classId and nonceId, and a signer with MINTER_ROLE.
• Pass position units as bigint. Distinguish these units from ERC-20 amounts with decimals.
• Complete eligibility, agreement and funding checks, including any required allowlisting, before calling.

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 a position in a specific series

Use classId: 20n, nonceId: 202709n and units: 10n. agreementId is your application’s agreement ID, included in the result for ledger persistence.

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 { BondTokenHelper } from '@hazbase/kit';
type Signer = Parameters<typeof BondTokenHelper.deploy>[1];

export async function allocateBond(input: {
  agreementId: string;
  tokenAddress: string;
  classId: bigint;
  nonceId: bigint;
  investor: string;
  units: bigint;
  issuer: Signer;
}) {
  // The class and nonce must already exist; issuer needs MINTER_ROLE.
  if (input.units <= 0n) throw new Error('Units must be positive.');
  const bond = BondTokenHelper.attach(input.tokenAddress, input.issuer);
  const receipt = await bond.issue(
    input.investor, input.classId, input.nonceId, input.units,
  );
  const balance = await bond.balanceOf(
    input.investor, input.classId, input.nonceId,
  );

  return {
    agreementId: input.agreementId,
    classId: input.classId.toString(),
    nonceId: input.nonceId.toString(),
    investor: input.investor,
    issuedUnits: input.units.toString(),
    balance: balance.toString(),
    transactionHash: receipt.hash,
  };
}

Implementation considerations

Extending the architecture

Related API and SDK reference