Avançar para o conteúdo principal

Serviço de Atestado

Como configurar, executar e gerenciar um serviço de atestado como um validador de Celo.

Nova atualização (em janeiro de 2023)

Validadores que participam do protocolo de atestado:

  • pode desativar suas instâncias de Serviço de Atestado imediatamente incluindo todos os nós completos e assinaturas de API SMS (ou seja, Twilio, Nexmo e MessageBird) que os suportam
  • deve permanecer os assinantes do certificado na cadeia até o Q1 2023 quando uma proposta de governança será votada para fazer o contrato de somente leitura dos Atestados
  • mais informações sobre o post no fórum

O que é um Serviço de Atestado?​

O Serviço de Atestado faz parte do protocolo de identidade de Celo. Ele envia SMS em nome dos usuários para permitir que eles atestem ter acesso a um número de telefone e mapeie-o a uma conta de Celo segura e privada. Pode ser visto nos passos 3 e 4 neste diagrama:

Os validadores recebem uma taxa (definida por governo on-chain, atualmente 0.05 cUSD) para cada certificado que processam e que é então resgatado com sucesso na cadeia pelo usuário. Os validadores podem reivindicar e retirar esta taxa usando: celocli identity:withdraw-attestation-rewards.

Esboços​

Este guia o leva até a configuração de um serviço de atestado:

  • Siga as instruções para configurar um validador no mainnet ou baklava
  • Configurar Twilio, MessageBird e Nexmo, provedores de SMS utilizados pela Attestation Service
  • Gerar e registrar uma chave de certificado
  • (para versões anteriores à 1.4.0) Implantar um nó completo de Celo com a chave de assinatura do certificado desbloqueada
  • Implantar o serviço de atestado
  • Configurar e publicar metadados do validador para que os clientes possam encontrar o seu serviço de atestado
  • Configurar monitoramento para o serviço de certificado e o nó completo (se aplicável)
Se você tiver quaisquer perguntas ou comentários depois de ler a documentação, Sinta-se à vontade para compartilhá-los conosco no GitHub: celo-org > identity > Discussions. Nós teremos prazer em responder para você e :::

Versões Recentes​

Arquitetura de Implantação​

O Serviço de Atestado precisa expor um endpoint HTTP ou HTTPS à Internet pública. Isto significa que não deve ser implantado no mesmo host físico que um Validador, que deve ser bombeado para permitir conexões de entrada apenas de seu proxy.

A variável de ambiente PORT define a porta de escuta do serviço na instância local. Observe que, dependendo da sua configuração, isso pode ser diferente da porta exposta à Internet pública.

O Serviço de Atestado expõe um ponto de extremidade HTTP, mas é altamente recomendável que você adote uma configuração que implemente o TLS. Serviço de atestado deve expor as seguintes rotas na Internet pública: POST /attestations, POST /test_attestations, GET /get_attestations, POST /delivery_status_nexmo, (v1.5. +) POST /delivery_status_twilioverificar, (v1.5.0+) POST /delivery_status_twiliomessaging, (pré-v1. .0) POST /delivery_status_twilio, e (v1.2.0+) GET (não POST) /delivery_status_messagebird. Ele também deve expor GET /status. Opcionalmente, você pode optar por expor os GET /healthz e GET /metrics. Note que a URL fornecida no validador de metadados não deve incluir nenhum destes sufixos.

Da versão 1.4.0 em diante, há duas maneiras de implantar o Serviço de Atestado. Recomendamos que os novos validadores usem o método de keystore (em vez de usar um nó completo de Celo) para gerenciamento de chaves, e os validadores existentes eventualmente migram para a nova arquitetura.

Um Serviço de Atestado antes da versão 1.4.0 normalmente é implantado ao lado de uma instância completa do node do Celo que precisa ter a chave assinante do certificado desbloqueada. Isto pode ser usado na mesma máquina física ou em uma VM ou em um container em um host diferente.

Ainda é possível usar o método completo de nó descrito abaixo, da versão 1.4. em vez disso, é recomendado implantar o Serviço de Atestado com acesso a um arquivo keystore que criptografa a chave da assinatura do atestação. Isto permite que o serviço assine certificados localmente em vez de dependendo da instância separada do nó para assinar certificados. A senha para descriptografar o arquivo keystore deve ser passada como uma variável de ambiente ao iniciar o Serviço de Atestação. Pelo menos um Provedor de Celo (variável de ambiente CELO_PROVIDERS (recomendado) ou CELO_PROVIDER) é atualmente necessária. a fim de conectar ao ContractKit e ler as informações necessárias da cadeia. Listar alguns provedores de acesso é recomendado, como se o primeiro nó estivesse atrás ou sincronizado, o Serviço de Atestação usará um dos nós de backup listados. Mais detalhes sobre isso estão na Execução do Serviço de Atestado v1.4.0 + seção abaixo. Espera-se que o novo método de assinatura reduza os erros de Serviço de Atestado devido ao nó completo não estar sendo sincronizado e geralmente reduzir a sobrecarga de operação.

O Serviço de Atestado é um serviço sem estado que usa uma base de dados para persistir no status de tentativas de entrega de SMS atuais e recentemente concluídas. A arquitetura de implantação mais simples é ter uma única máquina ou VM executando três contêineres (duas para as versões 1.4. onwards): um serviço de atestação, um nó Celo Blockchain (somente para versões anteriores a 1.4.0) e uma única instância de banco de dados.

Para uma configuração de alta disponibilidade, várias instâncias podem ser implantadas atrás de um balanceador de carga e compartilhar um único serviço de banco de dados. O balanceador de carga deve ser configurado com uma política de roteamento em rodízio usando o endpoint /healthz da instância. Implantar uma instalação de um banco de dados de alta disponibilidade está além do escopo destas instruções, mas é direto com a maioria dos provedores da nuvem. Nesta configuração, se um relatório de entrega para um SMS emitido por uma instância for recebido por outra instância essa instância pode identificar o registro correspondente no banco de dados compartilhado e atuar sobre o recibo para reenviar, se necessário.

