Load Network Bundler
The LN Bundler is the fastest, cheapest and most scalable way to store EVM data onchain
Last updated
The LN Bundler is the fastest, cheapest and most scalable way to store EVM data onchain
Last updated
To upload data to Load Network with the alphanet bundling service, see in the quickstart docs for the and .
Load Network Bundler is a data protocol specification and library that introduces the first bundled EVM transactions format. This protocol draws inspiration from Arweave's specification.
Bundler as data protocol and library is still in PoC (Proof of Concept) phase - not recommended for production usage, testing purposes only.
For the JS/TS version of LN bundles, .
Reduces transaction overhead fees from multiple fees (n
) per n
transaction to a single fee per bundle of envelopes (n
transactions)
Enables third-party services to handle bundle settlement on LN (will be decentralized with LOAD1)
Maximizes the TPS capacity of LN without requiring additional protocol changes or constraints
Supports relational data grouping by combining multiple related transactions into a single bundle
Bundler: Refers to the data protocol specification of the EVM bundled transactions on Load Network.
Envelope: A legacy EVM transaction that serves as the fundamental building block and composition unit of a Bundle.
Bundle: An EIP-1559 transaction that groups multiple envelopes (n > 0
), enabling efficient transaction batching and processing.
Large Bundle: A transaction that carries multiple bundles.
Bundler Lib: Refers to the Bundler Rust library that facilitates composing and propagating Bundler's bundles.
A bundle is a group of envelopes organized through the following process:
Envelopes MUST be grouped in a vector
The bundle is Borsh serialized according to the BundleData
type
The resulting serialization vector is compressed using Brotli compression
The Borsh-Brotli serialized-compressed vector is added as input
(calldata) to an EIP-1559 transaction
The resulting bundle is broadcasted on Load Network with target
set to 0xbabe
addresses based on bundle version.
Bundles versioning is based on the bundles target address:
v0.1.0
0xbabe1
v0.2.0
0xbabe2
An envelope is a signed Legacy EVM transaction with the following MUSTs and restrictions.
Transaction Fields
nonce
: MUST be 0
gas_limit
: MUST be 0
gas_price
: MUST be 0
value
: MUST be 0
Size Restrictions
Total Borsh-Brotli compressed envelopes (Bundle data) MUST be under 9 MB
Total Tags bytes size must be <= 2048 bytes before compression.
Signature Requirements
each envelope MUST have a valid signature
Usage Constraints
MUST be used strictly for data settling on Load Network
MUST only contain envelope's calldata, with optional target
setting (default fallback to ZERO address)
CANNOT be used for:
tLOAD transfers
Contract interactions
Any purpose other than data settling
The selection of transaction types follows clear efficiency principles. Legacy transactions were chosen for envelopes due to their minimal size (144 bytes), making them the most space-efficient option for data storage. EIP-1559 transactions were adopted for bundles as the widely accepted standard for transaction processing.
Envelopes exist as signed Legacy transactions within bundles but operate under distinct processing rules - they are not individually processed by the Load Network as transactions, despite having the structure of a Legacy transaction (signed data with a Transaction type). Instead, they are bundled together and processed as a single onchain transaction (therefore the advantage of Bundler).
Multiple instances of the same envelope within a bundle are permissible and do not invalidate either the bundle or the envelopes themselves. These duplicate instances are treated as copies sharing the same timestamp when found in a single bundle. When appearing across different bundles, they are considered distinct instances with their respective bundle timestamps (valid envelopes and considered as copies of distinct timestamps).
Since envelopes are implemented as signed Legacy transactions, they are strictly reserved for data settling purposes. Their use for any other purpose is explicitly prohibited for the envelope's signer security.
A Super Account is a set of wallets created and stored as keystore wallets locally under your chosen directory. In Bundler terminology, each wallet is called a "chunker". Chunkers optimize the DevX of uploading LB chunks to LN by splitting each chunk to a chunker (~4MB per chunker), moving from a single-wallet single-threaded design in data uploads to a multi-wallet multi-threaded design.
Large Bundles are built on top of the Bundler data specification. In simple terms, a Large Bundle consists of n
smaller chunks (standalone bundles) that are sequentially connected tail-to-head and then at the end the Large Bundle is a reference to all the sequentially related chunks, packing all of the chunks IDs in a single 0xbabe2
bundle and sending it to Load Network.
Determining Number of Chunks
To store a file of size S (in MB) with a chunk size C, the number of chunks (N) is calculated as:
N = ⌊S/C⌋ + [(S mod C) > 0]
Special case: if S < C then N = 1
Maximum Theoretical Size
The bundling actor collects all hash receipts of the chunks, orders them in a list, and uploads this list as a LN L1 transaction. The size components of a Large Bundle are:
2 Brackets [ ] = 2 bytes
EVM transaction header without "0x" prefix = 64 bytes per hash
2 bytes for comma and space (one less comma at the end, so subtract 2 from total)
Size per chunk's hash = 68 bytes
Therefore: Total hashes size = 2 + (N × 68) - 2 = 68N bytes
Maximum Capacity Calculation
Maximum L1 transaction input size (C_tx
) = 4 MB = 4_194_304 bytes
Maximum number of chunks (Σn
) = C_tx
÷ 68 = 4_194_304 ÷ 68 = 61_680 chunks
Maximum theoretical Large Bundle size (C_max
) = Σn
× C_tx
= 61_680 × 4 MB = 246,720 MB ≈ 246.72 GB
500 mgas/s (current)
4MB
4MB
246 GB
1 gigagas/s (upcoming)
8MB
8MB
492 GB
Build an envelope, build a bundle
Example: Build a bundle packed with envelopes
Example: Send tagged envelopes
Example: construct and disperse a Large Bundle single-threaded
Example: construct and disperse a Large Bundle multi-threaded
Example: Retrieve Large Bundle data
from
's envelope property derived from sig)N.B: All of the
/v1
methods (0xbabe1
) are available under/v2
for0xbabe2
Large Bundles.
A Large Bundle is a bundle under version 0xbabe2 that exceeds the Load Network L1 and 0xbabe1
transaction size limits, introducing incredibly high size efficiency to data settling on LN. For example, with running @ 500 mgas/s, a Large Bundle has a max size of 246 GB. For the sake of DevX and simplicity of the current 0xbabe2 stack, Large Bundles in the Bundler SDK have been limited to 2GB, while on the network level, the size is 246GB.
For more examples, check the tests in .
Base endpoint: