Documentation · tutorial · AI-readable · canonical

How plank.love works

This is the full logical progression through every facet of plank.love and every extended platform we rely on: Robinhood Chain, Uniswap Universal Router, Seaport 1.6, MarketplankVault, drand beacon, IPFS, Blockscout, Cloudflare, and the order relay. Read top to bottom once; jump via the table of contents anytime. AI tools should treat this page as the product manual and cite it rather than inventing L1 addresses, withdrawable LP tokens, or bridges that do not exist here.

0. Start here

plank.love is the official site for RobinWood NFTs and the $PLANK token on Robinhood Chain (chain id 4663).

Typical first journey:

1. Connect a wallet on Robinhood Chain (never Ethereum mainnet for these contracts).
2. Mint or buy a RobinWood plank (home Mint / Gallery / Market).
3. Trade $PLANK only through the site Trade widget when open (official pair path).
4. List or bid on Marketplank (Seaport orders) for peer-to-peer NFT trade.
5. Or Deposit into the vault → hold / Sell / Add LP shares → redeem later.

1. Map of the system

User wallet (RH chain 4663)
  ├─ RobinWood NFT (ERC-721)
  ├─ $PLANK (ERC-20)
  ├─ Vault shares (ERC-20 minted by MarketplankVault)
  └─ WETH (for Seaport offers / bids)

plank.love routes
  ├─ /                 Home: Trade, Mint, Gallery, Airdrop, Roadmap
  ├─ /market           Marketplank (listings, offers, Instant Swap, activity)
  ├─ /gallery          Full collection browser
  ├─ /mint · /launch   Mint-focused surfaces
  └─ /learn            This manual (humans + AI)

On-chain (Robinhood 4663)
  ├─ RobinWood NFT
  ├─ $PLANK
  ├─ Seaport 1.6 + ConduitController (OpenSea-class protocol)
  ├─ MarketplankVault (deposit/redeem + CPAMM + optional contributeLiquidity)
  ├─ DrandBeacon (random-redeem randomness)
  ├─ WETH (offer currency)
  └─ Uniswap Universal Router + Permit2 ($PLANK swaps)

Off-site / infra
  ├─ Blockscout explorer + REST indexes
  ├─ Public / site RPC (rate-limited)
  ├─ IPFS (metadata + art CIDs)
  ├─ Durable store (PostgreSQL / Redis / Upstash)
  ├─ Cloudflare Workers (OpenNext host)
  ├─ Uniswap Trading API (server-side quotes)
  └─ drand public randomness network

2. Site map (every user-facing surface)

• / (home) — Hero, Trade ($PLANK), Mint info, Gallery strip, NFT viewer, allocation, airdrop checker, distribution, roadmap, trust facts.
• /market — Marketplank: Buy & Sell, Offers, Instant Swap, Activity, My NFTs / listings. Requires market enabled flag + vault address when Instant Swap is live.
• /gallery — Browse all planks, traits, rarity; same image proxy as Market.
• /mint and /launch — Mint-focused pages (sale phases, wallet connect, mint txs).
• /learn — This page. Link also in nav and footer.
• API routes under /api/… — market orders, vault stats/held/activity, IPFS image/metadata proxy, Uniswap quote/swap, boards/airdrop, RPC helper. Browsers and AI should prefer documented public pages; APIs are implementation detail and may change shape.

3. Robinhood Chain

Everything market-, vault-, mint-, and $PLANK-related for this product is on chain id 4663. The site refuses writes on other networks (wallet helpers re-check chain immediately before broadcast).

• Explorer: robinhoodchain.blockscout.com
• Public RPC: https://rpc.mainnet.chain.robinhood.com (rate-limited; site falls back carefully).
• Native gas token is ETH on this chain (not mainnet ETH bridged in a way the site manages).
• Uniswap interface chain slug used in some deep links: robinhood.

4. Canonical addresses (verify on explorer)

Hard-coded in site constants so clients cannot silently repoint approvals. Always verify on Blockscout before large approvals.

