[Developer Utilities] Offer Liability and Capacity Audit

[egekoca]

Goal

Inspect an account's current offers alongside balance and liability fields to explain which asset obligations constrain further offers. Present a diagnostic snapshot, not a trading recommendation.

Data source: Horizon GET /accounts/{account_id} and GET /accounts/{account_id}/offers on one network.

This issue is independent of every other new-season issue. Implement it entirely in features/offer-liability-headroom/; the generated registry handles routing, search and navigation. Do not require another feature or pull request to land first.

Acceptance criteria

• Associate each offer with buying and selling asset identities.
• Show balance, selling liabilities, buying liabilities and trustline limit separately.
• Use exact rational price and amount arithmetic when deriving a display estimate.
• Explain when an offer has no matching current balance row or when the two reads are from different ledgers.
• Never imply that a displayed estimate guarantees execution.

At least 35 meaningful file changes

Start with npm run new:feature -- offer-liability-headroom "Offer Liability and Capacity Audit" developer. The scaffold supplies the standard 23-file shape; add the twelve task-specific files below and replace all placeholders with working behavior. Every listed file must contain relevant implementation, coverage, fixture data or documentation; empty or duplicated files do not count. A PR may change more than 35 files inside this slice when justified.

Required file	Responsibility
features/offer-liability-headroom/manifest.ts	Registry metadata and supported networks
features/offer-liability-headroom/panel.tsx	Route-mounted feature entry point
features/offer-liability-headroom/types.ts	Input, result, state and error-code types
features/offer-liability-headroom/schema.ts	Raw input validation without requests
features/offer-liability-headroom/copy.ts	All user-facing strings and actionable error text
features/offer-liability-headroom/lib/offerLiabilityHeadroom.ts	Result-based feature orchestration
features/offer-liability-headroom/lib/offerLiabilityHeadroom.errors.ts	Transport or decode failure mapping
features/offer-liability-headroom/lib/format.ts	Presentation formatting
features/offer-liability-headroom/hooks/useOfferLiabilityHeadroom.ts	Idle, loading, success and error state machine
features/offer-liability-headroom/components/OfferLiabilityHeadroomPanel.tsx	Composition of every state
features/offer-liability-headroom/components/OfferLiabilityHeadroomForm.tsx	Accessible input controls
features/offer-liability-headroom/components/OfferLiabilityHeadroomResult.tsx	Successful result overview
features/offer-liability-headroom/components/OfferLiabilityHeadroomEmptyState.tsx	Pre-interaction guidance
features/offer-liability-headroom/__tests__/offerLiabilityHeadroom.test.ts	Domain success and failure cases
features/offer-liability-headroom/__tests__/schema.test.ts	Input and boundary validation
features/offer-liability-headroom/__tests__/format.test.ts	Exact display formatting
features/offer-liability-headroom/__tests__/useOfferLiabilityHeadroom.test.tsx	State transitions and network changes
features/offer-liability-headroom/__tests__/OfferLiabilityHeadroomPanel.test.tsx	Rendered behavior
features/offer-liability-headroom/__tests__/a11y.test.tsx	WCAG 2.1 A/AA in at least two states
features/offer-liability-headroom/fixtures/offerLiabilityHeadroom.fixture.ts	Deterministic normal-case data
features/offer-liability-headroom/msw/handlers.ts	Network fixtures, or an empty array for offline tools
features/offer-liability-headroom/e2e/offer-liability-headroom.spec.ts	Main browser journey
features/offer-liability-headroom/README.md	Behavior, data boundaries and design decisions
features/offer-liability-headroom/lib/offer-assets.ts	Normalize offer asset identities.
features/offer-liability-headroom/lib/liability-audit.ts	Associate liabilities with balances and offers.
features/offer-liability-headroom/lib/rational-price.ts	Format rational prices without float drift.
features/offer-liability-headroom/components/OfferRows.tsx	Show active offers and their assets.
features/offer-liability-headroom/components/LiabilityRows.tsx	Show balance and liability context.
features/offer-liability-headroom/components/SnapshotWarning.tsx	Explain read skew and unmatched rows.
features/offer-liability-headroom/__tests__/offer-assets.test.ts	Tests for lib/offer-assets.ts
features/offer-liability-headroom/__tests__/liability-audit.test.ts	Tests for lib/liability-audit.ts
features/offer-liability-headroom/__tests__/rational-price.test.ts	Tests for lib/rational-price.ts
features/offer-liability-headroom/fixtures/offers.fixture.ts	Deterministic edge-case fixture
features/offer-liability-headroom/fixtures/unmatched-assets.fixture.ts	Deterministic edge-case fixture
features/offer-liability-headroom/e2e/unmatched-offer.spec.ts	Distinct edge-case browser journey

Error outcomes

• invalid_account: map to specific, actionable copy and cover with a test
• account_not_found: map to specific, actionable copy and cover with a test
• malformed_offer: map to specific, actionable copy and cover with a test
• inconsistent_snapshot: map to specific, actionable copy and cover with a test
• rate_limited: map to specific, actionable copy and cover with a test
• request_failed: map to specific, actionable copy and cover with a test

Shared quality bar

• Use Result<T, Code> for expected failures; keep all user-facing copy in copy.ts.
• Cover idle, loading, success and error states. For fully offline tools, loading may be a brief local-processing state.
• Use strings and BigInt for Stellar amounts; never accept, display, store or transmit secret keys.
• Derive valid Stellar addresses from fixed seeds in fixtures; mock requests with MSW.
• Test normal, boundary, malformed-input and transport cases where applicable, plus at least two accessibility states.
• Pass npm run check and npm run verify:features -- offer-liability-headroom.
• Keep the pull request inside features/offer-liability-headroom/.

Implementation note: Offer price is rational in ledger data; converting it to a JavaScript float can distort a capacity explanation.

Reference slice: features/liquidity-pool-inspector; also read the feature contract.

Out of scope

• No offer creation, cancellation or trading action.
• No market price prediction.

[Richkid2]

@Richkid2 has applied to work on this issue as part of the Stellar Wave Program's 9th wave.

Hello maintainer, i can work on this issue, please assign me.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Richkid2 to this issue.

[DeFex-lab]

@DeFex-lab has applied to work on this issue as part of the Stellar Wave Program's 9th wave.

Hi Maintainer, I’d like to take on this issue. I have relevant experience and can get started immediately.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @DeFex-lab to this issue.

[codetamer]

@codetamer has applied to work on this issue as part of the Stellar Wave Program's 9th wave.

Hi good maintainer! I would love to work on this issue, please assign me. Ready to submit a clean PR with passing tests right away!

ℹ️ Repo Maintainers: To accept this application, review their application or assign @codetamer to this issue.

[DanielTobiDev]

@DanielTobiDev has applied to work on this issue as part of the Stellar Wave Program's 9th wave.

Good morning maintainer. Kindly assign this issue for me.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @DanielTobiDev to this issue.

[Caneryy]

@Caneryy has applied to work on this issue as part of the Stellar Wave Program's 9th wave.

Can I work on this issue

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Caneryy to this issue.

[drips-wave]

Congratulations, @Caneryy! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on September 30, 2026.

🧑‍💻 @Caneryy: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox!

@Caneryy's PR #493 was approved and merged by @egekoca.

🏆 @Caneryy: You earned 40 FoxPoints for this contribution! Your current tier: Builder (1,822 total points). Track your full progress on GrantFox.

👏 Great work, @Caneryy! Keep contributing to RevenantLabs.