Web3 para el equipo: el mínimo común

Un cliente avisa por soporte: "les envié 1.000 USDC hace un minuto, ya aparece en el explorador, ¿por qué no lo veo en mi saldo?". La persona de soporte mira el explorador de bloques y ve la transacción con un "1 confirmación". El sistema interno todavía no la abona. ¿Quién tiene razón? Los dos, y ese es el problema que resuelve este capítulo: el equipo necesita un vocabulario común y una regla escrita sobre cuándo un depósito ya no puede desaparecer.

Este es el primer módulo de la ruta práctica. No enseña a programar contra una red: el equipo ya domina sus lenguajes y su infraestructura. Explica el mínimo que cualquier persona (desarrollo, operación, soporte, cumplimiento) debe entender antes de mover un activo, y termina con dos entregables: un glosario operativo y una tabla de finalidad por red.

Cuatro palabras que todo el equipo debe usar igual

Volvamos al depósito. El cliente "envió a una dirección". Una dirección es un identificador público, como 0x7E5F…5Bdf en Ethereum, que cualquiera puede usar como destino. Detrás de ella hay una cuenta: un registro en el estado de la red con su saldo y su contador de transacciones. En Ethereum existen cuentas controladas por una llave privada y cuentas controladas por código (contratos). [1] Si quieres ver cómo una llave se convierte en dirección, el capítulo Cuentas, claves y direcciones sin humo lo hace paso a paso.

Una transacción es una orden firmada que cambia ese estado. Incluye destino, valor, datos opcionales, límite de gas, comisiones máximas, la firma y un nonce: un contador que sube de uno en uno con cada transacción de la cuenta emisora. [2] El nonce importa en operación por dos razones. Impide que alguien reenvíe la misma transacción para cobrar dos veces. Y obliga a un orden: si la transacción con nonce 7 se atasca, la 8 espera detrás de ella.

La regla que más cuesta interiorizar es esta: una transacción firmada no se puede revocar. No existe un "cancelar" en el protocolo. Mientras no entre en un bloque, lo único posible es competir con otra transacción del mismo nonce que pague más comisión; una vez dentro de un bloque finalizado, ya no hay vuelta atrás. Por eso todos los controles de este programa (políticas, aprobaciones, listas de destinos) viven antes de la firma, no después.

Comisión: quién paga, cuánto y qué pasa si no alcanza

Ahora el escenario inverso: el equipo de tesorería envía un retiro y el cliente pregunta por qué recibió 999,58 y no 1.000. En las redes públicas, quien envía la transacción paga una comisión para que se procese. En Ethereum se mide en gas, la unidad de trabajo de cómputo, y la paga siempre la cuenta emisora en la moneda nativa de la red (ETH), aunque el activo transferido sea USDC. [2]

La comisión de Ethereum tiene dos partes: una comisión base que la red quema y una propina para el validador que incluye la transacción. El emisor fija un máximo por unidad de gas y un límite de gas; si el precio de mercado sube por encima de su máximo, la transacción queda pendiente. [2] El detalle del cálculo y del recibo está en Una transacción Ethereum por dentro.

Tres consecuencias operativas que el equipo debe convertir en reglas:

• Cada wallet que envía necesita saldo en la moneda nativa. Una wallet con 50.000 USDC y cero ETH no puede mover sus USDC. Alguien debe vigilar y reponer ese saldo.
• El costo de una transacción no es fijo. Depende de la congestión de la red en el momento del envío. Si el producto promete un retiro "sin costo", el negocio absorbe una variable.
• Una transacción atascada bloquea a las siguientes de la misma cuenta. El procedimiento para acelerarla (reemplazarla con el mismo nonce y más comisión) debe estar escrito antes de necesitarlo.

Confirmación no es finalidad

Volvamos al "1 confirmación" que vio soporte. Una confirmación es cada bloque que se añade encima del bloque que contiene la transacción. La transacción incluida en el último bloque tiene una; con cada bloque nuevo suma otra. El riesgo es la reorganización (reorg): la red descarta los bloques más recientes y los sustituye por otros, y una transacción que parecía asentada desaparece o cambia de posición. Circle lo resume así en su documentación: cada confirmación extra hace menos probable un reorg, y el número necesario varía por red. [3]

La finalidad es una garantía más fuerte: el punto a partir del cual revertir la transacción exige romper las reglas de la red, no solo tener mala suerte. Ethereum, desde que usa prueba de participación, divide el tiempo en ranuras de 12 segundos y épocas de 32 ranuras. Cuando validadores con al menos dos tercios del ETH en stake votan por dos puntos de control consecutivos, el anterior queda finalizado; revertirlo obligaría a un atacante a perder al menos un tercio de todo el ETH en stake. [4]

En la práctica, Circle estima esa espera en unos 65 bloques, de 15 a 19 minutos. [10] La propia interfaz de los nodos lo expone: al consultar el estado se puede pedir el bloque latest (el último propuesto), safe (la cabeza segura) o finalized (el último finalizado). [5] Un servicio que acredita depósitos leyendo latest está apostando a que no habrá reorg. El capítulo Indexers, eventos y reorgs muestra cómo indexar sin perder ni duplicar.

