A
Alfassa Chain Docs
1. Architettura di Rete 2. MetaMask 3. Ecosistema & Token 4. Endpoints e API 5. Smart Contract 6. Sicurezza ★ Integrazioni
Documentazione ufficiale · IT Team Alfassa

Guida completa ad
Alfassa Chain

Blockchain Mainnet EVM-compatibile con consenso PoA (Geth Clique). Coin nativa ALFA. Progettata per velocità, stabilità e integrazione nativa con dApp, plugin WordPress e sistemi aziendali.

⚡ Collega MetaMask Integrazioni Web3 → Swap DEX ↗
Parametri di rete
Nome reteAlfassa Chain
Chain ID8455 (0x2107)
ConsensoPoA / Geth Clique
Coin nativaALFA (18 dec.)
Block time~2 secondi
Tipo reteMainnet
Stato rete
Online
⛓️

1. Architettura di Rete

Alfassa Chain è una blockchain Mainnet EVM-compatibile basata su Geth con algoritmo di consenso Proof of Authority (Clique). Questo modello garantisce blocchi prodotti ogni ~2 secondi, finalità quasi immediata e un ambiente stabile e prevedibile per applicazioni mission-critical.

Essendo pienamente compatibile con l'ecosistema Ethereum, tutti gli strumenti standard — MetaMask, ethers.js, web3.js, Solidity, Hardhat, Foundry — funzionano nativamente senza alcuna modifica.

~2s
Block Time
PoA
Consenso Clique
8455
Chain ID
EVM
Compatibilità

Stack Tecnologico

🖥️ Blockchain Node (Geth)

Percorso: /opt/alfassa-stack/geth. Gestisce il consenso PoA Clique, la validazione dei blocchi e l'esposizione degli endpoint RPC e WebSocket.

🔧 API Chain (Node.js)

Percorso: /opt/alfassa-stack/api. Backend che gestisce token, prezzi, quote swap e sincronizzazione con la factory. Espone endpoint REST pubblici.

🔍 Explorer (Blockscout)

Percorso: /opt/blockscout. Reverse proxy su porta 18766. Accessibile pubblicamente su explorer.alfassa.org.

💱 Swap DEX (Frontend)

Percorso: /opt/alfassa-stack/swap-app. Reverse proxy su porta 3022. DEX proprietario su swap.alfassa.org.

Architettura a Livelli

🌐
Applicazioni
dApp, wallet, plugin
→
🔌
RPC / WS
:9545 / :9555
→
⛓️
Geth Node
PoA Clique
→
📦
Blockchain
Mainnet 8455
🦊

2. Configurazione MetaMask

Per interagire con Alfassa Chain, aggiungi la rete al tuo wallet MetaMask o a qualsiasi wallet EVM-compatibile (Rabby, Trust Wallet, Coinbase Wallet, ecc.).

Parametri di rete
Nome rete: Alfassa Chain Nuovo URL RPC: http://104.248.240.97:9545 Chain ID: 8455 Simbolo: ALFA Block Explorer: https://explorer.alfassa.org

Procedura passo-passo

1
Apri MetaMask e vai su "Aggiungi rete"

Clicca sull'icona del selettore reti in alto, poi su "Aggiungi rete" → "Aggiungi rete manualmente".

2
Inserisci i parametri di rete

Compila tutti i campi con i dati riportati sopra. Il Chain ID 8455 identifica univocamente Alfassa Chain.

3
Salva e seleziona la rete

Clicca "Salva". MetaMask passerà automaticamente ad Alfassa Chain e mostrerà il saldo in ALFA.

4
Importa i token ERC-20

Vai su "Importa token" e incolla l'indirizzo del contratto (es. FHM). MetaMask compilerà automaticamente simbolo e decimali.

💡
Stesso indirizzo su tutte le chain EVM Il tuo indirizzo 0x... su Alfassa Chain è identico a quello che usi su Ethereum, Polygon o BSC. Puoi usare lo stesso wallet senza creare nuovi account.
🌱

3. Ecosistema e Token