Todos os registros na base de dados incluem o emissor validador em sua chave, para que uma única configuração como a acima possa ser usada para fornecer certificados para vários validadores.

Provedores de SMS​

Atualmente o Serviço de Atestado suporta três provedores de SMS:

  • Twilio
    • da v1.5., o Serviço de Atestado trata o Twilio Messaging Service (twiliomessaging) e a Twilio Verify API (twilioverific) como provedores separados.
  • Nexmo
  • MessageBird (da versão 1.2.0 e posterior)

É recomendável que você se inscreva com todas as três.

Consulte a seção de configuração para obter informações sobre como especificar opções de configuração.

Twilio​

Após se inscrever no Twilio em https://www.twilio. om/try-twilio, você deve ver o seu ACCOUNT SID e o seu AUTH_TOKEN no canto superior direito do console. Você também precisará inserir um cartão de crédito para financiar a conta. Para a maioria das mensagens de texto, os custos geralmente são muito baixos (e significativamente inferiores à taxa de certificado paga pelo usuário). Encontre uma lista de preços mais abrangente em https://www.twilio.com/sms/pricing. Se houver países que você não quer servir, pode especificá-los com a opção de configuração TWILIO_UNSUPPORTED_REGIONS.

Em seguida, ajuste as configurações do Geo para atender números de telefone globalmente em https://www.twilio.com/console/sms/settings/geo-permissions. Caso contrário, o serviço não será capaz de enviar SMS para a base de usuário global da Celo e o seu validador terá um impacto negativo na experiência do usuário Celo.

Para realmente conseguir enviar SMS, você precisa criar um serviço de mensagens via SMS Programmable > SMS. Forneça o SID resultante na variável de configuração TWILIO_MESSAGING_SERVICE_SID.

Agora que você já forneceu o seu serviço de mensagens, você precisa comprar pelo menos 1 número de telefone para enviar SMS. Você pode fazê-lo sob a opção Números da página de serviço de mensagens. É altamente recomendável que você compre pelo menos um número de EUA (+1) que parece fornecer altas taxas de sucesso. Se você comprar números em outras localidades, o Twilio selecionará inteligentemente o melhor número para enviar cada SMS.

Verify Service (post v1.4.0)​

Estamos no processo de transição para Serviço de Verificação do Twilio, que gerenciará automaticamente um conjunto de números de telefone para o alcance global. Crie um Serviço de Verificação no Portal Twilio navegando para Verificar e clique + para criar um novo serviço. É importante fornecer Celo como o nome amigável do serviço, já que isso vai aparecer no conteúdo da mensagem de texto.

  1. Defina o comprimento do código como 8 dígitos.
  2. Digite sell-oh no nome TTS SERVICE NAME.
  3. Ativar SMS, CALLe E-MAIL canais de entrega.

Depois de criar o serviço de confirmação, você deve criar um ticket para ativar o código personalizado. Forneça suporte a sua nova verificação de SID e solicite ativar o código personalizado. Monitore sua resposta e responda a qualquer pergunta de acompanhamento.

Modelo de pedido de ticket suporte

Olá, eu gostaria de habilitar códigos personalizados para nossa API de verificação com SID {YOUR_VERIFY_SID}. Sei que seremos cobrados por cada tentativa de verificação do usuário.

Depois que o Twilio habilita códigos personalizados, você verá a seguinte propriedade no painel Twilio ao visualizar seu serviço de verificação:

Custom Code Property

Uma vez que você tenha a confirmação de que códigos personalizados são ativados na sua conta Twilio, você pode fornecer a variável de configuração SID resultante na variável TWILIO_VERIFY_SERVICE_SID e iniciar o serviço. Uma vez que existem alguns países para os quais o Serviço de Mensagens supera consistentemente o Serviço de Verificação (e vice-versa), da versão v1.5. a seguir, tratamos a aplicação Mensagens e Verificar serviços como provedores SMS separados, que podem ser especificados como twiliomessaging e twilioverific, respectivamente. Esses provedores podem ser especificados por país; ou seja, você poderia especificar o Serviço de Mensagens a ser usado em um determinado país definindo SMS_PROVIDERS_X=twiliomessaging,nexmo,... (Observe que twilio continuará a funcionar como abreviação de twiliomessaging,twilioverify, para manter a compatibilidade com versões anteriores.)

Para enviar mensagens para os EUA, nós recomendamos o uso da verificação de API Twilio (provedor: twilioverify) em oposição ao serviço de mensagens para cumprir com os regulamentos 10DLC (isso pode ser especificado na variável SMS_PROVIDERS_US). Caso contrário, você poderá precisar registrar sua marca para evitar tarifas.

Nexmo​

Depois de se inscrever para o Nexmo, clique no saldo no canto superior esquerdo para ir para Faturamento e Pagamentos, onde você pode adicionar fundos. É altamente recomendável que você use um cartão de crédito ou débito (ao contrário de outros tipos de pagamentos), já que então você será capaz de ativar a recarga automática. Você também deve habilitar alertas de saldo baixo. Ambas ajudarão a evitar falhas na entrega de SMS quando seus fundos forem esgotados. Parece que estas opções não podem estar imediatamente disponíveis para todas as novas contas devido a verificações de fraude: tente enviar alguns SMS, verificando novamente após alguns dias ou criando uma conta de suporte.

Em Seus Números, crie um número dos EUA e certifique-se de que isso esteja ativado para SMS; este número será usado para enviar mensagens de texto internacionais. Observe que os números Nexmo parecem ter um limite de taxa de 250 SMS por dia. Recomendamos configurar seu Serviço de Atestado para não usar o Nexmo para servir aos EUA (i.. remova nexmo em SMS_PROVIDERS_US). Se você ainda quer fazê-lo, por favor, configure um número de chamada grátis dos EUA de acordo com a orientação aqui e certifique-se de que o seu Serviço de Atestado está funcionando em v1. 0,2+.

