PaymeChain.SDK 1.0.3

PaymeChain SDK para .NET

Bem-vindo ao SDK oficial da PaymeChain para a plataforma .NET. Esta biblioteca foi projetada para simplificar e acelerar a integração de suas aplicações com a blockchain Payme, abstraindo as complexidades de comunicação, descoberta de nós e gerenciamento de segurança.

Objetivo

O principal objetivo do PaymeChain SDK é fornecer uma interface fluente, segura e resiliente para interagir com a rede Payme. Ele automatiza tarefas essenciais para que os desenvolvedores possam focar na lógica de negócios de suas aplicações, em vez de na infraestrutura da blockchain.

• Conexão Simplificada: Configure o SDK uma vez e deixe-o gerenciar o ciclo de vida da conexão.
• Alta Disponibilidade: Encontra automaticamente o nó da rede mais saudável e performático para enviar as requisições.
• Segurança Integrada: Gerencia o download e a atualização de certificados de segurança da rede de forma automática.
• Interface Intuitiva: Oferece um cliente único (PaymeClient) com acesso a todos os serviços da blockchain de forma organizada.

Instalação

O SDK está disponível como um pacote NuGet. Você pode instalá-lo usando a CLI do .NET ou o Gerenciador de Pacotes do Visual Studio.

.NET CLI:

dotnet add package PaymeChain.SDK

Gerenciador de Pacotes:

Install-Package PaymeChain.SDK

Inicialização e Configuração

A inicialização do SDK é feita em dois passos simples:

1. Configure o appsettings.json

Adicione uma seção PaymeSdk ao seu arquivo appsettings.json.

{
  "PaymeSdk": {
    "NodeRegistryUrl": "https://apivalidators.paymechain.com", //Serviço oficial
    "HealthCheckIntervalSeconds": 300,
    "SeedNodes": [
      "http://node1.payme.com:5000",
      "http://node2.payme.com:5000"
    ],
    "NodeSelectionStrategy": "LowestLatency", "HighestBlockHeight", "Random" // Selecione um
    "ValidatorMode": "0", "1" // 0 para Archive e 1 Full Node
  }
}

• NodeRegistryUrl (Obrigatório): A URL do serviço central que fornece a lista de validadores da rede.
• HealthCheckIntervalSeconds (Opcional): O intervalo, em segundos, que o SDK usará para verificar a saúde dos nós e selecionar o melhor. O padrão é 300 (5 minutos).
• SeedNodes (Opcional): Uma lista de URLs de nós conhecidos. O SDK usará esses nós como ponto de partida se o NodeRegistryUrl estiver indisponível, util para realizar teste localmente.

2. Registre o SDK

No arquivo de inicialização da sua aplicação (Program.cs ou MauiProgram.cs), registre o serviço do SDK.

Exemplo para API ASP.NET Core (Program.cs):

using DE.Payme.SDK.Extensions; // Adicione este using

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddPaymeSdk(options => 
    builder.Configuration.GetSection("PaymeSdk").Bind(options)
);

// ... resto da sua configuração

Exemplo para App MAUI (MauiProgram.cs):

using DE.Payme.SDK.Extensions; // Adicione este using

public static class MauiProgram
{
    public static MauiApp CreateMauiApp()
    {
        var builder = MauiApp.CreateBuilder();
        // ...
        
        // Adiciona configurações do appsettings.json
        var config = new ConfigurationBuilder()
            .AddJsonStream(Assembly.GetExecutingAssembly().GetManifestResourceStream("SeuApp.appsettings.json"))
            .Build();
        builder.Configuration.AddConfiguration(config);

        builder.Services.AddPaymeSdk(options => 
            builder.Configuration.GetSection("PaymeSdk").Bind(options)
        );

        return builder.Build();
    }
}

Uso Básico

Após a configuração, você pode injetar o PaymeClient em qualquer serviço, controller ou ViewModel da sua aplicação.

public class MeuServico
{
    private readonly PaymeClient _paymeClient;

    public MeuServico(PaymeClient paymeClient)
    {
        _paymeClient = paymeClient;
    }

    public async Task FazerAlgo()
    {
        // Exemplo: Buscar o último bloco da blockchain
        var resultado = await _paymeClient.Blocks.GetLatestBlockAsync();

        if (resultado.Success)
        {
            Console.WriteLine($"Bloco encontrado: {resultado.Data.Index}");
        }
        else
        {
            Console.WriteLine($"Erro: {resultado.Message}");
        }
    }
}

O Retorno Padrão: CommandResult<T>

Todas as chamadas de método que interagem com a rede retornam um objeto CommandResult<T>. Esta estrutura padronizada permite um tratamento de erros e sucesso de forma consistente.

public class CommandResult<T>
{
    // Indica se a operação foi bem-sucedida.
    public bool Success { get; set; }

    // Uma mensagem descritiva sobre o resultado da operação.
    public string Message { get; set; }

    // O objeto de dados retornado em caso de sucesso.
    public T Data { get; set; }

    // Um código de status que fornece mais detalhes sobre o resultado.
    public EStatusCode StatusCode { get; set; }
}

EStatusCode

O enumerador EStatusCode oferece um contexto mais granular sobre a resposta:

Visão Geral dos Endpoints (PaymeClient)

O PaymeClient é a porta de entrada para todos os serviços da blockchain.

• client.Accounts: Métodos relacionados a contas de usuários, como consultar saldos e informações.
• client.Blocks: Funções para consultar blocos específicos, o último bloco ou um intervalo de blocos.
• client.Explorer: Endpoints comumente usados por exploradores de blockchain, fornecendo dados agregados.
• client.LightClient: Suporte a provas de Merkle e cabeçalhos de bloco para clientes leves.
• client.Staking: Operações de Staking, como delegar, retirar stake e consultar recompensas.
• client.Statistics: Informações e estatísticas sobre a saúde e o estado da rede.
• client.Tokens: Funções relacionadas a tokens na rede Payme (se aplicável).
• client.Transactions: Métodos para submeter novas transações, consultar o status de transações e buscar pelo ID.
• client.Validators: Informações sobre os validadores da rede.
• client.Wallet: Funções de conveniência para gerenciamento de carteiras, como criar, derivar endereços e construir transações.
• client.Realtime: Um cliente SignalR para receber atualizações da rede em tempo real (ex: novos blocos).

Funcionamento em Background

É importante entender que, uma vez configurado, o SDK opera de forma autônoma:

1. Gerencia o Certificado: Mantém o certificado de segurança da rede atualizado.
2. Monitora os Nós: Constantemente avalia os nós da rede para garantir que suas requisições sejam sempre enviadas ao nó mais rápido e estável, garantindo performance e resiliência para sua aplicação.