ocat

# Self-Directed Draft: Solana Wallet Action Receipt ## Product specification **Purpose:** Give users a compact, human-readable record of what a Solana app asked them to approve—before and after wallet signing. ### Problem Wallet prompts and transaction signatures are difficult to interpret. Users need a durable summary of: - Which action they initiated - Which accounts or programs are involved - What assets may move - Whether the app received a signature - What the app can currently verify ### Receipt model ```ts type ActionReceipt = { id: string createdAt: string appName: string action: string wallet?: string network: "mainnet-beta" | "devnet" | "testnet" | "unknown" assets: Array<{ mint?: string symbol?: string amount?: string direction: "in" | "out" | "unknown" }> programs: string[] signature?: string state: | "draft" | "awaiting_signature" | "signed" | "submitted" | "confirmed" | "failed" | "unknown" message?: string } ``` ### UI requirements 1. **Before signing:** Show action name, wallet, network, asset movements, and program IDs. 2. **After signing:** Display the signature only when returned by the wallet. 3. **During submission:** Clearly distinguish “signed” from “submitted.” 4. **On failure:** Explain the app’s known failure state without implying funds moved. 5. **On unknown state:** Tell the user to check again rather than claiming success. 6. **Copy/export:** Allow JSON or plain-text export for support conversations. ### Safety rules - Never label an action “successful” solely because a wallet returned a signature. - Mark unavailable token metadata as `unknown`. - Keep raw addresses available behind an expandable detail view. - Do not infer asset movement from intent alone. - Redact private application metadata from exported receipts. ### Example user-facing receipt ```text Swap request Wallet: 7xK...9Qa Network: mainnet-beta You asked the app to: • Send: 1.00 token • Receive: amount not yet known Status: Awaiting wallet signature Nothing has been submitted yet. ``` ### Minimal implementation surface ```ts createReceipt(input): ActionReceipt updateReceipt(id, patch): ActionReceipt formatReceipt(receipt, mode: "text" | "json"): string ``` ### Acceptance checklist - [ ] Receipt is created before wallet interaction. - [ ] Every state transition is timestamped. - [ ] Signing and submission are separate states. - [ ] Unknown values remain explicitly unknown. - [ ] User can copy a support-ready summary. - [ ] No success message appears without application-defined confirmation evidence.

# Self-Directed Draft: Solana Transaction Preflight Guard ## Product specification **Purpose:** Help Solana applications identify risky or invalid transactions before requesting a wallet signature. ### User flow 1. User initiates an action. 2. App builds the transaction. 3. Guard simulates it using the configured RPC endpoint. 4. Guard returns a structured result. 5. UI shows either a clear warning or a confirmation summary. 6. Only then does the app request a signature. ### Result model ```ts type PreflightResult = | { ok: true unitsConsumed?: number logs: string[] warnings: Warning[] } | { ok: false code: | "SIMULATION_FAILED" | "BLOCKHASH_INVALID" | "ACCOUNT_MISSING" | "INSUFFICIENT_FUNDS" | "UNKNOWN" message: string logs: string[] } type Warning = { code: "HIGH_COMPUTE" | "NEW_ACCOUNT" | "UNEXPECTED_PROGRAM" | "CUSTOM" message: string } ``` ### Guard interface ```ts async function preflightTransaction( connection: Connection, transaction: Transaction, options?: { commitment?: Commitment minBalanceLamports?: number allowedProgramIds?: string[] } ): Promise<PreflightResult> ``` ### Safety rules - Never request a signature if simulation fails. - Display the destination, action type, and estimated fee when available. - Flag instructions targeting programs outside the app’s configured allowlist. - Treat simulation output as advisory; revalidate immediately before submission. - Do not expose raw RPC logs as the primary user message. - Provide a “report technical details” expansion for debugging. ### Example user-facing messages - **Simulation passed:** “Ready to review. No simulation errors detected.” - **Insufficient funds:** “This wallet may not have enough SOL to complete the transaction and pay its fee.” - **Unexpected program:** “This action includes an unrecognized program. Review before continuing.” - **Simulation failed:** “The network could not validate this action. Your wallet has not been asked to sign.” ### Acceptance checklist - [ ] Failed simulations block the signature request. - [ ] Error codes are stable and testable. - [ ] Raw logs are retained for developer diagnostics. - [ ] Allowlisted and non-allowlisted instructions are distinguishable. - [ ] The guard has unit tests for success, failure, missing accounts, and insufficient balance. - [ ] UI copy avoids claiming certainty when simulation is only a prediction.

# Self-Directed Draft: Solana Transaction Status Normalizer ## Product specification **Purpose:** Provide one consistent transaction-status model for Solana applications, regardless of whether a transaction is pending, confirmed, failed, expired, or unknown. ### Core status model ```ts type TxStatus = | "idle" | "building" | "awaiting_signature" | "submitted" | "confirming" | "confirmed" | "failed" | "expired" | "unknown"; ``` ### Normalized receipt ```ts type TxReceipt = { signature?: string; status: TxStatus; submittedAt?: string; finalizedAt?: string; slot?: number; confirmationLevel?: "processed" | "confirmed" | "finalized"; errorCode?: string; errorMessage?: string; retryable: boolean; source: "client" | "rpc" | "indexer"; }; ``` ### Required behavior - Never display “success” solely because a wallet returned a signature. - Treat missing or contradictory RPC responses as `unknown`, not `failed`. - Separate user rejection from network failure. - Make confirmation level explicit in the UI. - Stop polling after a configurable timeout and expose a retry action. - Preserve the signature whenever one exists. - Ensure retries do not silently submit duplicate intent. ### Suggested UI copy - `awaiting_signature`: “Approve the transaction in your wallet.” - `submitted`: “Transaction submitted. Waiting for network confirmation.” - `confirming`: “Confirmation in progress.” - `confirmed`: “Transaction confirmed.” - `failed`: “Transaction failed. No further action was completed.” - `expired`: “Confirmation took too long. Check activity before retrying.” - `unknown`: “Status could not be verified. Check activity before retrying.” ### Acceptance checklist - [ ] User rejection has a distinct error state. - [ ] Blockhash or expiration errors map to `expired`. - [ ] Program errors preserve a human-readable fallback. - [ ] Polling uses bounded retries and backoff. - [ ] Refreshing the page can recover status from the signature. - [ ] Retry requires explicit user action. - [ ] Analytics distinguish submitted, confirmed, failed, and unknown. - [ ] Tests cover delayed, malformed, and contradictory responses.

# Self-Directed Draft: Solana Wallet Sign-In Kit ## Product specification **Purpose:** Give Solana teams a reusable way to authenticate a wallet without asking users to sign a transaction. **Flow** 1. The server issues a one-time challenge containing the app’s domain, an intended action (`sign in`), a random nonce, and an expiration time. 2. The client displays the challenge and requests a message signature from the wallet. 3. The client returns the message, signature, and public key. 4. The server verifies the signature against the **exact message bytes**, then checks the domain, action, expiration, and unused nonce. 5. On success, the server consumes the nonce and issues a short-lived session bound to that public key. **Required safeguards** - Reject altered messages, reused nonces, expired challenges, and domain mismatches. - Store nonces server-side; never treat a public key alone as proof of wallet control. - Keep sign-in sessions separate from permissions to submit transactions or spend funds. - If a wallet cannot sign messages, show an unsupported-wallet state rather than silently switching to transaction signing. **Acceptance test:** A valid signature signs in once; replaying the same signed challenge fails.

# Self-Directed Draft: Solana RPC Failure-Mode Test Harness ## Product specification **Purpose:** Help Solana teams test application behavior when RPC responses are delayed, incomplete, inconsistent, or temporarily unavailable. ### Inputs - RPC endpoint configuration - Read methods used by the application - Transaction submission flow - Confirmation strategy - Retry and timeout settings - Expected user-facing error states ### Test scenarios - Request timeout - HTTP 429 rate limit - HTTP 5xx response - Malformed JSON-RPC response - Stale account data - `sendTransaction` success followed by confirmation timeout - Duplicate transaction submission - Blockhash expiration before signing or confirmation - WebSocket disconnect during signature tracking - Temporary mismatch between simulation and submission results ### Required outputs For each scenario, record: - Trigger method - Expected application behavior - Actual behavior - Retry count and delay - Whether duplicate submission is possible - User-visible message - Recovery action - Structured log or alert emitted ### Safety rules - Never retry indefinitely. - Use bounded exponential backoff with jitter. - Do not blindly rebuild or resubmit a transaction unless the application can determine whether the original landed. - Preserve the original transaction signature when tracking confirmation. - Treat unknown confirmation state as unresolved, not failed. - Redact private keys, seed phrases, and sensitive payloads from logs. ### Acceptance criteria - Every RPC call has an explicit timeout. - Retries are limited and observable. - Submission and confirmation are separate states. - A dropped connection does not automatically imply transaction failure. - Users receive actionable recovery guidance. - Tests run deterministically against mocked RPC responses. - Results export as JSON for CI or release review. ### Minimal result schema ```json { "scenario": "confirmation_timeout", "request_id": "test-001", "expected": "poll status, then show unresolved state", "actual": "recorded by test runner", "retries": 3, "duplicate_submission": false, "user_message": "Confirmation is still pending. Check activity before retrying.", "passed": true } ``` ### Suggested deliverable A small command-line tool with: ```bash rpc-chaos test --config ./rpc-tests.json rpc-chaos report --format json ``` The tool should use mock responses by default and require an explicit flag before testing against a real endpoint.

# Self-Directed Draft: Sponsored Transaction Budget Gate ## Product specification **Purpose:** Help a Solana team decide whether its service should pay the network fee for a user-requested transaction. **Inputs:** A transaction proposal, fee-payer account, requesting app/user identifier, configured spending limits, and a current fee estimate supplied by the team’s RPC provider. **Decision rules:** - Reject proposals that do not match an approved instruction policy. - Reject proposals requiring any signer other than those explicitly expected. - Reserve the estimated fee against both a per-requester limit and a global daily limit *before* approving sponsorship. - Expire reservations that are not used within a configured window. - Fail closed when the fee estimate, policy configuration, or budget state is unavailable. **Output:** `approved`, `rejected`, or `retry_later`, with a machine-readable reason, reservation ID, and expiry. Log the decision without storing secrets. **Acceptance test:** Two simultaneous requests cannot both consume the same remaining budget. An expired reservation restores capacity. A changed transaction must be evaluated again. **Boundary:** Approval is permission to attempt sponsorship—not a guarantee that the transaction will succeed or cost exactly the estimate.

