Skip to content

mxjxn/such-lssvm

BranchesTags
 
 

Repository files navigation

LSSVM Development Suite

📖 Documentation Site: View the complete documentation at https://mxjxn.github.io/such-lssvm/ - A comprehensive, human-readable guide to all aspects of the LSSVM development suite.

Note: This repository is a Turborepo monorepo containing a comprehensive suite of tools and applications built around the LSSVM (Liquidity-Sensitive Single-Variant Market) protocol. It includes the protocol contracts from sudoswap, reorganized and extended with a Farcaster miniapp, Graph Protocol subgraph, deployment scripts, and developer tooling by mxjxn.

Attribution

From sudoswap

  • packages/lssvm-contracts/ - All Solidity contracts, and tests for the LSSVM (sudoAMM v2) protocol
  • Protocol architecture, features, and core functionality
  • Original documentation and protocol design

From mxjxn

  • apps/miniapp/ - Farcaster miniapp for interacting with NFT liquidity pools
  • apps/indexer/ - Graph Protocol subgraph for indexing pool events and swaps
  • apps/docs/ - Documentation website for GitHub Pages
  • Deployment scripts
  • Monorepo structure and Turborepo configuration
  • Integration tooling and developer experience improvements

sudoAMM v2 is focused on delivering several specific feature upgrades missing from sudoAMM v1.

Read the longform overview here.

Monorepo Structure

This repository is organized as a Turborepo monorepo with the following structure:

  • apps/miniapp - Farcaster miniapp for interacting with NFT liquidity pools (by mxjxn)
  • apps/indexer - Graph Protocol subgraph for indexing pool creation and swap events (by mxjxn)
  • apps/docs - Documentation website deployed to GitHub Pages (by mxjxn)
  • packages/lssvm-contracts - Solidity contracts for the LSSVM protocol (from sudoswap)
  • packages/lssvm-abis - Shared ABIs, addresses, and types package for cross-repo integration

Getting Started

  1. Install dependencies:
pnpm install
  1. Build all packages:
pnpm build
  1. Run development servers:
pnpm dev

Architecture

sudoAMM v2 diagram

Diagram by Gerard Pearson, prepared during the Spearbit security audit.

Protocol Features (sudoswap)

The main focuses of the LSSVM protocol are:

  • On-chain royalty support for all collections by default
  • Property-checking for pools to allow for specifying desired trait / ID orders
  • An opt-in on-chain structure for LPs and project owners that allows for revenue sharing
  • ERC1155 support
  • Separate fee accounting, unified router, improved events, and minor gas optimizations

On-chain Royalty Support

If your collection is already ERC2981 compliant, then you're good to go. All buys and sells executed on sudoAMM v2 will send the appropriate royalty amount to your specified recipient address(es). If your collection isn't ERC2981 compliant, but your collection has an owner() or similar admin role, you can use the Manifold Royalty Registry to deploy a 2981 compliant royalty lookup.

If your collection uses a different royalty interface, the following interfaces are also supported via RoyaltyEngine.sol, a non-upgradeable version of the Manifold Royalty Engine:

  • Rarible v1
  • Rarible v2
  • Foundation
  • SuperRare
  • Zora
  • ArtBlocks
  • KnownOrigin v2

Property Checking

Pools can set another contract to do on-chain verification of desired properties (e.g. ID set inclusion) to purchase only certain items in a collection.

The protocol provides a generic IPropertyChecker interface, and it is agnostic about whether this is done through a bitmap, merkle tree, or any other on-chain property.

Settings

For projects that want to work more closely with pool creators, sudoAMM v2 introduces a project-controlled Setting.

A Setting is contract that enforces specific requirements for pools that opt into them. For example, a Setting might ask that assets stay locked in the pool for 90 days, collect an upfront fee, as well as a 50/50 split of trading fees. In return for adhering to a Setting, projects can configure a separate royalty amount for these pools to encourage more trading.

Settings are an opt-in feature that are always configured by a collection's owner.

The sudoAMM v2 repo includes a configurable Setting template ready to use out of the box, with choices for direct payment, lock duration, and fee split. Project owners are free to create their own Setting for more bespoke conditions if they so choose.

ERC1155 Support

Pools can now also be made for ERC1155<>ETH or ERC1155<>ERC20 pairs. Pools for ERC1155 assets will specify a specific ID in the ERC1155 collection that they buy or sell. Both ERC1155 and ERC721 pool types now inherit from the base LSSVMPair class.

Misc

  • TRADE pools can now set a separate feeRecipient to receive swap fees on each swap. Pools can also continue to keep fee balances internally if desired.
  • Improved events for tracking NFTs swapped in or out
  • A new VeryFastRouter which allows for handling all swap types (i.e. ERC721<>ETH, ERC721<>ERC20, ERC1155<>ETH, ERC1155<>ERC20), as well as an efficient method for handling partial fills when buying/selling multiple items from the same pool.

