Skip to content

State the pool share trustline two-reserve exception on the Lumens and Accounts pages #2844

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
kaankacar wants to merge 2 commits into
base: main
Choose a base branch
from
+6 −3
Open

State the pool share trustline two-reserve exception on the Lumens and Accounts pages #2844

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
becc399
State the pool share trustline two-reserve exception on the Lumens an…
kaankacar Sep 9, 2026
1e67426
Correct the claimable balance reserve in the minimum balance example
kaankacar Sep 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/learn/fundamentals/lumens.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,13 +27,13 @@ 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.

@ElliotFriend ElliotFriend Sep 15, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreeing with Copilot here. "The one exception" has no antecedent in this paragraph, because nothing before it establishes that a trustline normally counts as one subentry. The parenthetical "(for both traditional assets and pool shares)" also ends up fighting the sentence that immediately qualifies it.

This version states the counting rule directly, folds the 1,000 cap in ahead of it so that "counts as two" implies two against the cap without repeating the number, and drops the now redundant parenthetical since the following clause names pool shares anyway.

It also picks up the point Copilot raised and then suppressed, that this page states the cap but never said a pool share trustline consumes two of it.

Suggested change
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.

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`.

Expand Down
5 changes: 4 additions & 1 deletion docs/learn/fundamentals/stellar-data-structures/accounts.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).

@ElliotFriend ElliotFriend Sep 15, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot's point here is sharper than it reads. The nearest "rule above" is the bullet list, which this PR just edited to say "(two subentries each)", so the sentence announces an exception to a rule that already contains the exception. And read against the lead-in ("each of which increases an account’s minimum balance by one base reserve"), a pool share trustline is not an exception at all. It obeys that rule and simply is two subentries.

Since the bullets now carry the count, this paragraph only needs to carry the consequence:

Suggested change
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

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.
Expand Down
Loading