N-03: Incomplete Documentation For Native Token Supply Wrappers

N-05 Incomplete Documentation For Native Token Supply Wrappers

Severity: Note

Source: Midnight Foundation #02 — OpenZeppelin Compact Contracts Audit, Release 0.3.0-alpha.1 (2026-08-18)

Both supply wrappers, NativeShieldedTokenFamilyPublicSupply and NativeShieldedTokenPublicSupply, import and re-export the same two core maps. Ledger state is allocated once per module, so a contract composing both would receive a single pair. The single-token flavour keys its bucket to the unreserved all-zero Bytes<32>, while the per-domain flavour forwards an arbitrary caller domain. As a result, both wrappers would address the same entry, and the burn guard would stop binding per token type. That composition is already prohibited where it originates. Both token flavours state that a contract must not import both for the same reason, and a supply wrapper is useful only alongside its token flavour. Every exported circuit of the two wrappers also shares a name with its counterpart at a different arity, so a dual import cannot be written unprefixed. The residual gap is documentary.

Consider recording in both supply wrappers that they share one set of core ledgers and that only one may be composed, matching the notice the token flavours carry. Deriving the single-token bucket from a fixed tag would not remove the condition, since the per-domain wrapper accepts any caller-supplied domain and no value can be reserved against it.

Start with the two supply-wrapper definitions and compare their guidance with NativeShieldedTokenPublicSupplyCore.compact and NativeShieldedToken.compact. Update both wrappers to document their shared core ledgers and the rule that only one may be composed; the documentation is done when it matches the token-flavour notice.