Hubble data dictionary: num_subentries description and minimum balance formula are both incorrect

[ElliotFriend]

The Hubble data dictionary describes num_subentries in two places, and both descriptions are out of step with how stellar-core actually computes subentries and minimum balance. Found while reviewing #2844, which fixes the same pool share trustline error on the Lumens and Accounts fundamentals pages.

Affected files:

• docs/data/analytics/hubble/data-catalog/data-dictionary/bronze/accounts.mdx (line 27)
• docs/data/analytics/hubble/data-catalog/data-dictionary/silver/accounts-snapshot.mdx (line 27)

1. Pool share trustlines add 2, not 1

The bronze page says:

Any newly created trustline, offer, signer or data entry will increase the number of subentries by 1.

That is wrong for pool share trustlines, which add 2. CAP-0038 states it directly: "The pool share trust line should count as two subentries (and therefore require two base reserves)." In stellar-core, computeMultiplier in SponsorshipUtils.cpp returns 2 for an ASSET_TYPE_POOL_SHARE trustline and 1 for every other trustline, and that multiplier is what gets added to numSubEntries.

This matters more here than on a conceptual page, because anyone writing a query against num_subentries and back-computing a trustline count from it will be off by one for every pool share trustline in the set.

2. The minimum balance formula has both sponsorship signs inverted

Both pages give the reserve calculation as:

(2 + num_subentries - num_sponsoring + num_sponsored) * 0.5XLM

The signs on num_sponsoring and num_sponsored are backwards. From getMinBalance in stellar-core src/transactions/TransactionUtils.cpp:

effEntries += numSponsoring;
effEntries -= numSponsored;

So the correct formula is:

(2 + num_subentries + num_sponsoring - num_sponsored) * base_reserve

This is also what our own Sponsored Reserves guide already says, so the two pages currently contradict it. The logic check is in that same guide: when A sponsors an entry for B, B's num_subentries goes up and B's num_sponsored goes up, and those are supposed to cancel so B's minimum balance is unchanged. They only cancel if num_sponsored is subtracted.

As written, the formula inverts the entire point of sponsorship: it reports that sponsoring entries for other accounts lowers your minimum balance, and that being sponsored raises it.

Suggested fix

• Amend the bronze num_subentries description to note that a pool share trustline increases the count by 2 while other trustlines, offers, signers, and data entries increase it by 1.
• Correct the sign on num_sponsoring and num_sponsored in both formulas.
• Consider writing base_reserve instead of the hardcoded 0.5XLM, since validators can vote to change it, or at least hedging it as "currently 0.5 XLM" the way the fundamentals pages do.

The silver page's num_subentries description is vaguer ("The total number of ledger entries connected to this account") and is not strictly wrong on point 1, but it is worth bringing in line with bronze while the formula is being fixed.

[kaankacar]

🤖 Automated message from Kaan's Automated Triage Bot.

No maintainer assigned this issue, so I did not work it.

Assign @kaankacar, @ElliotFriend or @wmendes if you want me to open a PR for it.