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 tubulação instalar --atualização tubulação ferramentas de configuração roda |
Teste a instalação iniciando o Python e importando o módulo Couchbase:
|
1 2 3 4 5 |
tyler@megaserv:python-estelar$ python3 Python 3.8.10 (padrão, Nov 26 2021, 20:14:08) [GCC 9.3.0] em linux Tipo "ajuda", "copyright", "créditos" ou "licença" para mais informações. >>> importação 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 |
de couchbase.agrupamento importação Aglomerado, ClusterOptions de couchbase.autenticação importação PasswordAuthenticator agrupamento = Aglomerado('couchbase://localhost', ClusterOptions( PasswordAuthenticator("Administrador, "Administrador))) cb = agrupamento.balde("estelar) |
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 |
importação solicitações url = "https://horizon.stellar.org/accounts/GAF55XSX3WCHWUB6CEGSKKMLPKV56Y5MK4UCBRSSGRBBDENFEXSWWMDQ/" resposta = solicitações.solicitação("GET", url) jsondoc = resposta.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 |
importação solicitações, tempo de couchbase.agrupamento importação Aglomerado, ClusterOptions de couchbase.autenticação importação PasswordAuthenticator conta = 'GAF55XSX3WCHWUB6CEGSKKMLPKV56Y5MK4UCBRSSGRBBDENFEXSWWMDQ' def conectar(): agrupamento = Aglomerado('couchbase://localhost', ClusterOptions(PasswordAuthenticator("Administrador, "Administrador))) retorno agrupamento.balde("estelar) def getjson(): url = "https://horizon.stellar.org/accounts/%s/" % conta impressão("Fetching: " + url) resposta = solicitações.solicitação("GET", url) retorno resposta.json() def upsert_document(conexão, doc): agora = int( tempo.tempo() ) tentar: chave = str(agora) + "_" + conta[:5] resultado = conexão.upsert(chave, doc) impressão(resultado) exceto Exceção como e: impressão("Erro",e) cb = conectar() 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 aplicativo.py Buscando: https://horizon.stellar.org/accounts/GAF55XSX3WCHWUB6CEGSKKMLPKV56Y5MK4UCBRSSGRBBDENFEXSWWMDQ/ Resultado da operação<rc=0x0, chave='1644906573_GAF55', cas=0x16d3e1d051760000, contexto de rastreamento=0, saída de rastreamento=Nenhum> |
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 |
criar primário índice em padrão:estelar; criar índice idx_account_id em padrão:estelar(id); criar índice idx_modified em padrão:estelar(last_modified_time); criar índice idx_entrycount em estelar(subentry_count); |
Para cada um dos diferentes ativos:
|
1 2 3 4 |
criar índice idx_asset_code em estelar(balanços.código do ativo); criar índice idx_asset_type em estelar(balanços.tipo de ativo); criar índice idx_asset_issuer em estelar(balanços.emissor de ativos); criar índice idx_asset_balance em estelar(balanços.equilíbrio); |
Em seguida, teste o índice com uma consulta básica:
|
1 |
selecionar contagem(*) de estelar; |
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 |
SELECIONAR balanços.equilíbrio AS equilíbrio, balanços.código do ativo DE estelar INÚTIL balanços |
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