Em Configurações, copie a chave API para a variável de ambiente NEXMO_KEY, e o API secret para NEXMO_SECRET.

Se você deseja dividir os números usados nesta conta, você pode optar por criar e configurar uma aplicação Nexmo para cada uma. Em cada aplicativo, ative mensagens (rotuladas como Communicate with WhatsApp, Facebook Messenger, MMS and Viber) e atribua um número. Copie o valor de Application Id de cada aplicativo para o valor de configuração NEXMO_APPLICATION. de cada aplicação. Não há necessidade de gerar ou usar um par de chaves público/privada. Por padrão um Serviço de Atestado irá escolher um número do conjunto global de números não vinculados a uma aplicação Nexmo específica. O único efeito de fornecer NEXMO_APPLICATION é selecionar números daqueles que estão vinculados a esse aplicativo.

Note que a partir da versão 1.2.0, o Serviço de Atestado já não requer que URLs de callback sejam fornecidas no painel Nexmo. Isto significa que é possível suportar vários Serviços de Confirmação usando uma única conta. No entanto, para receber os comprovantes de entrega do Nexmo, é importante atualizar o método HTTP padrão no painel Nexmo para POST-JSON (ver imagem abaixo ou seguir as instruções aqui), desde que o Serviço de Atestado espera atualmente solicitações POST encaminhadas para o terminal /delivery_status_nexmo.

MessageBird​

O suporte ao MessageBird é introduzido na versão 1.2.0 e posterior. Após se cadastrar no MessageBird, localize a sua chave de API (Your API Keys) no Dashboard, clique em Mostrar (Show) ao lado da chave Live, e copie seu valor na variável de configuração MESSAGEBIRD_API_KEY. Clique em Recarga (Top Up) para adicionar crédito. MessageBird requer um número dedicado e/ou aprovação KYC para enviar SMS para certos países que os validadores precisam suportar. Clique em Números e depois Comprar Número para comprar um número. Você precisará comprar números separados para os EUA (veja abaixo) e o Canadá. Em seguida, visite Configurações de SMS (SMS Settings) e solicite aprovação para enviar para esses países. Você pode encontrar orientação sobre o preenchimento das informações necessárias aqui.

Devido às regulamentações de 10DLC a partir de 2021, recomendamos a criação de um número grátis de chamada para servir números nos EUA. Por favor, consulte esta página para obter mais orientações sobre como solicitar um número grátis de chamada e como preencher o formulário necessário. Se você não configurou um número grátis, você deve registrar sua marca de acordo com as instruções aqui OU remover messagebird da sua configuração de SMS_PROVIDERS_US.

O não cumprimento dos regulamentos 10DLC nos EUA pode potencialmente resultar em multas ou em tráfego bloqueado.

:::

Instalação​

Quando necessário, as instruções irão diferenciar entre pre-v1.4.0 (Celo full node para gerenciamento de chaves) e v1.4.0 + (recomendado uso de arquivos de keystore para gerenciamento de chaves). Esta seção usa várias variáveis de ambiente definidas durante a configuração do validador. Você precisará exportar CELO_IMAGE e CELO_VALIDATOR_RG_ADDRESS nesta máquina.

Configurar um Serviço de Atestado primeiro requer uma Chave do Sinalizador de Confirmação para ser registrada (Similar a Chaves de Validador e de Voto assinantes). Para isso, vamos iniciar nosso nó na máquina de Atestado (acompanhe a senha que você usa para essa conta):

# On the Attestation machine
docker run -v $PWD:/root/.celo --rm -it $CELO_IMAGE account new
export CELO_ATTESTATION_SIGNER_ADDRESS=<YOUR-ATTESTATION-SIGNER-ADDRESS>

Vamos gerar o proof-of-possession para o signatário do certificado:

# On the Attestation machine
docker run -v $PWD:/root/.celo --rm -it $CELO_IMAGE account proof-of-possession $CELO_ATTESTATION_SIGNER_ADDRESS $CELO_VALIDATOR_RG_ADDRESS

Com esta prova, autorize o signatário do certificado em sua máquina local:

# On your local machine
export CELO_ATTESTATION_SIGNER_SIGNATURE=<ATTESTATION-SIGNER-SIGNATURE>
export CELO_ATTESTATION_SIGNER_ADDRESS=<YOUR-ATTESTATION-SIGNER-ADDRESS>
celocli releasegold:authorize --contract $CELO_VALIDATOR_RG_ADDRESS --role attestation --signature 0x$CELO_ATTESTATION_SIGNER_SIGNATURE --signer $CELO_ATTESTATION_SIGNER_ADDRESS

Configurando Gestão de Chaves​

(recomendado) v1.4.0+ - Usando arquivos do Keystore​

Não é mais necessário executar um nó completo ao lado do Serviço de Atestado. Em vez disso, salve o caminho para o diretório de keystore gerado acima e a senha usada ao criar o CELO_ATTESTATION_SIGNER_ADDRESS acima, como você precisará quando executar o serviço:

export KEYSTORE_PARENT_DIR=$PWD
echo <CELO-ATTESTATION-SIGNER-PASSWORD> > $KEYSTORE_PARENT_DIR/.password

Em seguida, siga as instruções na seção Funcionando com o Serviço de Confirmação abaixo.

pre-v1.4.0 - Usando Nó Completo de Celo​

Agora você pode executar o node para o serviço de atestado em segundo plano com o seguinte comando. Lembre-se de especificar a senha que você usou durante a criação do CELO_ATTESTATION_SIGNER_ADDRESS. E, se você deseja executar o serviço de atestado para Baklava, adicione o sinalizador --baklava.

