Loyal: Web3 Customer Engagement that Works

A composable solidity protocol and lightweight dApp for real-world customer engagement.

Solidity protocol · Vendor dApp · Customer dApp · Deploy a Loyalty Program

Table of Contents

1. About
   • The problem
   • Solutions
   • Concepts
   • How it works
   • Important files and folders
   • Built With
2. License
3. Contact

About

The Loyal protocol provides a modular framework for blockchain based customer engagement programs.

• It uses a bespoke implementation of ERC-4337 Account Abstraction to abstract away any blockchain interaction from customers, while greatly simplifying setting up a paying account for vendors.
• It uses an ERC-20 token as loyalty points, allowing loyalty programs to access a global pool of loyalty gift contracts. Meanwhile, it retains exclusivity by linking points and gift vouchers to their parent loyalty program.

IMPORTANT: Do not use this project in any kind of production setting. The project is meant as a Proof of Concept for a new kind of blockchain based customer engagement programs. The code is in active development and has not been audited. It has only been deployed on a testnet - for good reason.

The problem

The use of blockchains for points based customer programs has been explored extensively. Blockchains potentially allow

• Dynamic customer experiences that are truly global.
• Transparency and interoperability between engagement programs.
• A more intimate customer experience with ownership of vouchers and points transferred from the vendor to the customer.

They have not yet been widely used though.

1. Blockchain interactions used to be too expensive for these uses cases.
2. Interaction with blockchains through web3 wallets is too cumbersome for most customers.
3. Tokens on blockchains can be used from one program to another. This goes against exclusivity of customer loyalty programs.

Solutions

1. The cost of blockchain interactions on most L2 chains has dropped dramatically, making this use case viable.

2. Loyal uses a bespoke implementation of ERC-4337 Account Abstraction.

   • Every Loyalty Card is a bespoke account abstraction that can only interact with its parent Loyalty Program.
   • The parent Loyalty Program pays for all interactions of its Loyalty Cards.
   • The Loyal protocol avoids setting up a complex paymaster-account workflow, while still retaining necessary protocol security.

3. The Loyal protocol strikes a balance between interoperability and exclusivity in loyalty programs.

   • Loyal allows anyone to act as a vendor, deploying a loyalty program, minting loyalty points and cards, and distributing points to loyalty cards.
   • Loyal allows anyone to deploy gifts that exchange loyalty points for gift vouchers.
   • Loyal disallows the use of loyalty points and vouchers in any other loyalty program than the one in which they were minted.

In short, gift contracts can be used across programs to exchange points; but points and gifts themselves are exclusive to programs.

Concepts

• Program: A contract that creates loyalty cards, distributes (ERC-20) loyalty points, white lists (ERC-721) loyalty gift and mints their gift vouchers.
• Gift: A contract that receives loyalty points and exchanges them for an gift voucher. Gift contracts are interoperable, but their vouchers are program exclusive.
• Card: An account abstraction that can only interact with the Loyalty Program that created it. All its transactions are funded by the Loyalty program.

How it works

Loyalty Programs (ERC-20)

• Are given a practically endless amount of loyalty points at construction.
• Can whitelist loyalty gifts.
• Automatically creates new loyalty cards every time a new account calls requestPoints.
• Can disallow the creation of new loyalty cards.

Loyalty Gifts (ERC-721)

• Allow Loyalty Programs to mint gift vouchers.
• Have a requirementsExchangeMet function that checks if a loyalty card meets requirements for exchange of points to a gift voucher. The requirement logic can be anything: number pf points, time of day, randomisation, anything goes.
• Have a requirementsRedeemMet function that checks if a loyalty card meets requirements for exchange of a gift voucher to a gift. Again, any logic goes.

Loyalty Cards (ERC-4337)

• Are bespoke Account Abstractions that are only allowed to interact with their parent loyalty program.
• They can also only interact with white listed gift contracts.
• They can collect points, exchange points for gift vouchers and exchange vouchers for actual gifts at the vendor.
• All interactions are paid for by the parent loyalty contract.

A simplified flowchart

Legacy projects

This project emerged from a previous loyalty program, build on the ERC-6551 token based account standard. See the following repositories:

• Solidity Protocol
• Solidity Gift Contracts
• Front end UI/UX

Important files and folders

.
|
├── foundry               # Contains all the contracts, interfaces and tests. 
│    ├── README.md        # All information needed to run contracts locally, test and deploy contracts.   
│    └── ...                     
| 
├── nextjs                # App workspace
|     ├── customer-app    # Project documentation for customer-app
|     │    ├── README.md   
|     │    └── ...   
│     └── vendor-app 
|          ├── README.md  # Project documentation for vendor-app 
│          └── ...   
│
├── public                # Images
│    └── ...   
|
├── LICENSE
└── README.md             # Project documentation.

(back to top)

Built With

• Solidity 0.8.26
• Foundry 0.2.0
• OpenZeppelin 5.0.2
• Eth-infinitism account-abstraction v0.7.0
• React 18
• NextJS 14
• Wagmi / viem
• Pimlico permisionless.js
• Reown appkit v1.1.7 (previously walletConnect)
• Privy.io
• Tailwind css

(back to top)

License

Distributed under the MIT License. See LICENSE.txt for more information.

(back to top)

Contact

Seven Cedars - Github profile - cedars7@proton.me

(back to top)