Tokenized Loyalty Program

What you will build.

A fictional merchant issues one reward for DEMO-PURCHASE-01. A repeated purchase event must not earn another reward, and an expired or previously redeemed entitlement must not look available. Model those decisions before connecting a point-of-sale system.

Your working record

Create a private worksheet with columns for the source reference, observed state, responsible system, observation time, expected result and unresolved issue. Use the same fictional case throughout the steps; do not paste live personal or financial records into this exercise.

1. 01Define one understandable reward
2. 02Check duplicate earning
3. 03Separate expiry from redemption
4. 04Design a returned-purchase review

Run the example before changing it.

Inspect the baseline record below. Download and read the complete JavaScript file before running it. It uses only Node’s built-in test and assertion modules; there is no package installation, account connection or secret to configure.

{
  "purchaseAlreadyCredited": false,
  "expired": false,
  "redeemed": false
}

Save it as tokenized-loyalty-program.mjs. Open a terminal in that folder and run:

node --version
node --test tokenized-loyalty-program.mjs

Expected result: four passing tests and zero failures. These tests verify the teaching classifier only. They do not verify a production integration, security boundary or financial outcome.

// Hybrid-Chain offline teaching model: tokenized-loyalty-program
// Fictional fields/states; NOT an API client, authorization system or production implementation.
// No network calls, credentials, payments or file writes. Review before running.
// Requires Node.js 22+. Run: node --test tokenized-loyalty-program.mjs
import test from 'node:test';
import assert from 'node:assert/strict';

export function inspect(record) {
  if (record.purchaseAlreadyCredited) return 'ALREADY_CREDITED';
  if (record.expired) return 'EXPIRED';
  if (record.redeemed) return 'ALREADY_REDEEMED';
  return 'READY_FOR_PROGRAM_REVIEW';
}

const baseline = {
  "purchaseAlreadyCredited": false,
  "expired": false,
  "redeemed": false
};
const cases = [
  {
    "name": "reviewable fixture",
    "patch": {},
    "expected": "READY_FOR_PROGRAM_REVIEW"
  },
  {
    "name": "duplicate earning",
    "patch": {
      "purchaseAlreadyCredited": true
    },
    "expected": "ALREADY_CREDITED"
  },
  {
    "name": "expired entitlement",
    "patch": {
      "expired": true
    },
    "expected": "EXPIRED"
  },
  {
    "name": "already consumed",
    "patch": {
      "redeemed": true
    },
    "expected": "ALREADY_REDEEMED"
  }
];

for (const example of cases) {
  test(example.name, () => {
    assert.equal(inspect({...baseline, ...example.patch}), example.expected);
  });
}

Know what the tests demonstrate

reviewable fixture

READY_FOR_PROGRAM_REVIEW

duplicate earning

ALREADY_CREDITED

expired entitlement

EXPIRED

already consumed

ALREADY_REDEEMED

Now change one fixture at a time. If you change a case’s input without changing its expected result, the test should fail. Read the actual-versus-expected difference and use the walkthrough to decide whether your rule or your expectation needs correcting. Keep an unchanged copy for comparison.

Work through the case, step by step.

1. 01

   Define one understandable reward

   Do this

   1. Record the issuer, benefit, eligible purchase and expiry rule in plain language.
   2. Give DEMO-PURCHASE-01 a stable earning reference and keep entitlement identity separate.
   3. Write how a return or transfer affects the reward before designing the UI.

   Expected result

   Support can explain what the reward means independently of its digital representation.

   If your result is different

   If the benefit is undefined, do not use a token balance as a substitute for program terms.

2. 02

   Check duplicate earning

   Do this

   1. Run the baseline with purchaseAlreadyCredited=false.
   2. Set purchaseAlreadyCredited=true and confirm ALREADY_CREDITED.
   3. Specify the unique purchase/program key that the real earning service will enforce atomically.

   Expected result

   Replayed purchase notifications are recognized as the same earning opportunity in the model.

   If your result is different

   This boolean does not implement a durable ledger; test simultaneous workers and event replay in the actual merchant service.

3. 03

   Separate expiry from redemption

   Do this

   1. Restore the baseline, set expired=true and expect EXPIRED.
   2. In a separate case set redeemed=true and expect ALREADY_REDEEMED.
   3. Keep revocation and transfer-policy checks as additional fields in your program worksheet.

   Expected result

   The interface can explain why a reward is unavailable instead of showing every unavailable reward as a zero balance.

   If your result is different

   A token transfer alone does not prove consumption. Identify the merchant's actual redemption record.

4. 04

   Design a returned-purchase review

   Do this

   1. Add a manual row in which a credited purchase is returned after the reward was redeemed.
   2. Assign the adjustment decision to the merchant and record the original purchase and redemption references.
   3. Keep the successful model result READY_FOR_PROGRAM_REVIEW and document the POS integration still needed.

   Expected result

   The design includes an exception path instead of assuming every return can silently reverse a reward.

   If your result is different

   Do not erase the original earning record to make balances appear correct; retain the correction relationship.

Review what you produced.

Save the worksheet, unmodified test output, one deliberately failing case and the explanation of its fix. A useful result includes an unresolved item with an owner; it is not just a screenshot of four green tests.

Map the model to actual systems.

Your program owns eligibility, reward economics, expiration terms, returns, fraud review, and point-of-sale integration. Confirm any required redemption operation rather than assuming a token transfer consumes a reward.

For each worksheet field, name the owning system, exact current operation, permission and error behavior. Put “not available” next to any missing operation and assign a dependency owner. Do not substitute the teaching classifier for that missing integration.

Open the current API reference and inspect each operation’s request, response, scope and implementation status. Code examples on this page are local models only; they do not call those operations.

Before a real deployment, the responsible organization must obtain appropriate legal, compliance and security review. The tutorial does not determine licensing, eligibility, entitlement enforceability or financial suitability.

Take the next technical step.

Use your worksheet and failing-case notes in the next walkthrough. Keep the same reference trail so you can see which assumptions become actual observations—and which remain dependencies.

Need help with access or an unavailable integration? Contact the team with a redacted error and the guide step. Never send credentials or private records.