Create Loyalty Program

Create a new loyalty program with custom tiers, rewards, and point configurations. This function initializes a new collection on the blockchain that will manage all loyalty passes for your program.

Overview

The createLoyaltyProgram function creates a new loyalty program as a Metaplex CORE collection. This collection will hold all loyalty passes issued for your program and define the tier structure, rewards, and point allocation rules.

Note: You can either provide a pre-uploaded metadata URI or provide an image buffer and filename to auto-upload the image and generate metadata.

Usage Examples

1. Using a Pre-uploaded Metadata URI

If you already have metadata uploaded to Arweave or another storage service:

import { createLoyaltyProgram } from '@verxioprotocol/core'
import { generateSigner } from '@metaplex-foundation/umi'

const result = await createLoyaltyProgram(context, {
  loyaltyProgramName: 'Coffee Brew Rewards',
  metadataUri: 'https://arweave.net/...', // Already uploaded metadata
  programAuthority: context.programAuthority,
  updateAuthority: generateSigner(context.umi), // Optional: Provide custom update authority
  metadata: {
    organizationName: 'Coffee Brew', // Required: Name of the host/organization
    brandColor: '#FF5733', // Optional: Brand color for UI customization
  },
  tiers: [
    {
      name: 'Bronze',
      xpRequired: 500,
      rewards: ['2% cashback'],
    },
    {
      name: 'Silver',
      xpRequired: 1000,
      rewards: ['5% cashback'],
    },
  ],
  pointsPerAction: {
    purchase: 100,
    review: 50,
  },
})

2. Uploading an Image and Generating Metadata

If you want the protocol to handle image upload and metadata generation:

import { createLoyaltyProgram } from '@verxioprotocol/core'
import { generateSigner } from '@metaplex-foundation/umi'
import fs from 'fs'

const imageBuffer = fs.readFileSync('logo.png')
const result = await createLoyaltyProgram(context, {
  loyaltyProgramName: 'Coffee Brew Rewards',
  imageBuffer, // Buffer of your image
  imageFilename: 'logo.png',
  programAuthority: context.programAuthority,
  updateAuthority: generateSigner(context.umi), // Optional: Provide custom update authority
  metadata: {
    organizationName: 'Coffee Brew', // Required: Name of the host/organization
    brandColor: '#FF5733', // Optional: Brand color for UI customization
  },
  tiers: [
    {
      name: 'Bronze',
      xpRequired: 500,
      rewards: ['2% cashback'],
    },
    {
      name: 'Silver',
      xpRequired: 1000,
      rewards: ['5% cashback'],
    },
  ],
  pointsPerAction: {
    purchase: 100,
    review: 50,
  },
})
// The protocol will upload the image, generate metadata, and use the resulting URI

Parameters

The function accepts a context object and a configuration object with the following parameters:

Parameter	Type	Required	Description
context	VerxioContext	✅	The initialized Verxio context object
loyaltyProgramName	string	✅	Display name for your loyalty program
metadataUri	string	❌	URI pointing to the program's metadata JSON (if not providing imageBuffer)
imageBuffer	Buffer	❌	Buffer of your image file (if not providing metadataUri)
imageFilename	string	❌	Name of your image file (required if providing imageBuffer)
imageContentType	string	❌	MIME type of your image (e.g., "image/png")
programAuthority	Signer	✅	The authority that can manage this program
updateAuthority	Signer	❌	Authority for program updates (optional)
metadata.organizationName	string	✅	Name of your organization
metadata.brandColor	string	❌	Hex color code for UI customization
tiers	Array<Tier>	✅	Array of tier definitions with names, XP requirements, and rewards
pointsPerAction	Record<string, number>	✅	Points awarded for different user actions

Tier Object Structure

Each tier in the tiers array should follow this structure:

Property	Type	Description
name	string	Display name for the tier (e.g., "Bronze", "Silver")
xpRequired	number	Points required to reach this tier
rewards	string[]	Array of reward descriptions for this tier

Return Value

The function returns a Promise that resolves to an object containing:

{
  collection: KeypairSigner,      // The collection signer for the program
  signature: string,              // Transaction signature
  updateAuthority?: KeypairSigner // Update authority (if provided)
}

Property	Type	Description
collection	KeypairSigner	The generated collection keypair that represents your loyalty program
signature	string	The transaction signature confirming the program creation
updateAuthority	KeypairSigner	The update authority for the loyalty program (if provided)

Error Handling

The function will throw errors in the following cases:

Invalid configuration: Missing required parameters or invalid parameter values
Image upload failure: If using imageBuffer and the upload fails
Metadata generation failure: If metadata cannot be generated from the provided data
Transaction failure: If the blockchain transaction fails
Insufficient funds: If the fee payer doesn't have enough SOL for the transaction

Important Notes

• You must provide either metadataUri OR imageBuffer with imageFilename
• The organizationName in metadata is required
• At least one tier must be defined in the tiers array
• The protocol fee for creating a loyalty program is 0.002 SOL

Related Functions

Next Steps

Issue Loyalty Pass- Create loyalty passes for users
Update Loyalty Program- Modify tiers and point values
Award Points- Give points to users for actions

Advanced Usage

Instruction Functions- Use transaction composition
Voucher Management- Create and manage vouchers

Verxio Protocol