L'ecosistema Alfassa Chain supporta nativamente lo standard ERC-20 e include un DEX proprietario per lo swap dei token, con un sistema di pricing gestito via database e backend Node.js.

Token presenti sulla rete

Token Tipo Decimali Descrizione
ALFA Coin Nativa 18 Coin base della rete. Utilizzata per le gas fee e le transazioni principali.
FHM ERC-20 18 Token dell'ecosistema Fondazione Homo Novus.
ALX ERC-20 18 Token di utilità dell'ecosistema Alfassa.
SCK ERC-20 18 Token presente sulla rete (test/utility).

Factory e Liquidity Pool

Factory Principale 0x28B2fcBaF0547f2a9d669c74750503b52AD5bf86
Factory Legacy 0x1A0358289bC3DFADc53f865e4B2C1272503551D2
Architettura DEX Router → Factory → Pair (LP)
Logica Prezzo amountOut = (amountIn × valueIn) / valueOut

Database del Sistema Prezzi

Il backend Node.js gestisce i prezzi tramite un database relazionale con le seguenti tabelle principali:

📋 tokens

Registra address, name, symbol, decimals, active. Fonte di verità per tutti i token sulla rete.

💰 token_rates

Contiene token_address, eur_value, updated_by, created_at. Aggiornata dal backend o manualmente dall'admin.

🔁 swap_quotes

Storico delle quote: token_in, token_out, amount_in, amount_out. Utile per analytics e audit.

🔌

4. Endpoints e API

Porte locali e servizi

ServizioPorta LocaleDominio Pubblico
RPC (Geth)9545http://104.248.240.97:9545
WebSocket (Geth)9555ws://104.248.240.97:9555
Explorer Backend18765—
Explorer Frontend18766explorer.alfassa.org
Swap DEX3022swap.alfassa.org
API Chain—apichain.alfassa.org
Admin Panel—admin.alfassa.org (in sviluppo)

API Chain — Endpoint Pubblici

L'API Chain espone endpoint REST per la lettura dei prezzi e il calcolo delle quote swap, utilizzabili da qualsiasi applicazione esterna.

REST API
// Lista prezzi correnti di tutti i token GET https://apichain.alfassa.org/public/prices/current // Prezzo di un token specifico per indirizzo GET https://apichain.alfassa.org/public/prices/current/:address // Calcolo quota swap POST https://apichain.alfassa.org/public/quote Body: { "tokenIn": "0x...", "tokenOut": "0x...", "amountIn": "1000000000000000000" }

Test di connessione RPC

Terminal (curl)
curl -X POST http://104.248.240.97:9545 \ -H "Content-Type: application/json" \ --data '{"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":1}' // Risposta attesa — Chain ID 8455 in hex = 0x2107 { "jsonrpc": "2.0", "id": 1, "result": "0x2107" }
📜

5. Smart Contract su Alfassa Chain

Su Alfassa Chain si deployano smart contract Solidity standard, identici a quelli di Ethereum. Il compilatore, i test con Hardhat/Foundry e le librerie OpenZeppelin funzionano senza modifiche.

Deploy con Hardhat

hardhat.config.ts
import { HardhatUserConfig } from "hardhat/config"; const config: HardhatUserConfig = { networks: { alfassachain: { url: "http://104.248.240.97:9545", chainId: 8455, accounts: [process.env.DEPLOYER_PRIVATE_KEY!] } }, solidity: "0.8.24" }; // npx hardhat run scripts/deploy.ts --network alfassachain

Deploy con Foundry

foundry.toml
[profile.default] src = "src" out = "out" libs = ["lib"] [rpc_endpoints] alfassa = "http://104.248.240.97:9545" // forge create --rpc-url alfassa --private-key $PK src/MyContract.sol:MyContract

Contratti ERC-20 personalizzati

AlfaToken.sol

Contratto base per token ERC-20 standard. Supporta mint, burn e transfer. Compatibile con la factory del DEX per la creazione di liquidity pool.

ERC-20 Standard
AlfaNFT.sol

