{"id":50521562,"url":"https://github.com/rhaiscript/rhai-bigint","last_synced_at":"2026-06-03T04:31:42.734Z","repository":{"id":356193416,"uuid":"1231441192","full_name":"rhaiscript/rhai-bigint","owner":"rhaiscript","description":"A Rhai scripting engine plugin providing seamless, arbitrary-precision BigInt arithmetic.","archived":false,"fork":false,"pushed_at":"2026-05-29T15:37:45.000Z","size":61,"stargazers_count":1,"open_issues_count":2,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-29T16:23:15.324Z","etag":null,"topics":["api-bindings","bigint","math","plugin","rhai","scripting"],"latest_commit_sha":null,"homepage":"https://crates.io/crates/rhai-bigint","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rhaiscript.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-07T01:00:01.000Z","updated_at":"2026-05-19T04:30:01.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/rhaiscript/rhai-bigint","commit_stats":null,"previous_names":["isserge/rhai-bigint","rhaiscript/rhai-bigint"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/rhaiscript/rhai-bigint","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rhaiscript%2Frhai-bigint","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rhaiscript%2Frhai-bigint/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rhaiscript%2Frhai-bigint/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rhaiscript%2Frhai-bigint/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rhaiscript","download_url":"https://codeload.github.com/rhaiscript/rhai-bigint/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rhaiscript%2Frhai-bigint/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33848860,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-03T02:00:06.370Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["api-bindings","bigint","math","plugin","rhai","scripting"],"created_at":"2026-06-03T04:31:41.911Z","updated_at":"2026-06-03T04:31:42.729Z","avatar_url":"https://github.com/rhaiscript.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# rhai-bigint\n\n[![Crates.io](https://img.shields.io/crates/v/rhai-bigint.svg)](https://crates.io/crates/rhai-bigint)\n[![Docs.rs](https://docs.rs/rhai-bigint/badge.svg)](https://docs.rs/rhai-bigint)\n[![License](https://img.shields.io/crates/l/rhai-bigint.svg)](https://crates.io/crates/rhai-bigint)\n[![Build Status](https://img.shields.io/github/actions/workflow/status/isSerge/rhai-bigint/ci.yml?branch=main)](https://github.com/isSerge/rhai-bigint/actions)\n\nA [Rhai](https://rhai.rs/) scripting engine plugin providing seamless, arbitrary-precision BigInt arithmetic.\n\n## Why this exists\n\nBy default, the Rhai scripting engine limits integers to 64-bit (or 128-bit via feature flags). When building financial applications, cryptography tools, or Web3 indexers, values frequently exceed these limits (e.g., 1 ETH = $10^{18}$ Wei). \n\nNaively casting these large numbers to floating-point (`f64`) results in catastrophic precision loss (IEEE 754 limits). Casting them to strings preserves the value, but breaks the ability to use native math operators inside the user's scripts.\n\n`rhai-bigint` solves this by injecting `num_bigint::BigInt` directly into the Rhai memory space and overloading the standard math and comparison operators. Users get the native ergonomics of standard operators, while the engine guarantees 100% lossless precision under the hood.\n\n## Features\n\n- Constructs `BigInt` from integers (`i64`), floats (`rhai::FLOAT`, truncated toward zero), and strings.\n- Overloads standard arithmetic operators (`+`, `-`, `*`, `/`, `%`, `**`).\n- Overloads unary negation (`-`).\n- Overloads bitwise operators (`\u0026`, `|`, `^`, `\u003c\u003c`, `\u003e\u003e`).\n- Overloads comparison operators (`==`, `!=`, `\u003e`, `\u003e=`, `\u003c`, `\u003c=`).\n- Converts `BigInt` back to a decimal string (`to_string`), hex string (`to_hex`), or float (`to_float`).\n- Provides `to_bigint()` as a method on integers and floats for ergonomic conversion: `42.to_bigint()`, `1.5.to_bigint()`.\n- Optional: Generate cryptographically secure random `BigInt`s by range or with up to specified bit-length (via the `rand` feature).\n\n## Installation\n\n### Add via Cargo\n\n```bash\ncargo add rhai-bigint\n```\n\n### Manual Configuration\n\nAdd the following to your `Cargo.toml`:\n\n```toml\n[dependencies]\nrhai = \"1.25.1\"\nrhai-bigint = \"0.1.10\"\n```\n\n### Feature Flags\n\n*   `sync`: Enables `rhai/sync` support. Turn this on if your Rhai engine requires thread-safe types (e.g., when evaluating scripts across a Tokio thread pool).\n*   `only_i32`: Passes `rhai/only_i32` through, making `rhai::INT` an `i32` instead of the default `i64`. All integer-accepting functions (`parse_bigint`, `to_bigint`, `**`, `\u003c\u003c`, `\u003e\u003e`) adapt automatically.\n*   `metadata`: Enables `rhai/metadata`, which exposes function signature and documentation metadata on the Rhai `Engine`. Required if you want to call `engine.gen_fn_signatures()` or similar introspection APIs.\n*   `rand`: Enables the generation of random `BigInt` values. Pulls in the `rand` crate and exposes the `rand_bigint` functions.\n\n## Usage\n\n### 1. Registering the Package in Rust\n\nUsing the plugin is as simple as registering the package with your Rhai `Engine`.\n\n```rust\nuse rhai::Engine;\nuse rhai::packages::Package;\nuse rhai_bigint::BigIntPackage;\n\nfn main() {\n    let mut engine = Engine::new();\n    \n    // Register the package into the engine\n    BigIntPackage::new().register_into_engine(\u0026mut engine);\n\n    // Now your scripts can seamlessly handle massive numbers!\n    let script = r#\"\n        let a = parse_bigint(\"1500000000000000000\"); // 1.5 ETH\n        let b = parse_bigint(\"500000000000000000\");  // 0.5 ETH\n        \n        let sum = a + b;\n        \n        sum \u003e parse_bigint(\"1900000000000000000\") // evaluates to true\n    \"#;\n\n    let result: bool = engine.eval(script).unwrap();\n    assert!(result);\n}\n```\n\n### 2. Scripting Examples\n\nOnce registered, your users can write natural, ergonomic scripts.\n\n#### Basic Arithmetic\n```js\nlet a = parse_bigint(42);                              // from integer\nlet b = parse_bigint(\"100000000000000000000000000000\"); // from string\n// let a = parse_bigint(1.5);  // from float — truncates toward zero, so this equals 1\n\nlet sum = a + b;\nlet diff = b - a;\nlet prod = a * b;\nlet quotient = b / a;\nlet remainder = b % a;\nlet power = a ** 3;    // exponentiation — exponent must be a non-negative integer\nlet negative = -a;\n\n// Bitwise operators (two's complement semantics)\nlet and_result  = a \u0026 parse_bigint(0xFF);\nlet or_result   = a | parse_bigint(0xFF);\nlet xor_result  = a ^ parse_bigint(0xFF);\nlet left_shift  = a \u003c\u003c 8;   // shift amount must be a non-negative integer\nlet right_shift = a \u003e\u003e 2;\n```\n\n#### Comparisons\n```js\nlet price = parse_bigint(\"2000000000000000000\");\nlet threshold = parse_bigint(\"1500000000000000000\");\n\nif price \u003e= threshold {\n    print(\"Threshold met!\");\n}\n```\n\n#### Random Number Generation (`rand` feature)\n\n```js\n// Generate a random, positive number at most 256 bits\nlet private_key = rand_bigint(256);\n\n// Generate a random number within a specific range [min, max)\nlet min = parse_bigint(100);\nlet max = parse_bigint(\"1000000000000000000\");\nlet random_amount = rand_bigint(min, max);\n```\n\n#### Integration with `rhai-rand`\n\nThis crate is designed to integrate seamlessly with [`rhai-rand`](https://github.com/rhaiscript/rhai-rand) via function overloading.\n\nRegister both packages:\n\n```js\nuse rhai::Engine;\nuse rhai::packages::Package;\nuse rhai_rand::RandomPackage;\nuse rhai_bigint::BigIntPackage;\n\nlet mut engine = Engine::new();\n\n// Register standard random number generation (for i64/f64)\nRandomPackage::new().register_into_engine(\u0026mut engine);\n\n// Register BigInt random number generation\nBigIntPackage::new().register_into_engine(\u0026mut engine);\n```\n\nIn Rhai scripts `rand()` function will route to the correct crate automatically based on the argument types:\n\n```js\n// Standard integers - routes to `rhai-rand`\nlet small_random = rand(1, 10); \n\n// BigInts - routes to `rhai-bigint`\nlet min = parse_bigint(\"1000000000000000000\");\nlet max = parse_bigint(\"9000000000000000000\");\nlet massive_random = rand(min, max); \n\n```\n\n#### Cross-type comparisons are errors\n\nAll six comparison operators (`==`, `!=`, `\u003c`, `\u003c=`, `\u003e`, `\u003e=`) raise a runtime error\nwhen one operand is a `BigInt` and the other is any other type (`int`, `float`, `string`,\n`bool`). This prevents subtle bugs where a mismatched comparison silently returns `false`\nwithout any indication that something is wrong. The error fires regardless of which side\nthe `BigInt` is on.\n\n**int**\n```js\n// ❌ All operators raise a runtime error\nparse_bigint(42) == 42\nparse_bigint(42) != 42\nparse_bigint(42) \u003c  42\nparse_bigint(42) \u003e= 42\n42 == parse_bigint(42)   // right-hand side equally affected\n\n// ✅ Wrap the int first\nparse_bigint(42) == parse_bigint(42)\nparse_bigint(100) \u003e parse_bigint(42)\n```\n\n**float**\n```js\n// ❌ Runtime error for every operator\nparse_bigint(42) == 3.14\nparse_bigint(42) \u003c  3.14\n\n// ✅ Convert the float to BigInt first via to_bigint() (truncates toward zero)\n3.14.to_bigint() == parse_bigint(3)\nparse_bigint(10) \u003e (2.9).to_bigint()\n```\n\n**string**\n```js\n// ❌ Runtime error for every operator\nparse_bigint(42) == \"42\"\nparse_bigint(42) \u003c  \"42\"\n\n// ✅ Parse both sides first\nparse_bigint(\"42\") == parse_bigint(\"42\")\nparse_bigint(\"100\") \u003e parse_bigint(\"42\")\n```\n\n**bool**\n```js\n// ❌ Runtime error — bool and BigInt are incompatible\nparse_bigint(1) == true\n\n// ✅ Express the intent explicitly with a BigInt comparison\nparse_bigint(1) != parse_bigint(0)   // \"is non-zero?\"\n```\n\n## Bridging Rust and Rhai\n\nIf you are writing a host application and need to inject a `BigInt` into a script's Scope, you can use the `Dynamic` wrapper:\n\n```rust\nuse rhai::{Engine, Scope, Dynamic, packages::Package};\nuse num_bigint::BigInt;\nuse rhai_bigint::BigIntPackage;\n\nlet mut engine = Engine::new();\nBigIntPackage::new().register_into_engine(\u0026mut engine);\n\nlet mut scope = Scope::new();\n\n// Inject a massive number from Rust into the Rhai scope\nlet my_rust_bigint = BigInt::parse_bytes(b\"999999999999999999999999\", 10).unwrap();\nscope.push(\"balance\", Dynamic::from(my_rust_bigint));\n\n// The script can interact with it natively\nlet script = \"balance \u003e parse_bigint(100)\";\nlet is_rich: bool = engine.eval_with_scope(\u0026mut scope, script).unwrap();\n```\n\n## Related Crates\n\n- **[rhai-evm](https://crates.io/crates/rhai-evm)** — Complements `rhai-bigint` with EVM-specific helpers: denomination constructors (`ether()`, `gwei()`, `usdc()`), Keccak-256 hashing, EIP-55 address utilities, and lossless conversion from `alloy-primitives` types (`U256`, `I256`) into `BigInt`.\n\n## License\n\n* MIT license (http://opensource.org/licenses/MIT)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frhaiscript%2Frhai-bigint","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frhaiscript%2Frhai-bigint","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frhaiscript%2Frhai-bigint/lists"}