{"id":20879409,"url":"https://github.com/joejordan/foundry-random","last_synced_at":"2026-04-26T19:31:14.859Z","repository":{"id":65026316,"uuid":"580938313","full_name":"joejordan/foundry-random","owner":"joejordan","description":"Generate reliably random numbers using Foundry's FFI cheat code.","archived":false,"fork":false,"pushed_at":"2022-12-23T17:38:59.000Z","size":1155,"stargazers_count":22,"open_issues_count":1,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-12-12T22:42:59.973Z","etag":null,"topics":["blockchain","ethereum","foundry","random-number-generator","solidity"],"latest_commit_sha":null,"homepage":"","language":"Solidity","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/joejordan.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-12-21T20:55:57.000Z","updated_at":"2024-06-18T13:57:02.000Z","dependencies_parsed_at":"2022-12-26T19:54:42.163Z","dependency_job_id":null,"html_url":"https://github.com/joejordan/foundry-random","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":"PaulRBerg/foundry-template","purl":"pkg:github/joejordan/foundry-random","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joejordan%2Ffoundry-random","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joejordan%2Ffoundry-random/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joejordan%2Ffoundry-random/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joejordan%2Ffoundry-random/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/joejordan","download_url":"https://codeload.github.com/joejordan/foundry-random/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joejordan%2Ffoundry-random/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32310804,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T19:15:34.056Z","status":"ssl_error","status_checked_at":"2026-04-26T19:15:15.467Z","response_time":129,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["blockchain","ethereum","foundry","random-number-generator","solidity"],"created_at":"2024-11-18T07:16:24.645Z","updated_at":"2026-04-26T19:31:14.835Z","avatar_url":"https://github.com/joejordan.png","language":"Solidity","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Foundry Random [![Open in Gitpod][gitpod-badge]][gitpod] [![Github Actions][gha-badge]][gha] [![Foundry][foundry-badge]][foundry] [![License: MIT][license-badge]][license]\n\n[gitpod]: https://gitpod.io/#https://github.com/joejordan/foundry-random\n[gitpod-badge]: https://img.shields.io/badge/Gitpod-Open%20in%20Gitpod-FFB45B?logo=gitpod\n[gha]: https://github.com/joejordan/foundry-random/actions\n[gha-badge]: https://github.com/joejordan/foundry-random/actions/workflows/ci.yml/badge.svg\n[foundry]: https://getfoundry.sh/\n[foundry-badge]: https://img.shields.io/badge/Built%20with-Foundry-FFDB1C.svg\n[license]: https://opensource.org/licenses/MIT\n[license-badge]: https://img.shields.io/badge/License-MIT-blue.svg\n\n***Generate reliably random numbers using Foundry's FFI cheat code.***\n\nMore than once now I have needed a reliably random number generator while using Foundry. Unfortunately, as of this writing, there is no `vm.random()` cheatcode included with this otherwise excellent development tool.\n\nThis project fills that gap by utilizing the FFI cheatcode to launch `cast wallet new`, a tool included with Foundry to quickly generate a new random keypair, and returning the generated private key as a `bytes32` value to the user. We have also included a few additional creature comforts via the inclusion of several plug-and-play random number generator functions to make life easier.\n\n### Example Use Case\n\nThe original use case I had for this was seeding a smart contract deploy script with random attribute values that would remain constant for the life of the contract. Similar seeding functionality could also be useful for certain types of tests.\n\n## Installation\n\n### Foundry\n\nFirst, run the install step:\n\n```sh\nforge install --no-commit joejordan/foundry-random\n```\n\nThen, add this to your `remappings.txt` file:\n\n```text\nfoundry-random=lib/foundry-random/src/\n```\n\n## Usage\n\nImport the library into your Solidity contract, i.e.\n\n```solidity\nimport { FoundryRandom } from \"foundry-random/FoundryRandom.sol\";\n```\n\nThe cleanest usage is probably to include it as an inherited contract on your Foundry Test or Script contract, as follows:\n\n\n```solidity\ncontract FoundryRandomTest is PRBTest, FoundryRandom {\n\n   function setUp() public {\n      // solhint-disable-previous-line no-empty-blocks\n   }\n\n   function testRandomNumber() public {\n      uint256 randomNum;\n      \n      // generate a random number between 0 and 255\n      randomNum = randomNumber(type(uint8).max);\n      assertLte(randomNum, type(uint8).max);\n\n      // generate a random number between 10 and 100\n      randomNum = randomNumber(10, 100);\n      assertGte(randomNum, 10);\n      assertLte(randomNum, 100);\n   }\n}\n\n```\n\nCheck out the [tests](https://github.com/joejordan/foundry-random/blob/main/test/FoundryRandom.t.sol) for more usage examples.\n\n## Contribute\n\nContributions are welcome! [Open](https://github.com/joejordan/foundry-random/issues/new) an issue or submit a PR. There is always room for improvement. The instructions below will walk you through setting up for contributions.\n\n### Pre-Requisites\n\nYou will need the following software on your machine:\n\n- [Git](https://git-scm.com/downloads)\n- [Foundry](https://github.com/foundry-rs/foundry)\n- [Node.js](https://nodejs.org/en/download/)\n- [Yarn](https://yarnpkg.com/)\n\n### Set Up\n\nClone this repository:\n\n```bash\n$ git clone https://github.com/joejordan/foundry-random.git\n```\n\nThen, inside the project's directory, run this to install dependencies:\n\n```bash\n$ yarn install\n```\n\nYour environment should now be ready for your improvements.\n\n## Security\n\nThis code has not been professionally audited by any third parties. If you include this codebase or parts of it in a professional audit, please let me know via [Twitter Direct Message](https://twitter.com/JJordan) for inclusion in this documentation.\n\nIf you discover any security issues with this codebase, please report them via [Twitter Direct Message](https://twitter.com/JJordan).\n\n### Disclaimer\n\nThis is experimental software and is provided on an \"as is\" basis. No expressed or implied warranties are granted of any kind. I will not be liable for any loss, direct or indirect, related to the use or misuse of this codebase.\n\n## Acknowledgements\n\n- [Gonçalo Sá](https://twitter.com/GNSPS) for his fantastic [solidity-bytes-utils](https://github.com/GNSPS/solidity-bytes-utils) library.\n- All of the contributors to the [Foundry toolkit](https://github.com/foundry-rs/foundry) for bringing Solidity development to the next level.\n\n## License\n\nfoundry-random is released under the [MIT License](./LICENSE.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoejordan%2Ffoundry-random","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjoejordan%2Ffoundry-random","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoejordan%2Ffoundry-random/lists"}