MagicWebb — Technical Whitepaper
Version 1.4 — 2026-05-14
Network: Flare Coston2 (testnet)
License: MIT
1. Abstract
MagicWebb is a non-custodial NFT marketplace shipped as a single Go binary (Go Fiber server + an embedded static Astro/Svelte UI + an on-chain event indexer) talking to immutable on-chain contracts. It supports fixed-price listings, English auctions, and fully on-chain escrowed offers across ERC-721 and ERC-1155 assets.
2. Design goals
| Goal | Rationale |
|---|---|
| Non-custodial | NFTs remain in seller custody until atomic settlement. |
| Minimal architecture | One Go binary (server + UI + indexer) plus the contracts. The Astro frontend is pre-built to app/dist/ and served as static assets by the Go binary — no Node runtime required at deployment. No separate frontend service, no container required. |
| Hybrid 721/1155 | One marketplace surface for both token standards. |
| Fully on-chain offers | Offers escrow native FLR in OfferBook on-chain — no off-chain signatures, deposits, or relayers. |
| Predictable operations | Single .env and a Makefile lifecycle (dev, build, run, migrate, test, deploy, load-addrs). |
| Wallet-only surface area | The app submits transactions when chain state requires it; users connect and confirm (or reject) in the wallet — no separate manual “claim” or “settle” hunting except on failure retry. |
3. System architecture
Wallet (ethers.js) --writes--> Flare RPC --> Contracts --events--> Indexer
--> Postgres --> Go Fiber server (static Astro UI + WebSocket) --reads--> Wallet / Browser
3.1 Contract roles
| Contract | Responsibility |
|---|---|
Marketplace |
All fixed-price, native-token listings. Listings are time-bounded (expiry); price and terms are set on-chain by the seller. |
AuctionHouse |
All English auctions (ERC-721 and ERC-1155). Auction copy, timers, and bid semantics should be internationalized in the app so every locale can follow reserve, increments, anti-snipe, and settlement without relying on English-only chain data. |
OfferBook |
All offer lifecycle, fully on-chain: makeOffer is payable and escrows the full principal (msg.value must equal it exactly). Each bidder holds one position per NFT: a repeat offer replaces the principal and refunds the old one in the same transaction — offers do not stack. Acceptance, rejection, and expiry refunds are on-chain. No signatures, no nonces, no separate deposit balance — the escrowed position is the source of truth. |
MarketplaceCore |
Shared immutable fee math (_feeOf), payout helpers (_payFee, _pay), standard-aware NFT transfer helpers, and ReentrancyGuard. No admin roles, no fee mutability, no pause switch — so listings, auctions, and offers cannot silently change fee economics or clash on shared settlement primitives. |
3.2 Platform fee (single, unified, immutable)
MagicWebb charges a single 2% platform fee (PLATFORM_FEE_BPS = 200, split PLATFORM_SHARE_BPS = 150 to feeRecipient and KEEPER_SHARE_BPS = 50 to the network keeper via manager.keeper() — falls back to 100% feeRecipient when no keeper is set), applied only on a successful sale and deducted from the seller’s proceeds. Listing, auction creation, bidding, and making offers are all free. One constant governs every settlement path.
The fee is a constant in MarketplaceCore.sol, not a constructor argument or mutable storage variable. It cannot be changed by any admin key, environment variable, or upgrade path. Changing it requires deploying new contracts.
Fee recipient: feeRecipient — an immutable wallet address set once at deploy time. Fees are sent directly via .call{value: fee}("") to this address. No intermediary contract, no vault, no accumulator.
The unified deploy script (DeployV34.s.sol) takes FEE_RECIPIENT_ADDR as the feeRecipient and KEEPER_ADDR as the network’s single keeper — the only address that may ever settle on the keeper tier, with no mechanism anywhere to enroll another. Every network — Coston2, Songbird and Flare — deploys UNSEALED with a single per-network admin (ADMIN_ADDR) that can perform instant, admin-gated upgrades; each network becomes immutable only when its admin calls renounceAdmin() on the owner’s explicit go-immutable order (a SEAL=true deploy mode also exists for sealing at deploy, requiring a multisig fee recipient) — see docs/IMMUTABILITY_TRANSITION.md. No FEE_BPS variable exists — the rate is fixed in code.
3.3 Fees applied, refunds, and failed transfers (all surfaces)
Where the 2% fee applies. The platform fee is charged only when a sale settles, deducted from the seller’s proceeds:
- Buy: 2% of sale price, deducted from seller proceeds (
_payFee+_pay) in the same atomic transaction as the NFT transfer. The buyer sends exactly the price. - Auction settlement: 2% of the winning bid, deducted from seller proceeds when
settle()is called. - Offer acceptance: 2% of the offer amount, deducted from seller proceeds when
acceptOffer()/acceptOffer1155()is called.
What is NOT charged: Listing, auction creation, bid placement, bid withdrawals and loser refunds, making/editing offers, offer rejection/expiry refunds, and listing cancellation — none of these deduct any fee. Bids and offer principals are fully refundable.
Auction bids (cumulative; no fee applied on bids). Every bid adds its msg.value to the bidder’s running total, cumulative[id][bidder]; your effective bid is the sum of everything you have sent to that auction. Every bidder — the leader and anyone trying to overtake — therefore sends only the top-up, never the full new amount: to take the lead, your cumulative total after the bid must reach at least the leader’s total + 1 native token (MIN_BID_INCREMENT), or clear the reserve when there is no leader yet. A bid that would not put you in the lead reverts (BidTooLow) and escrows nothing. A returning bidder who sends the “full new amount” adds it to their earlier escrow and bids more than they meant to. Being outbid does not refund you: your escrow stays in cumulative (not in pendingReturns) so you can top up and retake the lead. A non-leading bidder pulls 100% of their escrow at any time before settlement with withdrawLoserFunds(id); after settlement or forceCancel, refundLosers(id, batch) (permissionless; the keeper runs it) returns every losing bidder’s escrow in full. pendingReturns / withdrawRefund is only the fallback for a push that could not be delivered (for example to a contract wallet whose receive() reverts or needs more gas).
When the fee is applied (after NFT transfer). On every settlement path, the implementation performs the standard-aware NFT transfer first, then _payFee (fee → feeRecipient) and _pay (proceeds → seller). For buy and acceptOffer, if the transfer reverts, the whole transaction reverts: the fee is not applied and no sale state is finalized. settle is the exception: a failed auction delivery does not revert but finalises the auction without a sale (AuctionSettlementFailed, see §4.3); no fee is taken unless a contract winner refused an ERC-1155 delivery (AuctionWinnerRejected, the 2% fee is charged to that winner).
Expired or cancelled listings / unsold auctions. If nothing sells, no trade proceeds exist and the platform fee is not applied—there is no separate “fee escrow” to unwind. buy on an expired listing simply reverts (Expired). A seller-cancelled listing is deleted with no payment flow.
3.4 Wallet confirmations only (product automation)
On-chain rules still require transactions for settlement and pull refunds, but the MagicWebb app is responsible for submitting those transactions when reads show they are needed, so users normally only connect the wallet and approve or reject the prompts—no hunting for extra buttons like “settle” or “claim refund” unless a submission fails and a one-tap retry is shown.
Concrete behavior (reference implementation):
- Auction end: When an auction has bids and has passed
endsAt, opening the auction page with a connected wallet triggerssettleautomatically (wallet confirmation). - Outbid escrow: An outbid bidder’s escrow stays in the auction. The auction and token pages show Withdraw my bid (
withdrawLoserFunds) while you are not leading; after settlement the keeper returns losing escrow withrefundLosers. - Failed pushes: When a payment could not be pushed to your wallet, it is credited to
pendingReturnson that core contract. The profile Refunds card reads each core and withdraws withwithdrawRefund(one wallet confirmation per core). - Offer expiry refunds:
refundExpiredOfferis permissionless — anyone (a keeper or the bidder) can trigger the full-principal refund of an expired offer; the app prompts the bidder when one of theirs has lapsed.
Optional operations hardening (not required by contracts): a small relayer balance can call settle on users’ behalf so winners receive the NFT with zero signatures from them; that is a deployment choice and does not change fee application rules.
4. Data flow
4.1 Fixed-price purchase
- Seller lists an NFT on
Marketplace(on-chain listing acts as the seller’s offer to sell for the listed price until expiry). - Buyer calls
buywith exactmsg.valueequal to the list price (buyer accepts that listing; the buyer becomes the NFT recipient and the listed amount is taken from the buyer’s wallet in the same transaction). - Contract validates the listing, transfers the NFT, then splits payment (platform fee collected, remainder → seller) in the same atomic transaction, emits events.
- Frontend refreshes chain-backed reads after transaction receipt.
4.2 On-chain offer acceptance
- Bidder calls
makeOffer/makeOffer1155(payable), escrowing the full principal inOfferBook(msg.valuemust equalprincipalexactly). A repeat offer on the same NFT edits the existing position: the newprincipalreplaces the old one, the old principal is refunded in the same transaction, and the offer becomes exactly the new amount (send the full amount you want to offer, not a top-up). An edit does NOT refresh the expiry timer, cannot revive an expired offer, and cannot change the units or token standard (ERC-1155 units are frozen;cancelOffer()and offer again to change them). Offering is free. Bidders can cancel their offer before expiry viacancelOffer(). - Owner calls
acceptOffer/acceptOffer1155(must currently own and have approved the NFT). - Contract validates the position and ownership/approval, transfers the NFT to the bidder, then pays the seller
principal − 2%and the fee split tofeeRecipient/ keeper (FeeSplitevent) — one atomic transaction. Rejected or expired offers refund the full principal.
4.3 Auction settlement
- Seller creates an auction with reserve and end time. The bid increment is fixed marketplace-wide: taking the lead requires a cumulative total of at least the leader’s total + 1 native token (no per-auction increment settings).
- Bidders place bids. Bids are cumulative for everyone: each bid adds
msg.valueto that bidder’s total, so the leader and challengers alike send only the top-up that brings their total to the leader’s total + 1 native token. Outbid bidders keep their escrow in the auction (no fee applied on bids) and either top up again or pull it in full withwithdrawLoserFunds(see §3.3). - After
endsAt,settlemay be called once by the keeper, the seller, or the winning bidder — no other party can settle someone else’s auction (the keeper bot does it automatically the moment the auction ends). That transaction transfers the NFT to the highest bidder, then applies the immutable platform fee to the winning bid (the leader’s cumulative total) and pays the seller—fee is applied only on this winning settlement, not on intermediate bids. The app promptssettlewhen you view the auction (see §3.4); on-chain, it remains one atomic transaction, not a cron inside the contract. - Seller default. A met reserve is not a binding commitment by the seller: the NFT stays in the seller’s wallet until settlement, so a seller who moves it or revokes the approval can walk away at no cost beyond gas.
settlethen does not revert; it finalises the auction without a sale and emitsAuctionSettlementFailed(no fee, the seller gets nothing, the winner’s whole escrow is pushed back with apendingReturnsfallback). BeforeendsAtthe current leader can reach the same outcome early withclaimSellerDefault(id), which works only when the collection positively answers that the seller no longer holds the token(s) or no longer approvesAuctionHouse(a probe that reverts or runs out of gas proves nothing and the call reverts withSellerCanStillDeliver). Losing bidders are then refunded in full throughrefundLosers(permissionless; the keeper runs it, and any loser can call it with their own address).withdrawLoserFundsonly works before settlement.
Entry points behind the app’s buttons (the guides use the button names; the identifiers live here): Withdraw my bid → withdrawLoserFunds (a non-leading bidder pulls their cumulative escrow at any time before settlement); Cancel and refund everyone → forceCancel (winner, seller, or keeper, only 3 days after an unsettled end — releases every bidder’s escrow); Enable offers on a collection page → setOfferEligible (ERC-173 collection owner only); the profile Refunds card reads pendingReturns on each core contract and withdraws via withdrawRefund.
5. Security model
| Vector | Mitigation |
|---|---|
| Reentrancy on payable flows | ReentrancyGuard + checks-effects-interactions |
| Auction griefing via refund callback | Gas-capped, copy-free pushes with a pull fallback (pendingReturns / withdrawRefund); losing escrow is pulled (withdrawLoserFunds) or batch-refunded after settlement (refundLosers) |
| Offer / escrow integrity | Offers are on-chain payable positions (no signatures to replay); escrowed balance always equals the sum of active principals — enforced by an invariant test |
| Fee abuse | PLATFORM_FEE_BPS is a hardcoded constant (2%); no admin key, env var, or upgrade path can change it |
| Listing overwrite by third party | Seller collision checks (AlreadyListed) |
Residual accepted risks:
- Timestamp-based expiries inherit normal block timestamp variance.
tokenId == 0collection-wide sentinel behavior is documented and UI-constrained.
6. Operations
Canonical Makefile targets:
make dev— run the server locally (hot reload)make build— compile the single binary tobin/magicwebbmake run— build then runmake migrate POSTGRES_URL=…— apply Postgres migrations through the server’s own boot path (backend/cmd/migrate; they are also auto-applied at startup).make migrate-status POSTGRES_URL=…lists applied and pending ones. Both takePOSTGRES_URLfrom the command line or an exported environment variable only, never from.env(aPOSTGRES_URLline in.envdoes not override the one you exported)make test/make contracts-test— Go (-race) and Forge suitesmake deploy/make load-addrs— deploy contracts to Coston2 and sync addresses into.env
Configuration source of truth:
- committed template:
.env.example - local / production runtime:
.env(copy the template, then edit)
7. Roadmap
| Phase | Scope |
|---|---|
| Phase 1 | Coston2 with fixed-price, auctions, and on-chain escrowed offers. |
| Phase 2 | Multisig operational hardening. |
| Phase 3 | UX/performance iteration and broader collection coverage. |
8. Appendix — core event families
Marketplace:Listed,Cancelled,BoughtAuctionHouse:AuctionCreated,BidPlaced,OutbidNotification,AuctionExtended,AuctionSettled,AuctionSettlementFailed(seller default, includingclaimSellerDefault, or winner rejection),AuctionWinnerRejected,LoserRefunded,AuctionCancelled,AuctionForceCancelled. A credit the house could not push surfaces asAuctionSettlementFailed(the winner’s escrow) orPushFailed(any other push that fell back topendingReturns);withdrawRefundemitsRefundWithdrawn; the leader’s early exit on seller default isclaimSellerDefault, which emitsAuctionSettlementFailed.- Every core (
MarketplaceCore):PushFailed(a push fell back topendingReturns),RefundWithdrawn(withdrawRefund),FeeSplit OfferBook:OfferMade,OfferAccepted,OfferRefunded