# Exploring Swarm Storage Incentives: How Bee Nodes Earn BZZ for Decentralized Storage > Discover Swarm storage incentives and how Bee nodes earn BZZ for decentralized storage. Learn about the economic model driving data reliability and bandwidth provision on Swarm. - Repository: [Ethersphere/awesome-swarm](https://github.com/ethersphere/awesome-swarm) - Tags: deep-dive - Published: 2026-03-01 --- **Swarm storage incentives create a self-balancing economic layer where Bee node operators earn BZZ tokens for reliably storing data and serving bandwidth, while requestors pay for these services through postage stamps and per-request micropayments.** The Swarm network combines peer-to-peer storage with built-in economic mechanisms to ensure data persistence without centralized control. Implemented primarily in the `ethersphere/storage-incentives` repository, these incentives automatepayments between participants through a suite of Ethereum smart contracts that manage postage, accounting, and staking. ## Core Mechanisms of Swarm Storage Incentives The economic model relies on three distinct but interconnected smart contract systems that govern how value flows between data uploaders, storage providers, and bandwidth consumers. ### Postage Stamps: Pre-Paid Storage Guarantees The `PostageStamp.sol` contract implements a pre-payment system that ensures requestors purchase bandwidth before uploading content. When a client initiates an upload, they call `createBatch()` to lock BZZ tokens and generate a unique batch ID. This batch ID attaches to every chunk of data uploaded, signaling to storage nodes that sufficient payment exists to cover storage and retrieval costs. The contract parameters include `depth` (defining the batch size as 2^depth chunks) and `bucketDepth`, which determine the cost and distribution of the postage batch. ### SWAP: Micropayments for Bandwidth The `Swap.sol` contract manages real-time accounting between Bee nodes using a protocol called Swarm Accounting Protocol (SWAP). Instead of executing expensive on-chain transactions for every chunk served, nodes maintain off-chain balances with each peer. When a node forwards a request or serves data, it credits its balance and debits the requestor’s account. The `settleAll()` function periodically aggregates these micro-transactions into a single on-chain settlement, dramatically reducing gas costs while ensuring providers receive payment for bandwidth consumed. ### Staking and Storage Rewards Long-term data persistence is enforced through `Storage.sol`, which requires nodes to stake BZZ tokens as collateral to become storage providers. The contract tracks how much data each staked node holds and calculates rewards proportional to that storage commitment. If a node fails to serve data during a challenge-response audit, the contract executes a slashing penalty, confiscating a portion of the stake and redistributing it to honest providers. This creates a cryptographic guarantee that economic rationality aligns with data availability. ## How Swarm Storage Incentives Work: The Data Flow Understanding the incentive layer requires following a piece of data through its complete lifecycle, from upload to retrieval. 1. **Upload Phase**. A client purchases postage through `PostageStamp.sol` by calling `createBatch()` with the desired depth and BZZ amount. The resulting batch ID is embedded in the upload metadata, allowing Bee nodes to verify payment before accepting chunks for storage. 2. **Distribution Phase**. Data splits into chunks and replicates across multiple Bee nodes. Each storage node registers its commitment with `Storage.sol`, becoming eligible for periodic rewards based on the volume of data it retains. The more data a node stores reliably, the higher its reward share from the staking pool. 3. **Retrieval Phase**. When a consumer requests the data, they provide the original batch ID. Nodes that participate in forwarding or serving the content claim micropayments through their `Swap` balances with the requestor. These payments occur off-chain initially, with the `Swap.sol` contract recording the liability for future settlement. 4. **Settlement and Enforcement Phase**. Periodically, the network triggers on-chain settlement via `settleAll()` to consolidate SWAP debts. Simultaneously, `Storage.sol` distributes staking rewards to compliant nodes. If the challenge-response protocol detects missing data, the contract automatically slashes the offending node’s stake, transferring the penalty to providers who maintained the data correctly. ## Interacting with Storage Incentive Contracts Developers can interact directly with the incentive contracts using standard Ethereum libraries. Below are practical examples for purchasing postage, querying rewards, and settling balances. ### Buying a Postage Stamp (JavaScript/ethers.js) ```js import { ethers } from "ethers"; import PostageStampABI from "./PostageStampABI.json"; const provider = new ethers.providers.JsonRpcProvider("https://bsc-testnet.rpc"); const signer = provider.getSigner(); const postageStamp = new ethers.Contract( "0xPOSTAGE_STAMP_ADDRESS", PostageStampABI, signer ); // Parameters: depth (log2 of batch size), bucketDepth, amount (in BZZ wei) await postageStamp.createBatch( 16, // batch of 2^16 chunks (~16 MiB) 8, // bucket depth ethers.utils.parseEther("10") // 10 BZZ for the batch ); console.log("Postage batch created"); ``` ### Querying Storage Rewards (Python/web3.py) ```python from web3 import Web3 import json w3 = Web3(Web3.HTTPProvider("https://bsc-testnet.rpc")) with open("StorageABI.json") as f: storage_abi = json.load(f) storage = w3.eth.contract(address="0xSTORAGE_CONTRACT_ADDRESS", abi=storage_abi) # Node identifier is the Bee node's Ethereum address node = "0xYOUR_NODE_ADDRESS" reward = storage.functions.rewards(node).call() print(f"Current storage reward: {w3.fromWei(reward, 'ether')} BZZ") ``` ### Settling SWAP Balances (JavaScript/ethers.js) ```js import { ethers } from "ethers"; import SwapABI from "./SwapABI.json"; const swap = new ethers.Contract("0xSWAP_ADDRESS", SwapABI, signer); // Settle all pending off-chain balances in a single on-chain transaction await swap.settleAll(); console.log("Swap balances settled"); ``` ## Key Source Files in storage-incentives The `ethersphere/storage-incentives` repository contains the canonical implementations of the economic protocols. Developers building on Swarm should reference these specific contracts: - **`contracts/PostageStamp.sol`**. Defines the logic for creating, topping up, and expiring postage batches, including the `createBatch()` function and batch lifecycle management. - **`contracts/Swap.sol`**. Implements the SWAP protocol, including off-chain balance tracking, cheque handling, and the `settleAll()` function for batch settlements. - **`contracts/Storage.sol`**. Manages the staking registry, reward distribution algorithms, and the slashing mechanism for data availability challenges. - **`contracts/SwapUtils.sol`**. A utility library containing helper functions for balance calculations, Merkle proofs, and signature verification used by the SWAP system. ## Summary - **Swarm storage incentives** function through three core smart contracts: `PostageStamp.sol` for pre-paid uploads, `Swap.sol` for bandwidth micropayments, and `Storage.sol` for long-term staking rewards. - **Postage stamps** require uploaders to lock BZZ tokens before storing data, ensuring nodes receive guaranteed payment for storage and retrieval services. - **SWAP accounting** minimizes gas costs by settling peer-to-peer balances off-chain before periodic on-chain consolidation via `settleAll()`. - **Staking and slashing** in `Storage.sol` align economic incentives with data availability, rewarding honest storage providers and penalizing node failures through automated stake reduction. ## Frequently Asked Questions ### What are postage stamps in Swarm storage? Postage stamps are cryptographic proofs of payment created through the `PostageStamp.sol` contract that must be attached to uploaded data. They represent pre-locked BZZ tokens that guarantee storage nodes will receive compensation for storing and serving specific chunks, functioning similarly to pre-paid postage on physical mail. ### How do Bee nodes earn BZZ tokens through storage incentives? Bee nodes earn BZZ through two primary channels: **storage rewards** from `Storage.sol` (distributed periodically based on the volume of data staked and reliably stored) and **bandwidth payments** through the SWAP protocol (micropayments from requestors for forwarding and serving chunks). Both mechanisms require nodes to maintain active stakes and honest participation. ### What happens if a storage node loses data in Swarm? If a node fails to provide data during the network's challenge-response audit, the `Storage.sol` contract executes a **slashing** penalty. A portion of the node's staked BZZ is confiscated and redistributed to storage providers who maintained the data correctly, creating a strong economic disincentive for data loss while compensating honest operators. ### Where can developers find the deployed addresses for storage incentive contracts? Official contract addresses for mainnet and testnet deployments are documented in the [`README.md`](https://github.com/ethersphere/awesome-swarm/blob/main/README.md) file of the `ethersphere/storage-incentives` repository. Developers should verify these addresses against the repository's release tags, as the Swarm network periodically upgrades incentive contracts to optimize gas efficiency and security.