DEV Community: Jefferson Rodrigues

Saga pattern

Jefferson Rodrigues — Thu, 18 Sep 2025 10:58:43 +0000

Midaz Terraform Foundation: AWS, GCP e Azure

Jefferson Rodrigues — Thu, 05 Jun 2025 14:40:15 +0000

Provisionar uma infraestrutura sólida, segura e escalável é um passo essencial para rodar aplicações financeiras com alto grau de exigência — como o Midaz, o core bancário open source desenvolvido pela Lerian Studio.

Pensando nisso, a Lerian desenvolveu o Midaz Terraform Foundation, que oferece uma coleção de templates Terraform para criar a fundação necessária para operar o Midaz com eficiência, seguindo boas práticas e com suporte às três principais nuvens do mercado: AWS, Google Cloud Platform (GCP) e Microsoft Azure.

🎯 Foco na fundação: redes, DNS, bancos e Kubernetes

O repositório entrega módulos organizados por provedor e por componente, cobrindo todos os elementos essenciais para executar uma aplicação moderna em cloud:

examples/ ├── aws/ → VPC, Route53, RDS, Valkey, EKS ├── gcp/ → VPC, Cloud DNS, Cloud SQL, Valkey, GKE └── azure/ → Network, DNS, Database, Redis, AKS

A estrutura respeita a ordem lógica de provisionamento:

Rede
DNS
Banco de dados
Cache (Valkey/Redis)
Cluster Kubernetes

✅ Boas práticas incorporadas

Todos os templates seguem recomendações dos próprios provedores, utilizando módulos oficiais sempre que possível, aplicando versionamento e bloqueio de estado, e separando claramente código e configuração.

🔐 Segurança embutida

Autenticação via CLI com suporte a MFA, SSO e rotação de credenciais

Armazenamento remoto de estado com criptografia;
Compatibilidade com o princípio do menor privilégio;
Recomendações de uso com clusters privados e controle de acesso via RBAC;

🧩 Modularidade e reuso

Templates reutilizáveis por componente
Separação por ambiente via arquivos .tfvars
Estrutura compatível com automação em pipelines de CI/CD, como GitLab, GitHub Actions, Jenkins e outras ferramentas
Facilita a adoção de práticas GitOps e integração com gerenciadores de segredos

☁️ Suporte nativo a múltiplos provedores

O Midaz Terraform Foundation é compatível com AWS, GCP e Azure, permitindo que a infraestrutura seja criada no provedor que melhor se adapta à estratégia da organização — seja por razões técnicas, comerciais ou regulatórias.
Essa flexibilidade é ideal para:

Equipes que trabalham com múltiplos ambientes distribuídos em diferentes clouds;
Organizações que desejam evitar lock-in;
Produtos que precisam ser implantados em diferentes regiões ou clientes com requisitos distintos;

🛡️ Preparado para ambientes críticos

Projetado com foco em aplicações sensíveis como o Midaz, o Terraform Foundation é adequado para empresas que operam sob requisitos rigorosos de segurança, auditoria e conformidade.

Entre os destaques:

Prontidão para ambientes produtivos
Controle de versionamento e histórico de mudanças
Base segura para implantar o Midaz via Helm em clusters Kubernetes

🚀 Resumo

O Midaz Terraform Foundation oferece uma fundação de infraestrutura open source, robusta, segura e escalável — pronta para ser adotada por times que desejam acelerar a implantação do Midaz ou estruturar seus ambientes em nuvem com consistência, reutilização e governança.

Com suporte para AWS, GCP e Azure, os templates entregam flexibilidade, padronização e aderência às boas práticas de mercado, tudo em um único repositório acessível à comunidade.

🔗 Repositório: Midaz Terraform Foundation

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

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.

DEV Community: Jefferson Rodrigues

Saga pattern

Midaz Terraform Foundation: AWS, GCP e Azure

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

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

Garantindo confiabilidade do calculo valores monetários

Entendendo o que é precisão arbitrária

O problema da precisão

Por que esse erro acontece?

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

Armazenando centavos como inteiros

Ledgers Open Source: Transformando Conceitos em Vantagem Competitiva

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

Importance in the Financial Sector

Applications Beyond Financial Systems

How to Develop

The Said Operations

Encapsulation and Security

The Code in Production

How an Operation is Created

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

Possíveis soluções

Funcionamento dos Locks

Implementando locks com Redis

Diferença entre Pessimistic e Optimistic Lock?

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

Qual débito acontece primeiro?

O código em produção

Realizando o lock do saldo

Removendo os locks

Conclusão

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

Importância no Setor Financeiro

Aplicações além dos sistemas financeiros

Como desenvolver

As ditas operações

Encapsulamento e Segurança

O código em produção

Como é criada uma operação

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