Contratto ERC-721 per NFT. Utilizzabile per credenziali digitali, membership, certificati o asset di gioco nell'ecosistema Alfassa.

ERC-721 NFT
AlfaVesting.sol

Contratto di vesting per la distribuzione programmata di token nel tempo. Utile per team allocation, investor rounds e reward programs.

Vesting & Lock
AlfaMultisig.sol

Wallet multi-firma per la gestione sicura dei fondi della treasury. Richiede M-of-N firme per eseguire transazioni critiche.

Governance
AlfaStaking.sol

Contratto di staking per permettere agli utenti di bloccare ALFA o altri token ERC-20 e ricevere ricompense nel tempo.

DeFi / Staking
AlfaPayment.sol

Contratto per pagamenti on-chain con split automatico, commissioni e ricevute verificabili. Ideale per e-commerce e marketplace.

Payments
🛡️

6. Sicurezza

⚠️
Regola d'oro Nessun membro del team Alfassa ti chiederà mai seed phrase o private key. Mai. Per nessun motivo. Qualsiasi richiesta di questo tipo è una truffa.
  • Non condividere mai la seed phrase — con nessuno, in nessun contesto, nemmeno con il supporto tecnico.
  • Non condividere mai la private key — né via chat, né via email, né tramite form online.
  • Controlla sempre l'indirizzo destinatario — verifica almeno le prime e ultime 6 cifre prima di ogni invio.
  • Usa solo i domini ufficiali — alfassa.org e i suoi sottodomini verificati.
  • Non firmare transazioni che non capisci — se una dApp chiede autorizzazioni insolite, rifiuta e segnala.
  • Primo invio sempre di test — usa un importo minimo per verificare che l'indirizzo sia corretto.
  • Tieni aggiornato MetaMask — le versioni recenti includono protezioni anti-phishing.

★ Integrazioni: dApp, Plugin e Sistemi

Alfassa Chain è progettata per essere il livello blockchain (Layer 1) per una vasta gamma di applicazioni. Grazie alla piena compatibilità EVM, qualsiasi sistema che supporta Ethereum può essere connesso ad Alfassa Chain con modifiche minime. Di seguito trovi guide dettagliate per ogni tipologia di integrazione.

7.1 — dApp Web3
🌐
dApp Decentralizzata (React / Vue / Next.js)
Frontend Web3 con connessione diretta alla chain
ethers.js v6 wagmi viem React Next.js WalletConnect

Una dApp può connettersi ad Alfassa Chain tramite il provider RPC o tramite il wallet dell'utente (MetaMask). La libreria consigliata è ethers.js v6 o il moderno stack wagmi + viem. Il flusso tipico prevede: connessione wallet → lettura dati on-chain → firma e invio transazioni.

JavaScript — Connessione con ethers.js v6
import { ethers } from 'ethers'; // Provider RPC diretto (sola lettura) const provider = new ethers.JsonRpcProvider('http://104.248.240.97:9545'); // Provider via MetaMask (lettura + scrittura) const browserProvider = new ethers.BrowserProvider(window.ethereum); await browserProvider.send('eth_requestAccounts', []); const signer = await browserProvider.getSigner(); // Lettura saldo ALFA const balance = await provider.getBalance(await signer.getAddress()); console.log('Saldo ALFA:', ethers.formatEther(balance));
Configurazione wagmi (React)
import { createConfig, http } from 'wagmi'; import { defineChain } from 'viem'; const alfassaChain = defineChain({ id: 8455, name: 'Alfassa Chain', nativeCurrency: { name: 'Alfa', symbol: 'ALFA', decimals: 18 }, rpcUrls: { default: { http: ['http://104.248.240.97:9545'] }, public: { http: ['http://104.248.240.97:9545'] }, }, blockExplorers: { default: { name: 'Alfassa Explorer', url: 'https://explorer.alfassa.org' } } }); export const config = createConfig({ chains: [alfassaChain], transports: { [alfassaChain.id]: http() } });
✅
Compatibilità WalletConnect Alfassa Chain è compatibile con WalletConnect v2. Gli utenti possono connettere wallet mobile (Trust Wallet, Rainbow, ecc.) scansionando il QR code dalla dApp.
7.2 — Plugin WordPress
🔌
Plugin WordPress — Wallet Web3
Wallet ALFA integrato nel sito WordPress dell'utente
PHP WordPress ethers.js MetaMask Clone REST API WP

