The Transactions Domain in Midaz is managed by a Domain-Specific Language (DSL) called gold. It allows Midaz users to execute complex financial operations across multiple accounts, like PIX payments and interbank transfers.

Key Features

Allows asset transfers with clear definitions for sources, destinations, and amounts.
Simplifies transaction modeling with transaction templates and accounting routes.
Supports advanced transaction conditions for distributing amounts based on percentages or remaining balances.

Basic Structure of a `.gold` file

A .gold file defines a transaction in a readable and structured format. Below is an example of a .gold file:

(transaction v1
  (chart-of-accounts-group-name ACCOUNT_SLIP_10000)
  (description "description for the transaction not for the operation")
  (metadata
      (key value)
      (anotherKey anotherValue)
  )
  (send USD 10000|2 
    (source
      (from @originAccount :amount USD 10000|2
        (chart-of-accounts PAYMENT_001)
        (description "shown on the statement")
        (metadata
          (key value)
          (anotherKey anotherValue) 
        )
      )
    )
  )
  (distribute
    (to @destinationAccount :amount USD 10000|2
      (chart-of-accounts PAYMENT_101)
      (description "operation description")
      (metadata
	      (key value)
      )
    )
  )
)

Key Components of the DSL

transaction: Opens a new transaction context, defining the basic structure and processing elements.
send: Specifies the asset and amount to be transferred. The send block includes the source accounts and their respective values.
distribute: Specifies the destination accounts and the respective amounts to be credited.

Each section allows for further customization through elements like description, chart-of-accounts, and metadata, supporting detailed control over each aspect of a transaction.

Notations and Amount Handling

The DSL allows for various notations to specify amounts:

:amount: Direct value transfer defined by asset, value, and scale.
:share: A percentage of the amount defined in the send block, enabling proportional transfers.
:remaining: Designates the remaining balance for distribution to an account after other allocations.

Transaction Flow Examples

The following are common transaction flows that illustrate how to structure transactions and manage balances effectively.

Pix Out Transaction Flow

Below is a template example for a Pix Out transaction, with defined source and destination account movements:

(transaction v1
   (chart-of-accounts-group-name PIX_OUT)
   (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|2
         (description "PIX shipping")
         (chart-of-accounts pix_out_debit_82891231)
       )
       (from $sourceAccount :amount BRL $fee|2
         (description "PIX shipping rate")
         (chart-of-accounts pix_out_fee_debit)
       )
     )
   )
   (distribute
     (to @fees/PIX_OUT :amount BRL $fee|2
       (chart-of-accounts pix_out_fee_credit)
     )
     (distribute :remaining
       (to @external/BRL :remaining
         (chart-of-accounts pix_out_external)
         (description "internalTransactionId 99839218")
       )
     )
   )
)

This transaction template defines a PIX_OUT transaction using Domain-Specific Language (DSL) to structure a payment flow in Brazilian Reais (BRL). Each part of the code configures aspects of the transaction's metadata, sources, and destinations:

(transaction v1): Defines a new transaction using version 1 of the transaction schema.
(chart-of-accounts-group-name PIX_OUT): Sets the chart of accounts group name to PIX_OUT, which categorizes this transaction under a specific group, typically for easy identification and grouping within financial records.
(metadata (anyKey anyValue) (anotherKey anotherValue)): Adds metadata with arbitrary key-value pairs, providing additional contextual information for the transaction, which may be used for filtering, reporting, or tracking purposes.
(code PIX_OUT): Assigns the transaction a unique code, PIX_OUT, to identify and reference it in the system.
(description "description for the transaction not for the operation"): Provides a high-level description of the transaction. This description is for the transaction overall, not for individual operations within the transaction.
(send BRL $amount+$fee|2): Specifies that this transaction involves sending an amount in BRL (Brazilian Reais), which includes $amount and $fee, both rounded to two decimal places.
(source
(from $sourceAccount BRL $amount|2 ...)): Defines the source account, detailing where the transaction amount will be debited from:
- (description "PIX shipping"): A description for this part of the transaction, indicating it’s a "PIX shipping" operation.
- (chart-of-accounts pix_out_debit_82891231): Specifies the chart of accounts entry for debiting the main amount from the source account.
(from $sourceAccount
BRL $fee|2 ...): Specifies the fee amount that will also be debited from the source account:
- (description "PIX shipping rate"): A description for this fee portion, labeled as "PIX shipping rate."
- (chart-of-accounts pix_out_fee_debit): Identifies the chart of accounts entry for debiting the fee amount.
(distribute ...): This section defines how funds are distributed to different accounts after being debited from the source:
- (to @fees/PIX_OUT
  BRL $fee|2 ...): Sends the fee amount to a specific fee account for PIX_OUT:
(chart-of-accounts pix_out_fee_credit): Identifies the chart of accounts entry to credit this fee amount.
(distribute
...): Indicates that the remaining balance should be distributed to another account:
- (to @external/BRL
  ...): Credits the remaining balance to an external account in BRL.
- (chart-of-accounts pix_out_external): Identifies the chart of accounts entry for this remaining amount.
- (description "internalTransactionId 99839218"): Adds an internal transaction ID to this portion, which could be useful for tracking or auditing purposes.