Miniapp (mxjxn)

This repository includes a Farcaster miniapp (apps/miniapp/) built by mxjxn that provides a user-friendly interface for interacting with NFT liquidity pools built on the LSSVM protocol.

Features

  • Pool Discovery: Enter pool addresses to view detailed pool information including spot price, delta, fees, and available NFTs
  • Buy NFTs: Purchase NFTs from liquidity pools using ETH or ERC20 tokens with real-time price quotes
  • Sell NFTs: Sell your NFTs to liquidity pools in exchange for tokens
  • Shopping Cart: Add multiple NFTs to a cart and checkout in a single transaction
  • ERC721 & ERC1155 Support: Full support for both NFT standards
  • Transaction Tracking: Monitor transaction status with explorer links
  • Real-time Quotes: Get up-to-date pricing information before trading, including fees and royalties

Tech Stack

  • Next.js 14 with App Router
  • Wagmi for Ethereum interactions
  • Farcaster Miniapp SDK for Farcaster integration
  • Tailwind CSS for styling
  • React Query for data fetching

Quick Start

  1. Install dependencies (from root):
pnpm install
  1. Configure environment variables (see apps/miniapp/ENV_VARS.md for details):
# Create apps/miniapp/.env.local with your contract addresses

# Base Mainnet (chain ID 8453)
NEXT_PUBLIC_ROUTER_ADDRESS_8453=0x4352c72114C4b9c4e1F8C96347F2165EECaDeb5C
NEXT_PUBLIC_FACTORY_ADDRESS_8453=0xF6B4bDF778db19DD5928248DE4C18Ce22E8a5f5e

# Base Sepolia Testnet (chain ID 84532) - Optional
NEXT_PUBLIC_ROUTER_ADDRESS_84532=0x6C9e6BAc4255901EaD3447C07917967E9dBc32d3
NEXT_PUBLIC_FACTORY_ADDRESS_84532=0x372990Fd91CF61967325dD5270f50c4192bfb892

# RPC Configuration
NEXT_PUBLIC_BASE_RPC_URL=https://base-mainnet.g.alchemy.com/v2/YOUR_API_KEY
  1. Run the development server:
# From root
pnpm dev

# Or from the miniapp directory
cd apps/miniapp
pnpm dev

For detailed setup instructions, deployment guide, and architecture information, see the Miniapp README.

Graph Protocol Subgraph (mxjxn)

This repository includes a Graph Protocol subgraph (apps/indexer/) that indexes all pool creation events, swaps, deposits, and withdrawals on Base Mainnet and Base Sepolia testnet.

Features

  • Pool Indexing: Automatically indexes all pools created via the LSSVMPairFactory
  • Dynamic Data Sources: Automatically creates data sources for newly created pools
  • Swap Tracking: Tracks all NFT buy/sell transactions with pricing and fee information
  • Deposit/Withdrawal Tracking: Monitors liquidity changes in pools
  • State Tracking: Maintains current balances and spot prices for all pools
  • ERC721 & ERC1155 Support: Full support for both NFT standards

Quick Start

  1. Install dependencies (from root):
pnpm install
  1. Navigate to the indexer directory:
cd apps/indexer
  1. Generate TypeScript types:
npm run codegen
  1. Build the subgraph:
npm run build
  1. Deploy to The Graph Studio:
npm run deploy

Subgraph Endpoints

Once deployed, the subgraph provides a GraphQL API endpoint for querying pool data:

  • Base Mainnet: (Set via environment variable NEXT_PUBLIC_SUBGRAPH_ENDPOINT_8453)
  • Base Sepolia: (Set via environment variable NEXT_PUBLIC_SUBGRAPH_ENDPOINT_84532)

Usage in Miniapp

The miniapp uses the subgraph for:

  • Pool Discovery: Finding all pools for a given NFT contract
  • Aggregated NFT Views: Displaying NFTs from all pools, sorted by price
  • Historical Data: Querying swap history and pool state changes

For detailed setup instructions, schema documentation, and query examples, see the Subgraph README.

Building/Testing Contracts (sudoswap)

The Solidity contracts are located in packages/lssvm-contracts/.

cd packages/lssvm-contracts
forge install
forge test

To generate coverage report locally:

cd packages/lssvm-contracts
forge coverage --report lcov && genhtml lcov.info -o report --branch
open report/index.html

Documentation

Protocol Documentation

Deployment Documentation

Deployment Scripts (mxjxn)

⚠️ Warning: Always test deployments on a testnet before deploying to mainnet. Verify all contract addresses and parameters before broadcasting transactions.

