FOLIO: A global pay-it-forward chain

.gitignore

@@ -14,4 +14,4 @@ docs/
 .env
 .DS_Store
 
-node_modules/
+node_modules/

.gitmodules

@@ -1,3 +1,7 @@
+[submodule "folio/lib/forge-std"]
+	path = folio/lib/forge-std
+	url = https://github.com/foundry-rs/forge-std
+
 [submodule "nibble/lib/forge-std"]
 	path = OneByTwo/lib/forge-std
 	url = https://github.com/foundry-rs/forge-std

README.md

@@ -21,6 +21,8 @@ Below is a quick summary of each prototype currently available in this repositor
    Pay your rent with a yield-bearing stablecoin.
 1. **`RIFF`**  
    Listen to a bonding curve.
+1. **`Folio`**  
+   Participate in a global pay-it-forward chain.
 1. **`Nibble`**  
    Earn revenue share in your favorite restaurant.
 

folio/.gitignore

@@ -0,0 +1,14 @@
+# Compiler files
+cache/
+out/
+
+# Ignores development broadcast logs
+!/broadcast
+/broadcast/*/31337/
+/broadcast/**/dry-run/
+
+# Docs
+docs/
+
+# Dotenv file
+.env

folio/README.md

@@ -0,0 +1,12 @@
+# Folio
+### Pay it forward, get paid back
+
+### Problem
+Traditional pay-it-forward chains can raise charitable funds, but they are often vulnerable to exploitation. Additionally, they tend to lack excitement, and most efforts remain local rather than global-limiting their overall impact.
+
+### Insight
+By gamifying the pay-it-forward process, we can make chains more engaging and encourage increased donations. People are motivated when they believe they will be a part of something big. By using a blockchain, we can expand the scope to be worldwide, amplifying reach and participation.
+
+
+### Solution
+Create a global pay-it-forward competition on consumer payment rails. The potential to win a portion of the prize pot adds a competitive spark, increasing excitement and contributions. By keeping the chain encrypted, we avoid the case where people exploit the system by only contributing to the winning chain. This way every participant (new or returning) will feel that they have a fair chance to be a winner.

folio/foundry.toml

@@ -0,0 +1,6 @@
+[profile.default]
+src = "src"
+out = "out"
+libs = ["lib"]
+
+# See more config options https://github.com/foundry-rs/foundry/blob/master/crates/config/README.md#all-options

folio/src/ChainTracker.sol

