Midaz uses a Domain-Specific Language (DSL) called gold to structure financial transactions in a readable and intuitive way. Designed for business teams, gold simplifies transaction modeling by allowing operations to be processed through .gold files. These files make financial movements more accessible and aligned with accounting logic.

Why Use Gold?

Provides a clear, structured format for asset transfers.
Defines sources, destinations, and amounts explicitly.
Supports advanced transaction logic, such as distributing balances based on percentages or remaining amounts.
Enhances automation and consistency in financial workflows.

Structure of a `.gold` File

A .gold file represents a transaction using a hierarchical structure. Here’s an example:

(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)
        )
      )
    )
  )  
)

DSL Hierarchy

Below is the hierarchical structure of a .gold file, illustrating key relationships:

└─ transaction
   ├─ chart-of-accounts-group-name
   ├─ description
   ├─ code
   ├─ pending
   ├─ metadata
   │   └─ key value (n)
   ├─ send
   │   ├─ source
   │   │  └─ from
   │   │     ├─ description
   │   │     ├─ chart-of-accounts
   │   │     └─ metadata
   │   │        └─ key value (n)
   │   └─ distribute
   │      └─ to
   │         ├─ description
   │         ├─ chart-of-accounts
   │         └─ metadata
   └─           └─ key value (n)

Understanding DSL Keywords

transaction

Opens a new transaction block, where all related elements are defined.

send

Specifies the asset and amount to be transferred, including the source accounts from which the funds will be debited. Multiple from accounts can be grouped using source.

Format: send {asset_code} {value}|{scale}

distribute

Defines the destination accounts where the funds will be credited. Multiple to accounts can be included within distribute.

Value Notations in Transactions

The gold DSL supports different ways to express values within a transaction:

:amount – Standard notation specifying the asset, amount, and scale.
:share – Specifies a percentage of the total send amount.
:remaining – Allocates the remaining balance after all other distributions.

Example: Pix Out Transaction Flow

This example demonstrates a PIX Out transaction in .gold format:

(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")
        )
      )
    )
  )
)

Breakdown:

(transaction v1) – Defines a new transaction using version 1.
(chart-of-accounts-group-name PIX_OUT) – Categorizes the transaction.
(metadata ...) – Stores additional transaction data.
(send BRL $amount+$fee|2) – Specifies the total amount sent.
(source ...) – Details the source accounts from which the amount is debited.
(distribute ...) – Allocates the funds to the appropriate accounts.
(distribute :remaining ...) – Ensures any remaining balance is handled.

This format ensures a structured, transparent, and efficient way to manage transactions in Midaz.