Resumen

¡En este tutorial, te guiaremos para crear un antiguo libro de visitas de internet! (Créeme, ¡todos estaban de moda en su momento!) Estaremos examinando cómo se construye el proyecto, comenzando con el contrato inteligente. Luego, convertiremos ese contrato inteligente desplegado en un "paquete de bindings", lo que nos permitirá integrarlo sin problemas en nuestro proyecto frontend. Para autenticar a nuestros usuarios, utilizaremos la nueva capacidad de claves de acceso de Stellar y daremos a cada uno de nuestros usuarios su propia billetera inteligente. ¡Como beneficio adicional, este libro de visitas es ya un proyecto utilizable (en Testnet) con el que puedes experimentar y usar ahora mismo! Después de este tutorial, tendrás una comprensión sólida de cómo los contratos inteligentes y las aplicaciones web pueden trabajar juntos en armonía. También tendrás herramientas y ejemplos prácticos de cómo podrías integrar billeteras inteligentes impulsadas por claves de acceso en tus propios proyectos.

Para este tutorial, caminaremos por los pasos mientras construimos una aplicación de muestra que hemos llamado Ye¹ Olde Guestbook, que se utilizará para mostrar varias funciones.

advertencia

Aunque Ye Olde Guestbook es una aplicación completamente funcional en el Testnet de Stellar, ha sido desarrollada únicamente para mostrar la funcionalidad de Stellar para el beneficio educativo de la comunidad de Stellar. No debe ser desplegada y utilizada en el Mainnet de Stellar.

Configuración del proyecto

Requisitos del proyecto

Para crear esta aplicación de libro de visitas, necesitaremos varias piezas.

• Marco de aplicación: estamos utilizando SvelteKit, optando por un proyecto que verifica tipos utilizando TypeScript. SvelteKit (y Svelte por sí solo) es un marco bastante capaz, y utilizaremos algunas de sus características en este proyecto. Sin embargo, no estaremos profundizando en esas áreas específicas de Svelte en este tutorial. El código fuente del proyecto está libre y disponible y cuenta con comentarios informativos decentes a lo largo, si deseas revisarlo para esos propósitos.
• Marco frontend: Estamos utilizando Skeleton para simplificar el uso de Tailwind CSS.
• Una forma de interactuar con la red: esta es una aplicación TypeScript, y estamos utilizando @stellar/stellar-sdk para esto. Podrías hacer solicitudes tradicionales fetch si quisieras, dependiendo de tus decisiones de despliegue. En cualquier caso, necesitaremos el SDK para interactuar con keypairs y transacciones. También estaremos utilizando un indexador de datos para acceder a eventos históricos de la red, y cubriremos más sobre esto en un punto posterior del tutorial.
• Una forma de interactuar con la cuenta de un usuario: estamos prescindiendo de las billeteras tradicionales aquí, y utilizaremos passkey-kit para dar a nuestros usuarios una billetera inteligente con la que interactuar. Pueden interactuar con esta billetera inteligente (a través de passkey-kit) mediante métodos que ya conocen (huellas digitales, reconocimiento facial, etc.).

nota

Si bien estamos utilizando los componentes anteriores para construir nuestra aplicación, hemos hecho nuestro mejor esfuerzo para redactar este tutorial de tal manera que la dependencia de cualquier cosa en particular se minimice. Preferiblemente, deberías poder usar el código TypeScript que hemos escrito y adaptarlo a cualquier otro marco que desees con un esfuerzo mínimo.

Algunas decisiones que hemos tomado durante el curso del desarrollo:

• Algunos de los componentes no relacionados con Stellar se inclinan un poco más hacia la forma Svelte de hacer las cosas, pero hemos trabajado para que sea bastante fácil de traducir a React, Astro, etc.
• Este proyecto está escrito de tal manera que un único despliegue de la aplicación interactúa con un único despliegue del contrato inteligente. Podría haberse escrito de manera diferente, pero no lo hemos hecho aquí por simplicidad.
• Estamos implementando nuestro propio servicio de claves de acceso aquí. Eso significa que configuraremos y usaremos passkey-kit (tanto componentes del lado del cliente como del servidor) en nuestra propia dapp. A largo plazo, este puede no ser el patrón de uso necesario. Es probable que surjan servicios que actúen como una "fábrica de billeteras" que puedan crear billeteras inteligentes y facilitar la adición de firmantes para varias aplicaciones. ¿Quizás estos servicios serán proporcionados por billeteras existentes? ¿Quizás estos servicios serán desconocidos para el usuario (y tal vez incluso para los desarrolladores) en el futuro? ¡Quién sabe! ¡El cielo es el límite! (Pero eso no es así todavía, así que lo estamos haciendo nosotros mismos.)
• It should be relatively responsive, no promises, though
• Hemos elegido un tema de Skeleton, así que se ve bien desde el principio.
• Hay una mezcla de lógica del lado del cliente y del lado del servidor. Esto se debe a que necesitaremos mantener algunos credenciales de autenticación en secreto, y queremos evitar filtrar estos a el código orientado al usuario. Algunas de estas técnicas son un poco específicas de SvelteKit, pero al final debería ser comprensible.
• Estamos desplegando en un proyecto gratuito de Vercel. Hemos tenido mucho éxito en desplegar proyectos de SvelteKit y Stellar fácil y rápidamente, y con muy poca configuración. Tu experiencia puede variar, pero este debería ser un buen punto de partida.
• Es probable que la aplicación no sea tan eficiente como podría ser. Tampoco está optimizada como podría estarlo. Hemos intentado encapsular las varias funcionalidades de tal forma que tenga sentido para el desarrollador que lee la base de código, por lo que hay algo de duplicación de código y algunas cosas podrían hacerse de una manera "mejor".
• Hacemos algo de manejo de errores, pero no tanto como querrías para una aplicación del mundo real. Si algo parece que no está funcionando, y no estás viendo un error, abre tu consola de desarrollador y puede que logres averiguar qué ha salido mal.
• No hemos implementado ninguna prueba automatizada. Probablemente querrás algunas para tu aplicación.

