Saltar al contenido principal

Contratos completamente tipados

Cuando compilas un contrato creado con soroban-sdk, el archivo Wasm termina con una sección personalizada que contiene una descripción legible por máquina de los tipos de interfaz de tu contrato, a veces llamada su especificación o su API. Esto es similar a ABIs en Ethereum, excepto que Soroban almacenará cada uno de ellos on-chain desde el primer día, e incluyen comentarios del autor del contrato.

Estos tipos de interfaz están formateados utilizando XDR, un formato de datos utilizado ampliamente en Stellar. Puede ser complicado crear o consumir XDR manualmente, pero las herramientas pueden obtener estos tipos de interfaz para facilitarte la vida. Stellar CLI y Stellar SDK son dos de esas herramientas para hacerlo. Veamos cada uno.

Stellar CLI: stellar contract invoke​

De verdad, cada contrato inteligente es su propio programa y merece su propio CLI.

Así que eso es lo que te da Stellar CLI.

Un CLI único para cada contrato inteligente. Construido al vuelo, directamente desde los tipos de interfaz on-chain. Incluyendo los comentarios del autor. Un CLI implícito.

Por ejemplo, llamando al contrato de activo nativo en la red de prueba:

$ stellar contract invoke --network testnet --id CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC -- --help
Usage: CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC [COMMAND]

Commands:
  balance         Returns the balance of `id`.

                      # Arguments

                      * `id` - The address for which a balance is being queried. If the
                      address has no existing balance, returns 0.
  ...
  transfer        Transfer `amount` from `from` to `to`.

                      # Arguments

                      * `from` - The address holding the balance of tokens which will be
                      withdrawn from.
                      * `to` - The address which will receive the transferred tokens.
                      * `amount` - The amount of tokens to be transferred.

                      # Events

                      Emits an event with topics `["transfer", from: Address, to: Address],
                      data = amount: i128`
  ...

Options:
  -h, --help  Print help

Como cualquier otro CLI, también puedes obtener ayuda para cualquiera de estos subcomandos. Omitiendo todo antes del -- en el comando anterior, esto se vería así: … -- balance --help. Stellar CLI vuelve a obtener los tipos de interfaz on-chain, esta vez usándolos para generar una lista completa de todos los argumentos de la función, e incluso genera ejemplos.

consejo

Si no estás familiarizado con el separador -- de doble guion, este es un patrón utilizado por otros CLIs. Todo lo que sigue al doble guion, a veces llamado slop, se pasa al proceso hijo. Un ejemplo de otros CLIs que hacen uso de esto son npm run y cargo run.

Stellar JS SDK: contract.Client​

Para crear un cliente de contrato para el mismo contrato que se muestra para contract invoke arriba, usarías este JavaScript:

import { contract } from "@stellar/stellar-sdk";
const xlm = contract.Client({
  contractId: "CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC",
  networkPassphrase: "Test SDF Network ; September 2015",
  rpcUrl: "https://soroban-testnet.stellar.org",
});

Al igual que el CLI, esto obtendrá el contrato de la red activa y analizará los tipos/especificaciones del contrato. Generará automáticamente una clase que te permitirá llamar a los métodos del contrato de forma ergonómica:

xlm.balance({ id: "G123…" });

Ten en cuenta que todo lo mostrado arriba funciona dinámicamente desde un navegador. Sin embargo, a veces es agradable tener este comportamiento disponible también como una biblioteca, mientras construyes aplicaciones. Y en este caso, es realmente agradable tener TypeScript, que permite la autocompletado para todos los métodos en el contrato, y que puede incluir los comentarios del autor original del contrato. Eso es para lo que sirve el comando contract bindings typescript del CLI:

stellar contract bindings typescript \
  --network testnet \
  --output-dir xlm --overwrite \
  --id CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC

Esto crea un módulo NPM completamente tipado para el contrato dado.

Ya es el mejor; apenas comenzando​

Nos encanta que Soroban tuviera todos los tipos de interfaz de contratos disponibles on-chain desde el primer día. Sin llamadas API secundarias a servicios externos, sin gestión de tokens API secundarios, sin iniciar sesión ni crear una cuenta en ningún otro lugar, y con una fiabilidad casi perfecta. Es un cambio de juego dentro del espacio de blockchain.

Stellar CLI y JS SDK ya demuestran cómo esto puede ser desarrollado en herramientas fundamentales para brindar experiencias agradables a los desarrolladores. Y esto es solo el comienzo. En cada nivel del stack, puedes esperar—y construir—herramientas que hacen que interactuar con cualquier contrato sea predecible y fluido.

Pronto tendremos GUIs que se adaptan a cualquier contrato dado al vuelo, funcionando como documentación interactiva. Si estás escribiendo contratos que realizan llamadas entre contratos, la mayor parte del código que necesitas también puede ser autogenerado.

Y eso sigue siendo solo el comienzo. Con esos como bases, ¿qué más podemos construir? ¿Qué más puedes imaginar? ¿Cuál es el futuro de los componentes, ahora que un pequeño programa, también conocido como contrato inteligente, puede ser interactuado fácilmente en todas las capas del stack de software? Cuando se considera en combinación con Wasm—on-chain, en el navegador y en otros lugares—¿qué posibilidades de interoperabilidad podemos imaginar y co-crear?

No podemos esperar a ver qué construyes.