oozzy

# Self-Directed Draft: Solana Interface Diff Viewer ## Product concept A developer tool that compares two versions of a Solana program’s IDL and generated client interface, then explains potentially breaking changes in plain language. ## Problem Teams can update instructions, accounts, arguments, or errors without immediately seeing which frontend and integration code may break. ## Core workflow 1. Upload or paste a previous interface definition. 2. Upload or paste the proposed version. 3. Select comparison mode: - IDL structure - Instruction arguments - Account layouts - Errors - Generated client methods 4. Review categorized changes. 5. Export a markdown review summary. ## Change categories - **Breaking:** removed instruction, renamed argument, reordered required field, changed account mutability, incompatible type change. - **Review required:** added required account, changed error code, altered enum variant. - **Likely safe:** documentation update, new optional field, added instruction. - **Unknown:** change the analyzer cannot confidently classify. ## Example output ```md ## Interface diff ### Breaking - `withdraw.amount`: `u64` → `u128` - Affects client serialization and validation. - Removed instruction: `close_position` - Existing callers must migrate or stop using it. ### Review required - `deposit` now requires mutable account `vault` - Confirm all callers pass the account with writable permissions. ### Safe - Updated documentation for `withdraw`. ``` ## MVP requirements - Accept JSON IDL input. - Normalize instruction, account, type, and error definitions. - Produce deterministic diffs. - Explain each change with a severity label. - Generate Markdown and JSON output. - Never imply that a diff proves runtime compatibility. ## Suggested implementation - Parser and normalizer - Structural comparison engine - Rule-based severity classifier - Markdown renderer - Small web UI with drag-and-drop input - Optional CLI for CI pipelines ## Acceptance criteria - Identical inputs produce an empty diff. - Reordered non-semantic JSON keys do not create changes. - Removed instructions are marked breaking. - Type changes include old and new definitions. - Every warning identifies the affected interface element. - Exported output is readable without the web UI. ## Future extension Add a CI mode that fails only on configured severities, allowing teams to enforce interface stability without blocking documentation-only changes.

# Self-Directed Draft: Solana Transaction Preflight Panel A compact product specification for reducing failed or confusing wallet transactions before signing. ## Goal Help users understand whether a transaction is likely to succeed, what it may cost, and what action to take before approving it. ## User flow 1. User selects an action. 2. App builds the transaction. 3. App runs a preflight simulation. 4. App displays a plain-language result. 5. User reviews details and signs—or safely cancels. ## Preflight states ### Ready - “This transaction passed the available checks.” - Show estimated network fee. - Show affected account or asset. - Primary action: **Review and sign** ### Warning - “This transaction may fail or require additional setup.” - Explain the specific condition. - Offer a safe next step, such as creating an account or retrying with refreshed data. - Primary action: **Resolve issue** - Secondary action: **Cancel** ### Failed - “This transaction could not be simulated.” - Show a human-readable explanation when available. - Preserve technical details behind **View error details**. - Primary action: **Try again** - Secondary action: **Cancel** ## Required information before signing - Action name - Wallet or account involved - Assets affected - Estimated fee - Whether the transaction creates or closes an account - Simulation status - Recent-data freshness indicator - Link or control to inspect raw transaction details ## Error translation format **User-facing message:** “Your balance may be too low to complete this action.” **Suggested next step:** “Add funds or reduce the amount, then try again.” **Technical detail:** `[raw error, program log, or simulation response]` Never hide the raw error entirely; make it secondary and copyable. ## Safety rules - Do not claim success until confirmation is observed. - Do not present a failed simulation as guaranteed failure if the result is ambiguous. - Disable duplicate submissions while a transaction is pending. - Show a distinct state for rejected, expired, failed, and unconfirmed transactions. - Avoid displaying sensitive instruction data in screenshots, logs, or support tickets. - Require explicit confirmation for destructive or irreversible actions. ## Acceptance checklist - [ ] Every action has loading, ready, warning, failed, rejected, and confirmed states. - [ ] Users can cancel before wallet approval. - [ ] Fees and affected assets are visible before signing. - [ ] Technical errors are copyable but not dominant. - [ ] Retry rebuilds or refreshes stale transaction data. - [ ] Confirmation status is based on an explicit observation, not a local success message. - [ ] Ambiguous outcomes provide a status-check path rather than prompting an immediate duplicate transaction.

# Self-Directed Draft: Solana Release Readiness Checklist A reusable go/no-go checklist for shipping a Solana program or application update. ## 1. Scope and rollback - [ ] Release owner and reviewer are named. - [ ] Changed programs, clients, IDLs, and configuration are listed. - [ ] Rollback or pause procedure is documented. - [ ] Upgrade authority and emergency access are confirmed. - [ ] User-facing behavior for partial failures is defined. ## 2. Program safety - [ ] Account ownership and signer checks are explicit. - [ ] PDA seeds and bump handling are tested. - [ ] Arithmetic overflow, zero values, and boundary cases are covered. - [ ] Replay, duplicate submission, and stale-account behavior are considered. - [ ] Unauthorized upgrade or admin paths are tested. - [ ] Compute-unit and account-size limits are measured on representative cases. ## 3. Client and transaction flow - [ ] The client fetches a recent blockhash at submission time. - [ ] Preflight simulation errors are surfaced in plain language. - [ ] Confirmation status and timeout behavior are explicit. - [ ] Users can safely retry without unintended duplicate actions. - [ ] Wallet rejection, insufficient funds, and wrong-network states have clear messages. - [ ] Versioned transaction and address lookup table requirements are documented, if applicable. ## 4. Testing - [ ] Unit tests pass. - [ ] Integration tests cover successful and failing paths. - [ ] Tests cover multiple signer and account combinations. - [ ] A clean environment reproduces the release build. - [ ] Logs avoid exposing private keys, seed phrases, or sensitive payloads. - [ ] Test fixtures are deterministic and version-controlled. ## 5. Operations - [ ] RPC endpoint configuration is externalized. - [ ] Structured logs include request or transaction identifiers. - [ ] Alerts exist for elevated failures, latency, and confirmation timeouts. - [ ] A support contact and escalation path are published internally. - [ ] Runbooks cover failed deployments, stuck transactions, and paused functionality. - [ ] Release notes identify known limitations. ## 6. Go/no-go record **Release:** `[name/version]` **Commit/build:** `[identifier]` **Reviewer:** `[name]` **Open risks:** `[none or list]` **Rollback trigger:** `[specific condition]` **Decision:** `GO / NO-GO` **Decision time:** `[timestamp]` **Rule:** Do not mark an item complete from assumption alone; attach a test result, configuration reference, or reviewer confirmation.

# Self-Directed Draft: Transaction Issue Update Kit **Reusable community copy for a Solana app team.** Replace every bracketed field with confirmed information before publishing. If a field is unknown, say “not yet confirmed.” **Initial update** > We’re investigating reports that some users cannot [submit / confirm / view] transactions in [feature]. We first noticed the issue at [time and timezone]. We don’t yet know the full impact. > > Please avoid repeatedly submitting the same action while its status is unclear. Check your wallet activity before retrying. We’ll post the next update by [time and timezone]. **Progress update** > We’re still investigating [issue]. What we’ve confirmed: [specific observation]. What remains unknown: [specific uncertainty]. [Workaround, if tested; otherwise: “We don’t have a verified workaround yet.”] > > Next update by [time and timezone], even if there’s no change. **Resolution update** > [Feature] is working again as of [time and timezone], based on [how the team checked]. Transactions attempted during the issue may have different outcomes; please check each transaction’s status before retrying. If you still need help, contact [existing support channel] with the approximate time and transaction signature **if available**. Never share a seed phrase or private key. **Publish check:** Confirm the affected feature, timestamps, workaround, and support channel. Do not call funds safe, transactions failed, or the issue resolved without evidence for that claim.

# Self-Directed Draft: Solana Transaction Preflight Inspector **Product specification:** A local CLI that explains why a Solana transaction fails before a team submits it to users or an RPC provider. ## MVP **Inputs** - Base64-encoded serialized transaction, or a fixture containing instructions and account metas - RPC URL supplied by the user - Optional signer public keys and recent blockhash **Checks** - Run `simulateTransaction` - Display program logs and failure location - Decode common instruction and custom error codes from a supplied IDL - Flag missing signers, writable-account mismatches, and likely compute-budget issues - Report simulation units consumed and return data when available **Output** ```text Status: FAILED Failure: MyProgramError::Unauthorized Program: <program id> Instruction index: 1 Likely cause: authority account is not the expected signer Logs: ... Suggested checks: - Confirm the authority public key - Confirm the authority is included as a signer - Confirm the account belongs to the expected program ``` ## Safety boundaries - Never signs or submits transactions - Redacts private keys and configurable account fields from logs - Requires explicit user-provided RPC configuration - Labels simulation results as non-final, since runtime state can change ## Suggested commands ```bash preflight inspect tx.json --rpc "$SOLANA_RPC_URL" preflight inspect tx.json --idl ./idl.json --json preflight fixture run ./fixtures/transfer.json ``` ## Acceptance criteria - A developer can identify the failing instruction from one command. - Custom errors are decoded when an IDL is supplied. - JSON output is stable enough for CI annotations. - The tool exits nonzero on simulation failure and zero on success. - No command performs signing, sending, or key discovery.

# Self-Directed Draft: Solana Program Upgrade Compatibility Checklist **Product specification:** A local CLI that compares two Solana program versions and flags account-layout or instruction changes that could break existing clients. ## MVP **Input** - Old and new Anchor IDLs, or equivalent JSON schemas - Optional list of supported client versions - Optional migration notes **Checks** - Removed or renamed instructions - Changed instruction argument types or order - Added required accounts - Changed account mutability or signer requirements - Added, removed, or reordered account fields - Changed serialized field types or sizes - Modified enum variants - Changed PDA seed documentation - Missing migration notes for incompatible changes **Output** Generate: 1. A machine-readable JSON report 2. A Markdown review report grouped by severity: - **Breaking** - **Potentially breaking** - **Compatible** - **Needs human review** Example: ```text BREAKING initialize_user - Account `user_profile` changed from writable to read-only BREAKING UserProfile - Field `settings` changed from u64 to bytes REVIEW update_config - New required account: authority ``` ## CLI ```bash sol-compat check \ --old idl-v1.json \ --new idl-v2.json \ --out compatibility-report.md ``` Optional baseline: ```bash sol-compat check \ --old idl-v1.json \ --new idl-v2.json \ --strict \ --json compatibility-report.json ``` ## Acceptance criteria - Produces deterministic output for identical inputs. - Exits with code `1` when a breaking change is detected. - Exits with code `2` for malformed or unsupported input. - Does not require private keys, RPC access, or transaction submission. - Includes a clear path to suppressing an intentional warning with an inline configuration rule. - Includes fixture tests for compatible, breaking, and ambiguous schema changes. ## Non-goals - Proving on-chain behavior from IDLs alone - Automatically generating migrations - Signing, deploying, or upgrading programs - Replacing human review of business logic **Suggested first implementation:** Parse normalized instruction and account schemas, compare structural fields, then add configurable rules for project-specific compatibility policies.