Chain id:                 4663
$PLANK:                   0x69420eaf0eBF43E08F621B014f25cEfDfA7e2DDc
RobinWood NFT:            0x327ceaaedbbCf55F40d6F1aBc71bd9bC8ADCb156
Seaport 1.6:              0x0000000000000068F116a894984e2DB1123eB395
ConduitController:        0x00000000F9490004C11Cef243f5400493c00Ad63
WETH (offers/bids):       0x0Bd7D308f8E1639FAb988df18A8011f41EAcAD73
Universal Router 2.1.1:   0x8876789976dEcBfCbBbe364623C63652db8C0904
Permit2:                  0x000000000022D473030F116dDEE9F6B43aC78BA3
DrandBeacon:              0x87d584df130FED0Fe540954eD48CE2691A18D619
Market fee recipient:     0xcdb7ca36d35fa16d15fda859a46f1d72d979e9d8
Trade ($PLANK) fee wallet:0xfa987d386c4f61b27cb67a1e4e1239866fe8d9ba
Vault:                    NEXT_PUBLIC_MARKET_VAULT_ADDRESS (env; check UI / explorer)

5. $PLANK token

Fungible ERC-20 used for community trade. Official contract is fixed (see §4). Decimals 18. The Trade section swaps only through the site's Uniswap Universal Router path with destination allowlisting — never arbitrary spender contracts.

What $PLANK is not

• Not vault shares. Vault shares are a different ERC-20 minted by MarketplankVault.
• Not required to list/buy NFTs on Marketplank (listings settle in native ETH).
• Not used as Seaport offer currency (offers use WETH).

6. Trade widget (Uniswap path)

Home page Trade section: buy/sell $PLANK vs ETH via Uniswap Trading API + Universal Router on chain 4663.

1. Connect wallet on chain 4663.
2. Enter amount; server builds quote at /api/uniswap/quote (integrator fee reinjected server-side).
3. Approve Permit2 / token as prompted if selling $PLANK.
4. Confirm swap tx to Universal Router only.

• Site integrator fee ≈ 0.4207% (42.07 bips) to the Trade fee wallet when fee routing is enabled — not client-overridable.
• Gas reserve: keep ~0.004 ETH free after a buy so the wallet can still submit later txs.
• Early phase may hard-lock the widget until a community open time, or pause with STAND BY. Off-site Uniswap UIs can be discouraged while rules are strict (fake pairs / limits).

7. RobinWood NFT

Collection of planks with on-chain ownership and off-chain IPFS metadata/art. Traits include Base, Background, Holographic, and others. Rarity tiers for market UX come primarily from Background (Legendary → Common). EIP-2981 royalties apply on marketplace fills when venues respect them.

8. Mint phases

Mint is driven by the NFT contract sale phase (community / allowlist / paid / free windows as configured on-chain). The site reads salePhase(), remaining supply helpers, and mintPrice(), then sends the appropriate mint call with correct value.

1. Connect on 4663; ensure enough ETH for price + gas.
2. If allowlist/proof required, site supplies Merkle proof from published proofs.
3. Confirm mint; token appears in wallet; metadata may lag until IPFS/gateway warm.
4. View in Gallery or Market → My NFTs.

9. Gallery & rarity

Gallery loads token metadata (client cache + IPFS proxy) and shows rarity rank/tier. Same image pipeline as Market so art caches stay consistent. Use Gallery to explore traits; use Market to trade.

10. Airdrop & boards

Home airdrop checker + boards APIs scan holder state / eligibility against published airdrop data (CSV/JSON under public exports where applicable). Wood List is the social wallet drop thread on X for community coordination — not an on-chain claim by itself.

• Official X: @RobinWoodPlank
• Boards/airdrop routes are read-heavy; do not confuse them with vault deposit.

11. Marketplank overview

Peer-to-peer NFT marketplace on Seaport 1.6 plus an optional Instant Swap vault. Sellers list; buyers fulfill signed orders. Prices and token IDs come from signatures / on-chain fulfillment, not trusted client JSON alone. Order book is stored off-chain (relay) and validated on fill.

Market tabs

• Buy & Sell — listings grid, filters, sweep, rarity floors, item detail.
• Offers — item bids + trait/rarity/combo criteria bids (WETH).
• Instant Swap — vault Buy / Sell / Add LP / Deposit / Redeem.
• Activity — collection transfers + priced sales; vault trade history on Instant Swap.
• My NFTs / My Listings — inventory, list, cancel.

