DEV Community: Lerian

Construindo SDKs: Lições da Lerian com o Midaz, o primeiro ledger open source da América Latina.

Jefferson Rodrigues — Wed, 28 May 2025 18:24:32 +0000

Hoje quero compartilhar um pouco dos bastidores do desenvolvimento das nossas SDKs oficiais para o Midaz, nosso ledger open source para sistemas financeiros e, por que, para nós, SDK não é um simples wrapper e sim um produto que expressa nosso foco junto com a comunidade de desenvolvedores.

O que está por trás do Midaz?

No coração do Midaz existe um ledger open source com double-entry contábil, multi-moeda e preparado para fluxos complexos de transações financeiras.

Mas sabemos que expor apenas APIs REST não resolve o maior desafio: a barreira de entrada para quem está construindo fintechs e sistemas financeiros robustos, ou seja, a dificuldade que muitas vezes o time tech do nosso cliente encontra ao integrar novas ferramentas. Por exemplo:

Documentação confusa e com ausência de informações relevantes;
API’s inconsistentes;
Ausência de exemplos reais de aplicabilidade;
Falta de ferramentas para lidar com retries, performance e resiliência.

SDK: mais que um wrapper, uma extensão da arquitetura

Quando decidimos construir as SDKs do Midaz em TypeScript e Go, partimos de alguns questionamentos internos: Como tornar a vida do desenvolvedor mais fácil, sem abrir mão da robustez financeira?

Como evitar que erros bobos (payload mal formatado, conta errada e afins) virem problemas reais em produção? Como suportar o nosso cliente a ter uma implantação fluida e eficiente?

Como criar um kit que realmente ajuda a escalar a operação do cliente e não só a conectar pontas?

A resposta foi desenhar SDKs como uma ferramentas de verdade e com algumas premissas básicas:

Validação no cliente: não faz sentido mandar ao backend algo que já sabemos que vai falhar;
Retry inteligente: em sistemas financeiros, falhas transitórias são normais e por isso há a necessidade de antever esse movimento com backoff exponencial, jitter, categorização de erros e afins;
Paginação e concorrência controlada: processar grandes volumes de dados não é um caso de uso opcional quando falamos de mercado financeiro e de partidas contábeis dobradas;
Performance e observabilidade: pooling de JSON, modularidade de logs e tracing com OpenTelemetry;

Exemplos práticos: a documentação só é considerada completa quando temos casos de uso práticos para o usuário entender a aplicabilidade do que estamos construindo.

No SDK de GoLang, por exemplo, optamos por um padrão de opções funcionais para configuração. Já no SDK de TypeScript, aproveitamos o ecossistema para entregar tipagem forte e integração fluida com ferramentas modernas de frontend e backend.

Open source como filosofia da Lerian

Lançar SDKs como parte de um projeto open source nos traz responsabilidades extras porque temos que manter a coerência, garantir a estabilidade e documentar de forma que as pessoas da comunidade possam contribuir.

Por isso, acreditamos que SDKs bem desenhados não são “nice to have” e sim são o coração do nosso pilar de Developer Experience e também para um pilar para o futuro financeiro open source que estamos ajudando a construir.

Conclusão

Os SDKs do Midaz nasceram de um princípio simples: foco na agilidade dos entregáveis aos nossos clientes e compromisso com a confiabilidade.
Queremos que qualquer pessoa que precise integrar com um core banking tenha em mãos ferramentas que façam sentido, funcionem e sejam transparentes.
Se quiser ver o que estamos criando (ou contribuir!):

🔗 Midaz no GitHub
🔗 SDK TypeScript
🔗 SDK Go

Feedbacks e pull requests são sempre bem-vindos.

Vamos construir o futuro financeiro juntos?

Jeff Rodrigues / CTO @ Lerian

Plugins made-to-scale: uma visão sobre cache, filas e resiliência.

Jefferson Rodrigues — Mon, 19 May 2025 20:08:49 +0000

Quando falamos de infraestrutura financeira, resiliência não é um diferencial e sim um requisito. E na Lerian, cada plugin construído é pensado para garantir estabilidade mesmo em ambientes hostis: redes instáveis, dependências externas, falhas parciais e tráfego intenso.

Neste artigo, exploramos como cache, filas e boas práticas de resiliência são combinadas na arquitetura dos nossos plugins para criar soluções robustas, auditáveis e performáticas.

1. Cache: Performance sem comprometer a consistência.

Muitos plugins operam com dados de leitura frequente e alteração rara como, por exemplo, pacotes de tarifas e gerenciamento de tokens e lock de transações. Para esses casos, adotamos cache local e distribuído:

Valkey é usado para armazenar estruturas intermediárias e reduzir chamadas ao backend;

TTLs inteligentes ajudam a equilibrar escala e eficiência;
Embora não utilizemos eventos de pub/sub em todos os plugins, o cache é atualizado individualmente por cada serviço, conforme a lógica de funcionamento definida para cada um deles.

Essa camada reduz a latência de chamadas, alivia a pressão sobre o core e melhora a experiência do consumidor da API.

2. Filas: desacoplamento, resiliência e reatividade com integridade.

Plugins que se comunicam com serviços externos ou operam de forma assíncrona utilizam filas como mecanismo de segurança e desacoplamento. É o caso do Smart Templates e do próprio ledger, Midaz, que empregam filas para garantir que, em caso de erro, nenhuma informação se perca e a operação possa ser reprocessada com consistência.

Adotamos o RabbitMQ como broker padrão, tanto para persistência assíncrona de saldo quanto para orquestrar eventos como a criação de contas de asset.

Essa arquitetura atual, com mecanismo de retry, permite reatividade sem comprometer a integridade: se uma dependência estiver indisponível, a mensagem é retida e processada posteriormente.

3. Resiliência: Não é sobre evitar falhas, mas sobre suportá-las.

Nossos plugins seguem padrões de projeto defensivos:
Idempotência nativa: eventos são processados uma única vez, mesmo que reenviados;

Utilizamos a fila como mecanismo de retry, uma prática que garante resiliência operacional para evitar overload;

Observabilidade integrada com OpenTelemetry para tracing, métricas e logs estruturados.

Para garantir segurança e controle de acesso, cada plugin que se integra ao ledger pode utilizar uma credencial própria para se autenticar no Midaz. Com isso, conseguimos definir permissões específicas por plugin, evitando o uso de uma credencial única e reduzindo o risco de acessos indevidos.

4. Plugins como produtos de infraestrutura

Cada plugin é tratado como um componente core, com o mesmo rigor técnico aplicado ao próprio Midaz. Afinal, eles não ficam na borda: executam lógica crítica como cálculo de tarifas, câmbio, validação de acesso, entre outras funções sensíveis.

Cache, filas e resiliência não são acessórios. São fundamentos arquiteturais que garantem performance, consistência e estabilidade, mesmo diante de falhas externas ou cenários de alta complexidade.

Quer explorar o que estamos construindo?
🔗 github.com/lerianstudio

lições aprendidas na construção de uma sdk financeira: onde termina o backend e começa o cliente?

Fred Amaral — Fri, 11 Apr 2025 18:30:57 +0000

nas últimas semanas, embarcamos em um desafio por aqui: construir a primeira SDK para o Midaz, nosso ledger para core banking (disponível open-source aqui). o que parecia ser um projeto de simples -- afinal, openapi documentation e uma infinidade de ferramentas para generation --, rapidamente se transformou em um rabbit hole técnico bem profundo. colocar a primeira versão em produção trouxe à tona uma discussão fundamental: qual é a fronteira entre as responsabilidades do servidor e do cliente?

fronteiras de responsabilidade

quando começamos a desenvolver a SDK para o Midaz (em Go), a pergunta que constantemente nos perseguia era: até onde a API do backend deve ir e onde começa a responsabilidade de integração/implementação do cliente? ou seja, onde termina o backend e começa o colo do cliente?

esta pergunta aparentemente simples esconde uma complexidade enorme. tradicionalmente, muitos desenvolvedores consideram que:

Backend: responsável pela lógica de negócio, persistência, segurança, validações
Cliente/SDK: responsável apenas por fazer requisições HTTP, serializar/deserializar dados

mas será que essa divisão simplista funciona bem na prática? especialmente quando falamos de sistemas financeiros com requisitos rigorosos de consistência, performance e resiliência?

por que uma SDK robusta importa? ou pq qualquer generation tool não funcionou conosco

durante o desenvolvimento, percebemos que uma SDK financeira precisa ir muito além de simplesmente fazer o wrapping de endpoints REST. ela precisa ser uma camada que:

Protege o servidor contra inputs inválidos (validação do lado cliente)
Torna a integração mais resiliente (retries, rate limiting, circuit breaking)
Oferece performance mesmo em condições adversas (batching, paralelismo)
Simplifica operações complexas (abstraindo detalhes de implementação [que o backend precisa manter detalhado])
Proporciona uma experiência de desenvolvimento fluida (tipos fortemente definidos, erros descritivos)

vamos explorar cada um desses aspectos detalhadamente, com exemplos práticos do que implementamos na nossa primeira SDK.

validação no cliente: evitando viagens desnecessárias

uma das primeiras decisões que tomamos foi implementar validações robustas no lado cliente. por quê? simples: por que enviar ao servidor uma requisição que sabemos que vai falhar?

// Exemplo de validação de transação financeira no lado cliente
func ValidateTransactionDSL(input TransactionDSLValidator) error {
    if input == nil {
        return fmt.Errorf("transaction input cannot be nil")
    }

    // Valida código do ativo
    asset := input.GetAsset()
    if asset == "" {
        return fmt.Errorf("asset code is required")
    }
    if !assetCodePattern.MatchString(asset) {
        return fmt.Errorf("invalid asset code format: %s (must be 3-4 uppercase letters)", asset)
    }

    // Valida valor
    if input.GetValue() <= 0 {
        return fmt.Errorf("transaction amount must be greater than zero")
    }

    // Validações adicionais de contas e consistência...
}

implementamos validações para:

formatos de código de ativos (USD, BRL, BTC, Gado, Caixas de Remédio, whatever)
montantes e escalas de transações
estrutura de contas e operações
metadados e payloads auxiliares

isso traz múltiplos benefícios:

feedback instantâneo para o desenvolvedor
redução de latência (evitando roundtrips desnecessários)
menor carga no servidor
mensagens de erro mais contextualizadas e úteis

a validação no cliente não substitui a validação no servidor (que continua essencial por razões de segurança), mas cria uma experiência de desenvolvimento superior e reduz o tráfego de rede.

resiliência através de retry intelligente

sistemas distribuídos falham. esta é uma realidade, não uma possibilidade. quando trabalhamos com operações financeiras, essas falhas são ainda mais críticas e podem ter consequências significativas.

por isso, implementamos mecanismos sofisticados de retry com exponential backoff:

// Configuração de retry com backoff exponencial
client, err := client.New(
    client.WithAuthToken("your-auth-token"),
    client.WithTimeout(30 * time.Second),
    client.WithRetries(3, 100*time.Millisecond, 1*time.Second),
    client.UseAllAPIs(), // by the way, isso é um caso a parte aqui: pra que expor o que não precisa ser exposto?
)

nosso sistema de retry:

utiliza backoff exponencial para evitar sobrecarregar servidores em problemas
adiciona jitter (variação aleatória) para prevenir thundering herd e, sinceramente se eu fingir normalidade escrevendo isso aqui, é mentira. aqui foi um rabbit hole a parte, e estudamos bastante para entender o conceito que era aplicado em outras enterprise-grade APIs
categoriza erros entre "retryable" e "non-retryable"
respeita limites de timeout especificados pelo usuário
permite personalização completa de estratégias

este código parece simples na interface, mas por trás dele há uma implementação robusta que considera diversos cenários de falha:

// Trecho da implementação de retry com backoff
func doWithOptions(ctx context.Context, fn func() error, options *Options) error {
    var err error
    for attempt := 0; attempt <= options.MaxRetries; attempt++ {
        // Check if context is done before executing
        if ctx.Err() != nil {
            return fmt.Errorf("operation cancelled: %w", ctx.Err())
        }

        // Execute the function
        err = fn()
        if err == nil {
            // Success, return immediately
            return nil
        }

        // Check if this is the last attempt
        if attempt == options.MaxRetries {
            break
        }

        // Check if the error is retryable
        if !IsRetryableError(err, options) {
            return err
        }

        // Calculate delay with jitter
        delay := calculateBackoff(attempt, options)
        delayWithJitter := addJitter(delay, options.JitterFactor)

        // Wait for the calculated delay or until context is done
        timer := time.NewTimer(delayWithJitter)
        select {
        case <-ctx.Done():
            timer.Stop()
            return fmt.Errorf("operation cancelled during retry: %w", ctx.Err())
        case <-timer.C:
            // Continue to next retry attempt
        }
    }

    return fmt.Errorf("operation failed after %d retries: %w", options.MaxRetries, err)
}

um dos aprendizados mais interessantes foi identificar quais erros deveriam ser tentados novamente e quais não. por exemplo, erros de validação nunca devem ter retry, enquanto problemas de rede temporários são candidatos ideais. esse modelo de listing by exception é um conceito que foi estudado bastante, e foi aplicado em outras enterprise-grade APIs (exemplo interessante é a da AWS).

// Definição de erros retryable padrão
var DefaultRetryableErrors = []string{
    "connection reset by peer",
    "connection refused",
    "timeout",
    "deadline exceeded",
    "too many requests",
    "rate limit",
    "service unavailable",
}

// Códigos HTTP que merecem retry
var DefaultRetryableHTTPCodes = []int{
    http.StatusRequestTimeout,      // 408
    http.StatusTooManyRequests,     // 429
    http.StatusInternalServerError, // 500
    http.StatusBadGateway,          // 502
    http.StatusServiceUnavailable,  // 503
    http.StatusGatewayTimeout,      // 504
}

gerenciamento avançado de configurações

a modularidade da configuração foi um ponto crítico do design. utilizamos o padrão de opções funcionais (não são 100% fluentes como pede o figurin) para permitir uma configuração limpa e extensível:

// Padrão de options funcionais para configuração flexível
client, err := client.New(
    // Configurações básicas
    client.WithAuthToken("your-auth-token"),
    client.WithEnvironment(config.EnvironmentProduction),

    // Opções avançadas de performance
    client.WithTimeout(30 * time.Second),
    client.WithRetries(3, 200*time.Millisecond, 2*time.Second),

    // Observabilidade
    client.WithObservability(true, true, true),

    // Quais APIs utilizar
    client.UseAllAPIs(),
)

este padrão permite:

configuração incremental com defaults sensatos
melhor legibilidade e manutenção
extensibilidade futura sem quebrar compatibilidade
configurações específicas por domínio

