Enhance Marketplace Mini App with detailed README, refactor contract interfaces, and improve listing lifecycle management. Introduce new event emissions and modularize listing actions for better clarity and functionality. Update deployment scripts for EAS review schema configuration.

Author: escottalexander

README.md

@@ -1,3 +1,92 @@
+# Marketplace Mini App
+
+Farcaster-ready marketplace mini app built on Scaffold-ETH 2. It lets creators publish fixed-price listings payable in ETH or ERC-20, buyers purchase them trustlessly, and both parties leave on-chain EAS reviews. The app ships with a modular contract design, a Next.js frontend wired to SE-2 hooks, and optional indexing via Ponder.
+
+## What’s inside
+- **Frontend**: Next.js (App Router), Wagmi/Viem, RainbowKit, SE-2 components and hooks. Farcaster Mini App integration (Quick Auth, splash handling).
+- **Contracts**: `Marketplace`, `IListingType`, `SimpleListings`, and local `TestERC20` tokens for dev.
+- **Reviews**: EAS review schema registered automatically on local and known networks; config is emitted for frontend and indexer.
+- **Indexer**: Ponder project to index marketplace and review activity.
+
+## Farcaster Mini App integration
+- The mini app calls `sdk.actions.ready()` after the app is mounted to dismiss the splash screen (see `packages/nextjs/components/MiniappProvider.tsx`).
+- Authenticated requests can be made with `sdk.quickAuth.fetch` or by pulling a token via `sdk.quickAuth.getToken` on the client and sending it to your backend. See Farcaster Mini App docs for validation on the server using `@farcaster/quick-auth`.
+
+## Contracts architecture
+
+### Roles and components
+- **Marketplace.sol**: Router/orchestrator that stores pointers to listings and delegates all lifecycle operations to a pluggable listing-type contract implementing `IListingType`.
+- **IListingType.sol**: Lifecycle interface that any listing-type must implement. Phases: create, optional pre-buy, sale, and admin close; each has `before`, `on`, and `after` hooks.
+- **SimpleListings.sol**: A concrete `IListingType` implementation for fixed-price listings payable in ETH or an ERC-20.
+- **TestERC20.sol**: Simple mintable tokens for local development (2 and 6 decimals). Only deployed on `localhost`/`hardhat`.
+
+### Marketplace data model
+- `listingCount`: sequential marketplace-level IDs starting at 1.
+- `listings[id]`: `ListingPointer { creator, listingType, listingId }` where:
+  - `listingType` is the address of the listing-type contract (e.g., `SimpleListings`).
+  - `listingId` is the inner ID returned by the listing-type on creation.
+
+### Lifecycle and how contracts interact
+1) **Create**: `Marketplace.createListing(listingType, data)`
+   - Calls `beforeCreate(data)` on the `listingType`.
+   - Calls `onCreate(msg.sender, data)` which returns `innerId` (must be non-zero).
+   - Stores `ListingPointer` under new marketplace ID and calls `afterCreate`.
+   - Emits `ListingCreated(id, creator, listingType, innerId)`.
+
+2) **Optional pre-buy step**: `Marketplace.preBuyAction(id, data)`
+   - Delegates to `beforePreBuy / onPreBuy / afterPreBuy` on the `listingType` and emits `ListingPreBuy`.
+   - Useful for escrows, auctions, or reservations. `SimpleListings` treats this as a no-op.
+
+3) **Sale**: `Marketplace.buyListing(id, data)`
+   - Calls `beforeSale / onSale / afterSale` on the `listingType`, then emits `ListingSold(id, buyer)`.
+
+4) **Close**: `Marketplace.closeListing(id, data)`
+   - Only the marketplace-level `creator` can close. Delegates to `beforeClose / onClose / afterClose` and emits `ListingClosed`.
+
+### SimpleListings data and behavior
+- Stored as `SimpleListing { creator, paymentToken, price, ipfsHash, active }`.
+- `paymentToken == address(0)`: buyer pays in ETH by sending exactly `price` wei. ETH is forwarded directly to the creator.
+- `paymentToken != address(0)`: buyer pays in ERC-20; must approve `SimpleListings` for `price` before calling `buyListing`. No ETH is accepted in this path.
+- On successful sale, an event `SimpleListingSold(listingId, buyer, price, paymentToken)` is emitted and the listing is set inactive.
+- Only the listing `creator` can close an active listing via the marketplace; closing marks it inactive and emits `SimpleListingClosed`.
+
+### Encoding and views
+- `createListing(listingType, data)` forwards `data` to the listing-type. For `SimpleListings`, `data` must be `abi.encode(address paymentToken, uint256 price, string ipfsHash)`.
+- `getListing(id)` returns `(ListingPointer pointer, bytes data)`, where `data` is `listingType.getListing(pointer.listingId)`.
+- For `SimpleListings.getListing(listingId)`, `data` is `abi.encode(creator, paymentToken, price, ipfsHash, active)`.
+
+### Events
+- Marketplace: `ListingCreated`, `ListingPreBuy`, `ListingSold`, `ListingClosed`.
+- SimpleListings: `SimpleListingCreated`, `SimpleListingSold`, `SimpleListingClosed`.
+
+## EAS Reviews
+- A review schema `uint256 listingId,uint8 rating,string commentIPFSHash` is registered by `packages/hardhat/deploy/05_register_review_schema.ts` on local and known networks.
+- After deployment, config is written to:
+  - Frontend: `packages/nextjs/contracts/easConfig.json`
+  - Indexer: `packages/indexer/src/easConfig.json`
+- Use these addresses/UIDs from your app or indexer to submit and query review attestations.
+
+## Local development
+1. Start a local chain:
+   - `yarn chain`
+2. Deploy contracts (Marketplace, SimpleListings):
+   - `yarn deploy`
+3. (Optional) Deploy local EAS core + register review schema:
+   - `yarn deploy --tags EASLocal,ReviewSchema`
+4. (Optional) Deploy local test tokens:
+   - `yarn deploy --tags TestERC20`
+5. Start the frontend:
+   - `yarn start` → `http://localhost:3000`
+
+Contract artifacts/addresses are available under `packages/hardhat/deployments/<network>/`. The frontend uses SE-2’s generated `deployedContracts.ts` wiring for reads/writes.
+
+## Frontend contract interactions (SE-2 way)
+- Reads: `useScaffoldReadContract({ contractName, functionName, args })`
+- Writes: `useScaffoldWriteContract({ contractName })` → `writeContractAsync({ functionName, args, value? })`
+- Events: `useScaffoldEventHistory({ contractName, eventName, watch? })`
+
+---
+
 # 🏗 Scaffold-ETH 2
 
 <h4 align="center">
