Reference · Technical notes

The ledger.

Protocol overview

Mnhwa is a set of Anchor instructions around a per-rental escrow PDA.
Owners call register_nft to delegate a compressed NFT to the program and post a max-duration + daily rate.
Renters call start_rental to lock deposit + pro-rated fee and receive a receipt cNFT.
Time-based expiry is enforced on-chain; off-chain keepers crank force_return after end_time.

escrow(PDA) :: seeds = ['escrow', mint, renter] -- holds deposit + fee lamports + end_time.
registry(PDA) :: seeds = ['registry', owner] -- a map of mint -> rental params.
rental_state(PDA) :: seeds = ['rental', mint] -- active rental markers; prevents double-lease.
Fees accrue into fee_vault(PDA) and can be withdrawn by authority for buyback.

Entry 03#fees

Platform fee: 2.50% on every rental. 100% routed to $MNHWA buyback+burn.
Keeper tip: 5% of the locked deposit goes to whoever cranks force_return after expiry.
Deposit: default 3x daily rate, overridable per mint by the owner at register time.
Max duration: per-mint, owner-configurable. Default ceiling is 30 days.

Entry 04#keeper

Hono service on Railway scans rentals where status=active AND end_time<=now() every 30s.
Builds a force_return instruction signed by ESCROW_AUTHORITY_KEY, broadcasts via Helius.
On success: rental.status=returned, deposit snaps back to owner minus keeper tip.
A Telegram bot notifies subscribers 30 minutes before expiry, reducing keeper-tip churn.

Entry 05#api

GET /api/catalog -- paginated cNFTs registered as rentable. 60s Redis cache.
GET /api/catalog/:mint -- single volume, includes delegate + rate metadata.
POST /api/rentals/quote -- body { mint, durationSeconds }. Returns fee + deposit preview.
POST /api/rentals/prepare -- body { mint, duration, renter }. Returns unsigned tx (base64).
POST /api/rentals/submit -- body { signedTx }. Broadcasts and polls confirmation.
GET /api/stats -- global counters for the landing-page ticker.