# Blockulator

> FP127: signed 127.128 fixed-point math for the EVM, about 38 decimal
> digits in one int256 against 18 for the usual WAD libraries, deployed as
> one callable contract on Ethereum Sepolia and available as an inlinable
> Solidity library. Every op is a read-only eth_call: no gas, no wallet, no
> transaction. Agents get results more precise than a double by calling it.

## What it is

- 38 operations: add, sub, mul, div, fromFixed18, toFixed18, exp, exp2,
  exp10, ln, log2, log10, log2Up, sqrt, cbrt, pow, gavg, hypot, inv, abs,
  neg, sign, min, max, clamp, avg, zeroFloorSub, dist, lerp, floor, ceil,
  frac, round, gcd, factorial, lambertW0, lambertWm1, pi (Ramanujan's
  series, pi(terms): five terms reach the format's floor).
- Encoding: every operand and result is an int256 holding value * 2**128.
  Decode by dividing by 2**128. Range about +/- 1.7e38.
- Checked arithmetic: out-of-domain inputs revert with Overflow(),
  DivisionByZero() or OutOfRange(). Nothing wraps.
- Validated against mpmath at 200 decimal places: integer and rounding
  ops bit-exact; ln, log2 and log10 within one ULP; exp, exp2 and exp10
  146 bits or better. The transcendentals round to nearest with 64 guard
  bits, so iterated calls do not drift.
  /data/precision.json
- Machine-readable op table (signature, selector, domain, reverts):
  /data/ops.json

## How to call it

- Network: Ethereum Sepolia, chainId 11155111
- RPC: https://ethereum-sepolia-rpc.publicnode.com
- FP127: 0xe43F720861074497db2e974E5c4554E4A3b341B9 (CREATE2 through
  0x4e59b44847b379578588920cA78FbF26c0B4956C, salt "FP127 v3"; record at
  /contracts/deployments/FP127.md and /data/fp127.json)
- ABI: /data/abi.json. All functions are pure; selectors are in /data/ops.json.
- Example: sqrt(2) is `sqrt(int256)` with 2 * 2**128 =
  680564733841876926926749214863536422912; the result divided by 2**128 is
  1.41421356...
- Inline form: contracts/src/fp127/FP127Lib.sol in the repository,
  `forge install securedataresearch/blockulator`, remapping
  fp127/=lib/blockulator/contracts/src/fp127/.
- Manifest with the same data: /.well-known/agent.json

## The precision claim, as data

- /data/ladder.json: nine iterated scenarios (daily compounding, an
  amortising loan, exp(ln(x)) round trips, ...), 64 inputs in all, through
  FP127, FP127Lib, ABDKMath64x64, Solady and PRBMath for N in 1..10000.
  Every cell carries the decoded value, correct significant digits against
  the exact truth (digits) and against the truth from the parameters as the
  library received them (digitsFormat, the arithmetic alone), the signed
  error in ULPs, and gas per step; summaries give median and range over the
  inputs; the methodology key says how each number is defined. Daily
  compounding, reference input, N = 365: FP127 36 digits (40 against the
  format truth), Solady and PRBMath 16, ABDK 17.
- Any cell can be re-run on chain: LadderRunner at
  0x798C37A3E5B421D480AC850258466b5598A1A555 (salt "FP127 ladder v4"),
  run(uint8 scenario, uint8 form, uint32 n, int256[] p) returns (bool ok,
  int256 raw, bytes4 reason, uint256 gasPerStep, uint256 gasTotal), with p
  the input's floored parameters from /data/ladder-inputs.json. Scenario
  ids are in /data/scenarios.json; the record is
  /contracts/deployments/Ladder.md.
- /data/gas.json: gas per op and form, min/median/max.

## Pages

- /demo/ the ladder, /why/ the mechanism, /library/ address, ABI and
  the op table, /compare/ gas and precision per op, /writeup/ the story.

## Documentation

- FP127 README: https://github.com/securedataresearch/blockulator/blob/master/contracts/src/fp127/README.md
- Source: https://github.com/securedataresearch/blockulator
- EthCC[9] talk: https://www.youtube.com/watch?v=a_tL99NY-yc

## Notes for agents

- Reads are free and need no key; do not send transactions for math.
- Sepolia only today; there is no mainnet address yet.
- The Vyper calculators listed in /.well-known/agent.json with
  "status": "archived", and the games and futures market on /archive/,
  still run but call the legacy Huff FP127 and are not maintained. Use the
  FP127 contract above.