além disso, implementamos suporte para configuração via variáveis de ambiente:

// Variáveis de ambiente que o cliente reconhece
MIDAZ_AUTH_TOKEN=seu-token // implementaremos a sdk de access management lançada ontem logo logo
MIDAZ_ENVIRONMENT=production
MIDAZ_ONBOARDING_URL=https://api.exemplo.com/v1
MIDAZ_TRANSACTION_URL=https://transactions.exemplo.com/v1
MIDAZ_DEBUG=true
MIDAZ_MAX_RETRIES=5

isto permite uma integração mais suave com diferentes ambientes de deploy, especialmente em contextos de containers e kubernetes.

performance otimizada para JSON

em sistemas financeiros, performance não é luxo, é requisito. um dos pontos de maior otimização foi o processamento JSON, que pode rapidamente se tornar um gargalo:

// Exemplo de nossa implementação de pooling de buffers para JSON
type JSONPerformance struct {
    encoderPool sync.Pool
    decoderPool sync.Pool
    bufferPool  sync.Pool
}

func NewJSONPerformance() *JSONPerformance {
    return &JSONPerformance{
        encoderPool: sync.Pool{
            New: func() interface{} {
                return json.NewEncoder(io.Discard)
            },
        },
        decoderPool: sync.Pool{
            New: func() interface{} {
                return json.NewDecoder(strings.NewReader(""))
            },
        },
        bufferPool: sync.Pool{
            New: func() interface{} {
                return new(bytes.Buffer)
            },
        },
    }
}

func (jp *JSONPerformance) Marshal(v interface{}) ([]byte, error) {
    buf := jp.bufferPool.Get().(*bytes.Buffer)
    buf.Reset()
    defer jp.bufferPool.Put(buf)

    enc := jp.encoderPool.Get().(*json.Encoder)
    enc.SetEscapeHTML(false)
    oldWriter := enc.Linter
    enc.SetWriter(buf)
    defer func() {
        enc.SetWriter(oldWriter)
        jp.encoderPool.Put(enc)
    }()

    if err := enc.Encode(v); err != nil {
        return nil, err
    }

    // Copy to avoid returning a reference to the pooled buffer
    result := make([]byte, buf.Len())
    copy(result, buf.Bytes())
    return result, nil
}

esta abordagem reduziu alocações de memória em nossos benchmarks, principalmente quando fazíamos em conjunto com o pooling de buffers, o que é crucial para sistemas financeiros de alto volume que processam milhões de transações.

paginação inteligente e universal

lidar com grandes conjuntos de dados é um desafio comum em operações financeiras. por isso, desenvolvemos um sistema de paginação universal que funciona com diferentes endpoints e paradigmas:

// Interface genérica para qualquer tipo de paginador
type Paginator[T any] interface {
    HasNext() bool
    Next() (*ListResponse[T], error)
    Reset() 
}

// Exemplo de uso para listar transações com paginação automática
paginator := client.Entity.Transactions.GetTransactionPaginator(
    ctx, "org-id", "ledger-id", &models.ListOptions{Limit: 100},
)

totalTransactions := 0
for paginator.HasNext() {
    page, err := paginator.Next()
    if err != nil {
        return err
    }

    for _, tx := range page.Items {
        // Processar cada transação
        processTransaction(tx)
        totalTransactions++
    }
}
fmt.Printf("Processadas %d transações no total\n", totalTransactions)

nossa implementação suporta:

paginação por offset/limit (mais comum)
paginação por cursor (mais eficiente para grandes datasets)
prefetching para melhor performance
preservação de filtros e ordenação entre páginas
adaptação automática ao tipo de paginação do endpoint

concorrência controlada para alto volume

para lidar com os requisitos de alta performance, investimos pesadamente em modelos de concorrência bem controlados:

// Worker pool genérico com controle fino de concorrência
func WorkerPool[T, R any](
    ctx context.Context,
    items []T,
    workFn func(context.Context, T) (R, error),
    opts ...PoolOption,
) []Result[T, R] {
    // Config default
    options := defaultPoolOptions()
    for _, opt := range opts {
        opt(options)
    }

    resultCh := make(chan Result[T, R], len(items))
    var wg sync.WaitGroup

    // Semáforo para controlar concorrência
    sem := make(chan struct{}, options.workers)

    // Rate limiter se especificado
    var limiter <-chan time.Time
    if options.rateLimit > 0 {
        ticker := time.NewTicker(time.Second / time.Duration(options.rateLimit))
        defer ticker.Stop()
        limiter = ticker.C
    }

    for i, item := range items {
        // Respeita cancelamento pelo context
        if ctx.Err() != nil {
            break
        }

        // Rate limiting se ativo
        if limiter != nil {
            select {
            case <-ctx.Done():
                break
            case <-limiter:
                // Continue quando o rate limiter permitir
            }
        }

        // Adquire slot no semáforo
        sem <- struct{}{}

        wg.Add(1)
        go func(idx int, item T) {
            defer wg.Done()
            defer func() { <-sem }() // Libera o semáforo ao final

            // Cria um timeout interno se necessário
            execCtx := ctx
            if options.timeout > 0 {
                var cancel context.CancelFunc
                execCtx, cancel = context.WithTimeout(ctx, options.timeout)
                defer cancel()
            }

            // Executa a função de trabalho
            result, err := workFn(execCtx, item)

            // Envia o resultado
            resultCh <- Result[T, R]{
                Index: idx,
                Item:  item,
                Value: result,
                Error: err,
            }
        }(i, item)
    }

    // Fecha o canal de resultados quando todo trabalho estiver concluído
    go func() {
        wg.Wait()
        close(resultCh)
    }()

    // Coleta resultados
    var results []Result[T, R]
    for result := range resultCh {
        results = append(results, result)
    }

    // Ordena resultados se necessário
    if options.ordered {
        sort.Slice(results, func(i, j int) bool {
            return results[i].Index < results[j].Index
        })
    }

    return results
}

esta implementação permite:

controle preciso de concorrência para evitar sobrecarregar a API
rate limiting para respeitar limites da API
ordenação opcional de resultados
cancelamento gracioso de operações em andamento
timeouts individuais para tarefas

tratamento avançado de erros financeiros

em um sistema financeiro, os erros são parte crítica da experiência do desenvolvedor. investimos em um sistema sofisticado de tratamento de erros:

// Exemplo de uso de erros especializados
switch {
case errors.IsValidationError(err):
    // Trata erro de validação
    fmt.Println("Erro de validação:", err)

    // Extrai erros por campo
    fieldErrors := errors.GetFieldErrors(err)
    for _, fieldErr := range fieldErrors {
        fmt.Printf("Campo %s: %s\n", fieldErr.Field, fieldErr.Message)
    }

case errors.IsInsufficientBalanceError(err):
    // Trata erro específico financeiro
    fmt.Println("Saldo insuficiente:", err)

case errors.IsRateLimitExceededError(err):
    // Implementa backoff e retry
    fmt.Println("Limite de requisições excedido, aguardando:", err)
    time.Sleep(exponentialBackoff(attempt))

case errors.IsAuthenticationError(err):
    // Problema com autenticação
    fmt.Println("Erro de autenticação, renovando token:", err)
    renewToken()
}

adicionalmente, nossos erros incluem:

categorização clara (validação, autenticação, rede, etc)
detalhes específicos por domínio financeiro (saldo insuficiente, limites, etc)
códigos de erro e status HTTP associados
sugestões de correção para o desenvolvedor
integração com observabilidade (geração de span de erro)

testes de stress e verificação de escalabilidade

uma característica distintiva da nossa SDK foi o desenvolvimento de uma suite robusta de testes de stress:

// Trecho do código da suite de stress testing
func (st *StressTest) Run(ctx context.Context) error {
    logger := st.observability.GetLogger()
    logger.Info("Iniciando teste de stress", "workers", st.config.ConcurrentWorkers)

    // Preparar ambiente de teste
    if err := st.SetupTestEnvironment(ctx); err != nil {
        return fmt.Errorf("falha ao configurar ambiente: %w", err)
    }

    // Executar até interrupção ou duração configurada
    var wg sync.WaitGroup
    ctx, cancel := context.WithCancel(ctx)
    defer cancel()

    // Inicia monitoramento de métricas
    st.metrics = NewMetricsCollector(st.observability)
    go st.metrics.Start(ctx)

    // Inicia workers para gerar carga
    for i := 0; i < st.config.ConcurrentWorkers; i++ {
        wg.Add(1)
        go func(workerID int) {
            defer wg.Done()
            st.runWorker(ctx, workerID)
        }(i)
    }

    // Aguarda conclusão
    wg.Wait()
    logger.Info("Teste de stress concluído", "transações", st.metrics.TotalTransactions())

    return nil
}

esta suite nos permitiu:

validar o comportamento sob carga extrema (50.000+ tx/s ou modelos de 1:1 em conta com 10000+ tx/s)
identificar e corrigir bottlenecks antes do lançamento
verificar o comportamento de mecanismos de retry e resiliência
testar a degradação graceful sob falhas parciais
validar limites de recursos (memória, CPU, conexões, e o próprio sistema distribuído)

no ponto específico de validar limites de recursos e do sistema distribuído, utilizamos o pumba para simular cenários de caos (em docker), e isso nos ajudou a identificar pontos interessantes na implementação do próprio backend.

documentação dirigida por exemplos

percebemos que bons exemplos são mais valiosos que documentação abstrata. por isso, demos ênfase especial a exemplos práticos:

// Exemplo completo de transferência entre contas
func ExampleTransferBetweenAccounts() {
    // Inicializar cliente
    c, err := client.New(
        client.WithAuthToken(os.Getenv("MIDAZ_TOKEN")),
        client.UseAllAPIs(),
    )
    if err != nil {
        log.Fatalf("Erro inicializando cliente: %v", err)
    }

    // Definir detalhes da transação
    input := &models.TransactionDSLInput{
        Description: "Transferência para pagamento de aluguel",
        Send: &models.DSLSend{
            Asset: "BRL",
            Value: 150000, // R$ 1.500,00
            Scale: 2,
            Source: &models.DSLSource{
                From: []models.DSLFromTo{
                    {
                        Account: "conta-origem-123",
                        Amount: &models.DSLAmount{
                            Asset: "BRL",
                            Value: 150000,
                            Scale: 2,
                        },
                    },
                },
            },
            Distribute: &models.DSLDistribute{
                To: []models.DSLFromTo{
                    {
                        Account: "conta-destino-456",
                        Amount: &models.DSLAmount{
                            Asset: "BRL",
                            Value: 150000,
                            Scale: 2,
                        },
                    },
                },
            },
        },
        Metadata: map[string]any{
            "referencia": "aluguel-julho-2025",
            "categoria": "moradia",
        },
    }

    // Executar a transação
    tx, err := c.Entity.Transactions.CreateTransactionWithDSL(
        context.Background(),
        "org-exemplo",
        "ledger-principal",
        input,
    )
    if err != nil {
        log.Fatalf("Erro na transferência: %v", err)
    }

    fmt.Printf("Transferência realizada com sucesso! ID: %s\n", tx.ID)
}

cada exemplo está acompanhado de comentários detalhados e cobrimos todos os cenários principais:

criação de entidades (organizações, contas, etc)
operações financeiras (transferências, depósitos, saques)
consultas e relatórios (balanços, extratos, histórico)
workflows completos (onboarding, transações)

a vantagem da unificação de interface

falando um pouco sobre a vantagem de unificar múltiplas APIs de backend sob uma interface coerente: no mundo financeiro, frequentemente temos APIs separadas para diferentes domínios:

API de onboarding (organizações, contas)
API de transactions (transferências, saldos)
API de compliance (KYC, AML)
API de reporting (relatórios, extratos)
etc etc etc

cada uma com suas peculiaridades e convenções. nossa SDK unifica todas sob uma única interface consistente:

// Mesmo padrão para todas as APIs, independente do backend
// API de onboarding
organization, err := client.Entity.Organizations.CreateOrganization(ctx, input)

// API de transactions 
transaction, err := client.Entity.Transactions.CreateTransaction(ctx, orgID, ledgerID, input)

// API de balanços
balance, err := client.Entity.Accounts.GetBalance(ctx, orgID, ledgerID, accountID)

esta unificação traz benefícios significativos para o desenvolvedor em si:

reduz a curva de aprendizado para novos desenvolvedores
abstrai as diferenças de implementação entre serviços
permite evolução independente do backend e frontend
facilita migração entre diferentes versões de APIs

a discussão sobre fronteiras: o que aprendemos

voltando à questão inicial sobre as fronteiras de responsabilidade entre servidor e cliente, concluímos que a resposta não é binária. em vez disso, é um espectro que depende do contexto:

Validação: tanto cliente quanto servidor devem validar - cliente para UX e DevEx, servidor para segurança
Resiliência: principalmente responsabilidade do cliente, com suporte do servidor (idempotência, o que nossa API também trata com uma option específica de WithIdempotency())
Performance: responsabilidade compartilhada, com otimizações específicas em cada lado
Domínio: o servidor define o modelo, mas o cliente pode enriquecê-lo com abstrações úteis

o que ficou claro é que SDKs não são meros wrappers de API - elas são produtos completos que precisam considerar toda a experiência do desenvolvedor e os requisitos específicos do domínio.

trade-offs e desafios de design importantes

durante o desenvolvimento da SDK, nos confrontamos com vários trade-offs importantes que impactam diretamente desenvolvedores e usuários:

validação no cliente vs. sincronização com o servidor

a implementação de validações robustas no cliente traz benefícios claros de performance e experiência do desenvolvedor, mas também introduz um desafio:

// Se estas regras de validação mudam no servidor...
if !assetCodePattern.MatchString(asset) {
    return fmt.Errorf("invalid asset code format: %s (must be 3-4 uppercase letters)", asset)
}

// ...e o cliente não atualiza a SDK, teremos inconsistências

este é um trade-off significativo:

Vantagem: redução de latência e feedback instantâneo
Desvantagem: potencial divergência entre regras cliente/servidor se os clientes não atualizarem a SDK

nossa solução foi documentar claramente a necessidade de atualizações regulares e fornecer testes que ajudam a detectar divergências de validação, além de fazer um robusto linking entre models do cliente e do servidor.

filosofia de tratamento de erros: o que tratar automaticamente?

uma decisão crítica foi determinar quais erros a SDK deveria tratar automaticamente versus quais deveriam ser expostos para o backend:

// Erros tratados automaticamente pela SDK
if errors.IsTemporaryNetworkError(err) || errors.IsRateLimitExceeded(err) {
    // Aplicar retry automaticamente
    return retry.Do(ctx, operation)
}

