You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
docs: refine planner with domain-driven inputs and ETH supply walkthrough
- Change first input from bit width to domain max value (user knows
their cap/supply, not the bit count)
- Derive field width from domain max (log2 -> byte boundary)
- Add intro walkthrough using ETH total supply as the single example
- Fix input validation: mutual constraints via HTML min/max, byte-aligned
discarded bits (step=8), field width can't drop below discarded+8
- Add hex notation throughout (inputs, results)
- Prompt is now a template question for AI to derive the scheme,
not a pre-computed answer
- Fix per-slot to use Solidity type width, not raw encoded bits
- Warn when max representable < field max (Overflow gap)
<p>Say you are building a staking contract and need to store ETH balances. ETH has 18 decimals, so 1 ETH = 10<sup>18</sup> wei. Where do you start?</p>
152
+
<ol>
153
+
<li><strong>What is the largest value I will ever store?</strong> The total ETH supply is ~120M ETH = 1.2 × 10<sup>26</sup> wei. No single balance can exceed that, so it is a safe domain max. If the field is an accumulator (e.g., total staked across all users), estimate the worst-case accumulated total instead.</li>
154
+
<li><strong>How many bits does that need?</strong> log<sub>2</sub>(1.2 × 10<sup>26</sup>) ≈ 86.6, so 87 bits minimum. Next byte boundary: <code>uint88</code>.</li>
155
+
<li><strong>How much resolution can I sacrifice?</strong> Do you need wei-level resolution? Probably not for staking. If you accept rounding to the nearest 65,536 wei (2<sup>16</sup>), that is roughly 0.000000000000065 ETH: invisible to any user. So discarding 16 bits is safe.</li>
156
+
<li><strong>What is the result?</strong> With <code>uint88</code> and 16 discarded bits: 88 − 16 = 72 encoded bits, stored as <code>uint72</code>. The call is <code>create(16, 72)</code>.</li>
157
+
<li><strong>What do I lose?</strong> Max error per value is 2<sup>16</sup> − 1 = 65,535 wei ≈ 0.000000000000065 ETH. Values within 65,535 of <code>uint88.max</code> will revert with <code>Overflow</code>. Both are negligible for ETH staking. If you want zero error, enforce step-aligned inputs: the library provides <code>requireAligned()</code> and <code>encode(value, true)</code> which revert on non-aligned values, guaranteeing lossless round-trips.</li>
158
+
</ol>
159
+
<p>Enter your domain max below to run this reasoning for your own field.</p>
promptText.textContent=`Field with domain max ${fmt(maxVal)} and acceptable step ${fmt(resolution)}: use create(${r.d}, ${r.e}). Stores in ${r.uintType} (down from ${r.nativeType}). Step size ${fmt(r.step)} (2^${r.d}), max representable ${fmt(r.actualMax)}, worst-case error ${fmt(r.maxError)} per value. ${r.perSlot} value${r.perSlot===1 ? '' : 's'} per uint256 slot.`;
354
+
letp=`I'm building a Solidity contract that stores __________ (describe your field: e.g., ETH staking balances, token amounts, timestamps).\n\n`;
355
+
p+=`Using uint-quantization-lib (https://github.com/0xferit/uint-quantization-lib), help me:\n`;
356
+
p+=`1. Determine the domain max for this field (contract cap, supply bound, or worst-case accumulation)\n`;
357
+
p+=`2. Derive the minimum bit width and native Solidity type\n`;
358
+
p+=`3. Decide how many bits of resolution to discard and justify the tradeoff\n`;
359
+
p+=`4. Compute the quantization scheme: create(discardedBitWidth, encodedBitWidth)\n`;
360
+
p+=`5. Show the Solidity integration code with encode/decode calls`;
0 commit comments