Saltar al contenido principal

Generar bindings

Centrémonos en cómo interactuaremos con el contrato inteligente desplegado. ¡Aquí es donde entran los bindings de TypeScript! Pero, te escucho preguntar: ¿Qué son los bindings de TypeScript?

Estos bindings son una característica de la CLI de Stellar que generará y producirá un paquete NPM completamente tipado listo para integración en tu frontend. Esto significa que puedes importar e invocar un contrato inteligente como si fuera cualquier otro paquete de Node.js! Obtienes funciones tipadas para cada una de las funciones de tu contrato, y estas darán como resultado una transacción ensamblada, simulada, firmable y enviable!

consejo

¡Esto se puede hacer con CUALQUIER contrato que esté en vivo en la red! O, también puedes usarlo en contratos que solo has compilado localmente.

Generaremos nuestros bindings de contrato y los mantendremos en el mismo repositorio que nuestro código frontend. Sin embargo, podrías hacer esto de muchas maneras diferentes:

  • Tu frontend puede instanciar un contract.Client usando la función fromWasmHash del SDK de JavaScript. Esto puede generar bindings al vuelo mientras tus usuarios navegan por tu aplicación.
  • Tu proceso de implementación podría incluir un paso que crea/despliega/vincula un paquete de contrato en el momento del despliegue.
  • Incluso podrías generar y publicar un paquete de bindings por sí solo. Luego pnpm install <bindings_package_name> puede hacerse en cualquier dapp con el que necesites interactuar (o alguien más) que podría necesitar interactuar con ese contrato.

El método manual​

¡Antes de que saltes adelante! Echa un vistazo a esta sección (breve). Es realmente útil tener una comprensión completa de qué pasos estamos siguiendo en la sección automatizada. Esto te ayudará a adaptar y/o solucionar problemas de este tutorial para tus propósitos específicos.

Instalar el contrato compilado​

El código del contrato inteligente necesita ser instalado en la red primero. Esto sube el archivo Wasm binario compilado a la blockchain para que sea instanciado en un contrato posteriormente. Desde dentro de tu directorio de proyecto:

stellar contract install \
    --source <identity or secret key> \
    --network testnet \
    --wasm ./target/wasm32-unknown-unknown/release/ye_olde_guestbook.wasm

Desplegar una instancia de contrato​

Esto devolverá un hash hexadecimal correspondiente al Wasm ejecutable subido. Este hash puede ser usado en el comando de despliegue para crear una nueva instancia de contrato:

stellar contract deploy \
    --source <identity or secret key> \
    --network testnet \
    --wasm-hash <wasm_hash_from_install_step>

Generar bindings para el contrato desplegado​

Ahora podemos (de nuevo) usar la CLI de Stellar para generar bindings del contrato que acabamos de desplegar. También puedes generar estos bindings desde tu archivo Wasm local usando el parámetro --wasm-hash. El parámetro --overwrite se usa para decirle a la CLI que debe generar el paquete de bindings, incluso si encuentra que el directorio no está vacío (es decir, estamos volviendo a vincular un contrato porque hemos modificado el código y lo hemos redeployado).

stellar contract bindings typescript \
    --network testnet \
    --id <contract_address_from_deploy_step> \
    --output-dir ./packages/ye_olde_guestbook \
    --overwrite

Tendremos que construir el paquete de bindings, ya que (en su estado inicial) el paquete es mayormente de tipos de TypeScript y stubs para las varias funciones del contrato.

cd packages/ye_olde_guestbook
pnpm install
pnpm run build
cd ../..

Importar el paquete de bindings como una dependencia del proyecto​

Con nuestros bindings generados, podemos agregarlo a nuestro proyecto frontend. Ejecuta esto desde la raíz de tu proyecto:

pnpm add file:./packages/ye_olde_guestbook

Importar el cliente de bindings en el proyecto de SvelteKit​

información

Nos estamos desviando un poco hacia el lado Svelte de las cosas aquí. El objetivo principal de este paso es obtener el cliente del contrato (que es el "paquete de bindings" que acabamos de generar) en nuestro frontend de una manera que sea utilizable donde sea que lo necesitemos. En SvelteKit, lo ponemos en src/lib/contracts porque eso significa que podemos acceder fácilmente al cliente importando desde $lib/contracts/ye_olde_guestbook cuando y donde lo necesitemos.

Ahora, definiremos el cliente de contrato de una manera que podamos acceder fácilmente a través del resto de nuestra aplicación.

src/lib/contracts/ye_olde_guestbook.ts
import * as Client from "ye_olde_guestbook"; // import the package we just added as a dependency
import { PUBLIC_STELLAR_RPC_URL } from "$env/static/public"; // import the RPC url from the .env file

// instantiate and export the Client class from the bindings package
export default new Client.Client({
  ...Client.networks.testnet, // this includes the contract address and network passphrase
  rpcUrl: PUBLIC_STELLAR_RPC_URL, // this is required to invoke the contract through RPC calls
});

El método automatizado​

¡Eso fue un montón de pasos y un montón de trabajo, ¿verdad!? La buena noticia es que nuestra plantilla inicial (¿recuerdas eso?) viene con un script initialize.js que realizará todas esas acciones por ti! ¡Este script pasará por todos los siguientes pasos por ti:

  • Crear y financiar un keypair en la CLI
  • Instalar y desplegar todos los contratos en el directorio /contracts
  • Generar bindings de los contratos desplegados
  • Crear un archivo $lib/contracts/<contract_alias>.ts para fácil importación en tu código frontend

Siempre puedes personalizar este script para adaptarlo a tus necesidades. Consulta el código fuente aquí (que ha sido documentado con comentarios). O, puedes ver el script mantenido oficialmente en el repositorio soroban-template-astro, también.

Ejecuta el script de inicialización así:

node initialize.js
información

Para una visión más completa del proceso de crear, personalizar y usar scripts de inicialización como este, consulta la guía de plantilla frontend.

También hemos agregado un comando a los scripts de package.json, así que puedes ejecutar este script de inicialización simplemente ejecutando (desde la raíz de tu proyecto):

pnpm run setup

Bien, así que ahora hemos creado un proyecto inicial, escrito un contrato inteligente de libro de visitas y generado un paquete NPM que nos ayudará a interactuar con ese contrato en la red. ¡Increíble!

A continuación, echémosle un vistazo a cómo nuestros usuarios se conectarán e interactuarán con nuestra dapp. ¡Es hora de las claves de acceso! (insertar ruidos de cuerno de aire)📢