Issue Loyalty Pass

Create and distribute loyalty passes as NFTs to users. Each pass represents a user's membership in your loyalty program and tracks their points, tier status, and activity history.

Overview

The issueLoyaltyPass function creates a new NFT loyalty pass for a specific user within your loyalty program. The pass serves as the user's digital membership card and stores all their loyalty data on-chain.

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 pass metadata uploaded to Arweave or another storage service:

import { issueLoyaltyPass } from '@verxioprotocol/core'
import { generateSigner, publicKey } from '@metaplex-foundation/umi'

const result = await issueLoyaltyPass(context, {
  collectionAddress: context.collectionAddress,
  recipient: publicKey('RECIPIENT_ADDRESS'),
  passName: 'Coffee Rewards Pass',
  passMetadataUri: 'https://arweave.net/...', // Already uploaded metadata
  assetSigner: generateSigner(context.umi), // Optional: Provide a signer for the pass
  updateAuthority: programAuthority, // Required: Program authority of the Loyalty Program
  organizationName: 'Coffee Brew',
})

2. Uploading an Image and Generating Metadata

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

import { issueLoyaltyPass } from '@verxioprotocol/core'
import { generateSigner, publicKey } from '@metaplex-foundation/umi'
import fs from 'fs'

const imageBuffer = fs.readFileSync('pass.png')
const result = await issueLoyaltyPass(context, {
  collectionAddress: context.collectionAddress,
  recipient: publicKey('RECIPIENT_ADDRESS'),
  passName: 'Coffee Rewards Pass',
  imageBuffer, // Buffer of your image
  imageFilename: 'pass.png',
  updateAuthority: programAuthority, // Required: Program authority of the Loyalty Program
  organizationName: 'Coffee Brew',
})
// 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
collectionAddress	PublicKey	✅	The collection address of your loyalty program
recipient	PublicKey	✅	Wallet address of the user receiving the pass
passName	string	✅	Display name for the loyalty pass NFT
passMetadataUri	string	❌	URI pointing to the pass's metadata JSON (if not providing imageBuffer)
imageBuffer	Buffer	❌	Buffer of your image file (if not providing passMetadataUri)
imageFilename	string	❌	Name of your image file (required if providing imageBuffer)
imageContentType	string	❌	MIME type of your image (e.g., "image/png")
assetSigner	Signer	❌	Custom signer for the pass (auto-generated if not provided)
updateAuthority	Signer	✅	Program authority required for issuing passes
organizationName	string	✅	Name of the organization (required for metadata generation)

Return Value

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

{
  asset: KeypairSigner,    // The generated pass NFT signer
  signature: string        // Transaction signature
}

Property	Type	Description
asset	KeypairSigner	The generated loyalty pass NFT keypair
signature	string	The transaction signature confirming pass creation

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
Invalid authority: If the updateAuthority is not the program authority

Important Notes

• You must provide either passMetadataUri OR imageBuffer with imageFilename
• The organizationName is required for metadata generation
• The updateAuthority must be the program authority from the loyalty program creation
• The protocol fee for issuing a loyalty pass is 0.001 SOL

Verxio Protocol