Guide: The Native Loyalty Engine

The NHBCoin Loyalty Engine is a native economic engine for customer retention, built directly into the L1 protocol. Unlike traditional, closed-loop points systems, it creates an open and interoperable market for loyalty, powered by the <code>ZapNHB</code> token. This guide covers the two ways you can leverage this system.

Model A: Protocol Rewards (Automatic & Free)

This is the baseline loyalty layer that you and your users benefit from automatically. The L1 protocol itself acts as a universal rewards program.

How It Works

The StateProcessor, the brain of the L1, has a simple, hardcoded rule: for every successful EVM transaction (like a payment or smart contract call), both the sender and the receiver are automatically credited with **1 ZapNHB**. Their BalanceZNHB is updated in the same atomic operation as the payment itself.

The Benefit To You

You get this for free. By simply building your application on NHBCoin, every transaction your users make feels rewarding. This increases engagement and retention at zero cost and zero implementation effort for you.

Model B: Building Your Branded Loyalty Program

This is where the real power lies. Any business can build their own sophisticated, custom loyalty program on top of our native protocol, using <code>ZapNHB</code> as the underlying reward asset. Let's imagine an e-commerce store, 'Peeksly.com'.

Step 1: The Concept

Peeksly decides to create 'Peeksly Points'. They define their own business logic: 'Reward 5 Peeksly Points for every 10 NHB spent'. Critically, 'Peeksly Points' are not a new token; they are just a branded name for ZapNHB in their UI. 1 Peeksly Point = 1 ZapNHB.

Step 2: Funding Your Treasury

To give out rewards, Peeksly needs a pool of <code>ZapNHB</code>. They can easily acquire it by using the 'Swap' feature in the NHBCoin wallet to convert <code>NHBCoin</code> into <code>ZapNHB</code>. This funds their secure, on-chain treasury wallet.

Step 3: The Backend Reward Logic

Peeksly's backend server listens for confirmed payments. When a customer pays for an order, the server calculates the reward and sends it to the customer from the treasury wallet.

// Example: Node.js/Express backend webhook for Peeksly.com
import { ethers } from 'ethers';

// This is your business's secure, private treasury key. Load from env variables.
const PEEKSLY_TREASURY_KEY = process.env.PEEKSLY_TREASURY_KEY; 
const provider = new ethers.providers.JsonRpcProvider('YOUR_NHBCOIN_RPC_ENDPOINT');
const treasuryWallet = new ethers.Wallet(PEEKSLY_TREASURY_KEY, provider);

// Your webhook is triggered after a payment is confirmed
app.post('/webhook/payment-confirmed', async (req, res) => {
  const { customerAddress, paymentAmountNHB } = req.body;

  // Peeksly's rule: 5 points (ZapNHB) per 10 NHB spent
  const rewardAmount = Math.floor(paymentAmountNHB / 10) * 5;

  if (rewardAmount > 0) {
    // This is a standard EVM transfer of the ZAPNHB token
    // We would need the ZapNHB contract address to do this
    // For our native token, we would construct a native transaction instead.
    
    // PSEUDO-CODE for native ZNHB transfer:
    const tx = {
      type: 'NATIVE_ZNHB_TRANSFER', // A hypothetical native tx type
      to: customerAddress,
      value: rewardAmount,
      nonce: await treasuryWallet.getTransactionCount(),
    };
    const signedTx = await treasuryWallet.signTransaction(tx);
    // broadcast signedTx to the network...
    console.log(`Rewarded ${customerAddress} with ${rewardAmount} Peeksly Points!`);
  }
  
  res.sendStatus(200);
});

Step 4: Applying Rewards at Checkout (Redemption)

This completes the loop. A returning customer can use their accumulated 'Peeksly Points' (ZapNHB) to get a discount on their next purchase. Your checkout UI can fetch the user's <code>ZapNHB</code> balance and its current USD market value from an oracle, allowing them to apply it to their cart total.

// Example: Svelte component for Peeksly's checkout
<script>
  import { onMount } from 'svelte';
  import { getZNHBPrice } from '$lib/oracle'; // Our price oracle
  
  export let userZapBalance; // e.g., 500
  let zapPriceUSD = 0.10; // Default price
  
  $: zapBalanceUSD = userZapBalance * zapPriceUSD;

  onMount(async () => {
    // Get the live market price of ZapNHB
    const priceData = await getZNHBPrice();
    zapPriceUSD = priceData.usd;
  });

  function applyDiscount() {
    // Logic to apply the discount and create a ZapNHB transfer
    // from the user to the merchant's wallet.
  }
</script>

<div class="checkout-discount">
  <p>You have {userZapBalance} Peeksly Points!</p>
  {#if zapBalanceUSD > 0}
    <button on:click={applyDiscount}>
      Apply ${zapBalanceUSD.toFixed(2)} discount
    </button>
  {/if}
</div>