KDA Community Edition • Guía Pact

Anatomía de un Token Pact

Aprende a crear tokens fungibles en Kadena paso a paso. Una guía interactiva para entender cada componente.

01

Estructura General del Módulo

Un token en Pact se organiza dentro de un módulo. Piensa en el módulo como una caja que contiene todo: datos, permisos y funciones. Esta es la estructura jerárquica:

📦 Módulo
Contenedor principal. Define nombre y quién puede actualizarlo (governance).
📋 Schema + Tabla
Define la estructura de datos (balance, guard) y crea la tabla donde se guardan las cuentas.
🔑 Capabilities
Permisos que deben activarse para realizar acciones. Como llaves que abren puertas específicas.
⚙️ Funciones
Acciones que el token puede realizar: transferir, consultar balance, crear cuentas, etc.
02

Conceptos Clave

🛡️

Guard (Guardián)

Define quién puede usar una cuenta. Generalmente es un keyset (conjunto de llaves públicas). Sin el guard correcto, nadie puede mover tus tokens.

🔐

Capability (Permiso)

Un permiso que debe activarse para ejecutar ciertas acciones. El atributo @managed significa que tiene un límite (ej: transferir máx X tokens).

⚠️

Enforce (Verificar)

Verifica que una condición sea verdadera. Si es falsa, aborta toda la transacción. Es la base de la seguridad en Pact.

🗄️

Table (Tabla)

Almacena datos en la blockchain. Cada cuenta tiene un registro con su balance y guard. Similar a una base de datos tradicional.

💡

¿Por qué Capabilities?

Pact usa un modelo de seguridad basado en capacidades. En lugar de verificar permisos dentro de cada función, se "activan" los permisos necesarios al inicio y las funciones internas verifican que estén activos. Esto hace el código más seguro y fácil de auditar.

03

Código Explicado

Definición del Módulo

Todo comienza definiendo el módulo. El nombre debe ser único en toda la blockchain.

Pact Línea 1
;; El nombre del módulo es único en toda la blockchain
;; GOVERNANCE_KEYSET define quién puede actualizar el código

(module mi-token ADMIN_KEYSET
  
  ;; Implementamos el estándar fungible-v2
  ;; Esto garantiza compatibilidad con wallets y exchanges
  (implements fungible-v2)
  (implements fungible-xchain-v1)
  
  ;; ... resto del código
)

Schema y Tabla de Cuentas

El schema define la estructura de datos. La tabla almacena los registros.

Pact Schema
;; Estructura de cada cuenta:
;; - balance: cuántos tokens tiene
;; - guard: quién puede gastarlos

(defschema account-schema
  balance:decimal    ;; Cantidad de tokens
  guard:guard        ;; Autorización
)

;; Crea la tabla física en la blockchain
(deftable accounts-table:{account-schema})

Capabilities (Permisos)

Las capabilities son el corazón de la seguridad en Pact.

Pact Capabilities
;; TRANSFER: Permiso para transferir tokens
;; @managed = tiene límite gestionado (no puedes exceder amount)

(defcap TRANSFER:bool
  ( sender:string
    receiver:string
    amount:decimal
  )
  @doc "Capability para transferir tokens"
  @managed amount TRANSFER-mgr
  
  ;; Verificaciones de seguridad
  (enforce (!= sender receiver) "No puedes enviarte a ti mismo")
  (enforce (> amount 0.0) "La cantidad debe ser positiva")
  
  ;; Activa el permiso de débito automáticamente
  (compose-capability (DEBIT sender))
)

;; DEBIT: Solo el dueño puede restar de su cuenta
(defcap DEBIT:bool (sender:string)
  ;; Verifica que quien firma es el dueño
  (enforce-guard (at 'guard (read accounts-table sender)))
)

¿Qué es @managed?

Cuando una capability tiene @managed, el valor especificado (amount) actúa como un límite. Si intentas transferir más de lo autorizado en la firma, la transacción falla. Es una capa extra de seguridad.

Función de Transferencia

La función principal para mover tokens entre cuentas.

Pact Transfer
;; Transfiere tokens de sender a receiver
(defun transfer:string 
  (sender:string receiver:string amount:decimal)
  @doc "Transfiere tokens de sender a receiver"
  
  ;; with-capability: "Activa" el permiso TRANSFER
  ;; Esto verifica que sender firmó y amount es válido
  (with-capability (TRANSFER sender receiver amount)
    
    ;; Resta del sender
    (debit sender amount)
    
    ;; Suma al receiver
    (credit receiver 
      (at 'guard (read accounts-table receiver)) 
      amount)
  )
)
04

Flujo de una Transferencia

Cuando un usuario quiere transferir tokens, este es el proceso completo:

1
Usuario firma
con Ecko Wallet
2
TRANSFER cap
verifica firma
3
DEBIT activo
verifica guard
4
debit() resta
del sender
5
credit() suma
al receiver

Atomicidad

Si cualquier paso falla, toda la transacción se revierte. No hay estados intermedios. O se completa todo, o no se hace nada.

05

Tabla de Cuentas

Así se ve la tabla accounts-table en la blockchain:

account (KEY) balance guard
1,000.00 {keyset: "user-ks"}
500.50 {keyset: "user-ks-2"}
0.00 {keyset: "new-user"}

El prefijo k: indica que es una cuenta controlada por una llave pública. Es el formato estándar en Kadena.

06

Palabras Clave de Pact

Referencia rápida de las palabras clave más importantes:

enforce "Si esto es falso, ABORTA todo"
with-read "Lee de la tabla y usa los datos"
update "Modifica un registro existente"
insert "Crea un registro nuevo (falla si existe)"
write "Crea o actualiza (upsert)"
let "Guarda valor en variable temporal"
:= "Extrae valor y asigna a variable"
with-capability "Activa un permiso para este bloque"
require-capability "Solo ejecuta si el permiso está activo"
compose-capability "Activa otro permiso automáticamente"
07

Variables del Formulario

Estas son las variables que el formulario web reemplazará en la plantilla:

{{TOKEN_NAME}} Nombre del módulo (ej: "mi-token")
{{TOKEN_SYMBOL}} Símbolo corto (ej: "MTK")
{{DECIMALS}} Número de decimales (ej: 12 o 18)
{{TOTAL_SUPPLY}} Supply total (ej: 1000000.0)
{{GOVERNANCE_KEYSET}} Nombre del keyset que controla el módulo
{{ADMIN_KEYSET}} Referencia al keyset admin
08

Errores Comunes

Cuando algo falla, estos son los mensajes más frecuentes:

"Fondos insuficientes" El sender no tiene suficientes tokens para esta transferencia
"El guard no coincide" Estás intentando usar una cuenta con la firma equivocada
"Viola la precisión" Demasiados decimales (ej: 1.001 con precision=2)
"Cuenta no existe" Usa transfer-create en lugar de transfer para cuentas nuevas
"Keyset failure" La firma de la transacción no coincide con el keyset requerido
🚨

Siempre verifica en Testnet primero

Antes de desplegar en mainnet, prueba tu token en testnet. Los errores en mainnet pueden ser costosos y permanentes.