O

# Self-Directed Draft: Solana Transaction Intent Screen A reusable product specification for making high-impact wallet actions understandable before signing. ## Objective Show users exactly what an action is intended to do, who or what it affects, and what cannot be undone—without requiring them to inspect raw instruction data. ## Core screen **Header:** Review action **Intent summary:** > You are updating the fee recipient for **[product/program name]**. **Details** - **Action:** [Human-readable action] - **Network:** [Selected cluster] - **Signer:** [Connected wallet label + shortened address] - **Affected accounts:** [Names and shortened addresses] - **Assets involved:** [Token, amount, or “None detected”] - **Permissions changed:** [Old value → new value] - **Estimated network fee:** [Shown only when available] ## Risk panel Use a severity label: - **Low:** Read-only or non-financial interaction - **Medium:** Changes settings or permissions - **High:** Transfers assets, revokes access, or cannot be reversed Copy pattern: > **This action may be difficult or impossible to undo.** > Confirm that the destination, amount, and account details are correct before signing. Never describe an unknown field as safe. Instead show: > Some transaction details could not be interpreted. Review the raw instructions or cancel. ## Confirmation controls - Primary button: **Confirm and sign** - Secondary button: **Cancel** - For high-risk actions, require a typed confirmation: - Prompt: `Type CONFIRM to continue` - Disable the primary button until required fields are reviewed. - Do not auto-trigger the wallet prompt before the user presses the confirmation button. ## Error and mismatch states **Simulation unavailable** > We could not preview the outcome. You can cancel, retry, or review the raw transaction. **Wallet changed** > The connected wallet changed after this review. Please review the action again. **Details changed** > The transaction no longer matches the reviewed action. Signing was paused for your protection. **User rejected** > No transaction was signed. You can try again when ready. ## Implementation checklist - [ ] Render intent from structured application data, not only raw bytes. - [ ] Clearly distinguish detected values from unavailable values. - [ ] Show shortened addresses with copy and inspect controls. - [ ] Re-check the transaction immediately before wallet invocation. - [ ] Preserve a review state when the wallet rejects or times out. - [ ] Provide a raw-instruction escape hatch for technical users. - [ ] Test long names, missing metadata, mobile widths, and screen readers. - [ ] Log UI errors without storing secret keys or seed material.

# Self-Directed Draft: Safe Token Account Cleanup UX A product specification for a Solana app that helps users identify and close eligible empty token accounts without hiding risk or requiring protocol knowledge. ## Objective Make account cleanup understandable, reviewable, and reversible where possible—while preventing users from closing accounts that still contain assets or are required by an active workflow. ## Core flow 1. **Scan** - Load the connected wallet’s token accounts. - Display scan status and timestamp. - Never present incomplete results as final. 2. **Classify** - **Eligible:** empty and closeable. - **Needs review:** nonzero balance, unresolved metadata, delegated authority, or program-specific constraints. - **Unavailable:** account state cannot be verified. 3. **Review** Each eligible row shows: - Token mint name and shortened address - Account address - Current balance - Expected reclaimed value, labeled as an estimate - Destination for reclaimed value 4. **Select and confirm** - Default to no accounts selected. - Show selected count and estimated total. - Require explicit confirmation of the destination wallet. - Warn that closure is generally irreversible. 5. **Execute** - Process accounts in bounded batches. - Show signing, submission, confirmation, and incomplete states separately. - Preserve a local action history with timestamps and signatures when available. ## Safety rules - Do not classify an account as eligible without a current successful state read. - Block accounts with nonzero balances unless the product explicitly supports a documented sweep flow. - Never imply that estimated reclaimed value is guaranteed. - Re-check account state immediately before submission. - If any account changes between scan and submission, remove it from the batch and explain why. - Provide a “copy addresses” option for manual review. ## Suggested copy **Empty state:** “No closeable token accounts found in this scan.” **Review warning:** “Closing an account is usually irreversible. Review each address before continuing.” **Changed state:** “This account changed after your scan, so it was removed from this batch.” **Partial result:** “Some accounts were processed. Review the remaining items before retrying.” ## Acceptance criteria - Users can distinguish eligible, review, and unavailable accounts. - No account is submitted without a fresh eligibility check. - Estimated reclaimed value is clearly separated from confirmed results. - A partial batch cannot be reported as fully complete. - Every submitted transaction has a visible status and retrievable signature when available. - The interface works without requiring users to understand token-account terminology.

# Self-Directed Draft: Solana Transaction Failure Recovery Kit A reusable UX specification for helping users recover from failed, rejected, or stalled transactions. ## Objective Turn an unclear failure into a specific next action, without requiring users to understand RPC, blockhash, simulation, or confirmation terminology. ## Failure states and copy ### User rejected **Title:** Transaction canceled **Body:** You chose not to approve this transaction. No action was submitted. **Actions:** `Try again` · `Close` ### Simulation failed **Title:** Transaction could not be prepared **Body:** The app checked the transaction before submission, but a required condition was not met. **Actions:** `Review details` · `Try again` Show a collapsible technical section containing: - Human-readable reason, if available - Program or instruction label - “Copy diagnostic details” ### Submission failed **Title:** We couldn’t submit the transaction **Body:** Your wallet approval was received, but submission did not complete. Check your connection and try again. **Actions:** `Retry submission` · `Cancel` ### Confirmation uncertain **Title:** Transaction status is unclear **Body:** We submitted your transaction but could not confirm the result yet. Avoid repeating the action until you check your activity. **Actions:** `Check status` · `View activity` ### Insufficient balance **Title:** Not enough funds **Body:** Your wallet does not have enough funds for this action and its required network fees. **Actions:** `Add funds` · `Cancel` ## Retry rules - Preserve the user’s original form inputs. - Never retry automatically for an action that could create a duplicate. - Disable repeated clicks while a retry is in progress. - Generate or refresh transaction parameters when the app determines the previous attempt is stale. - Explain whether retrying means resubmitting, rebuilding, or merely checking status. - Keep the error visible until the user dismisses it or a new attempt begins. ## Technical details panel Use a non-alarming expandable panel: ```text Diagnostic details Status: [state] Action: [user action] Request ID: [local identifier] Time: [local timestamp] Error: [sanitized message] [Copy details] ``` Do not expose secrets, private keys, seed phrases, or raw sensitive payloads. ## Acceptance checklist - [ ] Every failure state has plain-language copy. - [ ] Every state offers one recommended next action. - [ ] Rejected transactions are clearly distinguished from failed transactions. - [ ] Uncertain confirmation warns against duplicate actions. - [ ] Retry behavior is deterministic and explained. - [ ] Technical details can be copied without leaking sensitive data. - [ ] Screen readers receive the error through an announced status region. - [ ] Error dialogs preserve keyboard focus and support Escape dismissal.

# Self-Directed Draft: Solana App Accessibility QA Checklist A reusable pre-release checklist for Solana wallets, dashboards, and dApps. ## Navigation and input - [ ] Every action is reachable by keyboard. - [ ] Focus order follows the visual order. - [ ] Focus indicators remain visible on dark and light themes. - [ ] Dialogs trap focus and return focus when closed. - [ ] Touch targets are large enough for mobile use. - [ ] Forms provide labels, examples, and specific validation messages. - [ ] Paste, autofill, and wallet-provided account values work correctly. ## Wallet and account context - [ ] The connected account is clearly identified without exposing unnecessary data. - [ ] Network or cluster context is visible wherever it affects an action. - [ ] Connection, disconnection, and account-change events update the interface. - [ ] Users can recover when a wallet extension or mobile handoff is interrupted. - [ ] Public keys are displayed in a copyable format with confirmation feedback. - [ ] Copy buttons have accessible labels and non-color success feedback. ## Status and errors - [ ] Loading states explain what is being fetched or prepared. - [ ] Empty states explain the next useful action. - [ ] Errors use plain language before technical details. - [ ] Retry actions preserve user-entered data. - [ ] Error messages do not imply success when the outcome is unknown. - [ ] Color is never the only way to communicate status. - [ ] Long errors, hashes, and addresses wrap or offer expandable detail. ## Motion, contrast, and responsive behavior - [ ] Text and controls meet the team’s chosen contrast standard. - [ ] The layout remains usable at narrow mobile widths. - [ ] Content remains usable at increased browser text size. - [ ] Animations respect reduced-motion preferences. - [ ] Toasts and alerts remain available long enough to read. - [ ] No essential action depends on hover. ## Test script Run each task with keyboard-only navigation, a screen reader, and a small-screen viewport: 1. Connect a wallet. 2. Switch account or disconnect it. 3. Copy a public key. 4. Trigger an empty state. 5. Trigger a recoverable error. 6. Retry without losing entered data. 7. Open and close a dialog. 8. Complete the primary user action. 9. Reload during a loading state. 10. Confirm that the final UI state is understandable without color, sound, or animation. **Release rule:** block release on any issue that prevents a user from identifying the current account, understanding the next action, or recovering from an error.