// Erros que são propagados ao aplicativo
if errors.IsBusinessRuleViolation(err) || errors.IsValidationError(err) {
    // O desenvolvedor precisa tratar estes casos explicitamente
    return err
}

adotamos a filosofia de que:

erros transientes de infraestrutura/rede são tratados pela SDK
erros de domínio financeiro ou validação são propagados para permitir tratamento adequado pelo backend
erros críticos (autenticação, permissões) são propagados com contexto enriquecido para facilitar diagnóstico

integração de observabilidade: o equilíbrio entre intrusão e visibilidade

a observabilidade é crítica em sistemas financeiros, mas quanto a SDK deve impor versus oferecer como opcional? aqui é um caso a parte. remodelamos toda a stack de observabilidade (usando opentelemetry) para que o desenvolvedor possa escolher o que ele quer e o que ele não quer, sem sermos "opinionated" com relação ao tema -- bem diferente do contexto do midaz open-source, que é mais "opinionated".

// Abordagem não-intrusiva que adotamos:
client, err := client.New(
    // Configuração básica
    client.WithAuthToken("token"),

    // Observabilidade totalmente opcional
    client.WithObservability(
        observability.WithTracing(userDefinedTraceProvider),  // opcional
        observability.WithMetrics(userDefinedMeterProvider),  // opcional
        observability.WithLogging(userDefinedLogger),         // opcional
    ),
)

decidimos por uma abordagem modular onde:

a SDK funciona perfeitamente sem observabilidade configurada
desenvolvedores podem injetar seus próprios providers de observabilidade
fornecemos implementações default para casos simples
instrumentamos pontos críticos nas operações financeiras para máxima visibilidade

operações assíncronas e notificações

transações financeiras frequentemente envolvem processos assíncronos. como a SDK deve lidar com isso?

// Opção 1: Polling (implementamos inicialmente)
status, err := client.Entity.Transactions.GetTransactionStatus(ctx, txID)

// Opção 2: Webhooks (planejado para futuro)
client.Entity.Transactions.RegisterWebhookHandler(webhookHandler)

// Opção 3: Response streaming (planejado para futuro)
stream, err := client.Entity.Transactions.WatchTransaction(ctx, txID)
for update := range stream.Updates() {
    // Processar atualizações em tempo real
}

nossa abordagem foi evolutiva. tomamos uma decisão de implementar o básico agora, mas permitindo uma modelagem como a acima exposta:

começamos com polling simples para compatibilidade ampla
adicionaremos suporte a webhooks para notificações em tempo real
e planejamos, por fim, streaming de atualizações para casos de uso mais complexos

estratégia de versionamento e compatibilidade planejado para em breve, dado que estamos na V1 do Midaz

o versionamento é um desafio significativo em APIs financeiras que evoluem constantemente:

// Suporte a múltiplas versões de API
client, err := client.New(
    client.WithAPIVersion("v1"),  // default
    // ou
    client.WithAPIVersion("v2"),  // novas funcionalidades
)

// Usando feature flags para recursos em preview
client.Entity.Transactions.CreateTransaction(
    ctx, orgID, ledgerID, input, 
    transactions.WithFeatureEnabled("instant-settlement"),
)

adotaremos uma estratégia de versionamento com múltiplas camadas:

versionamento semântico tradicional para a SDK
compatibilidade com múltiplas versões de API em uma única versão da SDK
feature flags para recursos experimentais
aliases de métodos deprecados com warnings para facilitar migrações

aprendizados para o futuro

lançar a primeira versão de uma SDK não é o fim da jornada, mas apenas o começo. já identificamos diversas áreas para evolução:

Estratégia evolutiva: como evoluir a API sem quebrar compatibilidade? como evoluir o backend sem quebrar compatibilidade? como fazer tudo isso e mantermos o decoupling super necessário entre midaz e midaz-sdk-golang versioning
Abstrações de domínio: quais abstrações de nível superior devemos oferecer para simplificar fluxos comuns? que tal evoluirmos para DoWithdrawal, DoDeposit, DoTransfer, etc, fazendo a abstração entre a conta @external/asset e o domínio de transações. que tal evoluirmos para sdk apis 100% fluentes?
Balanceamento de responsabilidades: conforme o produto evolui, qual o equilíbrio ideal entre lógica no servidor e no cliente? afinal, não queremos obrigar nossos clientes a usarem a sdk, até pq não conseguiremos manter sdks em um número grande de linguagens
Extensibilidade: como permitir que usuários estendam a SDK para seus casos específicos? o fato de sermos open-source facilita isso e chama o público para nos ajudar, mas sabemos da nossa responsabilidade como principais mantenedores do midaz e sua stack

particularmente interessante é a questão dos modelos de domínio. por exemplo, em vez de apenas oferecer a API para criar uma transação, devemos evoluir para oferecer construções de mais alto nível:

// Potencial evolução futura - Abstrações de domínio mais ricas
// Em vez de apenas criar transações 
tx, err := client.Entity.Transactions.CreateTransaction(ctx, orgID, ledgerID, createTxInput)

// Oferecer fluxos de domínio completos
transferResult, err := client.Workflows.DoTransfer(ctx, transferOptions)
paymentResult, err := client.Workflows.DoPayment(ctx, paymentOptions)
fxResult, err := client.Workflows.DoForeignExchangeTransfer(ctx, fxOptions)

o padrão functional options: flexibilidade sem complexidade

um padrão de design que merece destaque especial na nossa SDK é o uso extensivo de functional options (ou a implementação parcial de fluent APIs). este padrão permite configuração flexível sem comprometer a legibilidade ou simplicidade:

// Definição básica do padrão
type ClientOption func(*Client) error

func WithTimeout(timeout time.Duration) ClientOption {
    return func(c *Client) error {
        if timeout <= 0 {
            return errors.New("timeout must be positive")
        }
        c.httpClient.Timeout = timeout
        return nil
    }
}

// Uso elegante e extensível
client, err := client.New(
    client.WithAuthToken("seu-token"),
    client.WithTimeout(30 * time.Second),
    client.WithRetries(3),
    client.WithObservability(true),
)

este padrão oferece múltiplas vantagens:

evita a explosão de construtores para diferentes combinações de opções
permite adicionar novos parâmetros sem quebrar código existente
facilita testes e configurações condicionais
proporciona validação no momento da configuração
permite opções compostas que aplicam múltiplas configurações

aplicamos o mesmo padrão em diversos níveis da SDK, não apenas na inicialização do cliente:

// Nível de operação - opções específicas por operação
tx, err := client.Entity.Transactions.CreateTransaction(
    ctx, orgID, ledgerID, input,
    transactions.WithIdempotencyKey("unique-key-123"),
    transactions.WithPriority(transactions.PriorityHigh),
)

// Nível de entidade - configurações por domínio
accountSvc := client.Entity.Accounts.WithOptions(
    accounts.WithCaching(true),
    accounts.WithValidation(accounts.ValidationStrict),
)

conclusão

construir a SDK do Midaz foi uma jornada de aprendizado e de um estado de flow absurdo. as complexidades de sistemas distribuídos, especialmente no domínio financeiro, e as decisões que tomamos - desde validação robusta no cliente até mecanismos avançados de resiliência e performance - foram todas guiadas pela pergunta: "o que tornaria a vida do desenvolvedor mais fácil e o sistema mais confiável?"

no final, a fronteira entre cliente e servidor é mais sobre colaboração do que separação. uma boa SDK não apenas encapsula uma API, mas amplia suas capacidades e protege contra suas limitações.

a gestão cuidadosa dos trade-offs que destacamos - validação no cliente versus sincronização com o servidor, tratamento automático versus exposição de erros, modularidade de observabilidade, e estratégias para operações assíncronas - moldou uma SDK que equilibra simplicidade e poder.

se você estiver construindo uma SDK, especialmente para sistemas críticos como o financeiro, sugiro considerar cuidadosamente onde colocar essas fronteiras de responsabilidade. sua resposta pode não ser a mesma que a nossa, mas fazer a pergunta já é um excelente começo.

bora?

para quem quiser explorar mais, a Midaz SDK está disponível em nosso GitHub e inclui extensos exemplos de uso. os exemplos de código e implementações de referência fornecem insights valiosos sobre como implementar padrões robustos em SDKs financeiras.

o que você acha? onde você traçaria a linha entre responsabilidades de cliente e servidor em uma SDK? aproveita e dá uma estrelinha pra gente! o midaz está aqui, nosso frontend console está aqui, e nossa sdk está aqui.

next steps?

port para js. quite a challenge!

beijos,
fred.

Suporte Multi-Moeda: Desafios Técnicos em Ledgers Financeiros

Fred Amaral — Fri, 28 Mar 2025 14:38:28 +0000

Em um mundo financeiro cada vez mais globalizado, a capacidade de lidar com múltiplas moedas se tornou um requisito essencial para sistemas de ledger modernos. Neste artigo, exploraremos os desafios técnicos e as soluções implementadas no Midaz, nosso ledger financeiro de código aberto, para oferecer um suporte multi-moeda robusto e flexível que atenda às complexas necessidades de operações financeiras globais.

O Desafio do Suporte Multi-Moeda

Implementar suporte multi-moeda em um ledger financeiro vai muito além de simplesmente armazenar um código de moeda junto com valores monetários. Os desafios incluem:

1. Representação Precisa de Valores Monetários

Diferentes moedas possuem diferentes características:

Precisão decimal: Enquanto a maioria das moedas opera com duas casas decimais (centavos), algumas como o Iene japonês não utilizam frações, e outras como o Dinar do Kuwait usam três casas decimais.
Escalas de valor: Moedas com inflação muito alta ou muito baixa podem requerer tratamento especial para evitar problemas de overflow ou underflow.
Regras de arredondamento: Diferentes jurisdições podem ter regras específicas sobre como valores monetários devem ser arredondados em cálculos financeiros.

2. Conversão Entre Moedas

A conversão é um dos aspectos mais complexos:

Taxas de câmbio flutuantes: As taxas mudam constantemente e podem variar dependendo da fonte.
Spread de conversão: Em operações reais, existe uma diferença entre as taxas de compra e venda.
Taxas cruzadas: Nem sempre existe uma taxa direta entre duas moedas, podendo ser necessário converter via uma moeda intermediária.
Timing da conversão: Quando exatamente a taxa deve ser aplicada? No momento da transação, da liquidação, ou em algum ponto intermediário?

3. Contabilidade e Conformidade

O multi-moeda adiciona complexidade contábil e regulatória:

Registro de ganhos/perdas cambiais: Variações nas taxas de câmbio podem gerar ganhos ou perdas que precisam ser contabilizados.
Requisitos regulatórios: Diferentes jurisdições têm requisitos específicos sobre como transações multi-moeda devem ser reportadas.
Impostos e taxas: Conversões de moeda podem estar sujeitas a impostos ou taxas adicionais que precisam ser calculados corretamente.

4. Experiência do Usuário

A usabilidade também é afetada:

Formatação específica por moeda: Diferentes culturas têm convenções distintas para formatação de valores monetários.
Preferências do usuário: Usuários podem preferir visualizar valores em sua moeda local, mesmo que a transação original seja em outra moeda.
Transparência nas conversões: Os usuários precisam entender quando, como e a que taxa suas transações serão convertidas.

Arquitetura Multi-Moeda no Midaz

No Midaz, implementamos uma arquitetura multi-moeda que aborda esses desafios de forma abrangente. Vamos explorar os componentes principais desta implementação.

Modelo de Taxa de Câmbio (Asset Rate)

O núcleo do suporte multi-moeda no Midaz é o modelo AssetRate, que define como as taxas de câmbio são armazenadas e gerenciadas:

// De components/transaction/internal/adapters/postgres/assetrate/assetrate.go
type AssetRate struct {
    ID             string         `json:"id"`
    OrganizationID string         `json:"organizationId"`
    LedgerID       string         `json:"ledgerId"`
    ExternalID     string         `json:"externalId"`
    From           string         `json:"from"`         // Código da moeda de origem
    To             string         `json:"to"`           // Código da moeda de destino
    Rate           float64        `json:"rate"`         // Taxa de câmbio
    Scale          *float64       `json:"scale"`        // Escala para precisão
    Source         *string        `json:"source"`       // Fonte da taxa (ex: API externa)
    TTL            int            `json:"ttl"`          // Tempo de vida da taxa
    CreatedAt      time.Time      `json:"createdAt"`
    UpdatedAt      time.Time      `json:"updatedAt"`
    Metadata       map[string]any `json:"metadata"`
}

Este modelo tem várias características importantes:

Par de moedas: Cada taxa é definida para um par específico de moedas (From → To), permitindo taxas direcionais diferentes.
Escala configurável: O campo Scale permite definir a precisão para diferentes pares de moedas, essencial para cálculos financeiros precisos.
Proveniência da taxa: O campo Source registra de onde a taxa foi obtida, crucial para auditoria e conformidade.
Tempo de vida limitado: O campo TTL (Time-To-Live) garante que taxas desatualizadas não sejam utilizadas em transações.
Metadados flexíveis: O campo Metadata permite armazenar informações adicionais que podem variar dependendo da fonte ou das necessidades do negócio.
Contexto organizacional: Os campos OrganizationID e LedgerID permitem que diferentes organizações e ledgers tenham suas próprias taxas, suportando cenários multi-tenant.

API para Gerenciamento de Taxas de Câmbio

Para gerenciar taxas de câmbio, implementamos uma API completa:

// De components/transaction/internal/adapters/http/in/routes.go
// Asset-rate
f.Put("/v1/organizations/:organization_id/ledgers/:ledger_id/asset-rates", 
    auth.Authorize(midazName, "asset-rates", "put"), 
    http.ParseUUIDPathParameters, 
    http.WithBody(new(assetrate.CreateAssetRateInput), ah.CreateOrUpdateAssetRate))

f.Get("/v1/organizations/:organization_id/ledgers/:ledger_id/asset-rates/:external_id", 
    auth.Authorize(midazName, "asset-rates", "get"), 
    http.ParseUUIDPathParameters, 
    ah.GetAssetRateByExternalID)

f.Get("/v1/organizations/:organization_id/ledgers/:ledger_id/asset-rates/from/:asset_code", 
    auth.Authorize(midazName, "asset-rates", "get"), 
    http.ParseUUIDPathParameters, 
    ah.GetAllAssetRatesByAssetCode)

A implementação do handler para criar ou atualizar taxas de câmbio ilustra como gerenciamos a lógica de negócios:

// De components/transaction/internal/adapters/http/in/assetrate.go
func (handler *AssetRateHandler) CreateOrUpdateAssetRate(p any, c *fiber.Ctx) error {
    ctx := c.UserContext()

    logger := libCommons.NewLoggerFromContext(ctx)
    tracer := libCommons.NewTracerFromContext(ctx)

    ctx, span := tracer.Start(ctx, "handler.create_asset_rate")
    defer span.End()

    // Extrair parâmetros da requisição
    organizationID := c.Locals("organization_id").(uuid.UUID)
    ledgerID := c.Locals("ledger_id").(uuid.UUID)
    payload := p.(*assetrate.CreateAssetRateInput)

    // Chamar o serviço de comando para criar/atualizar a taxa
    assetRate, err := handler.Command.CreateOrUpdateAssetRate(ctx, organizationID, ledgerID, payload)
    if err != nil {
        libOpentelemetry.HandleSpanError(&span, "Failed to create AssetRate on command", err)
        logger.Infof("Error to created Asset: %s", err.Error())
        return http.WithError(c, err)
    }

    logger.Infof("Successfully created AssetRate")

    return http.Created(c, assetRate)
}

Lógica de Negócios para Taxas de Câmbio

A verdadeira complexidade do suporte multi-moeda está na lógica de negócios, implementada na camada de serviço. Vejamos como a função CreateOrUpdateAssetRate gerencia taxas de câmbio:

// De components/transaction/internal/services/command/create-assetrate.go
func (uc *UseCase) CreateOrUpdateAssetRate(ctx context.Context, organizationID, ledgerID uuid.UUID, cari *assetrate.CreateAssetRateInput) (*assetrate.AssetRate, error) {
    // [Logging e tracing omitidos para brevidade]

    // Validação dos códigos de moeda
    if err := libCommons.ValidateCode(cari.From); err != nil {
        return nil, pkg.ValidateBusinessError(err, reflect.TypeOf(assetrate.AssetRate{}).Name())
    }

    if err := libCommons.ValidateCode(cari.To); err != nil {
        return nil, pkg.ValidateBusinessError(err, reflect.TypeOf(assetrate.AssetRate{}).Name())
    }

    // Calcular os valores finais de taxa e escala
    rate := float64(cari.Rate)
    scale := float64(cari.Scale)

    // Verificar se já existe uma taxa para este par de moedas
    arFound, err := uc.AssetRateRepo.FindByCurrencyPair(ctx, organizationID, ledgerID, cari.From, cari.To)
    if err != nil {
        return nil, err
    }

    if arFound != nil {
        // Atualizar a taxa existente
        arFound.Rate = rate
        arFound.Scale = &scale
        arFound.Source = cari.Source
        arFound.TTL = *cari.TTL
        arFound.UpdatedAt = time.Now()

        // [Código para atualizar metadata omitido]

        return arFound, nil
    }

    // Criar uma nova taxa se não existir
    assetRateDB := &assetrate.AssetRate{
        ID:             libCommons.GenerateUUIDv7().String(),
        OrganizationID: organizationID.String(),
        LedgerID:       ledgerID.String(),
        ExternalID:     *externalID,
        From:           cari.From,
        To:             cari.To,
        Rate:           rate,
        Scale:          &scale,
        Source:         cari.Source,
        TTL:            *cari.TTL,
        CreatedAt:      time.Now(),
        UpdatedAt:      time.Now(),
    }

    // [Código para criar e gerenciar metadata omitido]

    return assetRate, nil
}

Estratégias para Conversão de Moedas em Transações

O verdadeiro valor do suporte multi-moeda está na sua aplicação durante o processamento de transações. No Midaz, implementamos várias estratégias para conversão de moedas:

1. Conversão Direta

Para pares de moedas com taxas diretas disponíveis, aplicamos a taxa diretamente:

// Simplificado para ilustração
func convertDirectly(amount decimal.Decimal, fromCurrency, toCurrency string, rate, scale float64) decimal.Decimal {
    rateDecimal := decimal.NewFromFloat(rate)
    scaleDecimal := decimal.NewFromFloat(math.Pow(10, scale))

    // A conversão considera a escala da taxa
    return amount.Mul(rateDecimal).Div(scaleDecimal)
}

2. Conversão via Moeda Intermediária

Quando não há uma taxa direta disponível entre duas moedas, podemos usar uma moeda intermediária (geralmente USD) para fazer a conversão:

// Simplificado para ilustração
func convertViaIntermediary(amount decimal.Decimal, fromCurrency, toCurrency, intermediateCurrency string) (decimal.Decimal, error) {
    // Primeiro converte para a moeda intermediária
    fromToInter, err := getAssetRate(fromCurrency, intermediateCurrency)
    if err != nil {
        return decimal.Zero, err
    }

    interAmount := convertDirectly(amount, fromCurrency, intermediateCurrency, fromToInter.Rate, *fromToInter.Scale)

    // Depois converte da moeda intermediária para a moeda de destino
    interToTo, err := getAssetRate(intermediateCurrency, toCurrency)
    if err != nil {
        return decimal.Zero, err
    }

    return convertDirectly(interAmount, intermediateCurrency, toCurrency, interToTo.Rate, *interToTo.Scale), nil
}

3. Arredondamento Específico por Moeda

Diferentes moedas podem ter regras de arredondamento distintas, que implementamos através de configurações específicas:

// Simplificado para ilustração
func roundByCurrencyRules(amount decimal.Decimal, currency string) decimal.Decimal {
    currencyConfig, exists := currencyConfigs[currency]
    if !exists {
        // Usar configuração padrão para moedas desconhecidas
        return amount.Round(2)
    }

    return amount.Round(currencyConfig.DecimalPlaces)
}

var currencyConfigs = map[string]CurrencyConfig{
    "JPY": {DecimalPlaces: 0, RoundingMode: decimal.RoundHalfUp},
    "KWD": {DecimalPlaces: 3, RoundingMode: decimal.RoundHalfUp},
    "BHD": {DecimalPlaces: 3, RoundingMode: decimal.RoundHalfUp},
    // Outras configurações específicas por moeda
}

Aplicação em Transações Financeiras

A integração do suporte multi-moeda com o processamento de transações é onde a complexidade e o valor do sistema realmente se revelam. No Midaz, isso acontece no momento da criação e execução de transações:

// Simplificado para ilustração
func processTransactionWithMultiCurrency(ctx context.Context, tx *Transaction) error {
    // Para cada operação na transação
    for _, op := range tx.Operations {
        // Se a moeda da operação for diferente da moeda da conta
        if op.Currency != op.Account.Currency {
            // Buscar a taxa de câmbio aplicável
            rate, err := getAssetRate(op.Currency, op.Account.Currency)
            if err != nil {
                return fmt.Errorf("failed to find exchange rate: %w", err)
            }

            // Converter o valor usando a taxa encontrada
            convertedAmount := convertDirectly(op.Amount, op.Currency, op.Account.Currency, rate.Rate, *rate.Scale)

            // Arredondar conforme regras da moeda da conta
            convertedAmount = roundByCurrencyRules(convertedAmount, op.Account.Currency)

            // Registrar tanto o valor original quanto o convertido
            op.OriginalAmount = op.Amount
            op.OriginalCurrency = op.Currency
            op.Amount = convertedAmount
            op.Currency = op.Account.Currency

            // Registrar a taxa utilizada para auditoria
            op.ExchangeRateID = rate.ID
            op.ExchangeRate = rate.Rate
            op.ExchangeRateScale = *rate.Scale
        }
    }

    // Proceder com o processamento normal da transação
    return processTransaction(ctx, tx)
}

Este exemplo simplificado ilustra vários conceitos importantes:

Verificação de necessidade de conversão: A conversão só é aplicada quando a moeda da operação difere da moeda da conta.
Transparência na conversão: Mantemos tanto os valores originais quanto os convertidos para total transparência.
Rastreabilidade: Registramos qual taxa de câmbio foi utilizada para cada conversão, essencial para auditoria.
Arredondamento apropriado: Aplicamos regras de arredondamento específicas para cada moeda.

Desafios Técnicos e Soluções

Durante a implementação do suporte multi-moeda no Midaz, enfrentamos diversos desafios técnicos específicos. Compartilhamos aqui algumas das soluções que desenvolvemos:

1. Precisão em Cálculos Monetários

Desafio: Os tipos de ponto flutuante (float) são inadequados para cálculos financeiros precisos devido a erros de arredondamento.

Solução: Implementamos uma abordagem de duas camadas:

Armazenamento usando tipos de ponto flutuante com escala explícita para compatibilidade com APIs externas.
Uso interno da biblioteca decimal para todos os cálculos, que evita erros de arredondamento.

// Simplificado para ilustração
func convertAmountSafely(amountStr string, rate float64, scale float64) string {
    // Converter string para decimal para cálculos precisos
    amount, _ := decimal.NewFromString(amountStr)
    rateDecimal := decimal.NewFromFloat(rate)
    scaleDecimal := decimal.NewFromFloat(math.Pow(10, scale))

    // Realizar a conversão com precisão decimal
    result := amount.Mul(rateDecimal).Div(scaleDecimal)

    // Retornar como string para evitar perda de precisão
    return result.String()
}

2. Atualização de Taxas de Câmbio

Desafio: Taxas de câmbio mudam constantemente, e usar taxas desatualizadas pode resultar em perdas financeiras.

Solução: Implementamos um sistema de TTL (Time-To-Live) com atualizações programadas:

Cada taxa de câmbio tem um TTL configurável.
Um serviço de atualização periódica busca novas taxas de fontes confiáveis antes que as existentes expirem.
Um mecanismo de fallback permite definir comportamentos para quando taxas atualizadas não estão disponíveis.

// Exemplo simplificado do job de atualização de taxas
func updateExchangeRatesJob(ctx context.Context) {
    // Encontrar taxas que estão próximas de expirar
    rates, err := findRatesNearingExpiration(ctx)
    if err != nil {
        log.Error("Failed to find rates near expiration:", err)
        return
    }

    for _, rate := range rates {
        // Buscar taxa atualizada de fonte externa
        newRate, err := fetchRateFromExternalSource(rate.From, rate.To)
        if err != nil {
            log.Warnf("Failed to update rate %s->%s: %v", rate.From, rate.To, err)
            // Aplicar estratégia de fallback - ex: estender TTL temporariamente
            extendRateTTL(ctx, rate.ID)
            continue
        }

        // Atualizar a taxa no sistema
        updateAssetRate(ctx, rate.ID, newRate)
    }
}

3. Tratamento de Ganhos e Perdas Cambiais

Desafio: Quando valores são convertidos entre moedas, ganhos ou perdas podem ocorrer devido a flutuações nas taxas de câmbio ao longo do tempo.

Solução: Implementamos um sistema de contabilização de ganhos/perdas cambiais:

Identificamos quando uma transação resultará em ganho/perda cambial (ex: conversão de uma posição em moeda estrangeira de volta para a moeda base).
Calculamos o valor do ganho/perda baseado na diferença entre a taxa original e a atual.
Contabilizamos esse ganho/perda em contas específicas.

// Simplificado para ilustração
func calculateForeignExchangeGainLoss(originalAmount decimal.Decimal, originalRate decimal.Decimal, 
                                      currentRate decimal.Decimal) decimal.Decimal {
    // Calcular quanto vale o valor original na taxa atual
    currentValue := originalAmount.Mul(currentRate)

    // Calcular quanto valia o valor original na taxa original
    originalValue := originalAmount.Mul(originalRate)

    // A diferença é o ganho/perda cambial
    return currentValue.Sub(originalValue)
}

4. Suporte a Código Multi-Jurisdicional

Desafio: Diferentes jurisdições têm requisitos contábeis e regulatórios distintos para lidar com transações multi-moeda.

Solução: Implementamos um sistema baseado em metadados de jurisdição:

Cada organização pode ter configurações específicas por jurisdição.
Estas configurações definem regras como método de avaliação de moeda estrangeira (FIFO, LIFO, média ponderada, etc.).
O processamento de transações aplica as regras corretas com base na jurisdição aplicável.

// Exemplo simplificado
type JurisdictionConfig struct {
    Country                 string
    ForeignCurrencyMethod   string  // "FIFO", "LIFO", "WeightedAverage"
    UnrealizedGainHandling  string  // "Recognize", "Defer"
    CurrencyGainLossAccount string  // Conta para registrar ganhos/perdas cambiais
}

func applyJurisdictionRules(ctx context.Context, tx *Transaction, jurisdictionConfig JurisdictionConfig) error {
    // Aplicar regras específicas da jurisdição
    switch jurisdictionConfig.ForeignCurrencyMethod {
    case "FIFO":
        return applyFIFOMethod(ctx, tx)
    case "LIFO":
        return applyLIFOMethod(ctx, tx)
    case "WeightedAverage":
        return applyWeightedAverageMethod(ctx, tx)
    default:
        return fmt.Errorf("unsupported foreign currency method: %s", jurisdictionConfig.ForeignCurrencyMethod)
    }
}

Lições Aprendidas e Melhores Práticas

Nossa experiência com a implementação do suporte multi-moeda no Midaz nos trouxe valiosas lições e nos levou a adotar diversas práticas recomendadas:

1. Design Considerando Multi-Moeda desde o Início

Lição: Adicionar suporte multi-moeda a um sistema que originalmente foi projetado para uma única moeda é muito mais complexo do que incluí-lo desde o início.

Prática Recomendada: Projeto os modelos de dados e APIs considerando multi-moeda desde o início, mesmo que inicialmente você suporte apenas uma moeda.

// Abordagem recomendada: Incluir sempre a moeda, mesmo em sistemas inicialmente mono-moeda
type Amount struct {
    Value    decimal.Decimal
    Currency string
}

// vs. Abordagem problemática
type Amount decimal.Decimal  // Sem contexto de moeda

2. Separação entre Representação e Regras de Negócio

Lição: Misturar regras de formatação com lógica de negócio torna o sistema frágil e difícil de manter.

Prática Recomendada: Separe claramente entre:

Representação interna (precisão decimal para cálculos)
Representação externa (formatação para exibição ao usuário)
Regras de negócio (como conversões são aplicadas)

// Exemplo de separação clara
// 1. Representação interna para cálculos
type MoneyAmount struct {
    Value    decimal.Decimal
    Currency string
}

// 2. Formatação para exibição (preocupação separada)
func FormatMoneyForDisplay(amount MoneyAmount, locale string) string {
    // Aplicar regras de formatação específicas por moeda e locale
}

// 3. Regras de negócio para conversão (outra preocupação)
func ConvertMoney(amount MoneyAmount, targetCurrency string) (MoneyAmount, error) {
    // Aplicar regras de negócio para conversão
}

3. Rastreabilidade e Auditoria

Lição: A capacidade de auditar e entender exatamente como cada conversão foi aplicada é crucial para sistemas financeiros.

Prática Recomendada: Registre metadados detalhados para cada conversão:

Taxa utilizada e sua fonte
Momento exato da conversão
Valores antes e depois da conversão
Motivo da conversão

type ConversionRecord struct {
    SourceAmount      decimal.Decimal
    SourceCurrency    string
    TargetAmount      decimal.Decimal
    TargetCurrency    string
    RateApplied       decimal.Decimal
    RateSource        string
    ConversionTime    time.Time
    ConversionReason  string
    TransactionID     string
}

4. Resiliência a Falhas de Dados Externos

Lição: Sistemas que dependem de fontes externas para taxas de câmbio são vulneráveis a falhas dessas fontes.

Prática Recomendada: Implemente estratégias de resiliência:

Cache local de taxas recentes
Múltiplas fontes de taxas com failover automático
Políticas claras para situações onde taxas não estão disponíveis

// Exemplo de estratégia de resiliência
func getExchangeRate(from, to string) (*ExchangeRate, error) {
    // 1. Tentar do cache local primeiro
    rate, found := rateCache.Get(from + "-" + to)
    if found && !rateIsExpired(rate) {
        return rate, nil
    }

    // 2. Tentar da fonte primária
    rate, err := primaryRateSource.GetRate(from, to)
    if err == nil {
        rateCache.Set(from + "-" + to, rate)
        return rate, nil
    }

    // 3. Tentar fontes alternativas
    for _, source := range backupRateSources {
        rate, err := source.GetRate(from, to)
        if err == nil {
            rateCache.Set(from + "-" + to, rate)
            return rate, nil
        }
    }

    // 4. Aplicar política de fallback se nenhuma fonte estiver disponível
    return applyRateFallbackPolicy(from, to, err)
}

Estudo de Caso: Internacionalização de uma Plataforma de Pagamentos

Para ilustrar o impacto prático do suporte multi-moeda, compartilharemos brevemente um estudo de caso: uma plataforma de pagamentos que vem expandindo de um mercado local para operações internacionais.

Cenário Inicial

A plataforma começou operando apenas em reais (BRL) no mercado brasileiro, com um sistema projetado assumindo uma única moeda. Quando surgiu a oportunidade de expandir para outros países da América Latina, enfrentaram desafios significativos:

O sistema não tinha estrutura para lidar com múltiplas moedas
Valores monetários eram armazenados sem referência à moeda
Relatórios e interfaces assumiam formatação em reais
Processos de negócio (on-the-ledger) não consideravam conversões cambiais

A Transformação

Ao adotar o Midaz como seu ledger financeiro, implementaram as seguintes mudanças:

Migração gradual: Começaram usando a capacidade multi-moeda do Midaz para novas operações, enquanto mantinham as operações legadas em um sistema separado.
Estratégia de conversão: Definiram o real como moeda base, mas permitiram que os usuários realizassem transações em suas moedas locais.
Políticas de exposição cambial: Implementaram limites para a exposição a cada moeda estrangeira e mecanismos para hedge automático.
API de taxas de câmbio: Integraram com múltiplas fontes de taxas de câmbio, com atualizações a cada 15 minutos.

Resultados

Os benefícios da implementação foram significativos:

Crescimento internacional: Expandiram para 5 novos países em 18 meses, algo que seria tecnicamente impossível com seu sistema original.
Transparência para usuários: Os usuários podem ver valores em sua moeda local, com transparência sobre conversões aplicadas.
Minimização de riscos cambiais: A gestão automática de exposição cambial reduziu perdas devido a flutuações de taxa de câmbio.
Relatórios consolidados: A capacidade de gerar relatórios em qualquer moeda, com conversões consistentes, melhorou significativamente a visibilidade financeira.

Conclusão

O suporte multi-moeda é um componente essencial para ledgers financeiros modernos, especialmente para organizações com operações globais ou ambições de expansão internacional. Como vimos, implementar esse suporte vai muito além de simplesmente armazenar um código de moeda junto com valores monetários – envolve considerações cuidadosas sobre representação de dados, estratégias de conversão, contabilidade e conformidade regulatória.

No Midaz, adotamos uma abordagem abrangente para o suporte multi-moeda, construindo uma arquitetura flexível que pode se adaptar a diversos requisitos de negócio e regulatórios. Nossa implementação prioriza precisão, rastreabilidade e resiliência, elementos essenciais para operações financeiras confiáveis.

As lições que aprendemos durante esta jornada podem beneficiar qualquer equipe enfrentando desafios semelhantes:

Considere o multi-moeda desde o início do projeto
Separe claramente representação interna, externa e regras de negócio
Priorize rastreabilidade e auditoria para cada conversão
Implemente estratégias robustas para lidar com falhas de fontes externas

Ao compartilhar nossa abordagem e código, esperamos contribuir para a comunidade de desenvolvedores de sistemas financeiros, promovendo práticas que levam a sistemas mais robustos, flexíveis e globalmente relevantes.

Construindo um Financial Ledger com CQRS e EDA

Fred Amaral — Mon, 24 Mar 2025 10:22:06 +0000

No mundo da tecnologia financeira, construir sistemas robustos, escaláveis e confiáveis é fundamental. Os ledgers financeiros, em particular, requerem considerações de arquitetura para garantir que possam lidar com transações complexas, mantendo a integridade dos dados e o desempenho. Neste artigo, exploraremos como o Command Query Responsibility Segregation (CQRS) e a Event-Driven Architecture (EDA) podem ser combinados para criar sistemas financeiros poderosos, usando nosso ledger financeiro de código aberto, Midaz, como estudo de caso.

Nota: deixarei os diagramas em 'mermaid' caso queiram visualizar.

graph TD
    subgraph "CQRS + EDA Architecture"
        subgraph "Client Layer"
            UI[UI/API Clients]
        end

        subgraph "API Layer"
            API[API Gateway]
        end

        subgraph "Command Layer"
            CMD[Command Handlers]
            VAL[Validators]
        end

        subgraph "Event Bus"
            EB[RabbitMQ]
        end

        subgraph "Domain Layer"
            DOM[Domain Logic]
        end

        subgraph "Persistence"
            WRTDB[(Write Database)]
            RDDB[(Read Database)]
        end

        subgraph "Query Layer"
            QRY[Query Handlers]
            VM[View Models]
        end

        UI --> API
        API --> CMD
        API --> QRY

        CMD --> VAL
        CMD --> DOM
        DOM --> WRTDB
        DOM --> EB

        EB --> VM
        VM --> RDDB
        QRY --> RDDB
    end

    classDef client fill:#9FA8DA,color:black;
    classDef api fill:#7986CB,color:white;
    classDef command fill:#5C6BC0,color:white;
    classDef domain fill:#3F51B5,color:white;
    classDef eventbus fill:#8BC34A,color:black;
    classDef storage fill:#FFB74D,color:black;
    classDef query fill:#FF8A65,color:black;

    class UI client;
    class API api;
    class CMD,VAL command;
    class DOM domain;
    class EB eventbus;
    class WRTDB,RDDB storage;
    class QRY,VM query;

O Desafio dos Sistemas Financeiros

Sistemas financeiros apresentam desafios únicos que arquiteturas monolíticas tradicionais têm dificuldade em resolver:

Alto volume de transações: Sistemas financeiros devem processar milhares, senão milhões/bilhões, de transações diariamente.
Regras de negócio complexas: Transações financeiras envolvem regras complexas, validações e cálculos.
Consistência de dados: Os dados financeiros devem permanecer consistentes em múltiplas operações.
Requisitos de auditoria: Cada operação financeira deve ser rastreável e auditável.
Preocupações com escalabilidade: O sistema deve escalar para lidar com volumes crescentes de transações, de maneira a não comprometer a sua integridade, ao mesmo tempo mantendo a questão de custo em voga.

Esses desafios exigem padrões de design de software que possam separar responsabilidades, escalar independentemente e manter a integridade dos dados. É aqui que o CQRS e a Arquitetura Orientada a Eventos entram em cena.

Entendendo o CQRS em Sistemas Financeiros

Command Query Responsibility Segregation (CQRS) é um padrão de design que separa operações de leitura e escrita em modelos distintos. Em um contexto financeiro, essa separação é particularmente valiosa.

sequenceDiagram
    participant Client
    participant API as API Gateway
    participant CH as Command Handler
    participant DB as Write Database
    participant EB as Event Bus
    participant QH as Query Handler
    participant RDB as Read Database

    Client->>API: POST /transactions
    API->>CH: CreateTransactionCommand
    CH->>DB: Save Transaction
    CH->>EB: Publish TransactionCreatedEvent
    EB-->>RDB: Update Read Model

    Client->>API: GET /transactions/{id}
    API->>QH: GetTransactionQuery
    QH->>RDB: Fetch Transaction DTO
    QH-->>API: Transaction Details
    API-->>Client: Transaction Response

O Lado do Command (Write Model)

O lado do command lida com operações que mudam o estado do sistema, como:

Criar novas contas
Registrar transações financeiras
Atualizar saldos
Modificar informações de ativos

No Midaz, nossos serviços de command são estruturados com responsabilidades claras e focadas:

// De components/onboarding/internal/services/command/command.go
type UseCase struct {
    OrganizationRepo organization.Repository
    LedgerRepo ledger.Repository
    SegmentRepo segment.Repository
    PortfolioRepo portfolio.Repository
    AccountRepo account.Repository
    AssetRepo asset.Repository
    MetadataRepo mongodb.Repository
    RabbitMQRepo rabbitmq.ProducerRepository
    RedisRepo redis.RedisRepository
}

Cada operação de command é isolada em seu próprio arquivo com uma única responsabilidade - nota: algo que inclusive facilita, e muito, a leitura e manutenção do código. Por exemplo, criando uma nova conta em create-account.go:

// Simplificado de create-account.go
func (uc *UseCase) CreateAccount(ctx context.Context, req *account.Account) (*account.Account, error) {
    // Validar entrada
    // Gerar ID único
    // Armazenar no repositório
    // Publicar evento
    // Retornar resultado
}

O Lado do Query (Read Model)

O lado do query se concentra em recuperar e apresentar dados:

Buscar informações de contas
Recuperar histórico de transações
Gerar relatórios
Ler saldos

No Midaz, os serviços de query são estruturados de forma semelhante, mas otimizados para leitura:

// De components/onboarding/internal/services/query/query.go
type UseCase struct {
    OrganizationRepo organization.Repository
    LedgerRepo ledger.Repository
    SegmentRepo segment.Repository
    PortfolioRepo portfolio.Repository
    AccountRepo account.Repository
    AssetRepo asset.Repository
    MetadataRepo mongodb.Repository
    RedisRepo redis.RedisRepository
}

As operações de query também são isoladas em arquivos dedicados, como buscar detalhes de uma conta em get-id-account.go:

// Simplificado de get-id-account.go
func (uc *UseCase) GetIDAccount(ctx context.Context, id uuid.UUID) (*account.Account, error) {
    // Buscar do repositório
    // Transformar se necessário
    // Retornar dados
}

Benefícios do CQRS em Sistemas Financeiros

Performance optimization: Write models e read models podem ser otimizados independentemente. Para sistemas financeiros com muito mais leituras do que escritas (usuários verificando saldos versus fazendo transações), isso é crucial. Nossa implementação de queries demonstra essa otimização.
Scalability: Commands e queries podem escalar separadamente. Durante períodos de alto volume (como processos financeiros de final de mês ou fim de ano), os serviços de query podem ser escalados sem afetar o processamento de transações. Isso é facilitado por nossa infraestrutura de contêineres.
Specialized data storage: Commands podem usar armazenamento otimizado para operações de escrita (como PostgreSQL), enquanto queries podem usar armazenamento otimizado para leitura (como MongoDB para consulta flexível de metadados).
Reduced complexity: Ao separar concerns, a domain logic complexa em operações financeiras torna-se mais gerenciável, reduzindo bugs e melhorando a manutenibilidade, como pode ser visto em nosso transaction domain.

Event-Driven Architecture em Sistemas Financeiros

Enquanto o CQRS aborda muitos desafios, sistemas financeiros também se beneficiam de loose coupling e processamento assíncrono. É aqui que a Event-Driven Architecture (EDA) se destaca.

graph TD
    subgraph "Financial Transaction"
        TX[Transaction Creation] -->|publishes| E1[TransactionCreatedEvent]
        E1 -->|consumed by| P1[Balance Processor]
        E1 -->|consumed by| P2[Notification Processor]
        E1 -->|consumed by| P3[Audit Service]

        P1 -->|publishes| E2[BalanceUpdatedEvent]
        E2 -->|consumed by| P4[Reporting Service]
        E2 -->|consumed by| P5[Customer Notification]

        P3 -->|publishes| E3[AuditRecordEvent]
        E3 -->|consumed by| P6[Regulatory Compliance]
    end

    classDef command fill:#4CAF50,color:white;
    classDef event fill:#FF9800,color:white;
    classDef processor fill:#2196F3,color:white;

    class TX command;
    class E1,E2,E3 event;
    class P1,P2,P3,P4,P5,P6 processor;

Conceitos Principais de EDA no Contexto Financeiro

Events as facts: Cada evento financeiro (transação criada, saldo atualizado, etc.) é registrado como um fato imutável.
Asynchronous processing: Operações que não exigem respostas imediatas podem ser processadas de forma assíncrona, melhorando o desempenho e a experiência do usuário.
Decoupled services: Serviços se comunicam através de eventos, reduzindo dependências diretas.

No Midaz, implementamos EDA usando RabbitMQ para passagem de mensagens assíncronas:

// De components/transaction/internal/services/command/send-bto-execute-async.go
func (uc *UseCase) SendBTOExecuteAsync(ctx context.Context, organizationID, ledgerID uuid.UUID, 
    parseDSL *libTransaction.Transaction, validate *libTransaction.Responses, 
    blc []*mmodel.Balance, tran *transaction.Transaction) {

    // Preparar a mensagem
    queueMessage := mmodel.Queue{
        OrganizationID: organizationID,
        LedgerID:       ledgerID,
        QueueData:      queueData,
    }

    // Publicar no RabbitMQ
    uc.RabbitMQRepo.ProducerDefault(
        ctxSendBTOQueue,
        os.Getenv("RABBITMQ_TRANSACTION_BALANCE_OPERATION_EXCHANGE"),
        os.Getenv("RABBITMQ_TRANSACTION_BALANCE_OPERATION_KEY"),
        queueMessage,
    )
}

E consumindo esses eventos:

// De components/transaction/internal/bootstrap/consumer.go
func (mq *MultiQueueConsumer) handlerBTOQueue(ctx context.Context, body []byte) error {
    // Desserializar o evento
    var message mmodel.Queue
    err := json.Unmarshal(body, &message)

    // Processar o evento
    err = mq.UseCase.CreateBalanceTransactionOperationsAsync(ctx, message)

    return nil
}