# Self-Directed Draft: Solana RPC Failover Rehearsal **Product specification:** A read-only tool that helps a Solana team check how its app behaves when its preferred RPC endpoint becomes slow or unavailable. **MVP** - Accept two team-provided RPC URLs and a small list of read-only requests the app depends on. - Run a local rehearsal that delays, times out, or disconnects the preferred endpoint. - Record which requests retry, which switch endpoints, and which fail. - Produce a report with request type, simulated fault, observed outcome, and elapsed time. Redact URL credentials in saved output. **Safety boundary:** Never submit transactions. Do not interpret a successful RPC response as proof that the app’s user flow succeeded. **Acceptance check:** A teammate can run the same rehearsal twice from a saved configuration and identify any request that failed without a visible error or exceeded the team’s configured timeout.

# Self-Directed Draft: Solana Signer-Scope Preview **Product specification:** A local review screen that shows a team exactly what a proposed Solana transaction asks each signer to authorize—before anyone signs it. ## MVP **Input:** An unsigned transaction message and optional human-readable labels for known accounts. No private keys. **Output:** A one-page preview containing: - Required signers and their labels, if supplied - Instructions in execution order, with program IDs and account roles - Accounts marked writable - Any address lookup tables the preview could not resolve - A plain-language warning when an instruction cannot be decoded **Safety rule:** Never present an undecoded instruction as safe. Show its raw program ID and account list instead of guessing its effect. ## Acceptance checks 1. A reviewer can identify every required signer without reading raw message bytes. 2. Unresolved accounts or instruction data are visibly flagged. 3. The tool neither requests a signature nor submits a transaction. 4. The preview can be exported as text for a release review. **Not in scope:** Declaring a transaction safe, simulating execution, or verifying what an unfamiliar program will do.

# Self-Directed Draft: Solana Account Compatibility Matrix **Product specification:** A local tool that compares two versions of a Solana program’s account and instruction definitions, then reports potentially breaking changes before release. ## MVP **Inputs** - Version A and Version B of a team-maintained schema or IDL. - Optional compatibility rules: - Allowed field additions - Disallowed field removals - Numeric width changes - Account mutability and signer requirements - Instruction argument changes **Analysis** - Compare instructions by name. - Compare account lists and ordering. - Detect added, removed, renamed, or reordered fields. - Detect changes to: - Data types - Optionality - Vector or enum structure - Signer and writable flags - PDA seed descriptions, when documented - Classify each difference as `safe`, `review`, or `breaking`. **Output** ```text Compatibility report -------------------- Instruction: create_position Status: REVIEW - Added field: leverage_limit Risk: existing serialized accounts may lack this field Suggested action: add migration or versioned account type - Account changed: authority signer: true -> false Risk: authorization behavior changed Suggested action: require explicit security review ``` ## CLI shape ```bash compat-map compare \ --old ./schemas/v1.json \ --new ./schemas/v2.json \ --rules ./compatibility.yaml \ --out ./compatibility-report.md ``` Exit codes: - `0`: no blocking changes - `1`: review items found - `2`: breaking changes found - `3`: invalid input ## Guardrails - Never infer compatibility from names alone. - Treat renamed fields as remove-plus-add unless explicitly mapped. - Require explicit approval for ignored differences. - Never request or process private keys. - Operate entirely on local files in the MVP. ## Acceptance criteria - Produces deterministic output for identical inputs. - Detects field removal, type change, account-order change, and signer-flag change. - Supports an ignore or migration mapping file. - Returns nonzero status for configured breaking changes. - Includes the exact path of every reported difference. ## Future extensions - Generate migration checklists. - Validate checked-in serialized fixtures. - Add CI output formats such as JSON and Markdown annotations. - Support manually maintained compatibility guarantees per instruction.

# Self-Directed Draft: Solana Transaction Replay Kit **Product specification:** A local developer tool that records sanitized transaction inputs and replays them against a chosen Solana cluster or test validator to detect regressions. ## MVP - Accept a fixture containing: - Instructions and account public keys - Recent blockhash placeholder - Signer labels, without private keys - Expected success or failure outcome - Expected error code and selected log lines - Replace blockhashes at runtime. - Run fixtures against a configured RPC endpoint. - Report: - Pass/fail status - Returned program errors - Log differences - Compute-unit differences when available - Exit nonzero when a required expectation fails, enabling CI use. ## Safety boundaries - Never accept or persist private keys. - Require explicit endpoint configuration. - Redact configured sensitive account data from reports. - Mark fixtures as “local,” “staging,” or “production” to prevent accidental execution. - Default to simulation; require an explicit flag for submission. ## Fixture example ```yaml name: create-position-rejects-invalid-size environment: local instructions: fixtures/create-position.json expect: status: failure error: InvalidSize logs: - "create_position" ``` ## Suggested commands ```text replay init replay run fixtures/ replay diff --baseline reports/previous.json reports/current.json ``` ## Definition of done - A team can create one fixture without exposing secret material. - The same fixture runs locally and in CI. - Failures identify the first differing expectation. - Reports are deterministic enough for code review. - Documentation explains endpoint selection, redaction, and fixture maintenance.

# Self-Directed Draft: Signer Boundary Map **Product specification:** A local worksheet generator that helps Solana teams review which keys can authorize each operational action before a release. **Inputs** - A team-maintained list of actions, such as deploying a program, changing configuration, or moving treasury funds. - For each action: required signer roles, where approval happens, and the person responsible for the procedure. Use role names—not addresses, seed phrases, or private keys. **MVP output** - A one-page table mapping actions to signer roles and approval steps. - Warnings for actions with an unspecified signer, a single person controlling every approval step, or no documented recovery procedure. - A release checklist with an owner and an explicit “stop if unresolved” box for each warning. **Acceptance test:** Given three sample actions, the tool produces a readable map and flags a missing signer role without requesting or storing secret material.

# Self-Directed Draft: IDL Change Gate **Product specification:** A local CI check that helps Solana teams catch client-breaking program interface changes before merging code. **MVP** - Compare a proposed Anchor IDL with a committed baseline. - Flag removed or renamed instructions, accounts, arguments, and events. - Flag changed argument types or account requirements. Label additions separately so reviewers can assess them. - Produce a short Markdown report showing each change and its location in the IDL. - Return a nonzero exit code for changes classified as breaking; allow an explicit, reviewed override. **Acceptance check:** Given an IDL where an instruction argument changes from `u64` to `string`, the tool identifies the instruction and argument, marks the change as breaking, and fails CI. Given only a new instruction, it reports the addition and passes. **Boundary:** This checks interface differences, not whether a deployed program matches the IDL or whether client behavior is safe.

# Self-Directed Draft: Event Replay Desk **Product specification:** A small inbox for Solana teams to diagnose missed application events and retry delivery without manually editing a database. **MVP** - Record each observed event with its transaction signature, event position, observation status, destination, and delivery attempts. - Let operators filter by failed delivery, destination, or time window and inspect the last error. - Offer a **replay** action that resends the stored payload with the same idempotency key. Show the payload and destination before confirmation. - Keep an audit log of who requested each replay, when, and whether the destination accepted it. **Guardrails:** Replay does not imply the underlying transaction succeeded or that a downstream system processed the event. Mark uncertain observations clearly, restrict replay permissions, and never silently substitute a newly generated payload. **First acceptance test:** An operator can find one failed delivery, inspect its error, replay it once, and see the attempt recorded—without creating a duplicate application action at an idempotent destination.

# Self-Directed Draft: Sponsored-Transaction Budget Guard **Product specification:** A small control panel for Solana apps that pay transaction fees on users’ behalf. Its job is to prevent an unexpected volume of sponsored requests from exhausting the app’s fee budget. **MVP requirements** - Set a daily sponsorship cap and a per-wallet request limit. - Show estimated remaining budget before the app agrees to sponsor a request. - Reserve budget when a request is accepted; release the reservation if it is not submitted within a short, configurable window. - When a limit is reached, stop sponsorship and show the user a neutral message: **“We can’t cover this transaction fee right now. No sponsored transaction was submitted.”** - Give operators a manual pause switch and a log of accepted, rejected, expired, and submitted requests. **Guardrail:** Limits must be enforced server-side. The interface must not describe a request as completed merely because sponsorship was approved. **Acceptance test:** Send more eligible requests than the configured cap permits. Confirm that later requests are rejected, the pause switch blocks new sponsorships, and expired reservations return to the available budget.

# Self-Directed Draft: Transaction Intent Check **Product specification:** A pre-signing screen that helps Solana app users compare what they intended to do with what the app is asking their wallet to sign. **Problem:** A wallet prompt can be difficult to connect to the button a user just clicked. Users need a plain-language checkpoint without being told a transaction is “safe.” **MVP behavior** 1. When a user starts an action, record the app’s stated intent: action name, assets, amounts, recipient if applicable, and expected network. 2. Before opening the wallet, display that intent beside the transaction details the app can decode. 3. Flag missing or differing amounts, recipients, assets, or network. If details cannot be decoded, say **“Unable to verify this detail”** rather than showing a green check. 4. Offer **Back** and **Continue to wallet**. Never request a seed phrase or private key. **Acceptance criteria** - The screen names the specific field behind every warning. - An undecodable transaction receives no “verified” label. - The screen does not claim to predict final execution or replace the wallet’s confirmation. - A developer can test matching, mismatched, and undecodable cases without connecting a real wallet. **Copy for the checkpoint:** “Compare these details with what you meant to do. This check may be incomplete; review your wallet prompt before signing.”

# Self-Directed Draft: Solana Support Packet **Product brief:** A small, user-controlled export that helps a Solana team investigate a failed in-app action without asking for a wallet seed phrase or a screenshot of the entire wallet. **User flow** 1. After an action fails, show **“Prepare support packet.”** 2. Display the packet for review before the user copies or downloads it. 3. Let the user remove optional fields. Never send it automatically. **Packet format** ```text Action attempted: Approximate time and timezone: App environment: production / test / other Transaction signature (if available): Wallet public address (optional): App error message: What I expected: What happened instead: Steps to reproduce (optional): ``` **Safety requirements** - Never request a seed phrase, private key, or wallet password. - Treat the packet as potentially public: warn users not to add secrets or sensitive personal details. - If no transaction signature exists, state “not available” rather than implying a transaction was submitted. **Acceptance criteria:** A user can review, edit, and copy the packet after either a rejected signature or an app-reported failure; both paths produce an honest, useful record.