# Self-Directed Draft: Transaction Status Timeline **Product specification for Solana app teams** ## Purpose Give users a readable explanation of what happened after they approved a transaction—without requiring them to understand explorer terminology. ## User flow After signing, show a compact status panel: 1. **Submitted** — the wallet approval was received. 2. **Processing** — the app is waiting for the network result. 3. **Confirmed** — the transaction reached the requested confirmation level. 4. **Needs attention** — the transaction failed, expired, or could not be checked. ## Status panel **Title:** `Transaction status` **Fields:** - **Action:** Plain-language label, such as “Swap tokens” - **Status:** Current state with timestamp - **Wallet:** Shortened public key - **Network:** App-selected cluster label - **Reference:** Copyable transaction signature, when available **Primary actions:** - `View details` - `Try again` when retrying is safe - `Close` ## Failure copy Avoid generic “Something went wrong.” Use specific, non-blaming messages: - **Rejected by wallet:** “You declined the request in your wallet. No retry is needed.” - **Transaction failed:** “The transaction was submitted but did not complete. Review the details before trying again.” - **Confirmation timeout:** “We haven’t received a final status yet. Check again before submitting another transaction.” - **Missing signature:** “The wallet did not return a transaction signature. No status lookup was performed.” - **Lookup unavailable:** “The transaction reference is available, but its current status could not be loaded.” ## Safety rules - Never label a transaction successful solely because signing completed. - Do not offer automatic retry for swaps, transfers, or other potentially repeatable actions. - Preserve the signature locally for the session and provide a copy button. - Make uncertainty explicit; distinguish “failed” from “status unknown.” - Keep user-entered amounts and addresses visible in the details view. - Do not expose a full public key by default. ## Suggested event model ```text transaction_started wallet_approval_requested wallet_approval_rejected signature_received confirmation_pending transaction_confirmed transaction_failed confirmation_unknown ``` Each event should include: ```text action_id wallet_public_key cluster_label client_timestamp signature_optional error_code_optional ``` ## Acceptance checklist - [ ] Every signing flow has a visible post-approval state. - [ ] Rejected, failed, and unknown outcomes use different copy. - [ ] Users can copy the signature when one exists. - [ ] Retry requires an explicit user action. - [ ] Refreshing the page does not erase the current status context. - [ ] Error details are useful without exposing sensitive data. - [ ] Screen readers receive status changes. - [ ] The UI does not claim success before confirmation criteria are met.

# Self-Directed Draft: Transaction Intent Preview **Product brief for Solana app teams** ## Purpose Give users a clear, reversible review step before signing a wallet transaction. Reduce surprises by showing what the app intends to do, what it cannot guarantee, and what happens if the request fails. ## Review panel **Title:** `Review transaction` Show: - **Action:** Plain-language description, e.g. “Swap tokens” or “Create listing” - **Accounts involved:** User wallet and any app-controlled accounts, labeled by role - **Assets changing:** Token names, quantities, and direction - **Network fee:** Display the estimated fee when available; otherwise say `Fee estimate unavailable` - **Simulation status:** `Ready`, `Could not simulate`, or `Simulation unavailable` - **Expiry:** If the transaction has a validity window, show a countdown or concise expiry notice ## Safety copy > Review the details before signing. Your wallet will show the final signing request. Never share your recovery phrase or private key. If simulation fails: > We couldn’t verify this transaction before signing. You can cancel and try again, or continue only if you understand the request. ## Actions - `Cancel` - `Back` - `Sign transaction` Disable `Sign transaction` when required transaction details are missing. Do not imply that simulation guarantees success. ## Error states ### User rejected > Signing was canceled. No transaction was submitted. Action: `Try again` ### Submission failed > The transaction was not submitted successfully. Check your connection and try again. Actions: `Retry submission`, `Close` ### Confirmation pending > Transaction submitted. Waiting for network confirmation. Actions: `View status`, `Close` ## Acceptance checklist - [ ] Review appears before every signing request. - [ ] Asset amounts and directions are readable on mobile. - [ ] Unknown values are labeled as unavailable, not guessed. - [ ] Signing never requests secret keys or recovery phrases. - [ ] Cancel leaves the user on a safe, recoverable screen. - [ ] Errors distinguish rejection, submission failure, and pending confirmation. - [ ] UI does not claim success before confirmation.

# Self-Directed Draft: Wallet Connection Recovery UX **Product brief for Solana app teams** ## Goal Help users recover from disconnected, stale, or mismatched wallet sessions without refreshing the page or guessing what went wrong. ## Core states ### 1. Disconnected **Banner:** “Your wallet is disconnected.” **Primary action:** `Reconnect wallet` **Secondary action:** `Continue browsing` ### 2. Wrong network or cluster **Banner:** “This app is connected to a different network than your wallet.” **Actions:** `Switch network` · `Cancel` Do not present signing controls until the expected network is detected. ### 3. Stale session **Banner:** “Your wallet session needs to be refreshed.” **Action:** `Refresh connection` Preserve the user’s current form inputs where safe. ### 4. Account changed **Banner:** “Your connected account changed.” **Actions:** `Review account` · `Cancel` Clear account-specific drafts or approvals unless they can be safely reassigned. ### 5. Wallet unavailable **Banner:** “Your wallet could not respond. You can try again or choose another wallet.” **Actions:** `Try again` · `Choose another wallet` ## Interaction rules - Never request a seed phrase, private key, or secret recovery data. - Disable signing buttons while connection state is unknown. - Show the shortened public address and a copy button. - Make retry actions idempotent; repeated clicks should not create duplicate requests. - Keep errors near the action that caused them. - Provide a visible “Disconnect” option in wallet settings. - Announce connection changes for screen readers. ## Suggested event model ```text wallet_connect_started wallet_connected wallet_disconnected wallet_account_changed wallet_network_changed wallet_reconnect_requested wallet_reconnect_succeeded wallet_reconnect_failed ``` Include only non-sensitive metadata such as app route, wallet adapter name, and error category. Avoid logging addresses by default. ## Acceptance checklist - [ ] User can reconnect without a full-page reload. - [ ] Network mismatch blocks signing and explains why. - [ ] Account changes invalidate account-specific actions. - [ ] Retry feedback appears within the same UI region. - [ ] Forms retain safe, non-sensitive inputs. - [ ] No secret wallet data is requested or logged. - [ ] Keyboard and screen-reader users can complete recovery. - [ ] Each recovery state has one clear primary action.

# Self-Directed Draft: Failed Transaction Support Checklist **Reusable checklist for Solana app teams** Use this when a user reports that an action failed. The goal is to collect enough context to investigate without asking for wallet secrets. ### Support intake - [ ] Ask what the user tried to do and roughly when. - [ ] Ask for the exact error text or a screenshot with personal details removed. - [ ] If the wallet shows a transaction signature, ask for it. Do not assume one exists. - [ ] Ask whether the wallet rejected the request, the app displayed an error, or the action appeared to submit but did not complete. - [ ] Record the app version or page, wallet name, and device/browser. - [ ] Never request a seed phrase, private key, password, or remote access. ### First response template > Sorry that didn’t work. Please tell us what you were trying to do, the approximate time, and the error you saw. If your wallet provides a transaction signature, you can include that too. **Do not send your seed phrase or private key.** We’ll check what we can from those details before suggesting another attempt. ### Internal triage - [ ] Distinguish **rejected before signing**, **submitted with an error**, and **outcome unclear**. - [ ] For an unclear outcome, verify the result before advising a retry; repeating an action could have unintended effects. - [ ] Give the user a specific next step or state what remains unknown.

# Self-Directed Draft: Transaction Review Modal **Product spec for Solana app teams** **Goal:** Make wallet signing requests understandable before users approve them. ## Modal structure **Header:** **Review transaction** **Plain-language summary:** “Your wallet is asking you to approve this action. Review the details before signing.” **Action details:** - **Action:** `[Swap / Mint / Stake / Transfer]` - **Asset involved:** `[amount] [token]` - **Destination or program:** `[short name]` - **Estimated network fee:** `[amount] SOL` - **User authorization:** “This approval may allow the requested action to be completed. Only approve if the details match your intent.” **Safety notice:** “Never approve a request you do not recognize. Your wallet may show additional details.” ## Controls - **Cancel** - **Open wallet** - **I’ve reviewed this — Continue** The final button remains disabled until the user checks the review box: > “I reviewed the action, amount, destination, and fee.” ## Edge states - **Details unavailable:** “We could not prepare a readable summary. Review the wallet’s request carefully or cancel.” - **Changed request:** “The transaction details changed. Please review them again.” - **Fee unavailable:** “The network fee could not be estimated. Your wallet may show the final fee.” ## Acceptance checklist - Shows action, assets, destination/program, and fee when available. - Clearly separates application-provided details from wallet-provided details. - Never labels an unknown destination as trusted. - Requires an explicit review step before opening the signing flow. - Handles missing or changed transaction data without silently proceeding. - Provides a clear cancel path at every stage.

# Self-Directed Draft: Wallet Connection Panel **Product spec for Solana app teams** **Goal:** Help people understand what connecting a wallet does—and does not do—before they connect. **Panel copy** > **Connect a wallet** > Connecting lets this app see the public address your wallet shares and request actions for you to review. Connecting alone does not send a transaction. Your wallet should ask you to approve any transaction separately. Include a link to the app’s privacy notice, if one exists. Do not imply that disconnecting erases data already shared. **Required behavior** - Show the wallet name and shortened public address after connection, with a copy-address control. - Put **Disconnect** in the account menu, not behind a settings search. - If connection fails or is declined, say: “Wallet not connected. You can try again.” Do not label a decline as an error. - Before requesting a signature, explain what the signature is for on that screen; do not rely on the connection panel as consent. **Acceptance check:** A first-time user can identify their connected address, find Disconnect, and distinguish connecting from approving a transaction.

# Self-Directed Draft: Transaction Recovery Screen **Product spec for Solana app teams** **Goal:** Help users recover from a failed or uncertain transaction without accidentally submitting it twice. ## Required states and copy - **Submitting:** “Sending your transaction. Keep this screen open while we check its status.” - **Confirmed failure:** “This transaction did not complete. No retry has been sent.” Show the available error detail in plain language, with technical detail expandable. - **Status unknown:** “We can’t confirm the result yet. Check the transaction status before trying again.” - **Confirmed success:** “Transaction confirmed.” Show the resulting balances only after refreshing them. ## Recovery behavior 1. Save the transaction signature when available and offer **Copy signature**. 2. If the status is unknown, provide **Check status again**—not an immediate **Retry** button. 3. Before any retry, refresh the relevant balances and app state. Clearly label it as a *new transaction* requiring a new signature. 4. If the original action could be duplicated, require the user to acknowledge that risk before retrying. **Acceptance test:** Simulate a network timeout after submission. The screen must show “Status unknown” rather than “Failed,” preserve the signature if available, and prevent one-tap resubmission.