# Self-Directed Draft: Solana Authority Boundary Auditor ## Product specification **Purpose:** Help Solana teams review who can authorize sensitive program actions before release. ### Inputs - Program source or pseudocode - IDL, if available - Instruction handlers - PDA seed definitions - Account constraints and signer declarations - Optional threat model ### Checks - Identify every instruction that can move funds, change ownership, pause activity, upgrade configuration, or alter authorities. - List required signers for each sensitive instruction. - Map each authority to its storage location and validation rule. - Flag authorities accepted from user-provided accounts without an explicit relationship check. - Detect PDA seeds that omit an expected identity, domain, or resource identifier. - Highlight writable accounts that are not obviously necessary. - Compare authority behavior across initialization, update, and emergency paths. - Mark unchecked assumptions, such as “caller is trusted” or “this account is canonical.” ### Output Generate a table: | Instruction | Sensitive action | Required signer | Authority source | Validation evidence | Risk | |---|---|---|---|---|---| | `...` | `...` | `...` | `...` | `...` | Low/Medium/High | Then produce: 1. **Critical findings** — missing or ambiguous authorization checks. 2. **Account-flow diagram** — signer → authority account → affected resource. 3. **Recommended tests** — unauthorized signer, substituted authority, wrong PDA, duplicate account, closed account, and replay-like sequences. 4. **Release gate** — Pass, Pass with warnings, or Block. ### Suggested implementation - Parser layer for source/IDL/account metadata. - Rule engine with explicit, reviewable checks. - Human-confirmation step for uncertain findings. - Markdown and JSON export for pull requests and CI. - No transaction submission or wallet access; analysis remains local or read-only. ### Acceptance criteria - Every sensitive instruction appears in the report. - Each listed authority has a stated validation path or an “unknown” marker. - Findings link to an instruction and account relationship. - The same input produces deterministic output. - The tool never labels an authority boundary safe solely because a signer exists.

# Self-Directed Draft: Solana Transaction Preflight Report ## Product specification **Purpose:** Turn a serialized Solana transaction or transaction-building log into a readable preflight report before submission. ### User inputs - Base64-encoded transaction, or structured instruction log - Intended cluster label entered by the user - Optional expected signer list - Optional expected program list ### Report sections 1. **Transaction summary** - Legacy or versioned format - Instruction count - Signer count - Account count - Recent blockhash presence 2. **Instruction map** - Program address - Read-only vs writable accounts - Signer requirements - Data length and hexadecimal preview - Unknown or unrecognized instructions clearly marked 3. **Risk checks** - Missing expected signer - Writable account not in the user’s allowlist - Unexpected program address - Duplicate or unusual account metas - Empty instruction set - Oversized or malformed input - Address lookup table references that cannot be resolved from supplied data 4. **Human-readable verdict** - `PASS`: no configured checks failed - `REVIEW`: information is incomplete or an unknown instruction is present - `BLOCK`: a configured signer, program, or account constraint failed ### Minimal interface - Paste/upload panel - “Expected signers,” “Allowed programs,” and “Writable account policy” fields - “Analyze” button - Copyable Markdown and JSON report - No automatic signing or submission ### Example output ```text VERDICT: REVIEW Transaction: versioned Instructions: 2 Signers found: 1 WARNINGS - Instruction 2 targets an unrecognized program. - One address lookup table reference was not supplied, so account permissions are incomplete. CHECKS [PASS] Expected signer present [REVIEW] Allowed-program validation incomplete [REVIEW] Writable-account validation incomplete ``` ### MVP acceptance checklist - [ ] Accepts malformed input without crashing - [ ] Never requests private keys or seed phrases - [ ] Separates decoded facts from heuristic warnings - [ ] Displays full addresses without truncation in copied output - [ ] Supports deterministic JSON export - [ ] Includes fixture tests for legacy and versioned transactions - [ ] Redacts pasted payloads from analytics and logs by default - [ ] Clearly states when decoding is incomplete ### Suggested positioning **“Know what a Solana transaction intends to touch before you sign it.”**

# Self-Directed Draft: Solana Interface Drift Checker ## Product specification **Purpose:** Detect mismatches between a Solana program’s expected interface and the client code that calls it—before they become confusing runtime failures. ### Inputs - Program interface definition or IDL - Client repository or pasted instruction builders - Optional deployment/environment labels - User-defined compatibility rules ### Checks - Instruction names and argument order - Argument types and optionality - Account names, mutability, and signer requirements - PDA seed descriptions - Expected error codes - Client/program version labels - Missing or newly added instructions ### Output A concise report with: - **Status:** compatible, review needed, or incompatible - File and line references where available - Side-by-side expected vs. observed interfaces - Severity: - Blocker - High - Informational - Suggested remediation - Machine-readable JSON export ### MVP workflow 1. Upload or paste the interface definition. 2. Connect a client code sample or repository snapshot. 3. Select the comparison profile. 4. Run deterministic static checks. 5. Review findings and export Markdown or JSON. ### Example finding > **Blocker — `withdraw` account mismatch** > Interface expects `authority` as a signer. Client marks it read-only. > **Fix:** update the client account metadata and regenerate its request fixture. ### Guardrails - Never submit transactions. - Never request private keys or seed phrases. - Treat uploaded code as untrusted. - Redact likely secrets before displaying findings. - Clearly distinguish static analysis from runtime verification. ### Acceptance criteria - Same inputs produce the same report. - Every finding links to an input location or rule. - Unknown syntax produces a visible “not analyzed” notice. - Users can suppress a finding with a written rationale. - Reports remain useful without access to a live network. ### Future extensions - CI command that fails builds on Blocker findings - Snapshot tests for instruction serialization - Compatibility history across client releases - Team review comments attached to findings

# Self-Directed Draft: Solana RPC Failure Reproducer ## Product specification **Purpose:** Help Solana developers reproduce intermittent RPC and transaction failures using sanitized, copyable test cases. ### Core workflow 1. User selects a failure category: - Timeout - Blockhash expired - Simulation failure - Confirmation failure - Unexpected account state 2. User pastes: - Error text - Transaction signature, if available - RPC method and parameters, with secrets removed - Approximate occurrence time 3. Tool validates and redacts sensitive fields. 4. Tool generates: - A concise incident summary - A reproducibility checklist - A cURL or JavaScript request template - A support-ready Markdown report ### MVP interface **Page title:** Reproduce the failure, not the whole story. **Fields:** - Failure category - Exact error message - Transaction signature (optional) - RPC method - Sanitized request payload - Expected result - Actual result - Client library and version - Network/environment label - Approximate timestamp **Primary button:** `Generate reproduction report` **Secondary button:** `Clear all data` ### Generated report format ```md ## RPC Failure Reproduction ### Summary - Category: [category] - Expected: [expected result] - Observed: [actual result] - Approximate time: [timestamp] - Environment: [network/client/version] ### Request - Method: [method] - Parameters: [redacted payload] ### Transaction - Signature: [signature or “not provided”] ### Reproduction checklist - [ ] Retry with the same request - [ ] Retry against a separate configured endpoint - [ ] Confirm the request uses the intended network - [ ] Record the first failing response - [ ] Compare simulation and submission responses ### Redaction notes [Fields removed or masked by the tool] ``` ### Safety requirements - Never request seed phrases, private keys, wallet passwords, cookies, or bearer tokens. - Mask fields named `secret`, `privateKey`, `mnemonic`, `password`, `token`, or `authorization`. - Perform redaction in the browser before any optional export. - Clearly label signatures and public addresses as user-supplied identifiers. - Provide plain-text export without requiring account creation. ### Acceptance criteria - A user can produce a report without connecting a wallet. - Invalid JSON is identified with a useful error message. - Sensitive-looking fields are masked before preview or copy. - Empty optional fields do not block report generation. - The generated report is readable in a standard Markdown viewer. - “Clear all data” removes form contents from the current page.

# Self-Directed Draft: Solana Transaction Explainability Card ## Product concept A small web tool that turns a user-provided Solana transaction signature into a readable “what happened” card for support teams and developers. It should explain: - Whether the transaction succeeded or failed - Which program instructions were attempted - Token and SOL balance changes - Human-readable error details when available - Links or identifiers needed for independent verification The tool must never request seed phrases, private keys, or wallet connection permissions. ## Primary user flow 1. User pastes a transaction signature. 2. Tool validates the signature format. 3. User selects a cluster: Mainnet, Devnet, or Testnet. 4. Tool displays a loading state and a clear data-source label. 5. Tool renders a shareable explanation card. 6. User can copy a redacted report for support. ## Explanation card ```text TRANSACTION REVIEW Cluster: [cluster] Signature: [signature] Status: [Succeeded / Failed / Not found] Slot: [slot, if available] Block time: [time, if available] SUMMARY [One-sentence plain-language explanation] INSTRUCTIONS 1. [Program label] — [action] 2. [Program label] — [action] BALANCE CHANGES - SOL: [before] → [after] - [Token symbol]: [before] → [after] ERROR [Readable error, or “No error reported.”] IDENTIFIERS Fee payer: [public address] Programs: [public addresses] ``` ## Safety and privacy rules - Never request wallet credentials or signing authority. - Treat pasted signatures and addresses as public identifiers, not proof of ownership. - Escape and sanitize all explorer-returned text before rendering. - Display raw addresses alongside shortened versions. - Mark unavailable fields as “Unavailable,” never infer them. - Do not claim a transaction is safe, reversible, profitable, or authentic. - Avoid storing signatures by default; provide explicit opt-in retention only. ## MVP acceptance criteria - Accepts a valid signature and selected cluster. - Handles malformed, missing, and unavailable signatures distinctly. - Separates confirmed success from lookup failure. - Shows raw error data beside any simplified explanation. - Produces copyable plain text and JSON output. - Includes a visible disclaimer: **“This report summarizes returned transaction data; verify important details independently.”** ## Suggested implementation boundary Use a server-side RPC adapter with a small normalized interface: ```ts type TransactionReview = { cluster: "mainnet" | "devnet" | "testnet"; signature: string; status: "succeeded" | "failed" | "not_found" | "unavailable"; feePayer?: string; slot?: number; blockTime?: number; instructions: Array<{ program?: string; summary: string }>; balanceChanges: Array<{ asset: string; before: string; after: string }>; error?: { raw: string; summary?: string }; }; ``` The UI should depend on this normalized object rather than directly on provider-specific response formats.

# Self-Directed Draft: Solana Support Intake Form **Purpose:** Give Solana teams enough information to investigate a failed user action without asking for wallet secrets. ## User-facing form copy **What were you trying to do?** Describe the action and what you expected to happen. **What happened instead?** Paste the error message, or describe what you saw. **When did it happen?** Approximate date, time, and time zone. **Optional details** - App version and device or browser - Wallet app name - Transaction signature, **if a transaction was submitted** - Public wallet address, **only if needed to investigate** **Safety note:** Never send a seed phrase, private key, password, recovery code, or wallet export. Support will not ask you to sign a transaction to resolve a ticket. ## Team handling checklist - [ ] Confirm whether a transaction was submitted before requesting a signature. - [ ] Remove secrets accidentally included in a ticket and follow the team’s incident procedure. - [ ] Separate wallet-connection, transaction-submission, and confirmation issues. - [ ] Ask for one missing detail at a time; do not request a full wallet log by default. - [ ] Close with the outcome and a reusable help-center note if the issue is recurring.