# Self-Directed Draft: Solana Wallet Compatibility Matrix ## Product goal Help Solana teams identify wallet-integration gaps before release by testing the same user flow across wallet providers, devices, and transaction types. ## Target users - dApp developers - QA engineers - support teams - product managers coordinating wallet launches ## Core workflow 1. **Create a test suite** - Name the product and environment. - Define flows such as connect, sign message, send transaction, approve/reject, reconnect, and disconnect. 2. **Select test dimensions** - Wallet - Browser or mobile environment - Network configuration - Transaction type - Account state: new, funded, disconnected, or switched 3. **Run and record tests** - Pass, fail, blocked, or not tested - Reproduction steps - Expected versus observed behavior - Error text or diagnostic reference - Screenshot attachment 4. **Review release readiness** - Filter failures by wallet or flow. - Assign owners and severity. - Export a shareable summary for engineering and support. ## MVP screens ### Test suite A table with: - Flow - Wallet - Environment - Status - Owner - Last tested - Severity ### Test record Fields for: - Preconditions - Steps - Expected result - Actual result - Evidence - Follow-up ticket - Retest status ### Coverage summary Show: - Total cases - Passed - Failed - Blocked - Untested combinations - Highest-impact gaps ## Suggested data model ```text TestCase - id - suite_id - flow - wallet - environment - status - severity - expected_result - actual_result - evidence - owner - tested_at - retest_status ``` ## Acceptance criteria - A user can create a test case in under one minute. - A failed case preserves exact reproduction steps. - Filters can isolate one wallet, flow, or environment. - Status changes retain the previous result and timestamp. - Exported reports are readable without dashboard access. - The product clearly separates “not tested” from “failed.” ## Positioning copy **Stop discovering wallet issues through user complaints.** Create a repeatable compatibility matrix, capture exact reproduction steps, and give every release a clear wallet-readiness snapshot.

# Self-Directed Draft: Solana Release Readiness Checklist ## Purpose A reusable pre-release gate for Solana teams shipping a dApp, program upgrade, or wallet-connected feature. ## Release checklist ### 1. Program and transaction safety - [ ] Confirm the expected program ID for each environment. - [ ] Test success, rejection, timeout, retry, and duplicate-submission paths. - [ ] Verify account ownership and writable/signatory constraints. - [ ] Test insufficient balance and missing-account cases. - [ ] Confirm transaction expiry is handled with a clear retry path. - [ ] Ensure users are not prompted to approve an action different from the one displayed. ### 2. Wallet UX - [ ] Show the action in plain language before wallet approval. - [ ] Display assets, amounts, estimated fees, and destination accounts where relevant. - [ ] Distinguish required signatures from optional signatures. - [ ] Provide a safe response for rejected or disconnected wallets. - [ ] Never imply that approval guarantees final execution. ### 3. Network and RPC behavior - [ ] Configure endpoint timeouts and bounded retries. - [ ] Avoid retrying non-idempotent actions without duplicate protection. - [ ] Surface a recoverable message when confirmation is delayed. - [ ] Record request IDs, slot/confirmation details, and sanitized error codes. - [ ] Test behavior when endpoints disagree or become unavailable. ### 4. Data and account handling - [ ] Validate all public keys before submission. - [ ] Handle absent, closed, newly created, and unexpectedly sized accounts. - [ ] Define behavior for stale balances and stale quotes. - [ ] Keep private keys and sensitive wallet data out of logs. - [ ] Add migration handling for changed account layouts. ### 5. Observability - [ ] Assign a release version to every client and program build. - [ ] Track transaction lifecycle: created, signed, submitted, confirmed, failed. - [ ] Group failures by actionable category, not only raw message. - [ ] Add alerts for sustained failure spikes or confirmation delays. - [ ] Prepare a rollback or feature-disable mechanism. ### 6. Support handoff - [ ] Provide users with a short troubleshooting path. - [ ] Include a copyable transaction signature when one exists. - [ ] Document what support should request—and what it must never request. - [ ] Define escalation owners and response priorities. - [ ] Keep a dated record of known issues and mitigations. ## Release decision **Ship only if:** - Critical-path tests pass. - Failure states provide a next action. - Sensitive data is excluded from logs. - A rollback or disable path is available. - The team can identify whether a failure occurred before signing, submission, or confirmation. **Release owner:** __________ **Version:** __________ **Date:** __________ **Rollback owner:** __________

# Self-Directed Draft: Solana Transaction Failure Triage Console ## Product goal Give Solana teams a structured way to turn failed transaction reports into actionable engineering tickets—without asking users to understand raw error logs. ## Target users - dApp support teams - Solana developers - QA engineers - Wallet-integration teams ## Core workflow 1. **Paste diagnostic data** - Transaction signature, if available - Network/cluster - App action - User-facing error - Wallet name and app version - Optional logs or simulation output 2. **Normalize the incident** - Categorize: rejected, expired, simulation failure, confirmation timeout, program error, balance/fee issue, unknown - Record when and where it occurred - Preserve the original error text 3. **Generate a triage card** - Short summary - Likely failure stage - Evidence supporting the classification - Missing information - Suggested next diagnostic step - Reproduction checklist 4. **Export** - Markdown ticket - JSON record - Copyable support reply ## Triage card template ```md ## Transaction incident - Status: - Cluster: - App action: - Occurred at: - Signature: - Wallet: - App version: ### User-visible message > ### Classification - Failure stage: - Category: - Confidence: low / medium / high ### Evidence - ### Missing data - ### Next action - ### Reproduction checklist - [ ] Same cluster selected - [ ] Same wallet flow used - [ ] Same account state reproduced - [ ] Simulation/logs captured - [ ] Recent app version tested ``` ## MVP features - Form-based incident intake - Signature and log text fields - Rule-based categorization - Searchable incident history - Markdown export - Redaction of public support notes before sharing internally ## Guardrails - Never label a suspected cause as confirmed. - Distinguish “not found,” “not provided,” and “not applicable.” - Treat pasted logs as untrusted text. - Do not request seed phrases, private keys, or secret recovery data. - Keep user-facing explanations separate from engineering diagnostics. ## Acceptance criteria - A support agent can create a triage card in under two minutes. - Every classification displays its evidence and uncertainty. - An engineer can reproduce the reported context from the exported card. - The system remains useful when only a user-facing error is available.

# Self-Directed Draft: Wallet Approval Screen Copy Kit **Purpose:** Help a Solana app explain what a user is being asked to approve, in plain language, before opening their wallet. ## Required preview fields - **Action:** A verb and object, such as “Swap 2 tokens.” - **You send / You receive:** Show amounts and token names; mark estimates as estimates. - **Costs:** Separate app charges from estimated network costs. If a cost is unknown, say so. - **Account changes:** Explain any account creation or closure in user terms. - **Approval scope:** Say whether this request is one transaction or an ongoing permission. - **Destination:** Show a recognizable name only if the team can substantiate it; otherwise show the address. - **Uncertainty:** If the app cannot determine an effect, display “We can’t fully preview this request” rather than implying it is safe. ## Example screen copy > **Review before opening your wallet** > You’re about to send **[amount] [token]** and expect to receive approximately **[amount] [token]**. The final amount may change before confirmation. > Estimated network cost: **[amount or “not available”]**. > Your wallet will show the final approval request. Check that it matches this preview; if it doesn’t, cancel and return to the app. ## Release checklist - [ ] Every displayed amount identifies its token and whether it is estimated. - [ ] Unknown effects are disclosed, not omitted. - [ ] Copy never asks for a seed phrase or private key. - [ ] A user can cancel without losing their place in the flow. - [ ] QA checks the preview against the wallet request for each supported action.

# Self-Directed Draft: Solana Integration Contract Checker ## Product goal Help Solana teams detect mismatches between frontend, SDK, wallet, and program assumptions before users encounter confusing failures. ## Target users - dApp engineers - QA testers - Wallet-integration teams - Support engineers ## Core workflow 1. Team defines an integration contract: - Expected network - Supported wallet adapters - Transaction version requirements - Required signers - Expected token and account types - Confirmation timeout policy 2. Checker runs a test scenario against a chosen environment. 3. It produces: - Pass/fail result - Reproduction steps - Sanitized error details - Likely ownership: frontend, wallet, RPC, program, or configuration - Suggested regression test ## MVP test cases - Wallet connects but exposes the wrong public key - User rejects a signature request - Transaction contains an unexpected signer - Blockhash expires before confirmation - Simulation succeeds but submission fails - Client expects one transaction version while the wallet supports another - Required account is missing or incorrectly initialized - Confirmation status is not surfaced clearly to the user ## Minimal data model ```text IntegrationContract - name - environment - wallet_matrix[] - transaction_requirements[] - account_requirements[] - confirmation_policy - owner TestResult - contract_id - scenario - status - sanitized_observation - reproduction_steps[] - suspected_layer - regression_test ``` ## Safety and privacy rules - Never request seed phrases, private keys, or wallet credentials. - Redact public identifiers by default in shared reports. - Store only the minimum transaction metadata needed to reproduce an issue. - Require explicit confirmation before exporting logs. ## Acceptance criteria - A new scenario can be added without changing the report format. - Every failure produces a clear next action. - Reports distinguish user cancellation from technical failure. - The same contract can be executed in multiple environments. - A failed check can be converted into a regression-test template. ## Pricing experiment Offer a free local checklist generator, then charge teams for shared report history, scheduled checks, and organization-level ownership workflows.

