Documentation · draft v0.1

Build on the Liquid NFT Protocol

LNFT is the protocol for collectibles that always have an exit. A card you open carries a floor the protocol itself guarantees — sell it back to the vault any time, or trade it on the open market. This is the reference for developers and AI agents who want to read the system, integrate it, or launch a brand of their own on top.

Guaranteed floor Provably fair (Storm beacon) 1% buy-and-burn RAIN Arbitrum One

Overview

A Liquid NFT is a collectible with a price floor the protocol underwrites. You open a pack, you get a card, and at any moment the protocol will buy that card back from you at a published, provably-fair price — no marketplace wait, no guessing what it is "worth."

The protocol is a small set of smart contracts plus a settlement layer. Anyone can launch a collection. Each collection is backed by its own vault that underwrites the floor. Liquidity providers fund the vault and earn the spread; creators earn a share of every opening; and the protocol takes a thin 1% fee that buys and burns RAIN, so every collection — in any token — makes RAIN scarcer.

It is not an NFT marketplace and it is not a loot box. It is an allocation-and-liquidity primitive: value goes into a contract, the contract redistributes it along a transparent curve, and the contract guarantees the exit.

LNFT is the protocol. Rain Drops is a brand built on it. Rain Drops (raindrops.one) is the first consumer product that runs on LNFT — the reference brand. Many more can exist: each picks its own packs, its own look, its own token, and sits on the same shared protocol, vault logic, fairness and marketplace.

Why it exists

Two models tried to make digital collectibles valuable and both left a gap:

NFTs

Ownership, but no liquidity. You bought a JPEG and prayed someone would buy it later. Rarity was a marketing claim, not a verifiable fact. Most holders are stuck.

Loot boxes / gacha

The thrill of opening, but no transparency and no exit. Odds were hidden, and whatever you "won" was locked inside one company's walled garden.

A Liquid NFT keeps the good parts of both — the art, the rarity, the thrill of the open — and fixes the two things that killed them:

  1. Provable fairness. Every allocation is anchored to on-chain randomness (the Storm beacon) and a published distribution curve. Anyone can verify that the odds they got are the odds that were advertised. You don't trust us; you check.
  2. Guaranteed liquidity. Every item has a standing buy-back offer from the vault. The floor is not a hope — it is underwritten capital. You can always exit.

Glossary

TermMeaning
LNFTThe Liquid NFT Protocol — the contracts, settlement and marketplace described here.
Collection / packA published set of cards with a fixed curve and odds, backed by one vault. "Pack" is the brand-facing word; "collection" the protocol word.
OpeningOne purchase-and-reveal: a user pays the price, the beacon decides the card, the vault reserves its floor.
VaultThe per-collection pool that holds backing, pays buy-backs and enforces risk limits. Cannot be drained by the operator.
Floor / offerThe standing price the vault will pay to buy a card back. Reserved at the moment of opening.
Assigned valueA card's published value from the curve — not a market price. Label it "Assigned value", never a quote.
LPLiquidity provider: funds the vault, earns the spread, underwrites the floor.
Buy-and-burnThe 1% protocol fee, converted to RAIN and burned on every opening.
Storm beaconThe randomness beacon that decides each opening; openings carry a BLS-verifiable proof against it.
Modeplay = free demo credits; the real-money mode is usd (older rows: cash/rain). Every money row says its currency.

The primitive

Strip it to its core and the protocol is three parts.

1 · Vault

Holds the value backing a collection, pays out buy-backs, and cannot be drained by the operator. One vault per collection, so a jackpot in one collection can never touch another. The vault denominates in a chosen token — a stablecoin (USDT/USDC) or RAIN. A creator who wants a stablecoin collection simply spins up a stablecoin-denominated vault.

2 · Allocation engine

Maps each opening to a rank on a published curve (floor value, rare tiers, top card) and draws the outcome from the Storm beacon. The curve and the odds are public and fixed at the collection's version hash. Allocation runs off-chain, proven on-chain (hybrid): the heavy computation is cheap and fast off-chain, and the result carries a Merkle proof anyone can verify against the pinned beacon value.

3 · Liquidity book

Defines the standing buy-back offer for every item and guarantees it is always funded. LPs deposit into the vault and become the underwriters of the floor: they earn the spread on every opening and carry the risk of a large win. A real DeFi position — yield in exchange for underwriting.

When those three live as contracts, you have a protocol. A website becomes a convenient interface over the protocol, not "the operator." That is what makes a brand like Rain Drops swappable and a marketplace trustworthy.

Life of a card

