Landmark ($LMRK)

Stake to Mark, Vote to Earn

A Base Mini-App for posting geolocated landmarks. Users stake $LMRK to post map "Landmarks" (photos, facts, memes) at a geohash6 location; others upvote by spending $LMRK; daily per-region rewards distribute from a pool.

Built with OnchainKit, Base RPC, MapLibre GL, and Supabase. No Neynar or paid APIs required.

🎯 Features

Post Landmarks: Stake 0.1 $LMRK to drop a landmark at any geohash6 location
Vote & Earn: Upvote great content; 90% goes to creators, 10% to treasury
Mint NFTs: Burn 10 $LMRK to mint commemorative "Placemark" NFTs
Regional Leaderboards: Daily rewards distributed to top landmarks per region
Privacy-First: Geohash6 (~1.2km grid), EXIF stripping, no GPS tracking
PWA Ready: Installable, offline-capable, mobile-optimized

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                        Frontend (Next.js)                    │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐   │
│  │   Map    │  │   Post   │  │   Vote   │  │   Mint   │   │
│  │  (MapGL) │  │  Sheet   │  │  Button  │  │  Button  │   │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘   │
│         ↓              ↓              ↓             ↓        │
│  ┌──────────────────────────────────────────────────────┐  │
│  │          OnchainKit + Wagmi (Base RPC)              │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                          ↓                    ↓
┌─────────────────────────────────┐  ┌─────────────────────┐
│   Smart Contracts (Base)        │  │  Indexer (Serverless)│
│  ┌──────────────────────────┐  │  │  ┌──────────────┐   │
│  │  LandmarkRegistry.sol    │  │  │  │ Event Indexer│   │
│  │  - postPin()             │  │←─┤  │ - Posted     │   │
│  │  - upvote()              │  │  │  │ - Voted      │   │
│  │  - withdrawStake()       │  │  │  │ - Settled    │   │
│  └──────────────────────────┘  │  │  └──────────────┘   │
│  ┌──────────────────────────┐  │  │         ↓           │
│  │  LandmarkNFT.sol         │  │  │  ┌──────────────┐   │
│  │  - mintFromPost()        │  │  │  │  Supabase DB │   │
│  └──────────────────────────┘  │  │  │ + Storage    │   │
└─────────────────────────────────┘  └──┴──────────────┴───┘

🚀 Quick Start

Prerequisites

Node.js ≥ 20
pnpm ≥ 9
Foundry (for smart contracts)
Base RPC URL (public or Alchemy/Infura)
Supabase account (free tier)

1. Clone & Setup

git clone https://github.com/yourusername/landmark.git
cd landmark

# Initialize submodules
git submodule update --init --recursive

# Install dependencies
pnpm install

2. Environment Variables

Copy .env.example to .env.local:

Copy-Item .env.example .env.local

Fill in required values:

# Base Network
NEXT_PUBLIC_BASE_RPC_URL=https://mainnet.base.org
NEXT_PUBLIC_CHAIN_ID=8453

# Contracts (populate after deployment)
NEXT_PUBLIC_LMRK_TOKEN_ADDRESS=0x...
NEXT_PUBLIC_LANDMARK_REGISTRY_ADDRESS=0x...
NEXT_PUBLIC_LANDMARK_NFT_ADDRESS=0x...
NEXT_PUBLIC_TREASURY_ADDRESS=0x...

# Supabase
NEXT_PUBLIC_SUPABASE_URL=https://xxx.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbGc...
SUPABASE_SERVICE_ROLE_KEY=eyJhbGc...

# Feature Flags
NEXT_PUBLIC_FF_SHARE_CARDS=true
NEXT_PUBLIC_FF_PWA=true
NEXT_PUBLIC_FF_OFFLINE_QUEUE=true

3. Deploy Smart Contracts

cd contracts

# Set deployment env vars
$env:BASE_RPC_URL="https://mainnet.base.org"
$env:PRIVATE_KEY="0x..."
$env:LMRK_TOKEN_ADDRESS="0x..." # Your $LMRK token
$env:TREASURY_ADDRESS="0x..."   # Treasury wallet

# Compile
forge build

# Deploy to Base
forge script script/Deploy.s.sol:DeployScript --rpc-url $env:BASE_RPC_URL --broadcast --verify

Copy contract addresses to .env.local

4. Setup Supabase

Run the schema migration:

-- See docs/supabase-schema.sql
-- Create tables: landmarks, leaderboard
-- Create storage bucket: landmarks

5. Run Development Server

pnpm dev

Open http://localhost:3000