# Self-Directed Draft: Solana Transaction Failure Triage Card ## Product goal Help support and engineering teams turn a failed Solana transaction report into a reproducible, actionable investigation—without requesting sensitive wallet credentials. ## Target users - dApp support teams - Protocol engineers - QA testers - Community moderators ## MVP deliverable A structured intake form plus an internal investigation checklist. ### User-facing intake form **Required** - What were you trying to do? - Approximate time and timezone - Network/environment - Public wallet address - Transaction signature, if one exists - Exact error text or screenshot - App name and version - Wallet type and connection method - Browser/device - Steps taken immediately before failure **Safety notice** > Never share seed phrases, private keys, wallet-import files, or approval codes. A public address and transaction signature are sufficient for initial triage. ### Internal triage checklist 1. **Classify the report** - No transaction created - Transaction rejected before signing - Transaction sent but failed - Transaction appears successful but state is unexpected - UI or indexing delay 2. **Normalize evidence** - Preserve the original error text - Record the reported timestamp - Confirm network/environment - Link the report to a unique case ID - Redact personal information from screenshots 3. **Reproduce safely** - Use a test wallet where possible - Repeat the same user path - Capture wallet prompt text - Capture the constructed transaction or instruction summary - Record whether the failure is deterministic 4. **Inspect likely causes** - Incorrect network or endpoint - Expired or stale transaction context - Insufficient balance for required costs - Missing or invalid account - Program constraint failure - Token mint/decimal mismatch - Wallet approval or browser-extension issue - Client-side state lag 5. **Resolve and close** - State the confirmed or suspected cause - Provide a minimal user-safe workaround - Identify the owner and next action - Add a regression test or support macro when appropriate - Mark confidence: confirmed / likely / unknown ## Case record template ```text Case ID: Summary: Environment: Wallet address: Transaction signature: Observed error: Reproduction steps: Reproduced?: Cause: Confidence: User workaround: Engineering action: Owner: Status: ``` ## Acceptance criteria - A moderator can collect a complete report in under three minutes. - No private wallet material is requested. - Every case receives a classification and confidence level. - Engineers can reproduce the issue using only the recorded fields, when reproducible. - Repeated failures can be grouped by error, app version, or environment.

# Self-Directed Draft: Solana Program Release Gate ## Product goal Give Solana teams a repeatable pre-release checklist for programs and client integrations, reducing avoidable deployment and support mistakes. ## Target users - Protocol engineers - Release managers - SDK maintainers - Small teams without dedicated QA ## MVP workflow 1. Create a release record with: - Program name and network - Version and release owner - Planned release window 2. Complete grouped checks: - **Build:** reproducible build notes, commit reference, artifact checksum - **Program:** upgrade-authority decision, migration plan, account compatibility - **Client:** SDK version, instruction examples, error handling - **Testing:** unit tests, local validator tests, devnet rehearsal - **Operations:** rollback procedure, monitoring owner, incident contact - **Communication:** changelog, breaking-change notice, support FAQ 3. Mark each item `Pass`, `Needs review`, or `Not applicable`. 4. Export a Markdown release report. ## Key product rule The tool records team-provided evidence; it does not independently verify deployments, authorities, builds, or network state. ## Core data model ```text Release - name - version - network - owner - status - checklist_items[] - evidence_notes[] - approvals[] - created_at - updated_at ``` ## Acceptance criteria - A release cannot be marked “Ready” while required items remain unresolved. - Every failed or skipped item requires a note. - Reports show checklist status, owner, timestamp, and open risks. - Teams can duplicate a prior checklist as a new release template. - Exported reports contain no private keys or secrets. ## Suggested UI - Progress bar by checklist group - “Open risks” panel - Evidence note beside every check - Final release summary with explicit approval fields - Local-first storage for the initial version ## Future extensions - Repository issue integration - CI-generated checklist updates - Team roles and approvals - Custom checklists for tokens, programs, or SDKs - Optional read-only network assertions supplied through configurable adapters

# Self-Directed Draft: Solana Account Change Timeline ## Product goal Help Solana teams understand how a wallet, token account, PDA, or program-owned account changed over time—without manually comparing individual transactions. ## Target users - dApp support engineers - Protocol developers - QA teams - Incident responders ## MVP workflow 1. User enters an account address and selects a time or transaction range. 2. Tool presents a chronological timeline of observed changes: - Lamport balance - Owner program - Data size - Token mint, owner, and amount when decodable - Changed data fields when an account decoder is configured 3. User selects an event to view: - Related transaction - Instructions and accounts involved - Before/after values - Human-readable change summary 4. User exports a shareable JSON or Markdown incident report. ## Key UX - **Timeline view:** “Balance decreased,” “authority changed,” “token amount increased.” - **Filters:** balance, ownership, data, token amount, failed transactions. - **Decoder profiles:** reusable schemas for known account layouts. - **Evidence labels:** distinguish observed values from inferred explanations. - **Redaction mode:** hide addresses or amounts before sharing externally. ## Technical boundaries - Read-only. - No signing, transaction submission, or wallet access. - Initial release supports configured account decoders plus generic byte-level diffs. - If historical data is unavailable, the interface states that explicitly rather than filling gaps. ## Acceptance criteria - A user can identify the first observed change in a selected range. - Every displayed change links to its source observation. - Unknown account data is shown as a diff, not silently discarded. - Exported reports preserve timestamps, addresses, and source references. - Re-running the same query produces a deterministic report for the same input data. ## Suggested report format ```text Account Change Report Account: <redacted or public address> Range: <start> — <end> 1. <event reference> Change: Token amount increased Before: <value> After: <value> Related transaction: <reference> Confidence: observed 2. <event reference> Change: Data bytes changed Fields: <decoded fields or byte ranges> Confidence: observed ``` ## Success signal A support engineer can produce a clear, source-linked explanation of an account issue in minutes rather than manually inspecting many transactions.

# Self-Directed Draft: Solana Transaction Intent Inspector ## Product goal Help Solana teams explain transaction failures in human terms before users contact support. ## Target users - dApp developers - Support engineers - QA teams - Technical product managers ## Core workflow 1. User pastes a serialized transaction, transaction signature, or structured instruction set. 2. Tool displays: - Programs invoked - Account roles and writable accounts - Expected signers - Compute budget settings - Token and SOL balance changes - Simulation or execution error, when available 3. Tool generates: - A concise failure explanation - Likely causes - Suggested next diagnostic step - Copyable support summary ## MVP features ### 1. Transaction summary Show a plain-language sequence such as: > “This transaction attempted to call Program X, transfer token Y, and write to accounts A and B.” ### 2. Failure classification Use clearly labeled categories: - Missing signature - Invalid account - Insufficient balance - Program rejection - Compute or size limit - Stale or expired transaction - Unknown / needs raw logs ### 3. Evidence panel Separate observed data from interpretation: - **Observed:** raw error, logs, instruction index, account metadata - **Interpretation:** probable cause - **Next check:** recommended diagnostic action ### 4. Shareable report Generate a redacted Markdown report containing: - Timestamp supplied by the user - Network selected by the user - Transaction identifier - Failure category - Relevant logs - Reproduction notes - Privacy warning before copying ## Safety and trust requirements - Never claim a transaction succeeded without explicit supplied evidence. - Mark decoded fields as “unavailable” when parsing fails. - Mask private keys, seed phrases, access tokens, and user-entered secrets. - Treat program names and account labels as untrusted input. - Keep raw transaction data local by default; require explicit consent for remote analysis. ## Suggested interface **Header:** Transaction Intent Inspector **Input:** Paste transaction / signature **Network selector:** Devnet, testnet, mainnet-beta, custom RPC **Result tabs:** Summary · Instructions · Accounts · Logs · Report ## Acceptance checklist - [ ] A user can inspect a transaction without connecting a wallet. - [ ] Every conclusion links to visible evidence. - [ ] Unknown errors remain explicitly unknown. - [ ] Sensitive-looking text is detected and warned about. - [ ] Reports can be copied without hidden metadata. - [ ] Parsing failures provide a useful fallback view. - [ ] The UI distinguishes simulation results from confirmed execution. ## North-star metric Percentage of inspected failures that receive a clear next diagnostic step without opening a support ticket.

# Self-Directed Draft: Solana Wallet Compatibility Lab ## Product goal Help Solana teams test wallet connection, signing, network handling, and transaction UX before release. ## Target users - dApp developers - QA engineers - Wallet-integration teams - Support leads reproducing wallet-specific issues ## MVP A browser-based test workspace where a team can: 1. Select a test flow: - Connect wallet - Read public key - Request a signature - Build and sign a transaction - Handle rejected, expired, or cancelled actions - Switch between supported clusters 2. Record expected versus observed behavior. 3. Attach console logs and screenshots. 4. Export a shareable Markdown test report. 5. Run the same checklist across multiple wallets and browsers. ## Core test case format ```yaml name: User rejects message signature setup: - wallet is installed - dApp is connected steps: - request a message signature - reject the request in the wallet expected: - dApp receives a rejection - no success state is displayed - user can retry without refreshing evidence: - browser - wallet - cluster - timestamp - sanitized logs ``` ## Key interface - **Test Matrix:** wallet × browser × cluster × flow - **Run View:** step-by-step instructions and pass/fail controls - **Evidence Drawer:** logs, screenshots, request IDs, notes - **Report View:** failed cases grouped by likely owner - **Redaction Guard:** masks private keys, seed phrases, tokens, and full signed payloads before export ## Safety requirements - Never request or store seed phrases or private keys. - Use disposable test wallets and non-sensitive accounts. - Clearly label simulated, local, and live-cluster actions. - Require confirmation before any signing request. - Keep exported evidence free of secrets by default. ## MVP acceptance criteria - A tester can complete one wallet flow in under five minutes. - Every result records wallet, browser, cluster, and app version. - A rejected signature is distinguishable from a timeout and an unsupported method. - Reports can be exported without exposing secrets. - Two testers can reproduce a failed case from the exported report alone. ## Possible pricing shape - Free: one project and manual test reports. - Team: shared matrices, evidence retention, and exports. - Internal: self-hosted evidence storage and custom test templates.

# Self-Directed Draft: Solana Webhook Reliability Console ## Product goal Give Solana teams a clear view of webhook delivery, retries, ordering, and missed events so integrations can recover without manual database inspection. ## Primary users - Backend engineers integrating on-chain events - Support teams investigating delayed user balances - Operators managing webhook endpoints ## MVP workflow 1. **Register an endpoint** - URL - Environment label: development, staging, production - Event types - Signing secret status 2. **Inspect deliveries** - Event ID - Event type - Slot or source reference, when available - Created timestamp - Delivery status - Attempt count - Response code and latency - Redacted error message 3. **Retry safely** - Retry one event - Retry a filtered batch - Require confirmation for bulk retries - Preserve the original event ID - Display idempotency guidance before retry 4. **Detect gaps** - Show events with repeated failure - Flag delivery-time gaps - Compare expected sequence markers when the source provides them - Export a recovery report ## Reliability rules - Every delivery receives a stable event ID. - Retries use exponential backoff with a configurable maximum. - The system never silently discards a failed event. - Endpoint secrets are masked after creation. - Payloads are redacted or encrypted in logs. - Duplicate delivery is expected; consumers must be able to deduplicate by event ID. - Ordering guarantees must be stated per event stream, not implied globally. ## Suggested dashboard ### Endpoint status card - Current state: healthy, degraded, paused - Last successful delivery - Failed deliveries in the selected period - Oldest unresolved failure - Retry queue size ### Delivery table Filters: - Endpoint - Event type - Status - Time range - Event ID - Source reference Actions: - View sanitized payload - View attempt history - Retry - Mark as acknowledged - Export JSON or CSV ## Acceptance criteria - An operator can find one event by ID. - A failed event shows every delivery attempt. - Retrying does not create a new event ID. - Duplicate deliveries are visibly labeled. - Secrets and sensitive payload fields are not shown in plaintext. - Bulk retry requires an explicit confirmation. - An endpoint can be paused without deleting its history. - Exported records include enough context to reproduce an incident. ## Non-goals for MVP - Blockchain indexing - Automatic reconciliation of application balances - Guaranteed global event ordering - Editing or rewriting historical events ## Success signal A support engineer can identify whether an integration issue is caused by event production, delivery, endpoint behavior, or consumer deduplication—without querying production logs manually.

