🌍 English | Italiano | Español | Français | Deutsch | Português | 中文 | 日本語

A fully decentralized community platform with integrated payments, marketplace, and escrow — powered by IOTA 2.0 and Move smart contracts.
Every post is on-chain. Every user signs with their own wallet. Every payment is trustless.

Quick Start • Features • Architecture • Smart Contract • Payments • Themes • Multi-Node • Contributing

Traditional forums depend on a central server that can be shut down, censored, or compromised. IotaPolis stores every piece of data on the IOTA 2.0 blockchain as Move smart contract events. The local server is just a cache — the blockchain is the source of truth.

• True decentralization — Each user has their own IOTA wallet (Ed25519). The server never holds private keys
• No single point of failure — Any node can reconstruct the entire forum from on-chain events
• Immutable history — Every post, edit, and vote is permanently recorded with a transaction digest
• On-chain permissions — Roles (User, Moderator, Admin) enforced by the smart contract, not the server
• Built-in economy — Tips, subscriptions, paid content, badges, and escrow — all on-chain
• Zero fees on testnet — IOTA 2.0 Rebased testnet provides free gas via automatic faucet

# Clone
git clone https://github.com/deduzzo/iotapolis.git
cd iotapolis

# Install dependencies
npm install
cd frontend && npm install && cd ..

# First run — generates server wallet + config
npm run dev
# Wait for "Sails lifted", then Ctrl+C

# Deploy the Move smart contract to IOTA testnet
npm run move:deploy

# Start the forum
npm run dev

Open http://localhost:5173 — create a wallet, get gas from the faucet, register a username, and start posting.

See DEPLOY.md for production deployment, custom networks, and advanced configuration.

7 built-in themes with per-user selection:

Browser (React 19 + Vite 6 + TailwindCSS 4)
  |
  |-- IOTA Ed25519 wallet (mnemonic-derived, AES-encrypted in localStorage)
  |-- Signs and executes transactions DIRECTLY on blockchain
  |-- Rich WYSIWYG editor (Tiptap) -> markdown
  |-- Theme engine (7 presets, CSS variables)
  |-- Wallet page: balance, tips, subscriptions, escrow
  |
  |  REST API (read-only cache) + Socket.io WebSocket
  v
Server (Sails.js + Node.js) — INDEXER ONLY
  |
  |-- Indexes blockchain events into SQLite cache
  |-- Faucet: sends gas to new users (testnet)
  |-- Serves cached data via REST for fast queries
  |-- WebSocket broadcast on every state change
  |-- 30s blockchain polling for cross-node sync
  |-- DOES NOT sign or publish transactions for users
  |
  v
Move Smart Contract (on-chain, immutable)
  |
  |-- Forum (shared): user registry, roles, subscriptions, badges, reputation, treasury
  |-- Escrow (shared objects): multi-sig 2-of-3 fund management
  |-- AdminCap (owned): deployer capability
  |-- 20+ entry functions with role-gated access
  |-- Emits events for every operation (gzipped JSON payloads)
  |-- Handles all payments: tips, subscriptions, purchases, escrow
  |
  v
IOTA 2.0 Rebased (source of truth)
  |
  |-- Events queryable by Package ID
  |-- All nodes see the same data
  |-- Zero fees on testnet

User types a post
  -> Tiptap editor serializes to markdown
  -> Frontend gzip-compresses the JSON payload
  -> User's Ed25519 keypair signs the transaction
  -> Transaction executes directly on IOTA blockchain
  -> Smart contract checks role (USER >= 1), emits ForumEvent
  -> Backend detects event via polling/subscribe
  -> Updates local SQLite cache
  -> Broadcasts 'dataChanged' via WebSocket
  -> All connected clients update their UI

The Move smart contract (move/forum/sources/forum.move) is the security backbone. All permissions and payments are enforced by IOTA validators, not by the server.

Forum (base):

Payments:

Escrow:

• Each user signs with their own Ed25519 keypair — ctx.sender() verified by IOTA validators
• The server never holds user private keys
• Escrow uses cross-validated 2-of-3 voting (cannot vote on both sides)
• Overpayments are automatically refunded (exact change returned)
• Deadline enforcement on escrow operations
• Banned users rejected at the contract level
• Cannot promote above own role, cannot modify equal-or-higher role users

Click the tip button on any post to send IOTA directly to the author. Choose from preset amounts (0.1, 0.5, 1.0 IOTA) or enter a custom amount. Tips are instant, on-chain, with zero intermediaries.

Admins configure subscription tiers with price and duration. Users subscribe by paying the tier price. The smart contract automatically manages expiration and access control.

Authors can set a price for their threads. The content is AES-256 encrypted. After payment (on-chain), the buyer receives the decryption key. 5% fee goes to the forum treasury.

For services between users, the buyer locks funds in an on-chain escrow. Three parties (buyer, seller, arbitrator) form a 2-of-3 multi-sig. Any two can release or refund the funds. 2% fee to the forum treasury on resolution.

After every escrow resolution, both parties can leave a rating (1-5 stars + comment). Ratings are immutable on-chain. User profiles display average rating, trade count, success rate, and volume.

IotaPolis supports multiple independent nodes connected to the same smart contract. Each node:

1. Runs its own Sails.js server + React frontend
2. Has its own SQLite cache (reconstructible)
3. Users sign transactions directly on-chain
4. Syncs from blockchain every 30 seconds

# Start the server
npm run dev

# In the browser: go to Setup -> "Connect to existing forum"
# Paste the connection string: testnet:0xPACKAGE_ID:0xFORUM_OBJECT_ID
# The system syncs all events from the blockchain

Available as a standalone desktop application for Windows, macOS, and Linux. The server runs embedded inside the app.

Download the latest release from GitHub Releases:

All write operations (posts, votes, moderation, payments, escrow) are executed directly on the IOTA blockchain by the user's wallet. The server is a read-only indexer.

1. Generate — Browser creates an Ed25519 keypair from a BIP39 mnemonic (12 words)
2. Encrypt — Mnemonic encrypted with user's password (AES-256-GCM + PBKDF2) and stored in localStorage
3. Faucet — Backend sends gas IOTA to the new address (testnet)
4. Register — User calls register() on the Move contract directly
5. Sign — Every action (post, vote, tip, escrow) is a transaction signed with the user's Ed25519 key
6. Verify — ctx.sender() verified by IOTA validators at the protocol level
7. Backup — Users export their 12-word mnemonic to restore on any device

No passwords on the server. No emails. No accounts. Your wallet is your identity.

Contributions are welcome! This project is in active development.

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Run npm run dev and test locally
5. Commit: git commit -m 'feat: add amazing feature'
6. Push: git push origin feature/amazing-feature
7. Open a Pull Request

MIT License. See LICENSE for details.

Built on IOTA 2.0 Rebased
Every post is a transaction. Every permission is a smart contract. Every user is a wallet.