Introduction

This guide helps you apply Formance Ledger patterns to real-world financial operations. The recipes that follow are illustrative — they show how Numscript can serve as an intent layer where business, finance, and engineering teams agree on financial logic in a clear, executable form. Your own regulatory, legal, and accounting obligations will shape the final implementation; treat these as a starting vocabulary, not a turnkey solution.

Intent-Based Finance#

At the heart of the Formance approach is the concept of Numscript as an intent layer. This means:

Separation of Concerns#

Benefits of This Approach#

• Business Clarity: Finance and operations teams can understand and validate the logic without deep technical knowledge.
• Rapid Iteration: Changes to business logic require updating Numscripts, not redeploying entire systems.
• Consistency: The same Numscript produces the same results, eliminating implementation drift across services.

Leveraging Bi-Temporality#

A critical feature of the Formance Ledger is bi-temporality, which means every transaction tracks two timestamps:

• Request Time: When the transaction was submitted to the ledger (machine clock time)
• Transaction Time: When the transaction is considered to have occurred (business effective time)

Why This Matters for Financial Operations#

In real-world financial operations, you frequently encounter timing mismatches:

• Settlement Delays: Payment authorizations happen in real-time, but bank settlements occur T+1 to T+3 days later. Your ledger should reflect the true effective dates of these movements, not just when you learned about them.
• Batch Processing: Bank statements arrive the next day. You need to record yesterday's transactions with their correct effective timestamps.
• Corrections and Adjustments: When errors are discovered or chargebacks occur, you may need to backdate transactions to reflect when they truly should have occurred.
• Multi-Timezone Operations: Events happening in different timezones need consistent temporal representation.

Implementing Bi-Temporality in Your Numscripts#

When executing Numscripts for real-world events, always provide the appropriate transaction timestamp, if reporting for point in time balances of accounts is important:

{
  "script": {
    "plain": "send [USD/2 100.00] (\n  source = @bank:account\n  destination = @user:123:main\n)",
    "vars": {
      "amount": "100.00",
      "userId": "123"
    }
  },
  "timestamp": "2024-10-20T14:30:00Z"  // Business effective time, not current time
}

Key Capabilities Demonstrated#

Throughout these recipes, you'll see how the Formance Ledger handles:

Multi-Asset Operations#

Accounts are multi-asset by default. The same account structure and Numscripts work across USD, EUR, GBP, stablecoins, or any other asset you define.

send [$ASSET] (
  source = @bank:nostro
  destination = @user:main
)

The $ASSET variable makes the script reusable across all currencies.

Rich Metadata#

Attach business context to accounts and transactions directly within your Numscripts for powerful querying, reporting, and integration.

vars {
  account $user
  monetary $amount
  string $auth_id
  string $card_scheme
}

send $amount (
  source = {
    @user:main
    @user:credit_line
  }
  destination = @hold:authorization
)

set_tx_meta("payment_method", "card")
set_tx_meta("card_scheme", $card_scheme)
set_tx_meta("authorization_id", $auth_id)

Constraint Enforcement#

The ledger automatically enforces business rules:

• Prevent overdrafts on customer accounts
• Ensure sufficient reserves for liabilities
• Validate transaction amounts and parties