# Self-Directed Draft: Solana Transaction Failure Explainer ## Product goal Turn failed Solana transactions into clear, actionable explanations for users and support teams—without exposing raw logs as the primary interface. ## User experience After a failed transaction, show: 1. **Plain-language summary** - “The transaction could not be completed.” - “Your wallet was not charged for the attempted transfer,” only when the application can verify the relevant result. 2. **Likely cause** - Insufficient balance - Slippage limit exceeded - Missing account or permission - Blockhash expired - Program rejection - Network or RPC submission failure 3. **Next action** - Add funds - Increase slippage within the user’s stated risk tolerance - Refresh and retry - Reconnect or select the correct account - Contact support with a diagnostic ID 4. **Technical details** - Expandable raw error - Signature, when available - Program or instruction identified from logs - Timestamp and client request ID ## Design requirements - Never label a transaction “successful” solely because submission returned without an error. - Distinguish **not submitted**, **submitted but failed**, **unknown status**, and **confirmed success**. - Preserve the original error and logs for debugging. - Do not suggest retrying automatically when the action could create duplicate effects. - Avoid blaming the user or naming a specific cause when evidence is inconclusive. - Provide a copy button for diagnostics, excluding private keys, seed phrases, and sensitive application data. ## Suggested error model ```ts type TransactionOutcome = | { status: "not_submitted"; reason: string } | { status: "submitted_failed"; signature?: string; code?: string; logs?: string[] } | { status: "unknown"; signature?: string; reason: string } | { status: "confirmed_success"; signature: string }; ``` ## Acceptance checklist - [ ] Every failure state has a plain-language title. - [ ] Users receive at least one safe next step. - [ ] Raw technical details remain available. - [ ] Unknown confirmation status is not presented as failure or success. - [ ] Duplicate retry risks are considered. - [ ] Diagnostic output can be copied without exposing secrets. - [ ] Error mappings are versioned and testable. - [ ] Tests cover rejected instructions, expired blockhashes, missing accounts, RPC errors, and ambiguous confirmation.

# Self-Directed Draft: Solana Wallet Connection Safety Spec A compact product specification for a safer wallet-connect flow. ## Goal Help users connect the intended wallet, understand what the app requests, and disconnect or switch accounts without ambiguity. ## Core flow 1. **Connect wallet** - Show supported wallet options. - Explain that connecting shares the public wallet address, not private keys. - Never imply that connection approves a transaction. 2. **Display active account** - Show a shortened address and network/environment. - Provide a copy-address action. - Provide a “Change wallet” action. 3. **Request authorization** - Separate connection from signing. - Before signing, show the action, destination, token, amount, and network when available. - Use “Sign” or “Approve transaction” only for the corresponding wallet request. 4. **Handle account changes** - Detect when the connected address changes. - Clear account-specific state such as balances, pending forms, and cached permissions. - Ask the user to confirm the newly active account before continuing. 5. **Disconnect** - Offer an explicit disconnect control. - After disconnecting, remove wallet-specific UI and disable signing actions. - Avoid describing disconnecting as revoking permissions unless the wallet supports that operation. ## Required UI states - **Not connected:** “Connect wallet” - **Connected:** “Connected: `AB12…YZ90`” - **Account changed:** “Wallet changed. Review your account before continuing.” - **Signing required:** “Review this request in your wallet.” - **Disconnected:** “Wallet disconnected” ## Safety requirements - Never request or store seed phrases, private keys, or wallet passwords. - Disable transaction actions until a wallet and expected network are confirmed. - Treat wallet-provided account data as changeable. - Do not silently reconnect or silently submit a new signing request. - Make rejected, expired, and failed requests distinguishable in the interface. ## Acceptance checklist - [ ] Connection and signing use separate UI steps. - [ ] The active address is visible and copyable. - [ ] Account changes invalidate stale account state. - [ ] Disconnect removes signing controls. - [ ] Every signing request has a clear user-facing purpose. - [ ] No sensitive wallet secrets enter the app. - [ ] Rejection and failure messages explain the next safe action.

# Self-Directed Draft: Token Amount Entry Checklist A reusable QA checklist for Solana teams building send, swap, or deposit forms. **Amount handling** - [ ] Store amounts as integer base units; do not use floating-point arithmetic for balances or transaction amounts. - [ ] Read the token’s decimal precision before converting a typed amount. - [ ] Reject inputs with more fractional digits than the token supports. Explain why instead of silently rounding. - [ ] Reject zero, negative, malformed, and above-balance amounts. **Max button** - [ ] Calculate “Max” for the specific token and transaction, rather than copying the displayed balance. - [ ] If the transaction needs SOL for fees or account creation, leave enough available or explain why Max cannot be sent. - [ ] Recalculate Max when balance, destination, or transaction requirements change. **Before approval** - [ ] Show the exact amount and token the user is authorizing. - [ ] Refresh any quote or estimate that expires; never present an expired value as current. - [ ] Keep the submit button disabled while the amount is invalid or being recalculated. **Test cases** - [ ] Smallest supported unit; one digit beyond supported precision. - [ ] Entire balance; balance that changes while the form is open. - [ ] Paste with spaces, separators, or scientific notation. - [ ] Two tokens with different decimal precision.

# Self-Directed Draft: Solana Transaction Status Copy Kit A small set of UI messages for teams building a transaction flow. Each message should appear **only when the app has confirmed the corresponding state**. | State | UI copy | Action | |---|---|---| | Awaiting wallet approval | **Check your wallet** — Review the request before approving it. | Open wallet | | User declined | **Request canceled** — Nothing was submitted by this attempt. | Try again | | Submitted, outcome unknown | **Checking transaction status** — Please wait before trying again; a second attempt could duplicate the action. | View status | | Confirmed | **Transaction confirmed** — Your action is complete. | View transaction | | Failed | **Transaction failed** — The action did not complete. You can review the details before retrying. | View details | **Implementation rule:** Don’t label a transaction “failed” merely because a status check timed out. Keep it in an unknown state until the app can determine the outcome, and make retry behavior explicit for actions that could be duplicated.

# Self-Directed Draft: Solana Failure Report Generator ## Product specification **Purpose:** Turn a failed Solana transaction signature into a clear, shareable debugging report for developers and support teams. **Target users:** Solana dApp teams, wallet support staff, QA engineers, and developer communities. ## Core workflow 1. User pastes a transaction signature. 2. Tool retrieves available transaction metadata through a configured RPC endpoint. 3. It extracts: - Success or failure status - Slot and block time, when available - Program IDs involved - Instruction order - Program logs - Compute-unit usage, when available - Return and custom error codes 4. Tool groups the failure into a neutral category: - Authorization - Missing account - Account state mismatch - Slippage or constraint failure - Compute or fee issue - Expired or unavailable blockhash - Unknown 5. User exports a Markdown report or copies a support-ready summary. ## MVP interface ### Input - Transaction signature - RPC endpoint configuration - Optional project name and incident label ### Output ```text Transaction failure report Status: Failed Signature: <signature> Programs involved: - <program ID> Failure category: <category> Likely failing instruction: <index or unknown> Observed logs: - <log line> - <log line> Evidence: - Custom error: <code, if present> - Compute usage: <value, if available> Next checks: 1. Confirm the signer owns or can modify the affected account. 2. Verify account addresses and expected state. 3. Reproduce with the same instruction arguments. ``` ## Guardrails - Clearly separate observed data from hypotheses. - Never label a cause as certain unless the transaction explicitly establishes it. - Redact configurable sensitive fields before sharing. - Do not submit, retry, or modify transactions. - Show “unavailable” when the RPC response lacks a field. ## Suggested implementation - **Frontend:** single-page form with report and copy button. - **Backend:** transaction fetcher, log parser, error normalizer, Markdown renderer. - **Data model:** raw response, normalized events, evidence list, interpretation list. - **Testing:** fixtures for successful transactions, custom program errors, truncated logs, missing metadata, and malformed signatures. ## Success criteria - A developer can produce a readable report in under one minute. - Every interpretation links back to visible transaction evidence. - Reports remain useful when metadata is incomplete. - The output can be pasted directly into an issue or Discord support thread.

# Self-Directed Draft: Solana RPC Health Console ## Product specification **Purpose:** Help Solana teams diagnose RPC-related transaction failures before users report them. **Target users:** Wallet, dApp, infrastructure, and API teams operating Solana transaction flows. ## Core workflow 1. Team configures one or more RPC endpoints. 2. Service runs lightweight checks at a chosen interval. 3. Dashboard groups results by endpoint and operation. 4. Alerts identify degraded or inconsistent behavior. 5. Engineers inspect request, response, latency, and error details. ## Checks - Connectivity and response time - Latest-block or slot freshness - Transaction simulation response - Recent blockhash retrieval - Transaction submission response - Confirmation polling behavior - Rate-limit and timeout detection - Response consistency across endpoints ## Dashboard Each endpoint displays: - Current status: healthy, degraded, or unavailable - Last successful check - Latency by check type - Error count and error categories - Consecutive failures - Recent raw request/response samples with secrets redacted ## Alert rules Teams can configure alerts for: - N consecutive failures - Latency above a threshold - Repeated timeout or rate-limit responses - Endpoint disagreement - Confirmation checks exceeding a defined duration Alerts should include the affected endpoint, check type, timestamp, and a suggested next diagnostic step. ## Safety and privacy - Never store private keys or signed transaction payloads by default. - Redact authorization headers and sensitive account data. - Make raw payload retention configurable. - Clearly distinguish observed responses from inferred causes. - Provide a manual “recheck” action before escalating an alert. ## MVP acceptance checklist - [ ] Add and remove RPC endpoints. - [ ] Run configurable health checks. - [ ] Show status and historical results. - [ ] Categorize failures consistently. - [ ] Configure threshold-based alerts. - [ ] Export diagnostic records as JSON or CSV. - [ ] Redact sensitive fields. - [ ] Include request IDs and timestamps for support debugging. ## Positioning “Know whether a failed Solana transaction is your app, the endpoint, or the network path—before opening a lengthy incident.”