# Self-Directed Draft: Transaction Intent Card **Product specification for Solana app teams** **Goal:** Help users understand a proposed transaction before signing, using only information the app can explain and verify locally. ## Approval screen Show: - **Action:** “Swap,” “Deposit,” “Transfer,” or “Interact” - **Assets involved:** token name, symbol, amount, decimals, and copyable mint address - **Accounts affected:** shortened addresses with copy controls - **Expected result:** plain-language outcome - **Minimum received / maximum spent:** when applicable - **Fees:** separate network, platform, and priority fees when known - **Expiry:** when the quote or transaction becomes invalid - **Program IDs:** expandable technical details for advanced users Use this warning when the outcome cannot be confidently summarized: > **Review carefully:** This transaction includes instructions we cannot describe in plain language. Only sign if you trust this application and understand the requested action. ## Confirmation copy > **You are about to sign a transaction.** > Signing may authorize the instructions listed above. Review the accounts, assets, and limits before continuing. Buttons: - **Cancel** - **Sign transaction** Avoid buttons labeled “Claim,” “Continue,” or “Verify” when they trigger signing. ## Validation rules Before presenting the approval screen, the app should: - Re-fetch or validate all user-visible amounts. - Confirm the transaction’s recent block reference or expiry status. - Detect unexpected writable accounts or additional instructions. - Highlight changes from the user’s previous quote. - Refuse to display “guaranteed” outcomes unless the app can enforce them. - Keep the approval screen visible until the wallet request is complete or canceled. ## Post-signing state Show: - Pending, confirmed, failed, or expired status - Transaction signature with a copy control - What the app expected to happen - What the app can currently observe - A retry option that creates a fresh transaction rather than reusing stale data Suggested copy: > **Signature submitted.** The result is still pending. Do not submit again unless this transaction is confirmed failed or expired. ## Acceptance checklist - [ ] Every asset has a copyable mint address. - [ ] Every affected account is identifiable. - [ ] Limits and fees are visible before signing. - [ ] Unknown instructions are clearly labeled. - [ ] No success state appears before confirmation criteria are met. - [ ] Errors explain whether the user should retry, reconnect, or stop.

# Self-Directed Draft: Wallet Connection Review **Product spec for Solana app teams** **Goal:** Let users understand what connecting a wallet does before they approve it, without implying that connection alone authorizes a transaction. ### Connection screen Display the requesting app name as supplied by the app, the wallet address that will be shared, and this plain-language copy: > **Connect your wallet?** > This app can view your public wallet address and request actions for you to review. Connecting does not approve a transaction. Review any later signature or transaction request in your wallet before accepting it. Actions: **Connect** and **Cancel**. Neither should be preselected. Do not describe the app as “verified” unless the wallet has an explicit verification mechanism. ### After connection Provide a visible **Disconnect wallet** control. Explain that disconnecting stops this app session from using the connection; it does not undo transactions or revoke permissions managed elsewhere. ### Acceptance checklist - The displayed address is identifiable even when truncated, with a way to inspect or copy the full address. - A rejected connection leaves the app in a usable disconnected state. - Reconnecting does not silently approve a pending action. - Transaction and message-signing requests receive their own review, separate from connection.

# Self-Directed Draft: Token Search Safety Brief **For Solana app teams building a token picker** **Goal:** Help users identify the token they intend to select without treating a name, symbol, or logo as proof of identity. ### Interaction requirements - Show the **token name and symbol**, but never use either as the sole identifier. - Show a **copyable mint address** on every token detail view. In search results, show a shortened address and an easy way to reveal the full one. - If multiple results share a name or symbol, display them as separate results. Do not silently choose one. - Keep any app-curated label visually distinct from user-supplied token metadata. Define exactly what the label means before using it. - Before a user confirms an action, repeat the selected token and its mint address in the confirmation view. ### Suggested copy **Multiple tokens match this search** > Names and symbols can be reused. Check the mint address before continuing. **Unfamiliar token** > This token is not on this app’s curated list. That does not by itself tell you whether it is safe or unsafe. ### Release checklist - [ ] Duplicate names and symbols remain distinguishable on mobile. - [ ] A long token name cannot hide the mint address. - [ ] Missing logos do not block selection or imply a warning. - [ ] Curated labels have documented criteria and an owner responsible for updates. - [ ] Support instructions never ask users for a seed phrase or private key.

# Self-Directed Draft: RPC Status Banner **Product spec for Solana app teams** **Goal:** When an app cannot reliably read network data, tell users what is affected without implying their funds or transactions have changed. **Banner copy** > **Live data is temporarily unavailable** > Balances and activity may be out of date. You can retry, or check again later. Do not repeat an action solely because it is missing from this screen. **Behavior** - Show the banner after repeated read failures; do not show it for a single slow request. - Mark affected balances and activity with “Last updated [time]” rather than displaying stale values as current. - Keep cached information visible only when its age is clear. - Offer **Retry**. If reads recover, refresh the affected views before removing the banner. - If the app cannot determine whether a submitted action completed, show an **Outcome unknown** state—not “Failed”—and provide a way to check its status. **Acceptance check:** A user can distinguish “the app cannot load current data” from “an action failed” without reading technical error logs.

# Self-Directed Draft: Solana Transaction Debug Card ## Purpose Give users a safe, copyable summary when a transaction does not complete, so support teams can diagnose issues without requesting private keys, seed phrases, or screenshots of sensitive data. ## User flow After an unsuccessful or uncertain transaction, show: > **Something needs attention** > We couldn’t complete this action. Copy the diagnostic details below or send them to support. ### Diagnostic fields - **Action:** Human-readable description, such as “Swap token A for token B” - **Status:** Rejected, simulation failed, expired, or outcome unknown - **Network label:** The app’s configured cluster name - **Wallet type:** Wallet adapter name, if available - **App version:** Release identifier - **Client time:** Local timestamp - **Transaction identifier:** Only when one exists - **Failure stage:** Before signing, during submission, or after submission - **Safe technical message:** Sanitized error category and message - **Suggested next step:** Retry, refresh, inspect wallet, or contact support ## Copy action Provide a **Copy diagnostic details** button that produces plain text: ```text Action: [human-readable action] Status: [status] Failure stage: [stage] Network: [configured network] Wallet: [wallet name or unavailable] App version: [version] Client time: [timestamp] Transaction ID: [identifier or unavailable] Error category: [category] Message: [sanitized message] ``` ## Privacy rules - Never include secret keys, seed phrases, wallet connection tokens, or full account inventories. - Truncate or redact arbitrary program error strings before display. - Let users review the text before copying. - Clearly label any wallet address or transaction identifier as shareable public information. - Avoid automatically uploading diagnostics unless the user explicitly consents. ## Acceptance criteria - Every terminal transaction state offers a diagnostic path. - Unknown outcomes remain labeled as unknown; the card must not imply success or failure without evidence. - Copying works on desktop and mobile. - Missing fields display `Unavailable`, not fabricated values. - Support can distinguish signing rejection, submission failure, and post-submission uncertainty. - The card remains useful when no transaction identifier exists.

# Self-Directed Draft: Solana Transaction Preflight Checklist A reusable review checklist for teams shipping transaction flows. ## Before signing - [ ] Show the action in plain language, not only an instruction like “Sign transaction.” - [ ] Identify the account or asset affected. - [ ] Display amounts with decimals and readable units. - [ ] Show network fees separately from the transfer amount. - [ ] Explain whether the action can be reversed. - [ ] Warn when the destination is new, unrecognized, or user-entered. - [ ] Never request a seed phrase, private key, or wallet export. - [ ] Make the **Cancel** path as visible as the **Confirm** path. ## During wallet approval - [ ] Keep the app’s pending state visible while the wallet prompt is open. - [ ] Prevent accidental duplicate submissions. - [ ] Tell users not to approve a request they do not recognize. - [ ] Avoid claiming success before the app has sufficient confirmation evidence. - [ ] Preserve the intended action if the user returns from the wallet. ## After signing - [ ] Distinguish clearly between: - Not submitted - Submitted, outcome unknown - Confirmed - Rejected or failed - [ ] Provide a retry action only when retrying is safe. - [ ] Warn before retrying actions that could execute twice. - [ ] Offer a support reference such as a transaction signature when available. - [ ] Let users copy diagnostic details without exposing secrets. - [ ] Explain what the user can do next instead of showing only an error code. ## Failure cases to test - Wallet locked or disconnected - User rejects the request - Network or RPC timeout - App reloads during confirmation - Transaction expires or becomes invalid - Insufficient balance for amount plus fees - User switches wallet or network - Confirmation arrives after the UI timed out - The same button is clicked repeatedly ## Acceptance rule A transaction flow is ready when a user can answer three questions without contacting support: 1. **What was I about to approve?** 2. **Did it actually happen?** 3. **What is the safest next step?**

# Self-Directed Draft: Transaction Status That Admits Uncertainty **Product specification for Solana apps** **Problem:** After a user approves an action, an app can lose track of its outcome. Showing “failed” too early may prompt a duplicate attempt; showing “success” too early may mislead the user. **Core UI states** - **Awaiting approval:** The wallet prompt is open. No outcome is implied. - **Submitted:** Show the transaction signature if available, with a copy button. - **Checking:** Say “We’re checking the outcome,” not “Completed.” - **Confirmed:** Show the completed action and a clear next step. - **Not confirmed:** Explain what is known, what remains uncertain, and whether retry is safe to offer. **Retry rule:** Never make **Try again** the primary button while the original attempt’s outcome is unknown. Offer **Check again** instead. If the user chooses to start another attempt, explain that it could duplicate the action. **Acceptance checklist** - Closing or refreshing the page does not turn an unknown outcome into “failed.” - The status screen distinguishes wallet rejection from an unresolved submitted transaction. - Every status message uses plain language and avoids promising an outcome the app has not established.

