Introducción

Esta sección ofrece una visión general de los contratos Stellar, describiendo sus conceptos clave sobre los contratos inteligentes en la red Stellar.

Contrato Inteligente en WebAssembly (Wasm)

Un contrato inteligente en Stellar es un conjunto programable de binarios ejecutables en WebAssembly (Wasm). WebAssembly (Wasm) es un formato liviano y portátil de instrucciones binarias diseñado para ejecución de alto rendimiento en varios entornos, incluidas las blockchains, navegadores web y servicios en la nube. En Stellar, Wasm sirve como la base para los contratos inteligentes al permitir un entorno de ejecución seguro y eficiente.

• Compilación: Una vez que el contrato inteligente está escrito en un lenguaje admitido, como Rust, el contrato se compila en un archivo ejecutable Wasm. Este archivo contiene un bytecode de bajo nivel que puede ejecutarse eficientemente dentro de un entorno aislado.
• Carga y almacenamiento: Después de la compilación, el ejecutable Wasm se carga primero en la red Stellar, donde se almacena en una entrada ledger llamada CONTRACT_DATA. La entrada CONTRACT_DATA del ledger se crea para almacenar los datos binarios Wasm.
• Se crea un hash único: Un identificador único para esta entrada CONTRACT_DATA es el hash del archivo ejecutable, llamado Wasm hash. Cabe destacar que este ejecutable binario se almacena independientemente de su(s) contrato(s) desplegado(s).
• Múltiples instancias de contrato: Se pueden desplegar múltiples instancias de contrato que referencian el mismo código de bytes Wasm, con cada instancia manteniendo su propio almacenamiento, estado y configuraciones.

Instancias de Contrato

Después de que el código de bytes ejecutable se carga on-chain, se pueden desplegar instancias de contrato que referencian el mismo código de bytes. Un ejecutable Wasm de contrato puede tener una relación uno-a-muchos con sus instancias de contrato que funcionan de forma independiente. Esto significa que el mismo código ejecutable puede ser usado por múltiples instancias de contrato que se comportan idénticamente debido al código ejecutable compartido, manteniendo datos de estado separados y distintos porque los datos están vinculados a la instancia del contrato. Una instancia de contrato se almacena como su propia entrada en el ledger, y cualquier almacenamiento de la instancia del contrato se guarda en la misma entrada del ledger junto con la instancia del contrato. Por lo tanto, los datos almacenados en el almacenamiento de la instancia del contrato tienen un TTL igual al de la instancia del contrato misma. Si un contrato está en vivo y no ha expirado, el almacenamiento de la instancia también está garantizado que esté disponible.

información

Nota Importante: El código de bytes Wasm se almacena por separado de las instancias de contrato desplegadas. Esta separación permite que múltiples instancias de contrato referencien el mismo ejecutable Wasm mientras mantienen sus propios almacenamiento, estado y configuraciones de contrato.

Almacenamiento de Contrato

Además de las entradas del ledger que se crean durante el proceso de carga/despliegue del contrato, cada contrato puede crear y acceder a su propio conjunto de entradas del ledger. Estas entradas del ledger (así como el código del contrato y las entradas del ledger de la instancia del contrato) están sujetas a los tiempos de vida de archivado de estado o comportamiento TTL (time-to-live). Cada tipo de almacenamiento tiene estructuras de tarifas distintas, comportamiento TTL y está diseñado para almacenar tipos específicos de datos. Usar el almacenamiento incorrecto puede causar errores lógicos en tu aplicación, además de afectar los costos.

Atributo	Almacenamiento Temporal	Almacenamiento Persistente	Almacenamiento de Instancia
Tarifas	El más económico	El más caro (igual que Instancia)	El más caro (igual que Persistente)
Persistencia	Eliminado permanentemente cuando se alcanza el TTL del ledger	Puede archivarse incluso si la instancia del contrato está activa. Su tiempo de vida es independiente de la instancia del contrato.	Comparte el tiempo de vida de la instancia del contrato. Datos accesibles si no se ha alcanzado el TTL de la instancia.
Recuperación	No puede ser restaurado	RestoreFootprintOp	extendFootprintTTLOp
Capacidad	Ilimitada	Ilimitada	Limitada
Casos de uso	Datos con límite temporal o fácilmente recreables (ej. oráculos de precios, firmas). No adecuado para verificaciones de corrección	Datos de usuario a largo plazo que deben persistir más allá del TTL (ej. saldos)	Estado compartido del contrato vinculado a la instancia del contrato (ej. cuentas admin, metadatos del contrato)

Invocar Contratos

Ahora que has aprendido los conceptos básicos de un contrato Stellar, vamos a entender algunos conceptos sobre la invocación de contratos. Cuando una transacción intenta invocar una función en el contrato, primero se recupera el código de bytes Wasm del ledger, y se instancia una máquina virtual ("VM") segura e independiente para ejecutar el código de bytes del contrato y luego finalizar. Este enfoque ofrece varios beneficios, incluyendo seguridad ya que la máquina virtual (VM) opera en un entorno aislado y ofrece ejecución determinista.

Para probar la invocación de contratos en Testnet, por favor visita Explorador de contratos de Stellar Lab.

Información del Contrato

El Wasm de un contrato Stellar contiene secciones personalizadas dedicadas. Estas proporcionan metadatos útiles que las implementaciones pueden usar para mejorar la experiencia del usuario.