Figura 1

Un depósito, de la firma al abono

Fuentes:

[4][5]

Cómo leer esta figura

Cinco cajas en fila conectadas por flechas: firmada (el nodo la recibe), pendiente (en el mempool), incluida (una confirmación), N confirmaciones o bloque safe, y final (bloque finalized). Sobre cada caja una nota: aún se puede sustituir; puede no entrar nunca; un reorg la puede sacar; reorg cada vez menos probable; revertir cuesta stake. Debajo, una banda de color que va de rojo a verde rotulada riesgo de que el saldo desaparezca, de alto a bajo salvo fallo de la red. Abajo, una caja morada, política de abono, con flechas discontinuas hacia las cajas de N confirmaciones y final, y una caja roja que dice la firma no se revoca, solo se compite con otra del mismo nonce.

Descargar SVGDescargar .tex

Código TikZ

Abrir `.tex` en otra pestaña

No todas las redes funcionan así. En las de prueba de trabajo, como Bitcoin, la finalidad es probabilística: nunca llega a ser absoluta, solo cada vez más improbable de revertir. El mecanismo y por qué hace falta consenso para que un pago no se gaste dos veces están en El ataque del doble gasto. Y cualquier tiempo de confirmación supone que la red se comporta con cierta sincronía; qué ocurre cuando no, lo cuenta GST: estabilización global.

Red principal y redes de pruebas

El último concepto evita un error caro y frecuente en equipos nuevos. La red principal (mainnet) es donde los activos tienen valor. Las redes de pruebas (testnets) imitan su funcionamiento con monedas sin valor. En Ethereum, los equipos de clientes mantienen hoy dos: Sepolia, recomendada para probar aplicaciones, y Hoodi, para probar actualizaciones del protocolo y validadores. [6]

La misma documentación desaconseja reutilizar cuentas de mainnet en redes de pruebas y viceversa. [6] Para el equipo eso se traduce en separar ambientes de punta a punta: credenciales de API, llaves, listas de destinos y monitoreo distintos. Los proveedores contratados suelen ofrecer espacios de trabajo separados para pruebas y producción; cuáles exactamente y cómo se aíslan es un punto a validar con cada uno.

Un detalle más: el mismo token puede existir en varias redes. USDC en Ethereum y USDC en Solana son activos distintos en cadenas distintas; enviar por la red equivocada puede perder fondos. Los módulos de stablecoins vuelven sobre este riesgo.

Cómo lo resuelven Fireblocks, BitGo, Kaleido y Circle

Ningún proveedor elimina la decisión de finalidad: la parametrizan. Lo que cambia es dónde se configura y qué evento recibe tu sistema.

Fireblocks documenta una política de control de depósitos y confirmaciones: cada espacio de trabajo tiene una por defecto con un número de confirmaciones por red, y se puede definir una propia. Su guía recomienda bajar el número solo para orígenes conocidos (una cuenta propia, una contraparte de confianza) y no para direcciones externas desconocidas. También permite confirmar manualmente o por API una transacción concreta, lo que la marca como completada de inmediato. [7] Esa capacidad de forzar es útil y peligrosa: quién puede usarla es una decisión de política.

BitGo expone el umbral en el webhook de transferencias: el campo numConfirmations fija cuántas confirmaciones debe alcanzar una transferencia antes de notificar, y 0 equivale a no poner umbral. [8] Kaleido describe su capa de conectores como la que calcula gas, administra nonces y maneja reorgs, con entrega "exactamente una vez"; no encontramos en su documentación pública el umbral de confirmaciones por red, así que queda a validar. [9]

Circle no es proveedor de wallets en este programa, sino emisor de USDC; aun así su documentación es una referencia útil. Para su protocolo de transferencias entre cadenas publica cuántas confirmaciones espera en cada red: en modo estándar, por ejemplo, unos 65 bloques en Ethereum (15 a 19 minutos), 32 en Solana y de 2 a 3 en Polygon PoS. [10] Son los umbrales que el emisor usa para su propio riesgo, no una norma para el tuyo.

Decisiones del módulo y entregables

La decisión que abre este módulo es una sola, pero se aplica a cada red: cuántas confirmaciones, o qué nivel de finalidad, exige el sistema antes de dar un depósito por bueno. Conviene tomarla por red y por tramo de monto, y escribirla en el mismo lugar donde se configura el proveedor.

El primer entregable es el glosario de la sección inicial, en el formato que use el equipo. El segundo es la tabla de finalidad por red. La plantilla siguiente parte de los umbrales que Circle publica como referencia; la columna "Umbral propuesto" la completa el equipo, y toda red sin fuente queda marcada como pendiente.

El siguiente módulo, Llaves: generación, guarda, respaldo y rotación, responde la pregunta que este dejó abierta: si una firma no se revoca, ¿dónde vive la llave que firma y quién puede usarla?