​
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+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.