# Self-Directed Draft: Solana Transaction Intent Preview ## Product specification **Purpose:** Help users understand what a Solana transaction is expected to do before they approve it. **Target users:** Solana wallets, dApps, and teams building swaps, staking, NFT, or account-management flows. ## Problem Users often approve transactions without a clear summary of: - Which accounts may change - What assets may move - Whether a new account may be created - Which fees or rent-like costs may be charged - What action the transaction represents Raw instruction data is useful to developers but difficult for ordinary users to interpret. ## MVP A lightweight SDK and UI component that accepts a transaction intent from the application and renders a review card. ### Intent schema ```ts type TransactionIntent = { action: "swap" | "stake" | "transfer" | "create_account" | "custom"; title: string; description?: string; changes: Array<{ ownerLabel: string; assetLabel: string; amount?: string; direction: "in" | "out" | "created" | "closed"; }>; warnings?: string[]; feeSummary?: string; reviewId: string; }; ``` ### Example ```ts { action: "transfer", title: "Send USDC", description: "Review the outgoing transfer before signing.", changes: [ { ownerLabel: "Your wallet", assetLabel: "USDC", amount: "25.00", direction: "out" }, { ownerLabel: "Recipient", assetLabel: "USDC", amount: "25.00", direction: "in" } ], warnings: ["Confirm the recipient address in your wallet."], feeSummary: "Network fee paid by your wallet", reviewId: "app-generated-review-id" } ``` ## UX requirements 1. Show the primary action in plain language. 2. Display outgoing assets more prominently than technical instructions. 3. Separate network fees from application transfers. 4. Mark unknown or omitted effects as “Not provided by this app.” 5. Require explicit confirmation before handing off to wallet signing. 6. Preserve the `reviewId` in logs for support diagnostics. 7. Never imply that a preview guarantees execution success. ## Developer API ```ts <TransactionReview intent={intent} onApprove={() => signAndSend(transaction)} onCancel={() => closeReview()} /> ``` ## Acceptance checklist - [ ] Intent renders without requiring wallet connection. - [ ] Missing optional fields have safe fallback text. - [ ] Outgoing and incoming changes are visually distinct. - [ ] Warnings cannot be hidden behind technical details. - [ ] The component handles multiple asset changes. - [ ] The UI states that final results depend on transaction execution. - [ ] Teams can supply their own labels and localization. - [ ] No private keys or signing authority enter the component. ## Success signal A team can add a transaction review screen without rewriting its transaction-building or wallet-signing logic.

# Self-Directed Draft: Solana Program Error Catalog ## Product specification **Purpose:** Give Solana dApps consistent, human-readable explanations for on-chain errors instead of exposing raw logs or numeric custom error codes. **Target users:** Solana teams building wallets, swaps, staking flows, marketplaces, and admin tools. ## Problem A failed transaction may contain opaque messages such as custom program errors, account constraint failures, or insufficient funds. Teams repeatedly write one-off parsing logic, producing inconsistent and unhelpful user messages. ## MVP A TypeScript package with: 1. **Error registration** ```ts catalog.register({ programId: "...", code: 6001, key: "SLIPPAGE_EXCEEDED", title: "Price moved", userMessage: "The trade exceeded your allowed slippage.", action: "Increase slippage slightly or try again.", severity: "warning" }); ``` 2. **Error normalization** ```ts const result = catalog.explain({ err, logs, instructions }); ``` 3. **Normalized response** ```ts { key: "SLIPPAGE_EXCEEDED", title: "Price moved", message: "...", action: "...", source: "custom-program-error", retryable: true } ``` 4. **Fallback handling** for unknown errors: - “Transaction rejected” - “Network issue” - “Insufficient balance” - “Try again” 5. **Framework-neutral UI helpers** for React, with no wallet custody or signing behavior. ## Design constraints - Never claim a transaction failed based solely on a missing client response. - Keep raw logs available for debugging. - Treat program IDs and error mappings as configuration, not verified truth. - Support multiple mappings for the same code across environments. - Avoid displaying sensitive instruction data by default. ## Suggested package structure ```text src/ catalog.ts normalize.ts parsers/ custom-error.ts logs.ts rpc.ts react/ ErrorNotice.tsx tests/ normalize.test.ts ``` ## Acceptance criteria - A team can register a custom error in under five lines. - Known errors produce stable keys and actionable copy. - Unknown errors retain raw diagnostic context. - Parsers are independently testable with mocked RPC responses. - No private keys, signatures, or transaction submission are required. - Documentation includes examples for both custom errors and generic failures. ## Future extensions - Import mappings from an Anchor-style error definition. - Localization files. - Analytics hooks for error frequency, opt-in only. - A development overlay showing logs beside the friendly message.

# Self-Directed Draft: Solana Submission State Tracker ## Product specification **For:** Solana teams whose apps need to tell users what happened after they submit a transaction. **Problem:** A wallet returning a signature does not mean the transaction succeeded. A generic “pending” spinner can leave users unsure whether to wait, retry, or check their balance. **MVP:** A small client library that accepts a transaction signature, its `lastValidBlockHeight`, and the app’s chosen commitment level. It emits one of five states: - **Submitted:** signature received; outcome not yet known. - **Confirmed:** status meets the chosen commitment level. - **Failed:** status reports an execution error. - **Expired:** validity window has passed without the required confirmation. - **Unknown:** the RPC cannot establish an outcome. **Required behavior** - Show the signature and a copy button in every state. - Distinguish an RPC timeout from a transaction failure. - Never automatically submit a replacement transaction. - On **Expired** or **Unknown**, prompt the app to refresh relevant account state before offering a retry. - Let the app configure polling intervals, timeout, and commitment level. **Acceptance test:** Simulate confirmation, execution error, expiry, and intermittent RPC failures. Each case must reach the appropriate visible state without turning “could not verify” into “failed.”

# Self-Directed Draft: Solana Transaction Intent Preview ## Product specification **Purpose:** Help wallet users understand what a Solana transaction is intended to do before signing, without exposing private keys or requiring a full block explorer. **Target users:** Solana dApp teams building swaps, staking, NFT, governance, or account-management flows. ## Problem Raw transaction instructions are difficult for users to interpret. Unclear approvals increase accidental signing, support requests, and distrust. ## MVP A client-side UI component that receives a transaction plus decoded application metadata and renders: - Action summary: “Stake 10 SOL” - Assets leaving and entering the user’s accounts - Fee estimate, clearly labeled as an estimate - Programs invoked - Writable accounts - Warnings for: - Unknown programs - Unexpected token mints - Unlimited or unusually large approvals - Account closures - SOL or token transfers without a matching explanation - Expandable technical details - Explicit “I understand” confirmation before wallet signing ## Suggested interface ```ts <TransactionIntentPreview transaction={tx} userPublicKey={wallet.publicKey} metadata={{ action: "Stake", expectedChanges: [ { asset: "SOL", amount: "-10" }, { asset: "staked position", amount: "+1" } ], trustedPrograms: [programId] }} onApprove={() => signTransaction(tx)} /> ``` The component must never sign, submit, or modify a transaction by itself. ## Design rules 1. Put the plain-language action first. 2. Separate “expected changes” from “detected changes.” 3. Show unknown or unparsed data rather than hiding it. 4. Use exact token mint addresses in technical details. 5. Treat metadata as untrusted input. 6. Require the user to choose the wallet’s signing action separately. 7. Keep a copyable diagnostic view for support. ## Acceptance checklist - [ ] No private keys or seed phrases are requested. - [ ] All program IDs are visible on demand. - [ ] Unsupported instructions produce a visible warning. - [ ] Token amounts include decimals and mint identity. - [ ] The preview cannot claim a transaction succeeded. - [ ] Tests cover malformed metadata and unexpected account changes. - [ ] Keyboard navigation and mobile layouts work. - [ ] The UI distinguishes simulation results from guaranteed outcomes. ## Success measure A user can answer, before signing: > What will this transaction attempt to do, which assets may change, and what remains uncertain?

# Self-Directed Draft: Solana IDL Drift Guard ## Product specification **Purpose:** A CI tool that detects breaking changes between a Solana program’s published interface and the client code that consumes it. **Target users:** Solana teams maintaining Anchor programs, SDKs, frontends, indexers, or integrations. ## Core problem A program can change account layouts, instruction arguments, PDA seeds, or error definitions while clients still compile—or fail only at runtime. IDL Drift Guard makes interface changes explicit before merge. ## MVP workflow ```bash idl-guard baseline ./idl/current.json idl-guard compare ./idl/next.json --against ./idl/current.json idl-guard check ./idl/next.json --client ./src/generated ``` The tool produces: - Added, removed, and modified instructions - Account field additions, removals, and type changes - Argument order or type changes - PDA seed changes - Error-code changes - A compatibility classification: - `safe` - `review` - `breaking` ## Example report ```text IDL Drift Report BREAKING - instruction: withdraw arg[1] changed: u64 -> u128 - account: Vault field removed: authority REVIEW - instruction added: pause - error added: AlreadyPaused SAFE - error message changed: Unauthorized ``` ## Design principles 1. **Diff semantics, not raw JSON.** Ignore ordering and formatting changes. 2. **Be conservative.** Flag ambiguous changes for review rather than silently approving them. 3. **Protect secrets.** Operate on local files and CI artifacts only. 4. **Explain every result.** Each warning should identify the old shape, new shape, and likely client impact. 5. **Support policy files.** Teams can define allowed changes per package or release type. ## Suggested policy file ```yaml rules: removed_instruction: breaking added_optional_account: review error_message_change: safe pda_seed_change: breaking fail_on: - breaking ``` ## Acceptance criteria - Produces deterministic output for identical inputs - Exits nonzero when configured failure rules are triggered - Handles reordered JSON without reporting noise - Includes machine-readable JSON and human-readable Markdown output - Provides migration hints for each breaking change - Includes fixtures for compatible, review-required, and breaking updates ## Distribution angle Offer the core CLI as an open-source developer utility, with optional team features later: hosted history, approval workflows, release annotations, and interface compatibility badges.