# Self-Directed Draft: Solana Transaction Review Checklist A reusable, human-in-the-loop checklist for reviewing a Solana transaction builder before release. ## 1. Inputs and accounts - [ ] Every public input has an explicit type and validation rule. - [ ] Account addresses are parsed and validated before instruction creation. - [ ] Required signers are clearly identified. - [ ] Writable accounts are limited to those genuinely needed. - [ ] Optional accounts cannot silently become arbitrary writable accounts. - [ ] Remaining accounts are documented and reviewed separately. ## 2. Instruction construction - [ ] Program IDs are supplied through explicit configuration, not hidden defaults. - [ ] Instruction discriminators and argument encoding match the intended interface. - [ ] Integer bounds, decimal conversion, and rounding behavior are tested. - [ ] User-controlled values cannot create unintended large allocations or fees. - [ ] PDA seeds and bump handling are deterministic and covered by tests. - [ ] Account ordering is tested; do not rely on object or map iteration order. ## 3. Wallet and authority safety - [ ] The fee payer is displayed before signing. - [ ] The application identifies all signer roles and requested signatures. - [ ] Authority-changing instructions receive an explicit confirmation step. - [ ] No private key or seed phrase is logged, persisted, or sent to a server. - [ ] A rejected signature or disconnected wallet fails closed. ## 4. Preview and failure handling - [ ] Users can inspect destination programs, token accounts, amounts, and fees. - [ ] Simulation is treated as a debugging aid, not proof of successful execution. - [ ] RPC errors, blockhash expiry, and confirmation timeouts are distinguishable. - [ ] A retry cannot unintentionally duplicate a non-idempotent action. - [ ] The UI never reports success solely because a transaction was submitted. ## 5. Test matrix - [ ] Valid transaction with expected accounts. - [ ] Wrong program ID. - [ ] Missing signer. - [ ] Read-only account supplied as writable, and vice versa. - [ ] Malformed address and boundary numeric values. - [ ] Expired blockhash and dropped confirmation. - [ ] Duplicate-click or retry behavior. - [ ] User cancellation at each signing step. ## Release gate Do not ship the transaction path until each unchecked item has either: 1. a test demonstrating the intended behavior, or 2. a written, reviewable reason why it does not apply. Record the reviewer, commit identifier, and unresolved risks in the release notes.

# Self-Directed Draft: Anchor IDL Compatibility Check ## Product A local CLI for Solana teams that compares two Anchor IDL files and highlights changes likely to break existing clients. It checks the interface described by the files; it does not test a deployed program. ```bash idl-check released.json proposed.json --format markdown ``` ## First-version checks - **Breaking:** removed instruction, account, argument, or error name; changed argument type or order; changed required account order. - **Review:** added required account or argument; changed account mutability or signer requirement. - **Informational:** added instruction, event, or error. Each finding includes the instruction or type path, old and new values, and a short explanation. Exit code `1` means at least one breaking finding, so teams can use it in CI. ## Acceptance criteria Given two valid IDLs, the tool produces the same ordered findings on repeated runs. Given an invalid IDL, it names the file and parse error without claiming a compatibility result. A clean report says **“No differences detected by these checks”**, not “safe to deploy.”

# Self-Directed Draft: Solana Deployment Config Diff ## Product A local CLI that compares two Solana app configuration files before a release. It flags changes that deserve human review, such as a new program ID, treasury address, cluster, or transaction fee payer. It does **not** verify on-chain state or approve a deployment. ## Command ```bash sol-config-diff previous.json candidate.json --format markdown ``` ## Input Each file contains a `cluster` and named entries under `programs`, `accounts`, and `feePayers`. The tool compares values by name; it never needs keys or wallet access. ## Output A short report with: - **Changed:** old and new values, grouped by field - **Added or removed:** entries that may need documentation updates - **Review prompts:** “Is this the intended cluster?” and “Has the new treasury address been independently checked?” - **Exit status:** `0` for no differences, `1` for differences, `2` for invalid input ## First-release boundaries Run entirely offline. Reject malformed public keys and unknown clusters. Never label an address “safe” or “verified.” Keep the report deterministic so a team can attach it to a release review.

# Self-Directed Draft: Solana Transaction Failure Reproducer ## Product A local CLI that converts a failed Solana transaction into a compact, shareable debugging bundle. It helps teams reproduce failures without exposing private keys or requiring access to production systems. ## Core Workflow ```bash sol-repro inspect <transaction-signature> --rpc <endpoint> sol-repro replay bundle.json --rpc <endpoint> sol-repro redact bundle.json --out safe-bundle.json ``` ## Output The tool generates: - Transaction message and account metas - Instruction program IDs and data - Signer and writable-account flags - Recent blockhash context - Simulation result and log messages - Error classification - Runtime and feature-set metadata when available - Redacted JSON suitable for issue trackers Example summary: ```text Status: FAILED Category: ACCOUNT_NOT_INITIALIZED Failing instruction: 2 Program: <program-id> Likely action: verify account creation and owner before retrying ``` ## Safety Requirements - Never export secret keys, seed phrases, or wallet adapters - Mask configurable account addresses in redacted bundles - Make all RPC calls read-only or simulation-only - Require explicit confirmation before replaying any instruction set - Clearly distinguish observed errors from heuristic suggestions ## MVP Scope 1. Fetch a transaction by signature. 2. Parse instructions and log messages. 3. Run a simulation using the recovered message where supported. 4. Classify common failures: - Missing account - Invalid account owner - Insufficient funds - Custom program error - Compute exhaustion - Blockhash expiration 5. Export Markdown and JSON reports. ## Acceptance Checklist - Same input produces deterministic report structure. - Reports remain useful when simulation is unavailable. - Redaction removes private-looking fields before export. - No signing or transaction submission code is included in the MVP. - Every heuristic includes an “evidence” section pointing to logs or account metadata. ## Suggested Packaging - Rust or TypeScript CLI - JSON schema for bundles - Fixture-based tests using sanitized transactions - Plugin interface for program-specific error decoders

# Self-Directed Draft: Solana RPC Compatibility Probe ## Product A local CLI that tests whether an RPC endpoint supports the read methods and response shapes required by a Solana application. It performs read-only requests and produces a machine-readable compatibility report. ## Intended Users - Wallet and portfolio app developers - Indexer and analytics teams - Support engineers comparing RPC providers - CI pipelines validating staging infrastructure ## CLI ```bash rpc-probe \ --url "$SOLANA_RPC_URL" \ --suite wallet-readiness \ --json report.json ``` ## Test Suite ### Core connectivity - `getHealth` - `getVersion` - `getGenesisHash` - `getSlot` - `getEpochInfo` ### Account and token reads - `getBalance` - `getAccountInfo` - `getMultipleAccounts` - `getTokenAccountBalance` - `getTokenAccountsByOwner` ### Transaction history - `getSignaturesForAddress` - `getTransaction` - `getLatestBlockhash` - `isBlockhashValid` Each test records: ```json { "method": "getBalance", "status": "pass", "latency_ms": 143, "http_status": 200, "error": null, "schema_checks": ["value.number", "context.slot.number"] } ``` ## Compatibility Rules A test passes only when: 1. The RPC returns a valid JSON-RPC response. 2. The response contains the expected `result` or structured `error`. 3. Required fields have the expected types. 4. The configured commitment is accepted. 5. Errors are classified rather than treated as generic failures. Error classes: - `unsupported_method` - `invalid_params` - `rate_limited` - `upstream_unavailable` - `malformed_response` - `timeout` ## Sample Summary ```text RPC Compatibility Report Endpoint: configured URL Suite: wallet-readiness Passed: 11 Failed: 2 Warnings: 1 FAIL getTokenAccountsByOwner class: unsupported_method impact: token-account discovery unavailable FAIL getTransaction class: malformed_response impact: transaction detail parsing may fail WARN getHealth class: upstream_unavailable impact: health status cannot be trusted ``` ## Safety Boundaries - Read-only JSON-RPC methods only - No private keys, signing, transaction submission, or account mutation - Redact endpoint credentials from logs - Replace public keys and URLs with hashes in optional shared reports - Configurable request timeout and concurrency limit ## Acceptance Criteria - Runs against a local validator or configured RPC URL. - Exits `0` when all required tests pass. - Exits `1` when required tests fail. - Emits both human-readable text and stable JSON. - Supports a custom YAML suite with method, parameters, required fields, and severity. - Includes request IDs and timestamps for reproducibility without exposing secrets.

# Self-Directed Draft: Solana Token Configuration Linter ## Product A read-only CLI that checks whether a Solana token’s on-chain configuration and published project configuration are internally consistent before documentation, support, or launch communications are prepared. ## Inputs - Mint address - Optional expected configuration file: ```yaml decimals: 6 freeze_authority: null mint_authority: "expected-address" token_program: "expected-program-id" ``` - RPC endpoint supplied by the operator ## Checks - Mint account is readable - Token program identity - Supply and decimals - Mint authority status - Freeze authority status - Token-2022 extension presence - Metadata account discoverability, when applicable - Expected values versus observed values - Incomplete or contradictory configuration entries - RPC response consistency across repeated reads ## Output Terminal report: ```text Token Configuration Report Status: REVIEW REQUIRED [PASS] Mint account readable [PASS] Decimals match expected value: 6 [WARN] Freeze authority is active [FAIL] Expected token program differs from observed program [INFO] Supply: <value returned by RPC> Next actions: 1. Confirm the intended token program. 2. Document whether freeze authority is deliberate. 3. Re-run after configuration changes. ``` Machine-readable JSON should include: - `mint` - `observed` - `expected` - `checks` - `severity` - `rpc_endpoint_label` - `generated_at` ## Safety Boundaries - Never signs transactions - Never submits transactions - Never changes authorities or metadata - Does not label a token safe, legitimate, or investable - Treats missing RPC data as `UNKNOWN`, not `PASS` - Redacts private keys and environment secrets from errors ## Suggested Commands ```bash tokenlint inspect <MINT> tokenlint inspect <MINT> --expected config.yaml --json report.json tokenlint compare report-a.json report-b.json ``` ## Acceptance Checklist - [ ] Works with an operator-provided RPC endpoint - [ ] Clearly distinguishes `PASS`, `WARN`, `FAIL`, and `UNKNOWN` - [ ] Handles malformed addresses without crashing - [ ] Supports retries with bounded timeouts - [ ] Produces deterministic JSON field names - [ ] Includes fixture-based tests for standard and Token-2022 mints - [ ] Documents that RPC responses may be incomplete or stale - [ ] Includes no signing, wallet import, or transaction submission code

# Self-Directed Draft: Solana Transaction Failure Triage Kit ## Product A local CLI that converts a failed Solana transaction into a concise, reproducible debugging report for developers and support teams. It decodes available logs and account metadata without signing, submitting, or modifying transactions. ## Problem Teams often receive only a signature, wallet address, or screenshot when a transaction fails. Engineers then manually inspect logs, instruction ordering, program errors, account permissions, and compute usage. ## MVP ```bash solana-triage inspect \ --signature <SIGNATURE> \ --rpc-url <RPC_URL> \ --output report.md ``` Optional offline mode: ```bash solana-triage inspect --json transaction.json --output report.md ``` ## Report Sections 1. **Transaction identity** - Signature, slot, block time if supplied by the RPC - Success or failure status 2. **Failure summary** - First detected error - Program ID associated with the error - Log line and instruction index 3. **Instruction timeline** - Program invoked - Account count - Compute units consumed, when available - Inner instructions 4. **Likely causes** - Missing signer - Invalid account owner - Account not initialized - Insufficient funds - Custom program error - Compute budget exceeded - Blockhash or confirmation issue 5. **Reproduction bundle** - Sanitized transaction message - Relevant logs - Input arguments when available - CLI version and configuration hash 6. **Suggested next checks** - Verify account ownership - Confirm required signer set - Compare expected account layout - Re-run against a controlled test fixture ## Design Requirements - Never request private keys or seed phrases. - Never sign, broadcast, retry, or alter transactions. - Redact configurable address fields in exported reports. - Preserve raw logs separately from the human-readable summary. - Mark every inference as “possible cause,” not a diagnosis. - Support JSON and Markdown output. - Exit with a nonzero status when the inspected transaction failed. ## Example Output ```text Status: FAILED Failure: custom program error Program: <PROGRAM_ID> Instruction: 3 Log: failed to deserialize account data Possible causes: - Account data layout does not match the deployed program. - Wrong account supplied for instruction 3. - Account belongs to a different program version. Next checks: [ ] Confirm account owner [ ] Compare data length with expected layout [ ] Reproduce with a known-good fixture ``` ## Success Criteria A support engineer can turn a transaction signature into a shareable report in one command, while the tool remains strictly read-only and clearly separates observed evidence from hypotheses.

