POLP è un protocollo decentralizzato per la certificazione on-chain della posizione geografica di un utente, con validazione combinata tramite NFC e GPS.
Integra un'infrastruttura Web3 per garantire che ogni interazione fisica sia dimostrabile, tracciabile e verificabile pubblicamente.
La tecnologia PAW (Proof of Activity Witnessing) è utilizzata come framework operativo e portale utente per gestire le visite, l’autenticazione e l’assegnazione di badge NFT come prova di presenza.
Certificare su blockchain che un utente si sia trovato in un luogo fisico specifico in un dato momento, attraverso:
- Validazione NFC (prossimità)
- Validazione GPS (coordinate geografiche)
- Firma crittografica e salvataggio IPFS/IPNS
- Emissione NFT univoci come badge di presenza
-
Frontend (PAW Web App)
- React + TailwindCSS + shadcn/ui
- Web NFC API per lettura tag NFC
- Geolocation API per coordinate GPS
- Web3Auth per login e wallet istantaneo
- Redux Toolkit per la gestione degli stati
- Interfaccia utente per vedere visite, badge e progressi
-
Backend (Express.js)
- API RESTful per validazione e registrazione delle visite
- Salvataggio dati su IPFS + versionamento con IPNS
- Validazione coordinate con
geolib - Analisi semantica delle visite tramite
faiss-node - Firma e verifica dei dati per emissione NFT
-
Blockchain
- Contratto
POLPBadge.solsu Gnosis Chain (ERC-721) - Controllo delle claim NFT per utente e visita
- Minting sicuro eseguito solo dal backend
- Contratto
Backend
- Node.js + Express.js
- Sequelize (ORM)
- PostgreSQL
- ipfs-http-client
- faiss-node
- ethers.js
- hardhat
- geolib
Frontend
- React 18
- TailwindCSS
- shadcn/ui
- Redux Toolkit
- Web NFC API
- Web Geolocation API
- Web3Auth
- Axios
Smart Contract
- Solidity
- Hardhat
- Gnosis Chain (per gas bassi ed EVM compatibile)
- L’utente si autentica tramite Web3Auth (creazione wallet in 1 click).
- Viene scansionato un tag NFC tramite Web NFC API.
- Le coordinate GPS vengono acquisite via browser.
- I dati vengono validati, hashati e salvati su IPFS.
- L’hash viene firmato digitalmente e il CID salvato su IPNS.
- Se valido e non già registrato, viene mintato un NFT Badge.
- Tutto il processo è tracciabile e verificabile on-chain.
Il progetto è completamente containerizzato e può essere avviato facilmente tramite Docker Compose. Sono forniti Dockerfile specifici per backend (Node.js 22.13.1) e frontend (Node.js 22.13.1), oltre a un servizio PostgreSQL.
Requisiti
- Docker e Docker Compose installati
- Nessuna dipendenza locale richiesta: tutte le dipendenze (inclusi build-essential, faiss-node, ipfs, ecc.) sono gestite nei container
Porte esposte
- Backend API:
4000(http://localhost:4000) - Frontend:
4173(http://localhost:4173) - PostgreSQL:
5432(solo per sviluppo, non esposto pubblicamente)
Variabili d'ambiente
- Le variabili d'ambiente possono essere definite nei file
.envall'interno di./backende./frontend(vedi i commenti neldocker-compose.yml). - Per PostgreSQL, le credenziali di default sono:
POSTGRES_USER=polpPOSTGRES_PASSWORD=polpPOSTGRES_DB=polp
Avvio rapido
- Clona il repository e posizionati nella root del progetto.
- Avvia tutti i servizi: ```sh docker compose up --build ```
- Accedi ai servizi:
- Frontend: http://localhost:4173
- Backend API: http://localhost:4000
Note e configurazioni
- I dati del database non sono persistenti di default. Per persistenza, decommenta la sezione
volumesrelativa apostgresneldocker-compose.yml. - Puoi personalizzare le variabili d'ambiente creando i file
.envnelle rispettive cartelle. - Il backend e il frontend sono eseguiti come utenti non-root per maggiore sicurezza.
Per dettagli avanzati consulta i Dockerfile in ./backend e ./frontend e il file docker-compose.yml.
🚧 Staging — Prototipo in sviluppo avanzato.
Il codice è strutturato, documentato e pronto per test e miglioramenti iterativi.
Questo progetto è open-source e rilasciato sotto licenza MIT.
Per contribuire o proporre partnership, contattare: dev@polp.space