7cedars/loyalty-program-contracts

Loyal: A Solidity Protocol for Web3 Customer Engagement Programs

A composable, lightweight and fully open source solidity protocol build for real-world customer engagment.
Explore the docs »

View Demo of a dApp interacting with the protocol. · Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Roadmap
5. Contributing
6. License
7. Contact
8. Acknowledgments

About The Project

A fully open source solidity protocol for real-world customer engagment.

This protocol sets out a standard for loyalty programs: ERC-1155 based contracts that mint (fungible) points and (non-fungible) loyalty cards. Loyalty Cards are implemented as ERC-6551 Token Based Accounts that accumulate loyalty points. See this repository for an example implementation.

Loyalty programs interact with a second protocol that sets out a standard for contracts - loyalty gift contracts - that exchange points for gifts or vouchers. For this protocol, see this repository for example implementations.

Crucially, interactions between the two protocols are bounded: points and vouchers that are minted by a loyalty program can only be used among its own loyalty cards. Loyalty cards themselves are freely transferable.

See the following schema for more detail:

(back to top)

Built With

• Solidity 0.8.19
• Foundry 0.2.0
• OpenZeppelin 5.0

(back to top)

Getting Started

To get a local copy up and running do the following.

Prerequisites

Install Foundry

$ curl -L https://foundry.paradigm.xyz | bash

$ foundryup

Check if the chain has an ERC-6551 registry at address 0x000000006551c19487814612e58FE06813775758. If not (and if the contract is deployed on a local chain), set up a registry following the steps at tokenbound.org.

Clone the repository

1. Get a free alchemy API Key at alchemy.com
2. Clone the repo

 git clone https://github.com/7Cedars/loyalty-program-contracts.git

3. Install packages

 yarn add

Run the test and build the contracts

4. Run tests

$ forge test

5. Build contracts

 $ forge build

Deploy

6. Run deploy script at an EVM compatible Chain

 $ forge script --fork-url <RPC_URL> script/DeployLoyaltyProgram.s.sol --broadcast

(back to top)

Usage

A front-end dApp demonstration of this web3 protocol has been deployed on vercel.com. Try it out at https://loyalty-program-psi.vercel.app/.

(back to top)

Roadmap

• Further develop testing. Basic unit, integration and invariant tests have been implemented, but fuzz tests not yet. Test coverage is only around 50 percent.
• Implement deployment to multiple testnets.
• ...

See the open issues for a full list of proposed features (and known issues).

(back to top)

Contributing

Contributions make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Thank you!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

License

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

(back to top)

Contact

Seven Cedars - @7__Cedars - [email protected]

GitHub profile https://github.com/7Cedars

(back to top)

Acknowledgments

• This project was build while following PatrickCollins amazing Learn Solidity, Blockchain Development, & Smart Contracts Youtube course. Comes highly recommended for anyone wanting to get into Foundry & intermediate/advanced solidity coding.
• An introduction to ERC-6551 by Pinata's Kelly Kim was really useful.
• As was the documentation from Tokenbound (an organisation advocating the implementation of Tokan Based Accounts).
• I took the template for the readme file from Drew Othneil.
• And a special thanks should go out to SpeedRunEthereum and LearnWeb3 for providing the first introductions to solidity coding.

(back to top)