Un plugin WordPress può integrare un wallet Web3 completo, permettendo agli utenti registrati di gestire i propri ALFA e token ERC-20 direttamente dal sito. Il plugin deve essere pre-configurato con Alfassa Chain (Chain ID 8455) come rete di default non modificabile dagli utenti base. Le chiavi private vengono cifrate nel browser e nel profilo utente WordPress.

Architettura del Plugin

🖥️ Frontend (JS)

Shortcode [alfassa_wallet] che carica un'interfaccia React/Vue nel frontend. Gestisce connessione wallet, saldo, invio e ricezione token.

⚙️ Backend (PHP)

REST API WordPress per la gestione sicura dei dati utente. Salva configurazioni nel DB WP. Pagina admin stand-alone per la configurazione avanzata.

🔐 Sicurezza

Chiavi private cifrate con AES-256 nel localStorage + profilo utente WP. Solo gli admin possono aggiungere nuove reti o modificare i token di default.

🪙 Token Pre-caricati

Il token FHM è pre-caricato di default con la sua icona ufficiale. Gli admin possono aggiungere altri contratti ERC-20 dal pannello di controllo.

PHP — Registrazione REST API
// functions.php del plugin add_action('rest_api_init', function() { register_rest_route('alfassa/v1', '/wallet/(?P<user_id>\d+)', [ 'methods' => 'GET', 'callback' => 'alfassa_get_wallet_data', 'permission_callback' => 'is_user_logged_in' ]); }); function alfassa_get_wallet_data($request) { $user_id = $request['user_id']; $address = get_user_meta($user_id, 'alfassa_wallet_address', true); return rest_ensure_response([ 'address' => $address, 'chainId' => 8455, 'rpc' => 'http://104.248.240.97:9545' ]); }
🔧
Pagina Admin Stand-alone Il plugin deve includere una pagina di configurazione accessibile all'URL /wp-admin/admin.php?page=alfassa-chain con un link visibile nel menu laterale di WordPress. La pagina non deve mostrare header/footer del tema.
📝
Plugin WordPress — Login Web3 (Sign-In with Ethereum)
Autenticazione tramite firma crittografica del wallet
SIWE WordPress Auth ethers.js

Permette agli utenti di accedere al sito WordPress firmando un messaggio con il loro wallet Alfassa Chain, senza username e password. Il backend PHP verifica la firma crittografica e crea/aggiorna la sessione WordPress.

JavaScript — Firma messaggio SIWE
const message = `Accedi ad Alfassa\nNonce: ${nonce}\nTimestamp: ${Date.now()}`; const signature = await signer.signMessage(message); // Invia firma al backend WordPress per verifica await fetch('/wp-json/alfassa/v1/auth', { method: 'POST', body: JSON.stringify({ message, signature, address }) });
7.3 — E-Commerce e Pagamenti
🛒
WooCommerce — Pagamenti in ALFA / Token ERC-20
Gateway di pagamento crypto per WooCommerce
WooCommerce WordPress Smart Contract Gateway

Un gateway WooCommerce personalizzato permette ai clienti di pagare ordini in ALFA o in qualsiasi token ERC-20 presente su Alfassa Chain. Il flusso prevede: generazione indirizzo di pagamento → monitoraggio transazione on-chain → conferma ordine automatica.

1
Generazione indirizzo e importo

Il gateway calcola l'importo in ALFA usando l'API prezzi (/public/prices/current) e mostra l'indirizzo del merchant con il QR code.

2
Monitoraggio transazione

Il backend PHP interroga l'API Chain o il nodo RPC tramite WebSocket per rilevare la transazione in arrivo entro un timeout configurabile.