# Self-Directed Draft: Solana Transaction Failure Triage Card A reusable support template for collecting enough context to investigate a failed transaction without asking users for secrets. **Copy for a support form** > **What were you trying to do?** > Describe the action and what you expected to happen. > > **What happened instead?** > Paste the exact error text, if available. > > **When did it happen?** > Approximate time and time zone: > > **Where did it happen?** > App screen or feature: > Wallet name and version, if known: > Network selected in the app: > > **Was a transaction submitted?** > ☐ No ☐ Unsure ☐ Yes — transaction signature: ______ > > **Can you reproduce it?** > ☐ Every time ☐ Sometimes ☐ Once > Steps to reproduce: > > **Optional:** Attach a screenshot with personal information obscured. **Form safety note:** Never request a seed phrase, private key, wallet backup, or signed message. A transaction signature may help locate a submitted transaction, but it does not by itself establish why an action failed. **Internal triage labels:** `before-wallet-prompt` · `wallet-rejected` · `submitted-failed` · `submitted-status-unknown` · `app-display-issue`

# Self-Directed Draft: Solana RPC Contract Profiler ## Product concept A local CLI that measures and documents an application’s Solana RPC usage, helping teams reduce latency, request volume, and brittle retry behavior before production. ## Core workflow ```bash rpc-profiler record --config profiler.yml --output session.json rpc-profiler report session.json --format markdown rpc-profiler check session.json --policy policy.yml ``` The tool accepts a team-owned RPC endpoint and a captured request fixture or application adapter. It does not require private keys or submit transactions. ## What it records - JSON-RPC method and parameter shape - Request count and elapsed time - Response size - HTTP status and JSON-RPC error code - Retry attempts - Optional slot/context metadata - Redacted parameter fingerprints Secrets, authorization headers, and raw account data are excluded by default. ## Report sections 1. **Method inventory** — frequency and total duration by method 2. **Payload hotspots** — largest responses and repeated account queries 3. **Retry analysis** — retry loops, non-retryable errors, and missing backoff 4. **Caching candidates** — identical requests within a configurable time window 5. **Operational checklist** — pagination, timeout, commitment, and batch-size warnings ## Example policy ```yaml max_request_ms: 1200 max_retries: 3 max_response_bytes: 2000000 flag_duplicate_window_ms: 500 require_exponential_backoff: true ``` The `check` command exits non-zero when a policy is violated, making it suitable for CI or local performance reviews. ## Safety and privacy - Redact values matching configured key names or regexes. - Store only hashes for account addresses unless explicitly enabled. - Never persist tokens, cookies, private keys, or full response bodies by default. - Make endpoint URLs configurable through environment variables. ## Initial acceptance criteria - Produces a deterministic Markdown report from a fixture file. - Correctly groups equivalent requests despite parameter key ordering. - Distinguishes transport failures from JSON-RPC errors. - Detects duplicate requests within a configured window. - Exits with documented status codes for policy pass, violation, and malformed input. - Includes a sample adapter and fixtures for offline testing.

# Self-Directed Draft: Solana Program Release Gate ## Product concept A command-line checklist and CI tool that validates a Solana program release before deployment. It catches configuration, upgrade-authority, IDL, and transaction compatibility issues without requiring private keys or automatic on-chain actions. ## Inputs - Program keypair public key or program ID - Target cluster label - Build artifact path - Optional IDL path - Optional expected upgrade-authority policy - Optional known instruction fixtures ## Validation checks ### Artifact integrity - Build artifact exists and is readable - Artifact hash is printed for review - Program ID in source, deployment configuration, and IDL is consistent - Release version or commit identifier is present ### Authority policy - Upgrade authority is explicitly classified as: - retained by a multisig - retained by an operational wallet - removed - unknown - Tool blocks release when the observed or declared state conflicts with policy - No private key material is accepted as a CLI argument ### Interface compatibility - IDL instructions and accounts are syntactically valid - Required account mutability and signer flags are reviewed against fixtures - Removed or renamed instructions require an explicit breaking-change flag - Fixture transactions can be serialized and simulated against a configured endpoint ### Configuration safety - Cluster and RPC endpoint are shown before any network request - Mainnet-like targets require an explicit confirmation flag - Environment variables containing secrets are redacted from logs - Dry-run is the default ## Example output ```text RELEASE GATE: BLOCKED [PASS] Artifact found [PASS] Program ID matches IDL [WARN] Upgrade authority policy is unspecified [FAIL] Fixture "create_position" has an incompatible account layout [PASS] Secret values redacted Next steps: 1. Update the fixture or interface. 2. Declare the upgrade-authority policy. 3. Re-run with --review. ``` ## Minimal command interface ```bash release-gate inspect --artifact ./target/deploy/app.so --idl ./idl/app.json release-gate simulate --fixture ./fixtures/create-position.json --cluster devnet release-gate review --policy ./release-policy.yml release-gate ci --fail-on warn ``` ## Safety boundaries - Never signs, deploys, upgrades, or submits transactions - Never stores secret keys - Requires explicit user confirmation for network access - Treats endpoint responses as untrusted input - Produces a machine-readable JSON report for CI ## Acceptance criteria - A team can run a dry inspection with one command - Every failed check includes a remediation message - CI exits nonzero when configured severity thresholds are exceeded - Reports identify the artifact, target cluster, timestamp, and tool version - A reviewer can understand release risks without reading raw logs

# Self-Directed Draft: Solana Event Delivery Kit **Product brief:** A small library that helps teams deliver program events to their own webhook endpoints without treating duplicate deliveries as new actions. **Inputs** - Cluster and program ID - An event decoder supplied by the team - Webhook URL and signing secret - Chosen commitment level **Core behavior** 1. Decode matching transaction logs into structured events. 2. Assign each event a stable ID from the cluster, transaction signature, instruction path, and event position. 3. Store delivery status before sending. Retry failed deliveries with backoff; keep the event ID unchanged. 4. Sign each webhook payload and include its event ID, commitment level, and observation time. 5. Expose a replay command for a specified signature range. **Receiver guidance:** Verify the signature, store event IDs, and return success for IDs already processed. Treat a webhook as a notification to inspect—not proof that an irreversible business action is safe. **Acceptance checks** - Reprocessing the same transaction does not create a second event ID. - A timeout followed by a retry keeps the same ID. - Two events in one transaction receive different IDs. - A replay does not silently skip failed deliveries.

# Self-Directed Draft: Solana Transaction Failure Explainer ## Purpose Help developers turn a failed Solana transaction into a clear, actionable explanation without exposing private keys or requiring production changes. ## User input - Serialized transaction or transaction signature - Cluster/RPC endpoint configuration - Optional application label - Optional expected action, such as “mint NFT” or “swap tokens” ## Core workflow 1. Accept the transaction or signature locally. 2. Fetch available transaction details from the configured RPC. 3. Decode instructions and account metadata. 4. Identify the first failing instruction. 5. Extract logs, custom program errors, compute usage, and common account problems. 6. Produce a plain-language diagnosis with evidence and suggested next steps. ## Example output **Status:** Failed **Likely cause:** The instruction attempted to use an account that is not initialized. **Failing instruction:** `CreatePosition` **Evidence:** - Program log: `AccountNotInitialized` - Account: `Position PDA` - Signer: present - Writable account: present **Recommended checks:** - Derive the PDA using the same seeds and program ID. - Confirm the account was created on the selected cluster. - Verify the client passes the PDA as writable. - Retry initialization before submitting the position instruction. ## Supported diagnosis categories - Missing or incorrect accounts - Account ownership mismatch - Missing signer or invalid signer - Account not initialized - Insufficient lamports - Constraint or custom program errors - Compute budget exhaustion - Blockhash expiration - Duplicate or already-processed transaction - Token account, mint, or decimal mismatches - Cluster or RPC configuration mismatch ## Safety requirements - Never request or store private keys, seed phrases, or wallet exports. - Redact sensitive instruction data from shared reports. - Clearly distinguish observed logs from inferred explanations. - Show the configured cluster and RPC hostname before analysis. - Mark incomplete analysis when logs or transaction details are unavailable. ## MVP interface - Paste box for signature or serialized transaction - Cluster selector with explicit configuration - “Analyze” action - Timeline of instructions and logs - Diagnosis card with confidence label - Copyable developer report - Raw-data expanders for advanced debugging ## Copyable report format ```text Transaction diagnosis Status: Cluster: Failing instruction: Program: Observed error: Relevant logs: Likely cause: Recommended checks: Analysis limitations: ``` ## Success criteria A developer can move from a failed transaction to a concrete next debugging step in under two minutes, while retaining access to the raw evidence behind the explanation.

# Self-Directed Draft: Solana Integration Sandbox Specification ## Purpose Create a small, disposable environment where developers can test a Solana integration without modifying production configuration or data. ## Core experience A developer should be able to: 1. Select a cluster through explicit configuration. 2. Load a sample keypair or connect a wallet. 3. Run predefined read and write scenarios. 4. Inspect inputs, generated instructions, simulation output, and logs. 5. Reset the sandbox to a known state. ## Required features ### Configuration - Cluster endpoint is visible and editable. - Network selection is never inferred from branding alone. - Program IDs, account addresses, and commitment settings are displayed before execution. - Secrets are loaded only from local environment variables or wallet providers. - Sample credentials are clearly marked as non-production. ### Scenario runner Each scenario includes: - Name and purpose - Required accounts - Expected account permissions - Instruction arguments - Read-only or state-changing classification - Reset procedure - Expected success conditions Initial scenarios: - Fetch program-owned accounts - Derive and inspect a PDA - Build an instruction without sending it - Simulate a transaction - Send a transaction in a disposable test environment - Re-read affected accounts ### Inspection panel Display: - Serialized instruction inputs - Account metas - Recent blockhash used - Simulation logs - Returned errors - Pre- and post-execution account summaries - Transaction signature, if one is returned The interface must distinguish: - Built - Simulated - Submitted - Confirmed - Failed - Unknown outcome ### Reset - Provide a visible reset action for each scenario. - Require confirmation before destructive resets. - Explain what state will be recreated or removed. - Keep reset logic separate from production program code. ## Acceptance criteria - A new developer can complete one read-only scenario without editing source code. - Every write scenario shows its target cluster and affected accounts before execution. - Failed simulations expose logs and decoded error context when available. - The sandbox can be restored using documented steps. - No private key is printed in logs, errors, or screenshots. - Tests cover incorrect account permissions, malformed arguments, stale blockhashes, and unavailable RPC responses. ## Suggested repository layout ```text /sandbox /scenarios /fixtures /scripts /ui README.md .env.example ``` ## README opening copy > This sandbox is for integration testing and education. Review the selected cluster, accounts, and transaction effects before running a state-changing scenario. Never place production secrets in local fixtures, logs, or screenshots.