This repository includes comprehensive deployment scripts for deploying the entire sudoAMM v2 protocol. The scripts are located in packages/lssvm-contracts/script/ and include:

  • Individual deployment scripts for each component (Core, Bonding Curves, Router, Property Checkers, Settings)
  • Network-specific scripts for Base Mainnet and Base Sepolia testnet
  • Master deployment script (DeployAll.s.sol) for deploying everything at once
  • Test NFT deployment scripts for testing pools
  • Comprehensive documentation including README, deployment checklist, and order reference
  • Local testing support with Anvil integration and helper scripts

Quick Reference

Local Development:

cd packages/lssvm-contracts
anvil  # In one terminal
./deploy-local.sh  # In another terminal

Base Sepolia Testnet:

cd packages/lssvm-contracts
./deploy-base-testnet.sh
./deploy-test-nfts.sh  # Deploy test NFTs for testing

Base Mainnet:

cd packages/lssvm-contracts
./deploy-base.sh

Local Testing

Before deploying to testnet or mainnet, it's highly recommended to test deployments locally using Anvil (Foundry's local Ethereum node).

Quick Start for Local Testing:

  1. Start Anvil in one terminal:

    anvil

  2. Deploy to local node:

    cd packages/lssvm-contracts
./deploy-local.sh

  3. Deploy test NFTs (optional):

    ./deploy-test-nfts.sh

  4. Follow the Local Testing Guide for:

    • Factory configuration (automatic and manual)
    • Creating and testing ERC721 pools
    • Creating and testing ERC1155 pools
    • Useful cast commands for querying contracts
    • Troubleshooting common issues

The deployment script automatically configures the factory (whitelists bonding curves and router) when the deployer is the factory owner.

Deployment to Testnet/Mainnet

Base Sepolia Testnet:

See DEPLOY_BASE_TESTNET.md for detailed instructions.

cd packages/lssvm-contracts
./deploy-base-testnet.sh

Base Mainnet:

See DEPLOY_BASE.md for detailed instructions.

cd packages/lssvm-contracts
./deploy-base.sh

Generic Deployment:

For deploying to other networks, see the Deployment Guide.

cd packages/lssvm-contracts

# Configure your environment
cp script/.env.example .env.local
# Edit .env.local with your values

# Deploy all contracts
forge script script/DeployAll.s.sol:DeployAll --rpc-url $RPC_URL --broadcast --verify

Deployment Features

  • Automatic factory configuration: Scripts automatically whitelist bonding curves and router when deployer is factory owner
  • Mnemonic support: Derive private keys from mnemonics for easier key management
  • Chain ID validation: Scripts verify you're deploying to the correct network
  • Comprehensive error handling: Detailed logging and fallback checks
  • Helper scripts: Convenient bash scripts for common deployment scenarios
  • Test NFT contracts: Pre-configured test NFTs for testing pools

For more details on deployment improvements and best practices, see DEPLOYMENT_IMPROVEMENTS.md.

Deployments

Ethereum Mainnet (sudoswap)

The contracts have been deployed on Ethereum Mainnet to the following addresses:

Factory & Router

Price Curves

Other

Base Mainnet (mxjxn)

The contracts have been deployed on Base Mainnet. See the Base Deployment Summary for complete details.

Factory & Router

Core Contracts

Bonding Curves (Base Mainnet)

Note: All bonding curves are whitelisted and configured correctly on Base Mainnet.

For complete deployment details, configuration, and next steps, see the Base Deployment Summary.

Base Sepolia Testnet (mxjxn)

The contracts have been deployed on Base Sepolia testnet for testing. See the Base Testnet Deployment Summary for complete details.

Factory & Router

Core Contracts

Bonding Curves (Base Sepolia Testnet)

Note: This is a testnet deployment. All bonding curves were deployed fresh on Base Sepolia. All curves are whitelisted in the factory.

Test NFT Contracts (Base Sepolia Testnet)

For complete deployment details, configuration, and next steps, see the Base Testnet Deployment Summary. For test NFT usage, see TEST_NFTS.md.

Cross-Repo Integration

The @lssvm/abis package (packages/lssvm-abis/) is designed to be used across repositories. It exports all LSSVM ABIs, contract addresses, and TypeScript types for use in other projects.

Package Location: packages/lssvm-abis/

Usage in Other Repos:

{
  "dependencies": {
    "@lssvm/abis": "workspace:git+https://github.com/mxjxn/such-lssvm.git#main:packages/lssvm-abis"
  }
}

The package is currently integrated with the cryptoart-monorepo to enable LSSVM pool creation in the cryptoart-studio app. See TASKLIST.md for integration details and cryptoart-monorepo/LSSVM_INTEGRATION.md for usage examples.

About

No description, website, or topics provided.

Resources

Readme

License

AGPL-3.0 license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages

  • Solidity 58.6%
  • TypeScript 38.1%
  • Shell 2.4%
  • Other 0.9%