# Self-Directed Draft: Solana Support Snapshot **Product specification for Solana wallets and apps:** Let users create a privacy-conscious diagnostic bundle when a transaction or account action needs support. ## Objective Reduce back-and-forth between users and support teams without requesting seed phrases, private keys, or unnecessary personal data. ## User flow 1. User taps **Get help**. 2. App shows exactly what will be included. 3. User reviews and removes optional fields. 4. App generates a copyable text snapshot or downloadable JSON file. 5. User shares it through their chosen support channel. ## Snapshot contents ```text Support Snapshot Generated: [local timestamp] App version: [version] Network: [cluster selected by the app] Wallet adapter: [adapter name, if available] Public wallet address: [full or shortened, user-controlled] Action: [send / swap / sign / create account / other] Transaction signature: [if available] Recent error message: [raw message] Readable status: [pending / confirmed / failed / unknown] Suggested next step: [contextual guidance] ``` ## Privacy guardrails - Never include seed phrases, private keys, wallet connection secrets, or signing payloads. - Make the public address optional. - Warn that transaction signatures and addresses are publicly visible identifiers. - Redact tokens that resemble secrets before copying. - Keep generation local by default. - Do not upload the snapshot automatically. - Let users inspect the final text before sharing. ## UI copy **Button:** `Create support snapshot` **Review notice:** “Check this information before sharing. It may contain public blockchain identifiers and technical error details. It will not include your private keys.” **Empty state:** “We couldn’t find a transaction signature. You can still share the action, error, and app version.” **Completion:** “Snapshot ready. Review it, then copy or download it.” ## Acceptance checklist - [ ] Snapshot generation works without a network request. - [ ] Sensitive credential fields are excluded by design. - [ ] Optional public identifiers have clear controls. - [ ] Raw errors are preserved alongside plain-language guidance. - [ ] Unknown values are labeled `unknown`, never guessed. - [ ] Copy and download actions provide visible confirmation. - [ ] The app documents how long any locally stored snapshot remains available.

# Self-Directed Draft: Solana Recipient Review Panel **Product specification for wallet-connected apps:** Help users verify a destination before sending tokens or initiating an account action. ## Objective Make the final recipient review explicit, readable, and resistant to copied-address mistakes—without claiming the app can determine ownership of an address. ## Review panel Display: - **Action:** “Send” / “Create account” / “Delegate” - **Asset and amount:** token symbol, decimal amount, and estimated network fee if available - **Recipient label:** user-entered label, such as “Treasury” - **Full address:** monospace, with copy button - **Short address:** first and last 4–6 characters - **Network:** Solana cluster selected by the app - **Warning:** “Verify this address independently. A confirmed transaction may not be reversible.” ## Required interaction 1. User pastes or selects a destination. 2. App normalizes whitespace but does not silently alter characters. 3. App shows the full address before confirmation. 4. User must explicitly confirm: **“I verified the recipient address.”** 5. Confirm button remains disabled until the checkbox is selected. 6. The final submitted address is displayed in the activity record. ## Address states - **Missing:** “Enter a recipient address.” - **Invalid format:** “This does not look like a valid Solana address.” - **Valid, unlabeled:** “Address format accepted. Ownership is not verified.” - **Saved label:** Show the label plus the full address. - **Changed after review:** Reset the verification checkbox and require review again. - **Unavailable metadata:** Do not replace the address with a blank, zero, or guessed identity. ## Suggested warning copy > Check every character of the recipient address before confirming. This app cannot verify who controls an address. Send only after you independently confirm the destination. ## Acceptance checklist - [ ] Full recipient address is visible before confirmation. - [ ] No address is shortened without an expansion or copy option. - [ ] A changed address invalidates prior confirmation. - [ ] Labels never imply verified ownership. - [ ] The selected network is visible. - [ ] Failed or cancelled submissions do not appear as completed transfers. - [ ] Confirmation text is generated from the exact amount, asset, and address being submitted.

# Self-Directed Draft: Solana Transaction Failure Explainer **Product spec for wallet-connected apps:** Turn failed transactions into actionable recovery steps instead of opaque error messages. ## Goal Help users understand what happened, what was affected, and what to try next—without implying that a failed transaction changed on-chain state. ## Required UI states ### 1. Submission pending - Show: “Waiting for wallet approval.” - Provide a cancel/close option if supported. - Do not label the transaction successful before confirmation. ### 2. Rejected by user - Show: “You canceled the transaction.” - Offer: **Try again** and **Return to activity**. - Avoid alarming language. ### 3. Sent, confirmation pending - Show the transaction identifier when available. - Label status as **Pending confirmation**. - Keep the action’s original intent visible, such as “Swap 1 token” or “Create listing.” ### 4. Failed before confirmation - Show: “The transaction was not confirmed.” - Explain that the app should verify the current account state before retrying. - Offer **Retry** and **View details**. ### 5. Confirmed but application state is delayed - Show: “Transaction confirmed; updating your account.” - Refresh relevant data. - Preserve the transaction identifier and link only when an application has a known, valid explorer destination. ## Error-message template > **Transaction not completed** > No confirmed change was detected. > **Possible reason:** {human-readable reason, if known} > **Try:** {specific next step} > Transaction ID: `{identifier, if available}` If the cause is unknown: > We couldn’t confirm this transaction. Check your wallet activity before retrying to avoid submitting the action twice. ## Safety rules - Never say “success” based solely on wallet submission. - Never describe a failed transaction as a balance change. - Preserve the wallet address and network context used for the attempt. - Disable duplicate submission while approval or confirmation is pending. - Make raw technical details expandable rather than hiding them entirely. - Ensure retrying creates a fresh, clearly identified attempt. ## Acceptance checklist - [ ] Every transaction has distinct approval, pending, confirmed, and failed states. - [ ] Users can copy the transaction identifier. - [ ] Retry guidance changes based on whether a transaction was submitted. - [ ] The UI does not imply state changes without confirmation. - [ ] Screen-reader users receive status updates. - [ ] Error text remains useful when no technical cause is available.

# Self-Directed Draft: Read-Only Data Degradation Checklist **Reusable checklist for Solana app teams:** Keep an app understandable when account data cannot be refreshed. An unavailable balance must never look like a zero balance. - [ ] Give each data panel an explicit state: **loading**, **current**, **stale**, **unavailable**, or **empty**. Use “empty” only after a successful response confirms no items. - [ ] Show when stale data was last refreshed. Label it as cached; do not present it as live. - [ ] If one request fails, preserve unaffected panels instead of replacing the whole page with an error. - [ ] Offer a manual **Retry** action. Prevent rapid repeated requests while a retry is in progress. - [ ] Keep read-only navigation available during data failures. Disable actions that require unverified balances or other missing inputs, with a short reason. - [ ] Never substitute `0`, an empty list, or a success message for a failed request. - [ ] When data returns, remove stale warnings only after the relevant panel has successfully refreshed. **Acceptance test:** Force a balance request to fail while another panel succeeds. The balance panel says **Unavailable** or **Stale**, the successful panel remains usable, and no action treats the missing balance as zero.

# Self-Directed Draft: Wallet Session Hygiene **Product spec for Solana apps:** Prevent stale account data from appearing after a wallet disconnect, account switch, or network change. **Required behavior** - Scope balances, activity, permissions, and saved selections to the active wallet address and network. - On session change, clear account-specific UI immediately and cancel or ignore responses from the previous session. - Remove old subscriptions before starting new ones. - Keep non-sensitive form drafts only if useful; require users to review them again before acting. - Show a neutral loading state until data for the new session is ready. Never briefly display the previous account’s data. **Acceptance checklist** - [ ] Switch accounts while a balance request is pending: the old response never renders. - [ ] Disconnect with an account page open: account-specific content disappears. - [ ] Change networks: cached balances and activity are not reused. - [ ] Reconnect the original account: its data is fetched or validated before display. - [ ] Repeat each test in two open tabs and with a slow connection.

# Self-Directed Draft: Solana Transaction Recovery Panel **Product spec:** A reusable UI component that helps users understand and recover from failed or delayed Solana transactions. ## Problem A wallet prompt may close without a clear result. Users need to know whether to retry, wait, refresh, or avoid submitting the same action twice. ## Core behavior - Display transaction state: **Preparing**, **Awaiting signature**, **Submitted**, **Confirmed**, or **Needs attention**. - Show a short, plain-language status message. - Provide a transaction identifier when available, with a copy button. - Offer context-appropriate actions: - **Retry** when signing or submission fails. - **Refresh status** when confirmation is pending. - **Return to app** after confirmed completion. - Warn before retrying if a prior submission may still be processing. - Preserve the user’s intended action details during recovery. ## Error message patterns - **Signature declined:** “No transaction was submitted. You can try again.” - **Submission failed:** “The network did not accept this transaction. Review the action and retry.” - **Confirmation pending:** “Your transaction was submitted. We’re still checking its status.” - **Unknown result:** “We could not confirm the outcome. Avoid repeating the action until you refresh.” ## Acceptance checklist - [ ] Every state has a visible status label. - [ ] Retry is unavailable while a submission is actively pending. - [ ] Unknown outcomes do not claim success or failure. - [ ] Transaction identifiers are copyable when present. - [ ] The component supports keyboard navigation and screen readers. - [ ] Error text avoids unexplained technical terms. - [ ] The app records no sensitive wallet information in client-visible logs. ## Success measure Users can determine the next safe action within one screen, without guessing whether they might submit the same transaction twice.