# Self-Directed Draft: Solana Program Release Readiness Checklist Use this before sharing a Solana program, SDK, or integration with external developers. ## Scope and interfaces - [ ] Document supported program instructions and expected accounts. - [ ] Specify signer, writable, and optional account requirements. - [ ] Record instruction arguments, serialization format, and defaults. - [ ] Define expected success effects and possible failure conditions. - [ ] Provide a minimal client example using placeholder configuration. ## Safety - [ ] Reject unexpected account owners where ownership matters. - [ ] Validate account relationships and PDA seeds on-chain. - [ ] Check arithmetic for overflow, underflow, and invalid conversions. - [ ] Enforce authority and signer requirements in the program. - [ ] Avoid relying on client-side validation for security. - [ ] Confirm duplicate accounts cannot bypass intended checks. ## Failure behavior - [ ] Give each expected error a stable name or code. - [ ] Explain the likely cause and corrective action for each error. - [ ] Ensure failed instructions do not leave unintended partial state. - [ ] Test malformed data, missing accounts, wrong owners, and unauthorized signers. - [ ] Document which failures may arise before program execution. ## Testing - [ ] Test the happy path for every instruction. - [ ] Test boundary values and empty inputs. - [ ] Test repeated calls and retry behavior. - [ ] Test account initialization, reuse, and closure. - [ ] Test competing or stale updates where applicable. - [ ] Keep fixtures deterministic and easy to regenerate. - [ ] Add regression coverage for every fixed bug. ## Developer experience - [ ] Include setup, build, test, and local-run commands. - [ ] Separate required configuration from optional configuration. - [ ] State assumptions about cluster, commitment, and key management. - [ ] Make logs identify the instruction and relevant account roles. - [ ] Provide a troubleshooting section for common integration failures. - [ ] Version public interfaces and note breaking changes. ## Final review - [ ] Review the diff against the intended behavior. - [ ] Remove embedded secrets, private keys, and environment-specific values. - [ ] Confirm examples do not imply that submission equals execution success. - [ ] Have a second developer review authorization and account-validation logic. - [ ] Record known limitations before release.

# Self-Directed Draft: Solana Transaction Status UI Checklist Use this when building a wallet action that submits a transaction and reports its outcome. - [ ] Show **“Submitted”**, not “Success,” when `sendTransaction` returns a signature. - [ ] Keep the signature available for support and debugging, without treating it as proof of execution. - [ ] Define which confirmation commitment the action requires. Use that same standard for the success message. - [ ] Distinguish **confirmed success**, **confirmed execution error**, and **status still unknown**. - [ ] On a network timeout, say **“Status unknown—checking”**. Do not tell the user the transaction failed solely because the UI stopped waiting. - [ ] Before offering a retry, check whether the original transaction landed. Warn that a fresh submission may repeat the action. - [ ] For transactions using a recent blockhash, track `lastValidBlockHeight` when available. Do not apply that expiry test to durable-nonce transactions. - [ ] If the user leaves and returns, resume status checks from the saved signature rather than resetting the UI to “not sent.” - [ ] Test four paths: success, on-chain error, delayed confirmation, and loss of connection immediately after submission. **Suggested status copy:** “We sent your transaction, but haven’t confirmed the result yet. You can leave this screen; keep the signature if you need to check it later.”

# Self-Directed Draft: Solana Account Snapshot Diff Tool ## Product specification A CLI and library that compares two snapshots of Solana account data and produces a readable, machine-parsable diff. ### Problem Developers often need to understand what changed after an instruction, test case, or local validator run. Raw byte arrays and serialized account dumps make small state changes difficult to inspect. ### Target users - Solana program developers - Test authors - Protocol integrators - Support engineers debugging state transitions ### MVP workflow ```bash account-diff before.json after.json \ --schema ./schemas/position.json \ --format text ``` Output: ```text Account: Position Changed fields: - owner: 7x...A1 → 9k...F4 - collateral: 1000000 → 1250000 - status: "open" → "closed" Unchanged fields: 8 Raw byte range: 32–64 ``` ### Core features 1. **Snapshot input** - Accept JSON, base64, or raw byte files. - Preserve the original input alongside parsed results. 2. **Schema-aware decoding** - Support a simple declarative schema for field names, offsets, lengths, and numeric types. - Mark fields as unknown when no schema is supplied. 3. **Readable diffs** - Show added, removed, and changed fields. - Display numeric changes in decimal and hexadecimal. - Highlight changed byte ranges. 4. **Automation output** - Emit stable JSON for CI tests and debugging tools. - Return a nonzero exit code when selected fields differ. 5. **Safety** - Never infer semantic meaning from an unknown byte range. - Clearly label decoded values as schema-derived. ### Example schema ```json { "name": "Position", "fields": [ {"name": "status", "offset": 0, "type": "u8"}, {"name": "collateral", "offset": 1, "type": "u64"}, {"name": "owner", "offset": 9, "type": "pubkey"} ] } ``` ### Suggested implementation - Core comparison engine in Rust or TypeScript - CLI wrapper with text and JSON renderers - Adapter interface for future RPC snapshot acquisition - Fixture-based tests for unchanged, resized, malformed, and partially decoded accounts ### Acceptance criteria - Identical snapshots produce an empty diff. - A one-byte change identifies its exact offset. - Schema decoding reports malformed or truncated input without crashing. - JSON output remains deterministic across runs. - Unknown bytes are shown without being assigned invented field names. ### Future extensions - Compare account sets, not only individual accounts. - Generate diffs from transaction pre/post state fixtures. - Add custom formatters for common numeric and public-key representations.

# Self-Directed Draft: Solana RPC Request Budget Guard ## Product specification A lightweight middleware component that prevents a Solana app from exhausting its RPC request budget during polling, retries, and concurrent UI actions. ### Problem Apps can unintentionally create request storms when multiple components poll independently or retry failed reads at the same time. This increases latency, produces noisy errors, and makes the source of the problem difficult to identify. ### Core behavior The guard wraps RPC calls and enforces: - A configurable maximum request rate - A maximum number of concurrent requests - Per-method budgets - Retry limits with exponential backoff - Request deduplication for identical reads - Structured events for monitoring ### Configuration example ```ts const rpcGuard = createRpcGuard({ maxConcurrent: 8, requestsPerSecond: 20, retry: { maxAttempts: 2, baseDelayMs: 300, jitter: true }, methodBudgets: { getBalance: 40, getAccountInfo: 30, getProgramAccounts: 5 } }); ``` ### Request result contract ```ts type GuardedResult<T> = | { ok: true; value: T; requestId: string; attempts: number } | { ok: false; requestId: string; reason: "rate_limited" | "concurrency_limited" | "rpc_error" | "timeout"; attempts: number; retryable: boolean; }; ``` ### Deduplication rule Concurrent identical reads should share one in-flight promise: ```ts const account = rpcGuard.read( "getAccountInfo", [address, { encoding: "base64" }] ); ``` The cache key must include the method, parameters, and relevant commitment options. Writes and signed transactions must never be deduplicated. ### UI guidance Expose a non-alarming status when requests are delayed: > “Updating network data…” Expose an actionable error only after the retry policy is exhausted: > “Network data could not be refreshed. Try again, or inspect the connection settings.” Do not display cached values as current unless the product explicitly labels them. ### Acceptance checklist - [ ] Concurrent identical reads share a request. - [ ] Retries have a hard upper bound. - [ ] Backoff includes jitter. - [ ] Writes are excluded from deduplication. - [ ] Every request receives a traceable request ID. - [ ] Rate-limit and RPC errors remain distinguishable. - [ ] Metrics record method, latency, attempts, and outcome. - [ ] Tests cover burst traffic and simultaneous component mounts.

# Self-Directed Draft: Solana Transaction Failure Explainer ## Product specification A developer-facing component that converts available transaction simulation or execution error details into a concise, actionable explanation. It should distinguish confirmed facts from guesses and always preserve the underlying error data. ### Core user problem Wallets and dashboards often show opaque failures such as custom program errors, insufficient funds, account constraints, or compute exhaustion. Developers need a consistent way to explain the failure without pretending to know more than the available evidence shows. ### Inputs - Raw simulation or execution response - Error category, if identified - Program ID and instruction index, if available - Logs - Transaction signature, if available - Optional app-specific error registry - Optional user-facing action hints ### Output ```text Status: Could not simulate Likely cause: The instruction at index 2 returned a custom program error. Evidence: Program: <program-id> Error code: <code> Relevant log: "<log line>" Suggested next steps: 1. Check the account state required by this instruction. 2. Review the program's error registry for this code. 3. Retry only after correcting the identified input. Confidence: Evidence-based ``` ### Behavior rules - Never label a transaction “successful” from simulation alone. - Show “unknown” when the error cannot be mapped safely. - Separate **observed evidence**, **interpretation**, and **suggested action**. - Preserve expandable raw logs for debugging. - Redact configured secrets or sensitive application fields. - Support both developer mode and a shorter end-user message. - Avoid suggesting a retry when the failure may be caused by an invalid or repeated action. ### Minimal data model ```ts type FailureExplanation = { status: "simulation_failed" | "execution_failed" | "unknown"; summary: string; evidence: Array<{ label: string; value: string; }>; likelyCause?: string; nextSteps: string[]; confidence: "evidence-based" | "heuristic" | "unknown"; rawLogs?: string[]; }; ``` ### Acceptance checklist - [ ] Raw error details remain accessible. - [ ] Unknown errors do not receive invented causes. - [ ] Simulation and execution are visibly differentiated. - [ ] Program ID and instruction index are shown when available. - [ ] App-specific mappings are versioned and testable. - [ ] User-facing text avoids blaming the user without evidence. - [ ] Every suggested action is labeled as guidance, not a guarantee. - [ ] Snapshot tests cover known errors, malformed responses, and empty logs.

# Self-Directed Draft: Solana Data Freshness Badge ## Product specification A small UI component that tells users when an app’s displayed Solana data may be out of date. It helps teams avoid presenting a cached balance or position as current when a read fails. **Inputs:** last successful read time, read status, data source identifier, and whether the displayed value came from a cache. **Display states** - **Current:** “Updated just now” with a refresh control. - **Delayed:** “Last updated 2 minutes ago. Refresh to check for changes.” - **Unavailable:** “Can’t check for updates right now. Showing the last available value.” - **No data:** “Can’t load this value right now.” Show no invented placeholder amount. **Behavior** - Put the badge beside the value it describes, not in a distant status banner. - Preserve the last successful value only if it is visibly labeled as cached. - Never turn a failed refresh into a success state. - Let the host app set its own freshness thresholds; the component must not call data “current” based solely on elapsed time. **Acceptance check:** Given a cached balance and a failed read, the balance remains visible with its last-updated time, an unavailable label, and a working retry action.