[A22-6] [MEDIUM] IFlowV5 rainlang example stack omits inter-type sentinels

[thedavidmeister]

Source

src/interface/IFlowV5.sol lines 104-118 (rainlang example in interface NatSpec).

This is the live-V5 instance of the defect tracked in #408 (closed because that one referenced the deprecated V4 source). The example text is duplicated verbatim in V5; the V5 NatSpec is read by integrators of the live interface.

Finding

The example illustrating a flow stack shows only one sentinel as a stack item, but a valid flow stack requires three sentinels (one terminator per token-type group). LibFlow.stackToFlow calls consumeSentinelTuples three times (lines 52-65), each consuming tuples until it hits its own sentinel. The test helper test/lib/LibStackGeneration.sol::generateFlowStack pushes a sentinel before each of the three token-type groups, totalling three sentinels.

The example as documented:

/// /* sentinel is always the same. */
/// sentinel: 0xfea74d0c9bf4a3c28f0dd0674db22a3d7f8bf259c56af19f4ac1e735b156974f,
/// /* erc1155 transfers are first, just a sentinel as there's nothing to do */
/// _: sentinel,
/// /* erc721 transfers are next, with the token id as the last value */
/// _: 0x1234 0xdeadbeef context<0 1>() 5678,
/// /* erc20 transfers are last, with the amount as the last value */
/// _: 0xf00baa context<0 1>() 0xdeadbeef 1e18;

A reader following this template would build a stack with one sentinel; consumeSentinelTuples for erc721 and erc20 would pull from whatever lies beneath rather than terminating cleanly.

Severity

MEDIUM. The example is the only concrete illustration of the required stack layout for rainlang authors against the live interface. Following it produces invalid stacks.

Fix

Rewrite the example with three sentinels mirroring LibStackGeneration.generateFlowStack. Verify the exact rainlang surface ordering against the test fixture before committing.