# Self-Directed Draft: Solana Authority & Upgrade Inventory A read-only tool that helps Solana teams document administrative control over programs, mints, token accounts, and treasury wallets. It produces a shareable inventory without signing, submitting, or changing transactions. ## Problem Teams often store authority information across scripts, explorers, spreadsheets, and chat. During audits or handoffs, nobody has a single view of: - Which keys control critical assets - Whether authorities are revoked, retained, or unknown - Which multisig or governance process is expected - When the inventory was last reviewed ## MVP ### Input ```yaml network: mainnet-beta entries: - label: Core program address: "<program-address>" kind: program expected_authority: multisig - label: Main mint address: "<mint-address>" kind: mint expected_authority: revoked ``` Supported entry types: - Program - Mint - Token account - System account - Custom address ### Output Generate: 1. **Authority table** - Label - Address - Resource type - Observed authority fields - Expected authority - Status: `match`, `mismatch`, `unknown`, or `not_applicable` 2. **Review queue** - Missing labels - Unexpected authorities - Duplicate addresses - Entries requiring manual confirmation 3. **Machine-readable JSON** - Timestamp - Network selected by the user - Input configuration - Observations - Tool version ## Safety rules - Read-only by default - Never request private keys - Never sign or submit transactions - Treat RPC responses as observations, not proof of organizational ownership - Clearly distinguish “authority is set to address X” from “address X is controlled by team Y” - Require explicit user confirmation before marking an issue resolved ## Suggested interface ```text Authority Inventory Network: mainnet-beta Reviewed: 2025-01-01T12:00Z STATUS RESOURCE OBSERVED AUTHORITY EXPECTED PASS Main mint None Revoked WARN Core program <address> Multisig OPEN Treasury Unknown Multisig 3 entries | 1 pass | 1 warning | 1 open review ``` ## Acceptance criteria - Imports and validates the YAML schema. - Rejects malformed public-key strings. - Handles unavailable RPC responses without inventing values. - Exports Markdown and JSON. - Preserves the exact input alongside observations. - Gives every non-pass result a human-readable reason. - Includes tests for revoked, populated, unavailable, and duplicate entries. ## Future extensions - Scheduled re-checks with user-controlled storage - Signed, locally generated review reports - Support for multisig member documentation - Diff view between two inventory snapshots

# Self-Directed Draft: Solana Token Launch Readiness CLI A local CLI that turns token-launch configuration into a reviewable checklist before a team publishes instructions or executes transactions. It inspects supplied addresses and configuration, but never signs or submits transactions. ## MVP command ```bash token-ready check --config launch.yaml --output report.json ``` ## Configuration ```yaml network: mainnet-beta mint: "<MINT_ADDRESS>" decimals: 6 expected_supply: "1000000000" authorities: mint: "<EXPECTED_AUTHORITY>" freeze: null distribution: treasury: "<ADDRESS>" treasury_amount: "400000000" ``` ## Checks - Network and address format - Mint decimals match the declared configuration - Expected supply matches the configured allocation total - Mint authority status and expected address - Freeze authority status and expected address - Treasury and allocation addresses are distinct where required - Allocation totals reconcile without rounding - Duplicate recipient detection - Optional review of metadata URI and symbol fields - Required approvals recorded outside the chain ## Report format Each check returns: ```json { "id": "allocation.total", "status": "pass", "severity": "error", "message": "Configured allocations reconcile.", "evidence": "..." } ``` Statuses: `pass`, `warn`, `fail`, or `not_checked`. The terminal summary should show only blockers first: ```text READY: NO 2 errors · 1 warning · 8 passed ERROR allocation.total ERROR authorities.freeze WARNING metadata.uri ``` ## Safety boundaries - Read-only by default - No private-key or seed-phrase input - No automatic authority changes - Explicitly labels RPC-derived values as observations - Requires a human to confirm any “ready” decision - Supports exporting a timestamped JSON report for internal review ## Delivery slice 1. Config parser and schema validation 2. Read-only chain inspection adapter 3. Deterministic allocation reconciliation 4. Human-readable and JSON reports 5. Fixture-based tests for missing authorities, mismatched supply, duplicates, and invalid addresses ## Success criterion A reviewer can run one command and identify launch-blocking configuration errors without manually comparing multiple spreadsheets or transaction screens.

# Self-Directed Draft: Solana Event Delivery Reliability Kit A lightweight, self-hostable service for receiving Solana-related events, recording delivery attempts, and replaying failed notifications. It helps teams distinguish chain processing from their own webhook delivery problems. ## Core workflow 1. An event producer submits an event with a unique `event_id`. 2. The service stores the event and delivery status. 3. It sends the payload to configured HTTPS endpoints. 4. Failed attempts use bounded retries. 5. Operators can inspect, pause, or replay individual events. ## MVP scope ### Event record ```json { "event_id": "evt_123", "type": "transaction_observed", "network": "configured-network", "source_reference": "opaque-reference", "payload": {}, "created_at": "2025-01-01T00:00:00Z" } ``` ### Delivery states - `pending` - `delivered` - `retrying` - `failed` - `paused` ### Required controls - Endpoint registration and disable switch - Per-endpoint signing secret - Idempotency key: `event_id` - Configurable timeout and retry limit - Manual replay - Redacted delivery logs - Payload size limit - Basic rate limiting ## Operator view For each endpoint, show: - Delivery success count - Last successful attempt - Last failure reason - Pending and failed event counts - Replay button - Pause/resume control Never display signing secrets after creation. Avoid storing private keys or wallet credentials. ## API sketch ```text POST /events GET /events/{event_id} POST /events/{event_id}/replay GET /endpoints/{endpoint_id}/deliveries POST /endpoints/{endpoint_id}/pause POST /endpoints/{endpoint_id}/resume ``` ## Acceptance checklist - Duplicate `event_id` does not create duplicate records. - Every delivery attempt has a timestamp and outcome. - Replays remain traceable to the original event. - Failed endpoints cannot block unrelated endpoints. - Secrets are encrypted at rest or injected through deployment configuration. - Logs redact authorization headers and sensitive payload fields. - The system clearly labels event receipt separately from downstream delivery. ## Non-goals - Custody of funds - Transaction signing - Guaranteeing event completeness - Replacing a Solana RPC provider - Claiming that a delivered webhook proves transaction finality ## Positioning “Know whether your event was received, delivered, retried, or lost—without building the queue yourself.”

# Self-Directed Draft: Solana Wallet Approval Preview **Product spec:** A small UI component that helps users understand a proposed transaction *before* they approve it. It provides context, not a safety guarantee. ## MVP Given an unsigned transaction and the connected wallet address, display: - The requesting app’s name as supplied by the app, clearly labeled **unverified**. - The network and fee payer. - A plain-language summary of recognized instructions, including token, amount, sender, and recipient when available. - An **“Unknown action”** label for every instruction the component cannot interpret. - Any requested account permissions, with special emphasis on delegate or authority changes. The original wallet approval screen remains the final source of action; this component must not silently sign or submit transactions. ## Design rules - Never replace missing data with a reassuring guess. - Show raw account addresses behind an expandable detail control. - If a transaction contains both recognized and unknown instructions, show both; do not summarize the whole transaction as a simple transfer. - Use neutral warnings: “Cannot interpret this instruction,” not “This is a scam.” ## Acceptance test A user reviewing a transaction with one recognizable transfer and one unrecognized instruction sees the transfer details **and** a prominent unknown-action warning before choosing whether to continue.

# Self-Directed Draft: Solana Transaction Triage Card A reusable support artifact for diagnosing failed transactions without exposing private keys or requiring production access. ## Purpose Help developers move from “the transaction failed” to a useful bug report or next debugging step. ## User flow 1. Copy the transaction signature and intended action. 2. Record the wallet/network context. 3. Capture the simulation or explorer error. 4. Classify the failure. 5. Attach the smallest safe evidence bundle. ## Triage template ```md ## Transaction failure report - Network/cluster: - Approximate time: - Transaction signature: - Intended action: - Wallet or client version: - Program ID(s), if known: - Expected result: - Actual result: ### Error details - User-facing message: - Simulation logs: - Program error code: - Compute budget / priority settings: - Recent account or balance changes: ### Classification - [ ] Insufficient balance or token account issue - [ ] Account missing, incorrect, or already initialized - [ ] Authority or signer mismatch - [ ] Stale blockhash / expired transaction - [ ] Compute limit or fee issue - [ ] Program constraint or validation failure - [ ] Client serialization or instruction mismatch - [ ] Unknown ### Safety checks - [ ] No seed phrase or private key included - [ ] No raw sensitive user data included - [ ] Signature and public addresses double-checked - [ ] Reproduction steps written clearly ### Suggested next action - [ ] Reproduce with simulation - [ ] Compare instruction data against the client schema - [ ] Verify account ownership and signer flags - [ ] Retry with a fresh blockhash - [ ] Increase compute budget or review account inputs - [ ] Escalate with complete logs ``` ## Product shape - **Format:** Markdown template plus optional CLI generator. - **Input:** Transaction signature, cluster, and free-text context. - **Output:** Redacted Markdown report suitable for an issue tracker or support channel. - **Non-goals:** Custody, automatic retries, key handling, or claiming that an error has been resolved. ## Acceptance criteria - Produces a report in under two minutes. - Separates observed evidence from guesses. - Warns users before including secrets. - Supports both technical debugging and nontechnical support handoff. - Can be used offline except where the user manually supplies transaction details.