nota

Este tutorial probablemente sea mejor visto como "casi completo." No vamos a guiarte a través de cada uno de los archivos en nuestra base de código, y los archivos que utilizamos para ilustrar conceptos en el tutorial pueden no estar totalmente presentes o explicados. Sin embargo, cubriremos lo básico y te señalaremos ejemplos más completos en la base de código cuando sea aplicable.

Ayudantes de desarrollador

• Passkey Kit: Un SDK de TypeScript para crear y gestionar billeteras inteligentes de Stellar.
• Launchtube: Similar a un Paymaster en el mundo de EVM, el servicio de Launchtube tiene como objetivo aliviar todos los desafíos y complejidades de obtener una transacción en-chain al darte una API que acepta operaciones de Soroban y luego maneja la presentación exitosa de esas entradas a la red.
• Stellar Lab: Un laboratorio experimental para interactuar con la red Stellar.

Comenzar

Estos son los pasos que hemos tomado para comenzar a construir Ye Olde Guestbook. Siéntete libre de inspirarte y personalizar estas direcciones como mejor te parezca. Toda la base de código de Ye Olde Guestbook está libre y disponible en GitHub para referencia.

Comienza desde el repositorio soroban-template

Con el paso al desarrollo de contratos inteligentes, una utilidad emergente en el ecosistema Stellar es el "template de Soroban." Estos templates pueden ayudar a aliviar la carga de escribir código base, y pueden ayudar a adaptar flujos de trabajo típicos de desarrollo de Stellar en templates de referencia específicos de marco. Hemos creado justo tal template que puede ayudarte a comenzar a desarrollar con SvelteKit y claves de acceso desde el principio. Puedes utilizar el template en el sitio web de GitHub:

O, puedes (hacer un fork y) clonar el repositorio del template localmente, y empezar a trabajar de esa manera:

git clone https://github.com/ElliotFriend/soroban-template-sveltekit-passkeys ye-olde-guestbook

Este template frontend te dará una estructura y algunos valores predeterminados (opinionados). ¡Lo que hagas a partir de ahí depende de ti!

Este template te dará varias cosas para ayudarte a empezar rápidamente:

• un directorio /contracts inicial con un contrato hello_world en él,
• un conjunto preconfigurado de dependencias y paquetes, incluyendo el paquete de bindings hello_world,
• lógica y ayudas de claves de acceso ya escritas de fábrica,
• un script de inicialización para desplegar contratos y generar bindings para ellos, y
• tendrás un sitio de SvelteKit listo para personalizar, escrito en TypeScript.

¿Qué más podrías querer!?

Configura el archivo .env

El template viene con un archivo .env.example, que necesitarás modificar. Primero, copia o mueve este archivo a .env:

cp .env.example .env

Luego, abre el archivo .env, y comienza a personalizar cualquiera de las entradas que necesites. Si planeas ejecutar en Testnet (y deberías empezar allí), la mayoría de las variables serán adecuadas tal como están.

Algunas variables que querrás cambiar incluyen:

PUBLIC_STELLAR_ACCOUNT=stroopy # you're welcome to use stroopy, but if you have an name you'd prefer, put that here
PRIVATE_FUNDER_SECRET_KEY=S...ECRET # fund an account on Testnet and put the secret key here
PUBLIC_FUNDER_PUBLIC_KEY=G...ADDRESS # put the public key from the funded account here

Instalar dependencias

Con nuestro template preexistente, todo lo que necesitas se debe extraer de los archivos package.json y Cargo.toml. Todo lo que tienes que hacer es abrir una terminal e instalar las dependencias:

pnpm install

nota

No estamos tratando de dictar qué gestor de paquetes deberías usar. Al construir una aplicación SvelteKit de pila completa usando Stellar y claves de acceso, hemos visto recientemente mucho éxito y confiabilidad usando pnpm. ¿Quién puede decir por qué es así?, y puede que seguramente sea un golpe de suerte y limitado a nuestra propia experiencia. En cualquier caso, estaremos usando pnpm para el resto de este tutorial.

A continuación, veamos el contrato inteligente que está en el corazón del proyecto.

Notas

Footnotes

1. Dato curioso: El carácter "Y" en la palabra "Ye" se usaba comúnmente en los períodos de inglés antiguo y medio, y representaba la letra Thorn, que ya no forma parte del alfabeto inglés moderno. En realidad, no se pronunciaba de la manera en que decimos la letra moderna "y", sino que se vocalizaba como el dígrafo "th." Así que, hace 500 años, habrías pronunciado "Ye" exactamente de la misma manera en que pronuncias "the" hoy en día. ¡Loco, ¿verdad!? ↩