• Meta de Entorno
• Meta de Contrato
• Especificación del Contrato

Explora la información del contrato en el Explorador de Contratos de Stellar Lab.

Meta de Entorno

Los contratos deben contener una sección personalizada Wasm llamada contractenvmetav0 que contenga un SCEnvMetaEntry serializado. La versión de interfaz almacenada debe igualar la versión de las funciones host admitidas. Para referencia, consulta CAP-46-1 Env Meta.

Para ver la Meta de Entorno, considera usar el Explorador de Contratos de Stellar Lab o el comando stellar contract info env-meta --contract-id <contract-id> de la CLI de Stellar.

Meta de Contrato

Los contratos pueden incluir opcionalmente una sección personalizada Wasm llamada contractmetav0, que contiene un SCMetaEntry serializado. Esta sección no es usada por la red misma, pero permite que los contratos incorporen metadatos arbitrarios, incluyendo nombre del contrato, versión, autor, interfaces admitidas, repositorio fuente o dominio principal. Las aplicaciones y herramientas pueden leer estos metadatos para ofrecer mejores experiencias de desarrolladores, mejor indexación o descubrimiento mejorado de contratos. Para referencia, consulta SEP-46 Contract Meta.

Para añadir metadatos a la Meta de Contrato, usa el comando de CLI Stellar stellar contract build --meta <meta>, o usa el SDK de Rust (ej. contractmeta!(key="name", val="Defi Swap Contract")).

Para ver la Meta de Contrato, usa el Explorador de Contratos de Stellar Lab o el comando CLI stellar contract info meta --contract-id <contract-id> de Stellar.

Especificación del Contrato

Los contratos deben contener una sección personalizada Wasm llamada contractspecv0 que contenga un flujo serializado de SCSpecEntry. Debe existir un SCSpecEntry para cada función, estructura y unión exportada por el contrato. Para referencia, consulta SEP-48 Contract Interface Specification.

Una especificación de contrato es como un ABI (Interfaz Binaria de Aplicación) en Ethereum. Es una descripción estandarizada de la interfaz de un contrato inteligente, típicamente en formato JSON o XDR. Define las funciones, estructuras de datos, eventos y errores del contrato de manera que aplicaciones externas puedan entender y usar.

Cuando compilas un contrato inteligente usando el SDK de Rust, el archivo Wasm resultante incluye una sección especial que contiene una descripción completa de los tipos de la interfaz de tu contrato. Esto suele denominarse spec o especificación del contrato. La especificación de contratos inteligentes Stellar, conocida como especificación del contrato, es un elemento fundamental para interactuar con contratos y construir dApps en la red Stellar. La especificación del contrato provee definiciones robustas y totalmente tipadas para interactuar con contratos inteligentes, ofreciendo funcionalidad equivalente al ABI de Ethereum mientras supera sus limitaciones.

La especificación del contrato sirve como una interfaz estandarizada para interactuar con contratos inteligentes Stellar. Similar a los ABIs de Ethereum, pero con ventajas clave:

• Disponibilidad on-chain: Cada especificación del contrato se almacena on-chain
• Comentarios del desarrollador: Se preservan los comentarios del autor del contrato
• Comunicación fluida entre contratos y aplicaciones externas
• Compatibilidad en todo el ecosistema con herramientas como billeteras, exploradores y SDKs

Esta estandarización simplifica integraciones y acelera el proceso de desarrollo.

Definiciones Completamente Tipadas del Contrato

La Especificación del Contrato impone definiciones completamente tipadas para todas las funciones del contrato, entradas y salidas. Esto garantiza que:

• Los desarrolladores pueden definir el comportamiento del contrato explícitamente, reduciendo ambigüedades.
• Se minimizan desajustes de tipo y errores en tiempo de ejecución, conduciendo a contratos inteligentes más confiables.
• Las herramientas pueden ofrecer sugerencias inteligentes y validaciones durante el desarrollo.

Al incorporar seguridad de tipos a nivel de protocolo, la Especificación de Contrato de Stellar crea un entorno de desarrollo más predecible y robusto.

Comparación con ABI de Ethereum

La Especificación de Contrato de Stellar comparte muchas similitudes con el ABI de Ethereum pero también introduce mejoras:

Característica	ABI de Ethereum	Especificación de Contrato Stellar
Contratos completamente tipados	Parcial	Sí
Decodificación y validación	Manual o externa	Incorporada
Enfoque en seguridad	Moderado	Alto (seguridad de tipos aplicada)

Generar especificaciones de contrato

El CLI de Stellar proporciona un comando para generar una especificación de contrato a partir del código fuente de un contrato. Este proceso es fácil pero requiere que tengas el binario Wasm del contrato.

A veces, puede que no tengas acceso al código fuente del contrato o la capacidad para compilarlo. En tales casos, debes usar el comando stellar contract fetch para descargar el binario Wasm del contrato y generar la especificación.

Finalmente, usamos el comando stellar bindings para generar la especificación del contrato a partir del binario Wasm.

El Stellar Lab tiene un Explorador de Contratos que también ofrece la capacidad de ver y descargar la especificación de un contrato.

nota

Habiendo leído la introducción de un contrato Stellar, intentemos escribir un contrato inteligente siguiendo la guía Comenzar.