# Self-Directed Draft: Solana Release Readiness Checklist A reusable checklist for teams preparing a Solana program, client SDK, or frontend release. ## 1. Scope and compatibility - [ ] List changed programs, instructions, accounts, APIs, and UI flows. - [ ] Record whether existing accounts remain readable. - [ ] Identify required migrations and whether they are reversible. - [ ] Document supported cluster, program IDs, and dependency versions. - [ ] Define the intended rollback or pause procedure. ## 2. Program safety - [ ] Verify signer and authority checks for every changed instruction. - [ ] Validate account ownership, mutability, seeds, and constraints. - [ ] Check arithmetic boundaries, token decimals, and rounding behavior. - [ ] Confirm duplicate-account and unexpected-account handling. - [ ] Test failure paths, not only successful execution. - [ ] Review upgrade authority and initialization paths. ## 3. Transaction behavior - [ ] Confirm compute-unit and transaction-size assumptions. - [ ] Test expired blockhash and dropped-transaction handling. - [ ] Ensure retries cannot unintentionally repeat an action. - [ ] Display simulation errors in actionable language. - [ ] Verify confirmation-status handling across commitment levels. - [ ] Test wallet rejection, insufficient balance, and missing-account cases. ## 4. Data and migration - [ ] Define the source of truth for indexed or cached data. - [ ] Version serialized account layouts and client types. - [ ] Prepare migration scripts with dry-run and progress reporting. - [ ] Verify migration results against expected counts and invariants. - [ ] Preserve a recovery snapshot where practical. ## 5. Operational controls - [ ] Document who can pause, upgrade, migrate, or change configuration. - [ ] Test emergency procedures in a non-production environment. - [ ] Prepare a short incident message template. - [ ] Assign an owner for release decisions and post-release monitoring. - [ ] Record transaction IDs and configuration changes for internal review. ## 6. User-facing release notes Include: ```text Release: Date: Affected program/client: What changed: Who is affected: Required user action: Known limitations: How failures are reported: Support contact or issue channel: Rollback or pause status: ``` ## Release gate Ship only when: - Critical-path tests pass. - Migration and rollback procedures have been exercised. - Authority and configuration changes are reviewed by a second person. - Client behavior matches the deployed program interface. - Known limitations are written in user-facing language. - The release owner has explicitly recorded a go/no-go decision.

# Self-Directed Draft: Solana Program Surface Map **Product specification for Solana teams** A local CLI that turns a Solana program repository into a clear, reviewable map of its public instructions, accounts, authorities, and documentation gaps. ## Problem Teams often understand their codebase but lack a concise artifact for reviewers, integrators, and support contributors. Important details are scattered across source files, IDLs, tests, and README pages. ## MVP Command: ```bash surface-map scan ./programs/my_program ``` Generate: - Public instruction list - Required signers and writable accounts - Account initialization and closure paths - Authority/admin references - Custom errors - IDL-to-source mismatches - Instructions without nearby tests - Instructions missing user-facing documentation - Unresolved or “unknown” fields marked explicitly Output formats: ```bash surface-map scan . --format markdown surface-map scan . --format json ``` ## Example Markdown output ```md ## update_config **Purpose:** Update protocol configuration **Signers:** config_authority **Writes:** config_account **Errors:** Unauthorized, InvalidFee **Tests found:** yes **Documentation:** missing **Confidence:** source + IDL ``` ## Safety principles - Read-only analysis; never signs, submits, or modifies transactions. - Distinguish parsed facts from inferred descriptions. - Never label an account as safe, trusted, or harmless automatically. - Preserve source locations for every finding. - Fail clearly when the repository cannot be parsed. ## Ideal users - Solana program maintainers - Security-review preparation teams - SDK and integration developers - Community support contributors ## Acceptance criteria - Produces a deterministic report from the same repository state. - Links each finding to a file and line where possible. - Handles missing IDLs without inventing metadata. - Exits nonzero when parsing fails. - Includes a sample fixture repository and snapshot tests. - Keeps generated reports suitable for pull requests. ## Natural paid extensions - Custom report templates for a team - CI checks for undocumented public instructions - Historical surface-map diffs between releases - Integration-specific summaries for SDK maintainers

# Self-Directed Draft: Solana Transaction Recovery Panel **Product specification for Solana teams** A compact UI that helps users understand what happened after they submit a transaction and choose a safe next step—without encouraging blind retries. ## Problem Users often see a spinner or generic error after signing. They cannot tell whether a transaction: - Was never submitted - Is still being checked - Succeeded - Failed before execution - May have executed despite a client-side timeout ## Core experience Show a transaction status card with: - **Current state:** Preparing, Submitted, Confirmed, Failed, or Verification uncertain - **Short explanation:** Plain-language status, not raw RPC errors alone - **Explorer action:** Open a transaction link only when a usable signature exists - **Next action:** Retry, refresh status, edit inputs, or contact support - **Technical details:** Collapsible signature, program error, slot, and raw response ## Safety rules 1. Never label a transaction failed solely because the frontend timed out. 2. If a signature exists, check status before displaying a retry button. 3. For operations that could duplicate an action, use wording such as **“Verify before retrying.”** 4. Keep user-entered inputs visible so they can confirm amount, destination, and settings. 5. Treat missing or stale status as **unknown**, not successful. ## Suggested copy **Verification uncertain** “We received a response timeout. This action may still have been processed. Check its status before trying again.” **Confirmed** “Your transaction was confirmed.” **Failed** “The transaction was rejected before completion. Review the details and try again.” **Retry guard** “Check status first” → “Retry only if this action was not completed.” ## Implementation brief - Assign every submission a local attempt ID. - Store the signature separately from frontend request state. - Poll status with bounded retries, then transition to **Verification uncertain**. - Make status handling idempotent: repeated refreshes must not create duplicate actions. - Log sanitized error categories for support diagnostics. - Provide a reusable component API: ```ts <TransactionRecovery signature={signature} actionLabel="Swap" retry={() => submitAgain()} inputs={summary} /> ``` ## Acceptance criteria - A timeout never renders as definitive failure. - A known signature is always available for copying. - Retry is disabled or guarded while status is unknown. - Users can distinguish wallet rejection, simulation failure, network uncertainty, and confirmed success. - The component works on mobile without hiding the primary status.

# Self-Directed Draft: Solana Transaction Intent Preview **Product specification for Solana teams** A pre-signing panel that explains what an app is asking a wallet to approve, using only decoded instruction data and clear uncertainty labels. ## Core experience Before the wallet prompt, show: - **Action:** “Swap,” “Create account,” “Transfer,” or “Unknown action” - **Assets involved:** token symbols and amounts when confidently decoded - **Destination:** shortened address plus copy button - **Network fee:** estimated fee, if available - **Account changes:** accounts created, closed, or modified - **Authority changes:** ownership, delegate, freeze authority, or spending permissions when detected - **Warnings:** plain-language risks requiring attention ## Trust rules - Never describe an instruction as safe merely because it decoded successfully. - Mark incomplete data as **“Could not verify.”** - Do not infer token identity from an unverified symbol alone. - Distinguish **app-provided labels** from **on-chain decoded data**. - Keep the wallet’s final signing prompt authoritative. - Provide a “View technical details” drawer for advanced users. ## Example copy **You’re about to approve** > Transfer 25 USDC to `7xK…pQ2` > Network fee: approximately 0.000005 SOL > No authority changes detected. **Review carefully** > This request would modify an account authority. Confirm that you recognize the destination and intended action. **Unable to interpret** > This transaction contains instructions this app cannot fully decode. Review the wallet prompt before signing. ## Minimal API shape ```ts type IntentPreview = { title: string; instructions: Array<{ label: string; confidence: "high" | "medium" | "unknown"; details: string[]; warnings: string[]; }>; feeLamports?: number; modifiedAccounts: string[]; authorityChanges: string[]; rawTransactionLink?: string; }; ``` ## Acceptance checklist - [ ] Preview appears before wallet signing. - [ ] Unknown instructions are visibly labeled. - [ ] Addresses can be copied without truncation. - [ ] Amounts include token mint context where available. - [ ] Authority changes receive prominent treatment. - [ ] No secret keys, seed phrases, or signing material are requested. - [ ] Technical details remain available without overwhelming first-time users. - [ ] Preview failure does not silently become approval.

# Self-Directed Draft: Wallet Sign-In Session Controls **Product spec for Solana teams** A small account panel that lets users see and end sessions created through wallet sign-in. Its purpose is to make access visible and revocable—not to manage wallet permissions. **User flow** 1. After sign-in, show the connected account, the app’s name, and when the app session expires. 2. In **Active sessions**, list each session’s creation time, last activity time, and a user-friendly device label. Avoid precise location claims. 3. Offer **Sign out this device** and **Sign out all devices**. Confirm the latter before acting. 4. After revocation, require a fresh sign-in for protected actions. **Implementation requirements** - Use a single-use, short-lived sign-in challenge tied to the intended app domain and account. Verify the signed challenge server-side. - Store session credentials securely; never request a seed phrase or private key. - Expire idle sessions and invalidate revoked sessions server-side. - Treat a disconnected wallet and an active app session as separate states; explain that distinction in the UI. **Acceptance check:** A revoked session can no longer access a protected endpoint, even if its browser tab remains open.

# Self-Directed Draft: Solana Transaction Failure Report **Product brief:** A small component Solana apps can add after a failed transaction. It turns a technical error into a useful support report without asking users to share wallet secrets. ## User flow 1. Show **“Transaction not completed”**, not “funds lost.” If the result is uncertain, show **“Status unknown—check before retrying.”** 2. Offer a short explanation based only on the error data available to the app. Label guesses as guesses. 3. Provide **Copy support report** and **Try again**. Do not make retry the primary action when status is unknown. ## Copyable report ```text Action attempted: [app-provided description] Network: [selected network] Time: [device time and timezone] Status: [failed / unknown] Error code and message: [raw values, if available] Transaction signature: [if available] App version: [version] ``` Show the report for review before copying. Exclude seed phrases, private keys, authentication tokens, and full wallet addresses by default; let users choose whether to add a public address. ## Acceptance criteria - An absent signature is shown as “Not available,” never fabricated. - Unknown errors retain their raw code and message. - The component never recommends repeated submission when confirmation is uncertain. - Copying the report requires an explicit user action.

# Self-Directed Draft: Transaction Preview Card **Product spec for Solana teams** A reusable UI card that helps users understand a proposed transaction *before* they approve it in their wallet. It must never describe an outcome as guaranteed. ## Required fields - **Action:** Plain-language description supplied by the app, such as “Swap tokens.” - **Network and account:** Display the selected network and a shortened public address. - **Estimated changes:** Show assets expected to leave and enter the account, with units. - **Costs and uncertainty:** Show the available fee estimate, slippage setting if relevant, and a clear “estimate may change” label. - **Unknowns:** If the app cannot interpret an instruction or estimate an asset change, say so prominently rather than showing a reassuring summary. ## Interaction rules 1. Keep the **Review in wallet** button disabled until the preview finishes loading or explicitly reports what it cannot determine. 2. Refresh the preview when the account, network, amount, or transaction changes. 3. If the wallet presents materially different details, instruct the user to stop and review rather than relying on the card. **Acceptance test:** A user can identify the selected account, expected asset changes, estimated costs, and any unresolved uncertainty without opening a developer console.

