Tropico Wallet 🌴

🏆 Dev3pack Global Hackathon 2026 — #1 Venezuela · #28 Global · #10 LatAm (de 386 proyectos)

Infraestructura abierta de pagos: tu plata vive en USDC, pagás en bolívares al instante, sin intermediarios bancarios.

Tropico es la primera wallet non-custodial en Solana que cierra el círculo entre cripto y el sistema de pagos venezolano. Tu patrimonio vive en USDC/SOL, y cuando necesitás pagar a un comercio, Tropico convierte al instante a bolívares vía Pago Móvil VE — sin abrir cuentas en otro país, sin hacer P2P en una exchange, sin esperar 30 minutos.

El moat técnico es BsX: un protocolo open-source en Solana que actúa como rail JIT (just-in-time) entre USDC y el sistema bancario local. El mismo protocolo escala a otras monedas LatAm (ARS, COP, CUP, PEN) — Venezuela es el primer mercado, no el único.

---

Demo rápido (para jueces)

Demo live: https://tropico-rho.vercel.app

1. Login con email → Privy crea wallet Solana embedded en 15 segundos
2. En /home → botón "Modo demo · devnet" → fondear con faucets públicos (SOL + USDC devnet)
3. /cambiar tab Bolívares → flujo BsX: depositá USDC, recibís BsX a la tasa del día
4. /pagar-servicios → Pago Móvil VE: escaneá QR Suiche7B o ingresá datos manual
5. /guacama → preguntá "¿cuánto vale el dólar hoy?" o "cobrale $5 a Juan en BsX"

Detalle completo: docs/JUDGE_DEMO_GUIDE.md

---

Quick start

# 1. Clonar
git clone https://github.com/[tu-usuario]/Tropico.git tropico
cd tropico

# 2. Instalar dependencias
npm install

# 3. Configurar variables de entorno
cp .env.example .env.local
# Editar .env.local con tus keys (ver sección Variables de entorno)

# 4. Levantar dev server
npm run dev
# → http://localhost:3000

Sin ninguna key, la app corre en modo demo con mocks honestos y banners explícitos. Guacama AI usa smart fallback (sin LLM real). Ningún flow visual queda roto.

Variables de entorno

# Privy — wallet MPC embedded
NEXT_PUBLIC_PRIVY_APP_ID=

# Helius — RPC de Solana
NEXT_PUBLIC_HELIUS_RPC=https://mainnet.helius-rpc.com/?api-key=YOUR_KEY
HELIUS_API_KEY=

# Guacama AI — LLM (elige uno)
GOOGLE_GENERATIVE_AI_API_KEY=   # Gemini 2.0 Flash
# DEEPSEEK_API_KEY=              # alternativa más barata

# Fee accounts de Tropico
NEXT_PUBLIC_TROPICO_FEE_OWNER=
NEXT_PUBLIC_TROPICO_FEE_ATA_USDC=
NEXT_PUBLIC_TROPICO_FEE_ATA_SOL=
NEXT_PUBLIC_TROPICO_FEE_ATA_USDT=

# Cluster
NEXT_PUBLIC_SOLANA_CLUSTER=mainnet-beta

---

Arquitectura

CAPAS DE TROPICO
═══════════════════════════════════════════════════════════════════

CAPA PROTOCOLO (Solana programs / Anchor)
  programs/tropico_bs/          ← BsX: mint/burn/attest/oracle
  programs/tropico_treasury/    ← registro on-chain de fees (audit)

CAPA INTEGRACIÓN (bridges)
  lib/tropico-bs-bridge.ts      ← USDC → Bs → Pago Móvil VE
  lib/suiche7b-parser.ts        ← QR Suiche7B (formato bancario VE)
  lib/jupiter.ts                ← swap Jupiter v6 platformFeeBps=50
  lib/solana-pay.ts             ← Solana Pay + durable nonces offline

CAPA AGENTE (Lumen runtime + Guacama)
  lumen-kit/                    ← KIT + 7 SKILLS declarativas (Lumen)
  lumen-capabilities/           ← scripts Python ejecutables (Lumen)
  lib/guacama-prompt.ts          ← system prompt Guacama AI
  app/api/guacama/               ← proxy LLM (DeepSeek / Gemini / fallback)

CAPA APLICACIÓN
  app/ (Next.js 15 App Router)  ← 9 módulos consumer + merchant
  lib/i18n/                     ← 4 idiomas (es/en/pt/fr)

WALLET / AUTH
  Privy MPC embedded            ← login email, non-custodial real
  Solana Wallet Adapter         ← Phantom / Solflare fallback

Ver docs/ARCHITECTURE.md para diagramas detallados y descripción de cada módulo.

---

BsX — el rail JIT