# Self-Directed Draft: Transaction Intent Preview **Product spec:** Give Solana users a plain-language preview of what an app is asking them to sign before the wallet prompt appears. ## Problem Wallet prompts often expose technical transaction details without clearly explaining the intended action. Users need a quick way to review recipient, assets, amounts, and permissions before approving. ## MVP ### Preview panel Display: - **Action:** “Swap,” “Send,” “Deposit,” or “Create account” - **Assets and amounts:** Include token symbols and raw values when available - **Destination:** Show a shortened address with copy and expand controls - **Accounts affected:** Identify accounts being created, modified, or closed - **Fees:** Separate network fee, app fee, and any priority fee when known - **Warnings:** Flag unknown instructions, unexpected programs, or missing metadata ### Review states - **Ready to review** - **Some details unavailable** - **Simulation failed** - **Transaction changed—review again** The sign button remains disabled until the preview is rendered or the user explicitly acknowledges unavailable details. ## Example copy > **Review transaction** > Swap 10 USDC for an estimated SOL amount > Destination: `8xK…4pQ` > Network fee: estimated > > **Check carefully:** This transaction includes an instruction from an unrecognized program. > > [View technical details] [Cancel] [Continue to wallet] ## Acceptance criteria - The preview is generated from the exact transaction currently queued for signing. - Any transaction mutation invalidates the prior review. - Unknown or undecoded instructions are labeled clearly rather than guessed. - Amounts distinguish estimates from guaranteed values. - Users can expand every shortened address. - The app never describes an action as successful before confirmation. ## Implementation notes - Use a parser with a strict fallback for undecoded instructions. - Keep a structured internal representation: instruction, program, accounts, token changes, fees, and confidence. - Record the preview version alongside the transaction request for debugging. - Make the panel usable on mobile before opening the wallet.

# Self-Directed Draft: Network Mismatch Guardrail **Product spec:** Prevent a Solana app from presenting an action as ready when its selected network and the connected wallet’s network do not match. **Core behavior** - Show the app’s selected network beside the wallet connection status. - Before enabling an action, check whether the wallet can sign for that network. - If they differ, disable the action and show: **“Network mismatch. This app is set to [network], but your wallet is connected to [network]. Check both settings before continuing.”** - Provide **Open wallet settings** only when the wallet supports it; otherwise give plain instructions. Never imply the app changed the wallet’s network. **Acceptance checklist** - The warning appears before any approval prompt. - A network change clears previously prepared transaction details. - An unknown wallet network is labeled **Unknown**, not guessed. - Test the guardrail on initial connect, reconnect, and a network change while the page is open.

# Self-Directed Draft: Safe Retry for Solana App Actions **Product spec:** Help users recover when an app loses contact with the network after they approve an action, without inviting an accidental duplicate. **Trigger:** The app has submitted a transaction but cannot confirm its outcome before its normal waiting period ends. **User-facing state** > **Outcome not confirmed** > Your wallet approved this action, but the app can’t confirm whether it completed. Don’t repeat it yet. We’ll check again. Show the action name, submission time, and transaction signature **only if the app has one**. Offer **Check status** and **Copy details**; do not show **Try again** in this state. **Recovery rules** - If the app has a signature, check its status before offering any resubmission. - If confirmed, show **Completed**. If definitively failed, explain the failure and offer a fresh attempt. - If the outcome remains unknown, keep that label. Never turn a timeout into “Failed.” - If no signature is available, say **“We couldn’t verify whether this was submitted”** and direct the user to review recent wallet activity before starting over. **Acceptance checklist:** Test slow confirmation, dropped connection after approval, known failure, missing signature, and a user reopening the app mid-check. In every case, the interface must distinguish **unknown** from **failed**.

# Self-Directed Draft: Transaction Intent Receipt **Product brief:** Give users a compact, human-readable explanation of what a Solana transaction is intended to do before they approve it. ## Core experience Before the wallet prompt, show a receipt containing: - **Action:** “Swap,” “Send,” “Stake,” “Create account,” or “Unknown action” - **Assets and amounts:** Include token symbols only when the app can resolve them reliably - **From / to:** Use shortened addresses with a copy button - **Estimated network fee:** Label as an estimate - **Account changes:** New accounts created, tokens received, or permissions affected - **Risk flags:** “Unknown program,” “Amount may vary,” or “This action cannot be easily reversed” - **Simulation status:** Clearly show `Not simulated`, `Simulation succeeded`, or `Simulation returned an error` Primary button: **Review in wallet** Secondary action: **Cancel** ## Safety rules 1. Never describe an unknown instruction as safe or successful. 2. Do not hide instructions merely because they are unfamiliar. 3. Separate app estimates from wallet-confirmed values. 4. Use “may,” “estimated,” and “expected” where outcomes are not guaranteed. 5. Preserve the raw transaction details behind **View technical details**. 6. Require explicit confirmation when the recipient, authority, or spend amount is unclear. ## Suggested copy > **You’re about to approve an action** > Send **25 USDC** from your connected account to **7xK…pQ2**. > Estimated network fee: **less than 0.001 SOL**. > This request includes **1 unfamiliar instruction**. Review the wallet prompt carefully. If parsing fails: > **We couldn’t fully explain this request.** > Review the technical details in your wallet before approving. ## Acceptance checklist - [ ] The receipt appears before the wallet request. - [ ] Amounts, recipients, and fees are visually distinct. - [ ] Unknown instructions are disclosed. - [ ] Simulation results cannot be mistaken for execution. - [ ] The user can cancel without signing. - [ ] Technical details remain available. - [ ] Copy avoids promising a successful outcome. - [ ] Tests cover malformed, partial, and multi-instruction transactions.

# Self-Directed Draft: Opt-In Support Bundle for Solana Apps **Product brief:** Help users report a confusing transaction without sending a screenshot of their wallet or exposing unnecessary account details. **User flow** 1. From an activity item, select **Get help with this action**. 2. Show a preview containing the app action, selected network, displayed status, timestamp, and—if available—the transaction signature. 3. Let the user remove optional fields and add a short description. 4. Offer **Copy support details**. Do not send anything automatically. **Copy for the preview** > Review what you’re sharing. A transaction signature can reveal public activity associated with this action. Remove it if you don’t want to include it. **Acceptance checklist** - Mark missing or unconfirmed information as **Unknown**, not **Failed** or **Complete**. - Never include seed phrases, private keys, wallet session tokens, or raw signing requests. - Keep the user’s description separate from app-generated details. - Make copying work even when no transaction signature is available. - After copying, say **Copied to clipboard**—not **Support request submitted**.

# Self-Directed Draft: Failed-Action Recovery for a Solana App **Product spec:** When an action fails, help the user decide what to do next without implying it succeeded or asking them to sign blindly. | App can identify | Message | Primary action | |---|---|---| | User declined the wallet request | “You declined the request. Nothing was submitted by this attempt.” | **Try again** | | Request expired before submission | “This request expired. Review a fresh request before signing.” | **Prepare again** | | App cannot confirm the outcome | “We can’t confirm whether this action completed. Check its status before trying again.” | **Check status** | | Other failure | “This action couldn’t be completed. No retry has started.” | **Review details** | **Interface requirements** - Show the action name and network alongside the error. - Separate **Try again** from **Check status**. Never automatically resubmit an action with an uncertain outcome. - If the app has a transaction signature, offer a copy button; otherwise, do not imply one exists. - Keep technical details expandable: error text, time, and a support-ready copy of non-sensitive diagnostics. - Before any retry that requires a wallet signature, show the current action details again.

# Self-Directed Draft: Read-Only Mode for a Solana App **Product brief:** Let visitors explore an app before connecting a wallet. Keep wallet-dependent actions visible, but explain why they are unavailable. **Interface requirements** - Label the mode **Browsing without a wallet**. Don’t imply that an account or holdings have been checked. - Show public product information normally. Mark personal balances, positions, and history as **Connect to view**, rather than displaying zero. - On a wallet-dependent action, show a short explanation before the connection prompt: “Connect a wallet to view your account and continue.” - Provide a persistent **Connect wallet** button and a way to dismiss the prompt without losing the visitor’s place. **Acceptance checklist** - [ ] No personal data is inferred from read-only mode. - [ ] A declined or unavailable wallet connection leaves the page usable. - [ ] Disconnecting returns personal fields to **Connect to view**. - [ ] Keyboard users can open, dismiss, and navigate past the prompt. - [ ] Analytics distinguish “viewed action” from “connected wallet”; neither is counted as a completed action.

# Self-Directed Draft: Solana Transaction Preview Panel **Purpose:** Help users understand a wallet request before signing, especially when instructions involve unfamiliar programs or token accounts. ## Core interface ### Header - **Action:** “Swap,” “Send,” “Create account,” or **Unknown action** - **Network:** Clearly display the intended cluster - **Status:** “Ready for your review” ### Human-readable summary Show: - Tokens leaving the wallet - Tokens expected to arrive - Recipient or destination - Estimated network fee - New accounts that may be created - Whether the amount is fixed or variable ### Risk and uncertainty labels Use plain-language badges: - **Verified by app:** Matches the action the user initiated - **Variable amount:** Final amount may differ - **New account:** This transaction creates an account - **Unknown instruction:** The app cannot explain part of the request - **Requires attention:** Review before signing Never hide an instruction merely because it is difficult to decode. ## Confirmation rules - Disable **Sign** until the preview loads or explicitly shows why it cannot. - If any instruction is unknown, place it above the confirmation button. - Use **Cancel** as the equally visible alternative. - Do not describe a transaction as successful until confirmation is independently observed. - After signing, show a receipt containing the signature, timestamp, and resulting state when available. ## Suggested copy **Known action:** > You’re about to send **2.00 USDC** to **Destination ending in 4K9P**. **Variable outcome:** > The final received amount may change because this action uses a variable exchange rate. **Unknown instruction:** > This request includes an instruction we can’t explain. Review the wallet prompt carefully, or cancel. **Post-signing state:** > Signature submitted. We’re checking the result—avoid submitting the same action again until the status is resolved. ## Acceptance checklist - [ ] User can identify every asset leaving the wallet. - [ ] Recipient and destination are visible before signing. - [ ] Fees are labeled as estimates where applicable. - [ ] Unknown instructions are surfaced, not buried. - [ ] Cancel and Sign are visually distinct. - [ ] The app preserves the signed transaction’s status for recovery. - [ ] No screen requests a seed phrase or private key.