# Self-Directed Draft: Solana Release Readiness Checklist A reusable pre-release checklist for Solana programs, clients, and operational tooling. ## 1. Scope and rollback - [ ] Release owner and reviewer are named. - [ ] Changed programs, clients, IDLs, scripts, and configuration are listed. - [ ] Rollback or pause procedure is written and tested in a non-production environment. - [ ] Upgrade authority and emergency authorities are documented for the team. - [ ] Migration order is explicit, including dependencies and abort conditions. ## 2. Program safety - [ ] Account ownership checks are enforced. - [ ] Signer requirements are enforced. - [ ] PDA seeds, bump handling, and expected program IDs are validated. - [ ] Account initialization and re-initialization paths are reviewed. - [ ] Arithmetic uses deliberate overflow and precision behavior. - [ ] Token mint, token program, decimals, and authority assumptions are checked. - [ ] Closing, draining, and authority-transfer paths have dedicated tests. - [ ] Error codes are stable, descriptive, and surfaced to clients. ## 3. Client compatibility - [ ] The client uses the intended program ID and cluster configuration. - [ ] IDL and generated types match the deployed interface. - [ ] Transaction instructions are inspected for account order and mutability. - [ ] Confirmation, timeout, retry, and blockhash-expiration behavior are defined. - [ ] The UI handles rejected, expired, partially completed, and retried transactions. - [ ] No private keys, seed phrases, or sensitive signing material enter logs or telemetry. ## 4. Testing - [ ] Unit tests cover success, failure, unauthorized, malformed, and boundary cases. - [ ] Integration tests cover realistic account states and transaction composition. - [ ] Tests include duplicate submission and retry scenarios. - [ ] Upgrade and migration tests run from a snapshot-like starting state. - [ ] Failure output includes program logs, instruction context, and a reproducible test case. ## 5. Observability - [ ] Release version is attached to application and service logs. - [ ] Important actions have correlation IDs or equivalent trace references. - [ ] Alerts distinguish user errors, RPC issues, program errors, and internal failures. - [ ] Logs redact secrets and unnecessary personal data. - [ ] A named person owns first response during the release window. ## 6. Go/no-go record **Release:** **Reviewer:** **Target cluster:** **Planned window:** **Known risks:** **Rollback trigger:** **Rollback command/procedure location:** **Decision:** ☐ Go ☐ No-go **Decision notes:**

# Self-Directed Draft: Solana Repro Pack ## Product concept A lightweight form and dashboard that turns vague Solana user reports into reproducible engineering tickets—without requesting private keys or seed phrases. ## Problem Reports such as “my transaction failed” often omit the exact network, signature, wallet, instruction, or error context needed to investigate. ## MVP workflow 1. **User submits a report** - Transaction signature, if available - Network/cluster - Approximate time - App action attempted - Expected result - Actual result - Screenshot or copied error - Optional contact method 2. **Form safety checks** - Block or warn on seed phrases, private keys, passwords, and access tokens - Explain that support will never request them - Redact sensitive-looking text before storage 3. **Automatic case summary** - One-line issue title - Reproduction inputs - Evidence links or pasted logs - Missing-information checklist - Severity selected by the team 4. **Internal triage** - Status: New, Needs information, Reproduced, Fix planned, Resolved - Owner - Labels: wallet, RPC, program, frontend, indexing, documentation - Internal notes and resolution text ## Suggested case template ```text Case ID: Reported at: Cluster: Transaction signature: User action: Expected: Observed: Error text: Reproduction steps: Related release/version: Severity: Owner: Current status: Resolution: ``` ## Guardrails - Never ask for a seed phrase, private key, or wallet password. - Treat pasted logs as untrusted input. - Allow users to delete their report. - Store only the minimum data needed for investigation. - Make transaction details optional; users may report non-transaction issues. - Clearly distinguish “transaction not found” from “transaction failed.” ## Success criteria - An engineer can begin investigation without a follow-up message in most complete reports. - Support can filter cases by component and severity. - Every resolved case produces a reusable explanation or troubleshooting article. - Sensitive credentials are rejected or redacted before submission. ## Sellable implementation scope - Report form - Redaction and validation layer - Team dashboard - Ticket export/webhook - Custom branding and fields - Deployment documentation - Optional monthly maintenance package

# Self-Directed Draft: Solana Transaction Intent Receipt ## Purpose Give users and signers a plain-language summary of what a Solana transaction is intended to do before approval. ## Problem Wallet prompts often expose technical details without clearly answering: - Which asset or account changes? - Who receives authority? - Is this a one-time action or an ongoing permission? - What should the user expect afterward? ## Product format An embeddable “intent receipt” shown immediately before wallet approval. ## Receipt layout **Header:** “Review this action before signing” **Intent summary:** > Deposit 25 USDC into the lending vault and receive a corresponding position token. **Change list:** - **You send:** asset, amount, source account - **You receive:** asset or position, destination account - **Permissions changed:** authority, delegate, spending limit, or “None” - **Network fee:** estimated fee, if available - **Expiry:** blockhash or signing deadline **Risk flags:** - New delegate or authority assigned - Unlimited or unusually large allowance - Unknown destination - Multiple instructions bundled - Action cannot be reversed through the app **Confirmation prompt:** “I understand the listed changes and want to continue.” ## Team-facing API shape ```ts type IntentReceipt = { title: string summary: string changes: Array<{ direction: "send" | "receive" | "permission" asset?: string amount?: string accountLabel?: string detail: string }> riskFlags: string[] expiry?: string technicalReference?: string } ``` The application—not the receipt component—must derive and validate these values from the transaction it is presenting. ## MVP - React component with mobile-first layout - Structured intent schema - Custom labels for known program instructions - Fallback display for unrecognized instructions - Copyable technical reference for support - Accessible color, icons, and screen-reader labels - “Back” and “Open wallet” actions without auto-submission ## Acceptance checklist - [ ] Receipt is generated from the exact transaction being signed. - [ ] Every listed send/receive value maps to a transaction instruction. - [ ] Authority and delegate changes are explicitly surfaced. - [ ] Unknown instructions are labeled as unknown, not guessed. - [ ] Users can inspect technical details without making them the default view. - [ ] The UI never implies success before confirmation is observed. - [ ] Copy is reviewed for amount, token, account, and destination accuracy.

# Self-Directed Draft: Solana Program Upgrade Readiness Checklist ## Purpose Help Solana teams coordinate a program upgrade safely across engineering, product, support, and users. ## Release checklist ### 1. Scope - [ ] Record the upgrade objective in one sentence. - [ ] List changed instructions, accounts, permissions, and dependencies. - [ ] Identify whether existing accounts and clients remain compatible. - [ ] Define rollback or pause procedures, if available. - [ ] Assign one release owner and one incident contact. ### 2. Testing - [ ] Test successful flows for every changed instruction. - [ ] Test invalid inputs, insufficient funds, missing accounts, and duplicate submissions. - [ ] Test migrations with representative account data. - [ ] Verify transaction messages and user-facing error states. - [ ] Confirm client behavior against the intended program version. - [ ] Document any known limitations. ### 3. Operational controls - [ ] Confirm upgrade authority and signer access. - [ ] Review deployment commands before execution. - [ ] Prepare a maintenance window or staged rollout plan. - [ ] Define stop conditions, such as unexpected failures or account mismatches. - [ ] Prepare a lightweight activity log: time, operator, action, result. ### 4. User communication Publish before the upgrade: > **Planned program update** > We are preparing an update to improve: **[brief purpose]**. > Expected user impact: **[none / limited access / specific behavior]**. > Planned window: **[date and time, with timezone]**. > During the update, please avoid: **[specific action, if applicable]**. > We’ll post a completion notice and explain any required user action. Publish after the upgrade: > **Program update status** > The update is **[complete / paused / delayed]**. > Current user impact: **[description]**. > Required action: **[none / steps]**. > Next update: **[time or condition]**. ### 5. Post-release verification - [ ] Confirm the deployed version or release identifier. - [ ] Run a minimal successful transaction path. - [ ] Verify read operations and account parsing. - [ ] Check logs and support channels for new failure patterns. - [ ] Record unresolved issues and owners. - [ ] Archive the final release notes. ## Definition of ready The upgrade is ready only when the owner, test evidence, stop conditions, communication copy, and post-release verification steps are all recorded in one shared document.

# Self-Directed Draft: Solana Transaction Failure Triage Panel ## Purpose Help users understand failed transactions and choose a safe next action without forcing them to decode raw errors. ## Product format A reusable UI component for Solana apps, displayed after a transaction fails or remains unresolved. ## Core panel **Title:** “Your transaction didn’t complete” **Sections:** 1. **What happened** — plain-language explanation. 2. **What you can do** — one recommended next action. 3. **Technical details** — expandable logs, signature, and error text. 4. **Support handoff** — copyable diagnostic summary. ## Error categories and copy ### User rejected **Message:** “You cancelled the request in your wallet.” **Action:** “Try again when you’re ready.” **Avoid:** Treating cancellation as a system failure. ### Insufficient balance **Message:** “Your wallet may not have enough balance to complete this transaction.” **Action:** “Review the required amount and try again.” **Avoid:** Promising an exact required amount unless calculated by the app. ### Stale or expired transaction **Message:** “This transaction is no longer valid. Please create a new request.” **Action:** “Try again.” ### Program or instruction error **Message:** “The app rejected this request because one of its instructions could not be completed.” **Action:** “Review the inputs and try again. If it continues, contact support.” **Technical detail:** Show the original program error when available. ### Network or RPC issue **Message:** “The app could not reliably submit or confirm your transaction.” **Action:** “Check your connection, then try again.” **Avoid:** Claiming the transaction definitely failed if its final state is unknown. ### Unknown **Message:** “We couldn’t determine the final result.” **Action:** “Check your activity before retrying to avoid submitting twice.” ## Diagnostic summary Provide a copy button containing: ```text App: Network: Wallet: Action: Approximate time: Transaction signature: Observed state: Error message: ``` Only include fields available to the app. Never fabricate a signature or final status. ## Interaction rules - Keep the primary action singular and obvious. - Preserve user-entered form data when safe. - Disable duplicate submission while a retry is being prepared. - Show raw logs behind “Technical details.” - Distinguish “failed” from “unknown” states. - Make all error copy screen-reader accessible. ## Acceptance checklist - [ ] Every failure maps to a plain-language category. - [ ] Retry does not silently alter user inputs. - [ ] Unknown outcomes warn against immediate duplicate submission. - [ ] Diagnostic details are copyable. - [ ] No UI claims confirmation without application evidence. - [ ] Error messages avoid blame and unexplained jargon.

# Self-Directed Draft: Solana Transaction Status UX Kit ## Purpose A reusable interface and copy system that helps users understand whether a Solana transaction is preparing, awaiting signature, submitted, confirmed, or needs action—without exposing technical details prematurely. ## Product format A small component library for web apps: - Status banner - Transaction progress stepper - Copyable signature field - Explorer-link slot - Retry and support actions - Developer diagnostic drawer ## User-facing states ### 1. Preparing **Title:** Preparing transaction **Body:** We’re getting this transaction ready. **Action:** None ### 2. Awaiting wallet **Title:** Confirm in your wallet **Body:** Review the request and approve it to continue. **Action:** `Open wallet` ### 3. Submitted **Title:** Transaction submitted **Body:** Your transaction was sent. We’re waiting for confirmation. **Action:** `View details` ### 4. Confirmed **Title:** Transaction confirmed **Body:** The network confirmed your transaction. **Actions:** `Continue` · `View details` ### 5. Failed **Title:** Transaction needs attention **Body:** The transaction was not confirmed. You can try again or share the details with support. **Actions:** `Try again` · `Copy details` ### 6. Unknown or delayed **Title:** Confirmation is taking longer than expected **Body:** Keep this window open while we check again. Avoid submitting a duplicate until the status is clear. **Actions:** `Check again` · `Copy signature` ## Developer diagnostic drawer Display only on request: - Network/environment - Transaction signature, if available - Submission timestamp - Last status checked - Application error code - Retry count - RPC response category - Explorer URL, when configured Never request or display seed phrases, private keys, or wallet approval secrets. ## Component contract ```ts type TransactionStatus = | "preparing" | "awaiting_wallet" | "submitted" | "confirmed" | "failed" | "unknown"; type TransactionStatusProps = { status: TransactionStatus; signature?: string; explorerUrl?: string; errorCode?: string; onRetry?: () => void; onRefresh?: () => void; }; ``` ## Acceptance criteria - Every state has a plain-language title and next action. - The signature can be copied without being altered. - Refreshing status does not create a second transaction. - Failed and delayed states remain distinguishable. - Technical diagnostics are hidden by default. - The component supports keyboard navigation and visible focus states. - Copy avoids promising confirmation before the application verifies it. - The UI can render when no signature is available. ## Implementation note Treat the application’s verified status as the source of truth for user-facing copy. Keep explorer links configurable rather than hard-coded.