programs/tropico_bs/ es el programa Anchor que actúa como rail just-in-time entre USDC y el sistema bancario local. BsX no es un instrumento de hold — es un token transitorio que existe solo durante la ventana del pago (segundos), para que el patrimonio del usuario nunca se devalúe en bolívares.

Instrucción	Qué hace
initialize(peg_rate)	crea PDAs del protocolo, delega mint authority
update_peg(new_rate)	oracle_authority actualiza la tasa del día
mint_bsx(usdc_amount)	mint JIT — usuario quema USDC al momento de pagar
burn_bsx(bsx_amount)	redime BsX no usados → USDC de vuelta
attest_reserves()	cualquiera escribe snapshot on-chain (usdc_reserves, bsx_supply)
set_pause(paused)	admin pausa/reactiva en emergencias

Matemática: bsx = usdc * peg_rate / 1_000_000. La tasa default es la oficial; el usuario puede activar tasas alternativas como configuración opt-in. El mismo protocolo escala a ARS, COP, CUP, PEN — Venezuela es el primer mercado, no el único.

Spec completa: docs/PROTOCOL_BSX.md

---

Módulos principales (25 rutas)

#	Módulo	URL	Qué hace
1	Wallet / Home	/home	Saldo on-chain real (USDC/SOL/SPL) via Helius + acciones rápidas
2	Cambiar	/cambiar	Tab Bolívares: USDC → BsX JIT al momento de pagar. Tab Tokens: Jupiter v6 (platformFeeBps=50)
3	Cobrar	/cobrar	QR Solana Pay client-side, fee 1% hacia arriba, merchant recibe monto exacto
4	Enviar	/enviar	P2P directo + claim links compartibles + pago a comercio con QR Suiche7B auto FX
5	Guardar	/guardar	Yield ~5-7% APY — mSOL (Marinade) o Kamino
6	Pago Móvil VE	/pagar-servicios	QR Suiche7B + conversión USDC→Bs + Pago Móvil al banco destino en 2-5s
7	Guacama AI	/guacama	Agente venezolano sobre Lumen — 7 capabilities + Modo Agente
8	Remesas	/remesas	On-ramp aggregator (MoonPay/Transak/Ramp/Stripe Crypto)
9	Mi Tropico	/perfil	Avatar, nombre editable, pubkey, cluster, importar wallet
10	Offline	/offline	Firma txs sin conexión con durable nonces de Solana — queue local, sync al reconectar
11	WhatsApp Bot	/guacama/whatsapp	Demo Guacama via WhatsApp Cloud API — comandos de texto, aprobación biométrica on-chain

Módulos auxiliares

Módulo	URL	Qué hace
Descubrir	/descubrir	Catálogo educativo de 9 tokens curados
Claim	/claim/[id]	Receptor de claim links de /enviar
Modo Agente	/guacama/agente	4 acciones autónomas: DCA, auto-yield, cashback, rebalance
Integraciones	/integraciones	Demo Tropico Pay para merchants e integradores
Intercambio P2P	/intercambio-p2p	OTC P2P entre usuarios
Comercios	/comercios	Directorio de comercios afiliados con cashback
Wallet crear/abrir	/wallet/crear, /wallet/abrir	Wallet local cifrada AES-GCM 256 + PBKDF2 100k

---

Guacama AI y Lumen

Lumen (lumen-kit/, lumen-capabilities/) es el runtime de agentes — framework open-source por @gabogabucho. Define personalidad (YAML), skills (markdown), y ejecuta capabilities (scripts Python).

Guacama (lib/guacama-prompt.ts, app/guacama/) es el agente de producto construido sobre Lumen. Habla venezolano, conoce Solana, y tiene reglas inviolables (cero política, cero garantías de rendimientos).

KIT (lumen-kit/kit/)
  personality.yaml  → identidad Guacama: voz VE, reglas, knowledge
        │
        ▼
SKILLS (lumen-kit/skills/)
  tropico-balances  tropico-prices   tropico-swap
  tropico-pay       tropico-yield    tropico-cashback
  tropico-agent-actions
        │
        ▼
CAPABILITIES (lumen-capabilities/)
  precio_bs.py      ← cotización USD/VES real (ve.dolarapi.com)
  precio_usd.py     ← precio token USD (Jupiter Price API v3)
  jupiter_quote.py  ← quote real Jupiter v6 con fee 0.5%
  [+ 5 capabilities pendientes post-hackathon]

Doc completa: docs/GUACAMA_AI.md — docs/LUMEN_INTEGRATION.md

---

Stack técnico

Capa	Tecnología
Framework	Next.js 15 (App Router) + React 19 + Tailwind 3
Wallet	Privy MPC embedded + Solana Wallet Adapter
On-chain	SPL Token, Jupiter v6, Marinade, Kamino
Programs propios	Anchor 0.30.1 — tropico_bs + tropico_treasury
RPC	Helius
AI	DeepSeek-V4 / Gemini 2.0 Flash / smart fallback
Datos VE	ve.dolarapi.com (tasa USD/VES)
State	TanStack Query 5
i18n	custom (es/en/pt/fr), sin librería externa