# Self-Directed Draft: Safe Transaction Retry Checklist **For Solana app teams:** Use this checklist when designing a “Try again” button. The goal is to prevent a slow or unclear result from prompting an accidental second action. - [ ] Record the user’s intended action locally before requesting a signature. - [ ] After submission, show a **Checking status** state. Do not treat a timeout as a failed transaction. - [ ] If a signature is available, check its status before offering another submission. - [ ] Separate **Confirmed**, **Failed**, and **Status unknown** in the UI. Give each state a distinct next step. - [ ] When status is unknown, offer **Check again** before **Create a new transaction**. - [ ] Make clear that creating a new transaction may repeat the action if the first one succeeded. - [ ] For actions with off-chain effects, use an application-level request ID so repeated submissions can be recognized. - [ ] Test slow responses, dropped connections, expired transactions, and users clicking the button twice. **Suggested unknown-status copy:** “We can’t confirm the result yet. Check again before starting a new transaction to avoid repeating this action.”

# Self-Directed Draft: Solana Wallet Issue Reporter **Product brief:** A privacy-conscious in-app form that turns vague wallet failures into actionable bug reports without asking users to share seed phrases, private keys, or sensitive account data. ## User flow ### 1. Describe the issue Offer selectable categories: - Wallet will not connect - Transaction did not appear to complete - Transaction failed - Balance or token display looks wrong - App shows an unexpected network - Other ### 2. Capture safe diagnostics Automatically include, with clear consent: - App version - Browser and operating system - Wallet name and adapter version, if available - Network or cluster selected by the app - Public wallet address, optionally shortened in the report - Transaction signature, if the user provides one - Timestamp and local timezone - Sanitized error message Never collect: - Seed phrases - Private keys - Wallet passwords - Secret recovery material - Unnecessary personal information ### 3. Add user context Prompt: > What were you trying to do? Provide a short text field and optional screenshot upload. Add a warning beneath uploads: > Check screenshots for private information before sending. ### 4. Review before sending Show a plain-language summary: - “This report includes your public wallet address.” - “No private keys or recovery phrases are requested.” - “Remove any field before submitting.” Buttons: - `Edit report` - `Copy diagnostic summary` - `Send report` ## Example report format ```text Issue: Transaction failed Time: [local timestamp] App version: [version] Wallet: [wallet name/version] Network: [selected network] Public address: [optional] Signature: [optional] Error: [sanitized message] User description: [free text] ``` ## Product requirements - Generate a local report preview before submission. - Make every automatically captured field removable where practical. - Redact obvious secret-like strings from pasted error text. - Provide a copyable report for users who prefer community support. - Preserve the original wallet error for debugging, but display a human-readable explanation beside it. - Never imply that a copied signature proves funds were received or a transaction finalized. ## Acceptance checklist - [ ] A first-time user can create a report without technical knowledge. - [ ] The form clearly distinguishes public data from secret data. - [ ] No seed phrase or private key field exists. - [ ] Reports remain useful when the wallet connection fails. - [ ] Users can cancel without submitting. - [ ] Support staff can reproduce the reported app state from the included context. - [ ] Error text is sanitized before leaving the device.

# Self-Directed Draft: Token Identity Card **Product brief:** A reusable component for Solana apps that helps users distinguish a token’s display name from its mint address before they act. **Display requirements** - Show the token name and symbol as labels, not proof of identity. - Show a shortened mint address with a one-click way to reveal and copy the full address. - Label the active environment, such as mainnet or devnet, beside the address. - If token metadata is missing, display “Unknown token” rather than guessing a name or icon. **Safety rules** - Never use an icon, name, or symbol alone to confirm which token is selected. - Do not call a token “official” or “verified” without an explicitly defined verification source. - When two tokens share a name or symbol, make their mint addresses visible in the selection list. **Acceptance checks** - A user can inspect and copy the full mint address before confirming an action. - Long names and addresses remain readable on mobile. - Missing or conflicting metadata does not block access to the mint address.

# Self-Directed Draft: Solana Transaction Flow Preflight Kit **Purpose:** A reusable UX and QA checklist that helps Solana teams make wallet-to-confirmation flows understandable, recoverable, and safe. ## Required states For each transaction action, design and test: 1. **Disconnected** - CTA: `Connect wallet` - Explain why connection is needed. 2. **Wrong or unsupported network** - Message: `Your wallet is connected, but this network is not supported here.` - CTA: `Switch network` or `Use another wallet` 3. **Ready to submit** - Show action name, destination/context, and any user-visible cost. - CTA: `Review transaction` 4. **Wallet approval pending** - Message: `Approve this request in your wallet.` - Never imply completion before confirmation. 5. **Rejected** - Message: `Transaction canceled in your wallet.` - CTA: `Try again` 6. **Simulation or preparation failed** - Message: `This action could not be prepared. Your wallet was not charged.` - Provide a support path and preserve technical details for diagnostics. 7. **Submitted, confirmation pending** - Message: `Transaction submitted. Waiting for confirmation.` - Show a non-blocking loading state and allow the user to remain on the page. 8. **Confirmed** - Message: `Transaction confirmed.` - Show the resulting app state, not only a success toast. 9. **Unknown outcome** - Message: `We could not verify the result yet. Check your wallet activity before trying again.` - Prevent accidental duplicate submissions. ## Acceptance checklist - [ ] Every CTA names the action, such as `Swap`, `Mint`, or `Deposit`. - [ ] Approval, submission, and confirmation are separate states. - [ ] A rejected request is not labeled as a failed onchain transaction. - [ ] Errors include one actionable next step. - [ ] Retry behavior prevents accidental duplicate actions. - [ ] No UI requests seed phrases, private keys, or wallet secrets. - [ ] Technical error data can be copied for support. - [ ] Refreshing the page does not falsely reset a pending action. - [ ] Mobile wallet handoff has a visible return path. - [ ] Success changes the relevant balance, ownership, or activity view. ## Minimal event model ```text wallet_connected transaction_reviewed wallet_approval_requested wallet_approval_rejected transaction_preparation_failed transaction_submitted transaction_confirmed transaction_outcome_unknown ``` Attach only operational metadata needed for debugging, such as action type, app version, and failure stage. Avoid collecting secrets or unnecessary personal data.

# Self-Directed Draft: Transaction Error Translator **Product specification:** A small UI component for Solana apps that turns a failed transaction attempt into a useful next step without hiding the original error. **Inputs:** Failure stage (`wallet`, `simulation`, `submission`, or `confirmation`), raw error, app action label, and optional transaction signature. **Output:** A short headline, one recommended action, and a collapsed “Technical details” section containing the unmodified error. Show a signature only when one exists. | Situation | Headline | Recommended action | |---|---|---| | User rejects a wallet request | “Request cancelled” | “Nothing was submitted. You can try again.” | | Wallet connection is unavailable | “Wallet unavailable” | “Check that your wallet is open, then retry.” | | Simulation fails | “This action can’t proceed as prepared” | “Review the action details before trying again.” | | Submission outcome is unknown | “Status not confirmed” | “Check the activity view before retrying to avoid a duplicate action.” | | Unrecognized error | “We couldn’t complete this action” | “Try again later or share the technical details with support.” | **Acceptance criteria:** Never label an attempt “failed” solely because confirmation timed out; never promise that retrying is safe when submission may have occurred; never request a seed phrase or private key.

# Self-Directed Draft: Solana Transaction Support Intake **Product brief:** A support form that helps a team investigate a transaction without asking users for wallet secrets. ## User-facing form **What were you trying to do?** [Short description] **What happened?** - The wallet did not open - I rejected the request - The app showed an error - I submitted it but cannot tell whether it completed - Something else: [text] **Optional details** - Transaction signature: [text] - Wallet public address: [text] - Network shown in the app: [text] - Approximate time and timezone: [text] - Error message: [text] **Safety note:** Never share a seed phrase, private key, password, or recovery code. A screenshot should hide balances or personal information you do not want to share. ## Team-facing behavior - Keep “submitted” separate from “confirmed”; do not infer an outcome from a user’s description alone. - If a signature is provided, show it as a searchable field in the support queue. - If no signature exists, route the report to a pre-submission category. - Let support mark the outcome **resolved**, **unresolved**, or **needs user follow-up**, with a short reason. **Success criterion:** A support teammate can identify the attempted action, the point of failure, and the next question to ask—without requesting sensitive credentials.

# Self-Directed Draft: Solana Release Readiness Checklist **Purpose:** Help a Solana team ship a wallet-connected feature with clear user states, controlled failure handling, and useful diagnostics. ## 1. User flow - [ ] Explain the action before wallet connection. - [ ] Show network/cluster context in the interface. - [ ] Distinguish **connect**, **sign**, **submit**, **confirmed**, and **failed** states. - [ ] Never describe an action as complete solely because a wallet opened. - [ ] Provide a safe way to cancel or return without trapping the user. ## 2. Transaction handling - [ ] Set explicit limits for stale blockhashes, retries, and request timeouts. - [ ] Prevent duplicate submissions caused by repeated clicks. - [ ] Keep a client-side request identifier for each attempted action. - [ ] Treat confirmation as a separate state from submission. - [ ] Make retry behavior explicit: retry the same intent only when safe. ## 3. Error experience - [ ] Use plain-language messages first; place technical details behind “View details.” - [ ] Separate user action errors from network, wallet, and application errors. - [ ] Avoid claiming funds were or were not moved unless the app has checked the relevant state. - [ ] Offer a support-report copy action with sensitive fields removed or redacted. - [ ] Include a clear next step: retry, refresh state, switch account, or contact support. ## 4. Security and privacy - [ ] Request only the wallet permissions required for the feature. - [ ] Never request or store seed phrases or private keys. - [ ] Validate amounts, accounts, program addresses, and user inputs before building instructions. - [ ] Keep secrets out of logs, analytics events, screenshots, and copied reports. - [ ] Review every external link and label destinations clearly. ## 5. Observability Record a minimally identifying event for each attempt: ```text event: transaction_attempt request_id: <unique client id> action: <controlled action name> cluster: <app-supplied cluster> wallet_connected: true|false submitted: true|false confirmed: true|false error_class: <controlled category or null> ``` Do not log private keys, seed phrases, raw wallet signatures, or unnecessary personal data. ## 6. Pre-release tests - [ ] Wallet disconnected. - [ ] User rejects connection. - [ ] User rejects signing. - [ ] Expired or invalid transaction. - [ ] Slow RPC response. - [ ] Duplicate click. - [ ] Account changes between preview and signing. - [ ] App reload during confirmation. - [ ] Partial or ambiguous status. - [ ] Unsupported cluster or wallet. ## Release gate Ship only when every test has a visible user outcome, a bounded retry policy, and a diagnostic path that does not expose sensitive information.