# Self-Directed Draft: Solana Wallet Integration Acceptance Checklist ## Purpose A reusable pre-release checklist for teams integrating wallet connection, signing, and transaction confirmation flows. ## Scope **Product:** **Environment:** devnet / testnet / mainnet **Owner:** **Review date:** ## 1. Connection - [ ] Wallet adapter initializes without blocking the page. - [ ] Connect, disconnect, and reconnect states are distinct. - [ ] Unsupported wallet errors are understandable. - [ ] Mobile and desktop connection paths are tested. - [ ] The app never requests a seed phrase or private key. - [ ] Public wallet addresses are displayed in shortened and copyable formats. ## 2. Network handling - [ ] The selected network is visible to the user. - [ ] Wallet network and application network mismatches are detected. - [ ] RPC failures produce an actionable message. - [ ] Retry behavior is bounded and does not create duplicate submissions. - [ ] Commitment level is defined for reads and confirmations. ## 3. Transaction flow - [ ] Users see what action they are approving before signing. - [ ] Fees and relevant account changes are explained where practical. - [ ] Signing, submission, confirmation, and failure are separate UI states. - [ ] The submitted transaction signature is captured when available. - [ ] Duplicate clicks cannot submit the same action twice. - [ ] Expired or blockhash-related failures offer a retry path. - [ ] Failed transactions do not appear as successful in the product UI. ## 4. Account and program safety - [ ] Required accounts are validated before transaction construction. - [ ] Program IDs and instruction parameters are environment-specific. - [ ] Token decimals and display units are handled consistently. - [ ] Account creation and rent implications are communicated. - [ ] Destructive or irreversible actions require explicit confirmation. - [ ] Transactions are simulated or otherwise checked before submission when appropriate. ## 5. Observability - [ ] Errors include a correlation ID or local event ID. - [ ] Logs exclude secret material and unnecessary personal data. - [ ] The team can associate a user action with its transaction signature. - [ ] Client, RPC, simulation, submission, and confirmation failures are distinguishable. - [ ] A support message tells users what information is safe to share. ## 6. Acceptance tests - [ ] Connect with a supported wallet. - [ ] Reject a signing request. - [ ] Switch to the wrong network. - [ ] Disconnect during submission. - [ ] Retry after an RPC timeout. - [ ] Submit an invalid transaction. - [ ] Refresh after submission but before confirmation. - [ ] Confirm success using the intended commitment level. - [ ] Test with an unfunded or missing associated token account. - [ ] Test on both mobile and desktop. ## Sign-off **Product owner:** **Engineering owner:** **Security reviewer:** **Known limitations:** **Rollback or disable-switch location:** **Approved for release:** yes / no

# Self-Directed Draft: Solana Transaction Triage Card ## Purpose A compact intake form for diagnosing failed or delayed transactions without requesting private keys or seed phrases. ## User-facing form **Report ID:** **Submitted by:** **Time observed (UTC):** **Environment:** mainnet / devnet / localnet / unknown **Wallet or app:** **RPC endpoint/provider:** **Transaction signature:** **Blockhash or slot, if known:** **Instruction/action attempted:** **Expected result:** **Observed result:** **Exact error message:** **First noticed at:** **Frequency:** once / intermittent / repeatable **Recent changes:** client / program / RPC / wallet / none known ## Evidence checklist - [ ] Transaction signature copied exactly. - [ ] Network identified. - [ ] Error preserved verbatim. - [ ] Reproduction steps recorded. - [ ] Failed and successful examples separated. - [ ] No seed phrases, private keys, access tokens, or personally identifying data included. ## Triage classification Assign one primary label: - **Submission:** transaction was not accepted or broadcast. - **Confirmation:** transaction was submitted but status is unclear. - **Execution:** transaction landed but an instruction failed. - **State:** account balance, ownership, PDA, or data differed from expectation. - **Fees/compute:** fee payer balance, compute budget, or priority settings involved. - **Client mismatch:** wallet, SDK, serialization, or program-version mismatch. - **Unknown:** insufficient evidence. ## Triage output **Likely boundary:** client / wallet / RPC / transaction / program / account state **Confidence:** low / medium / high **Next safe test:** **Owner:** **Status:** open / investigating / blocked / resolved **Resolution evidence:** **Follow-up action:** ## Operating rule Do not label an incident resolved solely because a retry succeeds. Record the original signature, the changed conditions, and evidence that the underlying failure mode is understood. ## Acceptance criteria for a small implementation - Form can be completed in under five minutes. - Required fields prevent missing network, signature, and exact error. - Sensitive-value warnings appear before submission. - Triage labels are searchable. - Every status change records an owner and timestamp. - Exported reports contain only the fields approved by the team.

# Self-Directed Draft: Solana Release Readiness Packet ## Purpose A lightweight template that helps Solana teams review a release before asking users to upgrade, without requiring production access or revealing secrets. ## Release summary - **Release name/version:** - **Owner:** - **Target date:** - **Change type:** feature / bug fix / migration / configuration - **Rollback approach:** - **Known limitations:** ## Impact map Document each affected surface: | Surface | Before | After | Risk | Owner | |---|---|---|---|---| | On-chain program | | | | | | Client/SDK | | | | | | Indexer/API | | | | | | Dashboard/docs | | | | | ## Required evidence Attach links or artifacts for: - [ ] Reproducible test cases - [ ] Account/schema changes - [ ] Compute-unit and transaction-size observations - [ ] Compatibility notes for existing clients - [ ] Migration or backfill instructions - [ ] Error-message changes - [ ] Monitoring signals and alert thresholds - [ ] Rollback procedure tested in a non-production environment ## Go/no-go review Each reviewer records one status: - **Ready:** evidence is sufficient. - **Blocked:** a specific issue prevents release. - **Conditional:** release is acceptable only with a named mitigation. **Open blockers** 1. Issue: Owner: Mitigation: Due date: ## User-facing release note > **What changed:** > **Who is affected:** > **What users need to do:** > **Potential interruption:** > **Where to report problems:** ## Acceptance criteria A release packet is complete when: - Every impacted surface has an owner. - Unknowns are explicitly marked. - Migration and rollback steps are written for a fresh operator. - At least one reviewer outside the implementation team signs off. - The user-facing note matches the technical scope. - Blockers have owners and dates, or the release is marked no-go. ## Suggested implementation Start with a Markdown form stored beside the release branch. Add a small CLI later that validates required fields, detects unchecked blockers, and generates the user-facing release note.

# Self-Directed Draft: Solana Program Upgrade Review Checklist Use this before proposing an upgrade. Record evidence beside each item; leave unknowns visible rather than treating them as approvals. **Scope** - [ ] Identify the program, proposed version, owner, and reason for the change. - [ ] List changed instructions, accounts, permissions, and user-visible behavior. - [ ] Confirm which clients or integrations need updating. **Safety** - [ ] Review authority and access-control changes with a second reviewer. - [ ] Test expected behavior, rejected inputs, and migration edge cases. - [ ] Record the exact build artifact and the source revision used to produce it. - [ ] Document how operators will detect a problem and who can pause dependent services. **Release decision** - [ ] Name the person authorized to approve the upgrade. - [ ] Define a go/no-go threshold for unresolved issues. - [ ] Write a recovery plan, including what cannot be reversed. - [ ] Prepare a short user notice covering impact, timing, and support contact. **Approval record:** version ___ · reviewers ___ · open risks ___ · decision ___

# Self-Directed Draft: Solana Transaction Failure Triage Kit ## Purpose Help Solana teams turn failed user transactions into actionable debugging reports without exposing private keys or requiring production database access. ## Core workflow 1. User pastes a transaction signature, serialized error, or application log. 2. Tool requests or accepts available transaction details. 3. It groups the failure into a likely category: - Blockhash expired - Instruction reverted - Account missing or incorrectly configured - Compute budget exceeded - Signature or authorization failure - RPC submission failure 4. It generates: - Plain-language explanation - Relevant instruction index - Suspected account or program - Suggested next diagnostic step - Copyable engineering report ## MVP interface ### Input panel - Transaction signature - Cluster selector - Optional application error message - Optional expected action, such as “deposit” or “swap” ### Result panel - Status: confirmed, failed, or unavailable - Failure category - Short explanation - Technical evidence - Diagnostic checklist - “Copy report” button ### Report format ```text Transaction triage report Signature: [provided signature] Cluster: [selected cluster] Observed status: [status] Failure category: [category] Instruction: [index/program if available] Summary: [Plain-language explanation] Evidence: - [log or decoded detail] - [account or execution detail] Next checks: - [check 1] - [check 2] - [check 3] ``` ## Safety and privacy requirements - Never request seed phrases, private keys, or wallet exports. - Treat pasted logs as untrusted text. - Redact likely secrets from copied reports. - Clearly distinguish observed data from hypotheses. - Show “insufficient information” instead of inventing a diagnosis. ## Technical design - Parser layer for transaction metadata and program logs. - Rule-based classifier for common failure patterns. - Adapter interface for optional RPC providers. - Local-first report generation where possible. - Pluggable decoder interface for team-specific programs. ## Acceptance criteria - A user can create a report in under two minutes. - Every diagnosis includes evidence or states that evidence is unavailable. - Reports can be copied as Markdown. - No private-key material is accepted by the input form. - The tool handles malformed signatures and unavailable transactions gracefully. - Team-specific error mappings can be added through a configuration file. ## Suggested pricing shape - Free local utility for individual debugging. - Paid team tier for shared error dictionaries, saved reports, and configurable program decoders.

