refactor(events): narrow the delta events' amount to uint120

[pviti]

All four delta events declared a uint256 amount next to uint120 balances, so a consumer decoding the tuple saw two widths for three quantities of the same kind.

No value changes, and no new cast

In capture and refund the emit now passes the uint120 local that already existed for the storage write — captureAmount120 / refundAmount120 — rather than the uint256 parameter. So no cast is introduced and the two existing safe-cast comments still carry the justification.

void and release were already emitting a uint120 local that only the event signature widened back to uint256, which is the clearest sign the declaration was what was off.

BREAKING — topic0 changes on all four

PaymentCaptured  0x460e11c3… → 0x77b933fc…
PaymentVoided    0xe60803c7… → 0xb37b3ce4…
PaymentReleased  0xaf7a769d… → 0x90204216…
PaymentRefunded  0xaa05bfb9… → 0xe53d95a7…

Must not deploy alone. It needs a VERSION bump, the coordinated rollout, and a full reindex.

Bundle it with #53 (the minimum refund window), which is also breaking and also unmerged: one bump covers both, and shipping them together avoids two reindexes. VERSION is deliberately left at 1.3.0 here, as in #53 — bumping it is a release decision across six live deployments, not a code change to slip in.

Companion indexer change: commercelayer/rail0-indexer#78.

Gas

+18 on capture (178,347 → 178,365), from reading the local rather than the parameter. Note a uint120 still occupies a full word in event data, so nothing is saved there either — this is consistency, not optimisation. Reporting it rather than claiming "no change".

What the tests proved

The four events are re-declared locally in RAIL0.t.sol for vm.expectEmit, and all four event tests failed until those declarations were narrowed too. That is the clearest local evidence topic0 moved — and it is now noted in the test file so the next reader sees what those declarations are actually guarding.

The indexer's config.events.test.ts then caught the same thing across repos: it compares config.yaml against the compiled contract ABI from the sibling checkout, and failed with the old selector until the contract was rebuilt. Worth knowing that guard works.

Suite: 120 tests pass. forge fmt --check clean.

Closes #47

🤖 Generated with Claude Code

[pviti]

Gas, measured properly this time

The PR body says "+18 on capture, from reading the local rather than the parameter". The number was right; the explanation was too broad. Full picture, measured against a clean main worktree rather than a hand-reverted tree:

operation	main	this branch	Δ
capture	178,347	178,365	+18
refund	204,193	204,214	+21
void	137,247	137,247	0
release	135,647	135,647	0

Deployed bytecode: 7,212 → 7,221 bytes (+9).

Why it splits that way

The two halves of the change have opposite gas profiles, which is the part the original note flattened:

• void and release cost nothing. Their emit already passed a uint120 local — the event signature was merely widening it back to uint256. Narrowing the declaration removes that widening, so it nets to zero. These two were pure declaration noise.
• capture and refund cost +18 / +21. Their emit previously passed the uint256 parameter straight through, which needs no preparation because a full word is already canonical. It now passes the narrowed uint120 local, whose upper bits must be cleaned before ABI-encoding into the event data. That cleanup is the +9 bytes of code and the extra gas.

An inline uint120(amount) cast at the emit instead of the local measures identically, so this is the narrow type's encoding, not the local's lifetime.

A methodology note, since it nearly published a wrong number

An intermediate measurement gave a 178,212 baseline and an apparent +153. That was an artefact: reverting the change by hand left a mixed state (one emit reverted, the other not), and the optimizer's output shifted enough to move capture's gas by ~135 even though nothing in capture differed. The clean-worktree numbers above are the authoritative ones — and worth knowing generally for this contract: partial hand-reverts do not give a usable gas baseline here.

Verdict

+18 and +21 on two of eight entrypoints, 0.01% each. Not a reason to reconsider the change, and not an optimisation either — the same conclusion as before, now with the numbers behind it.

[pviti]

Closed — measured, this makes gas worse, and the defect is cosmetic

Recording the decision here since the PR was closed without it.

entrypoint	main	with this PR	Δ
capture	178,347	178,365	+18
refund	204,193	204,214	+21
void	137,247	137,247	0
release	135,647	135,647	0

Plus 9 bytes of bytecode.

Narrowing an event's amount cannot save anything. In an event's data blob every argument occupies a full 32-byte word whatever its declared type, so there is nothing to reclaim. The narrow type only adds the upper-bit cleanup when the value arrives as a uint256 — which is precisely why void and release cost nothing (they already emitted a uint120 local) while capture and refund pay for it.

So the trade is 18–21 gas against ABI self-consistency, and #47 called the inconsistency cosmetic in its own title. Not worth a cost on two of the six fund-moving entrypoints.

Worth contrasting with #55, where the transient-storage lock saves ~2,000 gas on all six: there gas and code quality pointed the same way; here they oppose and gas wins.

Issue #47 is closed as won't-do with the same reasoning. commercelayer/rail0-indexer#78 is closed with it — without the contract change its golden signatures would be wrong. The branch stays, so the change is trivial to revive from this diff if the decision ever flips.