---

On-chain footprint

Programs propios

Program	Address (devnet)	Estado
tropico_treasury	3a5NkTssAsVaarUPqx4YokNwUcfxHnNebGugrgBBxe8S	implementado, listo para deploy a devnet
tropico_bs	EdWuyZDXao86mTcUSpRVzNXaT9Tb5muU6YGubFhADWdN	implementado, listo para deploy a devnet

Programs públicos usados

Program	Address	Para qué
SPL Token	TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA	transfers USDC, ATAs
Jupiter v6	JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4	swaps
Marinade	MarBmsSgKXdrN1egZf5sqe1TMThczhMLJhTndPfxN1V	yield mSOL
Kamino	KLend2g3cP87fffoy8q1mQqGKjrxjC8boSyAYavgmjD	vaults USDC

TROPI test token (devnet)

Mint:    AbkCW6BA2ZVoTw4Q6M1NvATiZjn2aMS3WvWZQbhRQf6K
Tx mint: 5rnR7yKT7z84awgCfvis4zbv3CDyYkzMUCEiBKJnQnYhNMhxjDbNweDy9kcoqCmBku6JkLcaG1cJxgXMCj7dJB5F

---

Tropico Pay — para merchants e integradores

Cualquier plataforma puede cobrar en USDC sobre Solana con un solo endpoint:

POST /api/checkout/create
{
  "merchantWallet": "Mer7Ghj...",
  "amount": 12.50,
  "tokenSymbol": "USDC",
  "partnerId": "yummy-rides",
  "orderId": "ORD-9182",
  "webhookUrl": "https://api.tuapp.com/webhook/tropico"
}

Devuelve: sessionId, solanaPayUrl, hostedCheckoutUrl, customerPays, merchantReceives. Webhooks firmados con HMAC-SHA256.

Spec completa: docs/INTEGRATION_API.md

---

Modelo de negocio

Stream	Tasa	Mecánica
Swap	0.5%	Jupiter platformFeeBps=50 al ATA de Tropico
Send	0.3%	spread USDC en envíos P2P
Yield	2% del yield	performance fee sobre mSOL/Kamino
Merchant fee	1%	cada cobro QR (cargo al cliente)
Tropico Pay	0.5%	cada checkout de plataforma externa

---

Non-custodial — cómo funciona

Privy MPC divide la clave privada en 3 shares:

Login usuario (email/Google)
  ├── share-1 → dispositivo del usuario (encriptado)
  ├── share-2 → infraestructura Privy (encriptado)
  └── share-3 → guardian backup (encriptado)

La llave privada completa NUNCA existe en ningún servidor.
Para firmar una tx, 2 de 3 shares cooperan sin reconstruirla.

El usuario puede exportar su seed phrase desde /perfil en cualquier momento. Tropico nunca accede a ningún share.

---

Internacionalización

UI disponible en 4 idiomas. Switcher en el header (icono globo):

Idioma	Código	Cobertura
Español venezolano (default)	es	100%
English	en	100%
Português	pt	100%
Français	fr	100%

Implementado custom en lib/i18n/dictionary.ts + lib/i18n/context.tsx. Sin librería externa.

---

Roadmap

Período	Hitos
Post-Colosseum	Deploy tropico_bs mainnet, oracle v2 con Pyth, multi-sig Squads
Q3 2026	WhatsApp Bot en producción (WhatsApp Cloud API), Lumen server real, tool calling, Tropico Pay GA, on-ramp real
Q4 2026	Tropico Card (debit USDC + cashback), Tropico Vaults, bug bounty público
Q1 2027	Expansión LATAM (CO, AR, MX, PE, CL), app React Native, Solana Mobile dApp Store

---

Documentación

Documento	Contenido
docs/PROTOCOL_BSX.md	Spec técnica del protocolo BsX
docs/ARCHITECTURE.md	Arquitectura de componentes
docs/GUACAMA_AI.md	Guacama AI: arquitectura, capabilities, FAQ
docs/LUMEN_INTEGRATION.md	Lumen runtime: setup, deployment, replicabilidad
docs/INTEGRATION_API.md	Spec Tropico Pay: endpoints, webhooks HMAC
docs/ANCHOR_PROGRAM.md	Deploy de los programas Anchor
docs/BLOCKCHAIN_BACKEND.md	Stack on-chain: flows end-to-end
docs/ROADMAP.md	Visión detallada Q3 2026 → Q1 2027
docs/JUDGE_DEMO_GUIDE.md	Guía de demo para jueces

---

License

MIT — ver LICENSE.

---

Tropico no es una wallet. Es la infraestructura abierta de pagos que LatAm necesita — empezando por el bolívar. 🌴