# Self-Directed Draft: Solana Wallet Integration Test Harness ## Purpose Give Solana teams a repeatable way to test wallet connection, account changes, transaction signing, and failure states before release. ## MVP A local web tool with: - **Wallet controls:** connect, disconnect, switch account, reject connection - **Transaction scenarios:** sign-and-send, sign-only, insufficient funds, expired blockhash, user rejection - **Network selector:** devnet, testnet, mainnet-beta, and custom endpoint - **Event log:** timestamped wallet events, public keys, errors, and transaction status - **Reset button:** clears state and starts a fresh test session - **Export:** copies a redacted diagnostic report for issue tickets ## Acceptance criteria - The selected cluster is visible at all times. - Every wallet state change creates a readable event-log entry. - Rejected signatures are shown as expected user actions, not generic crashes. - No secret keys or seed phrases are requested, stored, or displayed. - Diagnostic exports redact sensitive values and clearly mark simulated results. - The test harness distinguishes: - wallet unavailable - user rejection - RPC failure - transaction failure - confirmation timeout - A developer can reproduce each scenario from a documented test case. ## Suggested diagnostic format ```text Session: <local ID> Cluster: <selected cluster> Wallet: <redacted public key> Scenario: <scenario name> Step: <current step> Result: pass | fail | rejected | timeout Error: <wallet/RPC error, if present> Next action: <recommended debugging step> ``` ## Release checklist - [ ] Tested with at least two wallet adapters - [ ] Tested connect and disconnect - [ ] Tested account switching - [ ] Tested rejected connection and rejected signature - [ ] Tested RPC outage or invalid endpoint - [ ] Tested confirmation timeout - [ ] Verified secret material never enters logs - [ ] Verified exported reports contain no private data - [ ] Added a “known limitations” section - [ ] Added a support contact or issue-template location ## Positioning copy **Catch wallet bugs before your users do.** A focused Solana test harness for reproducing connection, signing, RPC, and confirmation failures—with redacted diagnostics your team can actually share.

# Self-Directed Draft: Solana Transaction Intent Preview ## Purpose Help users understand what a wallet signature is expected to do before approval, reducing confusion around unfamiliar transactions. ## Product specification ### User flow 1. User initiates an action in the app. 2. App parses the transaction into a human-readable preview. 3. User reviews: - Network/cluster selected by the app - Programs involved - Accounts read or modified - Token or SOL balance changes, when determinable - Whether the action requires signing or sending 4. User chooses **Continue to wallet** or **Cancel**. 5. After wallet response, the app shows the resulting status and preserves the preview for support reference. ### Safety rules - Never request seed phrases, private keys, or wallet exports. - Clearly label values that are estimated, unknown, or unavailable. - Do not describe an action as harmless merely because parsing succeeded. - Warn when the transaction contains unexpected programs, writable accounts, or balance changes. - Keep the wallet as the final signing authority; the preview must not replace wallet confirmation. ### MVP scope - Parse common SOL and SPL-token transfers. - Show signer, fee payer, writable accounts, and program identifiers. - Display expected balance deltas when available. - Provide a collapsible raw transaction view for advanced users. - Support copyable preview text with sensitive account data minimized or masked. ### Acceptance criteria - A user can cancel before the wallet prompt appears. - The preview distinguishes simulation results from guaranteed outcomes. - Failed parsing produces a clear “Unable to explain fully” state rather than blocking without context. - Account changes and token amounts are formatted consistently. - No private key or seed phrase is collected, logged, or displayed. - Tests cover approval, rejection, parsing failure, account switching, and network mismatch states. ### Suggested preview copy > **Review transaction** > This action may change assets in your connected wallet. Review the accounts, programs, and balance changes below before continuing. If anything looks unexpected, cancel and contact the app’s support team.

# Self-Directed Draft: Solana App Release Checklist **Use before shipping a wallet-facing change.** Assign an owner to each item; mark anything untested as a release risk. - [ ] **Network:** The app clearly identifies its selected cluster. Wallet prompts and app data use the same cluster. - [ ] **Wallet state:** Connect, disconnect, account switch, and rejected-signature flows behave as expected. - [ ] **Transaction preview:** Before a signature request, users can see the intended action, relevant assets, and any amount the app can determine. Unknown details are labeled unknown—not guessed. - [ ] **Failure paths:** Timeouts, unavailable RPC responses, and user rejection produce distinct, actionable messages. - [ ] **Privacy:** Logs and support tools do not request or capture seed phrases or private keys. - [ ] **Recovery:** The team has a named owner and a tested way to disable or roll back the change. **Release decision:** Ship only when every item is checked or an owner has documented the remaining risk and approved it.

# Self-Directed Draft: Solana Support Snapshot ## Purpose Help users report wallet and app issues with enough structured context for support teams to investigate—without requesting seed phrases, private keys, or unnecessary personal data. ## Product specification ### User flow 1. User selects **Help → Copy diagnostic report**. 2. App displays the fields that will be included. 3. User can remove optional fields. 4. App copies a plain-text report and offers a short issue-description box. ### Report fields **Required** - App name and app version - Current environment label configured by the app - Wallet adapter name, if available - Public wallet address, shortened by default - User-selected issue category: - Connection - Signing - Transaction pending - Transaction failed - Balance display - Other **Optional** - Public transaction signature supplied by the user - Recent UI error message - Client timestamp and timezone - Network/RPC label configured by the app - Browser and operating system ### Safety rules - Never collect seed phrases, private keys, wallet exports, or secret input. - Do not automatically transmit the report. - Clearly label every field as “included” or “excluded.” - Mask the wallet address unless the user explicitly expands it. - Treat pasted signatures and addresses as user-provided, unverified data. ## Copy-ready report format ```text Support Snapshot Issue: App: App version: Environment: Wallet: Wallet address: [masked] Network/RPC label: Browser/OS: Client time: Transaction signature: [optional] Error message: What I expected: What happened: ``` ## UI microcopy **Intro:** “Create a support snapshot. This does not request a signature or expose wallet secrets.” **Before copying:** “Review the information below. Nothing will be sent automatically.” **Success:** “Snapshot copied. Paste it into your support request.” **Warning:** “Remove any information you do not want to share before sending.” ## Acceptance criteria - No wallet signature is requested. - No secret material can enter the generated report through automatic collection. - Users can preview and edit the report before copying. - Optional fields are excluded by default. - The component works when wallet connection, RPC access, or transaction history is unavailable.

# Self-Directed Draft: Solana Transaction Outcome Card ## Purpose Give users a clear result after they submit a wallet transaction, without implying success when confirmation is incomplete. ## Product specification A reusable UI component for displaying transaction status and the next safe action. ### Required inputs - Submission state: not submitted, submitted, confirmed, failed, or unknown - App-provided transaction identifier, if available - Network label supplied by the host app - Confirmation timestamp, if available - Optional error category and user-safe explanation - Optional explorer URL supplied by the host app ### Display states **Confirmed** - “Transaction confirmed” - Network label - Short transaction identifier with copy control - “View transaction” action only when a valid URL is supplied - Optional app-specific outcome, such as “NFT listed” or “Settings updated” **Submitted / awaiting confirmation** - “Transaction submitted; confirmation is pending” - Avoid claiming that the requested action completed - Provide “Copy transaction ID” - Provide “Check again” when the host app supports a safe refresh **Failed** - “Transaction failed” - Plain-language reason when known - “Try again” only if retrying is safe - Preserve the transaction identifier for support diagnostics **Unknown** - “We couldn’t verify the outcome” - Explain that the user should avoid immediately repeating an action that could execute twice - Offer refresh or support details, if available ### UX rules - Never label a transaction successful solely because signing completed. - Never expose raw node errors as the primary message. - Keep technical details behind an expandable “Details” section. - Make identifiers copyable and keyboard accessible. - Do not generate or infer explorer links; accept them from the host app. - Use distinct visual treatment for confirmed, pending, failed, and unknown states. ### Acceptance checklist - [ ] Every state has a plain-language heading. - [ ] Pending and unknown states avoid false completion claims. - [ ] Copy controls provide confirmation feedback. - [ ] Missing identifiers do not create broken controls. - [ ] Retry is hidden unless explicitly enabled by the host app. - [ ] Component works on narrow mobile screens. - [ ] Screen readers receive the status update.

# Self-Directed Draft: Solana Transaction Safety Checklist A reusable preflight checklist for teams building transaction flows, helping users understand what will happen before signing. ## Before presenting the sign prompt - [ ] Show the connected network and app environment. - [ ] Display the user’s wallet address in shortened form, with a copy option. - [ ] State the intended action in plain language: “Swap,” “Deposit,” “Mint,” or similar. - [ ] Show assets leaving the wallet, including token symbols and amounts. - [ ] Show assets expected to arrive, when known. - [ ] Separate network fees from the app’s fee. - [ ] Identify any approval, delegate, or permission change. - [ ] Make slippage, expiry, and other user-controlled limits visible. - [ ] Explain whether the transaction is one signature or a sequence. - [ ] Disable signing until required values are loaded and validated. ## During signing - [ ] Keep the action summary visible beside the sign button. - [ ] Use explicit copy: “Sign transaction,” not “Continue.” - [ ] Prevent duplicate submission while a request is pending. - [ ] Provide a cancel path that does not look like an error. - [ ] Never describe a wallet rejection as a failed on-chain transaction. ## After signing - [ ] Distinguish these states: submitted, confirmed, failed, expired, or unknown. - [ ] Show a retry only when the host app determines retrying is safe. - [ ] Preserve the original action details for troubleshooting. - [ ] Provide a transaction identifier only when one exists. - [ ] Avoid claiming success before the app receives the required confirmation. - [ ] Offer a concise next step for each non-success state. ## Copy rules - Prefer: “Your wallet declined the request.” - Prefer: “The transaction was submitted; confirmation is still pending.” - Avoid: “Guaranteed,” “instant,” or “risk-free.” - Avoid hiding fees or permission changes behind expandable sections. - Never ask users to paste seed phrases or private keys. ## Acceptance test A new user should be able to answer, before signing: 1. What am I doing? 2. What leaves my wallet? 3. What might I receive? 4. What fees or permissions apply? 5. What happens if I cancel or the transaction does not confirm?

# Self-Directed Draft: RPC Health Banner **Product specification:** A small status banner that helps a Solana app explain connection problems without blaming a user’s wallet or implying that a transaction failed. **Inputs from the host app:** active network label, RPC request outcomes, time of last successful response, and whether the app can safely offer a retry. The component does not run its own health checks. | State | Banner copy | Action | |---|---|---| | Recent requests failing | “We’re having trouble reaching the network. Your wallet may be fine.” | “Retry connection,” only if the host app enables it | | Responses slow | “Network responses are taking longer than expected.” | “Wait” | | Status unknown | “Connection status is unavailable.” | None | | Recovered | “Connection restored.” | Dismiss | **Rules:** Show the network label so a test environment cannot be mistaken for production. Never say a submitted transaction failed based only on an RPC timeout. Do not display raw endpoint URLs or account identifiers in the banner. **Acceptance checks:** An unknown status never shows “recovered”; a disabled retry never appears clickable; and a timeout after submission directs the user to check transaction status before submitting again.

# Self-Directed Draft: Solana Error Message Design Brief **Product:** A small UI component that turns transaction failures into useful next steps. **Input:** An error category supplied by the host app, optional technical detail, and whether retrying is safe. The component must not infer safety from an unknown error. | Category | User-facing message | Action | |---|---|---| | User rejected | “Transaction not approved. Nothing was submitted by this attempt.” | Return to review | | Insufficient funds | “This account may not have enough SOL to cover the amount and fees.” | Review balance and amount | | Network unavailable | “The network response could not be confirmed.” | Check status before retrying | | Unknown | “We couldn’t determine what happened.” | Show technical detail and support route | **Requirements** - Never show “failed” as proof that a transaction did not land when its status is unknown. - Never retry automatically or ask for a seed phrase. - Keep the original error detail available for support, with a copy button. - Let the host app supply its own support route; display none if absent. **Acceptance test:** For every error category, a user can tell what is known, what remains uncertain, and the safest available next step.