Backend Engineer Guide: Immutable Double-Entry Payment Ledgers & Deadlock-Free Transfers in Go
In wallet, escrow, and payment settlement systems, updating an account balance with UPDATE accounts SET balance = balance - 100 without an append-only double-entry ledger makes reconciliation impossible when a webhook retries or a dispute occurs. Furthermore, if Transfer A locks `(Account 1, Account 2)` while concurrent Transfer B locks `(Account 2, Account 1)`, PostgreSQL deadlocks under load. As a backend engineer building PCI-DSS scope-isolated payment and ledger services in Go and PostgreSQL, I enforce balanced double-entry journals and deterministic lock ordering.
1. Deterministic Lexicographical Lock Ordering & Zero-Sum Journal Entries in Go
Every financial movement must record at least two ledger postings whose signed amounts sum to exactly zero (`debit + credit == 0`) in minor currency units (`int64`). Before acquiring `SELECT ... FOR UPDATE` row locks, we sort the participating account IDs lexicographically so two concurrent transfers between the same pair of accounts never deadlock:
// ledger/transfer.go
package ledger
import (
"context"
"database/sql"
"errors"
"sort"
)
var (
ErrInvalidAmount = errors.New("transfer amount must be positive minor units")
ErrInsufficientFunds = errors.New("insufficient available account balance")
)
func ExecuteAtomicTransfer(
ctx context.Context,
db *sql.DB,
idempotencyKey, sourceAcctID, destAcctID, currency string,
amountMinor int64,
) error {
if amountMinor <= 0 || sourceAcctID == destAcctID {
return ErrInvalidAmount
}
tx, err := db.BeginTx(ctx, &sql.TxOptions{Isolation: sql.LevelReadCommitted})
if err != nil {
return err
}
defer tx.Rollback()
// 1. Deterministic lock ordering prevents A->B vs B->A deadlocks
lockOrder := []string{sourceAcctID, destAcctID}
sort.Strings(lockOrder)
for _, acctID := range lockOrder {
var lockedID string
if err := tx.QueryRowContext(ctx,
`SELECT id FROM ledger_accounts WHERE id = $1 AND currency = $2 FOR UPDATE`,
acctID, currency,
).Scan(&lockedID); err != nil {
return err
}
}
// 2. Verify sufficient balance on source account
var sourceBalance int64
if err := tx.QueryRowContext(ctx,
`SELECT balance_minor FROM ledger_accounts WHERE id = $1`, sourceAcctID,
).Scan(&sourceBalance); err != nil {
return err
}
if sourceBalance < amountMinor {
return ErrInsufficientFunds
}
// 3. Insert immutable transaction header (idempotent via unique constraint)
var txID string
err = tx.QueryRowContext(ctx, `
INSERT INTO ledger_transactions (idempotency_key, currency)
VALUES ($1, $2)
ON CONFLICT (idempotency_key) DO NOTHING
RETURNING id
`, idempotencyKey, currency).Scan(&txID)
if errors.Is(err, sql.ErrNoRows) {
return nil // Already committed by an earlier request
} else if err != nil {
return err
}
// 4. Insert balanced double-entry postings (-amountMinor and +amountMinor)
if _, err := tx.ExecContext(ctx, `
INSERT INTO ledger_postings (transaction_id, account_id, amount_minor)
VALUES ($1, $2, $3), ($1, $4, $5)
`, txID, sourceAcctID, -amountMinor, destAcctID, amountMinor); err != nil {
return err
}
// 5. Update materialized account balances within the same ACID transaction
if _, err := tx.ExecContext(ctx,
`UPDATE ledger_accounts SET balance_minor = balance_minor - $1 WHERE id = $2`,
amountMinor, sourceAcctID,
); err != nil {
return err
}
if _, err := tx.ExecContext(ctx,
`UPDATE ledger_accounts SET balance_minor = balance_minor + $1 WHERE id = $2`,
amountMinor, destAcctID,
); err != nil {
return err
}
return tx.Commit()
}
2. Nightly Trial-Balance Invariant Verification
Alongside synchronous transaction constraints, a scheduled verification query asserts that SELECT SUM(amount_minor) FROM ledger_postings equals `0` and that every account's materialized `balance_minor` equals the exact sum of its historical postings.