{"id":21221772,"url":"https://github.com/primitivefinance/solstat","last_synced_at":"2025-07-10T13:32:54.653Z","repository":{"id":65169032,"uuid":"496410824","full_name":"primitivefinance/solstat","owner":"primitivefinance","description":"Math library written in solidity for statistical function approximations like the Normal Cumulative Distribution Function.","archived":false,"fork":false,"pushed_at":"2023-12-04T18:05:26.000Z","size":1553,"stargazers_count":119,"open_issues_count":6,"forks_count":4,"subscribers_count":11,"default_branch":"main","last_synced_at":"2025-04-05T13:51:27.012Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Solidity","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/primitivefinance.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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":"2022-05-25T22:42:23.000Z","updated_at":"2025-03-20T07:10:16.000Z","dependencies_parsed_at":"2024-11-20T22:45:39.608Z","dependency_job_id":"00c5c47c-ff0a-4222-9c09-95f3b6027074","html_url":"https://github.com/primitivefinance/solstat","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":"primitivefinance/hardhat-foundry","purl":"pkg:github/primitivefinance/solstat","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/primitivefinance%2Fsolstat","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/primitivefinance%2Fsolstat/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/primitivefinance%2Fsolstat/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/primitivefinance%2Fsolstat/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/primitivefinance","download_url":"https://codeload.github.com/primitivefinance/solstat/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/primitivefinance%2Fsolstat/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264585371,"owners_count":23632646,"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":[],"created_at":"2024-11-20T22:33:28.643Z","updated_at":"2025-07-10T13:32:53.983Z","avatar_url":"https://github.com/primitivefinance.png","language":"Solidity","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Beta\n\n\u003e This library is in beta. It's not ready for production.\n\n![](https://visitor-badge.laobi.icu/badge?page_id=solstat) [![](https://github.com/primitivefinance/solstat/actions/workflows/ci.yaml/badge.svg)](https://github.com/primitivefinance/solstat/actions/workflows/ci.yaml) [![](https://dcbadge.vercel.app/api/server/primitive?style=flat)](https://discord.gg/primitive) [![Twitter Badge](https://badgen.net/badge/icon/twitter?icon=twitter\u0026label)](https://twitter.com/primitivefi) \n\n# SolStat\n\nSolStat is a Math library written in solidity for statistical function approximations. The library is composed of two core libraries; Gaussian.sol, and Invariant.sol. We will go over each of these libraries and their testing suites. We at Primitive use these libraries to support development with RMM-01s unique trading function, which utilizes the cumulative distribution function (CDF) of the normal distribution denoted by the greek capital letter Phi($\\Phi$) in the literature [1,2]. You may recognize the normal or Gaussian distribution as the bell curve. This distribution is significant in modeling real-valued random numbers of unknown distributions. Within the RMM-01 trading function and options pricing, the CDF is used to model random price movement of a Markov process. Since price paths are commonly modeled with markovian proccesses, we believe that the greater community will find value in this library.\n\n## How to use\n\nRequirements: forge, node \u003e=v16.0.0\n\n```\nyarn install\nforge install\nyarn build\nforge test\n```\n\nTo compute values using the gaussian.js library, you can use this commmand in the cli:\n\n```\nyarn cli --cdf {value}\nyarn cli --pdf {value}\nyarn cli --ppf {value}\n```\n\n## Irrational Functions\n\nThe primary reason for utilizing these approximation algorithms is that computers have trouble expressing irrational functions. This is because irrational numbers have an infinite number of decimals. Some examples of irrational numbers are $\\pi$ and $\\sqrt(2)$. This only becomes a challenge when we try to compute these numbers. This is because computers don't have an infinite amount of memory. Thus mathematicians and computer scientists have developed a variety of approximation algorithms to achieve varying degrees of speed and accuracy when approximating these irrational functions. These algorithms are commonly iterative and achieve greater accuracy with more iterations.\n\n## Computational Constraints\n\nIn classical computing, our computational resources have become [abundant](https://en.wikipedia.org/wiki/Moore%27s_law), allowing us the liberty to iterate these algorithms to achieve our desired accuracy. However, the [Ethereum Virtual Machine (EVM)](https://ethereum.org/en/developers/docs/evm/) has a necessary monetary cost of computation. This computational environment has monetarily motivated developers to find efficient algorithms and hacks to reduce their applications' computational overhead (and thus the cost of computation).\n\n## `Gaussian.sol`\n\nThis contract implements a number of functions important to the gaussian distributions. Importantly all these implementations are only for a mean $\\mu = 0$ and variance $\\sigma = 1$. These implementations are based on the [Numerical Recipes](https://e-maxx.ru/bookz/files/numerical_recipes.pdf) textbook and its C implementation. [Numerical Recipes](https://e-maxx.ru/bookz/files/numerical_recipes.pdf) cites the original text by Abramowitz and Stegun, \"[Handbook of Mathematical Functions](https://personal.math.ubc.ca/~cbm/aands/abramowitz_and_stegun.pdf),\" which should be read to understand these unique functions and the implications of their numerical approximations. This implementation was also inspired by the [javascript Gausian library](https://github.com/errcw/gaussian), which implements the same algorithm.\n\n### Cumulative Distribution Function\n\nThe implementation of the CDF aproximation algorithm takes in a random variable $x$ as a single parameter. The function depends on a special helper functions known as the error function `erf`. The error function’s identity is `erfc(-x) = 2 - erfc(x)` and has a small collection of unique properties:\n\nerfc(-infinity) = 2\n\nerfc(0) = 1\n\nerfc(infinity) = 0\n\nThe reference implementation for the error function is on p221 of Numerical Recipes in section C 2e. A helpful resource is this [wolfram notebook](https://mathworld.wolfram.com/Erfc.html).\n\n### Probability Density Function\n\nThe library also supports an approximation of the Probability Density Function(PPF) which is mathematically interpeted as $Z(x) = \\frac{1}{\\sigma\\sqrt{2\\pi}}e^{\\frac{-(x - \\mu)^2}{2\\sigma^2}}$. This implementation has a maximum error bound of of $1.2e-7$ and can be refrenced in this [wofram notebook](https://mathworld.wolfram.com/ProbabilityDensityFunction.html).\n\n### Percent Point Function / Quantile Function\n\nFurthermore we implemented aproximation algorithms for the Percent Point Function(PPF) sometimes known as the inverse CDF or the quantile function. The function is mathmatically defined as $D(x) = \\mu - \\sigma\\sqrt{2}(ierfc(2x))$, has a maximum error of `1.2e-7`, and depends on the inverse error function `ierf` which satisfies `ierfc(erfc(x)) = erfc(ierfc(x))`. The invers error function, defined as `ierfc(1 - x) = ierf(x)`, has a domain of in the interval $0 \u003c x \u003c 2$ and has some unique properties:\n\nierfc(0) = infinity\n\nierfc(1) = 0\n\nierfc(2) = - infinity\n\n## `Invariant.sol`\n\n`Invariant.sol` is a contract used to compute the invariant of the RMM-01 trading function such that we compute $y$ in $y = K\\Phi(\\Phi^{⁻¹}(1-x) - \\sigma\\sqrt(\\tau)) + k$. Notice how we need to compute the normal CDF of a quantity. For a more detailed perspective on the trading function, please see the whitepaper. This is an example of how we have used this library for our research, development, and testing of RMM-01. The function reverts if $x$ is greater than one and simplifies to $K(1+x) + k$ when $\\tau$ is zero (at expiry). The function takes in five parameters\n`R_x`: The reserves of token $x$ per unit of liquidity, always within the bounds of $[0,1]$.\n`stk`: The strike price of the pool.\n`vol`: the implied volatility of the pool denoted by the lowercase greek letter sigma in finance literature.\n`tau`: The time until the pool expires. Once expired, there can be no swaps.\n`inv`: The current invariant given `R_x`.\nThe function then returns the quantity of token y per unit of liquidity denoted `R_y`, which is always within the bounds of $[0, stk]$. This is a clear example of how one would use this library.\n\n## Differential Testing with Foundry\n\nWe leveraged foundry's support of differential testing for this library. Differential testing is a popular technique that seeds inputs to different implementations of the same application and detects differences in their execution. Differential testing is an excellent complement to traditional software testing as it is well suited to detect semantic errors. This library used differential testing against the javascript gaussian library to detect anomalies and varying bugs. This helped us to be confident in the performance and implementation of the library.\n\n[1]: [Replicating Market Makers](https://arxiv.org/pdf/2103.14769.pdf)\n\n[2]: [Replicating Portfolios: Contstructing Permissionless Derivatives](https://arxiv.org/pdf/2205.09890.pdf)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprimitivefinance%2Fsolstat","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprimitivefinance%2Fsolstat","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprimitivefinance%2Fsolstat/lists"}