# Na máquina de atestado
echo <CELO-ATTESTATION-SIGNER-PASSWORD> > .password
docker run --name celo-attestations -it --restart always --stop-timeout 300 -p 127.0.0.1:8545:8545 -v $PWD:/root/.celo $CELO_IMAGE --verbosity 3 --syncmode full --http --http.addr 0.0.0.0 --http.api eth,net,web3,debug,admin --unlock $CELO_ATTESTATION_SIGNER_ADDRESS --password /root/.celo/.password --allow-insecure-unlock

Configuração do banco de dados​

Para armazenar e recuperar as solicitações de atestado, o serviço precisa de um banco de dados para manter essas informações. Atualmente sqlite, postgres e mysql são suportados. Para fins de teste, você pode usar sqlite, mas é recomendável executar um servidor de banco de dados autônomo usando mysql ou postgres se sua intenção for executar o Atestado Atendimento em ambiente de produção. Se você estiver executando em um provedor de nuvem popular, considere usar seus serviços SQL hospedados.

Dependendo da tecnologia da sua base de dados, é necessário criar uma base de dados com o acesso de um usuário e senha específicos.

Para especificar a url do banco de dados você precisa configurar a variável DATABASE_URL de uma dessas maneiras:

# Na máquina de atestado
export DATABASE_URL="sqlite://db/attestation.db"
export DATABASE_URL="mysql://user:password@mysql.example.com:3306/attestation-service"
export DATABASE_URL="postgres://user:password@postgres.example.com:5432/attestation-service"

Exemplo de configuração de um banco de dados de postgres local no Ubuntu:

apt install postgresql
sudo -u postgres createdb attestation-service
sudo -u postgres psql -c "ALTER USER postgres PASSWORD '<DATABASE_PASSWORD>';"
export DATABASE_URL="postgres://postgres:<DATABASE_PASSWORD>@localhost:5432/attestation-service"

Configuração​

Serviço de atestado pode usar sua configuração de um arquivo que pode ser especificado usando a variável de ambiente CONFIG. É altamente recomendável que você comece usando o arquivo de configuração do Attestation Service modelo, que contém padrões sensatos e atualizados, especialmente para SMS_PROVIDERS_<country>:

# Escolha um local para a configuração e busque os padrões
export CONFIG=/path/to/attestation-service-config
curl https://raw.githubusercontent.com/celo-org/celo-monorepo/master/packages/attestation-service/config/.env.development >$CONFIG

Linhas que começam # são tratadas como comentários. Além disso, quaisquer opções especificadas como variáveis de ambiente substituem valores fornecidos neste arquivo.

Opções exigidas:

VariávelExplicação
DATABASE_URLA URL para acessar o banco de dados local, por exemplo, sqlite://db/attestations.db
CELO_PROVIDERS(v1.4.0+) Recomendado sobre o CELO_PROVIDER; apenas um dos dois pode ser usado. Uma lista de URLs de nós Celo priorizados usados para se conectar à cadeia. 2-3 provedores são recomendados.
CELO_PROVIDER(obrigatório antes da versão 1.4.0; não recomendado da versão 1.4.0+) O URL do nó para o nó completo local no qual a chave do signatário do atestado está desbloqueada. e.g. http://localhost:8545. Não exponha esta porta à internet pública! (v1.4.0+ opcional) URL do nó Celo usado para conectar à cadeia.
CELO_VALIDATOR_ADDRESSEndereço da conta de validador. Se o Validator for implantado por meio de um contrato ReleaseGold, este é o endereço do contrato (ou seja, $CELO_VALIDATOR_RG_ADDRESS), não o beneficiário.
ATTESTATION_SIGNER_ADDRESSEndereço da chave do signatário do atestado do Validador
SMS_PROVIDERSLista separada por vírgulas de todos os provedores de SMS habilitados. Pode incluir twilio, nexmo. Da v1.2.0, pode incluir messagebird. Recomenda-se listar nexmo por último se estiver configurado. A partir da v1.5.0, pode incluir twiliomessaging e twilioverify em vez de twilio. Os provedores são tentados do primeiro ao último, a menos que SMS_PROVIDERS_RANDOMIZED seja definido como 1, caso em que eles são tentados em uma ordem aleatória.

Variáveis de ambiente opcionais:

