{"id":20245032,"url":"https://github.com/interlay/monetary","last_synced_at":"2025-07-20T12:32:28.773Z","repository":{"id":39883398,"uuid":"349475679","full_name":"interlay/monetary","owner":"interlay","description":"A library to handle currencies and money. Targeted at Dapps and other blockchain applications.","archived":false,"fork":false,"pushed_at":"2023-10-23T02:39:29.000Z","size":175,"stargazers_count":7,"open_issues_count":1,"forks_count":5,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-06-14T02:49:34.681Z","etag":null,"topics":["currencies","monetary","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/interlay.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-03-19T15:47:58.000Z","updated_at":"2024-05-11T23:44:20.000Z","dependencies_parsed_at":"2022-08-09T15:35:52.154Z","dependency_job_id":"d87b25d6-0df7-40cf-9a61-7057c925eed5","html_url":"https://github.com/interlay/monetary","commit_stats":{"total_commits":70,"total_committers":7,"mean_commits":10.0,"dds":0.6571428571428571,"last_synced_commit":"d69bf9838bcd7225c58ab66b93af433efe004157"},"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"purl":"pkg:github/interlay/monetary","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/interlay%2Fmonetary","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/interlay%2Fmonetary/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/interlay%2Fmonetary/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/interlay%2Fmonetary/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/interlay","download_url":"https://codeload.github.com/interlay/monetary/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/interlay%2Fmonetary/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265254646,"owners_count":23735118,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["currencies","monetary","typescript"],"created_at":"2024-11-14T09:18:36.461Z","updated_at":"2025-07-20T12:32:28.756Z","avatar_url":"https://github.com/interlay.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# monetary\n\nA library to handle currencies and money. Targeted at blockchain and cross-chain applications.\n\n## About\n\nBuilding systems with money is pretty hard. Especially when the monetary amounts that the application has to deal with uses different decimal representations, has numerous accounting units, and the same currency exists on multiple chains.\n\nTo tackle these issues, this library serves as a common interface to deal with monetary amounts in a safe and predictable way.\n\n### Objectives\n\nThe overall goal of this library is two-fold:\n\n1. Provide a secure currency interface. This includes safe arithmetic, type checking to ensure conversions between currencies are done correctly, and correct rounding.\n2. Provide a universal currency interface. The interface should be able to have an identifiable name and ticker, and an \"origin\".\n\n### Specification\n\nWe provide a light-weight specification to establish a common set of rules for the monetary library. Please check the [specification](docs/specification.md) for more details.\n\n### References\n\n- A good portion of this specification was inspired by this excellent post on [safe-money](https://ren.zone/articles/safe-money).\n- There is also a great library for fiat currencies called [dinero.js](https://github.com/dinerojs/dinero.js) based on this [post](https://frontstuff.io/how-to-handle-monetary-values-in-javascript).\n\n## Library\n\n### Getting started\n\nInstall from npmjs:\n\n```shell\nnpm i @interlay/monetary-js\n```\n\nOr\n\n```shell\nyarn add @interlay/monetary-js\n```\n\n### Usage\n\nAssuming that the library already provides the currencies you require, you can readily use them as indicated below.\nYou may also add your own currencies without having to make an upstream contribution as explained in the [defining your own currencies section](#defining-your-own-currencies).\n\n```ts\nimport Big from \"big.js\";\nimport { Bitcoin, Ethereum, BitcoinAmount, EthereumAmount, ExchangeRate} from \"@interlay/monetary-js\";\n\nconst bitcoins = new BitcoinAmount(0.5);\nconst ethers = new EthereumAmount(new Big(1).mul(10).pow(-9)); // one gwei\nconst sameEthers = new EthereumAmount(\"1e-9\"); // also one gwei\n\n// conversions to string and Big of different units\nconsole.log(`We have ${bitcoins.toString()} BTC, and ${ethers.toString()} ethers.`);\n\nconst weiBig: Big = ethers.toBig(0); // value in atomic units (ETH * 10^-18 aka. wei)\nconst gweiBig: Big = ethers.toBig(9); // value in gwei (wei * 10^9)\nconst alsoEthBig: Big = ethers.toBig(18); // value in eth (wei * 10^18)\nconst ethBig: Big = ethers.toBig(); // value in eth (no parameter =\u003e assumes \"natural\" denomination)\n\nconst satoshiString: string = bitcoins.toString(true); // value as string in atomic units (satoshi)\nconst btcString: string = bitcoins.toString(); // value as string in \"natural\" units (btc)\n\n// converting between different currencies\nconst ETHBTCRate = new ExchangeRate\u003cEthereum, Bitcoin\u003e(\n  Ethereum,\n  Bitcoin,\n  new Big(0.0598)\n);\n\n// for ETH/BTC, \"base\" is ETH, \"counter\" is BTC\nconst bitcoinsAsEthers: EthereumAmount = ETHBTCRate.toBase(bitcoins);\n\n// type-safe arithmetic\nconst totalEthers = ethers.add(bitcoinsAsEthers);\n// ethers.add(bitcoins); // error\n```\n\n### Defining your own currencies\n\nMonetary-js comes with Bitcoin, Ethereum and Polkadot predefined, but it is meant to be extensible for any currency. `src/currencies/bitcoin.ts` can be used as an example for the minimal work needed to define a currency. Another example is `DummyCurrency` defined inline for unit tests in `test/monetary.test.ts`\n\nThe first step is to define our currency, parametrising the type with decimals. \n\n```ts\nexport const Bitcoin: Currency\u003ctypeof BitcoinUnit\u003e = {\n  name: \"Bitcoin\",\n  ticker: \"BTC\",\n  decimals: 8,\n  humanDecimals: 5\n} as const;\nexport type Bitcoin = typeof Bitcoin;\n```\n\nFor a `MonetaryAmount`, the internal representation will be stored with a 10 to the power of `decimals` shift of the `Currency`. Rounding, default behaviors for `toString()` and `toBig()` will represent the amounts at that precision.\nFor example, when using an amount of `0.5 Bitcoin`, the internal representation is represented as `0.5 * 10^8` (50,000,000 Satoshi)\nand all operations (`.add(...)`, `.sub(...)`, etc.) will use the internal representation.\n\n`humanDecimals` is used for pretty-printing approximate (truncated) stringified values using `toHuman()`.\n\nAt this point, the currency is usable:\n\n```ts\nimport { Bitcoin, BitcoinUnit } from \"src/currencies/bitcoin\";\nconst btcAmount = new MonetaryAmount\u003cBitcoin, BitcoinUnit\u003e(\n  Bitcoin,\n  0.5,\n  Bitcoin.units.BTC\n);\n```\n\nHowever, this is a bit verbose. We can subclass `MonetaryAmount` for convenience:\n\n```ts\nexport class BitcoinAmount extends MonetaryAmount\u003cBitcoin, BitcoinUnit\u003e {\n  // added convenience method\n  static zero = () =\u003e new BitcoinAmount(0);\n}\n```\n\n## Development\n\n### Installation\n\nCheckout the code and install the dependencies:\n\n```shell\ngit clone https://github.com/interlay/monetary.git\ncd monetary\nyarn install\n```\n\nBuild:\n\n```shell\nyarn build\n```\n\nAnd run tests:\n\n```shell\nyarn test\n```\n\n## Contributing\n\nContributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated. Our basic [contributing guidelines](CONTRIBUTING.md) are found in this repository.\n\n1. Fork the project\n2. Create your feature branch (`git checkout -b feat/AmazingFeature`)\n3. Sign and commit your changes (`git commit -S -m 'feat: Add some AmazingFeature'`)\n4. Push to the branch (`git push origin feat/AmazingFeature`)\n5. Open a pull request\n\nIf you are searching for a place to start or would like to discuss features, reach out to us on the #development channel:\n\n- [Discord](https://discord.gg/interlay)\n\n## License\n\n(C) Copyright 2023 [Interlay](https://www.interlay.io) Ltd\n\nmonetary is licensed under the terms of the MIT License. See [LICENSE](LICENSE).\n\n## Contact\n\nWebsite: [Interlay.io](https://www.interlay.io)\n\nTwitter: [@interlayHQ](https://twitter.com/InterlayHQ)\n\nEmail: contact@interlay.io\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finterlay%2Fmonetary","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finterlay%2Fmonetary","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finterlay%2Fmonetary/lists"}