Optimize README for LLM ingestion and developer experience

Felipe Cevallos · Felipe Cevallos · commit 8f1de43ef6f7 · 2025-10-28T02:22:52.000-06:00
This update enhances the README to be more discoverable and useful for both LLMs and developers by adding:

- Clear project description with value proposition
- Structured "What It Does" and "Who It's For" sections with skill levels
- Comprehensive installation and setup instructions
- 5 copy-pasteable usage examples with CLI commands and Cadence code
- Complete technology stack and dependencies list
- Visual project structure with inline annotations
- Common integration patterns for different user types
- Key concepts glossary
- Security considerations
- Testing instructions with commands
- Enhanced contribution guidelines with development setup
- SEO-optimized keywords for better discoverability
- Support and community resource links

These improvements make the repository more accessible to AI assistants helping developers, while also providing a better onboarding experience for human developers new to the Flow NFT Storefront standard.
diff --git a/README.md b/README.md
@@ -1,61 +1,289 @@
-# NFT Storefront Contract Standard
+# Flow NFT Storefront Contract Standard
 
-The NFT Storefront contract standard is a cornerstone of the Open Marketplace ecosystem on Flow. An open market ecosystem promotes the 
-free flow of NFT listings across the network, emitted as events and consumed by other marketplaces (or any other consumer). Marketplaces may filter 
-listings consumed based on commission rates they may receive. Listings may be created with variable commission, royalties or other fractional revenue, paying to multiple accounts. NFT listings are not NFTs, they are Resources which can be transacted with using the `purchase` [function](https://github.com/onflow/nft-storefront/blob/jp-update-structure/contracts/NFTStorefrontV2.cdc#L300) to obtain the token indicated by the listing. 
+**A production-ready, non-custodial NFT marketplace smart contract standard for the Flow blockchain**
 
-The `NFTStorefrontV2` contract lets you create a non-custodial NFT marketplace to simplify integration with off-chain applications/UIs. The contract supports sellers who want to list and manage NFTs for sale simultaneously across any number of marketplaces. Listing expiry, orphaned and ghost listing cleanup are also of value for integrators to minimize overheads and ensure the best UX. 
+The NFT Storefront contract is the cornerstone of Flow's Open Marketplace ecosystem, enabling peer-to-peer NFT trading with robust security guarantees, automated royalty distribution, and multi-marketplace listing support.
 
-Marketplaces and sellers also benefit from the robust security guarantees of Flow's account model when trading NFTs. Through this standard a NFT trade takes place from peer-to-peer, directly from the Storefront Resource in the sellers account to the purchasers account. At the same time, the standard ensures that marketplaces or other recipients may receive royalties, fees or commissions with no risk to the seller.
+## What It Does
 
-Sellers or marketplaces can optionally configure their NFTStorefront to be limited or closed. However, those wishing to participate in the Open Marketplace ecosystem on Flow are required to use the NFTStorefront standard. 
+NFT Storefront provides a standardized way to:
+- **List NFTs for sale** across multiple marketplaces simultaneously from a single listing
+- **Execute secure peer-to-peer trades** directly from seller to buyer accounts
+- **Automate revenue splits** including royalties, marketplace commissions, and custom sale cuts
+- **Manage listing lifecycle** with expiry, ghost listing cleanup, and duplicate listing handling
+- **Enable marketplace interoperability** through standardized events and APIs
 
-Detailed docs: [docs/documentation.md](docs/documentation.md)
-Flow.com docs: [NFT Storefront Standard](https://developers.flow.com/build/core-contracts/nft-storefront)
+## Who It's For
 
-# Contract Addresses 
+**For Marketplace Developers (Intermediate to Advanced)**
+- Building NFT marketplaces on Flow
+- Integrating existing marketplaces with the Flow ecosystem
+- Implementing custom marketplace logic with commission structures
 
-|Name|Emulator|Testing Framework|Testnet|Previewnet|Mainnet|
-|----|----|------|-------|------|-------|
-|[NFTStorefront](contracts/NFTStorefront.cdc)| N/A | N/A |[0x94b06cfca1d8a476](https://flow-view-source.com/testnet/account/0x94b06cfca1d8a476/contract/NFTStorefront)|[0x6df5e52755433994](contracts/NFTStorefront.cdc)|[0x4eb8a10cb9f87357](https://flowscan.org/contract/A.4eb8a10cb9f87357.NFTStorefront)|
-|[NFTStorefrontV2 (recommended)](contracts/NFTStorefrontV2.cdc)|`0xf8d6e0586b0a20c7`| `0x0000000000000001` |[0x2d55b98eb200daef](https://flow-view-source.com/testnet/account/0x2d55b98eb200daef/contract/NFTStorefrontV2)|[0x6df5e52755433994](contracts/NFTStorefrontV2.cdc)|[0x4eb8a10cb9f87357](https://flowscan.org/contract/A.4eb8a10cb9f87357.NFTStorefrontV2)|
+**For NFT Project Developers (Beginner to Intermediate)**
+- Enabling secondary sales for your NFT collections
+- Implementing creator royalties
+- Setting up peer-to-peer trading for your community
 
-# Usage
+**For dApp Developers (Intermediate)**
+- Adding NFT trading functionality to games or applications
+- Building hybrid custody solutions with NFT trading
 
-If you'd like to test with the `NFTStorefrontV2` Smart contract on the emulator,
-it is automatically deployed to `0xf8d6e0586b0a20c7` or `0x0000000000000001` in the Cadence Testing Framework.
+## Key Features
 
-If you'd like to test with the `NFTStorefrontV2` Smart contract in your project,
-add it to your project by using the flow dependency manager:
+- **Non-custodial**: NFTs remain in seller's account until purchased
+- **Multi-marketplace support**: List once, sell anywhere
+- **Automated royalties**: Built-in support for creator earnings via MetadataViews
+- **Flexible commissions**: Variable marketplace fees with multiple recipients
+- **Listing management**: Expiry dates, ghost listing cleanup, duplicate handling
+- **Event-driven**: Real-time listing discovery through on-chain events
+- **Security-focused**: Leverages Flow's account model for safe trades
 
-```
+## Quick Start
+
+### Installation
+
+Install the contract dependency using Flow CLI:
+
+```bash
 flow dependencies install mainnet://0x4eb8a10cb9f87357.NFTStorefrontV2
 ```
 
-Use the addresses mentioned above for the `emulator` and `testing` import addresses in your project's flow.json.
+### Contract Addresses
+
+| Network | Address | Explorer |
+|---------|---------|----------|
+| **Mainnet** | `0x4eb8a10cb9f87357` | [View](https://flowscan.org/contract/A.4eb8a10cb9f87357.NFTStorefrontV2) |
+| **Testnet** | `0x2d55b98eb200daef` | [View](https://flow-view-source.com/testnet/account/0x2d55b98eb200daef/contract/NFTStorefrontV2) |
+| **Emulator** | `0xf8d6e0586b0a20c7` | - |
+| **Testing Framework** | `0x0000000000000001` | - |
+
+### Basic Usage Examples
+
+#### 1. Setup Storefront (One-time setup)
+
+```bash
+flow transactions send ./transactions/setup_account.cdc
+```
+
+Or using Cadence:
+```cadence
+import NFTStorefrontV2 from 0x4eb8a10cb9f87357
+
+transaction {
+    prepare(acct: auth(Storage, Capabilities) &Account) {
+        if acct.storage.borrow<&NFTStorefrontV2.Storefront>(from: NFTStorefrontV2.StorefrontStoragePath) == nil {
+            let storefront <- NFTStorefrontV2.createStorefront()
+            acct.storage.save(<-storefront, to: NFTStorefrontV2.StorefrontStoragePath)
+
+            let cap = acct.capabilities.storage.issue<&NFTStorefrontV2.Storefront>(NFTStorefrontV2.StorefrontStoragePath)
+            acct.capabilities.publish(cap, at: NFTStorefrontV2.StorefrontPublicPath)
+        }
+    }
+}
+```
+
+#### 2. List an NFT for Sale
+
+```bash
+# Basic listing
+flow transactions send ./transactions/sell_item.cdc \
+  --arg Address:0xNFTReceiverAddress \
+  --arg UInt64:1234 \
+  --arg UFix64:10.0
+
+# With marketplace commission
+flow transactions send ./transactions/sell_item_with_marketplace_cut.cdc \
+  --arg Address:0xMarketplaceAddress \
+  --arg UFix64:0.05
+```
+
+#### 3. Purchase a Listed NFT
+
+```bash
+flow transactions send ./transactions/buy_item.cdc \
+  --arg UInt64:listingResourceID \
+  --arg Address:0xStorefrontAddress
+```
+
+#### 4. Remove a Listing
+
+```bash
+flow transactions send ./transactions/remove_item.cdc \
+  --arg UInt64:listingResourceID
+```
+
+#### 5. Cleanup Ghost Listings
+
+```bash
+flow transactions send ./transactions/cleanup_ghost_listing.cdc \
+  --arg UInt64:listingResourceID
+```
+
+## Technology Stack
+
+- **Language**: Cadence (Flow's smart contract language)
+- **Blockchain**: Flow
+- **Standards**:
+  - NonFungibleToken (NFT standard)
+  - FungibleToken (payment standard)
+  - MetadataViews (royalty standard)
+- **Testing**: Cadence Testing Framework
+- **Dependencies**:
+  - NonFungibleToken
+  - FungibleToken
+  - MetadataViews
+  - ViewResolver
+
+## Project Structure
+
+```
+nft-storefront/
+├── contracts/
+│   ├── NFTStorefrontV2.cdc          # Main contract (recommended)
+│   ├── NFTStorefront.cdc             # Legacy V1 contract
+│   └── utility/                      # Test utilities
+├── transactions/
+│   ├── setup_account.cdc             # Initialize storefront
+│   ├── sell_item.cdc                 # Create basic listing
+│   ├── sell_item_with_marketplace_cut.cdc  # Listing with commission
+│   ├── buy_item.cdc                  # Purchase NFT
+│   ├── remove_item.cdc               # Remove listing
+│   ├── cleanup_ghost_listing.cdc     # Clean ghost listings
+│   └── cleanup_expired_listings.cdc  # Clean expired listings
+├── scripts/
+│   ├── read_storefront_ids.cdc       # Query all listings
+│   ├── read_listing_details.cdc      # Get listing info
+│   └── has_listing_become_ghosted.cdc # Check ghost status
+└── tests/
+    ├── NFTStorefrontV2_test.cdc      # V2 test suite
+    └── NFTStorefrontV1_test.cdc      # V1 test suite
+```
+
+## Documentation & Resources
+
+- **Detailed Documentation**: [docs/documentation.md](docs/documentation.md)
+- **Flow Developer Docs**: [NFT Storefront Standard](https://developers.flow.com/build/core-contracts/nft-storefront)
+- **Contract Source**: [NFTStorefrontV2.cdc](contracts/NFTStorefrontV2.cdc)
+- **GitHub Repository**: [onflow/nft-storefront](https://github.com/onflow/nft-storefront)
+
+## Common Integration Patterns
+
+### For Marketplace Developers
+
+1. **Listen for ListingAvailable events** to discover new listings
+2. **Filter listings by commission requirements** that match your marketplace
+3. **Call purchase()** with your marketplace's commission receiver capability
+4. **Execute cleanupPurchasedListings()** after successful sales
+
+### For NFT Projects
+
+1. **Implement MetadataViews.Royalties** in your NFT contract
+2. **Guide users** to list using provided transactions
+3. **Monitor ListingAvailable events** for your NFT type
+4. **Promote across marketplaces** that support the standard
+
+### For dApp Developers
+
+1. **Create Storefront resource** for users on first sale
+2. **Use sell_item transaction** with your custom parameters
+3. **Handle multiple token types** by creating multiple listings per NFT
+4. **Implement cleanup logic** for better UX
+
+## Running Tests
+
+```bash
+# Run all tests
+flow test tests/NFTStorefrontV2_test.cdc
+
+# Start emulator for manual testing
+flow emulator start
+
+# Deploy contracts to emulator
+flow project deploy --network emulator
+```
+
+## Key Concepts
+
+- **Storefront**: Account-level resource that manages all listings for a seller
+- **Listing**: Individual NFT sale offer with price, cuts, and conditions
+- **SaleCut**: Payment split sent to specific address (royalties, commissions, seller)
+- **Ghost Listing**: Listing without underlying NFT (should be cleaned up)
+- **Commission Receiver**: Marketplace capability that receives commission on sale
+
+## Security Considerations
+
+- NFTs never leave seller account until purchase completes
+- All payment splits execute atomically in single transaction
+- Expired listings automatically prevent purchases
+- Ghost listing detection prevents failed transactions
+- Capability-based access control ensures proper authorization
+
+## Migration from V1 to V2
+
+NFTStorefrontV2 adds:
+- Listing expiry functionality
+- Ghost listing detection and cleanup
+- Improved marketplace commission handling
+- Better duplicate listing management
+- Enhanced event emissions
+
+See migration guide: [V1 to V2 Migration](docs/documentation.md#migration)
+
+## SEO Keywords & Topics
+
+Flow blockchain, NFT marketplace, Cadence smart contracts, non-custodial NFT trading, NFT storefront, Flow NFT standard, marketplace integration, creator royalties, peer-to-peer NFT sales, Flow dApp development, NFT listing management, multi-marketplace NFT, Flow NFT API, blockchain marketplace development, NFT trading platform, Flow ecosystem, secondary NFT sales
+
+## Contributing
+
+We welcome contributions! Please follow these guidelines:
+
+1. **Fork the repository** and create a feature branch
+2. **Write tests** for new functionality
+3. **Follow Cadence best practices** and style guidelines
+4. **Update documentation** for any API changes
+5. **Submit a pull request** with clear description
+
+### Development Setup
+
+```bash
+# Clone repository
+git clone https://github.com/onflow/nft-storefront.git
+cd nft-storefront
+
+# Install Flow CLI (if not installed)
+sh -ci "$(curl -fsSL https://raw.githubusercontent.com/onflow/flow-cli/master/install.sh)"
+
+# Install dependencies
+flow dependencies install
+
+# Run tests
+flow test tests/
+```
+
+## Support & Community
+
+- **Issues**: [GitHub Issues](https://github.com/onflow/nft-storefront/issues)
+- **Discord**: [Flow Discord](https://discord.gg/flow)
+- **Developer Portal**: [Flow Developers](https://developers.flow.com)
 
-Detailed docs for how to manage listings are available on
-[the flow developer docs website](https://developers.flow.com/build/core-contracts/nft-storefront)
+## License
 
-# Brief Overview
+The works in these files are licensed under the [Apache License 2.0](LICENSE).
 
-Each account that wants to offer NFTs for sale installs a `Storefront`,
-and then lists individual sales within that `Storefront` as `Listing` resources.
+## Authors & Maintainers
 
-There is one `Storefront` per account that handles sales of all NFT types
-for that account.
+Maintained by the Flow Foundation and community contributors.
 
-Each `Listing` can list one or more cut percentages.
-Each cut is delivered to a predefined address. 
-Cuts can be used to pay listing fees or other considerations.
+**Core Contributors**:
+- Flow Foundation Team
+- Community developers
 
-Each NFT may be listed in one or more `Listing` resources.
-The validity of each `Listing` can easily be checked.
+## Version History
 
-Purchasers can watch for `Listing` events and check the NFT type and
-ID to see if they wish to buy the offered item.
+- **V2 (Current)**: Enhanced features with expiry, ghost listing management, improved events
+- **V1 (Legacy)**: Original storefront implementation (still supported on mainnet)
 
-Marketplaces and other aggregators can watch for `Listing` events
-and list items of interest.
+---
 
-See further docs and examples on [the developer docs site](https://developers.flow.com/build/core-contracts/nft-storefront).
+*Built on Flow - The blockchain for open worlds*