6. Run Indexer (Separate Process)

pnpm indexer:dev

The indexer subscribes to Base RPC events and populates Supabase.

📁 Project Structure

landmark/
├── contracts/              # Smart contracts (Foundry)
│   ├── src/
│   │   ├── LandmarkRegistry.sol
│   │   ├── LandmarkNFT.sol
│   │   ├── interfaces/
│   │   └── utils/
│   ├── script/Deploy.s.sol
│   └── foundry.toml
├── src/
│   ├── app/                # Next.js App Router
│   │   ├── api/            # API routes (upload, metadata)
│   │   ├── layout.tsx
│   │   ├── page.tsx
│   │   └── providers.tsx
│   ├── components/         # React components
│   │   ├── layout/         # AppShell, TopBar, BottomDock
│   │   ├── map/            # MapView (MapLibre GL)
│   │   ├── landmark/       # Detail, VoteButton, MintButton
│   │   ├── post/           # PostSheet
│   │   ├── wallet/         # ConnectButton
│   │   ├── ui/             # Toast, Dialog, etc.
│   │   └── icons/
│   ├── lib/                # Utilities & logic
│   │   ├── api.ts          # API client
│   │   ├── contracts.ts    # ABIs & addresses
│   │   ├── geohash.ts      # Geohash utilities
│   │   ├── image.ts        # EXIF stripping, validation
│   │   ├── sharecard.ts    # Share card generation
│   │   ├── store.ts        # Zustand state
│   │   ├── types.ts        # TypeScript types
│   │   ├── utils.ts        # Helpers
│   │   └── analytics.ts    # Privacy-friendly tracking
│   ├── indexer/            # Event indexer
│   │   └── index.ts
│   └── styles/
│       └── globals.css     # Tailwind + design tokens
├── public/
│   ├── manifest.json       # PWA manifest
│   ├── sw.js               # Service worker
│   └── offline.html        # Offline fallback
├── design/
│   └── tokens.json         # Design tokens (Figma-ready)
├── docs/
│   ├── third_party.md      # Submodule SHAs
│   └── supabase-schema.sql # Database schema
├── vendor/                 # Git submodules
│   ├── onchainkit/
│   ├── miniapps/
│   └── ...
├── .env.example
├── package.json
├── tailwind.config.js
├── tsconfig.json
└── README.md

🎨 Design System

All design tokens follow the Base Brand Kit.

Color Palette

--brand: #0052FF;      /* Base blue accent */
--bg: #0A0B0D;         /* Dark canvas */
--surface: #121418;    /* Elevated surfaces */
--text: #E7ECF2;       /* Primary text */
--token: #73F3C4;      /* $LMRK accent */

Typography

Font: Inter (400, 500, 600, 700, 800)
Sizes: 12/14/16/20/24/32 px
Line Height: 1.2 (tight), 1.35 (normal)

Components

See src/components/ for implementation. All components:

WCAG AA+ contrast
Keyboard accessible
Mobile-first (touch targets ≥ 44px)
Reduced motion support

🔐 Smart Contracts

LandmarkRegistry

Core Functions:

postPin(geohash6, region3, contentCID) → Stakes 0.1 $LMRK, emits LandmarkPosted
upvote(pinId, amount) → Splits 90% to author, 10% to treasury
withdrawStake(pinId) → After 7-day cooldown, 1% burn fee
settleRegion(region3, rewardAmount, topPins, shares) → Distributes daily rewards

Constants:

STAKE_AMOUNT: 0.1 $LMRK
COOLDOWN_PERIOD: 7 days
WITHDRAW_BURN_BPS: 100 (1%)
UPVOTE_AUTHOR_BPS: 9000 (90%)

LandmarkNFT

Core Functions:

mintFromPost(landmarkId, tokenURI) → Burns 10 $LMRK, mints ERC-721

Note: Each landmark can only be minted once.

📊 Indexer

The indexer:

Subscribes to Base RPC for LandmarkPosted, LandmarkVoted, RegionSettled events
Decodes geohashes to lat/lng
Stores in Supabase (landmarks, leaderboard tables)
Computes daily top-20 per region3

Run Indexer:

pnpm indexer:dev

For production, deploy as a serverless function (Vercel Cron, Railway, etc.).

🌐 API Endpoints

`GET /api/landmarks`

Fetch landmarks in viewport.

Query Params:

minLat, minLng, maxLat, maxLng: Bounding box
limit: Max results (default 500)

`POST /api/upload`

Upload image to Supabase Storage.

Body: multipart/form-data with file field

Response:

{
  "cid": "path/to/file",
  "url": "https://xxx.supabase.co/storage/v1/..."
}

`POST /api/nft/metadata`

Generate NFT metadata JSON.

Body:

{
  "landmarkId": "123",
  "imageUrl": "https://...",
  "caption": "Amazing view!"
}

Response:

{
  "tokenURI": "https://xxx.supabase.co/storage/v1/.../metadata/123.json"
}

🎯 User Flows

Drop a Landmark (≤60s)

Tap [+] FAB
Upload photo → Auto-strips EXIF
Write caption (≤200 chars)
Geohash auto-fills from map center
Tap Post → Approve $LMRK → Confirm stake
Success toast: "Posted • Stake locked"

Upvote

Tap marker on map → Detail sheet opens
Tap Upvote (0.01 $LMRK)
Approve → Confirm → "+1 upvote sent"

Mint Placemark NFT

In landmark detail → Tap Mint NFT
Modal shows burn amount (10 $LMRK)
Progress: Approve → Generate metadata → Mint
Success: "Placemark minted"

🔧 Configuration

Feature Flags

Set in .env.local:

NEXT_PUBLIC_FF_SHARE_CARDS: Enable share card generation
NEXT_PUBLIC_FF_PWA: Enable PWA features
NEXT_PUBLIC_FF_A11Y_HI_CONTRAST: High-contrast mode
NEXT_PUBLIC_FF_OFFLINE_QUEUE: Queue posts/votes offline

Bundle Optimization

Target: <180KB initial JS

Code splitting: Map, post sheet lazy-loaded
Tree shaking: OnchainKit, MapLibre modular imports
Image optimization: Next.js <Image> with AVIF/WebP

🧪 Testing

# Type check
pnpm type-check

# Lint
pnpm lint

# Smart contract tests
cd contracts
forge test

🚢 Deployment

Frontend (Vercel)

Connect repo to Vercel
Set environment variables
Deploy: vercel --prod

Contracts (Base Mainnet)

cd contracts
forge script script/Deploy.s.sol:DeployScript --rpc-url $BASE_RPC_URL --broadcast --verify

Indexer (Railway / Render)

Deploy src/indexer/index.ts as a long-running process.

Dockerfile Example:

FROM node:20-alpine
WORKDIR /app
COPY package.json pnpm-lock.yaml ./
RUN npm install -g pnpm && pnpm install --frozen-lockfile
COPY . .
CMD ["pnpm", "indexer:dev"]

📈 Performance Targets

Metric	Target	Notes
Initial Load	<1.5s	4G network
TTI	<2.5s	Time to Interactive
Map FPS	≥45	With 500 markers
Bundle Size	<180KB	Initial JS
Lighthouse PWA	≥90
Lighthouse A11y	≥95	WCAG AA+

♿ Accessibility

Keyboard Navigation: All controls operable without mouse
Screen Reader: ARIA labels, live regions for tx updates
Contrast: WCAG AA+ (4.5:1 minimum)
Focus Visible: 2px high-contrast rings
Reduced Motion: Respects prefers-reduced-motion

🔒 Security

No Private Keys: MiniKit/wallet handles signing
EXIF Stripping: Client-side before upload
Geohash Privacy: 6-char (~1.2km), no raw GPS
File Validation: Type/size checks, 2MB max
Rate Limiting: Consider Cloudflare/Vercel protection

📖 References

🤝 Contributing

Contributions welcome! Please:

Fork the repo
Create a feature branch: git checkout -b feature/amazing
Commit changes: git commit -m 'Add amazing feature'
Push: git push origin feature/amazing
Open a Pull Request

📄 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

Base for the incredible L2 infrastructure
Coinbase for OnchainKit and MiniKit
Farcaster for the MiniApps framework
MapLibre for the open-source map renderer

📞 Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Twitter: @LandmarkApp

Built with ❤️ on Base

Name		Name	Last commit message	Last commit date
Latest commit History 14 Commits
contracts		contracts
design		design
docs		docs
public		public
src		src
.dockerignore		.dockerignore
.editorconfig		.editorconfig
.env.example		.env.example
.gitignore		.gitignore
.gitmodules		.gitmodules
.prettierrc		.prettierrc
Dockerfile		Dockerfile
Dockerfile.dev		Dockerfile.dev
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml
next.config.js		next.config.js
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
postcss.config.js		postcss.config.js
tailwind.config.js		tailwind.config.js
tsconfig.json		tsconfig.json

License

steffenpharai/Landmark

Folders and files

Latest commit

History

Repository files navigation