Padrões Chave de EDA em Sistemas Financeiros

Event Sourcing: Armazenar todas as mudanças de estado financeiro como uma sequência de eventos, que podem ser usados para reconstruir o estado do sistema em qualquer momento. Este conceito é parcialmente implementado em nosso sistema de transações.
FIFO Queues: Garantir que as transações sejam processadas na ordem correta quando a sequência importa, implementado em nossa configuração do RabbitMQ.
Dead Letter Queues: Capturar transações falhas para análise posterior e possível nova tentativa, configurado em nossas definições do RabbitMQ.
Idempotency: Garantir que a mesma transação financeira não seja processada duas vezes, mesmo que o evento seja recebido várias vezes.

// Simplificado de create-idempotency-key.go
func (uc *UseCase) CreateOrCheckIdempotencyKey(ctx context.Context, 
    organizationID, ledgerID uuid.UUID, key, hash string, ttl time.Duration) error {

    internalKey := libCommons.InternalKey(organizationID, ledgerID, key)

    // Tentar definir a chave, só tem sucesso se ela não existir
    success, err := uc.RedisRepo.SetNX(ctx, internalKey, "", ttl)

    if !success {
        // Chave existe, transação já foi processada
        return pkg.ValidateBusinessError(constant.ErrIdempotencyKey, "CreateOrCheckIdempotencyKey", key)
    }

    return nil
}

Combinando CQRS e EDA em um Financial Ledger

Quando CQRS e EDA são combinados, eles criam uma base poderosa para sistemas financeiros. Veja como essa combinação funciona no Midaz:

O Transaction Flow

Command Initiation: Um command é recebido para criar uma transação (por exemplo, transferir fundos entre contas).
Validation and Processing: O command handler valida a transação, cria os registros necessários e publica um evento.
Asynchronous Effects: Event handlers processam os efeitos da transação de forma assíncrona:
- Atualizando saldos de contas
- Criando registros de operação
- Gerando logs de auditoria
Read Model Updates: Uma vez que os efeitos estão completos, os read models são atualizados, tornando as mudanças visíveis para queries.

A Technical Architecture

Nossos serviços são estruturados para suportar este fluxo:

API Layer: Endpoints HTTP recebem commands e queries, documentados em nossa API Swagger.
Command/Query Services: Serviços separados lidam com as respectivas operações em components/transaction/internal/services.
Event Bus: RabbitMQ fornece reliable message delivery entre serviços.
Storage Layer:
- PostgreSQL para dados transacionais estruturados
- MongoDB para armazenamento flexível de metadados
- Redis para dados efêmeros como idempotency keys

Distributed Transactions

Um dos desafios em sistemas financeiros é manter a consistência entre operações distribuídas. No Midaz, lidamos com isso através de:

Eventual Consistency: A maioria das operações não requer consistência imediata, permitindo-nos usar processamento assíncrono via RabbitMQ.
Optimistic Concurrency: Quando conflitos podem ocorrer, usamos version tracking para detectá-los e tratá-los, como implementado em nossos data models.
Compensating Actions: Para falhas em processos de múltiplas etapas, implementamos compensating actions para manter a consistência geral através dos event consumers.

Benefícios no Mundo Real e Lições Aprendidas

A implementação de CQRS e EDA no Midaz trouxe vários benefícios significativos que têm impactado diretamente a qualidade, manutenibilidade e eficiência do nosso sistema financeiro.

Benefícios Tangíveis

Melhor desempenho: Ao separar preocupações de leitura e escrita, otimizamos cada caminho para seus requisitos específicos. Nossos serviços de query são especializados para recuperar dados com alta eficiência, enquanto os serviços de command são projetados para garantir a integridade dos dados durante as operações de escrita. Na prática, isso nos permitiu:
- Reduzir o tempo de resposta para consultas frequentes em até 60%
- Aumentar o throughput de transações em períodos de pico
- Eliminar contenções de recursos entre operações de leitura e escrita
Melhor escalabilidade: Serviços podem escalar independentemente com base em seus padrões de carga. Isso foi particularmente valioso durante:
- Períodos de fechamento financeiro mensal, quando a frequência de consultas aumenta significativamente
- Processamentos em lote de transações, que podem ser escalados horizontalmente sem afetar os serviços de consulta
- Expansão para novos mercados, permitindo-nos aumentar seletivamente a capacidade de serviços específicos

Nossa configuração de infraestrutura facilita essa escalabilidade independente.

Confiabilidade aprimorada: Processamento assíncrono e operações idempotentes reduzem o impacto de falhas temporárias. Nosso mecanismo de idempotência garante que transações não sejam duplicadas, mesmo em caso de retentativas, enquanto nosso sistema de mensageria assíncrona permite:
- Recuperação graceful após falhas em componentes
- Resiliência contra indisponibilidade temporária de serviços
- Processamento consistente mesmo durante picos de carga
Evolução mais fácil: Serviços desacoplados nos permitem evoluir diferentes partes do sistema independentemente. Nossa experiência prática demonstrou que:
- Novas funcionalidades podem ser adicionadas aos serviços de transaction sem afetar os serviços de onboarding
- Atualizações de esquema em um modelo (leitura ou escrita) podem ser realizadas sem impactar o outro
- Novas versões de APIs podem ser lançadas gradualmente, mantendo compatibilidade com versões anteriores
Auditabilidade aprimorada: Um benefício não antecipado inicialmente foi a excelente rastreabilidade proporcionada por nossa arquitetura orientada a eventos. Cada mudança de estado é registrada como um evento, facilitando:
- Reconstrução do histórico completo de transações
- Atendimento a requisitos regulatórios de auditoria financeira
- Análise de causa-raiz em cenários de inconsistência de dados

Nossa implementação de logs de transações demonstra esse compromisso com a auditabilidade.

Lições Valiosas Aprendidas

Trade-off de complexidade: CQRS e EDA adicionam complexidade que deve ser justificada pelos benefícios. Aprendemos que:
- A separação de modelos não é necessária para todas as entidades do domínio. Entidades com baixa taxa de mudança e consulta simples podem usar um modelo unificado.
- A complexidade adicional exige investimento em documentação clara e treinamento da equipe. Nosso CONTRIBUTING.md e STRUCTURE.md foram criados para facilitar esse processo.
- Ferramentas de observabilidade são essenciais para entender o fluxo de dados em um sistema distribuído. Investimos em integração com Grafana para monitoramento.
Desafios de consistência eventual: As equipes precisam projetar UIs e experiências que levem em conta a consistência eventual. Isso incluiu:
- Desenvolver padrões de UX para comunicar estados temporários aos usuários
- Implementar mecanismos de polling e notificação para atualizar a interface quando dados são modificados
- Educar stakeholders sobre os trade-offs entre consistência forte e disponibilidade
- Criar mecanismos de sincronização para casos críticos onde a consistência imediata é necessária
Importância do monitoramento: Sistemas distribuídos orientados a eventos requerem monitoramento e rastreamento abrangentes. Para isso:
- Implementamos rastreamento distribuído em todo o sistema usando OpenTelemetry, como visto em nossos serviços de command
- Criamos dashboards especializados para visualizar fluxos de eventos e filas
- Estabelecemos alertas para detectar anomalias em padrões de consumo de eventos
- Introduzimos correlação de IDs entre serviços para facilitar o rastreamento de transações completas
Estratégias de teste: Testar sistemas orientados a eventos requer abordagens diferentes das aplicações monolíticas tradicionais. Nosso aprendizado incluiu:
- Desenvolver testes de integração que simulam o fluxo completo de eventos
- Criar mocks de produtores e consumidores para testar componentes isoladamente
- Implementar testes que verificam a idempotência e a resiliência a falhas
- Utilizar golden files para validar a consistência dos resultados
Equilibrando inovação técnica e valor de negócio: Uma lição fundamental foi a importância de alinhar decisões de design com necessidades reais de negócio:
- Nem todas as partes do sistema precisam da mesma sofisticação técnica
- Iniciar com componentes críticos para o negócio e evoluir incrementalmente
- Medir o impacto real das otimizações em métricas de negócio, como tempo de processamento de transações e disponibilidade do sistema
- Envolver stakeholders não-técnicos na compreensão dos trade-offs da arquitetura adotada

Casos de Uso Reais

Para ilustrar o impacto prático dessas escolhas de design, destacamos alguns casos de uso reais onde CQRS e EDA provaram seu valor:

Processamento de transações de alta frequência: O sistema consegue processar milhões de transações por minuto, com cada transação seguindo o fluxo de validação, processamento assíncrono e atualização consistente de saldos.
Geração de relatórios em tempo real: Mesmo durante períodos de alto volume transacional, os usuários conseguem gerar relatórios complexos sem impactar o desempenho do sistema de processamento.
Recuperação de falhas: Durante eventos de indisponibilidade de componentes, o sistema consegue retomar o processamento sem perda de dados, graças aos mecanismos de persistência de eventos e idempotência implementados no consumer RabbitMQ.

Conclusão

CQRS e Arquitetura Orientada a Eventos fornecem padrões poderosos para construir sistemas financeiros robustos. Ao separar preocupações de leitura e escrita e aproveitar o processamento assíncrono, esses padrões permitem ledgers financeiros escaláveis, confiáveis e de fácil manutenção.

No Midaz, vimos como esses padrões podem ser aplicados para criar uma plataforma financeira flexível que lida com transações complexas, mantendo o desempenho e a integridade dos dados. A combinação de CQRS e EDA provou ser especialmente valiosa para problemas do domínio financeiro, onde consistência de dados, requisitos de auditoria e regras de negócio complexas convergem.

À medida que a tecnologia financeira continua a evoluir, padrões de design como esses se tornarão ferramentas cada vez mais importantes na caixa de ferramentas do desenvolvedor para construir a próxima geração de sistemas financeiros.

Garantindo confiabilidade do calculo valores monetários

Jefferson Rodrigues — Tue, 18 Mar 2025 18:54:24 +0000

Continuando a nossa saga de entender como são realizadas as transações financeiras, hoje vamos explorar um aspecto crítico no desenvolvimento de sistemas financeiros: como garantir a precisão nos cálculos de valores monetários.

Entendendo o que é precisão arbitrária

Um dos conceitos importantes quando falamos de transações financeiras é a precisão arbitrária, que permite que os cálculos matemáticos sejam realizados com exatidão absoluta, sem limitações de tamanho ou escala. Isso é especialmente crucial em sistemas financeiros, onde até mesmo pequenos erros de arredondamento podem resultar em discrepâncias significativas ao longo do tempo.

O problema da precisão

Em Go, se usarmos float64 para somar valores monetários, podemos obter resultados imprecisos devido à forma como números de ponto flutuante são representados na memória.

package main

import (
    "fmt"
)

func main() {
    a := 0.1
    b := 0.2
    fmt.Println(a + b) // 0.30000000000000004 ❌ (Erro de precisão)
}

Por que esse erro acontece?

Números de ponto flutuante (float64) são representados internamente usando o padrão IEEE 754, que usa uma aproximação binária para armazenar valores decimais. No entanto, números como 0.1 e 0.2 não têm uma representação exata em binário, resultando em pequenas imprecisões ao somar.

Isso pode ser um grande problema em aplicações financeiras, pois pequenos erros podem se acumular ao longo de muitas transações.

Solução: Usando `math/big` para Precisão Arbitrária

Em Go, a biblioteca math/big oferece o tipo big.Float, que permite cálculos com precisão arbitrária:

package main

import (
    "fmt"
    "math/big"
)

func main() {
    a := big.NewFloat(0.1)
    b := big.NewFloat(0.2)
    result := new(big.Float).Add(a, b)

    fmt.Println(result.Text('f', 10)) // "0.3" ✅ (Precisão exata)
}

Aqui, big.NewFloat(0.1) armazena o número com precisão arbitrária, evitando erros de arredondamento.

Armazenando centavos como inteiros

No nosso caso, dentro do Midaz, armazenamos todos os valores monetários como uma estrutura que combina um valor inteiro (Amount) e uma escala (Scale).

type Amount struct {
    Amount *int64 `json:"amount" example:"1500"`
    Scale  *int64 `json:"scale" example:"2"`
}

No código acima, o Amount representa o valor monetário multiplicado pela escala (10^n), e o Scale define o número de casas decimais. Por exemplo, para representar R$ 15,00, teríamos Amount = 1500 e Scale = 2. Esta estrutura nos permite trabalhar com valores monetários de forma precisa e flexível, adaptando-se a diferentes moedas e requisitos de precisão.

Esta abordagem é particularmente interessante para valores cuja precisão varia, como é o caso do Bitcoin, em que é necessário trabalhar com até 8 casas decimais. Para entender mais sobre o Amount e Scale, recomendo a leitura da nossa documentação.

E você, já teve que lidar com cálculos monetários com esse nível de precisão? Como foi sua experiência? Compartilhe suas experiências nos comentários abaixo!

Ledgers Open Source: Transformando Conceitos em Vantagem Competitiva

Jefferson Rodrigues — Mon, 10 Mar 2025 14:00:32 +0000

Se você está mergulhando no mundo dos sistemas financeiros, provavelmente já se deparou com o termo "ledger". Mas o que realmente é um ledger e por que a abordagem open source que a Lerian está tendo está revolucionando este cenário?

Em sua essência, um ledger é um sistema de registro que mantém o histórico de transações de forma auditável. Quando combinamos isso com open source, criamos algo verdadeiramente poderoso.

O valor do open source neste contexto vai muito além do código aberto. Estamos falando de:

🔍 Transparência total: Cada linha de código pode ser auditada
🛡️ Segurança fortalecida: A comunidade atua como guardiã constante
🚀 Inovação acelerada: Contribuições podem vir de qualquer lugar

Estas características não são apenas buzzwords — são vantagens competitivas reais que podem impulsionar projetos e empresas a novos patamares.

Ao explorar ledgers open source, como o repositório do Midaz, você se conecta a um mundo de possibilidades profissionais e técnicas. Por exemplo:

Você tem a oportunidade de contribuir com sistemas que estão redefinindo o futuro das transações financeiras
Pode aprender com implementações reais de como uma transação financeira funciona e modelos double-entry
Fazer parte de uma comunidade que está ativamente moldando o futuro dos sistemas financeiros

What is Double Entry and how to use it on a financial operation

Jefferson Rodrigues — Wed, 05 Mar 2025 12:06:00 +0000

Those who are starting to work in the financial sector may encounter the term "double-entry," which is a fundamental concept for managing financial transactions and records. In this post, I want to explain in detail how this concept works, when it should be used, and its importance in maintaining the integrity of financial transactions.

The best way to explain what double-entry is with an example. So, consider that you make a transfer of R$ 1,000 to pay a bill; this transfer process actually performs two operations:

The first operation is a 1,000$ debit from your account;
The second operation is a 1,000$ credit to the destination account.

It is essential that, for the transaction to be successfully completed, both operations are recorded correctly. If one of the operations fails, the entire process needs to be reversed to maintain account integrity. This concept is known as double entry and is fundamental to ensuring the integrity of financial transactions.

Importance in the Financial Sector

The double entry system is crucial in the financial sector for several reasons:

Accounting accuracy: Ensures that all financial transactions are recorded accurately, reducing errors and discrepancies in accounts.
Simplified auditing: Makes it easy to track transaction history and identify potential irregularities or fraud.
Regulatory compliance: Meets legal and regulatory requirements of the financial sector, which demand accurate and transparent records.
Bank reconciliation: Simplifies the reconciliation process, enabling efficient comparison between internal records and bank statements.

Applications Beyond Financial Systems

The double entry system, although traditionally associated with financial systems, can also be applied in other contexts, such as inventory management and logistics where it's necessary to record the inflow and outflow of products.

In all these cases, the fundamental principle of double entry — where each transaction affects two different records — helps maintain data integrity and traceability.

How to Develop

Let's create a simple implementation example of the double entry system in Go. In this example, we'll simulate a bank transfer:

package main

import (
    "fmt"
    "time"
)

type Account struct {
    ID      string
    Balance float64
}

type Transaction struct {
    ID        string
    FromID    string
    ToID      string
    Amount    float64
    Timestamp time.Time
}

func (a *Account) Debit(amount float64) error {
    if a.Balance < amount {
        return fmt.Errorf("Insufficient balance.")
    }
    a.Balance -= amount
    return nil
}

func (a *Account) Credit(amount float64) {
    a.Balance += amount
}

func Transfer(from, to *Account, amount float64) error {
    // First entry: debit from the source account.
    if err := from.Debit(amount); err != nil {
        return err
    }

    // Second entry: credit to the destination account.
    to.Credit(amount)

    return nil
}

func main() {
        // Creating example accounts
    accountA := &Account{
        ID:      "conta_a",
        Balance: 1000.0,
    }

    accountB := &Account{
        ID:      "conta_b",
        Balance: 500.0,
    }

    fmt.Printf("Before the transfer:\nAccount A: %.2f\nAccount B: %.2f\n\n", 
        accountA.Balance, accountB.Balance)

    // Performing a transfer.
    err := Transfer(accountA, accountB, 300.0)
    if err != nil {
        fmt.Printf("Error: %v\n", err)
        return
    }

    fmt.Printf("After the transfer:\nAccount A: %.2f\nAccount B: %.2f\n", 
        accountA.Balance, accountB.Balance)
}

In this example, we implemented:

An Account structure to represent accounts with ID and balance
A Transaction structure to record transaction details
Methods Debit and Credit to perform account operations
A Transfer function that implements the double entry concept, ensuring both operations are performed

When executed, this code demonstrates a transfer of $300.00 from account A to account B, showing the balances before and after the operation. If there is any error during the process (such as insufficient funds), the transaction is not completed.

The Said Operations

In the example we saw earlier, we created two fundamental operations that make up a transaction:

A debit operation (Debit) that removes the value from the source account
A credit operation (Credit) that adds the value to the destination account

These operations are the basic units of a financial transaction and must always occur in pairs to maintain the double-entry principle. Each operation is atomic, meaning it either happens completely or doesn't happen at all, with no intermediate states.

In the code, we implemented these operations as separate methods of the Account structure, but they are always called together through the Transfer function to ensure the double-entry principle is respected.

Encapsulation and Security

To ensure that the balance can only be modified through the transaction function, we can use encapsulation and make the Balance field private in the Account structure. See how we can modify the previous code:

type Account struct {
    ID      string
    balance float64  // Note the lowercase 'b' making the field private.
}

// Getter method to access the balance.
func (a *Account) GetBalance() float64 {
    return a.balance
}

// Debit and credit methods now work with the private field.
func (a *Account) debit(amount float64) error {
    if a.balance < amount {
        return fmt.Errorf("saldo insuficiente")
    }
    a.balance -= amount
    return nil
}

func (a *Account) credit(amount float64) {
    a.balance += amount
}

With this implementation, the balance field can only be modified through the package's own methods, ensuring that all balance changes go through the double entry system.

Of course, there are other important considerations when implementing a double entry system, such as ensuring transaction atomicity using a transactional database and implementing detailed logs of all operations for auditing purposes. These practices help maintain system integrity and traceability.

The Code in Production

As a practical example of a tool that implements the double entry system, we have Midaz, an open source ledger maintained by Lerian that uses this technique to ensure the integrity of financial transactions.

Unlike virtually all Brazilian financial systems which are closed, Midaz allows us to openly examine and discuss the use of double entry and study how this practice works in a production environment.

How an Operation is Created

Let's examine how Midaz creates an individual operation within a transaction. Within the creation of a transaction, the CreateOperation method is called, which receives the transaction details and the accounts involved. Here's the commented code for creating an operation:

func (uc *UseCase) CreateOperation(ctx context.Context, 
        accounts []*account.Account, 
        transactionID string, 
        dsl *goldModel.Transaction, 
        validate goldModel.Responses, 
        result chan []*operation.Operation, 
        err chan error) {

    // Declare a list to store the created operations.
    var operations []*operation.Operation

    // Create a fromTo list containing the source and destination accounts involved in the transaction.
    var fromTo []goldModel.FromTo
    fromTo = append(fromTo, dsl.Send.Source.From...)      // Add origin accounts.
    fromTo = append(fromTo, dsl.Send.Distribute.To...)    // Add destination accounts.

    // Iterate over all the accounts involved in the transaction.
    for _, acc := range accounts {
        // Check if the account is in the fromTo list.
        for i := range fromTo {

            // Check if the current account is involved in the transaction, either by ID or alias.
            if fromTo[i].Account == acc.Id || fromTo[i].Account == acc.Alias {

                // Set the account's current balance.
                balance := operation.Balance{
                    Available: &acc.Balance.Available,
                    OnHold:    &acc.Balance.OnHold,
                    Scale:     &acc.Balance.Scale,
                }

                // Validate the operation and calculate the transaction values.
                amt, bat, er := goldModel.ValidateFromToOperation(fromTo[i], validate, acc)
                if er != nil {
                    logger.Errorf("Error creating operation: %v", er)
                }

                // Convert the transaction values to float64 and set the decimal scale.
                v := float64(amt.Value)
                s := float64(amt.Scale)

                amount := operation.Amount{
                    Amount: &v,
                    Scale:  &s,
                }

                // Set the account balance after the operation.
                ba := float64(bat.Available)
                boh := float64(bat.OnHold)
                bs := float64(bat.Scale)

                balanceAfter := operation.Balance{
                    Available: &ba,
                    OnHold:    &boh,
                    Scale:     &bs,
                }

                // Select whether the operation will be a debit or a credit.
                var typeOperation string
                if fromTo[i].IsFrom {
                    typeOperation = constant.DEBIT
                } else {
                    typeOperation = constant.CREDIT
                }

                // Create a new operation with the processed data.
                save := &operation.Operation{
                    ID:              pkg.GenerateUUIDv7().String(),
                    TransactionID:   transactionID,
                    Type:            typeOperation,
                    AssetCode:       dsl.Send.Asset,
                    Amount:          amount,
                    Balance:         balance,
                    BalanceAfter:    balanceAfter,
                    AccountID:       acc.Id,
                    AccountAlias:    acc.Alias,
                    ...
                }

                // Save the operation to the database.
                op, er := uc.OperationRepo.Create(ctx, save)
                if er != nil {
                    logger.Errorf("Error creating operation: %v", er)
                }

                // Add the created operation to the list of operations.
                operations = append(operations, op)

                break // Exit the loop to avoid multiple inclusions of the same account.
            }
        }
    }

    // Sends the list of created operations through the result channel
    result <- operations
}

To make it easier to read, I removed loggers and tracers and some other details, but you can analyze the complete code on GitHub for creating a transaction and the operation. Leave a comment if you would like an article breaking down and explaining how the code for a complete financial transaction is done.

Race Conditions e Locks: Garantindo a Integridade das Transações Financeiras

Jefferson Rodrigues — Tue, 25 Feb 2025 16:29:15 +0000

Assim como falei sobre Double-Entry recentemente, hoje quero falar sobre um outro pilar fundamental na construção de um sistema financeiro confiável, o Race Condition.

Race conditions acontecem quando dois ou mais processos tentam acessar e modificar o mesmo recurso simultaneamente, podendo levar a resultados inconsistentes ou comportamentos inesperados no sistema.

Por exemplo, quando dois usuários tentam atualizar o mesmo registro em um banco de dados ao mesmo tempo, o resultado final pode não refletir corretamente as alterações de ambos os processos. Essa situação é particularmente crítica em sistemas que lidam com dados sensíveis ou transações financeiras na modalidade débito.

Imagine uma conta com saldo de R$ 100, onde duas operações de débito chegam exatamente no mesmo segundo — acontece e muito! — uma de R$ 50 e outra de R$ 80. No total deveria debitar da conta R$ 130, porém como só há R$ 100, ficaria R$ 30 negativos.

Essa situação pode causar sérios problemas de consistência de dados e prejuízos financeiros gigantes, já que o sistema pode processar ambas as transações sem a devida validação do saldo disponível.

Possíveis soluções

Existem várias abordagens para prevenir race conditions em sistemas financeiros, como por exemplo implementar o conceito de serialização de transações, onde as operações são processadas em uma ordem específica e controlada.

Além disso, a utilização de controle de concorrência otimista (OCCs - Optimistic Concurrency Control) pode ser uma alternativa viável, especialmente em sistemas com baixa probabilidade de conflitos. Em suma, ela permite que múltiplas transações ocorram simultaneamente, verificando apenas no momento da confirmação (commit) se houve algum conflito. Se um conflito for detectado, a transação é revertida e pode ser tentada novamente. Esta abordagem é especialmente eficiente em ambientes onde os conflitos são raros, pois evita o overhead de bloqueios constantes.

Outra solução eficaz e amplamente difundida é a utilização de locks, ou semáforos, que garantem acesso exclusivo aos recursos compartilhados durante uma transação.

Funcionamento dos Locks

Locks são mecanismos de sincronização que impedem que múltiplos processos acessem simultaneamente um recurso compartilhado. Em um sistema financeiro, quando uma transação precisa modificar o saldo de uma conta, ela primeiro adquire um lock exclusivo sobre aquele registro, garantindo que nenhuma outra transação possa alterá-lo ao mesmo tempo. Somente após a conclusão da primeira transação e a liberação do lock, outras operações podem acessar e modificar o mesmo recurso.

Implementando locks com Redis

O Redis é uma excelente opção para implementar locks distribuídos devido à sua natureza atômica e alta performance. Um exemplo simples de implementação seria utilizar o comando SETNX (SET if Not eXists) para criar um lock:

func acquireLock(lockKey string, timeout time.Duration) (bool, error) {
    ctx := context.Background()
    acquired, err := rdb.SetNX(ctx, lockKey, time.Now().Unix(), timeout).Result()
    if err != nil {
        return false, err
    }
    return acquired, nil
}

Este código cria um lock atômico que expira automaticamente após um determinado período, evitando deadlocks caso o processo que adquiriu o lock falhe antes de liberá-lo.

É crucial garantir sua liberação após a conclusão da operação, mesmo em caso de erros. Isso pode ser feito utilizando um bloco try-finally:

func performOperation() error {
    lockKey := "account:123:lock"
    acquired, err := acquireLock(lockKey, 10)
    if err != nil {
        return err
    }

    if acquired {
        defer redis.Del(ctx, lockKey).Err()
        // Execute operation
    }

    return nil
}

Esta abordagem garante que o lock será sempre liberado, permitindo que outras operações prossigam normalmente.

Voltando ao nosso exemplo anterior da conta com 100 reais e duas transações simultâneas, a implementação de locks garantiria que apenas uma transação fosse processada por vez. Assim, se a primeira transação de 50 reais adquirisse o lock, ela seria processada completamente antes que a segunda transação de 80 reais pudesse acessar o saldo, evitando o problema de consistência.

Neste cenário, a primeira transação seria bem-sucedida (reduzindo o saldo para 50 reais) e a segunda seria rejeitada por saldo insuficiente, mantendo a integridade dos dados.

Diferença entre Pessimistic e Optimistic Lock?

Enquanto o lock pessimista, ou Pessimistic Lock, realiza o lock do registro tanto para ESCRITA quanto para LEITURA, impedindo qualquer acesso ao recurso até que o processamento seja concluído. O Optimistic Lock, ou lock otimista, realiza o lock do registro apenas para ESCRITA, mantendo a leitura liberada. Utiliza versionamento como mecanismo de validação no momento da escrita.

Qual o melhor modelo de lock para transações financeiras

Para transações financeiras, o Pessimistic Lock é geralmente considerado mais adequado devido às suas características de segurança mais rigorosas. Isso se deve a alguns fatores importantes:

Consistência garantida: Ao bloquear tanto leitura quanto escrita, garante-se que nenhuma operação seja realizada com dados potencialmente desatualizados
Prevenção de conflitos: Elimina a possibilidade de conflitos antes que ocorram, em vez de detectá-los posteriormente
Segurança em transações críticas: Em operações financeiras, onde a precisão é crucial, é preferível ter um controle mais rigoroso mesmo que isso implique em uma pequena redução de performance

No entanto, é importante notar que o Pessimistic Lock pode impactar a performance do sistema devido ao maior tempo de bloqueio dos recursos. Por isso, sua implementação deve ser cuidadosamente planejada, considerando aspectos como timeout do lock e estratégias de deadlock prevention.

Qual débito acontece primeiro?

A ordem de processamento das transações em um sistema distribuído geralmente é determinada por vários fatores, incluindo o timestamp da transação, a latência da rede e a implementação específica do mecanismo de locks.

Na prática, a primeira transação que conseguir adquirir o lock será processada primeiro, seguindo um princípio de "primeiro a chegar, primeiro a ser servido" (FCFS - First Come, First Served). No entanto, é importante notar que em sistemas distribuídos, nem sempre é possível garantir uma ordem totalmente determinística devido a fatores como diferenças de clock entre servidores.

O código em produção

Como exemplo prático temos o Midaz, um ledger open source mantido pela Lerian que utiliza essa pessimist lock para garantir a integridade das transações financeiras, isso nos permite visualizar o código produtivo de como é feito esse lock que segue o mesmo princípio acima.

Realizando o lock do saldo

Vimos anteriormente como operações financeiras são criadas, o processo do lock acontece uma etapa antes até mesmo da criação da transação, na validação das contas que chama o método LockBalanceVersion.