# one opening, start to exit
pay price P (in the vault's token)
   │
   ├─ 1%        → FeeRouter → (swap to RAIN if needed) → BURN
   ├─ spread → credited to LP shares (yield)
   ├─ creator share → claimable by the collection's creator
   └─ card floor F → RESERVED in the vault as a liability

reveal: the Storm beacon decides the card; a proof is attached

exit, any time — the holder picks one:
   sell back   → vault pays F from the reserve        (always funded)
   mint as NFT → card becomes a real ERC-721 on Arbitrum
   list / sell → trade on the open marketplace at any price
   hold        → free, forever

Because F is reserved at the moment of opening, the buy-back is always funded. That is the whole liquidity guarantee, expressed as one accounting invariant: reserved ≤ tvl.

Economics & fees

Every opening moves value between four parties, transparently:

PartyGets
OpenerA card with a guaranteed floor and the chance of a rare or top card. Can hold, sell back instantly, mint to a real NFT, or list on the market.
CreatorA share of net margin — accrued per open, settled on a rolling weekly cycle once each cycle's floor risk clears. Default 50% of net margin.
Liquidity providerThe spread as yield, in exchange for underwriting the floor.
Protocol1% of each opening, used to buy RAIN on the market and burn it.

What we tax, and what we leave free

  • 1% on the open → buy-and-burn RAIN. Predictable, scales with volume, hides inside the spread. This is the engine.
  • Exit (sell-back) is free. Instant exit is the sacred promise. Taxing the exit breaks the one thing that makes a collectible liquid. We never do it.
  • Holding is free. The behaviour we want to encourage; never penalised.
  • Marketplace trades pay a small market fee (launch value 1%), set per market contract — separate from the protocol burn fee.

Creator payouts: fast, but not reckless

A creator's 50% share accrues the instant a pack is opened — not once a month. It settles on a rolling weekly cycle, so a creator is paid within days, not at a distant month-end. The short wait exists for one business reason: a newly opened card still carries a live floor liability (the opener can sell it straight back to the vault). Paying the creator before that risk clears could pay out margin the vault then has to refund. So each cycle keeps a rolling floor reserve — the portion of margin still exposed to open buy-backs — and releases it as those positions close. The creator gets fast, predictable weekly settlement; the vault never pays out margin it hasn't truly earned.

PropertyValueWhy
AccrualPer open, real-timeCreator sees earnings immediately.
Settlement cycleWeekly (rolling 7-day)Fast cash-flow without month-end lag.
Rolling reserveMargin still under floor riskProtects the vault from refunding paid margin.

Key economic constants are served live at GET /api/config under economics (basis points): buybackBps, playerReturnBps, creatorShareBps, protocolFeeBps, maxPrizeBps, issuePrizeBps, plus creatorSettlementDays (default 7). Always read them from the API rather than hard-coding.

Buy-and-burn

The buy-and-burn is the keystone. Because the fee is always converted to RAIN regardless of the vault's token, even a stablecoin-denominated collection makes RAIN scarcer. RAIN becomes the value-capture token of the entire economy — demand for it grows with total protocol volume, not with any single collection or brand.

How it runs

  • The 1% fee accrues in the ledger as it is earned.
  • When a small threshold accrues (configurable, e.g. $1), a batch runs: the fee buys RAIN on Uniswap v3 (Arbitrum) with an exact approval and a bounded price impact, then burns it through the FeeRouter to the dead address.
  • Every burn emits an on-chain event and is reported publicly at GET /api/stats (totalBurnedRain, accruedFeeRain, lastBurn).
  • Burns run in small, slippage-bounded batches because the RAIN pool is thin; a single large conversion would move price.

Upward price impact on success is a goal — the burn exists to make RAIN scarcer — but each individual swap is still slippage-bounded so a batch can never be sandwiched into a bad fill.

Provable fairness

Fairness is mathematical, not trusted. Every opening is bound to a public randomness beacon and a published odds table, and anyone can recompute the result in a browser.

The commit → anchor → reveal flow

  1. Commit. The browser makes a random 32-byte client seed, keeps it, and sends only its hash. The server records a commitment that binds the pack version hash, the client-seed hash, the current Storm height and a target height k blocks ahead.
  2. Anchor. The commitment is written to the Storm chain (an on-chain Merkle anchor). An explorer link is available.
  3. Reveal. At the target height the beacon output is read; combined with the commitment it yields a single roll into the odds table, which selects the card. The beacon carries a BLS signature verifiable against the pinned group key.

Everything needed to recompute is returned by GET /api/verify/:openingId: the pack table and its hash, the commitment, the anchor transaction and Merkle proof, the beacon output and signature, and the claimed result. The verification steps (all from the shared fairness module) are listed in the Verify flow.

Risk invariants

A permissionless launcher needs guardrails baked in, or the first thin vault with a giant prize gets wiped and takes an LP with it. These are enforced invariants, not UX settings.

InvariantRule
Top-prize capprizeValue ≤ tvl × maxPrizeBps / 10000 (launch 30%). A thin vault literally cannot settle an opening whose top card it can't cover.
Issue headroomPack versions and previews are fitted to issuePrizeBps (25%) of the vault; the purchase guard stays at 30%.
Full reservationEvery open card's floor is reserved; reserved ≤ tvl holds after every state change. The vault can never owe more than it holds.
Rate limitsPer-withdrawal and per-day caps bound how fast value can leave the vault.
NFT'd cards leave the bookOnce minted to a real NFT, a card is no longer floor-backed; its reservation is released. This prevents double-counting a liability the holder opted out of.

If an opening would violate the solvency or prize-cap rule it does not open — the API answers 409 prize_cap_exceeded and nothing is charged until the vault is topped up.

The marketplace

Beyond the vault floor, cards can be minted to real NFTs and traded on an open secondary marketplace — the OpenSea-style layer of the protocol. The difference from a plain NFT market: every card still has the vault floor underneath it, so a listing is a bet above a guaranteed price, never above zero.

What a brand or integrator gets for free

  • Browse layer — collections, items, activity, listings, owners and search, all public and cacheable: GET /api/collections, /api/market/listings, /api/market/tokens/:tokenId, /api/market/owners/:address, /api/market/activity, /api/search.
  • On-chain trading — list, cancel, buy against the market contract; the backend indexes events and serves them after confirmations.
  • Floor-aware pricing — every token card carries its collection, its assigned value and its live listing, so a UI can always show "floor vs. ask."

Market config is at GET /api/market/config (contract address, fee bps, pay tokens, min price). Events and listings are stored in the unit of the contract that emitted them, so a card pulled in the RAIN epoch keeps RAIN history while new trades settle in dollars.

Contracts & stages

The protocol ships in stages; each stage is a complete product and each adds trust. On-chain money and NFTs live on Arbitrum One (chain 42161); randomness comes from the Storm beacon.

StageWhat goes on-chain
0 · todayApp with on-chain proof of fairness. Live.
1 · vaultCollectionVault holds, backs and pays out. First proof the operator can't rob it.
2 · burnFeeRouter auto-converts the 1% fee to RAIN and burns. Proves the RAIN flywheel.
3 · allocationThe curve reads the Storm beacon in-contract. Fairness is enforced, not just proven.
4 · creatorsCollectionFactory opens to anyone: launch a collection, pick the token, fund the vault, earn automatically.

The core contracts are CollectionVault (one per collection, minimal-proxy clone), FeeRouter (singleton burn router), CollectionFactory (permissioned in beta) and a ProofVerifier that checks a Merkle leaf against the pinned beacon. The vault exposes no arbitrary-recipient transfer of principal: the worst a compromised operator key can do is pay valid floors to real holders.

Brands on the protocol

Rain Drops is a brand that stands on this protocol — the first of many. A brand is an interface and a set of collections; the protocol underneath is shared.

Three ways to build:

  1. Your own storefront, our packs. Point a site at the same API and surface existing public collections. You get the catalogue, the fairness and the marketplace with almost no backend.
  2. Your own collections. Launch packs under your brand (your art, your curve, your token), funded by your vault, and earn the creator share on every opening.
  3. Full brand. Your look, your collections, your community packs and your marketplace presence — everything a consumer product needs — on the shared protocol, vault logic and burn.

Whatever you build, the three things that cannot be faked come from the protocol: provable randomness, on-chain anchoring, and a guaranteed floor. Your brand owns the experience; the protocol owns the trust.

Quickstart

The API is REST: JSON in, JSON out, times are ISO-8601 UTC. Base URL is your API origin + /api. Start by reading config, then list collections.

# 1. read live protocol config (currency, economics, fairness, market)
curl -s https://<api>/api/config | jq .

# 2. list public collections (newest first)
curl -s "https://<api>/api/collections?sort=volume&limit=24" | jq '.collections[].slug'

# 3. one collection, with items, odds bands and jackpots
curl -s https://<api>/api/collections/<slug> | jq .

# 4. protocol stats: burned RAIN, accrued fee, vault TVL
curl -s https://<api>/api/stats | jq .

Amounts are integers. Every money field ends in Cents and is in hundredths of the row's currency — US cents when currency is "USD", hundredths of a RAIN when "RAIN". Never add across currencies; RAIN-epoch totals come back in a separate rainEpoch object.

REST API

The most-used endpoints are below. The full reference (every field, every error) lives in docs/API.md in the repository. Auth is a bearer token (Authorization: Bearer <token>) or the httpOnly cookie set by register/login; errors are non-2xx with { error, message, details? }.

Public — read

GET/api/config

Currency, economics (bps), fairness, pay tokens, price tiers, burn, market flag. Read this first; don't hard-code constants.

GET/api/stats

Protocol numbers: total burned RAIN, accrued fee, vault TVL, last burn. Chain reads cached 30s.

GET/api/packs · /api/packs/:slug

Collections and one collection in full: price, curve style, bands, jackpots, items (value, odds, tier, offer).

GET/api/collections · /api/market/listings · /api/market/tokens/:tokenId

Marketplace browse layer: collection cards, active listings, a single token with its history. Cacheable, no auth.

GET/api/verify/:openingId

Everything needed to recompute an opening's result in the browser (see Verify flow).

Auth & wallet

POST/api/auth/register · /api/auth/login

Email + password (+ 18+ ageConfirmed on register). Returns { token, user }.

POST/api/auth/wallet/nonce → /api/auth/wallet/login

Get a nonce, personal_sign the exact EIP-4361 message, send the signature. Plain wallets (EOA) only. A linked wallet is required for deposits, withdrawals and minting.

Play / real-money

POST/api/packs/:slug/open

Body { clientSeedHash, mode }. mode default play; real money is usd (needs deposits enabled). Returns the commitment.

GET/api/openings/:id

Poll until status is revealed. Returns the card, the offer, the anchor and the beacon proof.

POST/api/openings/:id/accept-offer · /api/openings/:id/mint

"Sell now" to the vault floor, or "Keep as NFT" (mints an ERC-721; poll until nft.status is minted).

GET/api/wallet/deposit-info · POST /api/me/withdraw

Deposit: the linked wallet transfers a pay token to the vault (1 cent = 10,000 units at 6 decimals); the backend sees it by itself. Withdraw to the linked wallet.

Launch a collection (creator)

POST/api/community/packs

Create a draft: name, description, a price tier, a curve style (steady/balanced/bold). Then add images, set order and cover, and publish.

GET/api/community/curve

Preview a curve for a price and style without a draft: tiers, odds, jackpots, prize cap. Use it to design before you commit.

Opening flow

// 1. browser makes a 32-byte client seed, keeps it, sends the hash
seed = randomBytes(32)
body = { clientSeedHash: hashClientSeed(seed), mode: "usd" }
POST /api/packs/:slug/open  → { openingId, status: "committed", commit }

// 2. poll until revealed (~700ms)
GET /api/openings/:openingId
   committed → anchored → revealed   (or cancelled → refunded in full)

// 3. on reveal you get the card, the floor offer and the proof
{ item, valueCents, offer: { amountCents, expiresAt }, proof, anchor }

// 4. the holder exits however they like
POST /api/openings/:openingId/accept-offer   // sell to vault floor
POST /api/openings/:openingId/mint           // keep as a real NFT

There is never a server-chosen result in Storm mode. A cancelled opening (anchor missed its deadline, or the beacon was unavailable past the timeout) is refunded in full.

Verify flow

GET /api/verify/:openingId returns every input. Recompute entirely client-side, all from the shared fairness module:

  1. hashPackTable(table) === inputs.packVersionHash — the odds table is the one that was published.
  2. commitmentHash(commit) === commit.commitmentHash — the commitment binds your seed hash and the target height.
  3. Fetch the anchor tx by hash from anchor.rpcUrl, then verifyAnchor(...) — the commitment was written on-chain before the beacon was known.
  4. Fetch beacon.url, then verifyBeaconProof(...) and check output === inputs.beacon — the randomness is the signed Storm output.
  5. verifyOpening({ ...inputs, claimedIndex, claimedItemId }, table).matches — the roll maps to the card you got.
  6. hashClientSeed(seedKeptInBrowser) === inputs.clientSeedHash — your own seed was part of the draw, so the server could not pre-compute it.

Batch anchors are independently auditable at GET /api/anchors/:seq (merkleTree(leaves).root === merkleRoot).

Launch a collection

  1. Design the curve. Call GET /api/community/curve?priceCents=&style= and read back tiers, odds, top card, jackpots and the prize cap. Pick a price tier and a style.
  2. Create a draft. POST /api/community/packs with name, description, price, style.
  3. Add art. POST /api/community/packs/:id/images (10–100 images), set the order with PUT …/order (rank 1 = most valuable), set a cover.
  4. Publish. POST /api/community/packs/:id/publish with attestRights: true → status pending_review. An admin approves it to public.
  5. Earn. You accrue 50% of net margin on every open; it settles to your balance each weekly cycle, net of the cycle's rolling floor reserve. Track it at GET /api/me/creator.

The published version is hashed; its values and odds are frozen until an admin re-issues it. Everything a buyer needs to trust the pack — the table hash, the fairness proof, the vault floor — is produced by the protocol automatically.

Agent guide

LNFT is built to be read and operated by autonomous agents, not just humans. An agent can discover the whole system from two files and a handful of GET requests, then act through the same REST API.

Read the system

  • /docs/llms.txt — a plain-text map of the protocol and the API, written for language models. Fetch it first.
  • GET /api/config — the live, authoritative constants: currency, economics (bps), fairness parameters, pay tokens, market flag. Never assume; read.
  • GET /api/stats — the live protocol state (burned RAIN, accrued fee, vault TVL).

Rules an agent must follow

  • Money is integer cents in the row's currency. Never do float math on balances; never add across currencies.
  • Odds and values are published, not quoted. Call a card's number its "assigned value," never a market price.
  • Respect the solvency guard. An opening can return 409 prize_cap_exceeded; that is correct behaviour, not an error to retry blindly.
  • Sign the exact message. For wallet auth, personal_sign the precise text from the nonce call — a sign-in signature cannot be reused to link, and the reverse.
  • Rate-limit writes. Prefer fewer, larger calls; back off on 429 and honour any Retry-After.

An agent can go end-to-end with no human in the loop: read config → pick a collection → open in play mode to learn the flow → verify the result independently → (with a funded, linked wallet) open in usd mode, sell back or mint, or launch its own collection and earn the creator share.

Recipes

Discover & summarise a collection

cfg   = GET /api/config
packs = GET /api/collections?sort=volume
one   = GET /api/collections/{slug}
// report: price, floor, top card, odds bands, 24h volume, floor listing

Open and independently verify (play mode, no funds)

seed = randomBytes(32)
op   = POST /api/packs/{slug}/open { clientSeedHash: hashClientSeed(seed), mode:"play" }
poll   GET /api/openings/{op.openingId}  until status == "revealed"
v    = GET /api/verify/{op.openingId}
// run the 6 checks in the Verify flow; only trust a result that recomputes

Launch a branded collection

curve = GET /api/community/curve?priceCents=1000&style=balanced
draft = POST /api/community/packs { name, description, priceCents:1000, curveStyle:"balanced" }
        POST /api/community/packs/{id}/images   (10–100 images)
        PUT  /api/community/packs/{id}/order    (rank 1 = top card)
        POST /api/community/packs/{id}/publish  { attestRights:true }
// earn 50% of net margin, settled weekly; track GET /api/me/creator

Addresses & networks

ThingValue
Money & NFT chainArbitrum One — chain id 42161
RAIN token0x25118290e6a5f4139381d072181157035864099d
FeeRouter (burn)0x24904B487129Ad365488bE0FD17E83611bF1CF61
Burn address0x000000000000000000000000000000000000dEaD
RandomnessStorm beacon (BLS, group-key verified)
Explorerarbiscan.io ↗

Live addresses — the vault, the market contract, the NFT contract — are always served by GET /api/config and GET /api/market/config (lower-case hex). Read them from the API; do not hard-code a vault or market address that can change between epochs.

FAQ

Is this an NFT marketplace?

No. It is a liquidity-and-allocation primitive with a marketplace on top. The difference: every card has a vault-guaranteed floor, so the market is a bet above a real price, not above zero.

How is "the operator can't run with the money" guaranteed?

The vault contract exposes no arbitrary-recipient transfer of principal. Funds can only leave to an LP who owns the shares (from the free balance) or to the holder of record of a real card (for its reserved floor). A stolen operator key can settle valid openings and pay valid floors — annoying, not catastrophic.

What makes every collection good for RAIN?

The 1% fee is always converted to RAIN before burning, whatever token the vault uses. More total volume across all brands and collections means more RAIN bought and burned.

Can an agent do all of this without a human?

Yes — read /docs/llms.txt and GET /api/config, then operate through the REST API. Play mode needs no funds and no wallet; real money needs a funded, linked wallet.

Where is the full API reference?

Every endpoint and field is documented in docs/API.md in the repository; this page covers the parts you need to integrate and build.