Skip to content

Commit 191a4f4

Browse files
committed
Fix stale precision and encodeLossless references in docs
Update terminology from precision to resolution and encodeLossless to encode(value, true) across README.md, CLAUDE.md, copilot-instructions.md, and index.html to match the current API after PR #92.
1 parent bdaebb5 commit 191a4f4

File tree

4 files changed

+11
-11
lines changed

4 files changed

+11
-11
lines changed

.github/copilot-instructions.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ The core implementation is `UintQuantizationLib` in `src/UintQuantizationLib.sol
1212
- `Quant` layout is fixed: bits 0-7 = `shift`, bits 8-15 = `targetBits`.
1313
- Keep custom errors file-level with bare names (`BadConfig`, `Overflow`, `NotAligned`).
1414
- Keep fuzz constraints consistent with existing tests (`bound()` instead of `vm.assume`).
15-
- For precision-sensitive flows, prefer `encodeLossless`; for floor truncation use `encode`.
15+
- For resolution-sensitive flows, prefer `encode(value, true)`; for floor truncation use `encode`.
1616

1717
## Validation commands
1818

CLAUDE.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ forge test
2121
forge test --match-path test/UintQuantizationLib.t.sol
2222

2323
# Run a single test function
24-
forge test --match-test test_encodeLossless_notAligned_reverts
24+
forge test --match-test test_encodePrecise_notAligned_reverts
2525

2626
# Run with verbose output
2727
forge test -vv

README.md

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,7 @@ The `Quant` value type is a `uint16` with the following bit layout:
4949
| `q.shift()` | Returns the shift component (bits discarded during encoding). |
5050
| `q.targetBits()` | Returns the targetBits component (bit-width of the encoded value). |
5151
| `q.encode(value)` | Floor-encodes `value`. Reverts with `Overflow` when `value > max(q)`. |
52-
| `q.encodeLossless(value)` | Strict mode: also reverts with `NotAligned` when `value` is not step-aligned. |
52+
| `q.encode(value, true)` | Strict mode: also reverts with `NotAligned` when `value` is not step-aligned. |
5353
| `q.decode(encoded)` | Left-shifts `encoded` by shift, restoring discarded bits as zeros (lower bound). |
5454
| `q.decodeMax(encoded)` | Like `decode` but fills discarded bits with ones (upper bound within the step). |
5555
| `q.fits(value)` | Returns `true` when `value <= max(q)`. |
@@ -86,7 +86,7 @@ contract StakingVault {
8686
8787
/// Strict mode: reverts if msg.value is not step-aligned.
8888
function stakeExact() external payable {
89-
stakes[msg.sender] = uint96(SCHEME.encodeLossless(msg.value));
89+
stakes[msg.sender] = uint96(SCHEME.encode(msg.value, true));
9090
}
9191
9292
/// Restores the lower-bound value (what was actually stored).
@@ -114,7 +114,7 @@ contract StakingVault {
114114
return SCHEME.remainder(amount);
115115
}
116116
117-
/// True when `amount` is step-aligned (no precision loss).
117+
/// True when `amount` is step-aligned (no resolution loss).
118118
function isDepositLossless(uint256 amount) external pure returns (bool) {
119119
return SCHEME.isLossless(amount);
120120
}
@@ -131,18 +131,18 @@ contract StakingVault {
131131
}
132132
```
133133

134-
> `encode()` and `encodeLossless()` return `uint256` due to Solidity type constraints. The encoded
134+
> `encode(value)` and `encode(value, true)` return `uint256` due to Solidity type constraints. The encoded
135135
> result is guaranteed to fit in `2^targetBits - 1`, so store it using the matching `uintN` for
136136
> your scheme (for example, `uint16` for `targetBits=16`, `uint24` for `targetBits=24`). Using a
137137
> smaller type will silently truncate.
138138
139139
## Which encode function should I use?
140140

141-
> - `encode` — Floor encoding with overflow check. Reverts when the value exceeds `max(q)`.
142-
> - `encodeLossless` — Strict mode: reverts on overflow or when any precision would be lost.
141+
> - `encode(value)` — Floor encoding with overflow check. Reverts when the value exceeds `max(q)`.
142+
> - `encode(value, true)` — Strict mode: reverts on overflow or when any resolution would be lost.
143143
144144
Use `encode` when the caller controls or bounds the input and floor truncation is acceptable.
145-
Use `encodeLossless` when exactness is a protocol requirement (e.g., the transaction should revert
145+
Use `encode(value, true)` when exactness is a protocol requirement (e.g., the transaction should revert
146146
rather than silently truncate the value).
147147

148148
## Showcase and gas savings
@@ -162,7 +162,7 @@ state layout.
162162

163163
The staking showcase intentionally exercises the full API surface:
164164
- `stake()` uses `encode`.
165-
- `stakeExact()` uses `encodeLossless`.
165+
- `stakeExact()` uses `encode(value, true)`.
166166
- `unstake()` uses `decode`.
167167
- `maxDeposit()`, `stakeRemainder()`, and `isStakeLossless()` expose
168168
`max`, `remainder`, and `isLossless` for frontend UX.

index.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -173,7 +173,7 @@ <h2 class="section-title sr">API</h2>
173173
<div class="api-list sr" style="transition-delay:0.1s">
174174
<div class="api-item"><code class="api-fn">create(shift, targetBits)</code><span class="api-desc">Create a quantization scheme</span></div>
175175
<div class="api-item"><code class="api-fn">encode(value)</code><span class="api-desc">Floor-encode a value (reverts on overflow)</span></div>
176-
<div class="api-item"><code class="api-fn">encodeLossless(value)</code><span class="api-desc">Strict encode (reverts if value is not step-aligned)</span></div>
176+
<div class="api-item"><code class="api-fn">encode(value, true)</code><span class="api-desc">Strict encode (reverts if value is not step-aligned)</span></div>
177177
<div class="api-item"><code class="api-fn">decode(encoded)</code><span class="api-desc">Restore lower-bound value</span></div>
178178
<div class="api-item"><code class="api-fn">decodeMax(encoded)</code><span class="api-desc">Restore upper-bound value</span></div>
179179
<div class="api-item"><code class="api-fn">fits(value)</code><span class="api-desc">Check if value is representable</span></div>

0 commit comments

Comments
 (0)