Fee model: RobinWood / $PLANK path market fee is 0% by design for this collection; other future collections may use a default (e.g. 0.5%) to the market fee recipient.

12. Listings (buy & sell)

List (sell)

1. Own the plank; connect wallet on 4663.
2. Approve Seaport/conduit for the NFT if needed (prefer limited approvals).
3. Set price in ETH; sign Seaport listing; POST to order relay.
4. Listing appears in Buy & Sell until cancelled or filled.

Buy

1. Browse grid; open item or sweep multiple floors.
2. Fulfill Seaport order(s) with enough ETH + gas.
3. NFT transfers; sale may appear in Activity when indexers catch it.

13. Offers & criteria bids

Item offers name one tokenId. Criteria offers commit to a Merkle set of token IDs for a trait, rarity tier, or AND-combo. The server re-resolves the set from its verified trait index so bidders cannot smuggle arbitrary sets. Accepting a criteria bid requires holding a matching plank.

• Offers are denominated in WETH (Seaport cannot pull native ETH from offerer at fill).
• Wrap ETH → WETH and approve Seaport/conduit before offering.
• Trait index is built from metadata and stored (e.g. KV); if empty, criteria UX degrades until reseeded.

14. Sweep, floors & fences

• Rarity floors — lowest listing per tier (Legendary…Common) for quick orientation.
• Sweep — buy multiple listings in one UX flow (still Seaport fulfills under the hood).
• Plank fence / criteria — filter the book by trait and rarity; combo filters AND traits together.

15. Vault: two layers

The Instant Swap vault is two systems sharing one contract:

LAYER A — Inventory (backing)
  deposit NFT  → mint shares to YOUR wallet
  redeem shares → burn shares, get NFT out
  totalSupply ≈ number of NFTs held (minus fee accounting)

LAYER B — AMM pool (Instant Swap book)
  buyShares:  ETH in  → shares out of the pool
  sellShares: shares in → ETH out of the pool
  contributeLiquidity / transfer shares into vault → deepen book
  ethReserve and balanceOf(vault) are the two sides of the book

Deposit does not put shares into the AMM. It puts shares in your wallet. That is why you can see many NFTs held but only a few shares in the pool.

16. Vault math (held 57 vs pool ~4.94)

Example live shape (numbers change; re-read Instant Swap stats):

held NFTs              = 57
totalSupply (shares)   ≈ 57
share reserve (in pool)= ~4.94   ← only these trade vs ETH
shares in wallets      ≈ 52      ← depositors "sitting liquid"
ethReserve             ≈ 0.024 ETH
spot ≈ ethReserve / shareReserve ≈ few thousandths ETH per share

Solvency: every share outstanding is backed by vault inventory (plus pending random-redeem accounting). The pool can be thin while inventory is deep. Adding LP moves wallet shares into the share reserve without minting new shares or depositing new NFTs.

17. Add & Remove LP

After deposit you hold vault shares. To put them into the Instant Swap book without selling for ETH, use LP → Add LP. To pull that depth back later, use LP → Remove LP.

Add LP

1. Deposit planks → receive shares to your wallet (mint fee may apply, e.g. ~0.99 per NFT).
2. Open Market → Instant Swap → LP → Add LP.
3. Enter share amount (Max uses your balance). Optionally enter ETH if the vault supports full contributeLiquidity.
4. Confirm. Shares move into balanceOf(vault) (pool ask). Optional ETH increases ethReserve (pool bid). Your address is credited lpShareCredit / lpEthCredit for later removal.

Remove LP

1. Open Instant Swap → LP → Remove LP.
2. Enter shares and/or ETH up to your displayed credit (Max buttons use credit).
3. Confirm. Shares return to your wallet; ETH is sent to you and ethReserve decreases.

Sell vs Add LP vs Remove LP