VariávelExplicação
ATTESTATION_SIGNER_KEYSTORE_DIRPATH(v1.4.0+) Caminho para o diretório keystore que contém a chave privada criptografada de ATTESTATION_SIGNER_ADDRESS. Deve ser usado com ATTESTATION_SIGNER_KEYSTORE_PASSPHRASE.
ATTESTATION_SIGNER_KEYSTORE_PASSPHRASE(v1.4.0+) Senha usada para criptografar o arquivo de armazenamento de chaves de ATTESTATION_SIGNER_ADDRESS. Deve ser usado com ATTESTATION_SIGNER_KEYSTORE_DIRPATH
PORTPorta para escutar. Default 3000.
RATE_LIMIT_REQS_PER_MIN(v1.2.0+) Solicitações por minuto em todos os endpoints antes de novas solicitações são limitadas por taxa. Default 100.
SMS_PROVIDERS_<country>Substituir para definir provedores de SMS e solicitar um código de país específico (por exemplo, SMS_PROVIDERS_MX=nexmo,twilio). Nós recomendamos muito usar o arquivo de configuração padrão como base e, em seguida, fazer as alterações apropriadas.
SMS_PROVIDERS_RANDOMIZED(v1.2.0+) Se definido como 1 e nenhum provedor específico de país estiver configurado para o país do número solicitado, randomize a ordem dos provedores padrão. Default 0. Observação: definir isso como 1 só é recomendado se você não tiver o Vonage/Nexmo configurado como um provedor.
MAX_DELIVERY_ATTEMPTSNúmero de tentativas totais de entrega ao enviar SMS. Cada tentativa tenta o próximo fornecedor disponível no pedido especificado. Se omitido, a opção descontinuada MAX_PROVIDER_RETRIES será usada. O valor padrão é 3.
MAX_REREQUEST_MINSNúmero de minutos durante os quais o cliente pode resolicitar o mesmo certificado. O valor padrão é 55.
EXTERNAL_CALLBACK_HOSTPORTForneça a URL externa completa a partir da qual o serviço pode ser alcançado, geralmente o mesmo que o valor da requisição de ATTESTATION_SERVICE_URL no seu metadado. Esse valor, mais um sufixo por exemplo /delivery_status_twilioverificar será a URL na qual o serviço pode receber chamadas de recibo de entrega. Se este valor não estiver definido, e VERIFY_CONFIG_ON_STARTUP=1 (o padrão), a URL será tirada dos metadados do validador. Caso contrário, terá de ser fornecida.
VERIFY_CONFIG_ON_STARTUPRecuse-se a iniciar se o signatário ou os metadados estiverem configurados incorretamente. Default 1. Se você desativar isso, você deve especificar EXTERNAL_CALLBACK_HOSTPORT.
MAX_AGE_LATEST_BLOCK_SECS(v1.2.0+) Idade máxima do último bloco recebido, em segundos, antes da verificação de integridade relatar falha. Padrão é 20.
GET_BLOCK_TIMEOUT_MS(v1.4.0+) Tempo máximo em milissegundos para esperar após buscar o último bloco de uma conexão, antes que o tempo limite seja atingido. O padrão é 500 ms.
DISABLE_SMART_FALLBACK(v1.4.0+) Se true, não tentará selecionar o provedor mais atualizado para cada chamada, mas ainda tentará chamadas com falha com o(s) backup(s). O padrão é false.
DB_RECORD_EXPIRY_MINSTempo em minutos antes que um registro de um atestado no banco de dados possa ser excluído. Padrão 60 minutos.
LOG_LEVELUm de fatal, error, warn, info, debug, trace
LOG_FORMATUm de json, human, stackdriver
APP_SIGNATUREUm valor que é mostrado no campo chave appSignature no terminal /status que você pode usar para identificar várias instâncias.

Opções de configuração Twilio:

VariávelExplicação
TWILIO_ACCOUNT_SIDO ID da conta Twilio
TWILIO_MESSAGING_SERVICE_SIDO ID do serviço de mensagem Twilio. Inicia com MG
TWILIO_VERIFY_SERVICE_SIDO ID de Serviço de Verificação Twilio. Inicia com VA
TWILIO_AUTH_TOKENO token de autenticação API
TWILIO_UNSUPPORTED_REGIONSOpcional. Uma lista separada por vírgulas de códigos de países para não servir, valor recomendado CU,SY,KP,IR,SD

Opções de configuração Nexmo:

VariávelExplicação
NEXMO_KEYA chave da API para a API Nexmo
NEXMO_SECRETA senha da API para a API Nexmo
NEXMO_APPLICATIONOpcional. Use apenas números ligados à aplicação Nexmo com a ID correspondente, ao invés do pool global.
NEXMO_UNSUPPORTED_REGIONSOpcional. Uma lista separada por vírgulas de códigos de países para não servir, valor recomendado CU,SY,KP,IR,SD
NEXMO_ACCOUNT_BALANCE_METRICOpcional. Desativado por padrão. Se definido como 1, os saldos Nexmo serão publicados sob a métrica attestation_provider_balance.

Opções de configuração do MessageBird (v1.2.0+):

VariávelExplicação
MESSAGEBIRD_API_KEYA chave da API para a API MessageBird
MESSAGEBIRD_UNSUPPORTED_REGIONSOpcional. Uma lista separada por vírgulas de códigos de países para não servir, valor recomendado CU,SY,KP,IR,SD

Registrando Metadados​

Celo usa Metadados para permitir que as contas façam certas reivindicações sem ter que fazer isso na cadeia. Os usuários podem usar qualquer endereço de assinante autorizado para fazer reivindicações em nome da conta registrada. Por conveniência, este guia usa o CELO_ATTESTATION_SIGNER_ADDRESS, mas qualquer assinante autorizado funcionará. Observe que os metadados precisam ser recriados se a assinatura da chave for alterada; é recomendável não usar o endereço do assinante do validador, pois essa chave geralmente é rotacionada com mais regularidade.

Para concluir o processo de metadados, precisamos reivindicar de qual URL os usuários podem solicitar atestados. Execute os seguintes comandos em sua máquina local. Esta seção usa várias variáveis de ambiente definidas durante a configuração do validador.

# Na sua máquina local
celocli account:create-metadata ./metadata.json --from $CELO_VALIDATOR_RG_ADDRESS

A variável CELO_ATTESTATION_SERVICE_URL armazena a URL para acessar o Serviço de Atestado implantado. No comando a seguir especificamos a URL onde está esse Serviço de Atestado. Note que o URL fornecido no validador de metadados deve ser o caminho base no qual o serviço está acessível; não deve incluir /attestations.

# Na sua máquina local
celocli account:claim-attestation-service-url ./metadata.json --url $CELO_ATTESTATION_SERVICE_URL --from $CELO_ATTESTATION_SIGNER_ADDRESS

Você agora deve hospedar seus metadados em algum lugar acessível via HTTPS. Você pode usar um serviço como gist.github.com. Crie um gist com o conteúdo do arquivo e, em seguida, clique no botão Raw para receber o permalink para o arquivo legível pelo computador.

Agora podemos registrar esta url para que outras pessoas possam ver. Para isso, devemos ter o endereço do beneficiary do contrato ReleaseGold (CELO_VALIDATOR_ADDRESS) desbloqueado.

(Observação: se você usou um Ledger para criar o endereço beneficiary, adicione o sinalizador --useLedger e possivelmente o sinalizador --ledgerAddresses=N ao comando abaixo. O último sinalizador fará com que o livro verifique o número N de endereços, por exemplo --ledgerAddresses=5 faria o Ledger verificar 5 endereços. Não se esqueça de confirmar a transação no seu Ledger depois de iniciá-la através do CLI.)

