Este post describe cómo construir un cliente básico que registra la actividad en el Cadena de bloques descentralizada Stellar. Stellar alberga una lista creciente de nuevas y diferentes criptomonedas y tokens. Con el código de este post se puede crear una herramienta de consulta básica de los activos mantenidos en una cuenta Stellar, utilizando Couchbase para el almacenamiento y la consulta.
Lo que necesitas
Couchbase
Para seguir adelante, configura una versión reciente de Couchbase que sea igual o superior a 7.0.2. Puedes hacer la mayoría de las cosas con versiones anteriores, pero en futuras entradas no podrás acceder a los gráficos, ámbitos o colecciones integrados. Couchbase Capella también está disponible con una sencilla prueba gratuita, o puede instalar una base de datos on-prem o Versión Docker de Couchbase.
Utilizando la interfaz de administración integrada de Couchbase, elija la opción Cubo en la barra lateral y el menú Añadir cubo (arriba a la derecha). Cree un cubo llamado estelarcomo se muestra en la Figura 1. Necesita una memoria mínima asignada, la mía por defecto es de 300MB que será más que suficiente.
Figura 1. Añadir un nuevo bucket de datos al cluster de Couchbase.
Tardará un minuto en calentarse antes de ponerse en verde para indicar que está disponible, como se muestra en la figura 2.
Figura 2. El nuevo cubo ya está disponible.
Dirección de la Cartera Stellar
A continuación, necesitarás una dirección de monedero Stellar para realizar el seguimiento. Para encontrar una cuenta interesante, utiliza Stellar.expert y su navegador de cuentas para encontrar una identificación de la cartera.
Para mis experimentos, estoy utilizando esta dirección, ya que tiene una pequeña pero interesante colección de fichas:
|
1 |
GAF55XSX3WCHWUB6CEGSKKMLPKV56Y5MK4UCBRSSGRBBDENFEXSWWMDQ |
SDK de Python
A continuación usaremos Python 3 y el Couchbase Python SDK. Instala el SDK de Python usando el comando pip como se describe en el documentación. Incluya también el solicita que necesitaremos para descargar desde la API web de Stellar.
|
1 |
python3 -m pip install --upgrade pip setuptools wheel |
Pruebe la instalación iniciando Python e importando el módulo Couchbase:
|
1 2 3 4 5 |
tyler@megaserv:python-stellar$ python3 Python 3.8.10 (default, Nov 26 2021, 20:14:08) [GCC 9.3.0] on linux Type "help", "copyright", "credits" or "license" for more information. >>> import couchbase |
Si se completa sin errores, entonces estamos listos. Pulse CTRL+D para dejarlo.
Conexión a Couchbase
En Hola Couchbase de la documentación muestran la información básica de conexión que necesitamos añadir a nuestro script Python. Como mínimo, para conectarnos a nuestro nuevo bucket necesitamos:
- El nombre de usuario/contraseña del administrador (o una persona con derechos de acceso al nuevo cubo)
- El nombre/IP del servidor/cluster Couchbase
- El nombre del nuevo cubo (por ejemplo, estelar)
Cree un script llamado app.py:
|
1 2 3 4 5 6 7 |
from couchbase.cluster import Cluster, ClusterOptions from couchbase.auth import PasswordAuthenticator cluster = Cluster('couchbase://localhost', ClusterOptions( PasswordAuthenticator('Administrator', 'Administrator'))) cb = cluster.bucket('stellar') |
Puede ejecutar el script y ver si obtiene algún error antes de continuar.
Revisión del esquema de cuentas de Stellar.org
Para este proyecto, descargaremos la información de la cuenta directamente desde el API web estelar y almacenar los datos JSON en bruto en Couchbase para su posterior consulta.
Para acceder a una cuenta Stellar utilizaremos su servicio Horizon y pulsaremos su /público/activo punto final. Por ejemplo, yo utilizo Cartero.co para hacer una vista rápida del JSON resultante para tener una idea del esquema, como se muestra en la Figura 3.
Figura 3. Muestra del documento JSON de cuentas Stellar.
En la figura, observa que he contraído algunos objetos y listas para ver las cosas con más claridad. Los elementos del nivel raíz, como account_id, subentry_county última_hora_modificada son potencialmente útiles. Pero la mayoría de las entradas están en el saldos objeto, casi 1700 líneas de hecho.
Estos son los elementos esenciales del titular de los activos. Veámoslos con más detalle en la Figura 4.
Figura 4. Dos entradas de la lista de saldos.
En la figura anterior se muestran dos tipos de balanzas. Hay docenas de otros que no se muestran, pero todos son similares al primero que se muestra aquí. Se muestra un balance del número de fichas (1.7), el asset_code (ZDC son Fichas del zodíaco), y el emisor_de_activos (ya que muchas cuentas pueden emitir el mismo activo). Tenga en cuenta también la tipo_activo (credit_alphanum4).
La segunda entrada anterior es la única diferente tipo_activo en la lista (nativo). En este caso, se trata de un saldo base a nivel de cuenta, el token nativo de la cartera Lobstr del propietario, en este caso Lúmenes estelares (XLM). Este saldo puede intercambiarse con saldos de cualquier otro activo y viceversa a través de la cuenta de negociación de activos.
Planificación del flujo de trabajo
Teniendo en cuenta lo anterior, podemos planificar cómo almacenar y acceder a toda la información que nos interesa. Entonces, ¿qué nos interesa?
En primer lugar, nos interesa una actualización diaria de las estadísticas sobre la cuenta. Por lo tanto, supongamos que ejecutaremos nuestro script diariamente y actualizaremos la información en la base de datos.
Será bueno conocer los saldos actuales, incluida la cantidad nativa de XLM y los saldos de otros tokens. Mientras conservemos estos detalles en los documentos que almacenamos, podremos consultarlos en cualquier momento. También tendremos que asegurarnos de que nuestra clave sea una especie de marca de tiempo o ID incremental para que nuestros documentos no se sobrescriban con entradas más recientes.
También podríamos hacer algunos cálculos intermedios para mantener otro documento actualizado con los totales base, etc. pero eso lo dejaremos para un futuro post.
Los dos pasos siguientes son descargar este documento JSON y subirlo a Couchbase. A continuación, veremos el resultado en la interfaz de usuario de la consola web y probaremos las consultas y los gráficos.
Descarga de datos de cuentas Stellar con Python
Se trata de un ejemplo muy sencillo que podremos ampliar en las próximas semanas.
Para acceder a una API web utilizamos el módulo requests de Python y almacenamos los resultados en un objeto JSON.
|
1 2 3 4 5 6 7 8 9 |
import requests url = "https://horizon.stellar.org/accounts/GAF55XSX3WCHWUB6CEGSKKMLPKV56Y5MK4UCBRSSGRBBDENFEXSWWMDQ/" response = requests.request("GET", url) jsondoc = response.json() #for key, value in jsondoc.items(): # print(key, ":", value) |
Incluyo un ejemplo de bucle simple para mostrarte lo fácil que es si quieres verlo impreso de una forma muy fea. Hay técnicas de impresión más bonitas pero usaremos las integradas en Couchbase para hacerlo más fácil en lugar de escribir más código aquí.
Envío de documento JSON a Couchbase
A continuación usamos nuestro objeto bucket de Couchbase y hacemos una llamada upsert. Upsert es lo mismo que una sentencia de inserción de documento o base de datos, pero actualizará cualquier documento existente si ya existe. En nuestro caso, también queremos generar un ID único y utilizarlo para el ID de nuestro documento.
Añadamos una marca de tiempo unix con la función tiempo y crear una clave, como se muestra en la guía de inicio del SDK de Python, que también incluye la captura de algunas excepciones básicas.
Ponerlo todo junto
Ahora demos un paso atrás y veamos el ejemplo de código consolidado construido con varias funciones para ayudar a compartimentar todo y hacerlo un poco más reutilizable.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 |
import requests, time from couchbase.cluster import Cluster, ClusterOptions from couchbase.auth import PasswordAuthenticator account = 'GAF55XSX3WCHWUB6CEGSKKMLPKV56Y5MK4UCBRSSGRBBDENFEXSWWMDQ' def connect(): cluster = Cluster('couchbase://localhost', ClusterOptions(PasswordAuthenticator('Administrator', 'Administrator'))) return cluster.bucket('stellar') def getjson(): url = "https://horizon.stellar.org/accounts/%s/" % account print("Fetching: " + url) response = requests.request("GET", url) return response.json() def upsert_document(connection, doc): now = int( time.time() ) try: key = str(now) + "_" + account[:5] result = connection.upsert(key, doc) print(result) except Exception as e: print("Error",e) cb = connect() json = getjson() upsert_document(cb, json) |
El resultado mostrará la URL de la API web que se utilizó y mostrará un error o el icono OperationResult detalles:
|
1 2 3 4 |
$ python app.py Fetching: https://horizon.stellar.org/accounts/GAF55XSX3WCHWUB6CEGSKKMLPKV56Y5MK4UCBRSSGRBBDENFEXSWWMDQ/ OperationResult<rc=0x0, key='1644906573_GAF55', cas=0x16d3e1d051760000, tracing_context=0, tracing_output=None> |
Ver los resultados de los tokens en la consola web
Después de ejecutar el script unas cuantas veces, debería tener algunos documentos en el cubo del proyecto. Cuando haya seleccionado el estelar cubo, pulse la tecla Documentos (arriba a la derecha) para ver una lista de documentos con los que puede interactuar, uno de los resultados se muestra en la Figura 5.
Figura 5. Ejemplo de documento de cuenta Stellar abierto en la consola web de Couchbase.
Para habilitar la consulta necesitamos construir algunos índices. Cambie a la Consulta e introduzca lo siguiente N1QL para configurar algunos índices. Tenga en cuenta, estamos utilizando una colección por defecto de los documentos, por lo que el prefijo el nombre de cubo para denotar que. (En un futuro post segregaremos nuestros documentos para diferentes propósitos y usaremos colecciones para hacerlo).
|
1 2 3 4 |
create primary index on default:stellar; create index idx_account_id on default:stellar(id); create index idx_modified on default:stellar(last_modified_time); create index idx_entrycount on stellar(subentry_count); |
Para cada uno de los diferentes activos:
|
1 2 3 4 |
create index idx_asset_code on stellar(balances.asset_code); create index idx_asset_type on stellar(balances.asset_type); create index idx_asset_issuer on stellar(balances.asset_issuer); create index idx_asset_balance on stellar(balances.balance); |
A continuación, prueba el índice con una consulta básica:
|
1 |
select count(*) from stellar; |
En Resultados debería mostrar una salida básica con el número de documentos en el cubo, en este caso, 7 como se muestra en la Figura 6.
Figura 6. Ejemplo de consulta para contar los documentos del bucket.
Consulta de atributos en un conjunto de documentos JSON
Puedes construir consultas fácilmente ya que N1QL es muy similar al SQL estándar pero con inteligencia JSON incorporada. Hay funciones que nos permiten acceder a las entradas del archivo saldos como si fueran columnas. Utilización de UNNEST, cada una de las subentradas se convierte en un nombre de campo accesible en la consulta.
Por ejemplo, la siguiente consulta enumera todos los activos y saldos:
|
1 2 3 |
SELECT balances.balance AS balance, balances.asset_code FROM stellar UNNEST balances |
La ventana de consulta muestra los resultados en JSON por defecto, pero puedes cambiarla a la opción Tabla y ver nuestros resultados hasta el momento:
Próximos pasos
En nuestro próximo artículo, profundizaremos en la creación de algunos gráficos y utilizaremos más magia de consulta.
Aquí tiene otros enlaces para informarse sobre los temas que tratamos:
- Empieza a usar el SDK Python de Couchbase
- Hoja de control de Couchbase N1QL (PDF)
- Intercambio descentralizado Stellar (stellar.org)
- Conceptos básicos de Blockchain
- Documentación sobre la API para desarrolladores de Stellar (cuentas)
- Stellar Lumens - XLM - el token del futuro
