> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# DSL de Transações

> Migre do DSL Gold (depreciado) e entenda como arquivos .gold legados estruturavam transações no Midaz antes da API atual.

<Warning>
  **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](/pt/reference/midaz/create-a-transaction-using-dsl).
</Warning>

<Tip>
  **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](/pt/midaz/about-midaz).
</Tip>

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:

<CodeGroup>
  ```go Go expandable theme={null}
  (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)
          )
        )
      )
    )
  )
  ```
</CodeGroup>

## Hierarquia da DSL

***

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

```bash theme={null}
└─ 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`:

<CodeGroup>
  ```go Go expandable theme={null}
  (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")
          )
        )
      )
    )
  )
  ```
</CodeGroup>

### 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.