Skip to content

Optimize README for LLM ingestion and developer experience #112

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
0xLisanAlGaib wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Optimize README for LLM ingestion and developer experience #112

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8f1de43
Optimize README for LLM ingestion and developer experience
Oct 28, 2025
71c9826
fix: removed license related text
0xLisanAlGaib Oct 28, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
300 changes: 262 additions & 38 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,61 +1,285 @@
# 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/
```

Detailed docs for how to manage listings are available on
[the flow developer docs website](https://developers.flow.com/build/core-contracts/nft-storefront)
## Support & Community

# Brief Overview
- **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)

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*
Loading