Ledgers you can trust.
You let a merchant, say your gym, take its monthly payment from your account, and when it comes due the merchant asks your bank for the money. If your balance covers it, the bank pays. If not, the bank returns it unpaid and charges you a fee, and since the merchant can ask again, one unpaid bill can cost several fees. Years later a regulator calls those fees unfair, and every one of them has to be decided again and the difference refunded.
Now you're the engineer behind that bank's ledger, where the night's files and the day's live payments post against the same accounts, and that day has come. Could you run every payment since 2018 through the corrected rule with one command?
Keep reading.
Learn how one bank charged that fee every time the same payment came back, for three and a half years, until a regulator ordered the repeats refunded. Then see how a ledger in ObzenFlow replays its own record and decides every fee again under a corrected rule.
Run the demo yourself.
ObzenFlow's own bank example opens accounts and posts the day's files, then takes merchants' payments live over HTTP, charging each fee under the default rule, with nothing to install but Cargo. Post a retry while it runs, then replay the run through the corrected rule.
Four ways ObzenFlow helps you post batch and live as one ledger you can replay.
Challenges with ledgers
Where ObzenFlow fits
Batch and live data in one flow.
The night's file and the day's live traffic post in one stream, so every account has one order of entries and one balance.
Join every transaction to its matching account.
Every entry finds its account before it posts, even one opened that morning, so each decision is made against the right balance.
Rebuild account state for any historical flow.
Every fee records the balance it saw, the attempt it was and the rule that charged it, so nobody rebuilds that from a data warehouse later.
Replay any run during an audit to ask “what if”.
Replay the archive under the corrected rule and every fee is decided again in the same order, so every difference is counted before anyone is refunded.
Batch and live data in one flow.
Real systems ingest data from many sources, such as flat files, overnight batches and live streaming data. ObzenFlow gives you the vocabulary to work with all of these data sources in one flow.
The files come in as batch
Accounts open from a file, and the day’s debits arrive in two more, a ledger file and the merchants’ ACH file. Each is a finite source, read once to its end.
The day’s traffic comes in live
New accounts, entries and merchants’ debits keep arriving over HTTP while the run is up, and a merchant’s retry posts here the same way the morning’s file did. Every ACH debit, batch or live, is presented as a ledger entry before it goes any further.
Seamlessly merge into a single stream
accountsandtransactionsare merges undermerges::then_live. Each passes every batch row through to its natural end before any live row, so the batch posts first and the day’s traffic follows in one stream, and every account has one order of entries instead of a batch balance and a live balance that disagree.
stages: {
// Ingestion
batch_accounts = source!(AccountOpened => accounts_source);
batch_tx = source!(LedgerEntry => ledger_source);
batch_ach = source!(AchDebit => ach_debits_source);
live_accounts = async_infinite_source!(
AccountOpened => new_accounts_source
);
live_tx = async_infinite_source!(LedgerEntry => tx_source);
live_ach = async_infinite_source!(AchDebit => ach_source);
// Processing
batch_presentments =
transform!(AchDebit -> LedgerEntry => batch_presentments);
live_presentments =
transform!(AchDebit -> LedgerEntry => live_presentments);
accounts = merge!(AccountOpened => merges::then_live);
transactions = merge!(LedgerEntry => merges::then_live);
// …
},
topology: {
batch_accounts |> accounts;
live_accounts |> accounts;
batch_ach |> batch_presentments;
live_ach |> live_presentments;
batch_tx |> transactions;
batch_presentments |> transactions;
live_tx |> transactions;
live_presentments |> transactions;
// …
}Join every transaction to its matching account.
ObzenFlow gives you many ways to join reference data into richer domain types. A stream-table join can be inner, left or strict, over a table that is loaded once, kept live, or loaded first and kept live after, and a point-in-time join matches each transaction against the reference row in force at that moment, an interest rate down to the second.
The accounts are the table
postedkeys its table on the account id and loads every account from the file before it reads a single entry. Accounts that open during the day join the table live, so an entry can find an account that didn’t exist this morning.Every entry finds its account
Each entry looks up its account by id, and
postbuilds aPostedEntryfrom the pair that carries the owner and the account’s opening balance into the decision. The join is inner, so an entry with no account posts nothing, and then live, so the batch posts first and the day’s traffic follows, in the order the merges set.
fn post(account: AccountOpened, entry: LedgerEntry) -> PostedEntry {
PostedEntry {
account: entry.account,
owner: account.owner,
kind: entry.kind,
amount: entry.amount,
opening_balance: account.opening_balance,
note: entry.note,
originator: entry.originator,
}
}
let post_entry = joins::inner_then_live(
|account: &AccountOpened| account.account.clone(),
|entry: &LedgerEntry| entry.account.clone(),
post,
);
// …
posted = join!(
catalog accounts: AccountOpened,
LedgerEntry -> PostedEntry => post_entry
);
// …
(accounts, transactions) |> posted;Rebuild account state for any historical flow.
When the regulator asks why that gym payment cost two fees, you can answer that question with one command from the archive. Replay a flow at any point in time and you can determine the exact causal order of all fees that were charged to an account.
The balance is never overwritten
assessis a stateful stage, and ObzenFlow runs it as an event-sourced state machine. The balance it decides against, and which payments are still unpaid, are rebuilt from the archive rather than stored, so the balance at every moment is still there years later.Every decision is a fact
When a payment comes back unpaid, the stage reads the balance at that moment, applies the rule in force and writes what it decided, a fee charged or a retry returned, with the balance it saw and the rule that charged it. When the rule is corrected, the same archive replays under the new one, which is the next act.
// flow.rs
assess = stateful!(
PostedEntry -> { BalanceMoved, FeeCharged, RetryReturned }
=> assess_handler
);
// handlers.rs
pub struct Assessment {
balances: BTreeMap<AccountId, Balance>,
unpaid: BTreeMap<PaymentKey, Attempt>,
decided: Vec<outcome![BalanceMoved | FeeCharged | RetryReturned]>,
}
fn accumulate(&self, state: &mut Self::State, entry: PostedEntry) {
// …
let balance = state.balance(&entry);
if balance.covers(entry.amount) {
// …
return;
}
match self.fee_rule.fee(attempt) {
Some(fee) => {
let charged = FeeCharged { attempt, balance, fee, /* … */ };
state.decided.push(outcome(charged));
// …
}
None => {
let returned = RetryReturned { attempt, balance, /* … */ };
state.decided.push(outcome(returned));
}
}
state.unpaid.insert(payment, attempt);
}Replay any run during an audit to ask “what if”.
Every run is archived with everything it read and decided, the merged order, every posted entry and every balance. A replay is a second run over that archive, and it leaves the first exactly as it was. What comes back is a comparison, whether the question is what happened or what the corrected rule would have done.
Audit
Replay the run as it was and ObzenFlow rebuilds the exact state and order of every account from the archive, each fee against the balance it saw, on the attempt it was, under the rule in force. That is the regulator’s question answered, and
--verifyreports no difference between the replay and the record.Root cause and what-if
Change one thing, the rule, and replay the same inputs. The run names the one difference before it starts,
app.fee_rule, decides every fee again underone_fee_per_paymentand lets--verifycount what would have differed, fourteen differences across two stages. That is the one command the hero asked for, and its answer is a count and a list. Nobody gets refunded by that run. The refund is a new business process with new facts, fed by the difference list.
$ cargo run -p obzenflow --example http_ingestion_piggy_bank_demo \
--features prometheus,web-host -- \
--config "$DEMO/obzenflow.fee-rule-v2.toml" \
--replay-from "$RUN" --verify
Configuration differs from
target/http-ingestion-piggy-bank-demo-logs/flows/<flow_id>:
app.fee_rule
[replay] chk-60472 SPARKLE TV $15.49 attempt 2
returned, no fee (one_fee_per_payment)
[replay] chk-60472 SPARKLE TV $15.49 attempt 3
returned, no fee (one_fee_per_payment)
[replay] chk-58213 NORTHSIDE FIT $49.99 attempt 2
returned, no fee (one_fee_per_payment)
output diverged from the baseline: 14 difference(s) across 2 stage(s)
Build your next ledger on ObzenFlow.
ObzenFlow is open source. Star the project to follow its progress, or start a tutorial and build something yourself.
Have a question? Ask it in GitHub Discussions.