From becc399cad758ee8613114d2d8a34fdc78107700 Mon Sep 17 00:00:00 2001 From: Kaan Kacar Date: Wed, 9 Sep 2026 04:06:55 +0000 Subject: [PATCH 1/3] State the pool share trustline two-reserve exception on the Lumens and Accounts pages A pool share trustline counts as two subentries and needs two base reserves. The Liquidity Pools page says so, but the general Lumens and Accounts pages grouped pool shares with ordinary trustlines, so a reader sizing a minimum balance from those pages undercounts by one reserve. CAP-0038 specifies the rule, and stellar-core implements it in computeMultiplier (SponsorshipUtils.cpp) and calculateDelta (AccountSubEntriesCountIsValid.cpp), which also confirms the entry counts twice toward the 1,000 subentry cap. --- docs/learn/fundamentals/lumens.mdx | 2 +- docs/learn/fundamentals/stellar-data-structures/accounts.mdx | 5 ++++- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/learn/fundamentals/lumens.mdx b/docs/learn/fundamentals/lumens.mdx index 2b1c367995..a4b825ae22 100644 --- a/docs/learn/fundamentals/lumens.mdx +++ b/docs/learn/fundamentals/lumens.mdx @@ -27,7 +27,7 @@ Validators can vote to change the base reserve, but that’s uncommon and should ## Minimum balance -Stellar accounts must maintain a minimum balance to exist, which is calculated using the base reserve. An account must always maintain a minimum balance of two base reserves (currently 1 XLM). Every subentry after that requires an additional base reserve (currently 0.5 XLM) and increases the account’s minimum balance. Subentries include trustlines (for both traditional assets and pool shares), offers, signers, and data entries. An account cannot have more than 1,000 subentries. +Stellar accounts must maintain a minimum balance to exist, which is calculated using the base reserve. An account must always maintain a minimum balance of two base reserves (currently 1 XLM). Every subentry after that requires an additional base reserve (currently 0.5 XLM) and increases the account’s minimum balance. Subentries include trustlines (for both traditional assets and pool shares), offers, signers, and data entries. A pool share trustline is the one exception: it counts as two subentries, so it requires two base reserves (currently 1 XLM) instead of one. Learn more in the [Liquidity Pools section](./liquidity-on-stellar-sdex-liquidity-pools.mdx#trustlines). An account cannot have more than 1,000 subentries. Data also lives on the ledger as ledger entries. Ledger entries include claimable balances (which require a base reserve per claimant) and liquidity pool deposits and withdrawals. diff --git a/docs/learn/fundamentals/stellar-data-structures/accounts.mdx b/docs/learn/fundamentals/stellar-data-structures/accounts.mdx index d8eca575c0..c2328badc3 100644 --- a/docs/learn/fundamentals/stellar-data-structures/accounts.mdx +++ b/docs/learn/fundamentals/stellar-data-structures/accounts.mdx @@ -43,11 +43,14 @@ A base reserve is a unit of measurement used to calculate an account’s minimum Account data is stored in subentries, each of which increases an account’s minimum balance by one base reserve (0.5 XLM). An account cannot have more than 1,000 subentries. Possible subentries are: -- Trustlines (includes traditional assets and pool shares) +- Trustlines for traditional assets (one subentry each) +- Trustlines for pool shares (two subentries each) - Offers - Additional signers - Data entries (includes data made with the `manageData` operation, not smart contract ledger entries) +A pool share trustline is the one exception to the rule above: it counts as two subentries, so it requires two base reserves (currently 1 XLM) and it counts twice toward the 1,000 subentry limit. Learn more in the [Liquidity Pools section](../liquidity-on-stellar-sdex-liquidity-pools.mdx#trustlines). + ## Trustlines Trustlines are an explicit opt-in for an account to hold a particular asset. To hold a specific asset, an account must establish a trustline with the issuing account using the [`change_trust` operation](../transactions/list-of-operations.mdx#change-trust). Trustlines track the balance of an asset and can also limit the amount of an asset that an account can hold. From 1e67426a49b7152f45c6ee559e964fc2f0cda1d9 Mon Sep 17 00:00:00 2001 From: Kaan Kacar Date: Wed, 9 Sep 2026 04:10:23 +0000 Subject: [PATCH 2/3] Correct the claimable balance reserve in the minimum balance example A claimable balance with one claimant costs one base reserve, which is 0.5 XLM, not 1 XLM. The claimable-balances guide states the rule ('each claimant in that entry increases the source account's minimum balance by one base reserve') and stellar-core computeMultiplier returns claimants.size() for a CLAIMABLE_BALANCE entry. The example total is therefore 3 XLM. --- docs/learn/fundamentals/lumens.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/learn/fundamentals/lumens.mdx b/docs/learn/fundamentals/lumens.mdx index a4b825ae22..157d6f2d22 100644 --- a/docs/learn/fundamentals/lumens.mdx +++ b/docs/learn/fundamentals/lumens.mdx @@ -33,7 +33,7 @@ Data also lives on the ledger as ledger entries. Ledger entries include claimabl For example, an account with one trustline, two offers, and a claimable balance with one claimant has a minimum balance of: -2 base reserves (1 XLM) + 3 subentries/base reserves (1.5 XLM) + 1 ledger entry/base reserve (1 XLM) = 3.5 XLM +2 base reserves (1 XLM) + 3 subentries/base reserves (1.5 XLM) + 1 claimant/base reserve (0.5 XLM) = 3 XLM Minimum balance is not the same as the balance an account can spend. Selling liabilities (the amount an account has committed to open sell offers) are not part of the minimum balance. They reduce the balance available above it: `available balance` = `balance` - `minimum balance` - `liabilities.selling`. From 581b884e20f3ec7e39f9fac64539ff1922d93f6d Mon Sep 17 00:00:00 2001 From: kalepail Date: Wed, 16 Sep 2026 17:42:49 -0400 Subject: [PATCH 3/3] docs: clarify pool-share subentry counting --- docs/learn/fundamentals/lumens.mdx | 2 +- docs/learn/fundamentals/stellar-data-structures/accounts.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/learn/fundamentals/lumens.mdx b/docs/learn/fundamentals/lumens.mdx index 157d6f2d22..cfd9e960e1 100644 --- a/docs/learn/fundamentals/lumens.mdx +++ b/docs/learn/fundamentals/lumens.mdx @@ -27,7 +27,7 @@ Validators can vote to change the base reserve, but that’s uncommon and should ## Minimum balance -Stellar accounts must maintain a minimum balance to exist, which is calculated using the base reserve. An account must always maintain a minimum balance of two base reserves (currently 1 XLM). Every subentry after that requires an additional base reserve (currently 0.5 XLM) and increases the account’s minimum balance. Subentries include trustlines (for both traditional assets and pool shares), offers, signers, and data entries. A pool share trustline is the one exception: it counts as two subentries, so it requires two base reserves (currently 1 XLM) instead of one. Learn more in the [Liquidity Pools section](./liquidity-on-stellar-sdex-liquidity-pools.mdx#trustlines). An account cannot have more than 1,000 subentries. +Stellar accounts must maintain a minimum balance to exist, which is calculated using the base reserve. An account must always maintain a minimum balance of two base reserves (currently 1 XLM). Every subentry after that requires an additional base reserve (currently 0.5 XLM) and increases the account’s minimum balance. Subentries include trustlines, offers, signers, and data entries, and an account cannot have more than 1,000 of them. Each counts as one subentry, except a trustline for a pool share, which counts as two and so requires two base reserves (currently 1 XLM). Learn more in the [Liquidity Pools section](./liquidity-on-stellar-sdex-liquidity-pools.mdx#trustlines). Data also lives on the ledger as ledger entries. Ledger entries include claimable balances (which require a base reserve per claimant) and liquidity pool deposits and withdrawals. diff --git a/docs/learn/fundamentals/stellar-data-structures/accounts.mdx b/docs/learn/fundamentals/stellar-data-structures/accounts.mdx index c2328badc3..f526ffeb88 100644 --- a/docs/learn/fundamentals/stellar-data-structures/accounts.mdx +++ b/docs/learn/fundamentals/stellar-data-structures/accounts.mdx @@ -49,7 +49,7 @@ Account data is stored in subentries, each of which increases an account’s min - Additional signers - Data entries (includes data made with the `manageData` operation, not smart contract ledger entries) -A pool share trustline is the one exception to the rule above: it counts as two subentries, so it requires two base reserves (currently 1 XLM) and it counts twice toward the 1,000 subentry limit. Learn more in the [Liquidity Pools section](../liquidity-on-stellar-sdex-liquidity-pools.mdx#trustlines). +A pool share trustline therefore requires two base reserves (currently 1 XLM) and uses two of the account’s 1,000 subentries. Learn more in the [Liquidity Pools section](../liquidity-on-stellar-sdex-liquidity-pools.mdx#trustlines). ## Trustlines