DSL de Transações

Este recurso está descontinuado e será removido na próxima versão. Atualize seus fluxos de trabalho o mais rápido possível para evitar erros ou indisponibilidade.Para a abordagem atual de criação de transações, veja Transações.

Esta página é destinada a desenvolvedores migrando da DSL legada. Se você está procurando uma visão geral de nível de negócio sobre como as transações funcionam no Midaz, veja Sobre o Midaz.

O Midaz usa uma Domain-Specific Language (DSL) chamada gold para estruturar transações financeiras de forma legível e intuitiva. Projetada para equipes de negócio, a gold simplifica a modelagem de transações permitindo que operações sejam processadas através de arquivos .gold. Esses arquivos tornam as movimentações financeiras mais acessíveis e alinhadas com a lógica contábil.

Por que usar Gold?

Fornece um formato claro e estruturado para transferências de ativos.
Define origens, destinos e valores de forma explícita.
Suporta lógica avançada de transação, como distribuição de saldos baseada em percentuais ou valores remanescentes.
Melhora a automação e a consistência nos fluxos de trabalho financeiros.

Estrutura de um arquivo `.gold`

Um arquivo .gold representa uma transação usando uma estrutura hierárquica. Aqui está um exemplo:

(transaction v1
	(transaction route ID)
  (description "description for the transaction not for the operation")
  (metadata
    (key value)
    (anotherKey anotherValue)
  )
  (send USD 10000
    (source
     (from @originAccount :amount USD 10000
				(transaction route ID)
        (description "shown on the statement")
        (metadata
          (key value)
          (anotherKey anotherValue)
        )
      )
    )
    (distribute
     (to @destinationAccount :amount USD 10000
				(transaction route ID)
        (description "operation description")
        (metadata
          (key value)
        )
      )
    )
  )
)

Hierarquia da DSL

Abaixo está a estrutura hierárquica de um arquivo .gold, ilustrando os principais relacionamentos:

└─ transaction
   ├─ route
   ├─ description
   ├─ code
   ├─ pending
   ├─ metadata
   │   └─ key value (n)
   ├─ send
   │   ├─ source
   │   │  └─ from
   │   │     ├─ description
   │   │     ├─ route
   │   │     └─ metadata
   │   │        └─ key value (n)
   │   └─ distribute
   │      └─ to
   │         ├─ description
   │         ├─ route
   │         └─ metadata
   └─           └─ key value (n)

Entendendo as palavras-chave da DSL

transaction

Abre um novo bloco de transação, onde todos os elementos relacionados são definidos.

send

Especifica o ativo e o valor a ser transferido, incluindo as contas de origem das quais os fundos serão debitados. Múltiplas contas from podem ser agrupadas usando source. Formato: send {asset_code} {value}

distribute

Define as contas de destino onde os fundos serão creditados. Múltiplas contas to podem ser incluídas dentro de distribute.

Notações de valor em transações

A DSL gold suporta diferentes formas de expressar valores dentro de uma transação:

:amount – Notação padrão especificando o ativo, valor e escala.
:share – Especifica uma porcentagem do valor total do send.
:remaining – Aloca o saldo remanescente após todas as outras distribuições.

Exemplo: Fluxo de transação Pix Out

Este exemplo demonstra uma transação Pix Out no formato .gold:

(transaction v1
	(transaction route ID)
  (metadata
    (anyKey anyValue)
    (anotherKey anotherValue)
  )
  (code PIX_OUT)
  (description "description for the transaction not for the operation")
  (send BRL $amount+$fee|2
    (source
     (from $sourceAccount :amount BRL $amount
				(transaction route ID)
        (description "PIX shipping")
      )
     (from $sourceAccount :amount BRL $fee
				(transaction route ID)
        (description "PIX shipping rate")
      )
    )
    (distribute
     (to @fees/PIX_OUT :amount BRL $fee
				(transaction route ID)
      )
      (distribute :remaining
        (to @external/BRL :remaining
          (description "internalTransactionId 99839218")
        )
      )
    )
  )
)

Detalhamento:

(transaction v1) – Define uma nova transação usando a versão 1.
(Transaction route ID) – Categoriza a transação.
(metadata …) – Armazena dados adicionais da transação.
(send BRL fee|2) – Especifica o valor total enviado.
(source …) – Detalha as contas de origem das quais o valor é debitado.
(distribute …) – Aloca os fundos para as contas apropriadas.
(distribute :remaining …) – Garante que qualquer saldo remanescente seja tratado.

Esse formato garante uma forma estruturada, transparente e eficiente de gerenciar transações no Midaz.

​Por que usar Gold?

​Estrutura de um arquivo .gold

​Hierarquia da DSL

​Entendendo as palavras-chave da DSL

​transaction

​send

​distribute

​Notações de valor em transações

​Exemplo: Fluxo de transação Pix Out

​Detalhamento:

Por que usar Gold?

Estrutura de um arquivo `.gold`

Hierarquia da DSL

Entendendo as palavras-chave da DSL

transaction

send

distribute

Notações de valor em transações

Exemplo: Fluxo de transação Pix Out

Detalhamento: