System Requirements Document for solana-refund

1. Introduction

solana-refund is a first-party web application that helps Solana wallet holders and rugpull victims detect failed Solana transactions tied to their account and claim back recoverable SOL — the fees and rent locked up in failed transactions, and SOL recoverable from rugpull-affected assets backed by Solana.

The product intent, derived from the authoritative requirement thread, is twofold:

1. Failed-transaction recovery. A wallet holder scans a Solana account's on-chain history, the system detects failed transactions tied to that account, surfaces the recoverable SOL (fees/rent) those failures left behind, and lets the holder initiate a claim/withdrawal that returns that SOL to the account owner.
2. Rugpull asset recovery. A holder of a rugpull-affected asset backed by Solana locates the recoverable SOL associated with that asset position and claims it back.

The audience is everyday Solana wallet holders who have experienced failed transactions or drained accounts, and holders of rugpull-affected assets backed by Solana. They arrive anxious and uncertain about a confusing financial situation, and the product is designed to read as a calm, trustworthy guide rather than a cold blockchain dashboard.

2. System Overview

solana-refund is delivered as a custom first-party web application with application-owned identity and a supporting backend that performs on-chain scanning, recoverable-SOL accounting, and claim execution against Solana.

Actors

• Solana Wallet Holder (human persona) — scans an account's on-chain history for failed transactions and claims back recoverable SOL.
• Rugpull Victim / Asset Holder (human persona) — locates recoverable SOL tied to rugpull-affected asset positions and claims it back.
• Solana network / RPC providers (non-persona external systems) — supply on-chain transaction history and process claim/withdrawal transactions.
• solana-refund backend (non-persona system) — performs scanning, computes recoverable amounts, and submits claim transactions.

Accepted behavior

• Detection of failed Solana transactions tied to an account.
• Claim back / recovery of SOL (fees/rent) from failed transactions in an account.
• Support for Solana wallet holders as the primary user.
• Claiming back rugpull assets backed by Solana.
• Self-service enrollment for first-time wallet holders and rugpull victims.
• Returning verification for wallet holders and rugpull victims.

Ownership and access

The application owns identity. Anonymous visitors reach the Landing page and the Sign Up and Login access surfaces. Scan, Recoverable SOL, Claim, and Rugpull Recovery are protected destinations available after identity is established.

Narrow exclusions

This document does not add trading, swapping, token issuance, portfolio management, staking, NFT marketplaces, social features, or any capability beyond detecting failed transactions and claiming back recoverable SOL. No provider-owned or external-only surface is introduced; all accepted human-facing work is owned by first-party pages.

2a. Product Interpretation and Delivery Boundary

solana-refund is a current, first-party, application-owned product. Every accepted human-facing capability — scanning, reviewing recoverable SOL, claiming, and rugpull recovery — is delivered through custom pages owned by this application, backed by a backend that talks to the Solana network.

Identity and access. Because recovery state is durable and must remain bound to the correct wallet holder (a claim moves value to a specific owner, and a scan result must be resumable and revisitable), the application establishes its own identity. First-time users enroll through Sign Up; returning users verify through Login. Both access surfaces are anonymously reachable, since a protected destination cannot own the interaction that establishes access to itself. The Landing page is the anonymous public entry. Scan, Recoverable SOL, Claim, and Rugpull Recovery require an established identity.

Current vs. future. All requirements in this document are current. No future-horizon capabilities are accepted; nothing in this document should be read as committing to adjacent blockchain tooling, multi-chain support, or account-management features beyond enrollment and returning verification.

Provider and external boundaries. Solana RPC providers and the Solana network are external systems that supply on-chain history and process claim transactions. They are not product surfaces and own no human-facing interaction.

2b. Source Content Inventory

Not applicable. No reference directive in this project declares a content_source, so no source content inventory is produced.

2c. Page Content and Component Coverage

Landing

• Information / state. Anonymous public entry. Explains, in plain language, that the product detects failed Solana transactions tied to an account and helps wallet holders and rugpull victims recover SOL. Presents the two accepted recovery paths (failed-transaction recovery and rugpull asset recovery) as an editorial sequence of illustrated section openers.
• Primary action. A single rust-orange CTA leading to Sign Up.
• Supporting actions. A secondary text link to Login for returning users.
• Domain entities. None persisted; the page is explanatory only.
• Component responsibilities. Oversized Literata headline spanning the viewport in 3–4 flush-left lines; hand-drawn wallet illustration bleeding off the right edge on desktop and stacking below on mobile; illustrated section openers (key, shield, coin) each paired with a short serif subhead; simple cream top bar with Literata wordmark left and one rust-orange CTA right.
• States. Loading: not applicable (static content). Empty: not applicable. Success: not applicable. Error: not applicable. Recovery: not applicable.

Sign Up

• Information / state. Anonymous self-service enrollment for first-time wallet holders and rugpull victims. Collects the minimum identity information needed to establish an application-owned identity bound to the user's recovery state.
• Primary action. Submit enrollment to create the identity.
• Supporting actions. Link to Login for users who already have an identity.
• Domain entities. User identity (application-owned), associated Solana wallet address.
• Component responsibilities. Single-column form (max 720px reading measure); labeled inputs; inline validation messaging; submit button with the warm rounded-rectangle treatment; link to Login.
• States. Loading: submit button shows a pending state while enrollment is processed. Empty: form fields start empty with placeholder guidance. Success: identity created and the user is taken to Scan. Error: invalid or incomplete input is reported inline next to the offending field; a failed enrollment attempt reports a recoverable error and preserves entered values. Recovery: the user can correct input and resubmit without losing progress.

Login

• Information / state. Anonymous returning verification for wallet holders and rugpull victims who already control durable recovery state.
• Primary action. Submit credentials to verify identity and resume the user's recovery state.
• Supporting actions. Link to Sign Up for users without an identity.
• Domain entities. User identity (application-owned).
• Component responsibilities. Single-column form; labeled inputs; inline validation messaging; submit button; link to Sign Up.
• States. Loading: submit button shows a pending state during verification. Empty: form fields start empty. Success: identity verified and the user is taken to Scan. Error: incorrect credentials report a recoverable error without discarding the entered identifier. Recovery: the user can retry, or follow the link to Sign Up.

Scan

• Information / state. Protected. Owns scanning a Solana account's on-chain history to detect failed transactions tied to that account. Shows the account being scanned, scan progress, and the resulting set of detected failed transactions.
• Primary action. Initiate a scan of the account's on-chain history.
• Supporting actions. Re-run a scan; open a detected failed transaction's detail; continue to Recoverable SOL.
• Domain entities. Solana account, on-chain transaction history, failed transaction records, scan run.
• Component responsibilities. Account identifier display; scan trigger control; progress indicator during scanning; result list of detected failed transactions with tabular alignment and warm rules; per-transaction detail; empty-state illustration when no failed transactions are found; error panel when the scan cannot complete.
• States. Loading: progress indicator while the on-chain history is fetched and evaluated. Empty: a calm illustrated empty state explaining that no failed transactions were detected for this account, with the option to re-run the scan. Success: detected failed transactions are listed with their identifying details and the recoverable amount each contributes. Error: an RPC or network failure reports a recoverable error with a retry action; partial results are shown if some history was retrieved. Recovery: the user can retry the scan; previously detected results remain available.

Recoverable SOL

• Information / state. Protected. Presents the recoverable SOL (fees/rent) identified from failed transactions for the account, as a warm-ruled table with tabular numerals and a rust-orange total.
• Primary action. Continue to Claim to recover the presented amount.
• Supporting actions. Inspect the failed transaction behind each recoverable line item; return to Scan to refresh detection.
• Domain entities. Recoverable SOL line items, source failed transactions, account, total recoverable amount.
• Component responsibilities. Warm-ruled table with tabular numerals; rust-orange total; per-line-item drill-down to the originating failed transaction; continue-to-claim control; empty state when nothing is recoverable.
• States. Loading: table skeleton while recoverable amounts are computed. Empty: a calm empty state explaining that no recoverable SOL was found for the account, with a link back to Scan. Success: line items and total are displayed. Error: a computation or RPC failure reports a recoverable error with a retry action. Recovery: the user can retry computation or return to Scan.

Claim

• Information / state. Protected. Initiates a claim/withdrawal to move recoverable SOL back to the account owner. Shows the amount to be claimed, the destination account, and the claim's progress and outcome.
• Primary action. Confirm and submit the claim/withdrawal.
• Supporting actions. Review the recoverable line items being claimed; cancel before submission; view the resulting transaction signature.
• Domain entities. Claim request, recoverable SOL line items, destination account, claim transaction, transaction signature, claim status.
• Component responsibilities. Claim summary with the rust-orange amount; destination account display; confirm control; pending/progress indicator; outcome panel with the transaction signature and a link to the on-chain record; failure panel with a retry action.
• States. Loading: pending indicator while the claim transaction is submitted and confirmed. Empty: if there is nothing to claim, a calm state directing the user back to Recoverable SOL. Success: the claim is confirmed, the amount is shown as returned, and the transaction signature is presented. Error: a failed or rejected claim reports a recoverable error with the reason and a retry action; the recoverable amount is preserved so the user can try again. Recovery: the user can retry the claim, or return to Recoverable SOL to review the amount.

Rugpull Recovery

• Information / state. Protected. Identifies and claims back SOL recoverable from rugpull assets backed by Solana. Shows the user's rugpull-affected asset positions, the recoverable SOL associated with each, and the claim outcome.
• Primary action. Claim back the recoverable SOL tied to a rugpull-affected asset position.
• Supporting actions. Inspect an asset position's detail; select which positions to claim; view the resulting transaction signature.
• Domain entities. Rugpull-affected asset position, associated recoverable SOL, claim transaction, transaction signature, claim status.
• Component responsibilities. List of rugpull-affected asset positions with their recoverable SOL; per-position detail; selection controls; claim control; pending/progress indicator; outcome panel with transaction signature; empty state when no rugpull-affected positions are found; error panel with retry.
• States. Loading: pending indicator while positions and recoverable amounts are resolved. Empty: a calm illustrated empty state explaining that no rugpull-affected asset positions were found for this account. Success: recoverable SOL per position is displayed and, after claiming, the confirmed amount and transaction signature are shown. Error: a resolution or claim failure reports a recoverable error with a retry action; already-resolved positions remain visible. Recovery: the user can retry resolution or retry the claim.

3. Functional Requirements

Each requirement is a distinct story point with provenance, lifecycle facts, and observable acceptance.

FR-1 — Detect failed Solana transactions tied to an account (explicit) As a Solana Wallet Holder, I should scan a Solana account's on-chain history so that failed transactions tied to that account are detected.

• Trigger / input: the holder initiates a scan for a Solana account.
• Observable result: the set of failed transactions tied to that account is listed with identifying details.
• Access state: requires an established identity (protected destination: Scan).
• Failure / recovery: if the on-chain history cannot be retrieved, a recoverable error is shown with a retry action; partial results remain visible.
• Continuation: the holder proceeds to Recoverable SOL to review what can be recovered.

FR-2 — Claim back / recover SOL (fees/rent) from failed transactions in an account (explicit) As a Solana Wallet Holder, I should claim back the SOL (fees/rent) identified from failed transactions in my account so that the recoverable SOL is returned to my wallet.

• Trigger / input: the holder confirms a claim/withdrawal for the recoverable amount presented on Recoverable SOL.
• Observable result: the claim transaction is submitted and confirmed, the amount is shown as returned, and the transaction signature is presented.
• Access state: requires an established identity (protected destinations: Recoverable SOL, Claim).
• Failure / recovery: a failed or rejected claim reports the reason with a retry action and preserves the recoverable amount.
• Continuation: the holder can retry the claim or return to Recoverable SOL.

FR-3 — Support Solana wallet holders as the primary user (explicit) As a Solana Wallet Holder, I should be able to use the product as its primary user so that my failed-transaction recovery work is the product's central concern.

• Trigger / input: the holder arrives at the product.
• Observable result: the product's public entry and protected destinations address the wallet holder's failed-transaction recovery directly.
• Access state: the Landing page is anonymous; recovery destinations require an established identity.
• Failure / recovery: not applicable.
• Continuation: the holder enrolls or verifies identity and proceeds to Scan.

FR-4 — Support claiming back rugpull asset backed by Solana (explicit) As a Rugpull Victim / Asset Holder, I should identify and claim back the SOL recoverable from rugpull assets backed by Solana so that SOL tied to my rugpull-affected holdings is recovered.

• Trigger / input: the holder opens Rugpull Recovery and selects the rugpull-affected asset positions to claim.
• Observable result: the recoverable SOL per position is displayed and, after claiming, the confirmed amount and transaction signature are shown.
• Access state: requires an established identity (protected destination: Rugpull Recovery).
• Failure / recovery: a resolution or claim failure reports a recoverable error with a retry action; already-resolved positions remain visible.
• Continuation: the holder can retry resolution or retry the claim.

FR-5 — Self-service enrollment for first-time wallet holders and rugpull victims (required_inference) As a Solana Wallet Holder or Rugpull Victim / Asset Holder, I should be able to enroll myself on first use so that I can begin recovery work without waiting on anyone else.

• Trigger / input: an anonymous visitor chooses to begin and submits the enrollment form on Sign Up.
• Observable result: an application-owned identity is created and bound to the user's recovery state.
• Access state: Sign Up is anonymously reachable.
• Failure / recovery: invalid or incomplete input is reported inline; a failed enrollment attempt reports a recoverable error and preserves entered values.
• Continuation: the user is taken to Scan.

FR-6 — Returning verification for wallet holders and rugpull victims (required_inference) As a Solana Wallet Holder or Rugpull Victim / Asset Holder, I should be able to verify my identity on return so that I can resume the durable recovery state I already control.

• Trigger / input: a returning user submits their credentials on Login.
• Observable result: identity is verified and the user's recovery state is resumed.
• Access state: Login is anonymously reachable.
• Failure / recovery: incorrect credentials report a recoverable error without discarding the entered identifier; the user can retry or follow the link to Sign Up.
• Continuation: the user is taken to Scan.

4. User Personas

Solana Wallet Holder

Product context. Everyday Solana wallet holders who have experienced failed transactions or drained accounts. They arrive at solana-refund after something went wrong on-chain and they suspect SOL was left behind in failed transactions.

Primary goal. Detect failed Solana transactions tied to their account and claim back the recoverable SOL (fees/rent) so that SOL is returned to their wallet.

Distinct accepted responsibilities. Scanning their account's on-chain history for failed transactions; reviewing the recoverable SOL identified from those failures; initiating a claim/withdrawal of that recoverable SOL.

Relevant inputs or decisions. The Solana account to scan; whether to re-run a scan; which recoverable line items to inspect; whether to confirm the claim/withdrawal.

Interactions with other accepted participants. The holder is the sole human participant in the failed-transaction recovery lifecycle. The solana-refund backend performs the scan and submits the claim; the Solana network confirms it. The holder's own observable result is the returned SOL and the presented transaction signature.

Observable success. SOL is returned to their wallet, the claim is confirmed, and the transaction signature is presented.

What makes this role's work different. The wallet holder's work is diagnostic and account-scoped: it begins with uncertainty about what happened on-chain and proceeds through detection to a single confirmed withdrawal. It is not asset-scoped, and it does not depend on identifying a specific failed project.

Rugpull Victim / Asset Holder

Product context. Holders of rugpull-affected assets backed by Solana who need to identify and claim back recoverable SOL tied to those assets. They arrive knowing a specific asset position went wrong.

Primary goal. Locate the recoverable SOL associated with their rugpull asset positions and claim it back.

Distinct accepted responsibilities. Resolving their rugpull-affected asset positions; reviewing the recoverable SOL associated with each; selecting positions and claiming back the recoverable SOL.

Relevant inputs or decisions. Which rugpull-affected asset positions to resolve; which positions to select for claiming; whether to confirm the claim.

Interactions with other accepted participants. The victim is the sole human participant in the rugpull recovery lifecycle. The solana-refund backend resolves positions and submits the claim; the Solana network confirms it. The victim's own observable result is the confirmed recovered amount and the transaction signature.

Observable success. SOL recoverable from rugpull-affected holdings is recovered, with the confirmed amount and transaction signature shown.

What makes this role's work different. The rugpull victim's work is asset-scoped rather than account-scoped: it starts from a known failed asset position and asks what SOL can be pulled back from it, rather than from a general scan of account history. The two roles share identity and access but perform materially different recovery work.

5. Core User Flows

Flow A — Solana Wallet Holder: detect failed transactions and claim back SOL

1. The wallet holder arrives at the anonymous Landing page and reads what the product does: it detects failed Solana transactions tied to an account and helps recover SOL.
2. The holder chooses the primary CTA and lands on Sign Up (first-time) or follows the secondary link to Login (returning).
3. First-time: on Sign Up, the holder submits the enrollment form. On success, an application-owned identity is created and bound to their recovery state, and they are taken to Scan. On invalid input, errors appear inline and entered values are preserved so they can correct and resubmit. Returning: on Login, the holder submits their credentials. On success, their durable recovery state is resumed and they are taken to Scan. On incorrect credentials, a recoverable error is shown without discarding the entered identifier, and they can retry or follow the link to Sign Up.
4. On Scan, the holder initiates a scan of their Solana account's on-chain history. A progress indicator shows while the history is fetched and evaluated.
5. The system detects the failed transactions tied to that account and lists them with identifying details and the recoverable amount each contributes.
   • If no failed transactions are found: a calm illustrated empty state explains this, and the holder can re-run the scan.
   • If the scan cannot complete: a recoverable error is shown with a retry action, and any partial results remain visible. The holder retries.
6. The holder continues to Recoverable SOL, where the recoverable SOL (fees/rent) identified from the failed transactions is presented as a warm-ruled table with tabular numerals and a rust-orange total.
   • If nothing is recoverable: an empty state explains this and links back to Scan.

• If computation fails: a recoverable error is shown with a retry action.

7. The holder inspects individual line items, drilling down to the originating failed transaction, then continues to Claim.
8. On Claim, the holder reviews the amount to be claimed and the destination account, then confirms and submits the claim/withdrawal. A pending indicator shows while the transaction is submitted and confirmed.
9. The claim is confirmed: the amount is shown as returned to the holder's wallet and the transaction signature is presented with a link to the on-chain record. The holder's observable success is SOL returned to their wallet.
   • If the claim fails or is rejected: the reason is reported with a retry action, and the recoverable amount is preserved so the holder can try again.
10. Continuation: the holder can return to Scan to re-check the account, or return to Recoverable SOL to review remaining amounts.

Flow B — Rugpull Victim / Asset Holder: claim back SOL from rugpull assets backed by Solana

1. The rugpull victim arrives at the anonymous Landing page and reads that the product helps rugpull victims recover SOL from rugpull assets backed by Solana.
2. The victim chooses the primary CTA and lands on Sign Up (first-time) or follows the secondary link to Login (returning).
3. First-time: on Sign Up, the victim submits the enrollment form; on success an application-owned identity is created and bound to their recovery state, and they are taken to Scan. On invalid input, errors appear inline and entered values are preserved. Returning: on Login, the victim submits their credentials; on success their durable recovery state is resumed and they are taken to Scan. On incorrect credentials, a recoverable error is shown and they can retry or follow the link to Sign Up.
4. The victim navigates to Rugpull Recovery. A pending indicator shows while their rugpull-affected asset positions and their recoverable SOL are resolved.
5. The system identifies the victim's rugpull-affected asset positions backed by Solana and displays the recoverable SOL associated with each.
   • If no rugpull-affected positions are found: a calm illustrated empty state explains this.
   • If resolution fails: a recoverable error is shown with a retry action, and already-resolved positions remain visible. The victim retries.
6. The victim inspects an asset position's detail, then selects the positions to claim.
7. The victim initiates the claim back of the recoverable SOL tied to the selected positions. A pending indicator shows while the claim transaction is submitted and confirmed.

8. The claim is confirmed: the recovered amount and the transaction signature are shown. The victim's observable success is SOL recovered from rugpull-affected holdings.
   • If the claim fails: a recoverable error is reported with a retry action, and already-resolved positions remain visible so the victim can retry the claim.
9. Continuation: the victim can return to Rugpull Recovery to review remaining positions or re-attempt a claim.

6. Visuals Colors and Theme

The creative direction is authoritative for this section. Muse: Frank Chimero. Headline: Warm editorial clarity for on-chain recovery.

Color tokens (light mode)

No gradients. No neon. The generic indigo/blue-on-white SaaS template is forbidden for this project.

Typography

• Headings: Literata serif, medium weight, generous size, slight tight tracking. Sentence case, never all-caps.
• Body: Source Sans 3, comfortable reading sizes, generous line-height (1.6).
• Scale: 1.333 modular — 56px / 42px / 32px / 24px / 18px / 16px / 14px. Mobile headline 36px, desktop 56px.

Shape language. Soft, organic-modern. Rounded corners on cards and buttons (12–16px radius), not pill-shaped. Subtle warm shadows, no hard borders. Illustrated spot icons with hand-drawn quality. Section openers use a small illustrated mark. Buttons are rounded rectangles with a slight lift on hover, not glossy or bouncy.

Layout. Single-column reading measure (max 720px) centered on the page with generous margins. Editorial rhythm: large hero headline, then a calm sequence of illustrated section openers and readable text blocks. Data tables for recoverable SOL use tabular alignment with warm rules, not zebra stripes. Cards used sparingly, arranged in a gentle grid when needed. Navigation is a simple top bar with the wordmark left and a single CTA right — no mega-menu.

Imagery. Warm flat illustration with hand-drawn quality — not clip art, not 3D renders. Spot illustrations of a wallet, a key, a shield, a small character looking at a screen. Muted warm palette (rust, mustard, dusty blue, cream). Diagrams of the recovery flow are hand-drawn style with arrows and labels. No photography, no gradients, no abstract blobs.

Readable text and controls stay whole at every viewport: headlines, wordmarks, labels, numbers, and cards' text and controls stay entirely inside the viewport and their container at 375px, 768px, and 1280px, wrapping or scaling (for example font-size: clamp(...) with its mobile size) to fit, and no other element covers any part of them. Imagery and decoration may be cropped, bled off an edge, rotated, overlapped, or cut exactly as the direction asks, as long as they cover no readable text or control.

7. Signature Design Concept

The opening spread of an essay about getting your SOL back.

The public entry — the Landing page — is composed as the opening spread of a printed essay rather than a SaaS landing page. A cream ground (#F7F3EC) fills the viewport. An oversized Literata headline spans the viewport width in 3–4 flush-left, ragged-right lines, naming plainly what the product does: it detects failed Solana transactions tied to an account and helps wallet holders and rugpull victims recover SOL. The headline is set at 56px on desktop and 36px on mobile, wrapping rather than clipping.

Below the headline, placed asymmetrically to the right of the text column, sits a single hand-drawn illustration: a small character holding a wallet with a glowing SOL coin. On desktop the illustration bleeds off the right edge; on mobile it stacks below the text column. It never covers the headline, the CTA, or the secondary link.

Beneath the headline sits the primary CTA — a rust-orange (#C45C26) rounded rectangle with a subtle warm shadow and a 2px rust-orange bottom border — and beside it a secondary text link to Login. There is no centered composition, no gradient blob, and no blue button.

Below the fold, the page continues as a calm sequence of illustrated section openers — a key, a shield, a coin — each paired with a short Literata subhead and a readable Source Sans 3 paragraph, walking the visitor through failed-transaction recovery and rugpull asset recovery in the order the product performs them. The whole page reads at a single 720px measure, centered, with generous margins.

This concept recomposes only accepted content, states, and controls. It introduces no new behavior, page, or destination.

8. Interaction Model & Motion Direction

Interaction Model: Static (direction) Motion Tempo: restrained Hero Dimensionality: flat

Landing Hero Motion Brief

• Focal subject. The hand-drawn character holding a wallet with a glowing SOL coin, placed asymmetrically to the right of the flush-left headline column.
• Input → transformation → outcome thesis. As the visitor scrolls the Landing page, each illustrated section opener fades up gently into view — a subtle fade-up, nothing more — so the essay-like sequence of recovery steps reveals itself at reading pace. The outcome is a calm, legible walkthrough of what the product does, ending at the rust-orange CTA.
• Motion vocabulary. Gentle and mostly none. Small illustrated animations on scroll into view (a subtle fade-up for section openers). Hover states on buttons and links are warm and immediate, not springy. No parallax, no marquees, no kinetic type.
• Composed first frame. Cream ground; oversized Literata headline flush-left in 3–4 lines; hand-drawn wallet illustration bleeding off the right edge on desktop; rust-orange CTA pinned beneath the headline with a secondary text link beside it; simple cream top bar with the Literata wordmark left and one rust-orange CTA right.
• Reduced-motion state. With prefers-reduced-motion, all animations become instant fades. The hero renders as a fully composed static arrangement: headline, illustration, CTA, and secondary link all present and readable, with no scroll-triggered motion.

No user-requested 3D/WebGL scene is present, and the direction's hero dimensionality is flat, so no Canvas/R3F/Drei scene is required.

9. Non-Functional Requirements

• NFR-1 — Durable recovery state (required_inference). Recovery state — scan results, recoverable SOL line items, rugpull-affected positions, and claim outcomes — must persist across sessions and remain bound to the correct identity, because a claim moves value to a specific owner and must not be attributed to the wrong participant. Rationale: the accepted claim/withdrawal lifecycle produces a durable obligation and value transfer.
• NFR-2 — On-chain data integrity (explicit). Detected failed transactions and computed recoverable amounts must reflect the actual on-chain history of the scanned account; the product must not present an amount as recoverable that the network will not honor. Rationale: the accepted outcome is SOL actually returned to the wallet.
• NFR-3 — Claim confirmation visibility (explicit). Every claim must present its outcome — confirmed amount and transaction signature — so the holder can verify the result independently on-chain. Rationale: the accepted observable result is SOL returned to the wallet.
• NFR-4 — Recoverable failure handling (required_inference). RPC, network, computation, and claim failures must surface a recoverable error with a retry path, and must not discard already-resolved results. Rationale: the accepted lifecycles require material failure and recovery to remain usable.
• NFR-5 — Readable text and controls at every viewport (explicit, from the creative direction). Headlines, wordmarks, labels, numbers, and cards' text and controls stay entirely inside the viewport and their container at 375px, 768px, and 1280px, wrapping or scaling to fit; no other element covers any part of them.
• NFR-6 — Reduced-motion support (explicit, from the creative direction). With prefers-reduced-motion, all animations become instant fades and the page remains fully usable as a static arrangement.

• NFR-7 — Accessible contrast and legibility (required_inference). The cream/ink/dusty-blue/rust palette must be applied so that body text, labels, and controls remain legible against their grounds. Rationale: the audience is anxious and uncertain and must be able to read every amount and control without strain.

10. Tech Stack

• Frontend: React (web), single-column editorial layout per the creative direction.
• Backend: Python / FastAPI, extended with routes and modules for scanning, recoverable-SOL accounting, and claim submission. The backend reuses its existing process, port, dependencies, and deployment; no separate service is introduced for these domain features.
• Storage: a persistent datastore for application-owned identity and durable recovery state (scan runs, detected failed transactions, recoverable SOL line items, rugpull-affected positions, claim records and signatures).
• Solana integration: Solana RPC access for on-chain transaction history and claim/withdrawal submission.
• Packaging: Docker / docker-compose for the frontend, backend, and datastore.
• Kubernetes: not required for the current product scope.

11. Assumptions and Constraints

• A-1 (assumption). The user's Solana account address is the identifier against which on-chain history is scanned; the product does not require the user to import a private key to detect failed transactions.
• A-2 (assumption). Claim/withdrawal submission requires the account owner's authorization, performed through the user's Solana wallet.
• A-3 (constraint). All accepted requirements are current-horizon. No future-horizon capability is committed by this document.
• A-4 (constraint). The product does not add trading, swapping, token issuance, portfolio management, staking, NFT marketplaces, social features, or any capability beyond detecting failed transactions and claiming back recoverable SOL.
• A-5 (constraint). Application identity is used only to bind durable recovery state and value transfers to the correct participant. No role-based permissions, differentiated visibility, or account-management capabilities beyond enrollment and returning verification are established.
• A-6 (constraint). The creative direction is authoritative for visuals, typography, shape, layout, imagery, and motion. The generic indigo/blue-on-white SaaS template is forbidden.
• A-7 (assumption). Solana RPC providers are external systems; their availability affects scan and claim success, and their failures are surfaced as recoverable errors.

12. Glossary

• Failed transaction — a Solana transaction tied to an account that did not complete successfully and left recoverable SOL (fees/rent) behind.
• Recoverable SOL — the SOL (fees/rent) identified from failed transactions, and the SOL recoverable from rugpull-affected assets backed by Solana, that can be claimed back to the account owner.
• Claim / withdrawal — the action that moves recoverable SOL back to the account owner, producing a confirmed transaction and signature.
• Rugpull asset — an asset backed by Solana whose project drained or abandoned it, leaving recoverable SOL tied to holders' positions.
• Rugpull-affected asset position — a holder's specific holding in a rugpull asset, against which recoverable SOL is resolved and claimed.
• Scan — the operation that reads a Solana account's on-chain history and detects failed transactions tied to that account.
• Transaction signature — the on-chain identifier of a submitted claim transaction, presented to the user as the observable proof of the claim outcome.
• Application-owned identity — the identity established through Sign Up and verified through Login, to which durable recovery state and value transfers are bound.