Esta publicação descreve como criar um cliente básico que registra a atividade no Cadeia de blocos descentralizada Stellar. A Stellar hospeda uma lista crescente de tokens e moedas alternativas de criptomoedas novas e diferentes. Com o código desta publicação, você pode criar uma ferramenta de consulta básica de ativos mantidos em uma conta Stellar, usando o Couchbase para armazenamento e consulta.
O que você precisará
Couchbase
Para acompanhar, configure uma versão recente do Couchbase que seja igual ou superior à 7.0.2. Você pode fazer a maioria das coisas com versões anteriores, mas em postagens futuras não será possível acessar os gráficos, escopos ou coleções incorporados. Couchbase Capella O banco de dados como serviço também está disponível com uma avaliação gratuita simples, ou você pode instalar um banco de dados local ou Versão do Docker do Couchbase.
Usando a UI de administração integrada do Couchbase - escolha a opção Balde na barra lateral e o menu Adicionar balde (canto superior direito). Crie um bucket chamado estelarconforme mostrado na Figura 1. Ele precisa de um mínimo de memória atribuída a ele; o meu padrão é 300 MB, o que será mais do que suficiente.
Figura 1. Adicionar um novo bucket de dados ao cluster do Couchbase.
Ele levará um minuto para aquecer antes de ficar verde para mostrar que está disponível, conforme mostrado na Figura 2.
Figura 2. O novo bucket já está disponível.
Endereço da carteira Stellar
Em seguida, você precisará de um endereço de carteira Stellar para monitorar. Para encontrar uma conta interessante, use Stellar.expert e seu navegador de contas para encontrar uma carteira de identidade.
Para meus experimentos, estou usando esse endereço, pois ele tem uma coleção pequena, mas interessante, de tokens:
|
1 |
GAF55XSX3WCHWUB6CEGSKKMLPKV56Y5MK4UCBRSSGRBBDENFEXSWWMDQ |
SDK do Python
Em seguida, usaremos o Python 3 e o Couchbase Python SDK. Instale o Python SDK usando o comando tubulação conforme descrito no comando documentação. Inclua também o solicitações que precisaremos para fazer o download da API da Web do Stellar.
|
1 |
python3 -m pip install --upgrade pip setuptools wheel |
Teste a instalação iniciando o Python e importando o 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 |
Se ele for concluído sem erros, então estamos prontos para começar. Pressione CTRL+D para desistir.
Conexão com o Couchbase
O Olá, Couchbase na documentação mostram as informações básicas de conexão que você precisa adicionar ao nosso script Python. No mínimo, para nos conectarmos ao nosso novo bucket, precisamos de:
- O nome de usuário/senha do administrador (ou alguém com direitos de acesso ao novo bucket)
- O nome/IP do servidor/cluster do Couchbase
- O nome do novo bucket (por exemplo,, estelar)
Crie um script chamado 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') |
Você pode executar o script e verificar se há algum erro antes de continuar.
Revisão do esquema de contas do Stellar.org
Para este projeto, faremos o download das informações da conta diretamente do API da Web estelar e armazenar os dados JSON brutos no Couchbase para consulta posterior.
Para acessar uma conta Stellar, usaremos o serviço Horizon e acessaremos a conta /public/asset ponto final. Por exemplo, eu uso Carteiro.co para fazer uma visualização rápida do JSON resultante para ter uma ideia do esquema, conforme mostrado na Figura 3.
Figura 3. Amostra do documento JSON das contas Stellar.
Na figura, observe que eu reduzi alguns objetos e listas para ver as coisas com mais clareza. Os elementos de nível raiz, como account_id, subentry_counte last_modified_time são potencialmente úteis. Mas a maioria das entradas está na seção balanços objeto, quase 1.700 linhas na verdade.
Esses são os elementos essenciais do detentor do ativo. Vamos examiná-los um pouco mais detalhadamente na Figura 4 abaixo.
Figura 4. Duas entradas da lista de saldos.
Na figura acima, são mostrados dois tipos de balanços. Há dezenas de outros que não estão sendo mostrados, mas todos são semelhantes ao primeiro mostrado aqui. Ele lista um saldo do número de tokens (1.7), o asset_code (ZDC são Fichas do Zodíaco), e o emissor de ativos (já que muitas contas podem emitir o mesmo ativo). Observe também o tipo de ativo (crédito_alphanum4).
A segunda entrada acima é a única diferente tipo de ativo na lista (nativo). Nesse caso, é um saldo base no nível da conta, o token nativo da carteira Lobstr do proprietário, nesse caso Lumens estelares (XLM). Esse saldo pode ser trocado por saldos de qualquer outro ativo e vice-versa por meio da conta de negociação de ativos.
Planejamento do nosso fluxo de trabalho
Com o exposto acima em mente, podemos planejar como armazenar e acessar todas as informações de nosso interesse. Então, no que estamos interessados?
Primeiro, estamos interessados em uma atualização diária das estatísticas sobre a conta. Portanto, suponha que executaremos nosso script diariamente e atualizaremos as informações no banco de dados.
Será bom saber os saldos atuais, inclusive o valor nativo de XLM e os saldos de outros tokens. Desde que mantenhamos esses detalhes nos documentos que armazenamos, poderemos consultá-los a qualquer momento. Também teremos que nos certificar de que nossa chave seja uma espécie de carimbo de data/hora ou ID incremental para que nossos documentos não sejam substituídos por entradas mais recentes.
Também poderíamos fazer alguns cálculos intermediários para manter outro documento atualizado com os totais da base, etc., mas deixaremos isso para uma postagem futura.
As próximas duas etapas são fazer o download desse documento JSON e carregá-lo no Couchbase. Em seguida, veremos o resultado na interface do usuário do Console da Web e testaremos as consultas e os gráficos.
Download de dados de contas Stellar com Python
Este é, reconhecidamente, um exemplo muito simples que podemos desenvolver nas próximas semanas.
Para acessar uma API da Web, usamos o módulo de solicitações do Python e armazenamos os resultados em um 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) |
Incluo um exemplo de loop simples para mostrar como é fácil se você quiser vê-lo impresso de uma forma bem feia. Há técnicas de impressão mais bonitas, mas usaremos as que estão incorporadas no Couchbase para facilitar o processo, em vez de escrever mais código aqui.
Envio de documento JSON para o Couchbase
Em seguida, usamos o objeto do nosso bucket do Couchbase e fazemos uma chamada de upsert. Upsert é o mesmo que um comando de inserção de documento ou banco de dados, mas atualizará qualquer documento existente, se ele já existir. No nosso caso, também queremos gerar um ID exclusivo e usá-lo como ID do documento.
Vamos adicionar um carimbo de data/hora unix usando o tempo e criar uma chave, conforme mostrado no guia de introdução do Python SDK, que também inclui algumas capturas básicas de exceções.
Juntando tudo
Agora, vamos dar um passo atrás e examinar o exemplo de código consolidado criado com várias funções para ajudar a compartimentar tudo e torná-lo um pouco mais reutilizável.
|
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) |
O resultado listará o URL da API da Web que foi usado e mostrará um erro ou a mensagem Resultado da operação Detalhes:
|
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 os resultados do token no console da Web
Depois de executar o script algumas vezes, você deverá ter alguns documentos no bucket do projeto. Quando você tiver selecionado o estelar balde, pressione o botão Documentos (canto superior direito) para ver uma lista de documentos com os quais você pode interagir, um resultado é mostrado na Figura 5.
Figura 5. Exemplo de documento de conta Stellar aberto no console da Web do Couchbase.
Para permitir a consulta, precisamos criar alguns índices. Alterne para o índice Consulta e insira o seguinte N1QL para configurar alguns índices. Observe que estamos usando uma coleção padrão de documentos, portanto, colocamos um prefixo no nome do bucket para indicar isso. (Em uma postagem futura, separaremos nossos documentos para diferentes finalidades e usaremos coleções para isso).
|
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 um dos diferentes ativos:
|
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); |
Em seguida, teste o índice com uma consulta básica:
|
1 |
select count(*) from stellar; |
O Resultados deve mostrar uma saída básica com o número de documentos no compartimento, nesse caso, 7 documentos, conforme mostrado na Figura 6.
Figura 6. Exemplo de consulta para contar os documentos no compartimento.
Consulta de atributos em um conjunto de documentos JSON
Você pode criar consultas facilmente, pois o N1QL é muito semelhante ao SQL padrão, mas com a inteligência JSON incorporada. Há funções que nos permitem acessar entradas na tabela balanços como se cada uma delas fosse uma coluna. Usando INÚTIL, cada uma das subentradas se torna um nome de campo acessível na consulta.
Por exemplo, a consulta a seguir lista todos os ativos e saldos:
|
1 2 3 |
SELECT balances.balance AS balance, balances.asset_code FROM stellar UNNEST balances |
A janela de consulta mostra os resultados em JSON por padrão, mas você pode alternar para a opção Tabela e ver nossos resultados até o momento:
Próximas etapas
Em nosso próximo post, vamos nos aprofundar e criar alguns gráficos e usar mais magia de consulta.
Aqui estão alguns links adicionais para ler sobre os tópicos que discutimos:
- Comece a usar o Couchbase Python SDK
- Folha de verificação do Couchbase N1QL (PDF)
- Bolsa descentralizada Stellar (stellar.org)
- Noções básicas de blockchain
- Documentos da API do desenvolvedor Stellar (contas)
- Stellar Lumens - XLM - o token do futuro
