All field notes

Architecture · Retrospective

Batching NFT trades into one transaction

A tray of collectible cards passing through a glass gate, a magnifying glass above it.
Concept illustration · AI-generated

On 11 June we introduced Marketplace V3 on the Playermon blog. Its main change was that a player could list several NFTs, or buy several, in a single transaction instead of one at a time. Two weeks later, on 25 June, we added batch sending: moving several NFTs to another wallet in one transaction. Both were running on Polygon's Amoy testnet, open to our internal testers and to players we invited.

From the outside, batching looks like an interface convenience: fewer clicks, fewer confirmations. Underneath, it is an architecture change, because it changes the unit that succeeds or fails. That is where most of my thinking went this month.

What a batch saves

Every transaction on an EVM chain such as Polygon starts with a fixed cost of 21,000 gas before it does any work, and every transaction needs its own signature and its own wait for confirmation. A player selling ten Playermons one by one paid that overhead ten times and signed ten times. A batch pays it once and asks for one signature.

What a batch does not save is the work done for each item. Every transfer still updates the token's owner, and every listing still writes a seller and a price to storage. When our batch-sending post said you pay one fee, the accurate reading is one transaction fee, not a flat fee: it still grows with the number of NFTs inside it. A block also has a gas limit, so a batch has a ceiling. An interface should cap how many items one batch carries rather than let a large batch fail at the limit.

When one item fails

On the EVM, if any step in a transaction reverts, the whole transaction reverts. For a purchase, that default is safe: a buyer never pays for a basket and receives half of it.

A marketplace, though, is full of races. Between the moment a buyer fills a basket and the moment the transaction is mined, another player can buy one of those listings, or the seller can cancel it. With an all-or-nothing batch, one stale listing sinks the whole basket, and the buyer still pays gas for the failed attempt.

The alternative is to skip an item that can no longer be bought and refund its price. That is kinder to the buyer, but the contract then has to account for every refund exactly and record which items went through, and the interface has to show the buyer what they actually received. An atomic batch fails loudly. A skipping batch can fail quietly. Either can be right, as long as the choice is deliberate and players can see which one they are using.

What is still checked for each item

Batching moves many items through one call, but the checks still belong to each item:

  • The seller still owns the NFT, and the marketplace is still approved to move it. An owner can list a Playermon and then transfer it somewhere else.
  • The listing is still active, and its price is the price the buyer saw. Passing the expected price into the call stops a listing being repriced between viewing and buying.
  • The same token does not appear twice in one batch.
  • The payment covers the sum of the prices, and any excess goes back to the buyer.
  • Records are updated before tokens move. A safe transfer to a contract calls back into that contract, and a callback that arrives before the bookkeeping is finished is how reentrancy bugs start.

Batch sending has its own checks. ERC-1155, the standard behind our item NFTs, includes a batch transfer. ERC-721, the standard behind Playermons themselves, does not, so sending several Playermons at once means a contract looping over single transfers on the owner's behalf. To do that, the contract needs the owner's approval for the whole collection. That is broad authority, and a contract holding it should do one thing only: move tokens the caller owns, to the address the caller named, when the caller asks.

Why testnet first

A batch multiplies mistakes as readily as it multiplies savings. An error inside a loop is an error for every item in it. The cases worth breaking on a testnet are not the ordinary ones. They are a basket in which one listing has just sold, a batch containing the same token twice, a batch at the size limit, and a transfer to a contract that cannot receive NFTs.

None of these appear when one person lists one Playermon. They appear when many people trade at the same time, which is what a marketplace is for. Testing with invited players on Amoy is how we could learn what "one transaction" means once more than one person is using it.