# Na sua máquina local
celocli releasegold:set-account --contract $CELO_VALIDATOR_RG_ADDRESS --property metaURL --value <METADATA_URL>

Se tudo der certo, os usuários deverão ser capazes de ver suas reivindicações executando:

# Na sua máquina local
celocli account:get-metadata $CELO_VALIDATOR_RG_ADDRESS

Executando o Serviço de Atestado​

Há uma pequena diferença na inicialização do serviço, dependendo da opção de gerenciamento de armazenamento de chaves (arquivos de armazenamento de chaves, nó completo) usada, e ambas são descritas abaixo.

Antes de executar o Serviço de Atestado usando qualquer um dos métodos, verifique se os metadados foram registrados.

Ambas as opções a seguir para executar o serviço de atestado usam --network host para acessar um banco de dados local (funciona apenas no Linux) e escutar conexões na porta 80.

Ambos assumem que todas as opções de configuração necessárias foram adicionadas ao arquivo de configuração localizado em $CONFIG que o Docker processará. Como alternativa, você pode passar o arquivo de configuração para o serviço ler na inicialização usando -e CONFIG=<docker-path-to-config-file> e outras variáveis de ambiente diretamente adicionando argumentos no formato -e DATABASE_URL=$ DATABASE_URL.

Para ambas as opções abaixo, defina a variável de ambiente TAG para determinar qual imagem instalar. Use attestation-service-mainnet para a imagem mais recente adequada para mainnet (conforme abaixo), attestation-service-baklava para a imagem mais recente adequada para baklava ou especifique uma compilação específica conforme fornecido nas notas de lançamento vinculadas acima.

(recomendado) Executando o Serviço de Atestado v1.4.0+​

