π§ Products & Technology
What's running proves everything.
Most token whitepapers describe software that does not exist yet. This chapter describes software you can download today. Three native iOS apps are released and live on the App Store, the web platform is in production, and the Solana token services already mint real NFTs and verify real payments on mainnet. The two smart contracts that will govern the token's long-term economics are code-complete and moving through a staged audit β and we say exactly that, not more.
The suite at a glanceβ
Every client β iOS or web β talks to one Django backend, and only the backend talks to Solana. Apps never touch the chain directly: the rule is always app β Django β Solana.
β©οΈ Matsuri β the consumer appβ
The main app for guests and residents: booking, payments, shopping, crowdfunding, live streams, mining, and a full offline disaster lifeline β in one place, guest-mode friendly.
Open Matsuri on the App Store β
The app is organized around five tabs β Events, Shop, Restaurants, Crowdfunding, MyPage β with live streams, search, wallet, NFTs, and the disaster hub reachable from anywhere. Each surface has its own chapter; this table is only the map.
| Surface | In one line |
|---|---|
| Events & experiences | Book tours, events, meetups, and classes; QR tickets and staff check-in β Experiences |
| Restaurants | Discovery with dietary-need filters plus a real table-booking engine β Restaurants |
| Shop | KYC-verified seller marketplace with escrow orders and NFT products β Shop |
| Crowdfunding | All-or-Nothing campaigns with tiered MTC cashback β Crowdfunding |
| Live | Streams with chat, drops, and tipping across five rails β Live |
| Mining, wallet & NFTs | εζγγ€γγ³γ° (sanpai mining β worship mining), AR omikuji, MTC wallet, NFT gallery β Mining |
| Disaster Lifeline | Offline shelter maps, mesh messaging, SOS beacon β Disaster Lifeline |
| Payments | Stripe (cards, Apple Pay), Solana Pay / Phantom, MTC balance β prices always recomputed server-side |
Beyond features, the app leans hard into the iOS platform: home-screen widgets, Siri App Intents, Spotlight indexing, Live Activities for orders, pledges, and live streams, and push notifications localized server-side per user.
Disaster Lifeline under the hoodβ
The Disaster Lifeline chapter covers what it does; here is why it works when everything else fails. The design constraint is brutal and simple: every lifeline tool must work fully offline and without a login.
The nationwide evacuation-shelter dataset ships inside the app binary β the shelter map, distance list, and great-circle Shelter Compass need zero network. Safety guides in 5 languages are bundled the same way.
When cell networks die, phones become the network: an offline peer-to-peer mesh bulletin board relays posts device-to-device with multi-hop relay, and every message is cryptographically signed by its origin device β so a post that traveled five hops cannot be forged along the way.
A DisasterWatchdog service polls public JMA (Japan Meteorological Agency) feeds on launch and foreground; a major event auto-presents the full-screen Disaster Hub β for guests and logged-in users alike.
"I'm safe" goes out over whichever channel survives: mesh, SMS, the system share sheet, or web171 β Japan's official disaster message board.
π‘οΈ GCF Admin β the operator appβ
The operations app for GCF (Global Community Friends) members and staff: everything the web admin portal (gcf.works) can do, on a phone.
| Surface | In one line |
|---|---|
| Dashboard | KPI cards, revenue charts, quick actions |
| Members | Member list, detail, and tier management β GCF |
| Revenue | Commission tracking and payout management |
| Content | Create and publish events, articles, podcasts, and videos |
| Guide slots | Publish and monitor the guide marketplace β Experiences |
| Sacred sites & beacons | Site management and Sponsored Beacon configuration β Mining |
| Mining configuration | Omikuji odds in basis points, dynamic multipliers tuned in real time β Mining |
| Referrals | Branded QR-code generation and referral tracking |
This app is where the mining economy is steered: the dynamic multipliers (0.01Γβ50Γ) that push visitors toward depopulated regions, the omikuji probability tables, and the Sponsored Beacons that municipalities and merchants fund β all are operated from here, not hard-coded.
π° J-Times β the media appβ
"ζ₯ζ¬γγδΈηγΈ / Japan, to the World." The culture media app: articles, podcasts, and video β where reading itself earns MTC.
Open J-Times on the App Store β
| Surface | In one line |
|---|---|
| Articles | Rich reader with reading progress; the newsroom stack includes AI article generation and TTS β Media |
| Podcasts | 6 series, including Japan Decoded and Tech Japan Forward |
| Video | Series plus short-form video |
| Media mining | Reading, listening, watching, and quizzes pay MTC β daily cap 50 MTC β Media |
| Plans | Free / Premium / Pro reader tiers; premium items sold one-off via Stripe |
Engagement is progress-tracked per user per content, with admin-tunable reward rates, a 5-minute cooldown between rewards, and the 50 MTC daily cap β mining that rewards attention without becoming a faucet.
π¦ One shared core: JCCoreβ
All three apps are built on JCCore, a shared Swift package β one implementation of the risky plumbing instead of three drifting copies.
| Module | Role |
|---|---|
| JCAuth | Keychain-based token storage, session management, biometric auth (Face ID / Touch ID) |
| JCNetworking | Type-safe API client, WebSocket support, automatic snake_case wire conversion |
| JCModels | Shared data models β users, tokens, pagination, membership plans |
| JCDesign | Theme protocol and design tokens (spacing, radius) |
| JCUtilities | Date and string utilities |
One consequence users feel: the canonical 4-tier membership ladder (Levels & Tiers) means the same thing in every app, because it is decoded by the same code.
π₯οΈ The backend platformβ
The backend is a single Django monolith that runs the whole economy β bookings, escrow, crowdfunding ledgers, live streams, mining, and every yen and every MTC that moves.
- Framework
- Django 4.2 + Django REST Framework
- Async work
- Celery task queues for background jobs
- Realtime
- Django Channels WebSockets β chat, live interactions, presence
- Database
- PostgreSQL
- Live video
- LiveKit, self-hosted on Hetzner β no third-party streaming dependency
- Fiat rails
- Stripe for cards and Apple Pay; Stripe Connect for seller onboarding and payouts
- Payment safety
- Idempotency keys required on every state-mutating payment call
- Pricing
- Prices are always recomputed server-side β a client can never name its own price
- Chain access
- app β Django β Solana, no exceptions
The crypto payment flow shows the architecture rule in practice. The app never constructs or verifies a Solana transaction itself β it hands the user to Phantom and hands the proof to Django.
If the user gets interrupted mid-payment β a call, a dead battery, a network drop β the app resumes the pending Phantom payment on next launch, and idempotency keys guarantee the booking is settled exactly once.
π Token services β minting on demandβ
A dedicated three-tier stack (live on mainnet) handles everything that actually touches Solana:
- Minting API (Django + DRF + Celery) β API-key-authenticated endpoints the Matsuri, GCF, and J-Times platforms call for automatic NFT/SBT issuance, token operations, and on-chain metadata management.
- Solana signer (Node.js + Fastify) β the only service holding signing capability: SPL token creation and transfer, authority revocation, metadata updates, SBT minting, and Metaplex Core Collection management, with retry/backoff tolerance for indexer lag.
- Admin dashboard (Next.js) β coin and metadata management: Arweave uploads for permanent metadata hosting, creator info, and verification flags.
This is the stack that mints the platform's real assets: event-attendance NFT drops, εΎ‘ζ±ε° (goshuin β temple seal) omikuji NFTs, and the GCF Platinum SBT certificates β all Metaplex Core assets grouped into collections so wallets like Phantom display them properly, all Solscan-verifiable.
π Security & privacyβ
Auth tokens live encrypted in the iOS Keychain; Face ID / Touch ID gates sensitive actions.
HTTPS everywhere with certificate pinning between the apps and the backend.
The platform never holds a user's private key. Signing is delegated to Phantom β the app passes a request, the wallet signs, the backend verifies on-chain.
Linking a wallet to an account requires signing a fresh server-issued challenge, so a captured signature cannot be replayed to claim someone else's wallet.
Worship mining check-ins enforce a 200 m geofence, GPS-accuracy and proximity checks, and one check-in per user per site per day β teleporting bots earn nothing.
MTC balances live in an audited append-only ledger; withdrawals to self-custody pass limits, cooldowns, and fraud screening.
β Engineering qualityβ
The Rust contracts hold themselves to a stricter bar than the apps: zero clippy warnings, zero unwrap or panic in production code, and property-based tests alongside unit tests β because contract code, once deployed, cannot ship a patch on Tuesday.
βοΈ Smart contracts β open-source designβ
On-chain today: the MTC SPL token (900M fixed, mint and freeze authorities revoked), the Streamflow lockup of 550M MTC (cliff 2027-06-01), the initial Raydium MTC/SOL LP, and Solana Pay / Phantom payment verification in the production apps. Nothing else.
The programs below are code-complete and NOT deployed to any cluster. Security proceeds as a staged audit with Hashlock (initiated April 2026, TEAMZ Summit Tokyo): Phase 1 covers matsuri-buyback β submission package complete, kickoff targeted August 2026, findings September, final report October, mainnet deploy targeted OctβDec 2026 after DEX listing. Phase 1.5 covers matsuri-vesting plus matsuri-distribution in Q1 2027, going live at the 2027-06-01 Grand Unlock. We do not describe any of this as "audited" β audit-prep is complete and the staged audit is in progress.
All contract code is open source: github.com/Cootakahashi/matsuri-contracts. Security rests on visible design, not obscurity. The target architecture:
matsuri-buyback β the revenue intakeβ
The program that turns the buyback commitments β 20% of Matsuri HQ sales and 25% of GCF membership fees β into on-chain MTC demand. Its defining property: it is a conveyor, not a treasury.
- Role
- Atomic swap-and-forward of revenue into MTC β accepts whitelisted tokens, swaps, forwards
- Swap route
- Jupiter v6 via CPI, with a pinned, immutable Jupiter program id
- Accepted tokens
- MTC, USDC, SOL at launch β whitelist managed by authority
- Slippage defense
- Three layers: runtime bps within an immutable init-time cap within a compile-time hard ceiling of 10%
- Timelocks
- Recipient and authority changes are propose/execute/cancel flows, bounded 24 hours β 30 days
- Never holds balance
- A zero-balance post-condition is enforced after every swap β there is nothing to steal between transactions
- Size & tests
- 1,797 LOC, 17 tests (13 unit + 4 property)
- Status
- Code-complete, Hashlock Phase 1 audit target β NOT deployed
In Phase 1 the forwarding recipient is a Squads multisig; in Phase 2 it becomes a Buyback Splitter that fans revenue out to LP injection and ecosystem pools.
matsuri-vesting β one vault, one recipient, one clockβ
The program that executes the Grand Unlock schedule. It is deliberately boring: no miners, no scoring, no claims β just arithmetic on a clock.
- Design
- One vault, one timelock-protected recipient, one clock
- Pool
- 550M MTC, arriving from the Streamflow cliff on 2027-06-01
- Epochs
- 730-day (2-year) epochs; each releases 50% of the remaining pool
- Release path
- advance_epoch_and_release is a permissionless crank β anyone can trigger a due release
- Immutability
- Halving factor, epoch length, and total pool lock at initialize and can never be changed
- Size & tests
- 1,629 LOC, 26 tests (22 unit + 4 property)
- Status
- Code-complete, Phase 1.5 audit target (Q1 2027) β NOT deployed
Phase 2 design referencesβ
Three further programs exist as open design references β published for transparency, explicitly marked not-for-deployment, and slated for hardening in later audit phases:
| Program | Design intent |
|---|---|
| matsuri-worship | The worship routing engine β on-chain counterpart of the anti-overtourism multipliers in Mining |
| matsuri-referral | ηΈ (en β bonds) referral trees for En-Mining β Mining |
| matsuri-distribution | Halving distribution with per-miner scoring β being polished into the Phase 1.5 audit scope |
A Phase 2 Distribution Router (vesting fan-out to worship, referral, and general pools) and the Buyback Splitter are design-stage only. Until each program clears its audit phase, the corresponding logic runs off-chain in Django as an oracle β the same rules, upgraded to trustless execution in stages.
Shared design principlesβ
- Checked arithmetic everywhere β no unchecked math, and zero unwrap or panic in production code paths.
- Pure math modules β reward and release calculation is isolated in side-effect-free, exhaustively tested
mathmodules. - Separation of powers β the authority can propose changes only through bounded timelocks; pause halts the program but can never move or seize funds.
- Immutable economics β the parameters that define the token's scarcity are locked at initialization, on purpose.
The apps are shipped. The backend is live. The contracts are written, tested, and queued for audit. What remains is sequencing β and the Roadmap lays that out date by date.