Primera Transacción

En este momento crucial de tu viaje con KodeChain, llega el instante en que dejas de ser un observador para convertirte en un participante activo de la red. Esta guía te acompaña paso a paso a través de tu primera transacción, revelando cómo el código que has estado ejecutando cobra vida en una transferencia real de valor.

Requisitos Previos

• Nodo sincronizado ✅ - Tu instancia debe estar conectada y actualizada con la red
• Wallet generada ✅ - Tus claves post-cuánticas listas para firmar transacciones
• Tokens KDC - Fondos disponibles en testnet o mainnet para transferir

Verificar Estado del Nodo

Antes de enviar transacciones, es crucial verificar que tu nodo esté completamente sincronizado con la red, ya que solo un nodo actualizado puede procesar transacciones válidas:

curl http://localhost:8545/api/blockchain/status

Esta llamada a la API REST de tu nodo revela el estado interno del sistema blockchain:

{
  "status": "synced",
  "current_height": 15432,
  "latest_hash": "0x123abc...",
  "peer_count": 12,
  "consensus_type": "dpos"
}

Los números revelan la salud de tu participación: la altura actual muestra cuántos bloques has procesado, el conteo de peers indica tu conectividad P2P, y el tipo de consenso confirma qué algoritmo de validación estás utilizando.

Paso 1: Obtener Tu Address

Desde Keystore

Tu dirección es la identidad pública derivada de tus claves post-cuánticas ML-DSA-65:

# Ver tu address
cat ~/.kodechain/keystore/keystore-*.json | jq -r '.address'

Ejemplo de output:

0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb1

Esta dirección hexadecimal es lo que usarás para recibir fondos y firmar transacciones.

Crear Nueva Wallet

Si aún no tienes una wallet, el proceso de generación crea claves resistentes a ataques cuánticos:

cd handlers
make generate

Este comando ejecuta el código en handlers/validator_key_generator.go, generando:

• keystore-[timestamp].json - Tu clave privada encriptada con algoritmos post-cuánticos
• deposit_data-[timestamp].json - Los datos necesarios para staking y validación
• withdrawal_credentials.json - Las credenciales para retirar fondos de staking

Paso 2: Obtener Fondos

Testnet

Solicita tokens en el canal #faucet de Discord:

!faucet 0xTuAddress

Mainnet

Compra KDC en un exchange o recíbelos de otro usuario.

Paso 3: Verificar Balance

curl http://localhost:8545/api/blockchain/balance/0xTuAddress

Respuesta:

{
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb1",
  "balance": "1000000000000000000000",
  "balance_kdc": "1000.0",
  "nonce": 0
}

Paso 4: Preparar Transacción

Estructura Básica de Transacción

{
  "from": "0xSenderAddress",
  "to": "0xRecipientAddress",
  "amount": "1000000000000000000",
  "gas_limit": 21000,
  "gas_price": "1000000000",
  "nonce": 0,
  "data": ""
}

Conversión de Unidades

KodeChain usa 18 decimales:

1 KDC = 1,000,000,000,000,000,000 wei

Ejemplos:

• 1 KDC = 1000000000000000000 wei
• 0.5 KDC = 500000000000000000 wei
• 0.1 KDC = 100000000000000000 wei
• 0.01 KDC = 10000000000000000 wei

Paso 5: Firmar y Enviar Transacción

Método 1: API REST

curl -X POST http://localhost:8545/api/transactions/send \
  -H "Content-Type: application/json" \
  -d '{
    "from": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb1",
    "to": "0x1234567890123456789012345678901234567890",
    "amount": "1000000000000000000",
    "gas_limit": 21000,
    "private_key": "tu_clave_privada_aqui"
  }'

IMPORTANTE: Nunca expongas tu clave privada. En producción, usa un servicio de firma seguro.

Respuesta:

{
  "success": true,
  "tx_hash": "0xabc123...",
  "message": "Transaction submitted successfully"
}

Método 2: Firma Offline (Más Seguro)

1. Crear Transacción Sin Firmar

curl -X POST http://localhost:8545/api/transactions/create \
  -H "Content-Type: application/json" \
  -d '{
    "from": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb1",
    "to": "0x1234567890123456789012345678901234567890",
    "amount": "1000000000000000000",
    "gas_limit": 21000
  }'

Respuesta:

{
  "unsigned_tx": {
    "from": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb1",
    "to": "0x1234567890123456789012345678901234567890",
    "amount": "1000000000000000000",
    "gas_limit": 21000,
    "gas_price": "1000000000",
    "nonce": 0,
    "data": ""
  },
  "hash": "0xdef456..."
}

2. Firmar Offline

Usa tu herramienta de firma preferida para firmar el hash.

3. Enviar Transacción Firmada

curl -X POST http://localhost:8545/api/transactions/submit \
  -H "Content-Type: application/json" \
  -d '{
    "unsigned_tx": {...},
    "signature": "0xsignature..."
  }'

Paso 6: Verificar Transacción

Por Hash

curl http://localhost:8545/api/transactions/0xabc123...

Respuesta:

{
  "hash": "0xabc123...",
  "from": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb1",
  "to": "0x1234567890123456789012345678901234567890",
  "amount": "1000000000000000000",
  "status": "confirmed",
  "block_number": 15433,
  "timestamp": "2025-11-02T10:30:00Z",
  "gas_used": 21000,
  "fee": "21000000000000"
}

Estados de Transacción

• pending: En mempool, esperando inclusión
• confirmed: Incluida en bloque
• failed: Transacción falló (reverted)

Monitorear en Tiempo Real

# Esperar hasta confirmación
while true; do
  STATUS=$(curl -s http://localhost:8545/api/transactions/0xabc123... | jq -r '.status')
  echo "Estado: $STATUS"
  if [ "$STATUS" = "confirmed" ]; then
    break
  fi
  sleep 3
done
echo "¡Transacción confirmada!"

Paso 7: Verificar Nuevo Balance

# Tu balance
curl http://localhost:8545/api/blockchain/balance/0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb1

# Balance del receptor
curl http://localhost:8545/api/blockchain/balance/0x1234567890123456789012345678901234567890

Tipos de Transacciones

1. Transferencia Simple

{
  "type": "TRANSFER",
  "from": "0xSender",
  "to": "0xRecipient",
  "amount": "1000000000000000000"
}

2. Deploy de Contrato

{
  "type": "DEPLOY_CONTRACT",
  "from": "0xSender",
  "data": "0x608060405234801561001057600080fd5b50...",
  "gas_limit": 3000000
}

3. Llamada a Contrato

{
  "type": "CALL_CONTRACT",
  "from": "0xSender",
  "to": "0xContractAddress",
  "data": "0xa9059cbb000000000000000000000000...",
  "gas_limit": 100000
}

4. Stake

{
  "type": "STAKE",
  "from": "0xValidator",
  "amount": "10000000000000000000"
}

Cálculo de Fees

Gas Estimado por Tipo

Tipo de Transacción	Gas Estimado
Transferencia Simple	21,000
Deploy Contrato	2,000,000+
Llamada Contrato	50,000-500,000
Stake	100,000

Fórmula de Fee

Total Fee = Gas Used × Gas Price

Ejemplo:

Gas Used = 21,000
Gas Price = 1 Gwei = 1,000,000,000 wei
Total Fee = 21,000 × 1,000,000,000 = 21,000,000,000,000 wei = 0.000021 KDC

Estimar Gas

curl -X POST http://localhost:8545/api/transactions/estimate-gas \
  -H "Content-Type: application/json" \
  -d '{
    "from": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb1",
    "to": "0x1234567890123456789012345678901234567890",
    "amount": "1000000000000000000"
  }'

Respuesta:

{
  "gas_estimate": 21000,
  "gas_price": "1000000000",
  "estimated_fee": "21000000000000",
  "estimated_fee_kdc": "0.000021"
}

Transacciones Avanzadas

Batch Transactions

Enviar múltiples transacciones de una vez:

curl -X POST http://localhost:8545/api/transactions/batch \
  -H "Content-Type: application/json" \
  -d '{
    "transactions": [
      {
        "from": "0xSender",
        "to": "0xRecipient1",
        "amount": "1000000000000000000"
      },
      {
        "from": "0xSender",
        "to": "0xRecipient2",
        "amount": "2000000000000000000"
      }
    ],
    "private_key": "tu_clave_privada"
  }'

Transacción con Data

Para interactuar con contratos:

curl -X POST http://localhost:8545/api/transactions/send \
  -H "Content-Type: application/json" \
  -d '{
    "from": "0xSender",
    "to": "0xContractAddress",
    "amount": "0",
    "data": "0xa9059cbb0000000000000000000000001234567890123456789012345678901234567890000000000000000000000000000000000000000000000000000000000000000a",
    "gas_limit": 100000,
    "private_key": "tu_clave_privada"
  }'

Solución de Problemas

Error: "insufficient funds"

# Verificar balance
curl http://localhost:8545/api/blockchain/balance/0xTuAddress

# Asegúrate de tener suficiente para amount + fee

Error: "nonce too low"

# Obtener nonce correcto
curl http://localhost:8545/api/blockchain/nonce/0xTuAddress

# Usar nonce retornado en siguiente transacción

Error: "gas limit exceeded"

# Estimar gas primero
curl -X POST http://localhost:8545/api/transactions/estimate-gas \
  -H "Content-Type: application/json" \
  -d '{...}'

# Usar gas_estimate + 20% de buffer

Transacción Pendiente por Mucho Tiempo

# Ver estado de mempool
curl http://localhost:8545/api/mempool/stats

# Verificar que nodo esté sincronizado
curl http://localhost:8545/api/blockchain/status

# Aumentar gas_price y reenviar

Próximos Pasos

1. 💻 Aprende a crear contratos inteligentes
2. 🔐 Conviértete en validador
3. 💰 Explora el sistema de staking
4. 🌐 Entiende el sistema de consenso

---

¡Felicidades! Has completado tu primera transacción en KodeChain 🎉