Skip to content

Latest commit

 

History

History

foundry

README.md

Issues MIT License LinkedIn


Logo

Loyal: Web3 Customer Engagement that Works

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

Conceptual Overview · Vendor dApp · Customer dApp · Deploy a Loyalty Program

Table of Contents

About

The Loyal protocol provides a modular, composable and gas efficient framework for blockchain based customer engagement programs.

Built With

  • Solidity v0.8.19

  • Foundry v0.2.0

  • OpenZeppelin v5.0.2

  • eth-infinitism's account-abstraction v0.7.0

  • Pimlico

  • It builds on the following ERC standards:

    • [ERC-20 & ERC-721: Fungible and Non-Fungible Token standard]: the Loyalty Program contract mints fungible points; Gift contracts mint non-fungible loyalty Cards.
    • [ERC-4337: Account Abstraction]: Loyalty Cards are abstracted accounts.
    • [EIP-712: Typed structured data hashing and signing]: customer requests are executed through signed messages (transferred in front-end app as Qr codes) to the vendor. It allows the vendor to cover all gas costs.
    • [ERC-165: Standard Interface Detection]: gift contracts are checked if they follow they ILoyaltyGift interface.

For a previous version that builds on ERC-1155 (multi-token standard) and ERC-6551 (token based accounts) see here.

Directory Structure

foundry

│
├── lib                               # Foundry libraries
│   ├── account-abstraction           # eth-infinitism account abstraction library
│   │   └── ...                       
│   ├── forge-std                     # forge contracts library 
│   │   └── ...
│   ├── openzeppelin-contracts        # OpenZeppelin contracts library
│   │   └── ...
│   └── ...
│
├── script                            # Foundry libraries
│   ├── DeployFactoryPrograms.s.sol   # Deploy script of loyalty program factory
│   ├── DeployLoyaltyGifts.s.sol      # Deploy script for example gift contracts
│   ├── HelperConfig.s.sol            # Helper config 
│   └── SendPackedUser.s.sol          # Script to create packed user operations. 
|
├── src                               # Smart contract source code
│   ├── interfaces                    # Contracts interfaces
│   │   ├── ILoyaltyCard.sol          # Loyalty card interface
│   │   ├── ILoyaltyGift.sol          # Loyalty gift interface
│   │   └── ILoyaltyProgram.sol       # Loyalty program interface
│   ├── sample-gifts                  # Example gift contracts
│   │   ├── giftsMetadata             # Metadata for loyalty gifts 
│   │   │     └──...                   
│   │   ├── FreeCoffee.sol            # Example of points for gift exchange
│   │   ├── FreeCupCake.sol           # Example of points for gift exchange
│   │   ├── FridayFifteen.sol         # Example of time constrained exchange
│   │   └── GoldToken.sol             # Example of tiered access 
│   ├── FactoryCards.sol              # Factory contract to create loyalty cards.
│   ├── FactoryPrograms.sol           # Factory contract to create loyalty programs.
│   ├── LoyaltyCard.sol               # Bespoke ERC-4337 loyalty card contract.
│   ├── LoyaltyGift.sol               # ERC-721 base gift contract.
│   ├── LoyaltyProgram.sol            # ERC-20 loyalty program contract.
│   └── ...
│
├── test              # Foundry tests
│   ├── fuzz          # Fuzz tests.
│   │     └── ...
│   ├── invariant     # Invariant tests (tbi).
│   │     └── ...
│   └── unit          # Unit tests.
│         └── ...
│
├── .env.example      # Example .env file 
├── Makefile          # Deployment scripts
├── foundry.toml      # Foundry configuration file
└── README.md         # Foundry project README

Getting Started

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

Prerequisites

Foundry

  • Install following the directions at getfoundry.sh.
  • You'll know you did it right if you can run forge --version and you see a response like forge 0.2.0 (816e00b 2023-03-16T00:05:26.396218Z)

Quickstart

  1. Clone the repo 
    git clone https://github.com/7Cedars/loyalty-program-contracts.git
  2. navigate to the folder 
    cd loyalty-program-contracts
  3. create a .env file and add the following: 
    SELECTED_RPC_URL = <PATH_TO_RPC>

Where <PATH_TO_RPC> is the url to your rpc provider, for example: https://eth-sepolia.g.alchemy.com/v2/... or http://localhost:8545 for a local anvil chain.

Note that tests will not run on a chain that does not have an ERC-6551 registry deployed. Due to compiler conflicts, it is not possible to deterministically deploy the erc6511 registry inside the test suite itself.

  1. run make 
    make

Usage

Test

$ forge test

Test coverage

forge coverage

and for coverage based testing:

forge coverage --report debug

Build

 $ forge build

Deploy

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

Where <RPC_URL> is the url to your rpc provider, for example: https://eth-sepolia.g.alchemy.com/v2/...

Live example

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/.

Known Issues

This contract has not been audited. Do not deploy on anything else than a test chain. More specifically:

  • Testing coverage is still low. Fuzz tests especially are still underdeveloped.
  • The function _validateTarget at LoyaltyCard.sol is likely still insecure.
  • ...

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

Contributing

Contributions and suggestions are more than welcome. 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

License

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

Contact

Seven Cedars - @7__Cedars - [email protected]

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

Acknowledgments

  • This project was build while following PatrickCollins amazing Learn Solidity, Blockchain Development, & Smart Contracts Youtube course.
  • ...