# Self-Directed Draft: Wallet Action Preview — Product Specification **Purpose:** Give users a plain-language preview of a Solana transaction before they approve it, without overstating what simulation can guarantee. ## Core experience Before signing, display a compact preview card: - **Action:** “Swap 1.00 token A for approximately 24.5 token B” - **Network:** Cluster name supplied by the app - **Estimated network fee:** Show the estimate, or “Unavailable” - **Expected account changes:** Tokens sent, received, created, or closed - **Required approvals:** Number of signatures and approving wallets - **Simulation status:** `Passed`, `Failed`, `Not available`, or `Not run` - **Warnings:** Human-readable risks or missing information ## Safety rules - Never describe an action as guaranteed because simulation passed. - Use “estimated,” “expected,” and “based on simulation” where appropriate. - If simulation fails, explain that signing may still be possible but the app cannot predict success. - Mask account addresses by default, with a copy option. - Clearly distinguish network fees from protocol, priority, and application fees. - Do not claim funds moved until a confirmed result is independently available. ## Interaction **Primary button:** `Review and approve` **Secondary actions:** `View technical details`, `Cancel` Technical details should include: - Recent blockhash or transaction version, when available - Program addresses involved - Instruction count - Simulation logs, collapsed by default - Source of fee and balance estimates - Timestamp of preview generation ## Empty and error states - **Incomplete data:** “Some effects could not be determined. Review the technical details before approving.” - **Simulation unavailable:** “The preview could not be simulated. Check the network connection or continue only if you understand the action.” - **Changed transaction:** Invalidate the preview if the transaction changes after review and require a fresh preview. ## Acceptance criteria - Users can identify what they may send and receive before signing. - Every unavailable estimate is labeled rather than silently omitted. - A changed transaction cannot be approved from a stale preview. - The UI distinguishes simulation output from confirmed transaction results. - Sensitive account data is not exposed by default.

# Self-Directed Draft: Transaction Failure Report — Product Spec **Purpose:** Help a Solana app user report a failed action without copying a confusing error or exposing sensitive wallet data. **User flow** 1. When an action fails, show: “This action didn’t complete.” Do not imply funds moved or remained unchanged unless the app can confirm it. 2. Offer **Try again** and **Copy support report**. Keep the original action visible so the user knows what failed. 3. Preview the report before copying it. Let the user remove optional fields. **Report format** ```text Action: [app-defined label] Time: [local timestamp, with timezone] App version: [version] Network: [network label] Result: [simulation failed / submission failed / confirmation unknown] Error code: [code, if available] Transaction signature: [only if one exists; optional] ``` **Safety requirements** - Never include seed phrases, private keys, wallet-export data, or full request logs. - Treat “confirmation unknown” as distinct from “failed.” Advise users to check the action’s status before retrying when a duplicate action could matter. - Do not send reports automatically. Copying or submitting one requires an explicit user action. **Acceptance test:** A user can distinguish a known failure from an unknown outcome, preview exactly what they will share, and create a report without exposing credentials.

# Self-Directed Draft: Solana Program Release Checklist A reusable pre-release checklist for teams shipping a Solana program or client update. ## 1. Scope and compatibility - [ ] Record the release identifier and intended change. - [ ] List affected instructions, accounts, PDAs, and clients. - [ ] Define whether existing accounts remain readable and writable. - [ ] Document any migration, initialization, or deprecation steps. - [ ] Confirm client and program versions are compatible. ## 2. Account and instruction safety - [ ] Validate every signer, owner, writable account, and PDA seed. - [ ] Reject unexpected account relationships explicitly. - [ ] Check authority changes for correct signer requirements. - [ ] Confirm serialized layouts and discriminators are unchanged or migrated safely. - [ ] Verify arithmetic bounds and error paths. - [ ] Ensure failed instructions do not leave partial state changes. ## 3. Fees and compute - [ ] Measure compute usage for normal and worst-case inputs. - [ ] Test transactions near expected account-size and instruction-count limits. - [ ] Identify any new priority-fee or compute-budget requirements. - [ ] Confirm users can understand expected costs before approval. ## 4. Testing matrix - [ ] Unit-test success and failure cases. - [ ] Test malformed accounts, missing signers, stale state, and duplicate accounts. - [ ] Test repeated, reordered, and replay-like calls where relevant. - [ ] Test empty, minimum, maximum, and boundary values. - [ ] Run client tests against the exact deployed interface. - [ ] Record reproducible commands and expected outcomes. ## 5. Deployment controls - [ ] Define the target environment before deployment. - [ ] Verify the upgrade authority and ownership settings. - [ ] Back up required addresses, configuration, and migration data. - [ ] Use a staged rollout or operator-controlled pause where appropriate. - [ ] Assign an owner for rollback or containment decisions. - [ ] Do not publish addresses or commands until they are manually verified. ## 6. User-facing readiness - [ ] Explain what changed in plain language. - [ ] Show affected actions, costs, and required permissions. - [ ] Provide recovery guidance for interrupted or rejected operations. - [ ] Mark unsupported clients or old versions clearly. - [ ] Include a support template requesting wallet, instruction, error, and environment details—never secret keys. ## Release sign-off **Program owner:** **Client owner:** **Target environment:** **Release identifier:** **Migration required:** Yes / No **Rollback or containment path:** **Known limitations:** **Final reviewer:** **Date:**

# Self-Directed Draft: Wallet Connection Design Brief **Product:** A wallet-connection flow for a Solana app that makes account selection clear before the user begins an action. ## User experience 1. **Connect:** Show a neutral “Connect wallet” button. Do not imply that connecting authorizes a transaction. 2. **Select:** If the wallet offers multiple accounts, let the user choose one and display its shortened address. 3. **Verify:** Before any account-dependent action, show the selected address and intended network together. 4. **Change:** Keep “Switch account” accessible without requiring the user to restart the page. 5. **Disconnect:** Remove the connected-account display and clear account-specific UI data from the current session. ## Edge states - **Connection declined:** “No wallet connected. You can try again.” - **Wrong network:** Name the network the app expects; do not present an action as ready. - **Account changed externally:** Pause account-dependent actions until the screen reflects the new selection. - **Wallet unavailable:** Offer a retry, not a dead-end error. ## Acceptance checklist - [ ] The displayed account matches the account used to prepare the next action. - [ ] A network mismatch blocks that action with a specific explanation. - [ ] Switching accounts refreshes balances and permissions shown on screen. - [ ] Connecting alone never triggers a signing request. - [ ] Disconnecting leaves no stale account-specific controls enabled.

# Self-Directed Draft: Solana Failure Report ## Product specification A developer-facing report generator that turns a failed Solana operation into a compact, reproducible debugging packet. ### Goal Reduce back-and-forth between users, support teams, and engineers when an operation fails. ## Report contents - **Operation label:** e.g. “Deposit” or “Claim” - **Network and environment** - **Wallet public key** - **Relevant account addresses** - **Transaction signature**, if one exists - **Block or slot context**, if available - **Observed error message** - **Simulation result**, if available - **Recent client actions** - **Expected vs. observed outcome** - **Privacy controls:** redact balances, metadata, and sensitive fields ## User flow 1. User selects **Create failure report**. 2. The app gathers only locally available diagnostic data. 3. The user reviews and removes sensitive fields. 4. The app exports: - human-readable Markdown - structured JSON 5. The report receives a local reference ID for support conversations. ## Example Markdown output ```md # Solana Failure Report ## Operation Deposit ## Environment - App version: 0.0.0 - Network: user-provided - Wallet: redacted ## Transaction - Signature: user-provided or unavailable - Slot: user-provided or unavailable ## Expected Deposit completes and balance updates. ## Observed Wallet approval completed, but the app did not show a completed deposit. ## Diagnostics - Simulation: unavailable - Error: user-provided - Client timestamp: 2025-01-01T00:00:00Z ## Reproduction notes 1. Connect wallet. 2. Select deposit amount. 3. Submit transaction. 4. Observe result. ## Redaction review [ ] Wallet address [ ] Account addresses [ ] Amounts [ ] User notes ``` ## Implementation requirements - Never infer success from wallet approval alone. - Distinguish missing data from negative results. - Preserve original error text alongside normalized categories. - Generate reports offline where possible. - Make export and deletion explicit. - Avoid collecting private keys or seed phrases. ## Success criteria - A support engineer can understand the failure without requesting the same basics again. - Users can inspect every field before sharing. - Reports remain useful when no transaction signature exists.

# Self-Directed Draft: Solana Action Receipt ## Product specification A compact post-action screen that confirms what a user attempted, what the app observed, and what remains uncertain—without treating wallet approval alone as proof of completion. ### Goal Give users a clear, reviewable result after signing a Solana transaction. ## Receipt layout **Status** - Confirmed - Pending - Failed - Needs review **Human-readable summary** > You attempted to deposit 25 USDC into Vault A. **Observed details** - Network/environment - App action - Asset and amount - Destination or program label - Confirmation state - Time recorded by the app **Technical details** - Transaction signature, shown as copyable text - “View in explorer” button only when the app has a configured explorer URL - Expandable instruction and error details ## State rules - **Confirmed:** show only when the app’s configured confirmation check succeeds. - **Pending:** explain that the result has not been verified yet; provide refresh and retry guidance. - **Failed:** show the returned error when available; distinguish rejection from execution failure. - **Needs review:** use when the app cannot reliably match the observed result to the intended action. ## Safety copy > A wallet approval means the transaction was signed. This receipt reflects the status currently observed by the app. > If the details look unfamiliar, stop and contact the app’s support channel before retrying. ## Acceptance checklist - Never display “success” solely because a wallet returned a signature. - Preserve the signature for support and debugging. - Make pending status visually distinct from failure. - Explain retry consequences before offering a retry button. - Avoid exposing private keys, seed phrases, or sensitive wallet metadata. - Test rejection, timeout, failed execution, duplicate submission, and refresh scenarios. ## Reusable UI copy **Pending:** “Your transaction was submitted, but completion has not been verified.” **Failed:** “The transaction did not complete. Review the error before trying again.” **Rejected:** “The wallet declined the request. No completion was recorded by the app.” **Retry:** “Retry only if you understand whether the first attempt changed anything.”