@@ -77,4 +166,4 @@ To know more about its features, check out our [website](https://scaffoldeth.io)
 
 We welcome contributions to Scaffold-ETH 2!
 
-Please see [CONTRIBUTING.MD](https://github.com/scaffold-eth/scaffold-eth-2/blob/main/CONTRIBUTING.md) for more information and guidelines for contributing to Scaffold-ETH 2.
+Please see [CONTRIBUTING.MD](https://github.com/scaffold-eth/scaffold-eth-2/blob/main/CONTRIBUTING.md) for more information and guidelines for contributing to Scaffold-ETH 2.

packages/hardhat/contracts/IListingType.sol

@@ -2,26 +2,43 @@
 pragma solidity >=0.8.0 <0.9.0;
 
 interface IListingType {
-    // Creation lifecycle
-    function beforeCreate(bytes calldata data) external returns (bool);
-    function onCreate(address creator, bytes calldata data) external returns (uint256 listingId);
-    function afterCreate(uint256 listingId, bytes calldata data) external returns (bool);
+    struct ListingTypeMetadata {
+        string name;          // e.g. "SimpleListing"
+        string version;       // e.g. "1.0.0"
+        string description;   // optional
+        string abi;           // JSON ABI encoded as a string
+    }
 
-    // Sale lifecycle
-    function beforeSale(uint256 listingId, address buyer, bytes calldata data) external returns (bool);
-    function onSale(uint256 listingId, address buyer, bytes calldata data) external payable returns (bool);
-    function afterSale(uint256 listingId, address buyer, bytes calldata data) external returns (bool);
+    /// @notice Creates a new listing
+    /// @param creator The creator of the listing
+    /// @param listingId The ID of the listing
+    /// @param data The data for the listing
+    /// @dev All listings start at this step
+    function create(address creator, uint256 listingId, bytes calldata data)
+        external
+        returns (bool success);
 
-    // Pre-buy lifecycle (e.g., escrow setup, pre-payment, auction mechanism etc.)
-    function beforePreBuy(uint256 listingId, address buyer, bytes calldata data) external returns (bool);
-    function onPreBuy(uint256 listingId, address buyer, bytes calldata data) external payable returns (bool);
-    function afterPreBuy(uint256 listingId, address buyer, bytes calldata data) external returns (bool);
+    /// @notice Handles an action for a listing
+    /// @param listingId The ID of the listing
+    /// @param creator The creator of the listing
+    /// @param active Whether the listing is active
+    /// @param caller The caller of the action
+    /// @param action The action to handle
+    /// @param data The data for the action
+    /// @dev The caller must be the marketplace contract
+    function handleAction(
+        uint256 listingId,
+        address creator,
+        bool active,
+        address caller,
+        bytes32 action,
+        bytes calldata data
+    ) external payable;
 
-    // Admin lifecycle
-    function beforeClose(uint256 listingId, address caller, bytes calldata data) external returns (bool);
-    function onClose(uint256 listingId, address caller, bytes calldata data) external returns (bool);
-    function afterClose(uint256 listingId, address caller, bytes calldata data) external returns (bool);
-
-    // View helpers
-    function getListing(uint256 listingId) external view returns (bytes memory data);
+    /// @notice Returns the data for a listing
+    /// @dev The data is the encoded data for the listing
+    function getListing(uint256 listingId)
+        external
+        view
+        returns (bytes memory data);
 }

packages/hardhat/contracts/Marketplace.sol

@@ -1,96 +1,69 @@
-//SPDX-License-Identifier: MIT
+// SPDX-License-Identifier: MIT
 pragma solidity >=0.8.0 <0.9.0;
 
 import { IListingType } from "./IListingType.sol";
 
 contract Marketplace {
-    // Custom errors
-    error ListingTypeZeroAddress();
+    error ListingCreationFailed();
+    error OnlyListingTypeCanModify();
     error ListingNotFound();
-    error NotCreator();
-    error BeforeCreateFailed();
-    error InnerIdZero();
-    error AfterCreateFailed();
-    error BeforePreBuyFailed();
-    error OnPreBuyFailed();
-    error AfterPreBuyFailed();
-    error BeforeSaleFailed();
-    error OnSaleFailed();
-    error AfterSaleFailed();
-    error BeforeCloseFailed();
-    error OnCloseFailed();
-    error AfterCloseFailed();
+
     struct ListingPointer {
         address creator;
-        address listingType; // contract implementing IListingType
-        uint256 listingId; // ID inside the listing type contract
+        address listingType;
+        bytes32 contenthash;
+        bool active;
     }
 
     uint256 public listingCount;
     mapping(uint256 => ListingPointer) public listings;
 
-    event ListingCreated(uint256 indexed id, address indexed creator, address indexed listingType, uint256 listingId);
-    event ListingSold(uint256 indexed id, address indexed buyer);
-    event ListingClosed(uint256 indexed id, address indexed caller);
-    event ListingPreBuy(uint256 indexed id, address indexed buyer);
-
-    modifier onlyListing(uint256 id) {
-        if (listings[id].listingType == address(0)) revert ListingNotFound();
-        _;
-    }
-
-    function createListing(address listingType, bytes calldata data) external returns (uint256 id) {
-        if (listingType == address(0)) revert ListingTypeZeroAddress();
-
-        // lifecycle: beforeCreate -> onCreate -> afterCreate
-        if (!IListingType(listingType).beforeCreate(data)) revert BeforeCreateFailed();
-        uint256 innerId = IListingType(listingType).onCreate(msg.sender, data);
-        if (innerId == 0) revert InnerIdZero();
+    event ListingCreated(uint256 indexed id, address indexed creator, address indexed listingType, uint256 listingId, bytes32 contenthash);
+    event ListingAction(uint256 indexed id, address indexed caller, bytes32 action);
+    event ListingActivationChanged(uint256 indexed listingId, bool active);
 
+    function createListing(
+        address listingType,
+        bytes32 contenthash,
+        bytes calldata data
+    ) external returns (uint256 id) {
         id = ++listingCount;
-        listings[id] = ListingPointer({ creator: msg.sender, listingType: listingType, listingId: innerId });
-
-        if (!IListingType(listingType).afterCreate(innerId, data)) revert AfterCreateFailed();
-        emit ListingCreated(id, msg.sender, listingType, innerId);
+        bool success = IListingType(listingType).create(msg.sender, id, data);
+        if (!success) revert ListingCreationFailed();
+        listings[id] = ListingPointer(msg.sender, listingType, contenthash, true);
+        emit ListingCreated(id, msg.sender, listingType, id, contenthash);
     }
 
-    function preBuyAction(uint256 id, bytes calldata data) external payable onlyListing(id) {
+    function callAction(
+        uint256 id,
+        bytes32 action,
+        bytes calldata data
+    ) external payable {
+        if (id > listingCount) revert ListingNotFound();
         ListingPointer memory ptr = listings[id];
-
-        if (!IListingType(ptr.listingType).beforePreBuy(ptr.listingId, msg.sender, data)) revert BeforePreBuyFailed();
-        if (!IListingType(ptr.listingType).onPreBuy{ value: msg.value }(ptr.listingId, msg.sender, data))
-            revert OnPreBuyFailed();
-        if (!IListingType(ptr.listingType).afterPreBuy(ptr.listingId, msg.sender, data)) revert AfterPreBuyFailed();
-
-        emit ListingPreBuy(id, msg.sender);
+        IListingType(ptr.listingType).handleAction{value: msg.value}(id, ptr.creator, ptr.active, msg.sender, action, data);
+        emit ListingAction(id, msg.sender, action);
     }
 
-    function buyListing(uint256 id, bytes calldata data) external payable onlyListing(id) {
-        ListingPointer memory ptr = listings[id];
-
-        // lifecycle: beforeSale -> onSale -> afterSale
-        if (!IListingType(ptr.listingType).beforeSale(ptr.listingId, msg.sender, data)) revert BeforeSaleFailed();
-        if (!IListingType(ptr.listingType).onSale{ value: msg.value }(ptr.listingId, msg.sender, data))
-            revert OnSaleFailed();
-        if (!IListingType(ptr.listingType).afterSale(ptr.listingId, msg.sender, data)) revert AfterSaleFailed();
-
-        emit ListingSold(id, msg.sender);
+    function setActive(uint256 listingId, bool active) external {
+        ListingPointer storage record = listings[listingId];
+        if (msg.sender != record.listingType) revert OnlyListingTypeCanModify();
+        record.active = active;
+        emit ListingActivationChanged(listingId, active);
     }
 
-    function closeListing(uint256 id, bytes calldata data) external onlyListing(id) {
+    function getListing(uint256 id) external view returns (
+        address creator,
+        address listingType,
+        bytes32 contenthash,
+        bool active,
+        bytes memory listingData
+    ) {
         ListingPointer memory ptr = listings[id];
-        if (ptr.creator != msg.sender) revert NotCreator();
-
-        if (!IListingType(ptr.listingType).beforeClose(ptr.listingId, msg.sender, data)) revert BeforeCloseFailed();
-        if (!IListingType(ptr.listingType).onClose(ptr.listingId, msg.sender, data)) revert OnCloseFailed();
-        if (!IListingType(ptr.listingType).afterClose(ptr.listingId, msg.sender, data)) revert AfterCloseFailed();
-        emit ListingClosed(id, msg.sender);
-    }
-
-    function getListing(
-        uint256 id
-    ) external view onlyListing(id) returns (ListingPointer memory pointer, bytes memory data) {
-        pointer = listings[id];
-        data = IListingType(pointer.listingType).getListing(pointer.listingId);
+        creator = ptr.creator;
+        listingType = ptr.listingType;
+        contenthash = ptr.contenthash;
+        active = ptr.active;
+        listingData = IListingType(ptr.listingType).getListing(id);
     }
 }