Consider changing STS kWh amount quantization (ceil <1 / truncate ≥1)

[bobbybol]

Status

Integrator-facing docs are already in the README (kwh quantization note) and OpenAPI (TokenRequest.kwh). This issue is about whether to improve the quantization rule for kWh top-ups — not about missing documentation.

Current behavior

Amount.generateAmountBitString() maps kwh onto 0.1 kWh steps: ceil when < 1, truncate when ≥ 1. Inherited from NectarAPI; unchanged in NXT STS. Changing it would alter token output for the same inputs.

Examples today:

Requested kwh	Effective credit
0.01	0.1 (ceil)
0.11	0.2 (ceil)
1.19	1.1 (truncate)

Candidate improvement: round to nearest 0.1

A fairer rule would be:

1. Quantize to the nearest 0.1 kWh (suggest round half up for ties, e.g. 1.15 → 1.2).
2. If the requested amount is positive but would quantize to 0, use 0.1 instead (never issue empty credit for a real top-up).

That keeps the “don’t round down to zero” protection, but stops using always-ceil below 1 kWh and always-truncate above it. Average error would be smaller and small/large purchases would be treated consistently.

Requested kwh	Current	Nearest (with min 0.1 if > 0)
0.01	0.1	0.1 (min credit)
0.11	0.2	0.1
1.19	1.1	1.2

Alternatives

• Always ceil / always truncate
• Reject requests that are not exact multiples of 0.1 (push policy to the caller)
• Leave STS as-is; pre-quantize in the backend

Any change is a deliberate compatibility break and needs product + test-vector sign-off.

Proposed default until decided

No change in released behavior. Prefer caller pre-quantization to multiples of 0.1.

If we ever change it

• Choose the new rule (nearest + min 0.1 vs reject non-multiples vs other)
• Define tie-breaking explicitly (e.g. round half up)
• Update test vectors / known tokens
• Version / communicate the break to callers
• Align existing adopters' billing with the new rule