# Self-Directed Draft: Solana Sign-Intent Card ## Product specification A reusable pre-signing component that explains what a Solana transaction is intended to do before the user opens their wallet. ### Goal Help users make an informed signing decision without exposing raw instruction data as the primary explanation. ## Card content - **Action title:** “Swap tokens,” “Deposit,” or “Update settings” - **Assets involved:** token names, amounts, and direction - **Estimated network fee:** clearly labeled as an estimate - **Accounts affected:** concise labels for user-owned accounts - **Permission changes:** prominently flag authority, delegate, or ownership changes - **Risk notice:** identify irreversible or externally controlled actions - **Technical details toggle:** expandable instruction and account metadata - **Signing CTA:** “Review in wallet” - **Cancel CTA:** “Not now” ## Safety states ### Low-risk Show a short summary and normal review controls. ### Sensitive Add a highlighted warning when the transaction changes permissions, moves valuable assets, or interacts with an unfamiliar program. ### Unreadable If the app cannot confidently interpret the transaction: > **Review carefully** > This action contains details we cannot fully explain. Open your wallet to inspect the complete request before signing. Disable reassuring language such as “safe” or “guaranteed.” ## Copy rules - Use plain language before technical terminology. - Never imply that signing is required. - Never hide fees, account changes, or authority changes. - Distinguish estimates from confirmed outcomes. - Preserve the wallet’s final review as the source of truth. ## Component API ```ts type SignIntent = { title: string summary: string assets?: Array<{ direction: "in" | "out" symbol: string amount: string }> estimatedFee?: string affectedAccounts?: string[] permissionChanges?: string[] warnings?: string[] technicalDetails?: string interpretability: "clear" | "partial" | "unknown" } ``` ## Acceptance checklist - [ ] User can understand the intended action without reading raw data. - [ ] Asset movement is shown with direction. - [ ] Permission changes receive prominent treatment. - [ ] Unknown or partial interpretation is disclosed. - [ ] Canceling does not trap the user in the flow. - [ ] Technical details remain available for advanced users. - [ ] Copy avoids guarantees about transaction success or safety.

# Self-Directed Draft: Solana Wallet Connection Recovery Kit ## Product specification A reusable connection flow for Solana apps that helps users connect the intended wallet, switch environments, and recover from rejected or stale connection attempts. ### Goal Reduce confusion around wallet connection without hiding important security decisions. ## User flow 1. **Choose wallet** - Display installed wallet options. - Provide a clear “Install wallet” state when a wallet is unavailable. - Never imply a wallet is connected until the app receives confirmation. 2. **Confirm environment** - Show the app’s expected cluster or environment. - If the wallet reports a different environment, explain the mismatch plainly. - Offer “Switch network” only when supported; otherwise show instructions. 3. **Connect** - Disable duplicate connection clicks. - Show progress text: `Waiting for wallet approval…` - Keep the user on the same page after approval. 4. **Recover** - Rejected request: “Connection canceled. Try again when ready.” - Wallet locked: “Unlock your wallet, then retry.” - Stale session: offer `Disconnect and reconnect`. - Unknown error: provide a short error ID for support logs, without exposing secrets. ## UI copy **Disconnected** `Connect a wallet to continue.` **Wrong environment** `Your wallet is using a different network than this app. Switch networks or choose another wallet.` **Connected** `Connected: [shortened address]` `Disconnect` **Security reminder** `Only connect a wallet you control. Review every wallet prompt before approving.` ## Acceptance checklist - [ ] No wallet is selected by default. - [ ] Address is shortened visually but copied in full on explicit user action. - [ ] Connection requests cannot be triggered repeatedly. - [ ] Rejection and cancellation have separate, understandable messages. - [ ] The app clears stale connection state. - [ ] Wallet prompts are never described as transactions unless they are transactions. - [ ] No seed phrase, private key, or secret data is requested. - [ ] Accessible keyboard focus and screen-reader labels exist for every state. - [ ] Error telemetry excludes addresses, signatures, and wallet payloads by default. ## Implementation boundary This kit covers connection UX only. Transaction construction, signing, submission, and confirmation should remain separate modules so users can distinguish “connected” from “action completed.”

# Self-Directed Draft: Solana Transaction Recovery Panel ## Product specification A reusable UI component that helps users recover from pending or failed Solana transactions without guessing whether to retry. ### Purpose Make transaction outcomes understandable and provide safe next steps when confirmation is delayed or unsuccessful. ## Component states ### 1. Submitted > **Transaction submitted** > Your transaction was sent to the network. We’re waiting for confirmation. > > Keep this window open or check your wallet activity. Actions: - `View transaction` - `Cancel` (dismisses the panel only) ### 2. Confirmed > **Transaction confirmed** > The network confirmed your transaction. > > `View details` ### 3. Failed > **Transaction failed** > The network did not complete this transaction. Your wallet may allow you to try again. > > **Possible next steps:** > - Review the transaction details > - Check your balance and network selection > - Try again only if the intended action is still correct Actions: - `View details` - `Try again` - `Close` ### 4. Still pending > **Confirmation is taking longer than expected** > We haven’t received a final result yet. Avoid repeated submissions until you know whether the first attempt completed. > > `Refresh status` ### 5. Unknown result > **Status unavailable** > We couldn’t determine the final result. Check your wallet activity or transaction details before retrying. Actions: - `Check wallet` - `Refresh status` - `Close` ## Required technical inputs - Transaction signature, when available - Current confirmation status - Last status-check timestamp - Network/cluster label - Explorer URL generated from the known signature and cluster - Error message, if supplied by the wallet or RPC response ## Safety rules - Never label a transaction “confirmed” based only on wallet submission. - Never encourage an immediate retry while status is unresolved. - Preserve the original signature across refreshes. - Make explorer links secondary to the in-app status explanation. - Display the active network clearly. - Do not expose raw error codes without a human-readable explanation. ## Acceptance checklist - [ ] Every state has distinct visual styling and plain-language copy. - [ ] Pending and unknown states discourage accidental duplicate actions. - [ ] Retry creates a new deliberate wallet-signing step. - [ ] Status can be refreshed without re-submitting. - [ ] The component works with and without a transaction signature. - [ ] Mobile layout keeps primary actions visible.

# Self-Directed Draft: Solana Action Preview Sheet ## Product specification A reusable pre-signing sheet that translates a Solana app action into a short, human-readable summary before the wallet prompt opens. ### Purpose Help users understand **what they are about to sign**, especially when one action contains multiple instructions. ### Required fields - **Action:** “Swap tokens,” “Deposit,” “Claim,” or custom label - **Network:** Explicit cluster name supplied by the app - **Assets affected:** Token symbols and amounts, if known - **Destination:** Truncated address with copy control - **Fees:** Network fee and any app fee, if known - **Instruction count:** “This request contains 3 instructions” - **Warnings:** Unresolved amounts, unknown programs, or simulation failure - **Primary action:** `Review in wallet` - **Secondary action:** `Cancel` ### Interface copy > **Review action before signing** > > **Action** > Deposit 25 USDC > > **This request may change** > - Your USDC balance > - Your position in the selected pool > - Network balance by approximately 0.000005 SOL > > **Destination** > `8xKp…4QmL` [Copy] > > **Instructions** > 3 instructions included > > Confirm the details in your wallet before approving. Never share your seed phrase or private key. ### Warning states **Unknown program** > This request includes a program this app cannot describe. Review it carefully in your wallet before signing. **Incomplete amount** > The final amount is not available yet. Do not sign unless the wallet preview matches your intended action. **Simulation unavailable** > The app could not simulate this request. Signing may fail or produce an unexpected result. **Multiple signers** > This request asks for signatures from multiple accounts. Confirm that each signer is expected. ### Safety rules 1. Never label an address as trusted without an app-provided reason. 2. Never hide unresolved accounts, instructions, or fees. 3. Keep `Cancel` visually equal to the signing path. 4. Do not request a signature until the user selects `Review in wallet`. 5. Preserve a local, non-sensitive audit record containing action label, timestamp, and displayed summary—not secret material. ### Acceptance criteria - Users can identify the action, affected assets, destination, and fees before signing. - Unknown or incomplete transaction details produce a visible warning. - The sheet supports one- and multi-instruction requests. - No private key, seed phrase, or secret token is requested or stored. - All displayed values come from the app’s current transaction data and are marked unavailable when absent.

# Self-Directed Draft: Wallet Connection Consent Card ## Product specification A reusable card for Solana apps that explains what connecting a wallet will—and will not—do before the wallet prompt appears. **Card copy** > **Connect your wallet** > > Connecting lets this app view your public wallet address. It does not, by itself, approve a transaction. If an action later requires a signature, you’ll get a separate prompt. > > **Continue to wallet** · **Not now** **Requirements** - Show the app name and the reason for connecting in one plain-language sentence. - Keep the consent card separate from any transaction-signing flow. - Never request a seed phrase or private key. - Provide an obvious way to decline without trapping the user. - If connection fails or is declined, return to the prior screen without implying that a transaction occurred. **Acceptance checks** - A user can distinguish “connect” from “sign” before selecting a wallet. - The card works on a narrow mobile screen and with keyboard navigation. - Product teams can replace the reason-for-connecting sentence without changing the safety copy.