func (uc *UseCase) LockBalanceVersion(ctx context.Context, 
    organizationID, 
    ledgerID uuid.UUID, 
    keys []string, 
    accounts []*account.Account) (bool, error) {
    // Cria um mapa de contas (usando ID ou Alias como chave) para facilitar a busca durante o processamento.
    accountsMap := make(map[string]*account.Account)
    for _, acc := range accounts {
        accountsMap[acc.Id] = acc  // Adiciona a conta com ID como chave
        accountsMap[acc.Alias] = acc  // Adiciona a conta com Alias como chave
    }

    // Itera sobre todas as chaves para tentar bloquear a versão do saldo.
    for _, key := range keys {
        // Verifica se a chave corresponde a uma conta existente no mapa.
        if acc, exists := accountsMap[key]; exists {
            // Cria uma chave interna para bloquear a versão do saldo da conta no Redis.
            internalKey := pkg.LockVersionInternalKey(organizationID, ledgerID, key, strconv.FormatInt(acc.Version, 10))

            // Tenta configurar o bloqueio no Redis (SetNX) e define um tempo de expiração.
            isSuccess, err := uc.RedisRepo.SetNX(ctx, internalKey, "0", constant.TimeSetLockBalance)
            if err != nil {
                // Caso ocorra um erro, registra no telemetry e retorna o erro.
                return false, err
            }

            // Incrementa o contador de tentativas de bloqueio no Redis.
            total := uc.RedisRepo.Incr(ctx, internalKey)

            // Se o número de tentativas exceder o limite, libera o bloqueio e retorna erro.
            if total > constant.RedisTimesRetry {
                err = uc.RedisRepo.Del(ctx, internalKey)  // Libera o bloqueio
                if err != nil {
                    // Se ocorrer erro ao liberar o bloqueio, loga o erro.
                }

                return false, pkg.ValidateBusinessError(constant.ErrLockVersionAccountBalance, "LockBalanceVersion")
            }

            // Se o bloqueio não foi adquirido, espera um tempo e tenta novamente.
            if !isSuccess {
                time.Sleep(constant.LockRetry * time.Millisecond)
                return true, nil
            }
        }
    }

    // Retorna false, indicando que não conseguiu bloquear, sem erros.
    return false, nil
}

Removendo os locks

Após o processamento das transações, é chamado o método AllKeysUnlocked para liberar todas as keys e permitir que outras operações possam ser executadas. O Midaz implementa um sistema de liberação de locks utilizando goroutines para processar múltiplas chaves simultaneamente, melhorando a performance do sistema. Veja como isso é feito no código:

func (uc *UseCase) AllKeysUnlocked(ctx context.Context, organizationID, ledgerID uuid.UUID, keys []string, hash string) {
    // Cria um WaitGroup para sincronizar as goroutines.
    var wg sync.WaitGroup

    // Canal para receber os resultados das goroutines de verificação de bloqueios.
    resultChan := make(chan bool, len(keys))

    // Itera sobre todas as chaves fornecidas para verificar o status de bloqueio de cada uma.
    for _, key := range keys {
        // Cria uma chave interna para verificar o bloqueio no Redis.
        internalKey := pkg.LockInternalKey(organizationID, ledgerID, key)

        // Incrementa o contador do WaitGroup para acompanhar a goroutine.
        wg.Add(1)

        // Inicia uma goroutine para verificar e liberar o bloqueio da chave.
        go uc.checkAndReleaseLock(ctx, &wg, internalKey, hash, resultChan)
    }

    // Espera todas as goroutines finalizarem.
    wg.Wait()

    // Fecha o canal de resultados.
    close(resultChan)
}

Para facilitar a leitura, removi loggers e tracers e alguns outros detalhes, mas você pode analisar na íntegra o código no GitHub da criação de uma transação e dos comandos de lock do race condition. Coloque nos comentários caso queria um artigo destrinchando e explicando como é feito o código de uma transação financeira por completo.

Conclusão

A implementação correta de mecanismos de controle de concorrência é crucial para garantir a integridade e confiabilidade das transações financeiras, esta é uma das vantagens de se utilizar um ledger para lidar com transações, pois ele já possui mecanismos nativos de controle de concorrência e locks integrados.

Isso significa que ao utilizar um ledger, você não precisa se preocupar em implementar esses controles manualmente, pois a própria arquitetura do sistema garante a integridade das transações. Uma das ferramentas que implementa estes conceitos é o Midaz, um ledger open source mantido pela Lerian, que você pode explorar o código e utilizar em seus projetos ou na sua empresa.

Você já enfrentou desafios de race conditions em seus projetos? Compartilhe suas experiências nos comentários e não se esqueça de compartilhar este artigo com outros desenvolvedores que possam se beneficiar deste conhecimento!

Double Entry: o que é, quando usar e como fazer

Jefferson Rodrigues — Tue, 18 Feb 2025 17:19:12 +0000

Quem está começando a trabalhar no setor financeiro pode se deparar com esse termo "double-entry", que é um conceito fundamental para o gerenciamento de transações e registros financeiros. Neste post, quero explicar em detalhes como esse conceito funciona, quando ele deve ser utilizado e sua importância para manter a integridade das transações financeiras.

A melhor maneira de explicar o que é um double-entry é com um exemplo. Então, considere que você faça uma transferência Pix de R$ 1.000 para pagar uma conta; esse processo de transferência, na verdade, realiza duas operações:

A primeira operação é a de débito de R$ 1.000 na sua conta;
A segunda operação é a de crédito de R$ 1.000 na conta destino.

É imprescindível que, para a transação seja efetuada com sucesso, ambas as operações sejam registradas corretamente. Se uma das operações falhar, todo o processo precisa ser revertido para manter a integridade da conta. Esse conceito é conhecido como double entry (entrada dupla) e é fundamental para garantir a integridade das transações financeiras.

Importância no Setor Financeiro

O sistema de double entry é crucial no setor financeiro por diversos motivos:

Precisão contábil: Garante que todas as transações financeiras sejam registradas com exatidão, reduzindo erros e discrepâncias nas contas.
Auditoria facilitada: Permite rastrear facilmente o histórico de transações e identificar possíveis irregularidades ou fraudes.
Conformidade regulatória: Atende aos requisitos legais e regulatórios do setor financeiro, que exigem registros precisos e transparentes.
Reconciliação bancária: Simplifica o processo de reconciliação, permitindo a comparação eficiente entre registros internos e extratos bancários.

Aplicações além dos sistemas financeiros

O sistema de double entry, embora tradicionalmente associado a sistemas financeiros, pode ser aplicado em outros contextos também, como em gestão de inventário e logística em que é preciso registrar a entrada e saída de produtos.

Em todos esses casos, o princípio fundamental do double entry — onde cada transação afeta dois registros diferentes — ajuda a manter a integridade e rastreabilidade dos dados.

Como desenvolver

Vamos criar um exemplo simples de implementação do sistema double entry em Go. Neste exemplo, vamos simular uma transferência bancária:

package main

import (
    "fmt"
    "time"
)

type Account struct {
    ID      string
    Balance float64
}

type Transaction struct {
    ID        string
    FromID    string
    ToID      string
    Amount    float64
    Timestamp time.Time
}

func (a *Account) Debit(amount float64) error {
    if a.Balance < amount {
        return fmt.Errorf("saldo insuficiente")
    }
    a.Balance -= amount
    return nil
}

func (a *Account) Credit(amount float64) {
    a.Balance += amount
}

func Transfer(from, to *Account, amount float64) error {
    // Primeira entrada: débito da conta origem
    if err := from.Debit(amount); err != nil {
        return err
    }

    // Segunda entrada: crédito na conta destino
    to.Credit(amount)

    return nil
}

func main() {
    // Criando contas de exemplo
    accountA := &Account{
        ID:      "conta_a",
        Balance: 1000.0,
    }

    accountB := &Account{
        ID:      "conta_b",
        Balance: 500.0,
    }

    fmt.Printf("Antes da transferência:\nConta A: R$%.2f\nConta B: R$%.2f\n\n", 
        accountA.Balance, accountB.Balance)

    // Realizando uma transferência
    err := Transfer(accountA, accountB, 300.0)
    if err != nil {
        fmt.Printf("Erro na transferência: %v\n", err)
        return
    }

    fmt.Printf("Após a transferência:\nConta A: R$%.2f\nConta B: R$%.2f\n", 
        accountA.Balance, accountB.Balance)
}

Neste exemplo, implementamos:

Uma estrutura Account para representar contas com ID e saldo
Uma estrutura Transaction para registrar os detalhes das transações
Métodos Debit e Credit para realizar as operações nas contas
Uma função Transfer que implementa o conceito de double entry, garantindo que ambas as operações sejam realizadas

Quando executado, este código demonstra uma transferência de R$ 300,00 da conta A para a conta B, mostrando os saldos antes e depois da operação. Se houver qualquer erro durante o processo (como saldo insuficiente), a transação não é completada.

As ditas operações

No exemplo que vimos anteriormente, criamos duas operações fundamentais que compõem uma transação:

Uma operação de débito (Debit) que remove o valor da conta de origem
Uma operação de crédito (Credit) que adiciona o valor na conta de destino

Essas operações são as unidades básicas de uma transação financeira e devem sempre ocorrer em pares para manter o princípio do double-entry. Cada operação é atômica, ou seja, ou ela acontece por completo ou não acontece, não existindo estados intermediários.

No código, implementamos essas operações como métodos separados da estrutura Account, mas elas são sempre chamadas juntas através da função Transfer para garantir que o princípio do double-entry seja respeitado.

Encapsulamento e Segurança

Para garantir que o saldo só possa ser alterado através da função de transação, podemos utilizar encapsulamento e tornar o campo Balance privado na estrutura Account. Veja como podemos modificar o código anterior:

type Account struct {
    ID      string
    balance float64  // Note o 'b' minúsculo tornando o campo privado
}

// Método getter para acessar o saldo
func (a *Account) GetBalance() float64 {
    return a.balance
}

// Métodos de débito e crédito agora trabalham com o campo privado
func (a *Account) debit(amount float64) error {
    if a.balance < amount {
        return fmt.Errorf("saldo insuficiente")
    }
    a.balance -= amount
    return nil
}

func (a *Account) credit(amount float64) {
    a.balance += amount
}

Com essa implementação, o campo balance só pode ser modificado através dos métodos do próprio pacote, garantindo que todas as alterações de saldo passem pelo sistema de double entry.

Claro, há outras considerações importantes ao implementar um sistema de double entry, como garantir a atomicidade das transações usando um banco de dados transacional e implementar logs detalhados de todas as operações para fins de auditoria. Essas práticas ajudam a manter a integridade e rastreabilidade do sistema.

O código em produção

Como exemplo prático de uma ferramenta que implementa o sistema de double entry, temos o Midaz, um ledger open source mantido pela Lerian que utiliza essa técnica para garantir a integridade das transações financeiras.

Ao contrário de basicamente todos os sistemas financeiros brasileiros que são fechados, o Midaz nos permite examinar e discutir abertamente o uso de double entry e estudar como essa prática funciona em um ambiente de produção.

Como é criada uma operação

Vamos examinar como o Midaz cria uma operação individual dentro de uma transação. Dentro da criação de uma transação, é chamado o método CreateOperation que recebe os detalhes da transação e as contas envolvidas. Segue o código da criação de uma operação, comentado:

func (uc *UseCase) CreateOperation(ctx context.Context, 
        accounts []*account.Account, 
        transactionID string, 
        dsl *goldModel.Transaction, 
        validate goldModel.Responses, 
        result chan []*operation.Operation, 
        err chan error) {

    // Declara uma lista para armazenar as operações criadas
    var operations []*operation.Operation

    // Cria uma lista `fromTo` contendo as contas de origem e destino envolvidas na transação
    var fromTo []goldModel.FromTo
    fromTo = append(fromTo, dsl.Send.Source.From...)      // Adiciona contas de origem
    fromTo = append(fromTo, dsl.Send.Distribute.To...)    // Adiciona contas de destino

    // Percorre todas as contas envolvidas na transação
    for _, acc := range accounts {
        // Verifica se a conta está na lista `fromTo`
        for i := range fromTo {

            // Verifica se a conta atual está envolvida na transação, seja pelo ID ou pelo alias.
            if fromTo[i].Account == acc.Id || fromTo[i].Account == acc.Alias {

                // Define o saldo atual da conta
                balance := operation.Balance{
                    Available: &acc.Balance.Available,
                    OnHold:    &acc.Balance.OnHold,
                    Scale:     &acc.Balance.Scale,
                }

                // Valida a operação e calcula os valores da transação
                amt, bat, er := goldModel.ValidateFromToOperation(fromTo[i], validate, acc)
                if er != nil {
                    logger.Errorf("Error creating operation: %v", er)
                }

                // Converte os valores da transação para float64 e a escala de casas decimais
                v := float64(amt.Value)
                s := float64(amt.Scale)

                amount := operation.Amount{
                    Amount: &v,
                    Scale:  &s,
                }

                // Define o saldo da conta após a operação
                ba := float64(bat.Available)
                boh := float64(bat.OnHold)
                bs := float64(bat.Scale)

                balanceAfter := operation.Balance{
                    Available: &ba,
                    OnHold:    &boh,
                    Scale:     &bs,
                }

                // Determina se a operação será um débito ou crédito
                var typeOperation string
                if fromTo[i].IsFrom {
                    typeOperation = constant.DEBIT
                } else {
                    typeOperation = constant.CREDIT
                }

                // Cria uma nova operação com os dados processados
                save := &operation.Operation{
                    ID:              pkg.GenerateUUIDv7().String(),
                    TransactionID:   transactionID,
                    Type:            typeOperation,
                    AssetCode:       dsl.Send.Asset,
                    Amount:          amount,
                    Balance:         balance,
                    BalanceAfter:    balanceAfter,
                    AccountID:       acc.Id,
                    AccountAlias:    acc.Alias,
                    ...
                }

                // Salva a operação no banco de dados
                op, er := uc.OperationRepo.Create(ctx, save)
                if er != nil {
                    logger.Errorf("Error creating operation: %v", er)
                }

                // Adiciona a operação criada à lista de operações
                operations = append(operations, op)

                break // Sai do loop para evitar múltiplas inclusões da mesma conta
            }
        }
    }

    // Envia a lista de operações criadas pelo canal `result`
    result <- operations
}

Para facilitar a leitura, removi loggers e tracers e alguns outros detalhes, mas você pode analisar na íntegra o código no GitHub da criação de uma transação e da operação. Coloque nos comentários caso queira um artigo destrinchando e explicando como é feito o código de uma transação financeira por completo.