Merge pull request #262 from PaulRBerg/docs/polish-readme

docs: polish README

Author: PaulRBerg

README.md

@@ -7,6 +7,10 @@
 [license]: https://opensource.org/licenses/MIT
 [license-badge]: https://img.shields.io/badge/License-MIT-blue.svg
 
+<div align="center">
+  <img src="./assets/logo.png" alt="PRBMath Logo" width="250">
+</div>
+
 **Solidity library for advanced fixed-point math** that operates with signed 59.18-decimal fixed-point and unsigned 60.18-decimal fixed-point numbers.
 The name of the number format comes from the integer part having up to 59 digits for signed numbers and 60 digits for unsigned numbers, while the
 fractional part has up to 18 decimals. The numbers are bound by the minimum and the maximum values permitted by the Solidity types int256 and uint256.
@@ -21,15 +25,15 @@ fractional part has up to 18 decimals. The numbers are bound by the minimum and
 - Well-documented with NatSpec comments
 - Built and tested with Foundry
 
-I created this because I wanted a fixed-point math library that is at the same time intuitive, efficient and safe. I looked at
-[ABDKMath64x64](https://github.com/abdk-consulting/abdk-libraries-solidity), which is fast, but it uses binary numbers which are counter-intuitive and
-non-familiar to humans. Then, I looked at [Fixidity](https://github.com/CementDAO/Fixidity), which operates with denary numbers and has wide
-precision, but is slow and susceptible to phantom overflow. Finally, I looked at [Solmate](https://github.com/transmissions11/solmate), which checks
-all the boxes mentioned thus far, but it doesn't offer type safety.
+> [!NOTE]
+>
+> PRBMath is a fixed-point math library that is at the same time intuitive, efficient and safe.
+> [ABDKMath64x64](https://github.com/abdk-consulting/abdk-libraries-solidity) is fast, but uses binary numbers, which are counter-intuitive.
+> [Solmate](https://github.com/transmissions11/solmate) is fast and intuitive, but lacks type safety.
 
-## Install
+## 📦 Install
 
-### Node.js
+### 🟢 Node.js
 
 This is the recommended approach.
 
@@ -45,7 +49,7 @@ Then, if you are using Foundry, you need to add this to your `remappings.txt` fi
 @prb/math/=node_modules/@prb/math/
 ```
 
-### Git Submodules
+### 🔗 Git Submodules
 
 This installation method is not recommended, but it is available for those who prefer it.
 
@@ -70,7 +74,7 @@ Finally, add this to your `remappings.txt` file:
 @prb/math/=lib/prb-math/
 ```
 
-## Usage
+## 🚀 Usage
 
 There are two user-defined value types:
 
@@ -84,7 +88,7 @@ If you don't need negative numbers, there's no point in using the signed flavor
 Note that PRBMath is not a library in the Solidity [sense](https://docs.soliditylang.org/en/v0.8.17/contracts.html#libraries). It's just a collection
 of free functions.
 
-### Importing
+### 📥 Importing
 
 It is recommended that you import PRBMath using specific symbols. Importing full files can result in Solidity complaining about duplicate definitions
 and static analyzers like Slither erroring, especially as repos grow and have more dependencies with overlapping names.
@@ -107,7 +111,7 @@ import { UD60x18, ud } from "@prb/math/src/UD60x18.sol";
 
 Note that PRBMath can only be used in Solidity v0.8.19 and above.
 
-### SD59x18
+### ➕ SD59x18
 
 ```solidity
 // SPDX-License-Identifier: UNLICENSED
@@ -131,7 +135,7 @@ contract SignedConsumer {
 }
 ```
 
-### UD60x18
+### ➕ UD60x18
 
 ```solidity
 // SPDX-License-Identifier: UNLICENSED
@@ -155,12 +159,12 @@ contract UnsignedConsumer {
 }
 ```
 
-## Features
+## ✨ Features
 
 Because there's significant overlap between the features available in SD59x18 and UD60x18, there is only one table per section. If in doubt, refer to
 the source code, which is well-documented with NatSpec comments.
 
-### Mathematical Functions
+### 🔢 Mathematical Functions
 
 | Name    | Operator | Description                                      |
 | ------- | -------- | ------------------------------------------------ |
@@ -182,7 +186,7 @@ the source code, which is well-documented with NatSpec comments.
 | `powu`  | N/A      | Power function x^y with y simple integer         |
 | `sqrt`  | N/A      | Square root                                      |
 
-### Adjacent Value Types
+### 🔗 Adjacent Value Types
 
 PRBMath provides adjacent value types that serve as abstractions over other vanilla types:
 
@@ -198,7 +202,7 @@ These are useful if you want to save gas by using a lower bit width integer, e.g
 Note that these types don't have any mathematical functionality. To do math with them, you will have to unwrap them into a simple integer and then to
 the core types `SD59x18` and `UD60x18`.
 
-### Casting Functions
+### 🔄 Casting Functions
 
 All PRBMath types have casting functions to and from all other types, including a few basic types like `uint128` and `uint40`.
 
@@ -216,7 +220,7 @@ All PRBMath types have casting functions to and from all other types, including
 | `ud2x18`      | Alias for `UD2x18.wrap`   |
 | `ud60x18`     | Alias for `UD60x18.wrap`  |
 
-### Conversion Functions
+### ⚡ Conversion Functions
 
 The difference between "conversion" and "casting" is that conversion functions multiply or divide the inputs, whereas casting functions simply cast
 them.
@@ -228,7 +232,7 @@ them.
 | `convert(int256)`  | Converts a simple integer to SD59x18 by multiplying it by 1e18        |
 | `convert(uint256)` | Converts a simple integer to UD60x18 type by multiplying it by 1e18   |
 
-### Helper Functions
+### 🛠️ Helper Functions
 
 In addition to offering mathematical, casting, and conversion functions, PRBMath provides numerous helper functions for user-defined value types:
 
@@ -274,7 +278,7 @@ function addRshiftEq() pure returns (bool result) {
 
 ```
 
-### Assertions
+### ✅ Assertions
 
 PRBMath comes with typed assertions that you can use for writing tests with [PRBTest](https://github.com/PaulRBerg/prb-test), which is based on
 Foundry. This is useful if, for example, you would like to assert that two UD60x18 numbers are equal.
@@ -296,7 +300,7 @@ contract MyTest is PRBTest, PRBMathAssertions {
 }
 ```
 
-## Gas Efficiency
+## ⚡ Gas Efficiency
 
 PRBMath is faster than ABDKMath for `abs`, `exp`, `exp2`, `gm`, `inv`, `ln`, `log2`, but it is slower than ABDKMath for `avg`, `div`, `mul`, `powu`
 and `sqrt`.
@@ -351,12 +355,12 @@ Gas estimations based on the v3.0 release of ABDKMath. See my [abdk-gas-estimati
 | pow    | 303  | 4740 | 1792 |
 | sqrt   | 129  | 809  | 699  |
 
-## Contributing
+## 🤝 Contributing
 
 Feel free to dive in! [Open](https://github.com/PaulRBerg/prb-math/issues/new) an issue,
 [start](https://github.com/PaulRBerg/prb-math/discussions/new) a discussion or submit a PR.
 
-### Pre Requisites
+### 📋 Pre Requisites
 
 You will need the following software on your machine:
 
@@ -367,7 +371,7 @@ You will need the following software on your machine:
 
 In addition, familiarity with [Solidity](https://soliditylang.org/) is requisite.
 
-### Set Up
+### ⚙️ Set Up
 
 Clone this repository including submodules:
 
@@ -383,35 +387,45 @@ $ bun install
 
 Now you can start making changes.
 
-### Syntax Highlighting
+### 🎨 Syntax Highlighting
 
 You will need the following VSCode extensions:
 
 - [hardhat-solidity](https://marketplace.visualstudio.com/items?itemName=NomicFoundation.hardhat-solidity)
 - [vscode-tree-language](https://marketplace.visualstudio.com/items?itemName=CTC.vscode-tree-extension)
 
-## Security
+## 🔒 Security
 
 The codebase has undergone audits by leading security experts from Cantina and Certora. For a comprehensive list of all audits conducted, see the
 [SECURITY](./SECURITY.md) file.
 
-### Caveat Emptor
+### ⚠️ Caveat Emptor
 
 This is experimental software and is provided on an "as is" and "as available" basis. I do not give any warranties and will not be liable for any
 loss, direct or indirect through continued use of this codebase.
 
-### Contact
+### 📞 Contact
 
 If you discover any bugs or security issues, please report them via [Telegram](https://t.me/PaulRBerg).
 
-## Acknowledgments
+## 🙏 Acknowledgments
 
 - Mikhail Vladimirov for the insights he shared in the [Math in Solidity](https://medium.com/coinmonks/math-in-solidity-part-1-numbers-384c8377f26d)
   article series.
 - Remco Bloemen for his work on [overflow-safe multiplication and division](https://xn--2-umb.com/21/muldiv/), and for responding to the questions I
   asked him while developing the library.
 - Everyone who has contributed a PR to this repository.
 
-## License
+<h2>
+  <img src="./assets/op.png"
+       alt="Optimism logo"
+       width="23" />
+  Retro Funding
+</h2>
+
+A big shoutout and thank you to the [Optimism](https://optimism.io) team for funding the development of this library via the
+[Retro Funding](https://atlas.optimism.io/project/0x7e917a2d0718401c9fe2a82f43ea558f5128f251b1e658c76dc7ff9a5e9fd993) program.
+
+## 📄 License
 
 This project is licensed under MIT.