3
Conferma e fulfillment

Una volta confermata la transazione on-chain, WooCommerce aggiorna automaticamente lo stato dell'ordine e avvia il processo di evasione.

PHP — Monitoraggio via RPC
// Verifica transazione ricevuta $response = wp_remote_post('http://104.248.240.97:9545', [ 'body' => json_encode([ 'jsonrpc' => '2.0', 'method' => 'eth_getBalance', 'params' => [$merchant_address, 'latest'], 'id' => 1 ]) ]); $data = json_decode(wp_remote_retrieve_body($response)); $balance_wei = hexdec($data->result);
7.4 — Backend, Bot e Automazioni
🤖
Bot di Trading e Automazioni Node.js / Python
Script server-side per interazioni programmatiche con la chain
Node.js Python ethers.js web3.py Cron Job

Backend e bot possono interagire con Alfassa Chain per automatizzare operazioni come swap periodici, distribuzione di reward, monitoraggio eventi on-chain e aggiornamento prezzi.

Node.js — Invio transazione
const { ethers } = require('ethers'); const provider = new ethers.JsonRpcProvider( 'http://104.248.240.97:9545' ); const wallet = new ethers.Wallet( process.env.PRIVATE_KEY, provider ); const tx = await wallet.sendTransaction({ to: '0xDestinatario...', value: ethers.parseEther('1.0') }); await tx.wait();
Python — Lettura prezzi API
import requests # Lettura prezzi correnti res = requests.get( 'https://apichain.alfassa.org' '/public/prices/current' ) prices = res.json() # Calcolo quota swap quote = requests.post( 'https://apichain.alfassa.org' '/public/quote', json={ 'tokenIn': '0x...', 'tokenOut': '0x...', 'amountIn': '1000000000000000000' } )

Ascolto eventi WebSocket

Node.js — Listener eventi on-chain
const wsProvider = new ethers.WebSocketProvider( 'ws://104.248.240.97:9555' ); // Ascolta nuovi blocchi in tempo reale wsProvider.on('block', (blockNumber) => { console.log('Nuovo blocco:', blockNumber); }); // Ascolta eventi di un contratto ERC-20 const contract = new ethers.Contract(TOKEN_ADDRESS, ERC20_ABI, wsProvider); contract.on('Transfer', (from, to, amount) => { console.log(`Transfer: ${from} → ${to}: ${ethers.formatEther(amount)} token`); });
7.5 — App Mobile (iOS / Android)
📱
App Mobile React Native / Flutter
Wallet e dApp mobile native per iOS e Android
React Native Flutter ethers.js WalletConnect v2 Expo

Le app mobile possono connettersi ad Alfassa Chain tramite il provider RPC HTTP. Per la gestione sicura delle chiavi private su mobile si consiglia l'uso di Secure Enclave (iOS) o Android Keystore, oppure librerie come ethers.js con storage cifrato.

🔑 Gestione Chiavi

Usa expo-secure-store (React Native) o flutter_secure_storage (Flutter) per salvare chiavi private in modo sicuro nel keychain del dispositivo.

🔗 Connessione WalletConnect

Integra WalletConnect v2 per permettere agli utenti di connettere la tua app mobile come wallet a qualsiasi dApp desktop tramite QR code.

📊 Lettura Dati

Usa le API REST di apichain.alfassa.org per prezzi e quote. Per dati on-chain usa il provider RPC HTTP (non WebSocket per compatibilità mobile).

🔔 Notifiche Push

Combina un backend Node.js che ascolta eventi WebSocket on-chain con Firebase Cloud Messaging per inviare notifiche push all'app mobile.

7.6 — Oracoli e Price Feed
🔮
Oracolo On-Chain per Prezzi Esterni
Portare dati del mondo reale sulla blockchain
Oracle Pattern Solidity Node.js Keeper Price Feed