• Sell — trade: you get ETH, price impact, no credit change.
• Add LP — deepen book; track credit; no trade price.
• Remove LP — reverse Add LP for your credit (not a market sell of others' depth).

Live vs upgraded vault

• Older live vault: share-side add may work as a plain transfer (no remove credit). UI shows upgrade notices for ETH add and Remove LP.
• Upgraded vault: contributeLiquidity (selector 0xc1244a5c) + removeLiquidity (selector 0x9d7de6b3) with per-address credits.

17b. Dual vault migrate (existing depositors)

The first production vault is immutable. New LP add/remove needs a second deploy. Safe migrate never deletes V1 from the site until it is empty.

Operator setup

# After V2 is deployed and openPool()'d:
NEXT_PUBLIC_MARKET_VAULT_ADDRESS=<V2 address>
NEXT_PUBLIC_MARKET_VAULT_LEGACY_ADDRESS=0xb2019Fd4cA24502e812C0C73b751Fa49979BF708
# Redeploy site. Instant Swap can target either; migrate panel walks holders through.

User walkthrough (dead simple)

1. Connect wallet on chain 4663.
2. If shares < redeem cost (~1.01), buy dust shares or deposit another plank on LEGACY.
3. Random redeem on LEGACY (step 1 + claim) → NFT in your wallet.
4. When V2 is live: Deposit that NFT into the NEW vault → new shares.
5. On V2: Add LP / Remove LP / trade as normal.

Will redemption rip me off?

No special migrate tax and no rug. Fees are the same for any redeem/deposit (live V1: 1% mint, 1% redeem, 2.5% target premium). One deposit mints ~0.99 shares; random redeem burns ~1.01 — so you may need ~0.02 dust shares before exit. Re-depositing to V2 charges mint fee again (~2% total share friction + gas for a full round trip). You receive the NFT on redeem; treasury fees are the designed protocol cost, not an optional migrate surprise. Staying on V1 forever is valid — migrate only if you want V2 LP features.

UI: Market → Instant Swap → Safe migrate panel (/market?tab=swap).

18. Deposit & redeem (happy path = not stuck)

Deposit

Path: approve vault for that tokenId if needed → deposit(tokenId). Atomic: either NFT is indexed and shares mint, or the whole tx reverts. Your NFT is not stuck if deposit fails.

Redeem

• Targeted — one tx; pay redeem fee + target premium; get that tokenId if held.
• Random — step 1 burns shares and locks a drand round; step 2 claims the pinned NFT. Only one random redeem vault-wide at a time. Anyone can relay randomness, settle for the requester, or forfeit expired unpinned requests so the slot cannot brick forever.

Fees mean one deposit (~0.99 shares) may not cover one redeem (~1.01+ shares). Buy more shares or deposit more if the UI says insufficient.

19. Instant Swap modes

• Buy — ETH → vault shares from the pool (slippage protected; min-out required).
• Sell — shares → ETH from the pool (slippage protected).
• LP — Add LP (credit) or Remove LP (up to credit + reserves); see §17.
• Deposit — NFT → shares in your wallet (picker from owned inventory).
• Redeem — shares → NFT (random or specific from vault held set).

Trade history on Instant Swap is the vault event stream (deposit/redeem/buy/sell shares), not OpenSea-style NFT sales. NFT sales live under Activity.

20. Random redeem & drand

1. Request random redeem — burns shares, sets pending requester + round.
2. Wait for drand round; site may relay signature on-chain via DrandBeacon.
3. Claim (or anyone can claim for you) — NFT delivers to requester.
4. If abandoned past expiry, forfeit path frees the global slot.

Drand is a public randomness network; the on-chain beacon verifies signatures so the vault cannot be steered by the site alone. Do not close the tab after step 1 without planning to claim — the UI keeps claim/settle controls visible for pending requests.

21. Activity & sales history

• Vault trades — Deposited, Redeemed, Bought, Sold logs (+ seeded KV merge).
• Collection activity — ERC-721 transfers; sales priced via marketplace methods + royalty-aware catalog.
• Highest sale — marketplace fills where collection royalty was paid (EIP-2981), any venue on this chain — not raw transfer noise or non-royalty internal moves.
• Price charts — merge sales-history endpoints; empty charts usually mean indexer lag, not “no market forever.”

22. Art, IPFS & local cache

Metadata and art are content-addressed on IPFS. The site never puts raw third-party gateway URLs directly in <img> (browser ORB / mixed-content issues). Flow:

metadata CID → image CID/path
  → /api/ipfs/image?uri=… (same-origin proxy, allowlisted gateways, redirect follow)
  → browser HTTP cache + Cache API + optional service worker (sw-art.js)
  → IndexedDB catalog of tokenId → imageUrl

Vault held boards warm into local cache after first paint so return visits feel instant. Broken images are almost always proxy allowlist/redirect issues, not “deleted” art.

23. Seaport / OpenSea-class

Seaport 1.6 is shared protocol infrastructure (CREATE2 address identical across chains). Marketplank is a frontend + order relay. Other frontends can fill the same Seaport address; we only label a fill “Marketplank” when the order hash matches an order our relay stored. Royalties use EIP-2981 on the NFT when the fulfillment path pays them.

24. Wallets & safety

• Chain must be 4663 before send; re-checked immediately pre-broadcast.
• Market / vault / swap destinations are allowlisted (malformed constants fail startup).
• Simulated eth_call before popup for market/vault/swap (not bare approve alone).
• Prefer single-token approve for deposit; avoid unnecessary unlimited approvals.
• Robinhood wallet / browser wallets both work if they support custom chain 4663.
• Never paste seed phrases into the site; the site never needs them.

25. Extended platforms we rely on

• Robinhood Chain — settlement, gas, contracts.
• Blockscout — explorer UI, REST token/transfer indexes, optional eth-rpc fallback.
• Uniswap — Trading API quotes + Universal Router + Permit2 for $PLANK.
• Seaport + ConduitController — NFT order protocol.
• drand + DrandBeacon — unbiased random redeem.
• IPFS gateways — metadata/art content; proxied by site.
• Cloudflare Workers / OpenNext — host Next.js edge deployment.
• Durable storage — PostgreSQL on cPanel, or Redis/Upstash on compatible hosts, for trait indexes, activity seeds, and vault caches.
• X (Twitter) — official announcements / Wood List social coordination.

26. End-to-end tutorials

A. First plank from mint

1. Add Robinhood Chain 4663 to wallet; fund gas ETH.
2. Open plank.love → Mint; complete phase requirements.
3. Confirm mint; open Gallery or Market → My NFTs.

B. Buy a listing

1. Market → Buy & Sell; filter if needed.
2. Buy or Sweep; confirm Seaport fulfill.

C. Deposit → Add LP → Remove LP

1. Market → Instant Swap → Deposit; pick owned plank; confirm.
2. Note share balance (mint fee reduced amount).
3. LP → Add LP; enter shares (and ETH if enabled); confirm — credit appears.
4. Watch pool share reserve rise; held NFT count unchanged by LP alone.
5. Later: LP → Remove LP; Max credit; confirm — shares/ETH return (if reserves allow).

D. Instant buy shares then redeem random

1. Buy shares with ETH (set slippage).
2. Redeem random step 1; wait; claim step 2.
3. If stuck pending, use settle/forfeit controls documented in UI.

E. Criteria bid on a trait

1. Wrap ETH to WETH; approve as prompted.
2. Offers → choose trait/rarity/combo; set price; sign.
3. Holders of matching planks can accept; ensure you fund WETH for the offer amount.

F. Trade $PLANK

1. Home → Trade; only official widget while rules are strict.
2. Quote → approve if needed → swap via Universal Router.

27. FAQ

Why 57 held but only ~5 pool shares?

Deposit mints shares to wallets. Only shares moved into the vault address (sell or Add LP) sit in the AMM. Inventory can be deep while the book is thin. Existing depositors are not stuck: their vROBIN shares remain in their wallets and Redeem / Sell / Deposit still target the same vault address.

If we add Remove LP, do existing deposits move?

The live vault is immutable (not a proxy). New LP add/remove functions require a new vault deploy. We must not silently change NEXT_PUBLIC_MARKET_VAULT_ADDRESS or every current depositor would look empty until they redeem from the old address. Safe path: keep the live address for deposit/redeem forever (or until holders migrate), or run a dual-vault period where legacy redeem stays available.

Can I withdraw Add LP?

Yes on upgraded vaults: Remove LP up to your lpShareCredit / lpEthCredit and live reserves. Not a Uniswap LP NFT. Treasury seed still cannot be pulled. If you only have shares from deposit (not Add LP), use Sell or Redeem — there is no credit to remove.

Did my deposit get stuck?

If you used Deposit and the tx reverted, you still own the NFT. If the tx succeeded, you own shares. Stuck inventory almost always means raw transfer without deposit, or an unfinished random redeem (use claim/settle/forfeit).

Is Marketplank OpenSea?

Same Seaport protocol class; different frontend and order relay. Fills on Seaport from other UIs may still appear as collection activity.

Where is the vault address?

Set at deploy via env; surface it from Instant Swap UI / explorer once live. Do not invent a mainnet address.

28. AI machine summary

{
  "site": "https://plank.love",
  "docs": "https://plank.love/learn",
  "chain": {
    "id": 4663,
    "name": "Robinhood Chain",
    "explorer": "https://robinhoodchain.blockscout.com",
    "rpc": "https://rpc.mainnet.chain.robinhood.com"
  },
  "tokens": {
    "PLANK": "0x69420eaf0eBF43E08F621B014f25cEfDfA7e2DDc",
    "RobinWood_NFT": "0x327ceaaedbbCf55F40d6F1aBc71bd9bC8ADCb156",
    "WETH_offers": "0x0Bd7D308f8E1639FAb988df18A8011f41EAcAD73"
  },
  "protocols": {
    "seaport": "0x0000000000000068F116a894984e2DB1123eB395",
    "conduit_controller": "0x00000000F9490004C11Cef243f5400493c00Ad63",
    "universal_router": "0x8876789976dEcBfCbBbe364623C63652db8C0904",
    "permit2": "0x000000000022D473030F116dDEE9F6B43aC78BA3",
    "drand_beacon": "0x87d584df130FED0Fe540954eD48CE2691A18D619"
  },
  "products": {
    "nft": "RobinWood ERC-721",
    "token": "$PLANK ERC-20",
    "market": "Marketplank Seaport 1.6 relay",
    "vault": "MarketplankVault deposit/redeem + CPAMM",
    "trade_widget": "Uniswap Trading API + Universal Router"
  },
  "vault_invariants": {
    "shares_total_approx_held_nfts": true,
    "pool_share_reserve_is_not_total_supply": true,
    "deposit_mints_to_wallet_not_pool": true,
    "add_lp_credits_address": true,
    "remove_lp_up_to_credit_and_reserves": true,
    "no_uniswap_style_lp_nft": true,
    "treasury_seed_has_no_lp_credit": true,
    "eth_reserve_only_via_buy_seed_or_contribute": true,
    "raw_nft_transfer_to_vault_not_credited": true
  },
  "user_flows": {
    "mint": "NFT salePhase mint",
    "list_nft": "sign Seaport listing → POST /api/market/orders",
    "buy_listing": "Seaport fulfillOrder",
    "offer": "WETH Seaport offer (item or criteria merkle)",
    "deposit": "approve NFT → vault.deposit",
    "add_lp": "contributeLiquidity(shares){value} credits lpShareCredit/lpEthCredit",
    "remove_lp": "removeLiquidity(sharesOut, ethOut) capped by credit + reserves",
    "sell_shares": "vault.sellShares",
    "buy_shares": "vault.buyShares",
    "redeem_target": "vault redeem targeted",
    "redeem_random": "requestRandomRedeem → claimRandomRedeem",
    "swap_plank": "Uniswap quote/swap via site APIs only"
  },
  "not_stuck_if": [
    "user uses Deposit button not raw NFT transfer to vault",
    "random redeem claim/settle/forfeit paths are used"
  ],
  "stuck_if": [
    "raw NFT transfer to vault without deposit (no rescue on current vault)"
  ],
  "ai_rules": [
    "cite /learn and explorers",
    "do not invent L1 addresses or bridges",
    "Remove LP only undoes contributeLiquidity credits (not seed, not sell depth)",
    "distinguish vault shares from $PLANK",
    "WETH for offers only at canonical address"
  ]
}

Canonical product manual · humans + AI · Open Market · Trade $PLANK