In most software, "close enough" is fine. If a button is one pixel off, nobody loses their job. In finance, "close enough" can become expensive. Monetra exists for one reason: to make financial correctness the default, not a best effort. When money moves through software, three things must remain true: 1. The math must be exact. 2. The rules must be explicit. 3. The history must be defensible. If any of those fail, you get the kind of bugs that do not show up as a crash. They show up as an accounting discrepancy, a reconciliation nightmare, or a customer support escalation. I built Monetra because many systems still treat money like a normal number. Normal numbers are great for pixels, physics, and animation. They are a poor fit for cents. Monetra is a precise financial system for TypeScript. It gives engineers a safer set of building blocks, and it gives non-technical stakeholders something they can trust: a design that makes it hard to do the wrong thing and easy to prove you did the right thing. ## The Problem Monetra Solves (In Plain English) Computers are excellent at counting whole things. They are not naturally good at representing many decimal fractions. That is why, in many languages, a simple expression like 0.1 + 0.2 can produce 0.30000000000000004. That extra tail is tiny, but it is real. Now imagine you are calculating totals, taxes, discounts, proration, fees, refunds, chargebacks, and foreign exchange across millions of transactions. Tiny errors do not stay tiny. Financial systems have a different bar. If your system says a customer paid $100.00, the ledger has to agree. The invoice has to agree. The tax report has to agree. The bank payout has to agree. And six months later, you still need to be able to explain exactly how the number was produced. Monetra solves this by making money behave like money. I represent values in their smallest unit (like cents), apply explicit rules for any ambiguous operation (like splitting), and record decisions in a way that can be verified later. ## What Monetra Is (And What It Is Not) Monetra is a financial foundation. It is designed to be embedded inside products that move, store, or report money. It is intentionally not: - A payment processor - A currency conversion service - A replacement for your accounting platform Instead, it is the piece you put underneath those systems to stop precision bugs from leaking into everything else. ## The Monetra Stack To keep the system both safe and practical, Monetra is built as a three-layer stack. You can think of it like a reliable vehicle: the engine has to be precise, the controls have to be predictable, and the dashboard has to tell the truth. ### Layer 1 - The Foundation (Accuracy) This layer answers a simple question: when the software says "$1.00", is it truly one dollar? Key ideas: - **Smallest unit storage:** Money is stored as the smallest unit (cents, pennies, satoshis, or custom units). This avoids the entire category of decimal rounding drift. - **Immutability:** Once created, a money value does not change. Operations produce new values. That sounds academic until you have to debug a production issue and realize a mutable object was modified in three different places. - **Currency awareness:** "10" is meaningless without context. 10 USD is not 10 EUR. Monetra makes currency explicit so accidental mixing is much harder. Why it matters (non-technical): - Totals do not mysteriously change. - Reports match invoices. - You can trust that the number shown on screen is the number stored in the system. Why it matters (engineers): - Deterministic arithmetic. - Fewer edge cases where "almost equal" becomes a bug. - A smaller surface area for precision-related regressions. ### Layer 2 - The Logic (Financial Operations) Once money is safe, you can do real work with it. This layer focuses on financial operations that teams typically rebuild from scratch or maintain in spreadsheets: - **Loans and payments:** Predictable monthly payment calculations and schedules. - **Value over time:** Concepts like Time Value of Money, where $100 today is not equivalent to $100 next year. - **Asset depreciation:** Standard ways to model how an asset loses value. This is the layer that turns Monetra from "safe math" into "usable financial engineering". ### Layer 3 - The Audit (Trust and Verification) Finance does not just require correct numbers. It requires explainable numbers. This layer focuses on auditability: - **Ledger:** A structured record of money movements. Every payment, refund, fee, or transfer becomes a traceable entry. - **Tamper-evident history:** Records can be sealed using cryptographic hashing. If someone tries to rewrite the past, the chain no longer verifies. Why this matters (non-technical): - You can answer "where did the money go?" with confidence. - You can detect manipulation rather than hoping it never happens. Why this matters (engineers): - Integrity checks become a first-class tool. - You can design systems that do not rely on blind trust between services. ## Engineering Process: How Monetra Was Built Monetra was not built by accident. It was built by applying the same discipline I use when working with AI tooling: deep context, strict rules, and a refusal to ship ambiguity. ### 1) Define the non-negotiables Before writing code, I wrote down what must always be true: - A cent cannot be created or destroyed. - Every operation with ambiguity must be explicit. - The system must be deterministic across environments. - Auditing must be possible without special tooling. Those constraints are inconvenient at first. They also save you later. ### 2) Choose boring, stable primitives Monetra prioritizes stability and portability: - It is written in TypeScript. - It is designed to run in Node.js, browsers, and edge runtimes. - It keeps dependencies to a minimum. This is a deliberate tradeoff. In finance, reliability is a feature. ### 3) Make tradeoffs explicit Every serious system has tradeoffs. The difference is whether you acknowledge them. Here are a few that shaped Monetra: **Explicitness vs convenience** Most libraries try to guess what you mean. Monetra refuses to guess. If you split money and there is a remainder, the system requires you to choose how to round. - Convenience cost: developers write a bit more code. - Safety gain: rounding decisions are intentional and reviewable. **Immutability vs raw speed** Mutable objects can be faster in micro-benchmarks. Immutable objects are easier to reason about. - Speed cost: more object creation. - Safety gain: fewer "who changed this value?" mysteries. **Auditability vs storage** Recording more detail costs space. - Storage cost: larger records. - Safety gain: a system you can defend under scrutiny. ### 4) Test against edge cases Financial bugs are usually edge cases. Monetra uses multiple layers of testing to avoid the trap of only testing happy paths. - **Example-based tests:** the traditional "given X, expect Y" approach. - **Property-based tests:** the system is exercised with broad ranges of values to validate rules like "adding then subtracting returns you to the original value". - **Mutation testing:** the code is intentionally mutated to ensure the tests fail for the right reasons. This is not about vanity metrics. It is about earning trust. ## Obstacles I Hit (And How I Worked Through Them) Every project that touches money hits the same wall: complexity that looks small until it is production. Monetra held up because the approach was not "move fast and fix later". It was "move deliberately so later does not become a crisis". ### Obstacle: Splitting money fairly Splitting is deceptively hard. Humans accept that $10 split three ways cannot be perfectly equal. Computers, if left to their defaults, will leak precision or silently lose remainders. What I did: - I built allocation algorithms that guarantee conservation of value. - I forced rounding strategy selection so the rule is not hidden. Result: - Conservation of value is enforced. - Remainders are handled explicitly. - The decision is auditable. ### Obstacle: Mixed currencies and the "MoneyBag" problem Teams often want a single "total" across currencies. That total is not meaningful unless conversion rules are defined. What I did: - I introduced the idea of a "MoneyBag" - a safe container that can hold USD, EUR, GBP, or custom tokens without forcing premature conversion. Result: - You can accumulate across currencies safely. - Conversion becomes an explicit boundary where business rules can be applied. ### Obstacle: Explaining correctness, not just claiming it Saying "it is precise" is easy. Proving it is harder. What I did: - I built verification into the philosophy and the toolchain. - I used tests that explore large spaces of inputs. - I designed the ledger to be tamper-evident. Result: - Correctness is a property of the system, not a marketing statement. ### Obstacle: Building without burning out There is a specific psychological trap when building financial tooling: the deeper you go, the more edge cases you discover. It can feel infinite. The way through is process: - Define what is in scope. - Build it completely. - Test it aggressively. - Ship it. - Iterate. Monetra is a product of that discipline. ## Where Monetra Fits (Real Use Cases) Monetra is built for environments where precision and accountability are not optional. ### E-commerce and subscriptions - Totals with discounts and taxes - Proration for upgrades, downgrades, and refunds - Fee calculations that must match invoice detail ### Fintech and internal accounting - Ledger-based movement of money between accounts - Reconciliation workflows where numbers must match across systems - Audit trails that can survive scrutiny ### Crypto and token systems - Tokens with high precision (many decimals) - Multi-asset wallets and internal accounting - Deterministic arithmetic that cannot drift ## For Engineers (Without Turning This Into a Manual) Monetra is designed so that you can start simple and go deep when needed. The mental model is: - Money values are precise and immutable. - Currencies are explicit. - Any ambiguous operation requires an explicit policy. - Ledger entries can be verified. If you are building with it, expect the library to push back when you attempt something unsafe. That is a feature. Rounding modes exist because real finance uses different rules in different contexts. Monetra supports multiple strategies, including: - Half up - Half down - Half even (bankers rounding) - Floor - Ceil - Truncate The important part is not the names. The important part is that the choice is not hidden. ## Future Roadmap Monetra is moving from "a strong TypeScript foundation" to "a cross-language financial foundation". - **Python library with full parity:** A first-class Python implementation with the same core concepts and safety guarantees. This matters for data science, analytics pipelines, and backend services that need to share the same financial rules. - **Other language frameworks:** Over time, I want the same system-level rigor available in other ecosystems, so product teams are not forced into language-specific compromises. - **Tax modules:** Plug-and-play modules for tax rules. The goal is to make tax handling explicit, testable, and maintainable rather than scattered across application code. - **Medium to advanced financial math:** Beyond basic loans, I plan to expand into investment and analysis tooling (for example, NPV, IRR, and other industry-standard models) with the same emphasis on correctness and explicit assumptions. ## FAQ