A principal diferença entre o método antigo de executar o Attestation Service ao lado de um nó completo do Celo é que você precisará garantir que o Docker possa acessar o diretório que contém o keystore que armazena o CELO_ATTESTATION_SIGNER_ADDRESS</0 chave privada de > como um arquivo criptografado. Aqui, <code>keystore significa apenas um diretório (geralmente intitulado "keystore") que contém APENAS arquivos de armazenamento de chaves (arquivos que contêm a chave privada criptografada por senha em um formato específico). Este diretório e arquivos são criados automaticamente por geth ao importar chaves privadas (consulte Usando arquivos de armazenamento de chaves e podem ser usados aqui.

Para fazer isso, você precisa mapear o diretório que contém o keystore para o volume do Docker do Attestation Service e definir a variável de ambiente ATTESTATION_SIGNER_KEYSTORE_DIRPATH para o caminho desse diretório relativo ao contêiner do Docker. Você também precisará definir a variável de ambiente ATTESTATION_SIGNER_KEYSTORE_PASSPHRASE para a senha usada durante a criação do CELO_ATTESTATION_SIGNER_ADDRESS.

Além disso, certifique-se de que a variável de ambiente CELO_PROVIDERS aponte para pelo menos um (recomendado: 2-3 no total) nó Celo que pode ser usado para instanciar ContractKit; pode ser um nó completo separado ou, dependendo de sua configuração, seu nó proxy validador. A variável de ambiente CELO_PROVIDERS é uma lista de valores separada por vírgulas (ex. CELO_PROVIDERS=http://127.0.0.1:8545,https://forno.celo.org). Para usar o nó do proxy do validador, você precisaria permitir o acesso RPC, mas, por motivos de segurança, certifique-se de que ele esteja bloqueado apenas para o Serviço de Atestado. Como alternativa, forneça o endpoint para um nó Celo que você executa ou para um provedor de serviços de nó como Figment Datahub. Ao passar vários provedores para essa variável de ambiente, priorize essa lista pela ordem em que eles devem ser usados para repetir as chamadas com falha. A menos que DISABLE_SMART_FALLBACK seja definido, o Serviço de Atestado também tentará selecionar e usar a conexão mais atualizada para cada chamada.

O comando abaixo ilustra como isso pode parecer, se você usou o comando docker run -v $PWD:/root/.celo --rm -it $CELO_IMAGE conta nova anteriormente nas instruções acima para crie o CELO_ATTESTATION_SIGNER_ADDRESS. Lembre-se de que você definiu KEYSTORE_PARENT_DIR para o diretório de trabalho ($PWD) durante as instruções acima e salvou a senha no arquivo KEYSTORE_PARENT_DIR/.password. Observe que $KEYSTORE_PARENT_DIR/keystore deve conter APENAS arquivos keystore (sem subdiretórios ou outros tipos de arquivo). As variáveis de ambiente podem ser definidas em $CONFIG< /1> ou passado para o comando <code>docker run diretamente usando o sinalizador -e. (Neste exemplo, duas dessas variáveis são passadas por meio do sinalizador -e para maior clareza.)

# Vamos mapear $KEYSTORE_PARENT_DIR:DOCKER_VOLUME_PATH mais tarde
export VOLUME_DIRPATH=/root/.celo

# Na máquina de atestado
export TAG=attestation-service-mainnet
docker run --name celo-attestation-service -it --restart always --entrypoint /bin/bash --network host --env-file $CONFIG -v $KEYSTORE_PARENT_DIR:$VOLUME_DIRPATH -e PORT=80 -e ATTESTATION_SIGNER_KEYSTORE_PASSPHRASE=$(cat $KEYSTORE_PARENT_DIR/.password) -e ATTESTATION_SIGNER_KEYSTORE_DIRPATH=$VOLUME_DIRPATH -p 80:80 us.gcr.io/celo-testnet/celo-monorepo:$TAG -c " cd /celo-monorepo/packages/attestation-service && yarn run db:migrate && yarn start "

Executando o serviço de atestado anterior à v1.4.0​

Primeiro, certifique-se de que o seu nó local está totalmente sincronizado:

# Na máquina Attestation, se estiver usando um nó completo Celo para gerenciamento de chaves
sudo celocli node:synced --node geth.ipc

Em seguida, inicie o Serviço de Atestado executando:

# Na máquina de atestado
export TAG=attestation-service-mainnet
docker run --name celo-attestation-service -it --restart always --entrypoint /bin/bash --network host --env-file $CONFIG -e PORT=80 -p 80:80 us.gcr.io/celo-testnet/celo-monorepo:$TAG -c " cd /celo-monorepo/packages/attestation-service && yarn run db:migrate && yarn start "

Recibos de entrega​

O Attestation Services oferece suporte a recibos de entrega para que os provedores de SMS possam retornar a chamada para fornecer informações de entrega. Isso aciona novas tentativas conforme necessário, mesmo entre provedores, e permite que o sucesso da entrega e as métricas de tempo sejam registradas e disponibilizadas ao cliente.

Não há nenhuma configuração necessária para ativar os recibos de entrega Twilio ou Nexmo. O Serviço de Atestado usa o URL nos metadados do validador, desde que VERIFY_CONFIG_ON_STARTUP esteja ativado. A URL para callbacks pode sempre ser especificada com a opção de configuração EXTERNAL_CALLBACK_HOSTPORT. O serviço anexa /delivery_status_{PROVIDER} (ou seja, /delivery_status_twilioverify) ao URL e o fornece ao provedor por meio de sua API.

Para MessageBird, forneça o URL de retorno (certifique-se de incluir /delivery_status_messagebird) nas configurações da API do painel MessageBird página.

Se você estiver usando um balanceador de carga na frente do Attestation Service com uma configuração de roteamento baseada em URL, tome cuidado para evitar que essas rotas sejam filtradas.

Endpoint de teste​

O Serviço de Atestado fornece um endpoint de teste.

Você pode executar o seguinte comando reference para testar um serviço de atestado e enviar um SMS para você mesmo:

celocli identity:test-attestation-service --from $CELO_ATTESTATION_SIGNER_ADDRESS --phoneNumber <YOUR-PHONE-NUMBER-E164-FORMAT> --message <YOUR_MESSAGE> [--provider <PROVIDER>]

Você precisa da chave do signatário do atestado disponível e desbloqueada em sua máquina local.

Você pode querer fazer isso uma vez para cada provedor que você configurou (ou seja, --provider=messagebird). Se a opção provider não for reconhecida, atualize celocli.

Para twilio, observe o seguinte para testar o SMS versus a API de verificação da v1.5.0 em diante:

  • --provider=twilioverify (v1.5.0+)
  • --provider=twiliomessaging (v1.5.0+)
  • --provider=twilio (up to v1.4.0)

Observe que isso não usa um caminho de código idêntico para atestados reais (uma vez que exigem um estado específico na cadeia), portanto, esse ponto de extremidade não deve ser usado no lugar de logs e métricas de monitoramento.

Você deve receber um SMS, e o Serviço de Atestado deve registrar mensagens indicando que a mensagem foi Sent e então, se os relatórios de entrega puderem ser feitos com sucesso, Delivered. Dependendo do provedor, você pode receber vários retornos de chamada à medida que a mensagem avança pela rede.

Se isso funcionar, seu serviço de atestado deverá ser implantado com sucesso!

Monitoramento​

É importante monitorar o Serviço de Atestado e, se estiver usando um nó completo para gerenciamento de chaves, também monitorar o nó completo do qual ele depende.

Logs​

O Serviço de Atestado fornece logs estruturados no formato JSON.

Healthcheck​

O endpoint /healthz responderá com o status 200 quando todas as condições a seguir forem verdadeiras: a chave do signatário do atestado está disponível e desbloqueada, o nó não está sincronizando, o último bloco está recentes e o banco de dados está acessível. Caso contrário, ele responderá com o status 500.

Use esse endpoint ao configurar um balanceador de carga na frente de várias instâncias. Os resultados da última verificação de saúde são reportados através da métrica attestation_service_healthy.

Serviço de Atestado também tem um /status endpoint para informações de configuração.

Métricas​

O Serviço de Atestado expõe as seguintes métricas de formato Prometheus em /metrics para atestados feitos. Por favor, note que as métricas são por instância.

Observe que o monitoramento de endpoints incluindo métricas são expostos como um caminho na porta de host habitual. Isso significa que eles são públicos por padrão. Se quiser que as métricas sejam apenas internas, você precisará configurar um balanceador de carga adequadamente.

Métricas para o serviço:

  • attestation_service_healthy: Medidor com valor 0 ou 1 indicando se a instância falhou ou passou em sua última verificação de integridade. As chamadas para /healthz atualizam esse medidor e o processo também executa uma verificação de integridade em segundo plano a cada minuto. É altamente recomendável que você monitore esta métrica.

Métricas para solicitações de atestado:

  • attestation_requests_total: Contador para o número de pedidos de atestado.

  • attestation_requests_rerequest: Contador para o número de re-solicitações de atestado. Um cliente que solicita novamente o mesmo atestado é semelhante ao serviço que recebe uma notificação de falha na entrega.

  • attestation_requests_already sent: Contador para o número de solicitações de certificado que foram recebidas, mas descartadas porque os registros do banco de dados local que já foram concluídos.

  • attestation_requests_wrong_issuer: Contador para o número de pedidos de atestado que foram recebidos mas descartados porque eles especificaram o validador incorreto.

  • attestation_requests_without_incomplete_attestation: Contador para o número de solicitações de atestado recebidas, mas ao consultar o blockchain, nenhum atestado incompleto correspondente poderia ser encontrado.

  • attestation_requests_valid: Contador para o número de solicitações recebidas que são para o emissor correto e existe um atestado incompleto.

  • attestation_requests_attestation_errors: O contador para o número de solicitações para as quais produziu o atestado failed. Isso pode ser devido a um número de telefone ou salt que não corresponde ao hash, ou o atestado foi registrado menos de 4 blocos atrás.

  • attestation_requests_unable_to_serve: Contadores para o número de solicitações que não puderam ser atendidas porque nenhum provedor SMS foi configurado para o número de telefone na solicitação. O rótulo country detalha a contagem por código de país.

  • attestation_requests_number_type: Contador para solicitações de atestado pelo tipo de número de telefone. O rótulo country detalha a contagem por código de país. Rótulo type tem valores incluindo: fixed_line, mobile, fixed_line_or_mobile, toll_free, premium_rate, shared_cost, voip, personal_number, pager, uan, voicemail, unknown.

  • attestation_requests_sent_sms: Contador para o número de SMS enviados com sucesso.

  • attestation_requests_failed_to_send_sms: Contador para o número de SMS que falhou ao enviar.

  • attestation_requests_believed_delivered_sms: Contador para o número de SMS que foram eventualmente entregues, ou acredita-se em ser entregue após um tempo limite sem ouvir sobre falha de entrega.

  • attestation_requests_unexpected_errors: Contador para o número de erros inesperados.

As seguintes métricas acompanham cada tentativa de entrega. Cada solicitação de cliente para um atestado pode resultar em várias tentativas de entrega, no máximo MAX_DELIVERY_ATTEMPTS configurado para esse país:

  • attestation_attempts_delivery_status: Contador para tentativas de entrega. O rótulo country detalha a contagem por código de país. O rótulo provider identifica o provedor. Rótulo status identifica o resultado:

    • Created: A solicitação foi aceita pelo provedor.

    • Queued: O SMS está em buffer ou em fila, mas ainda em vôo.

    • Upstream: O SMS foi passado para uma operadora upstream.

    • Delivered: Um recibo de entrega final foi recebido indicando que o SMS foi entregue com sucesso.

  • attestation_attempts_delivery_error_codes: Contador de tentativas de entrega efetuadas. O rótulo country detalha a contagem por código de país. O rótulo provider identifica o provedor. O rótulo code identifica os códigos de erro específicos do provedor: consulte Códigos de erro do Twilio e códigos de erro Nexmo para mais detalhes.

Métricas administrativas:

  • O attestation_provider_balance rastreia o valor do saldo das contas em provedores suportados. O rótulo provider identifica o provedor. Isso é atualmente suportado apenas para Nexmo, e está desativado por padrão, mas pode ser ativado definindo NEXMO_ACCOUNT_BALANCE_METRIC. A métrica é preenchida como um valor na moeda da conta, por exemplo, USD, e somente uma vez que um SMS de sucesso tenha sido entregue por esse provedor.

Respostas de erro​

Aqui está uma lista de códigos de erro e mensagens retornadas pelo Serviço de Atestado e o que significam. Isso pode ser útil ao olhar através de logs de serviços de atestado bruto. Além dos códigos de erro listados abaixo, o serviço também retorna 500 para Unknown Error.

422, Unprocessable Entity​

  • Mismatching issuer, I am ${address} - A solicitação de atestado faz referência a um endereço do emissor que não corresponde ao do AS que realmente recebeu a solicitação.
  • NO_INCOMPLETE_ATTESTATION_FOUND_ERROR / 'No incomplete attestation found' - O contrato Attestations não tem registro de que este AS foi atribuído aleatoriamente como emissor para o par conta/identificador fornecido.
  • ATTESTATION_ERROR / 'Valid attestation could not be provided' - Uma chamada para validarAttestationCode no contrato Attestations falhou. Este método verifica que (1) existe um certificado incompleto não expirado atribuído ao emissor cuja assinatura constitui o código de atestado fornecido.
  • 'Invalid securityCodePrefix' - Um prefixo de código de segurança com comprimento incorreto foi fornecido na solicitação de atestado.
  • 'Invalid smsRetrieverAppSig' - O smsRetrieverAppSig fornecido não corresponde ao regex '^[\\w+]{5,12}$'
  • 'Attestation can no longer be re-requested' - O usuário está solicitando novamente um atestado que o AS acha que foi concluído há muito tempo para aceitar a nova solicitação.
  • 'Delivery attempts exceeded' - O AS tentou entregar este atestado ao usuário muitas vezes e não tentará novamente.
  • ErrorMessages.NO_PROVIDER_SETUP / 'No provider was setup for this phone number' - O AS não configurou um provedor de SMS
  • ErrorMessages.INVALID_SIGNATURE / 'Invalid signature provided' - A assinatura fornecida em um AttestationServiceTestRequest não foi gerada nem pelo endereço da conta do AS nem pelo endereço do signatário do atestado.

404, Not Found​

  • 'Attestation not found' - O atestado que o usuário está tentando preencher não foi encontrado no banco de dados do AS.

403, Forbidden​

  • 'Security code attempts exceeded' - O usuário tentou concluir o atestado com um código de segurança incorreto muitas vezes. O atestado não pode mais ser concluído.
  • 'Invalid security code' - O usuário tentou concluir o atestado com um código de segurança incorreto.

401, Unauthorized​

  • 'Missing authentication' - o cabeçalho de autenticação está faltando na solicitação
  • 'Invalid signature' - O cabeçalho de autenticação falhou na verificação da assinatura. Ele deve ser assinado pelo DEK da conta ou pela chave da carteira.

Blockchain​

O número de atestados solicitados e totalmente preenchidos está efetivamente registrado no blockchain. Os valores podem ser vistos em Celo Explorer: digite o endereço do Validador e clique na aba 'Celo Info'.

TheCelo rastreia contagens globais de atestados e taxas de sucesso e mostra informações detalhadas sobre tentativas recentes de atestados.

Painel de Serviço de Atestado​

Depois que seu serviço estiver funcionando, você poderá monitorar seu desempenho usando o Painel de serviço de atestado. Digite o endereço do seu validador na barra de pesquisa superior direita para visualizar as estatísticas do seu serviço. Esse painel também pode ser útil para solucionar vários problemas que surgirão com determinadas regiões geográficas ou provedores.