Overview

plop is three components and one chain.

 creator's wallet                       holders' wallets
       │ approve + zasil (fund)                ▲
       ▼                                       │ token.transfer, one per recipient
 ┌─────────────────────┐   kapnij(list)   ┌────┴───────────┐
 │  Kroplomierz        │ ◄────────────────┤  keeper        │  reads the registry every
 │  (dropper)          │                  │  (executor key)│  15 s, snapshots holders,
 │  holds the supply   │  Kropla event    │                │  applies the rules, sends
 │  caps every epoch   ├────────────────► │                │  the batches, keeps a journal
 └─────────┬───────────┘                  └────────────────┘
           │ listed in, rules stored in            ▲
           ▼                                       │ eth_getLogs Transfer(token)
 ┌─────────────────────┐                  ┌────────┴───────┐
 │  Fabryka            │  lista(), wpis() │  web app       │  dashboard, coin page,
 │  (registry)         ├────────────────► │  Next.js + API │  launch flow, JSON API,
 │  never holds tokens │                  │                │  same rules engine as keeper
 └─────────────────────┘                  └────────────────┘

Lifecycle of an airdrop#

1. Create. The creator calls Fabryka.utworz(token, executor, capPerEpoch, minInterval, logo, rules). The registry deploys a new dropper owned by the caller and lists it. In the web app this is the first of three signatures on the Add airdrop screen.
2. Fund. The creator approves the dropper and calls Kroplomierz.zasil(amount). Anyone can fund any dropper; funding is a gift to the holders. The dropper's balance is always token.balanceOf(dropper); there is no internal ledger.
3. Drip. Every minOdstep seconds the executor may open a new epoch by calling kapnij(epoch + 1, recipients, amounts, rulesHash, close). Large lists are split into several batches in the same epoch; all batches count towards the same cap. The dropper emits Kropla for every batch.
4. Repeat until the balance is smaller than one drop. The web app then shows the coin as empty. The creator can top it up at any time (Add supply).
5. Stop or take back. The owner can pause drips (ustawPauze), change the executor, cap and interval (ustaw), or withdraw the remainder (wyplac) at any time. The rules may declare a quiet period after which the creator intends to take the rest back; the contract does not enforce it.

Who qualifies for a drop#

Qualification is computed from a snapshot of the token's holders at a block, using the rules stored in the registry:

• balance at the snapshot block must be at least minSaldo;
• the balance must have stayed at or above that threshold continuously for at least minCzasTrzymania seconds (dipping below resets the clock);
• contracts are skipped when pomijajKontrakty is set (pools, routers, the bonding curve);
• the dropper's owner and executor are skipped when pomijajWlasne is set;
• the dropper itself is always skipped;
• the drop is split proportionally to balance, or equally when porowno is set, with an optional per-wallet cap sufitNaAdres whose overflow is redistributed.

The exact algorithm, including rounding and ordering, is specified in Split rules. The web app and the keeper run the same code (web/lib/regula.ts), so the list shown on the coin page is the list the keeper would send.

Epochs, batches and the cap#

The dropper does not know who should receive tokens; it only limits how much can leave and how often:

• maksNaEpoke is a hard cap on the sum of all batches of one epoch. Splitting a drop into a hundred calls does not raise it.
• minOdstep is the shortest allowed time between two epoch openings. Zero is rejected by the constructor and by ustaw.
• kapnij with epokaId == epoka + 1 opens a new epoch (interval enforced); with epokaId == epoka it continues the current one (no interval check) unless it was closed; anything else reverts.

Worst case, with a hostile executor, at most maksNaEpoke × (floor(86400 / minOdstep) + 1) base units can leave the dropper per day. The creator chooses both numbers; the Add airdrop screen shows the resulting figure before anything is signed.

Time and numbers on this chain#

Facts measured on Robinhood Chain that shape the code and the docs:

• Blocks are about 100 ms apart, produced by a single sequencer, first come first served, no public mempool and therefore no priority-fee auction. The keeper sends plain legacy transactions with gasPrice from the node.
• block.number returns the Ethereum L1 block number, as on every Arbitrum Orbit chain. The contracts use block.timestamp exclusively.
• blockTimestamp in eth_getLogs results can be 0x0. Every timestamp in the API is fetched from the block header instead.
• eth_getLogs is limited: roughly 50 000 to 100 000 blocks per query, at most 10 000 logs per response, and addresses × blocks must stay at or below 200 000. A filter without an address counts as five addresses. Over-use answers 429 without a Retry-After header; the node recovers in about 0.7 s.
• The public RPC is not an archive node. Historical eth_getCode and state reads need an archive endpoint; the web app keeps such an endpoint server-side and never exposes it.

Repository layout#

kontrakty/          Foundry project: Kroplomierz.sol, Fabryka.sol, tests, deploy scripts
web/                Next.js app (App Router), viem, TypeScript
  lib/regula.ts       split engine (pure, shared with the keeper)
  lib/holdery.ts      holder index built from Transfer logs
  lib/fabryka.ts      registry reads and rule conversions
  app/api/**          JSON routes, see HTTP API
  components/dto.ts   JSON shapes of every route
keeper/             executor: fabryka.mjs (all droppers), harmonogram.mjs (one dropper)
docs/               these pages

Glossary#

The contracts, the API and the code use Polish identifiers. This table is the bridge.

Contracts and roles#

Rules#

Data#