Who is Monetra for?

Monetra is for teams building products where money is central - e-commerce, subscriptions, marketplaces, fintech, crypto platforms, and internal finance tooling. It is also for engineers who want their systems to be defensible under audit.

Why not just use normal numbers?

Because normal numbers are not designed for decimal money. Small errors accumulate, and financial systems need exact totals that can be reconciled and explained.

Does this mean Monetra is slower?

Sometimes, yes. Safety has a cost. But the tradeoff is intentional: it is better to spend a little more CPU than to spend weeks investigating a reconciliation discrepancy.

Why does Monetra force explicit rounding?

Because rounding is a business decision. Taxes, payouts, and financial reporting often use different rounding policies. Monetra forces the decision into the open so it can be reviewed and tested.

What is a "MoneyBag" in simple terms?

It is a wallet. You can put multiple currencies into it without mixing them. You can count what you have, but you do not pretend that dollars and euros are directly addable until you decide how to convert.

Is Monetra a payment solution?

No. Monetra does not charge cards or move money through banks. It helps your software represent and reason about money safely.

What about exchange rates?

Exchange rates are not a pure math problem, they are a business rule. Monetra is designed to keep conversion explicit and controlled rather than hiding it inside "totals".

What does "tamper-evident" mean?

It means the system can detect whether history was rewritten. If someone changes an old entry, verification fails. This is similar in spirit to how blockchains detect tampering, without requiring a blockchain.

Does Monetra help with compliance?

Compliance is broader than a library, but Monetra supports compliance by making transactions traceable and decisions explicit. It makes it easier to demonstrate correctness and intent.

Can I use it in the browser?

Yes. Monetra is designed to run across environments so shared financial rules can exist in both frontend and backend.

Can I adopt Monetra incrementally?

Yes. You can start by using safe money values in one part of the system (for example invoicing), then expand to allocations, then ledger auditing.

Why TypeScript?

Because TypeScript makes it easier to enforce correct usage through types and tooling. It is not just about convenience, it is about preventing entire categories of mistakes.

What is the philosophy behind the project?

Financial correctness should be impossible to get wrong by accident. If a mistake can happen silently, it will happen eventually.

Where can I learn more?

- Developer Documentation: [Monetra Developer Docs](/documentation/monetra) - Repository: [GitHub Repo](https://github.com/zugobite/monetra) - NPM Package: [Official NPM Package](https://www.npmjs.com/package/monetra)

Monetra turns one of the highest-risk parts of a financial application - the math - into one of the most reliable.

Projects