Un oracolo permette agli smart contract su Alfassa Chain di accedere a dati esterni (prezzi EUR/USD, risultati sportivi, dati meteo, ecc.). L'architettura consigliata prevede un contratto AlfaOracle.sol on-chain e un keeper Node.js off-chain che aggiorna i dati periodicamente.

Solidity — Contratto Oracolo
// SPDX-License-Identifier: MIT pragma solidity ^0.8.24; contract AlfaOracle { address public keeper; mapping(bytes32 => uint256) public prices; mapping(bytes32 => uint256) public updatedAt; event PriceUpdated(bytes32 indexed pair, uint256 price); modifier onlyKeeper() { require(msg.sender == keeper, "Not keeper"); _; } function updatePrice(bytes32 pair, uint256 price) external onlyKeeper { prices[pair] = price; updatedAt[pair] = block.timestamp; emit PriceUpdated(pair, price); } }
🔮
Integrazione con l'API Chain Il keeper Node.js può leggere i prezzi direttamente dall'API Chain (/public/prices/current) e scriverli on-chain tramite il contratto oracolo, creando un bridge tra il sistema di pricing off-chain e gli smart contract.
7.7 — Sistemi Aziendali (ERP / CRM / SaaS)
🏢
Integrazione ERP / CRM / Sistemi Gestionali
Connettere software aziendali alla blockchain
ERP CRM REST API Webhook Middleware

Sistemi aziendali come ERP (SAP, Odoo, Gestionale1) o CRM (Salesforce, HubSpot) possono integrarsi con Alfassa Chain tramite un middleware REST che funge da bridge tra il sistema legacy e la blockchain. Questo permette di registrare fatture, contratti e pagamenti in modo immutabile on-chain.

📄 Registrazione Documenti

Calcola l'hash SHA-256 di fatture o contratti e registralo on-chain tramite un contratto di notarizzazione. Prova di esistenza immutabile e verificabile.

💸 Pagamenti B2B

Automatizza i pagamenti tra aziende in ALFA o token ERC-20. Il contratto AlfaPayment.sol gestisce split automatici e ricevute on-chain.

🎫 Tokenizzazione Asset

Rappresenta asset aziendali (crediti, quote, diritti) come token ERC-20 o NFT su Alfassa Chain per una gestione trasparente e trasferibile.

Middleware — Notarizzazione documento
const crypto = require('crypto'); const { ethers } = require('ethers'); // 1. Calcola hash del documento const docHash = crypto.createHash('sha256') .update(documentBuffer).digest('hex'); // 2. Registra hash on-chain const provider = new ethers.JsonRpcProvider('http://104.248.240.97:9545'); const wallet = new ethers.Wallet(process.env.PRIVATE_KEY, provider); const notary = new ethers.Contract(NOTARY_ADDRESS, NOTARY_ABI, wallet); const tx = await notary.register(`0x${docHash}`); await tx.wait(); console.log('Documento registrato on-chain:', tx.hash);
Riepilogo Integrazioni
Tipologia Tecnologie Endpoint Principale Difficoltà
dApp Web3 ethers.js, wagmi, viem RPC :9545 Bassa
Plugin WordPress (Wallet) PHP, ethers.js, WP REST API RPC :9545 + API Chain Media
Plugin WordPress (Login) PHP, SIWE, ethers.js RPC :9545 Bassa
WooCommerce Gateway PHP, WooCommerce, RPC RPC :9545 + API Chain Media
Bot / Automazioni Node.js, Python, web3.py RPC :9545 + WS :9555 Media
App Mobile React Native, Flutter RPC :9545 + API Chain Media
Oracolo On-Chain Solidity, Node.js Keeper RPC :9545 + API Chain Alta
ERP / CRM / SaaS REST Middleware, qualsiasi linguaggio RPC :9545 + API Chain Media
🚀
Pronto per la produzione La blockchain, l'Explorer, lo Swap DEX e le API Chain sono già online e funzionanti su Mainnet. Puoi iniziare a deployare smart contract e integrare i tuoi sistemi oggi stesso. Per supporto tecnico, contatta il team Alfassa tramite i canali ufficiali.