@@ -0,0 +1,168 @@
+// SPDX-License-Identifier: GPL-3.0
+pragma solidity ^0.8.13;
+
+/// @title Pay-it-Forward Chain Management Contract
+/// @notice This contract manages the process of tracking chains and chain details during a pay-it-forward competition.
+contract ChainTracker {
+    /// @notice Sets up the manager
+    address manager;
+
+    constructor() {
+        manager = msg.sender;
+    }
+
+    /// @notice Modifier to ensure only the competition contract can call certain functions
+    modifier competitionOnly() {
+        require(msg.sender == manager, "Only the competition smart contract can call this.");
+        _;
+    }
+
+    /**
+     * @dev Represents a "pay-it-forward" chain.
+     * Tracks participants, their contributions, and overall chain statistics.
+     */
+    struct ChainStats {
+        suint chainId; // Unique identifier for the chain
+        mapping(saddress => suint) links; // Tracks number of contributions for each participant/business
+        suint uniqueBusinesses; // Total distinct businesses involved in the chain
+        suint uniqueParticipants; // Total distinct participants in the chain
+        suint chainLength; // Total number of transactions in the chain
+    }
+
+    /**
+     * @dev Stores competition-wide statistics of terminated (nuked) chains.
+     * Tracks scores, lengths, and the highest-scoring chain.
+     */
+    struct CompStats {
+        mapping(suint => suint) chainFinalScores; // Chain ID => Final score of that chain
+        mapping(suint => suint) chainFinalLengths; // Chain ID => Total length of that chain
+        suint overallWinningChainId; // The ID of the highest-scoring chain
+    }
+
+    /**
+     * @dev Stores per-participant and per-business statistics for chain participation.
+     * Tracks their latest chains, and best chains and their contributions.
+     */
+    struct UserStats {
+        mapping(saddress => suint) latestChain; // Address => Last chain participated in
+        mapping(saddress => suint) bestChain; // Address => Best (longest) chain participated in
+        mapping(saddress => suint) bestChainLinks; // Address => Number of contributions in the best chain
+    }
+
+    ChainStats activeChain; // The currently active chain
+    CompStats comp; // Tracks global competition statistics
+    UserStats user; // Tracks user-specific statistics
+
+    /**
+     * @notice Adds transaction details to the active chain.
+     * Updates participation records for both the participant and the business.
+     * If the participant or business is contributing for the first time, their records are updated accordingly.
+     * @param pAddr The participant's address.
+     * @param bAddr The business's address.
+     */
+    function forgeLink(saddress pAddr, saddress bAddr) public competitionOnly {
+        // If this is the participant's first time contributing to this chain, update records.
+        if (user.latestChain[pAddr] != activeChain.chainId) {
+            updateToCurrentChain(pAddr);
+            activeChain.uniqueParticipants++;
+        }
+        activeChain.links[pAddr]++; // Increment participant’s contribution count
+
+        // If this is the business's first time being added to this chain, update records.
+        if (user.latestChain[bAddr] != activeChain.chainId) {
+            updateToCurrentChain(bAddr);
+            activeChain.uniqueBusinesses++;
+        }
+        activeChain.links[bAddr]++; // Increment business’s contribution count
+        activeChain.chainLength++; // Increment chain length
+    }
+
+    /**
+     * @dev Resets a participant/business’s contribution count and updates their latest chain.
+     * @param addr The address of the participant/business.
+     */
+    function updateToCurrentChain(saddress addr) internal {
+        checkIsChainLongest(addr); // Check if their latest chain was their longest
+        activeChain.links[addr] = suint(0); // Reset contribution count
+        user.latestChain[addr] = activeChain.chainId; // Assign the latest chain
+    }
+
+    /**
+     * @dev Checks if the participant/business’s latest chain had the highest score.
+     * If so, update their best chain records.
+     * This is public due to the need to check the final chain after the competition ends
+     * @param addr The address of the participant/business.
+     */
+    function checkIsChainLongest(saddress addr) public competitionOnly {
+        suint latestScore = comp.chainFinalScores[user.latestChain[addr]];
+        suint bestScore = comp.chainFinalScores[user.bestChain[addr]];
+        if (latestScore > bestScore) {
+            user.bestChain[addr] = user.latestChain[addr]; // Update best chain
+            user.bestChainLinks[addr] = activeChain.links[addr]; // Update best chain's contribution count
+        }
+    }
+
+    /**
+     * @notice Ends the active chain, records its statistics, and resets it to be used as the next chain.
+     * Updates the overall highest-scoring chain if applicable.
+     */
+    function nuke() public competitionOnly {
+        // Record final score and length of the nuked chain
+        comp.chainFinalScores[activeChain.chainId] =
+            calcChainScore(activeChain.uniqueParticipants, activeChain.uniqueBusinesses);
+        comp.chainFinalLengths[activeChain.chainId] = activeChain.chainLength;
+
+        // Update the overall winning chain if this one has a higher score
+        if (comp.chainFinalScores[activeChain.chainId] > comp.chainFinalScores[comp.overallWinningChainId]) {
+            comp.overallWinningChainId = activeChain.chainId;
+        }
+
+        // Reset the active chain for a fresh start
+        activeChain.chainLength = suint(0);
+        activeChain.uniqueParticipants = suint(0);
+        activeChain.uniqueBusinesses = suint(0);
+        activeChain.chainId++;
+    }
+
+    /**
+     * @dev Calculates a chain's final score based on distinct participants and businesses.
+     * @param pScore The number of distinct participants.
+     * @param bScore The number of distinct businesses.
+     * @return The calculated final score.
+     */
+    function calcChainScore(suint pScore, suint bScore) internal pure returns (suint) {
+        // Formula: finalScore = unique businesses * (1 + (unique participants / 10))
+        return bScore * (suint(1) + (pScore / suint(10)));
+    }
+
+    /// @notice Returns the ID of the highest-scoring chain.
+    function getWinningChainId() public view competitionOnly returns (uint256) {
+        return uint256(comp.overallWinningChainId);
+    }
+
+    /// @notice Returns the total length of the highest-scoring chain.
+    function getWinningChainLength() public view competitionOnly returns (uint256) {
+        return uint256(comp.chainFinalLengths[comp.overallWinningChainId]);
+    }
+
+    /// @notice Returns the best (highest-scoring) chain a participant/business has contributed to.
+    /// @param addr The address of the participant/business.
+    function getBestChainId(saddress addr) public view competitionOnly returns (uint256) {
+        return uint256(user.bestChain[addr]);
+    }
+
+    /// @notice Returns the number of times a participant/business contributed to their best chain.
+    /// @param addr The address of the participant/business.
+    function getBestChainCount(saddress addr) public view competitionOnly returns (uint256) {
+        return uint256(user.bestChainLinks[addr]);
+    }
+
+    /**
+     * @dev Resets a participant/business contribution count on the winning chain
+     * Prevents them from claiming rewards multiple times.
+     * @param addr The address of the participant/business.
+     */
+    function walletHasBeenPaid(saddress addr) public competitionOnly {
+        user.bestChainLinks[addr] = suint(0);
+    }
+}