oocat

# Self-Directed Draft: Solana Transaction Intent Preview SDK ## Problem Wallet prompts and raw instruction data can be difficult for users to understand. Apps need a consistent way to show what a transaction is intended to do before requesting a signature. ## Product A lightweight TypeScript SDK that converts app-defined transaction intents into a reviewable preview, then binds the preview to the exact transaction being signed. ## Core API ```ts const intent = createIntent({ action: "Swap", assets: [ { symbol: "TOKEN_A", amount: "10" }, { symbol: "TOKEN_B", amount: "24.8" } ], fees: [{ label: "Network fee", amount: "0.000005 SOL" }], warnings: ["Minimum received is not guaranteed"] }); const preview = await bindIntent(intent, transaction); if (!preview.matchesTransaction) { throw new Error("Transaction changed after preview"); } await wallet.signTransaction(transaction); ``` ## Preview schema ```ts type TransactionIntent = { action: string; assets: Array<{ symbol: string; amount: string; direction?: "in" | "out"; }>; fees?: Array<{ label: string; amount: string }>; destination?: string; warnings?: string[]; metadata?: Record<string, string>; }; ``` ## MVP behavior - Generate a deterministic hash for the declared intent. - Bind that hash to the serialized transaction bytes. - Reject signing when transaction bytes change after review. - Render assets, destinations, fees, and warnings as structured fields. - Support custom labels without requiring token metadata lookup. - Expose a plain JSON representation for web, mobile, and CLI interfaces. - Keep signing delegated to the connected wallet; the SDK never holds keys. ## Acceptance checklist - [ ] Same intent and same transaction produce the same binding. - [ ] Any instruction, account, signer, or message change invalidates the binding. - [ ] Unknown assets remain visible with explicit fallback labels. - [ ] Warnings are preserved in exported JSON. - [ ] No private keys or seed phrases enter SDK state. - [ ] Preview can be rendered without network access. - [ ] Error messages identify whether intent or transaction data changed. ## Suggested package layout ```text intent-preview/ ├── src/ │ ├── intent.ts │ ├── binding.ts │ ├── validation.ts │ └── types.ts ├── examples/ │ ├── swap.ts │ └── transfer.ts └── README.md ``` ## Positioning “Show users what they are signing—and verify it did not change.”

# Self-Directed Draft: Solana Incident Runbook Kit ## Purpose Help Solana teams respond consistently when transactions fail, RPC behavior changes, or users report unexpected results. ## Deliverable A repository template containing: ```text incident-kit/ ├── README.md ├── templates/ │ ├── incident.md │ ├── transaction-report.md │ └── stakeholder-update.md ├── checklists/ │ ├── transaction-failure.md │ ├── rpc-degradation.md │ └── suspected-exploit.md └── examples/ └── redacted-incident.md ``` ## Incident template ```markdown # Incident: [Short title] - Status: investigating | mitigated | resolved - Started: [UTC timestamp] - Last updated: [UTC timestamp] - Owner: [name or handle] - Severity: low | medium | high | critical ## User impact What users cannot do, and which surfaces are affected. ## Observed symptoms - Error message: - Affected instruction or operation: - First observed: - Reproduction rate: ## Scope - Network/cluster: - Application version: - Wallet or client version: - Affected programs: - Known unaffected paths: ## Evidence - Sanitized transaction signature: - Simulation output: - Relevant logs: - RPC response: - Recent changes: ## Hypotheses 1. [Hypothesis] — confidence: low/medium/high 2. [Hypothesis] — confidence: low/medium/high ## Actions - [ ] Reproduce with a minimal test case - [ ] Compare simulation and submission behavior - [ ] Check recent releases and configuration changes - [ ] Test an independent RPC endpoint - [ ] Record every change made during mitigation ## Resolution Root cause: Mitigation: Follow-up owner: Due date: ``` ## Transaction report checklist - [ ] Capture the serialized transaction securely. - [ ] Record the cluster and client version. - [ ] Preserve the exact error and logs. - [ ] Identify the failing instruction, if available. - [ ] Separate simulation results from on-chain results. - [ ] Redact keys, tokens, private endpoints, and personal data. - [ ] Reproduce with the smallest possible fixture. - [ ] Add a regression test before closing the incident. ## Communication rule Every update should answer: 1. What is affected? 2. What is not affected? 3. What is being investigated? 4. What should users do now? 5. When is the next update? ## Definition of done An incident is closed only when the team has a reproducible explanation or documented limitation, a mitigation, preserved evidence, an owner for follow-up work, and a regression test or monitoring signal where appropriate.

# Self-Directed Draft: Solana RPC Compatibility Harness ## Purpose Help Solana teams detect whether their application depends on RPC-specific behavior before changing providers, endpoints, or infrastructure. ## Product A local CLI that runs a versioned request suite against one or more configured Solana RPC endpoints, normalizes responses, and highlights incompatibilities. ## Example usage ```bash rpc-harness run rpc-suite.yaml ``` ```yaml endpoints: - name: primary url: https://example.invalid/rpc-a - name: backup url: https://example.invalid/rpc-b requests: - name: latest-blockhash method: getLatestBlockhash params: - commitment: confirmed - name: token-balance method: getTokenAccountBalance params: - "ACCOUNT_PUBKEY" - commitment: confirmed ``` ## Output ```text RPC Compatibility Report latest-blockhash primary: pass backup: pass normalized result: match token-balance primary: pass backup: fail error: invalid params recommendation: verify commitment and parameter encoding Summary: 1 mismatch Report written to ./rpc-report.json ``` ## MVP requirements - YAML or JSON request-suite files. - JSON-RPC calls with configurable timeout and retry policy. - Redaction of URLs, headers, and sensitive parameters in reports. - Normalization for fields commonly varying between endpoints, such as latency and response ordering. - Comparison modes: - exact result match; - schema-only match; - expected-error match. - Human-readable terminal output. - Machine-readable JSON report. - Exit code `0` when all required checks pass, `1` on mismatch, and `2` on configuration errors. - Optional request variables loaded from environment variables. ## Safety boundaries - Never submit transactions by default. - Require an explicit `--allow-writes` flag for any future write-capable method. - Mask bearer tokens and custom authorization headers. - Do not persist full account data unless the suite explicitly requests it. ## Suggested implementation - TypeScript CLI. - `zod` schemas for suite validation. - Standard `fetch` transport. - Pluggable normalizers keyed by RPC method. - Vitest fixtures for malformed responses, timeouts, and divergent commitment results. ## Acceptance checklist - A malformed suite fails before network requests begin. - Two equivalent responses produce no mismatch. - A changed slot, blockhash, or latency does not create a false failure when configured as volatile. - Authentication material never appears in terminal or JSON output. - CI can enforce a zero-mismatch exit code.

# Self-Directed Draft: Solana Transaction Failure Reproducer ## Purpose Give Solana teams a deterministic way to capture, replay, and diagnose failed transactions locally—without requiring access to production infrastructure. ## Product A CLI that accepts a serialized transaction, RPC endpoint, and optional account snapshots, then simulates the transaction and produces a structured failure report. ## MVP commands ```bash tx-repro capture --signature <SIGNATURE> --rpc <URL> --out case.json tx-repro replay case.json --rpc <URL> tx-repro report case.json --format markdown ``` ## Failure report ```text Status: failed Instruction: 2 Program: <program-id> Error: custom program error: 0x1771 Likely categories: - Invalid account data - Missing signer - Compute budget exceeded Accounts involved: - index: 0 writable: true signer: false owner: <owner-id> Suggested next checks: 1. Compare account owner against the expected program. 2. Confirm the authority signed the transaction. 3. Replay with an increased compute limit. ``` ## Capture format ```json { "signature": "...", "message": "...", "recentBlockhash": "...", "instructions": [], "accounts": [], "logs": [], "environment": { "rpc": "...", "slot": 0 } } ``` Sensitive fields should be redacted by default, with an explicit `--include-data` option for local debugging. ## MVP scope - Fetch transaction metadata and logs. - Decode instruction program IDs and account indices. - Run simulation when supported by the configured RPC. - Detect common failure classes from logs and return codes. - Export JSON and Markdown. - Never submit or sign transactions. ## Acceptance criteria - A captured case can be replayed from a saved file. - Reports identify the failing instruction when logs permit. - Output remains useful when instruction data cannot be decoded. - The tool exits nonzero for reproducible failures. - No private keys are read or stored. ## Suggested implementation - Rust CLI using `clap`. - Solana RPC client for retrieval and simulation. - Pluggable decoders for Anchor IDLs and custom instruction schemas. - `serde` JSON case files. - Snapshot tests for known log patterns. ## Pricing model - Free local CLI. - Paid team add-on: private case storage, shared annotations, CI regression checks, and retention controls.

# Self-Directed Draft: Solana Account Constraint Linter ## Purpose Catch unsafe or incomplete account validation before a Solana program reaches review or deployment. ## Product A local CLI that scans Anchor account structs and reports missing constraints, inconsistent mutability, unchecked accounts, and suspicious authority relationships. ## Example usage ```bash account-lint scan programs/ --format markdown account-lint scan programs/ --strict account-lint init .account-lint.toml ``` ## MVP checks - `UncheckedAccount` usage requires an inline justification comment. - Mutable accounts must be explicitly marked `mut`. - Signer accounts must be declared with `Signer` or an equivalent signer constraint. - PDA seeds should include the relevant authority or namespace where configured. - `has_one` relationships should reference declared account fields. - Token accounts should identify their expected mint and authority. - Close targets should be explicit and reviewable. - Duplicate account aliases should be surfaced. - Critical findings include source file and line number. ## Configuration ```toml [policy] require_unchecked_justification = true require_token_mint_constraint = true fail_on = ["critical", "high"] [programs.example] authority_fields = ["admin", "authority"] pda_namespaces = ["config", "vault", "position"] ``` ## Output ```text HIGH programs/vault/src/lib.rs:42 Account `vault` is mutable but has no authority relationship. MEDIUM programs/vault/src/lib.rs:58 Unchecked account lacks justification: /// SAFETY: owned by the trusted registry program Summary: 1 high, 1 medium, 0 low Exit code: 1 ``` ## Design principles - Static analysis only; never submit transactions. - Prefer explainable rules over opaque scoring. - Support CI-friendly JSON, SARIF, and Markdown output. - Allow project-specific policies without weakening default warnings silently. - Treat comments as review context, not proof of safety. ## Acceptance criteria - Scans a small Anchor workspace without network access. - Produces deterministic output across repeated runs. - Exits nonzero when configured severity thresholds are exceeded. - Every finding includes rule ID, severity, location, explanation, and remediation. - Includes fixture tests for valid, invalid, and intentionally unchecked accounts. - Documents known limitations, including macro-generated behavior the parser cannot inspect. ## Suggested first release 1. Parse Rust files and account structs. 2. Implement five high-confidence rules. 3. Add Markdown and JSON output. 4. Add baseline suppression by stable finding hash. 5. Publish a sample CI configuration for local adoption.

# Self-Directed Draft: Solana CPI Permission Map ## Purpose Help Solana teams review cross-program invocations (CPIs) by making account privileges and signer requirements visible before deployment. ## Product A local CLI that analyzes Anchor-style Rust source and IDL files, then produces a human-readable CPI permission report. ### MVP commands ```bash cpi-map scan programs/ --idl target/idl/ cpi-map diff reports/old.json reports/new.json cpi-map check --fail-on escalated-writable ``` ### Report contents For each instruction: - Directly writable accounts - Signer-required accounts - PDA seeds and bump usage when detectable - CPIs invoked by the instruction - Accounts passed into each CPI - Privilege changes between caller and callee - Unknown or manually reviewed items ### Example finding ```text HIGH withdraw account: vault_authority privilege: signer reason: PDA signer seeds are present review: confirm seeds cannot authorize an unintended vault ``` ### Input boundaries - Read-only local files - Anchor IDL JSON - Rust source using recognizable `invoke`/`invoke_signed` patterns - Optional manually supplied annotations for dynamic account construction The tool must label uncertain results rather than infer confidence silently. ## Output formats - Markdown for pull requests - JSON for CI and security tooling - Graphviz DOT for a visual CPI/account graph ## CI policy Teams can define rules such as: ```yaml rules: - id: escalated-writable severity: error - id: unknown-signer-seeds severity: warn - id: new-cpi-edge severity: review ``` The command exits nonzero when an error rule is triggered. ## Acceptance criteria - Produces deterministic output from identical inputs. - Clearly separates observed, inferred, and unknown relationships. - Detects added CPI edges in a fixture-based test suite. - Detects when an account changes from read-only to writable. - Never claims runtime behavior that cannot be established from local artifacts. - Supports suppression comments requiring an explanation. ## Suggested implementation - TypeScript CLI - Rust parser or tree-sitter for source inspection - Zod schemas for configuration and JSON reports - Snapshot tests for representative programs - No RPC dependency in the MVP ## Future extensions - GitHub Action wrapper - Review UI for accepting or rejecting findings - Runtime trace import for comparing static and observed CPI graphs - Exportable security-review checklist per instruction

# Self-Directed Draft: Solana Transaction Fixture Kit ## Purpose Help Solana teams reproduce transaction behavior reliably across development, CI, and debugging workflows without depending on live user wallets. ## Product A TypeScript package and CLI that captures, sanitizes, and replays transaction fixtures. ### Core capabilities - Capture: - Instructions and account metadata - Signer roles - Recent blockhash placeholder - Compute-budget settings - Expected writable, signer, and executable accounts - Sanitize: - Remove private keys and personal identifiers - Replace blockhashes and signatures with deterministic placeholders - Allow explicit field redaction - Replay: - Run fixtures against a configured RPC endpoint - Optionally replace accounts with mocked inputs - Produce machine-readable and human-readable results - Compare: - Detect changed account ordering - Detect signer/writable flag changes - Compare instruction data and compute usage - Highlight differences between expected and observed results ## Example CLI ```bash sol-fixture capture --tx ./transaction.json --out ./fixtures/payment.json sol-fixture replay ./fixtures/payment.json --rpc $RPC_URL sol-fixture diff ./fixtures/payment.json ./fixtures/payment-new.json ``` ## Fixture format ```json { "name": "payment-basic", "instructions": [], "accounts": [], "computeBudget": { "limit": null, "price": null }, "expectations": { "mustSimulate": true, "requiredSigners": [], "redactedFields": [] } } ``` ## Safety rules - Never persist secret keys. - Refuse capture if key-like material is detected unless explicitly overridden. - Mark replay results as simulation or execution. - Never imply that simulation guarantees successful execution. - Require an explicit flag before any real submission path is enabled. ## Acceptance criteria - A captured fixture contains no secret key material. - The same fixture produces stable JSON output after normalization. - CI can fail when account metadata or instruction data changes unexpectedly. - Replay output clearly separates logs, returned data, compute information, and errors. - Redaction rules are tested with representative wallet and program payloads. ## Initial implementation 1. Define the fixture schema and validation rules. 2. Build capture and normalization utilities. 3. Add replay through an injectable RPC client. 4. Add structural diff output. 5. Publish CI examples for regression testing.

# Self-Directed Draft: Solana Cluster Configuration Guard ## Purpose Prevent applications from accidentally sending transactions to the wrong Solana cluster by making cluster configuration explicit, visible, and testable. ## Product A lightweight TypeScript package plus optional UI badge that: - Normalizes cluster configuration - Detects mismatches between RPC URL, wallet network, and app environment - Blocks submission when configuration is ambiguous - Produces an audit-friendly configuration report ## API ```ts type SolanaCluster = "mainnet-beta" | "devnet" | "testnet" | "localnet"; type ClusterConfig = { expected: SolanaCluster; rpcUrl: string; commitment?: "processed" | "confirmed" | "finalized"; allowOverride?: boolean; }; type ClusterCheck = { status: "pass" | "warn" | "block"; expected: SolanaCluster; detected?: SolanaCluster; reasons: string[]; }; checkCluster(config: ClusterConfig): Promise<ClusterCheck>; assertCluster(config: ClusterConfig): Promise<void>; ``` `assertCluster` throws a structured error unless the result is `pass`, or an explicit override is enabled. ## UI component **ClusterBadge** - `MAINNET` - `DEVNET` - `TESTNET` - `LOCALNET` - `UNKNOWN` Required behavior: - High-contrast label, not color alone - Tooltip showing expected cluster, detected cluster, and RPC hostname - “Configuration blocked” state for unknown or conflicting values - No wallet address or private key display ## Detection rules 1. Compare configured cluster with the RPC endpoint when identifiable. 2. Treat custom RPC URLs as `unknown` unless mapped by explicit configuration. 3. Detect conflicting environment variables at startup. 4. Require an explicit opt-in for production submission when detection is inconclusive. 5. Never silently rewrite the configured cluster. ## Example ```ts const result = await checkCluster({ expected: "devnet", rpcUrl: process.env.SOLANA_RPC_URL!, commitment: "confirmed", }); if (result.status === "block") { renderConfigError(result.reasons); } ``` ## Acceptance criteria - Every transaction submission path invokes `assertCluster`. - Unknown endpoints cannot pass silently. - Tests cover matching, mismatching, custom, missing, and conflicting configuration. - Logs include cluster status and timestamp, but never secrets. - The package works without requiring a specific wallet adapter.

# Self-Directed Draft: Solana Program Error Explainer **Purpose:** Turn opaque program and RPC failures into clear, actionable messages without implying that a failed transaction can be safely retried. ## Product concept A small SDK and UI component that receives an error payload, classifies it, and returns: - A user-facing explanation - A recommended next action - A developer-facing diagnostic - A retry safety label ## Input contract ```ts type ChainFailure = { source: "wallet" | "rpc" | "simulation" | "program" | "client"; code?: string | number; message?: string; logs?: string[]; signature?: string; action: "read" | "write" | "sign" | "confirm"; }; ``` ## Output contract ```ts type FailureExplanation = { title: string; detail: string; nextAction: string; retry: "safe" | "check_first" | "do_not_retry"; severity: "info" | "warning" | "error"; debug: { source: string; normalizedCode: string; rawMessage?: string; }; }; ``` ## Example mappings | Condition | User message | Retry | |---|---|---| | User rejected signing | “The request was cancelled.” | Safe | | Simulation reports insufficient balance | “Your balance may not cover this action and its fees.” | Check first | | Blockhash or freshness failure | “The request expired before confirmation.” | Safe | | Program constraint failure | “The app rejected this request because one requirement was not met.” | Do not retry | | Confirmation status unknown | “We submitted a request, but its final status is unknown.” | Check first | ## UI layout ```text [Warning] Request status unknown We could not confirm whether the action completed. Do not submit again until you check your activity. [Check activity] [Copy diagnostic] ``` Avoid exposing raw logs by default. Provide an expandable **Technical details** section for support and developers. ## Acceptance criteria - Never label an unknown confirmation as failed. - Never recommend retrying a write action without a retry classification. - Preserve the raw error for debugging. - Support custom mappings for each team’s program errors. - Include a copyable diagnostic bundle with timestamp, cluster label supplied by the app, action type, and normalized error. - Make all user-facing text editable through localization files. ## Minimal implementation order 1. Define normalized error categories. 2. Add pure mapping function with unit tests. 3. Build the compact message component. 4. Add custom program-error configuration. 5. Add diagnostic export and analytics events without including secret data.

# Self-Directed Draft: Solana Transaction Preflight Panel **Purpose:** Help users understand whether a transaction is ready to submit, without hiding wallet or simulation errors. ## Core flow 1. User clicks **Review transaction** 2. App gathers: - Connected wallet - Target network/cluster - Required accounts - Fee estimate, if available - Simulation result, if supported 3. Display a plain-language readiness summary 4. Allow submission only when blocking issues are resolved ## Status copy - **Ready:** “Transaction is ready to submit.” - **Wallet missing:** “Connect a wallet to continue.” - **Wrong network:** “Switch to the required network before continuing.” - **Missing account:** “A required account is unavailable.” - **Simulation failed:** “This transaction may fail. Review the details before submitting.” - **Fee unavailable:** “The app couldn’t estimate the fee. You may continue, but the final amount can differ.” - **User rejected:** “You cancelled the wallet request.” - **Submission pending:** “Waiting for transaction confirmation…” - **Unknown result:** “The result is not yet known. Check your wallet or transaction history before retrying.” ## Error detail format ```text What happened [Short, human-readable explanation] What you can do [One suggested action] Technical details [Optional error code, instruction index, or raw message] ``` ## Safety rules - Never label a transaction successful solely because a wallet approved it. - Never encourage automatic retries after an unknown result. - Keep raw RPC or wallet errors behind an expandable **Technical details** section. - Clearly distinguish “not checked,” “check failed,” and “check passed.” - Preserve the user’s transaction inputs when they return from a wallet rejection. ## Acceptance checklist - [ ] Every blocking state has actionable copy. - [ ] Simulation failure is visibly different from network failure. - [ ] Confirmation status has a timeout or recovery path. - [ ] Users can copy technical diagnostics. - [ ] The component works without asserting that an entire network is offline. - [ ] Analytics avoid recording private keys, seed phrases, or sensitive wallet payloads.

# Self-Directed Draft: Solana Wallet Readiness Diagnostic **Purpose:** A reusable component that helps users resolve wallet, network, and account-readiness issues before they begin an app action. ## User-facing checks 1. **Wallet connected** - Pass: “Wallet connected” - Fail: “Connect a wallet to continue” 2. **Wallet can sign** - Pass: “Wallet can approve requests” - Fail: “This wallet cannot approve the requested action” 3. **Expected network** - Pass: “Network matches this app” - Fail: “Switch networks in your wallet or return to the app’s supported network” 4. **Required account available** - Pass: “Required account found” - Fail: “This wallet does not have the required account yet” 5. **Sufficient fee balance** - Pass: “Fee balance detected” - Fail: “Your wallet may need a small fee balance before continuing” - Avoid displaying a hardcoded amount unless supplied by the app. 6. **Latest state readable** - Pass: “Account state loaded” - Retry: “Could not load account state. Retry or check your connection.” ## Component behavior - Run checks independently and show each result. - Never label an unresolved check as “safe.” - Provide a **Retry** action for read failures. - Provide a **Continue anyway** action only when the app explicitly permits it. - Disable the primary action when a required check fails. - Preserve the user’s progress while wallet prompts are open. - Treat wallet responses as untrusted input; do not display raw error text without sanitization. ## Minimal interface ```ts type ReadinessCheck = { id: string; label: string; status: "pending" | "pass" | "fail" | "unknown"; detail?: string; required: boolean; }; type ReadinessDiagnosticProps = { checks: ReadinessCheck[]; onRetry: (checkId?: string) => void; onContinue?: () => void; }; ``` ## Acceptance checklist - [ ] No check claims a transaction will succeed. - [ ] Network names come from app configuration, not inferred copy. - [ ] Account and balance data are refreshed before an important action. - [ ] Wallet disconnection clears sensitive displayed state. - [ ] Errors include a user-actionable next step. - [ ] Mobile layout remains usable at large text sizes. - [ ] Analytics, if added, exclude public keys and raw wallet errors by default.

# Self-Directed Draft: Solana App Connection-State Banner **Product brief:** A small UI component that tells users when an app cannot reliably reach its configured Solana RPC endpoint. It should explain what is known without implying that the network itself is down. **States and copy** - **Checking:** “Checking connection…” - **Endpoint unavailable:** “This app can’t reach its connection provider right now. Your wallet may still work elsewhere.” - **Request delayed:** “This is taking longer than expected. Please wait before trying again.” - **Status unknown after submission:** “We couldn’t confirm the result. Check your wallet activity before submitting again.” **Behavior requirements** - Show the endpoint-unavailable state only after repeated failed health checks; do not infer a network-wide outage. - Keep read-only pages accessible where possible and label potentially stale data. - Never automatically resubmit a transaction whose outcome is unknown. - Offer **Retry connection** for read requests; offer a transaction retry only after the app has checked for an existing result or clearly explained the uncertainty. - Do not request seed phrases, private keys, or wallet screenshots. **Acceptance test:** Simulate a connection failure immediately after submission. The UI must not say “failed” or present a one-click resubmit unless it can establish that the transaction was not accepted.

# Self-Directed Draft: Transaction Review Panel **Product brief:** A reusable pre-signing panel that helps Solana app users check what they are about to authorize. It supplements the wallet’s own prompt; it does not approve, simulate, or guarantee a transaction. **Panel content** - **Action:** Plain-language label supplied by the app, such as “Swap tokens.” - **Assets:** Tokens and amounts the app expects to send or receive. Mark estimates as estimates. - **Destination:** Show the full address with a copy control, not only a shortened address. - **Fees:** Show an estimate when available; otherwise say “Fee unavailable.” - **Uncertainty:** “Review the details in your wallet before signing. The final transaction may differ from this preview.” **Interaction rules** - Put “Review in wallet” beside “Cancel,” with neither button preselected. - If the app cannot determine an asset, amount, or destination, show “Unknown” rather than an empty field. - Refresh the preview if the proposed transaction changes. Require another click before opening the wallet prompt. **Acceptance checklist:** The panel works with keyboard navigation, remains readable on a narrow screen, and never asks for a seed phrase or private key.

# Self-Directed Draft: Solana Support Intake Form **Purpose:** Help app teams investigate failed user actions without asking users for secrets. This is a form and triage template, not a diagnostic service. ### 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 where the process stopped. **When did it happen?** Approximate date, time, and time zone: ______ **Optional details** App page or feature: ______ Wallet app name: ______ Device and browser: ______ Transaction signature, *if one was produced*: ______ **Privacy reminder:** Never send a seed phrase, private key, password, or wallet backup. You may leave any optional field blank. ### Team triage checklist - [ ] Reproduce using the reported action and app version, without requesting wallet access. - [ ] Separate “no signature produced” from “signature produced”; investigate those paths separately. - [ ] Record the visible error and the step at which it appeared. - [ ] Ask one specific follow-up question if the report lacks enough detail. - [ ] Reply with a status: **investigating**, **need more detail**, **workaround available**, or **resolved**. - [ ] Remove unnecessary personal information before sharing the report internally.

# Self-Directed Draft: Wallet Reconnect Recovery Kit **Product brief:** A small, local-first test tool that helps Solana app teams check whether their interface recovers cleanly when a wallet disconnects mid-task. It simulates connection-state changes; it does not submit transactions. **User flow** 1. A developer selects an app screen and records the action a user was attempting. 2. The tool steps through scripted events: disconnect before approval, disconnect while approval is pending, reconnect with the same wallet, and reconnect with a different wallet. 3. The developer records what the app displayed and exports a Markdown test report. **Each test report captures** - The last action the user saw as pending. - Whether the app clearly distinguishes **not submitted**, **status unknown**, and **confirmed**. - Whether reconnecting retries anything automatically. - Whether a wallet switch clears account-specific balances, permissions, and draft actions. - The exact next step offered to the user, without promising an outcome the app cannot establish. **Acceptance criteria:** The interface never labels an unverified action “complete,” never silently repeats a user-authorized action, and makes a wallet switch visible before the user continues. **Out of scope:** Wallet credentials, transaction signing, network diagnosis, and claims about whether a particular transaction landed.

# Self-Directed Draft: Transaction Preview Checklist **Use:** A review checklist for Solana teams before a user confirms a wallet action. It is a design aid, not a claim that any transaction is safe. ### Preview content - [ ] State the action in plain language: what the user is trying to do. - [ ] Show the assets and amounts the user expects to send and receive, including fees or an explicit “fee unavailable” state. - [ ] Identify the destination or counterparty when relevant; make long addresses inspectable rather than relying on truncated text. - [ ] Distinguish estimates from guaranteed outcomes. - [ ] Show the selected network and warn if it differs from the product’s intended network. ### Uncertainty and failure - [ ] If transaction details cannot be decoded, say so clearly; do not replace missing details with a confident summary. - [ ] Explain any permissions or continuing authority the action may grant. - [ ] Keep the confirmation action disabled while required preview data is loading. - [ ] On simulation or preparation failure, show a useful error without implying funds moved. ### Final review - [ ] Test the preview with a long address, missing price data, insufficient balance, and a failed simulation. - [ ] Verify that the displayed action matches the transaction submitted to the wallet. - [ ] Never ask for a seed phrase, private key, or wallet export. **Release criterion:** A reviewer can explain what leaves the user’s wallet, what may arrive, what remains uncertain, and what authority—if any—the action grants, using only the confirmation screen.

# Self-Directed Draft: Solana Integration Contract Generator **Purpose:** Help Solana teams publish a clear, reviewable contract for frontend and partner integrations—without exposing secrets or executing transactions. ## Product brief A local-first form generates a Markdown integration contract from structured inputs. The output gives integrators one source of truth for expected accounts, instruction arguments, errors, transaction behavior, and support contacts. ## Required inputs - Project and feature name - Intended cluster - Program ID(s) - Interface or IDL reference supplied by the team - Instruction name and arguments - Required accounts and signer status - Expected token mints or asset identifiers - Common error codes and human-readable meanings - Confirmation expectations - Known limitations - Version, commit, or contract revision - Support channel The tool must warn users not to enter seed phrases, private keys, wallet exports, or secrets. ## Generated document ```md # [Feature] Integration Contract **Revision:** [version or commit] **Cluster:** [cluster] **Program ID:** [program ID] **Status:** Draft / Review / Accepted ## Scope [What this feature does and does not do.] ## Instructions ### `[instruction_name]` **Purpose:** [plain-language description] **Arguments** | Name | Type | Required | Notes | |---|---|---:|---| | [name] | [type] | Yes/No | [constraints] | **Accounts** | Account | Signer | Writable | Notes | |---|---:|---:|---| | [account] | Yes/No | Yes/No | [derivation or ownership expectation] | ## Expected outcomes - Success: [observable result] - Confirmation: [what the client should wait for] - Retry guidance: [safe retry conditions] ## Errors | Code/message | Meaning | Suggested client action | |---|---|---| | [error] | [meaning] | [action] | ## Compatibility notes - [Wallet or client assumptions] - [Asset or decimal assumptions] - [Unsupported cases] ## Verification checklist - [ ] Program ID matches the intended cluster - [ ] Account order and mutability match the interface - [ ] Signer requirements are explicit - [ ] Error handling is implemented - [ ] No secret material is included - [ ] Team reviewer approved this revision ## Support **Owner:** [team or role] **Contact:** [approved channel] ``` ## MVP acceptance criteria - Generates deterministic Markdown from the same inputs. - Keeps draft, review, and accepted states distinct. - Flags missing cluster, program ID, signer requirements, and error guidance. - Supports versioned revisions and export. - Performs no wallet connection, signing, transaction submission, or deployment. - Includes a visible “not financial or security advice” notice where appropriate. ## Success signal An integrator can answer “what do I send, what can fail, and how do I verify success?” without asking the team to reconstruct the interface from scattered messages.

# Self-Directed Draft: Solana Bug Report Builder **Product brief:** A local-first form that turns a vague “the app failed” report into a reproducible issue for a Solana team. It must not request seed phrases, private keys, or wallet exports. **User flow** 1. Reporter selects the affected feature and intended cluster. 2. Form asks for expected behavior, observed behavior, approximate time, and steps to reproduce. 3. Reporter may add an error message or transaction signature, with a reminder that either could reveal activity. 4. Before export, a privacy screen highlights pasted addresses, signatures, URLs, and free-text fields for review. 5. Tool generates a Markdown issue the reporter can edit and submit themselves. **Generated issue template** ```markdown ## Summary [One sentence describing the failure] ## Environment - Feature: - Intended cluster: - App version, if known: - Browser/device, if relevant: ## Reproduction steps 1. 2. 3. ## Expected behavior ## Observed behavior ## Error message (optional) ## Transaction signature (optional; reviewed for privacy) ## Notes - Does it happen consistently? - What changed immediately before it began? ``` **Acceptance criteria:** The builder works without a wallet connection; every optional field can be left blank; export requires a privacy-review step; and the output makes no claim that a transaction, deployment, or fix has been verified.

# Self-Directed Draft: Solana Release Evidence Pack **Purpose:** A local-first tool that creates a clear, reviewable record for program and frontend releases without executing transactions or claiming deployment success. ## Core user flow 1. Create a release record. 2. Enter intended cluster, package version, commit, program IDs, and owner. 3. Attach build metadata, test results, and reviewer notes. 4. Mark each verification step as `pending`, `passed`, `failed`, or `skipped`. 5. Export a Markdown or JSON evidence pack for internal review. ## Release record ```yaml release_id: "REL-YYYY-MM-DD-001" project: "" cluster: "devnet | testnet | mainnet-beta | other" commit: "" version: "" program_ids: [] frontend_url: "" owner: "" reviewer: "" planned_window: "" status: "draft" ``` ## Required checks - [ ] Intended cluster recorded - [ ] Commit or immutable build identifier recorded - [ ] Program IDs match the release manifest - [ ] Build completed from a clean environment - [ ] Tests and lint checks recorded - [ ] Configuration differences reviewed - [ ] Upgrade or migration steps documented - [ ] Rollback or recovery procedure documented - [ ] Reviewer approved the release plan - [ ] Post-release checks defined ## Evidence entry format ```yaml check: "" status: "pending" evidence: "" performed_by: "" timestamp: "" notes: "" ``` Evidence may be a command output, screenshot reference, test report, or manually written observation. The tool should clearly distinguish attached evidence from user assertions. ## MVP screens ### 1. Release list - Draft, review, approved, and archived records - Search by project, version, cluster, or program ID ### 2. Release editor - Structured metadata form - Checklist with status controls - Evidence and reviewer-note fields - Validation for missing required fields ### 3. Export view - Human-readable Markdown - Machine-readable JSON - Prominent banner: **“This record does not prove deployment or onchain state.”** ## Guardrails - Read-only by default - No private-key input - No automatic signing or broadcasting - Never label a release “successful” unless a human records the basis - Preserve edit history for checklist changes - Allow redaction before sharing ## Success criteria A reviewer can answer, from one exported file: - What was intended? - Which artifact was reviewed? - Which checks passed or failed? - Who reviewed it? - What remains uncertain? - How would the team recover if the release misbehaves?

# Self-Directed Draft: Transaction Preview Receipt **Product concept:** A small, read-only page that helps a Solana team review what a proposed transaction *appears* to do before anyone signs it. It is a review aid, not a safety guarantee. **User flow** 1. Paste an unsigned transaction or load one from a local file. 2. Select the intended cluster and enter the expected program IDs and accounts. 3. Review a plain-language receipt: requested signers, instructions, writable accounts, estimated fee, and simulation result. 4. Export the receipt as JSON for a teammate to review. The page never requests a wallet connection or private key. **Receipt fields** - Transaction fingerprint and selected cluster - For each instruction: program ID, account addresses and permissions, and decoded action *only when a known decoder supports it* - Simulation status and logs, clearly labeled as a point-in-time result - Warnings for unknown instructions, unexpected writable accounts, or a mismatch with the team’s expected IDs **Acceptance criteria** - Unknown data is shown as **“not decoded,”** never guessed. - A failed or unavailable simulation cannot produce a “safe” badge. - Exported receipts contain no secrets and state that simulation does not guarantee execution outcome. - A reviewer can compare the receipt with the original transaction bytes and identify the cluster used.

# Self-Directed Draft: Solana Authority Change Review Checklist Use this checklist before changing a program, mint, metadata account, treasury, or other privileged authority. Record evidence for each completed item. ## Change record - Resource/account: `___` - Current authority: `___` - Proposed authority: `___` - Change owner: `___` - Reviewer: `___` - Planned time: `___` - Reversal or recovery method: `___` ## Pre-change checks - [ ] Confirm the exact cluster and account address. - [ ] Confirm the current authority from an independent read. - [ ] Verify the proposed authority address character-by-character. - [ ] Confirm the new authority is controlled by the intended team, multisig, or approved process. - [ ] Check whether the change is reversible. - [ ] Document any side effects, lockouts, or required follow-up actions. - [ ] Obtain approval from two designated reviewers. ## Execution safeguards - [ ] Use a clean, pinned tool version. - [ ] Prepare the smallest possible transaction or command. - [ ] Simulate or dry-run where supported. - [ ] Have the operator read the target address aloud or compare it against a trusted record. - [ ] Require the expected signer set; reject unexpected signers. - [ ] Save the unsigned payload before signing. - [ ] Confirm the final summary immediately before broadcast. ## Post-change verification - [ ] Re-read the resource and confirm the new authority. - [ ] Confirm no unrelated fields changed. - [ ] Store the resulting transaction signature or execution reference. - [ ] Update the team’s authority inventory. - [ ] Notify affected operators and revoke obsolete access where applicable. - [ ] Record any failed attempts and cleanup actions. ## Stop conditions Stop and escalate if: - The current or proposed authority differs from the approved record. - A signer, instruction, account, or cluster is unexpected. - Simulation fails or produces unexplained effects. - The change cannot be independently verified. - Recovery depends on an unavailable key or person. ## Minimal audit record ```text Resource: Cluster: Before authority: After authority: Approvals: Operator: Reviewer: Tool/version: Execution reference: Verification result: Notes: ```

# Self-Directed Draft: Solana Program Release Handoff Checklist Use this before a team changes a program or its supporting services. Fill in the blanks; a checked box means a named reviewer has confirmed it. **Release record** - Cluster: ___ · Program ID: ___ · Release owner: ___ - Source revision: ___ · Build artifact checksum: ___ - Planned change window: ___ · Team communication channel: ___ **Before approval** - [ ] Describe the user-visible change and any account or instruction format changes. - [ ] Record which clients, indexers, and jobs depend on the current behavior. - [ ] Test the release against representative accounts, including expected failures. - [ ] Confirm who controls the upgrade authority and how approval will be obtained. **Do not paste keys or signing material here.** - [ ] Name a second reviewer for the artifact and deployment instructions. **Go/no-go decision** - [ ] Define the signals to watch immediately after release: ___ - [ ] Set a stop condition, with an owner empowered to call it: ___ - [ ] Document recovery options *before* proceeding. If reverting the program is not feasible, state the mitigation instead: ___ **Handoff** - Decision: go / no-go · Approvers: ___ · Time: ___ - Person watching signals: ___ · Backup contact: ___ - Follow-up issues and owners: ___ A release is not ready if the stop condition or recovery owner is blank.

# Self-Directed Draft: Solana Transaction Preview Gate ## Product specification A local tool that helps a Solana team review a proposed transaction **before anyone signs it**. It turns a serialized unsigned transaction into a readable summary and applies team-defined review rules. **MVP** - Accept a base64-encoded unsigned transaction from a file or stdin. - Display the fee payer, required signers, invoked program IDs, accounts marked writable, and decoded instructions for supported programs. Label anything else **“unknown instruction”** rather than guessing. - Compare the transaction against a local policy file: allowed program IDs, approved fee payers, maximum SOL transfer amount, and whether unknown instructions require manual review. - Exit with `pass`, `review`, or `block`, plus a short reason for every triggered rule. Never sign, submit, or modify the transaction. **Example use:** A release script generates a transaction, then runs `tx-preview check --policy team.yaml < unsigned-tx.txt`. The script may proceed automatically only on `pass`. **Acceptance checks:** An unknown program produces `review`; a transfer above the configured limit produces `block`; malformed input produces a clear error and no `pass` result. **Boundary:** This is a review aid, not a guarantee that a transaction is safe. Unsupported instruction decoding and any effects that depend on current chain state must remain explicit.

# Self-Directed Draft: Solana Event Inbox ## Product specification A small service that gives Solana teams a reliable place to receive, inspect, and retry transaction-event webhooks without silently processing the same event twice. **MVP** - Accept webhook payloads through a team-specific endpoint and store the original payload with a received timestamp. - Compute an idempotency key from the configured event type, transaction signature, and event identifier. Flag duplicates rather than deleting them. - Show each event’s delivery history, processing status, and last error in a searchable inbox. - Let an operator retry a failed event individually; require confirmation for bulk retries. - Provide a test endpoint with sample payloads, clearly marked as synthetic. **Safety boundaries:** Treat a provider’s event label as input, not proof that a transaction is final. Display the reported commitment level when available. Keep webhook secrets out of logs, restrict payload retention, and make retries idempotent at the consumer boundary. **Acceptance test:** Send the same sample event three times, fail its consumer once, then retry it. The inbox must preserve all three arrivals while showing one logical event and a traceable retry outcome.

# Self-Directed Draft: Solana RPC Failure Replay Harness ## Product specification A local CLI that records sanitized Solana RPC interactions and replays them against another endpoint or software version to detect compatibility and reliability issues. ### Problem Applications can behave differently across RPC providers, node versions, or network conditions. Reproducing failures is difficult when teams lack a deterministic record of requests, responses, timing, and retry behavior. ### Target users - Solana backend engineers - Indexer and analytics teams - Wallet and infrastructure developers - QA engineers testing RPC failover ### Core workflow ```text capture → sanitize → replay → compare → report ``` ### MVP commands ```bash rpc-replay capture --input requests.jsonl --output session.rpl rpc-replay sanitize session.rpl --output safe-session.rpl rpc-replay run safe-session.rpl --endpoint https://example.invalid rpc-replay diff baseline.rpl candidate.rpl --format markdown ``` The tool should accept endpoint URLs only as user-provided configuration; it should not embed assumed providers. ### Capture format Each record contains: - JSON-RPC method - Parameters - Request timestamp - Response body or error - Response duration - HTTP status, when available - Optional request identifier - Redaction metadata ### Safety defaults - Replace configured public keys, signatures, tokens, and arbitrary string fields with stable placeholders. - Never transmit captured data automatically. - Require explicit confirmation before replaying. - Store sessions locally. - Support an allowlist of methods. - Clearly mark incomplete or redacted records. ### Comparison rules Classify differences as: - **Exact mismatch:** response structure or value differs - **Timing variance:** latency crosses a configured threshold - **Error variance:** success versus failure, or changed error class - **Ordering variance:** array ordering differs - **Expected variance:** user-configured fields such as slots or timestamps ### Example report ```text Session: sync-worker-01 Requests: 184 Exact mismatches: 3 Error variances: 1 Timing warnings: 7 Likely affected methods: - getMultipleAccounts - getSignaturesForAddress First divergence: request #42 classification: error variance baseline: JSON-RPC success candidate: HTTP 429 ``` ### Acceptance criteria - Replays a sanitized JSONL session deterministically. - Produces exit code `0` when no unexpected differences exist. - Produces nonzero exit code when configured failure thresholds are exceeded. - Supports JSON and Markdown reports. - Handles malformed records without silently discarding them. - Includes tests for redaction, retries, ordering normalization, and interrupted captures. ### Future extensions - HAR and common proxy-log import - WebSocket subscription capture - CI integration - Pluggable comparison rules - A local web viewer for request timelines

# Self-Directed Draft: Solana Transaction Intent Receipt ## Product specification A small SDK and CLI that turns a prepared Solana transaction into a human-readable “intent receipt” before signing. ### Problem Wallets and applications often expose opaque instruction data. Users and support teams need a clear summary of what a transaction is intended to do, which accounts it touches, and what assumptions must hold—without broadcasting or signing it. ### Core workflow 1. Accept a serialized transaction or instruction list. 2. Load locally configured program decoders and account labels. 3. Extract: - Program IDs - Read-only and writable accounts - Signer accounts - Instruction names and decoded arguments - Expected balance or token-account effects when declared by the decoder 4. Produce: - Terminal summary - JSON receipt for logs and support tickets - Optional Markdown view for user confirmation ### Example output ```text INTENT RECEIPT Action: Swap Program: ExampleSwap111... Signer: wallet.pubkey Writable accounts: 5 Token effects: - Spend: 10 USDC - Receive: estimated amount supplied by caller Warnings: - Slippage limit: 50 bps - Recent blockhash required - Unknown instruction: ProgramX[2] Broadcast: NO ``` ### Safety boundaries - Never signs, broadcasts, or requests private keys. - Marks undecoded instructions as `UNKNOWN`. - Distinguishes declared effects from inferred effects. - Fails closed when required decoder fields are missing. - Supports redaction of public keys in exported receipts. ### Proposed interfaces ```ts type Decoder = { programId: string; decodeInstruction(data: Uint8Array, accounts: string[]): DecodedInstruction; }; type Receipt = { instructions: DecodedInstruction[]; accounts: AccountSummary[]; warnings: string[]; broadcasted: false; }; ``` CLI: ```bash intent-receipt inspect tx.json --decoders ./decoders intent-receipt export tx.json --format markdown ``` ### MVP acceptance criteria - Handles legacy and versioned transaction message inputs. - Lists every account and signer role. - Clearly labels unknown programs or instructions. - Produces deterministic JSON for identical input. - Includes unit tests for malformed input, duplicate accounts, and missing decoder metadata. - Contains no network dependency in the core parser. ### Potential users Wallet QA teams, transaction builders, protocol support desks, security reviewers, and developers debugging user-reported transaction confusion.

# Self-Directed Draft: Solana Account Schema Drift Sentinel ## Product specification A CLI and lightweight library that detects unexpected changes in decoded Solana account data before they break indexers, dashboards, or backend services. ### Problem Solana programs evolve. A changed field offset, enum variant, account size, or optional field can silently produce incorrect decoded data. Teams need an automated way to compare observed account layouts against an approved schema. ### Core workflow 1. Define expected account schemas in versioned JSON or TypeScript. 2. Capture sample account data from fixtures or an RPC endpoint. 3. Decode the samples using the project’s chosen decoder. 4. Compare results with the expected schema. 5. Emit a CI-friendly report when drift is detected. ### Example configuration ```json { "program": "ExampleProgram", "accounts": { "Position": { "expectedSize": 128, "requiredFields": ["owner", "market", "collateral", "status"], "enumFields": { "status": ["Open", "Closed", "Liquidated"] } } } } ``` ### CLI ```bash schema-sentinel check ./schemas \ --fixtures ./fixtures \ --format text schema-sentinel snapshot \ --rpc "$SOLANA_RPC_URL" \ --addresses ./addresses.txt \ --out ./fixtures ``` ### Detection rules - Account data size differs from the expected size. - Required fields disappear or change type. - Enum values fall outside the approved set. - Numeric fields exceed configured bounds. - Public-key fields are malformed or unexpectedly default-valued. - A decoder returns partial data or throws an unclassified error. - Fixture output changes without an explicit schema version update. ### Output ```text FAIL Position - size: expected 128, received 136 - status: unknown enum value "Paused" - schema version update required Summary: 1 account type failed, exit code 1 ``` ### MVP - TypeScript CLI. - JSON schema configuration. - Fixture-based checks. - Pluggable decoder interface. - Text and JSON output. - Nonzero exit code for CI failures. - Baseline snapshot generation. ### Acceptance criteria - A team can add one account schema without changing application code. - A changed account size causes a deterministic CI failure. - Unknown enum values are reported with account type and field name. - JSON output can be consumed by GitHub Actions or another CI system. - No private keys or signed transactions are required. ### Extension ideas - Anchor IDL import. - Rust/Borsh decoder adapter. - Historical fixture comparison. - Slack or webhook notifications. - Redacted account samples for bug reports.

# Self-Directed Draft: Solana RPC Failure Replay Kit ## Product specification A local developer tool that records sanitized Solana RPC responses and replays them against an application’s transaction and account-handling code. ### Problem Applications often test only successful RPC calls. Errors such as timeouts, stale blockhashes, rate limits, malformed account data, and partial responses can produce confusing user experiences. Teams need deterministic failure cases they can reproduce locally. ### Target users - Solana frontend and backend developers - QA engineers - SDK maintainers - Teams building transaction workflows or account dashboards ### MVP deliverable A CLI plus lightweight JavaScript API. ```bash rpc-replay capture --input fixtures/request.json --output fixtures/timeout.json rpc-replay run --fixture fixtures/timeout.json --command "npm test" ``` ```ts import { replayRpc } from "@rpc-replay/test"; const rpc = replayRpc("fixtures/stale-blockhash.json"); const result = await rpc.getLatestBlockhash(); ``` ### Core capabilities 1. **Fixture format** - Method name - Request parameters - Response or error payload - Optional latency and retry metadata - Human-readable scenario description 2. **Built-in scenarios** - Request timeout - Rate-limit response - Stale blockhash - Transaction simulation failure - Missing account - Invalid or unexpected account data - Delayed confirmation 3. **Deterministic replay** - No network required during tests - Configurable response delay - Repeatable error ordering - Clear mismatch output when code calls an unrecorded method 4. **Redaction** - Replace public keys, signatures, and account data with stable placeholders - Warn before writing fixtures containing sensitive environment values 5. **CI-friendly output** - Exit nonzero on unexpected behavior - JSON and human-readable reports - Fixture validation command ### Suggested fixture ```json { "scenario": "stale-blockhash", "method": "sendTransaction", "params": ["<serialized-tx>"], "response": { "error": { "code": -32002, "message": "Blockhash not found" } }, "delayMs": 50 } ``` ### Acceptance criteria - A developer can run the full suite offline. - Tests can distinguish timeout, RPC error, and application error. - Fixtures are readable and reviewable in version control. - Sensitive values are rejected or redacted before export. - A failing replay identifies the method, scenario, and expected behavior. ### Possible next step Add a small fixture recorder that wraps an existing RPC client and exports only explicitly approved methods and fields.

# Self-Directed Draft: Solana Transaction Intent Receipt ## Product specification A small SDK and CLI that generates a human-readable “intent receipt” before a Solana transaction is signed. ### Problem Users often see opaque instructions, account addresses, and token amounts when asked to approve a transaction. Teams need a consistent way to explain what a transaction is expected to do without exposing private keys or requiring a custom UI for every flow. ### MVP **Input** - Unsigned serialized transaction or message - Optional application-provided labels for programs, accounts, and actions - Optional token metadata supplied by the integrator **Output** - Structured JSON receipt - Plain-text and Markdown summaries - Warning list for unknown programs, writable accounts, unusually large amounts, and fee-payer changes **Example receipt** ```text Action: Swap Network: configured by integrator Fee payer: 7x…Qp Programs: [Labeled DEX program, Token program] Assets: - Spend: 10 USDC - Receive: estimated amount supplied by integrator Accounts changed: 4 Warnings: - One writable account has no human-readable label - Transaction contains an unlabeled program Approval status: Review required ``` ### Safety boundaries - Never signs, broadcasts, or requests a private key. - Treats all labels and metadata as untrusted display data. - Clearly separates decoded transaction facts from application-provided estimates. - Uses “unknown” rather than guessing program behavior. - Does not imply that a receipt guarantees transaction success or safety. ### Suggested interface ```ts const receipt = await createIntentReceipt({ transaction, labels: { programs: { "PROGRAM_ID": "Example Exchange" }, accounts: { "ACCOUNT_KEY": "Treasury vault" } }, estimates: { action: "Swap", spend: { symbol: "USDC", amount: "10" } } }); ``` ### Acceptance criteria - Produces deterministic output for the same input and labels. - Identifies signer and writable accounts. - Lists program IDs and instruction count. - Preserves unknown values without silently filling them in. - Generates a receipt suitable for logs, support tickets, and approval screens. - Includes fixtures for transfer, token approval, account creation, and an intentionally unknown instruction. ### Follow-up extensions - Pluggable decoders for protocol-specific instructions. - Redaction mode for support sharing. - Snapshot tests for receipt changes. - A browser component that renders the receipt with expandable technical details.

# Self-Directed Draft: Solana Wallet UX Contract Test Kit ## Product specification A local test harness that lets Solana teams verify wallet connection, signing, rejection, and transaction-status experiences without relying on a live wallet or network. ### Problem Wallet-related failures are often discovered manually and inconsistently. Teams need repeatable tests for both successful flows and clear user-facing errors. ### MVP **Inputs** - App adapter interface - Mock wallet scenarios - Transaction fixtures - Expected UI states and messages **Built-in scenarios** 1. Wallet connects successfully 2. User rejects a signature request 3. Wallet is locked or unavailable 4. Transaction simulation fails 5. Transaction is submitted but confirmation times out 6. User switches accounts or clusters 7. Unsupported transaction version is returned **Outputs** - Pass/fail terminal report - JSON results for CI - Human-readable failure details - Screenshot hook for browser-based runners ### Example scenario ```json { "name": "user_rejects_signature", "wallet": { "connected": true, "signTransaction": "reject" }, "expect": { "status": "recoverable_error", "message_contains": "cancelled", "retry_available": true } } ``` ### Suggested interface ```ts type WalletScenario = { name: string; setup: MockWalletConfig; action: "connect" | "sign" | "send"; expect: { status: "success" | "recoverable_error" | "fatal_error"; message_contains?: string; retry_available?: boolean; }; }; ``` ### Acceptance criteria - Runs entirely offline with deterministic fixtures. - Supports success, rejection, timeout, and malformed-response cases. - Produces nonzero exit status when expectations fail. - Separates technical error details from user-facing copy. - Allows teams to add custom wallet behaviors without changing the runner. - Includes a redacted JSON report suitable for CI artifacts. ### Product boundary This tool tests application behavior; it does not submit transactions, connect to wallets, or guarantee compatibility with any specific wallet implementation. ### Positioning copy > Catch wallet UX failures before users do. Test connect, sign, send, reject, and timeout states locally—with deterministic scenarios and CI-friendly reports.

# Self-Directed Draft: Solana Transaction Failure Triage Bundle ## Product specification A local CLI that turns a failed transaction’s simulation output into a shareable debugging bundle while removing likely secrets and user identifiers. **Input:** A JSON file containing simulation logs, an error value, instruction program IDs, and optional account addresses. No wallet connection required. **Output:** A Markdown report with: - the reported error and the last 20 log lines; - the instruction index, if present in the input; - a list of program IDs encountered, in log order; - account addresses replaced with stable labels such as `ACCOUNT_1`; - a warning when a log line cannot be confidently redacted. **Core rule:** Preserve the original file unchanged. Write the report to a new path, and never label the report “safe to share” when redaction is uncertain. **First-release acceptance checks** 1. The same input produces the same labels and report. 2. An input with no logs still produces a useful error summary. 3. Potentially sensitive strings in logs are either replaced or flagged for manual review. 4. The CLI works entirely offline and does not request signing keys. **Out of scope:** Diagnosing the root cause automatically or submitting transactions.

# Self-Directed Draft: Solana Compute-Budget Policy Linter ## Product specification A local CLI that checks a proposed transaction’s Compute Budget instructions against a team-defined policy before submission. **Input:** A JSON file containing the transaction’s instruction program IDs and encoded data, plus a policy file with a maximum requested compute-unit limit and maximum requested unit price. **Output:** A machine-readable report and a short human summary identifying decoded requests, policy violations, and instructions the tool could not interpret. Unknown encodings produce warnings, never a pass. **Core checks** - Flag requested limits or prices above policy. - Flag multiple instructions requesting the same setting for manual review. - Flag missing settings when the policy requires explicit values. - Report an estimated *requested priority-fee ceiling* only when both required values are available; do not present it as an actual charge. **Acceptance criteria:** A fixture below the configured caps passes; an over-cap fixture fails; an unknown instruction encoding yields an inconclusive result rather than silently passing. The CLI makes no RPC calls and never signs or submits transactions.

# Self-Directed Draft: Solana PDA Test-Vector Generator ## Product specification A local CLI that generates deterministic PDA test vectors from seed definitions, helping Solana teams verify address derivation across Rust, TypeScript, and other clients. ### Problem PDA bugs often come from inconsistent seed encoding, seed order, program IDs, or bump handling. A shared test-vector file gives every implementation the same expected inputs and outputs. ### Core workflow ```bash pda-vectors generate vectors.yaml --out vectors.json pda-vectors verify vectors.json ``` The tool performs no network calls and does not submit transactions. ### Input format ```yaml program_id: "PROGRAM_ID" cases: - name: "user_profile" seeds: - text: "profile" - pubkey: "USER_PUBLIC_KEY" - name: "vault" seeds: - text: "vault" - u64_le: 42 ``` Supported seed types: - `text` - `bytes_hex` - `pubkey` - `u64_le` - `u32_le` ### Output format ```json { "program_id": "PROGRAM_ID", "cases": [ { "name": "user_profile", "seeds": [ {"type": "text", "value": "profile"}, {"type": "pubkey", "value": "USER_PUBLIC_KEY"} ], "address": "DERIVED_ADDRESS", "bump": 255 } ] } ``` The generator should reject malformed public keys, unsupported seed types, oversized seed data, and ambiguous numeric encodings. ### Verification behavior `verify` recomputes every address and reports: ```text PASS user_profile FAIL vault expected address: ... computed address: ... expected bump: 254 computed bump: 255 ``` Exit codes: - `0`: all vectors pass - `1`: one or more vectors mismatch - `2`: invalid input or usage error ### Optional code generation ```bash pda-vectors emit vectors.json --lang typescript pda-vectors emit vectors.json --lang rust ``` Generated tests should preserve seed order and explicitly encode integer endianness. ### Acceptance checklist - [ ] Same input always produces byte-identical JSON output. - [ ] Seed order changes the derived result. - [ ] Text uses UTF-8 encoding. - [ ] Integers document little-endian encoding. - [ ] Every vector includes address and bump. - [ ] Invalid inputs fail before derivation. - [ ] Generated tests run without RPC access. - [ ] No private keys or signing operations are accepted.

# Self-Directed Draft: Solana Account-Layout Contract Checker ## Product specification A local tool that compares a Solana program’s expected account layout against client-side declarations and reports mismatches before integration testing. ### Problem Account-order and signer/writable-flag mistakes can produce confusing transaction failures. Teams need a small, deterministic check that runs in CI without submitting transactions or contacting an RPC endpoint. ### Inputs - A JSON contract describing each instruction’s accounts: - account name - position - signer requirement - writable requirement - optional PDA seed metadata - A client-side account manifest exported as JSON - Optional previous contract version for drift detection ### Output Markdown or JSON containing: - Missing accounts - Unexpected accounts - Position mismatches - Signer flag mismatches - Writable flag mismatches - Added, removed, or reordered accounts between versions - Exit code `0` for clean validation, `1` for contract violations ### Example contract ```json { "instruction": "initialize", "accounts": [ {"name": "payer", "position": 0, "signer": true, "writable": true}, {"name": "state", "position": 1, "signer": false, "writable": true}, {"name": "systemProgram", "position": 2, "signer": false, "writable": false} ] } ``` ### Example report ```text initialize: FAILED - position 1: expected "state", received "systemProgram" - position 2: expected "systemProgram", received "state" - state: expected writable=true, received writable=false Result: 3 contract violations ``` ### CLI surface ```bash account-contract check \ --contract contracts/initialize.json \ --client manifests/initialize.json \ --format markdown account-contract diff \ --before contracts/v1.json \ --after contracts/v2.json ``` ### Design constraints - Local-only by default - No private-key handling - No transaction submission - Stable, machine-readable JSON output - Human-readable Markdown for pull requests - Explicitly distinguish “reordered” from “added” or “removed” - Treat account names as identifiers, not proof of on-chain ownership ### Acceptance criteria - Detects every mismatch in the example above - Produces deterministic output for identical inputs - Returns nonzero status on any violation - Handles empty account lists - Rejects duplicate positions and duplicate names - Includes tests for reordered, missing, unexpected, signer, and writable accounts - CI can fail using only the process exit code ### Suggested repository layout ```text account-contract/ src/ parser validator reporter contracts/ manifests/ tests/ README.md ``` ### One-line positioning **“Catch Solana account-list mistakes in CI—before they become integration-test mysteries.”**

# Self-Directed Draft: Solana Simulation Failure Brief ## Product specification A local CLI that turns a saved `simulateTransaction` JSON response into a short, shareable failure report. It **does not submit transactions or contact an RPC endpoint**. **Input:** A JSON file containing simulation `err`, `logs`, and optional `unitsConsumed` and `innerInstructions`. **Output:** A Markdown brief with: - The reported error and compute units, when present. - An indented invocation trace reconstructed from program invoke, success, and failure log lines. - The deepest invocation that reported a failure, labeled **“failure reported here”**, not “root cause.” - Evidence lines copied from the input, with line numbers. - A warning when logs are missing, truncated, or insufficient to identify a failing invocation. Custom program errors remain numeric unless the user supplies a local code dictionary. The tool never guesses what an unknown code means. **CLI sketch:** `sol-brief simulation.json --out failure.md` **Acceptance checks:** It handles a nested CPI failure, a top-level failure, missing logs, and contradictory or incomplete log depth without crashing. Every conclusion in the brief points to input evidence; uncertainty stays visible.

# Self-Directed Draft: Solana RPC Capability Probe ## Product specification A CLI that tests whether an RPC endpoint supports the methods, commitments, WebSocket behavior, and response limits required by a Solana application. ### Problem An app may work against one RPC provider but fail elsewhere because of unsupported methods, different limits, missing WebSocket support, or inconsistent configuration. Teams need a portable preflight check before changing endpoints or deploying. ### Example usage ```bash rpc-probe \ --http "$SOLANA_RPC_URL" \ --ws "$SOLANA_WS_URL" \ --commitment confirmed \ --config rpc-probe.yml ``` ### Configuration ```yaml minimum_slot: true methods: - getHealth - getLatestBlockhash - getSignatureStatuses - getTokenAccountsByOwner - getProgramAccounts websocket: subscribe_account: true limits: max_response_bytes: 5000000 ``` ### Output ```text RPC preflight: FAILED ✓ getHealth ✓ getLatestBlockhash ✓ confirmed commitment ✗ getProgramAccounts reason: timeout after 3000ms ⚠ WebSocket account subscription reason: no message received within 5s Summary: 3 passed, 1 failed, 1 warning Machine-readable report: rpc-report.json ``` ### Core checks - Send JSON-RPC requests with configurable timeout and retries. - Verify required methods return valid JSON-RPC responses. - Test requested commitment levels explicitly. - Compare `getLatestBlockhash` and slot-related responses for basic consistency. - Open a WebSocket connection and validate one subscription lifecycle. - Record latency, HTTP status, RPC error code, and response size. - Never log authorization headers, query-string secrets, or full account data. - Support redacted JSON output for CI artifacts. ### Exit codes - `0`: all required checks pass. - `1`: one or more required checks fail. - `2`: invalid configuration or invocation. - `3`: probe could not establish a connection. ### Acceptance criteria - A team can define required RPC capabilities in version-controlled YAML. - CI fails when a required method or WebSocket capability is unavailable. - Reports identify the failed check without exposing credentials. - The probe can run against a local validator or remote endpoint. - No transaction signing, broadcasting, or wallet access is required. ### Suggested implementation - TypeScript CLI. - Separate HTTP and WebSocket adapters. - Pluggable check interface: `run(context): Promise<CheckResult>`. - JSON and human-readable reporters. - Unit tests using mocked RPC responses plus an optional local integration suite.

# Self-Directed Draft: Solana Account Compatibility Scanner ## Product specification A CLI and CI tool that compares expected Solana account layouts against decoded accounts before a program or client release. ### Problem Client updates can silently break when account fields, discriminators, sizes, or optional accounts change. Teams need a repeatable compatibility check that runs locally and in CI. ### Core workflow 1. Define account schemas in versioned YAML. 2. Export or provide sample account data for each schema version. 3. Run the scanner against fixtures or a configured RPC endpoint. 4. Receive a human-readable report and machine-readable JSON. 5. Block CI when a breaking change lacks an explicit migration annotation. ### Example schema ```yaml name: Position version: 2 discriminator: "base58-or-hex-value" fields: - name: owner type: pubkey - name: amount type: u64 - name: opened_at type: i64 - name: metadata type: bytes optional: true ``` ### Detected changes - Field insertion, removal, or reordering - Type or width changes - Discriminator changes - Account-size changes - Optional fields becoming required - Newly required accounts in an instruction fixture - Missing migration notes for incompatible versions ### CLI ```bash acctscan check schemas/ fixtures/ acctscan diff schemas/position-v1.yaml schemas/position-v2.yaml acctscan report --format json --out compatibility.json ``` ### CI policy ```yaml rules: fail_on: - discriminator_change - field_reorder - type_change - required_field_added warn_on: - optional_field_added - account_size_increase require_note_for: - field_removed - migration_required ``` ### Safety and privacy - Never request private keys or signing authority. - Treat RPC data as untrusted input. - Support local fixtures so sensitive account data need not leave a developer’s environment. - Redact raw account bytes from default reports. - Clearly label inferred compatibility versus confirmed compatibility. ### MVP acceptance criteria - Compares two schema versions deterministically. - Produces stable exit codes for CI. - Generates Markdown and JSON reports. - Includes fixture-based tests for compatible and breaking changes. - Documents supported primitive types and known limitations. - Lets reviewers approve an intentional breaking change with a migration note. ### Suggested repository layout ```text acctscan/ schemas/ fixtures/ src/ tests/ .github/workflows/compatibility.yml README.md ``` ### Success signal A reviewer can understand the compatibility impact of a schema change from one CI comment without manually decoding account bytes.

# Self-Directed Draft: Solana Transaction Failure Report Kit ## Product specification A small SDK and issue-template generator that helps Solana apps collect useful transaction failure reports without collecting wallet secrets. **User flow** 1. When a transaction fails, the app offers **“Download failure report.”** 2. The user previews the report and can remove any field before saving it. 3. The downloaded JSON can be attached to a support ticket. Nothing is uploaded by default. **Report fields** - App version, environment label, and timestamp - Cluster and selected RPC endpoint *hostname* (not credentials or query parameters) - Transaction signature, if one exists - Error code and sanitized error message - Locally available simulation logs, capped at a configurable length - Optional user-written description of what they expected to happen **Privacy rules** - Never include seed phrases, private keys, wallet-adapter storage, auth headers, or full RPC URLs. - Omit account addresses by default except the connected wallet and transaction signature; let the user remove those too. - Strip URL query strings and scan free-text fields for likely credentials before export. **Acceptance criteria** - A user can inspect and edit the report before download. - A failed transaction with no signature still produces a report. - Tests cover redaction, oversized logs, missing RPC responses, and malformed errors. - The SDK makes no network request to a reporting service.

# Self-Directed Draft: Solana Program Release Handoff Checklist Use one copy per proposed release. **Do not treat a checked box as proof; attach the evidence.** **Release record** - [ ] Record the program ID, target cluster, source commit, build artifact hash, release owner, and planned window. - [ ] Name the people authorized to approve and execute the upgrade. Confirm who can pause or cancel it. **Before execution** - [ ] Review the code change, account migrations, and any changed client assumptions. - [ ] Run tests against the exact build artifact intended for release; save results and known limitations. - [ ] Verify the upgrade authority and approval requirements independently of the person preparing the release. - [ ] Write a rollback decision rule and identify what can—and cannot—be reversed. **Execution and handoff** - [ ] Use a second reviewer to compare the proposed artifact and program ID with the approved release record. - [ ] Record the resulting transaction identifier and independently check the deployed program state. - [ ] Test critical user flows, including failure paths, before announcing completion. - [ ] Hand off monitoring owners, escalation contacts, and a short list of symptoms that require action. **Release note template:** “Changed: __. User impact: __. Known limitations: __. Verification completed: __. Contact for issues: __.”

# Self-Directed Draft: Solana Transaction Intent Policy Engine ## Product specification A lightweight library that evaluates an unsigned Solana transaction before a wallet signs it. It converts recognized instructions into human-readable intents and applies configurable safety rules. It never signs, submits, or changes transactions. ### Problem Apps often ask users to approve transactions without clearly explaining the expected account changes, authorities, or token movements. Teams need a reusable policy layer for warnings and approval screens. ### MVP **Input** - Serialized or in-memory unsigned transaction - Optional account metadata supplied by the integrating app - Policy configuration **Output** ```ts { status: "allow" | "warn" | "block", intents: [ { program: "known-program-id", action: "transfer", source: "account", destination: "account", mint: "mint-account", amount: "raw-amount" } ], findings: [ { code: "UNKNOWN_INSTRUCTION", severity: "warning", message: "Instruction could not be decoded." } ] } ``` ### Initial rules - Block transactions containing a configured forbidden program. - Warn when an instruction cannot be decoded. - Warn when a signer or writable account is unexpected. - Warn when a token transfer exceeds a caller-defined limit. - Warn when a transaction includes durable nonce or unusual fee settings. - Require explicit approval for authority-changing instructions. - Distinguish “what the app requested” from “what the transaction contains.” ### Integration surface ```ts const review = await policy.review({ transaction, expected: { action: "swap", programs: allowedPrograms, maxTokenValue: "configured-by-app" } }); ``` The SDK should expose deterministic results so apps can snapshot-test policy decisions. ### Non-goals - Private-key handling - Wallet connection management - Chain-state guarantees - Universal decoding of every Solana program - Replacing wallet confirmation UI ### Acceptance checklist - Same transaction and policy produce the same result. - Unknown instructions are never silently marked safe. - Every block or warning includes a stable code. - No signing or network submission occurs inside the package. - Decoders and rules can be added without modifying the core evaluator. - Malformed input returns a structured error rather than crashing. ### Suggested package layout ```text /core evaluator and result types /decoders program-specific instruction decoders /rules composable safety policies /fixtures redacted test transactions /docs integration and threat-model guidance ``` ### Positioning copy **Make transaction approval explainable.** A policy engine for Solana apps that turns unsigned transactions into reviewable intents, flags unexpected behavior, and keeps signing in the user’s wallet.

# Self-Directed Draft: Solana RPC Read-Path Guard ## Product specification A small SDK wrapper that helps Solana apps keep read-only screens usable when RPC requests are slow, duplicated, or failing. It does not submit transactions or silently switch the endpoint used for signing. **Core behavior** - Deduplicate identical in-flight reads and cache successful responses for a caller-defined lifetime. - Give each screen a request budget; queue low-priority refreshes rather than letting them crowd out user-initiated reads. - Return a typed state: `fresh`, `cached`, `stale`, or `unavailable`, with the response’s endpoint and observation time. - Permit a configured fallback read endpoint, but never present a fallback result as fresh unless it meets the caller’s freshness rule. **Safety boundary:** A stale balance or account state must be visibly labeled. The guard must not use cached data to decide whether a transaction is safe to sign. **First build:** Support `getAccountInfo` and `getMultipleAccounts` behind an adapter, with configurable timeouts, cache lifetimes, and per-screen budgets. **Acceptance test:** In a simulated outage, repeated requests for the same account produce one in-flight call, the UI receives a labeled stale result when permitted, and a signing flow receives no silent stale substitute.

# Self-Directed Draft: Solana Event Ingestion Replay Harness ## Product specification A local developer tool that replays recorded Solana transaction and account-change fixtures through an indexing pipeline, helping teams test parsers, deduplication, and schema migrations without relying on live network access. ### Problem Indexers can break when transaction formats, account layouts, commitment timing, or duplicate deliveries differ from the happy path. Reproducing those cases manually is slow and inconsistent. ### MVP - JSON fixture format for: - slot and signature metadata - account state before/after processing - transaction or instruction payloads - delivery sequence and duplicate events - CLI commands: - `replay run fixtures/example.json` - `replay validate fixtures/` - `replay diff --before old.json --after new.json` - Adapter interface for a team’s parser: - `decode(event)` - `normalize(decoded)` - `upsert(normalized)` - Run report showing: - parsed events - ignored events and reasons - duplicate handling - parser errors - output records before/after replay ### Design principles 1. **Deterministic:** identical fixtures produce identical reports. 2. **Offline-first:** no network access required for replay. 3. **Redaction-friendly:** fixtures can omit signatures, addresses, or payload fields. 4. **Pipeline-agnostic:** adapters support files, queues, or database sinks. 5. **Failure-preserving:** malformed inputs remain visible instead of being silently discarded. ### Example fixture ```json { "name": "duplicate-delivery", "events": [ { "id": "event-1", "slot": 123, "signature": "redacted", "payload": {}, "delivery": 1 }, { "id": "event-1", "slot": 123, "signature": "redacted", "payload": {}, "delivery": 2 } ] } ``` ### Acceptance criteria - A team can add a fixture without changing the replay engine. - Duplicate deliveries are reported and handled according to adapter policy. - A parser exception identifies the fixture, event ID, and processing stage. - Two runs with the same fixture produce byte-identical normalized output. - A schema change can be tested against both old and new expected output. ### Suggested first users - Teams maintaining custom indexers - Analytics pipelines consuming program events - Backend engineers writing wallet or activity histories - QA teams testing parser regressions ### Non-goals - Live RPC access - Transaction submission - Chain data verification - Replacing production observability or alerting

# Self-Directed Draft: Solana Transaction Intent Receipt ## Product specification A client-side component that shows users what a proposed transaction is expected to do *before* they sign, then saves a local receipt of what they approved. **Problem:** A wallet prompt may not explain an app’s intended outcome in terms a user can check. **Inputs:** An unsigned transaction, the app’s declared intent, and an optional simulation result. The declared intent states the expected token movements, fee payer, and any accounts the app expects to create. **Output:** A compact review card with: - **App says:** the declared intent, explicitly labeled as an app claim. - **Transaction shows:** decoded instructions and account changes the component can identify. - **Could not verify:** unknown instructions, missing simulation, or differences between the claim and decoded transaction. - **Receipt:** a locally saved copy of the review and the transaction signature, if the user later supplies it. **Safety rule:** Never label a transaction “safe.” If decoding is incomplete or the claim differs from what can be inspected, make that uncertainty prominent rather than hiding it behind a success indicator. **First version:** Support SOL transfers, SPL token transfers, associated token account creation, and unknown-instruction warnings. Keep signing outside the component. **Acceptance test:** Given a transaction that transfers more tokens than the app declares, the card displays both amounts side by side and warns of the mismatch before signing.

# Self-Directed Draft: Solana RPC Failure Triage Kit ## Product specification A small CLI and runbook that helps Solana teams distinguish application bugs from RPC, simulation, and transaction-propagation failures. ### Problem A failed transaction often produces an unclear error: stale blockhash, account-not-found, simulation rejection, rate limiting, or conflicting commitment assumptions. Engineers need a consistent diagnostic record before changing code or infrastructure. ### Core workflow ```text triage <transaction-or-request> 1. Capture request type, cluster label, commitment, and timestamp 2. Record relevant public keys and recent blockhash metadata 3. Run read-only checks against the configured RPC endpoint 4. Optionally compare the same checks against a second configured endpoint 5. Classify the failure and emit a redacted report ``` ### Failure categories - **Request construction:** malformed instruction, missing signer, invalid account metadata - **Simulation:** program error, compute exhaustion, account constraint failure - **Freshness:** expired or mismatched blockhash context - **Propagation:** submission accepted locally but not observed by follow-up queries - **Availability:** timeout, rate limit, or transport failure - **Configuration:** wrong cluster, commitment mismatch, or inconsistent endpoint settings ### Report format ```text Case ID: Cluster label: Endpoint label: Observed at: Request type: Result: Likely category: Evidence: Checks performed: Recommended next check: Sensitive fields removed: ``` The report must never print private keys, full authorization headers, or complete signed transaction bytes by default. ### Minimal commands ```text triage rpc-health triage simulate --file request.json triage transaction --signature <signature> triage report --case <case-id> ``` ### Design constraints - Read-only by default - No automatic retries that could duplicate a state-changing request - Explicitly label endpoint comparisons; do not treat disagreement as proof of correctness - Preserve raw RPC error text alongside normalized categories - Allow teams to provide their own cluster and endpoint labels - Exit with a nonzero status for unresolved or unsafe conditions ### Acceptance criteria - Produces a redacted, copyable report from one failed request - Separates simulation failure from transport failure - Records commitment and endpoint context - Detects and labels stale blockhash-related responses when identifiable - Works without requiring custody of signing material - Includes a fixture-based test suite for timeout, rate-limit, simulation, and malformed-request cases ### Suggested first release Ship a local CLI with JSON output and a Markdown renderer. Add endpoint comparison only after the single-endpoint report is reliable.

# Self-Directed Draft: Solana IDL Drift Sentinel ## Product specification A CI tool that detects when a Solana client’s generated types or instruction builders may no longer match the program interface expected by the repository. ### Problem Client code can silently become unreliable when instruction names, account ordering, discriminators, argument types, or error definitions change. Teams need an early warning before a release reaches users. ### Inputs - Repository path - Baseline IDL or interface snapshot - Current IDL, generated client output, or manually supplied interface manifest - Optional allowlist for intentional changes ### Checks - Added, removed, or renamed instructions - Account order, mutability, signer, and PDA-seed metadata changes - Argument type and optionality changes - Account type and field-layout changes - Custom error additions or renames - Generated source differing from its declared input - Missing test coverage for changed instructions ### Output A machine-readable report: ```json { "status": "breaking", "changes": [ { "kind": "account-order", "instruction": "deposit", "severity": "high", "message": "Account position 2 changed from vault to user" } ] } ``` Also produce a concise Markdown summary suitable for a pull request. ### CI behavior - Exit `0` for additive or approved changes - Exit `1` for unapproved breaking changes - Exit `2` for malformed or unavailable inputs - Support a committed review file for explicitly accepted changes - Never infer that a program is safe merely because no drift was detected ### Minimal CLI ```text idl-sentinel check \ --baseline interfaces/baseline.json \ --current interfaces/current.json \ --allow .idl-sentinel-allow.json \ --markdown report.md ``` ### MVP scope 1. Define a normalized interface manifest. 2. Implement deterministic diffing. 3. Classify changes as additive, behavioral-risk, or breaking. 4. Emit JSON and Markdown reports. 5. Add fixtures for common instruction and account-layout changes. 6. Document CI integration for pull requests. ### Acceptance checklist - [ ] Same inputs produce byte-identical reports. - [ ] Account metadata changes are detected. - [ ] Argument type changes are detected. - [ ] Allowlisted changes require an explicit reason. - [ ] No network access is required for baseline comparison. - [ ] Exit codes are documented and tested. - [ ] Reports identify the affected instruction or account. - [ ] Tool clearly states that interface compatibility is not runtime correctness.

# Self-Directed Draft: Transaction Preview Guard ## Product specification A local component that turns a proposed Solana transaction into a plain-language approval preview. It helps a signer spot unexpected account changes before approving. It is **not** a safety verdict. ### Input - Serialized proposed transaction - Expected signer and fee-payer addresses - Optional simulation result and application-provided intent, such as “send 2 tokens” ### Output A structured preview with three sections: 1. **Requested actions:** programs invoked, signer requirements, fee payer, and any transfers the component can decode. 2. **Expected changes:** balance and token-account deltas from simulation, clearly labeled *estimates*. 3. **Uncertainty:** undecoded instructions, missing account data, failed simulation, or differences between stated intent and decoded actions. ### Guardrails - Never label a transaction “safe.” - Show raw addresses alongside any display names. - Put an “Unable to explain fully” warning above the approval button when decoding or simulation is incomplete. - Do not silently treat a successful simulation as proof that execution will match it. - Keep transaction data local by default; require an explicit product decision before sending it to a remote service. ### First-release acceptance checks - A user can distinguish a decoded transfer from an opaque instruction. - A mismatched fee payer is visibly flagged. - A failed or unavailable simulation still produces a useful partial preview. - The component never signs, submits, or modifies the transaction.

# Self-Directed Draft: Solana Account Fixture Pack ## Product specification A repository format and small CLI for storing sanitized Solana account snapshots as deterministic test fixtures. Teams can use them to test decoders, dashboards, indexers, and client libraries without depending on live RPC responses. ### Problem Read-path code often breaks when account layouts, optional fields, byte lengths, or malformed data differ from assumptions. Live-chain tests are slow, nondeterministic, and may expose sensitive context. ### MVP **Fixture contents** - Account public key placeholder - Owner program placeholder - Lamports and executable flag - Data encoding: base64 or hex - Slot/context label supplied by the user - Expected decoded JSON - Optional malformed-data case - Human-readable scenario description **CLI** ```text fixture init <name> fixture validate ./fixtures fixture decode ./fixtures/token-account.json fixture diff ./fixtures/a.json ./fixtures/b.json ``` ### Validation rules - Required metadata is present. - Encoded data can be decoded. - Expected output is valid JSON. - Fixture identifiers are unique. - Placeholder keys match the configured format. - No fixture contains undeclared private-key material. - Decoder output matches the stored expectation. ### Suggested repository layout ```text fixtures/ healthy/ missing-optional-field/ wrong-owner/ truncated-data/ schemas/ fixture.schema.json scripts/ check-fixtures README.md ``` ### Example fixture ```json { "name": "healthy-example", "owner": "OWNER_PLACEHOLDER", "lamports": 1000, "executable": false, "data": { "encoding": "base64", "value": "AAECAwQ=" }, "expected": { "status": "decoded", "fieldA": 1 } } ``` ### Acceptance criteria - A new contributor can add a fixture using one documented template. - Validation fails with actionable file-and-field errors. - Tests run offline with no RPC dependency. - Malformed inputs are represented intentionally rather than hidden. - Fixture diffs are readable in code review. - Placeholder substitution is explicit and never silently applied. ### Distribution angle Offer the pack as a starter repository template, then add adapters for common client languages. The core remains format-first and dependency-light, making it useful to teams building different Solana products.

# Self-Directed Draft: Solana Integration Contract Linter ## Product specification A local CLI that checks whether a Solana application’s documented integration contract is complete and internally consistent before another team consumes it. ### Problem Teams often share program addresses, instruction names, account requirements, token assumptions, and failure conditions across scattered documents. Missing or contradictory details create avoidable integration work. ### Inputs - A YAML or JSON contract file - Optional Anchor IDL or equivalent interface description - Optional example transaction instructions - Optional environment labels such as `devnet`, `testnet`, or `mainnet` ### Contract format ```yaml program: address: "<program-address>" interface: "path/to/interface.json" instructions: - name: "example_instruction" accounts: - name: "authority" signer: true writable: false - name: "state" signer: false writable: true arguments: - name: "amount" type: "u64" assets: - symbol: "EXAMPLE" mint: "<mint-address>" decimals: 6 checks: - "authority must own the state account" - "amount must be greater than zero" ``` ### CLI ```text sol-contract lint contract.yaml sol-contract render contract.yaml --format markdown sol-contract diff old.yaml new.yaml ``` ### Lint rules - Required program and asset addresses are present. - Every writable account is explicitly marked. - Signer requirements are declared. - Instruction arguments have names and types. - Asset decimals are stated rather than assumed. - Example addresses are not reused across environment sections. - Referenced interface items exist in the supplied interface file. - Human-readable checks are attached to an instruction or marked global. - Placeholder values are visibly flagged. ### Output A deterministic report containing: - Errors that block integration - Warnings requiring human review - A normalized contract summary - A Markdown handoff document - A JSON report suitable for CI artifacts Example: ```text ERROR instructions.example_instruction.accounts: account "state" is writable but has no ownership expectation WARN assets[0].mint: address is marked as placeholder Summary: 1 error, 1 warning ``` ### Design constraints - Read-only by default - No wallet access - No signing or submission - Never treats a YAML declaration as proof of on-chain state - Preserves unknown fields for forward compatibility - Stable exit codes for CI use ### Acceptance criteria - Same input produces byte-for-byte identical JSON output. - Invalid contracts identify file paths and field names. - Markdown output can be handed to an integrator without terminal context. - A sample repository includes valid, invalid, and placeholder-heavy fixtures. - Documentation clearly distinguishes declared information from independently verified information.

# Self-Directed Draft: Solana Transaction Failure Notebook ## Product specification A local tool that turns a **user-supplied transaction simulation result** into a short, shareable debugging report. It helps a team discuss a failed transaction without passing around raw logs or exposing unnecessary account data. **Input:** Simulation logs, error details, and optional team-written labels for program IDs and instructions. The tool does not request wallet access or submit transactions. **Output:** A Markdown report containing: - The first reported failure and its instruction index - Relevant log lines in execution order - Compute units reported, if present - A distinction between observed facts and possible causes - A checklist of missing context needed to investigate further **Privacy defaults:** Redact signatures and account addresses unless the user explicitly keeps them. Show a preview before export. **MVP acceptance criteria:** Given a saved simulation result, a developer can produce a readable report locally; every quoted log line can be traced to the input; and the tool never presents a guessed cause as a confirmed diagnosis.

# Self-Directed Draft: Solana Upgrade Evidence Pack ## Product brief A CLI that generates a reviewable, machine-readable evidence bundle before and after a Solana program upgrade. It helps teams verify intended authorities, binaries, configuration, and post-upgrade behavior without making changes on-chain. ## Problem Upgrade reviews often rely on scattered terminal output and screenshots. A missed authority, unexpected binary, or incomplete post-upgrade check can make incident response harder. ## MVP command ```bash solana-upgrade-pack preflight \ --program-id <PROGRAM_ID> \ --cluster <CLUSTER> \ --expected-binary ./target/deploy/program.so \ --config upgrade-pack.yml \ --out ./evidence/preflight-<timestamp> ``` ```bash solana-upgrade-pack verify \ --pack ./evidence/preflight-<timestamp> \ --cluster <CLUSTER> ``` The tool is read-only unless an explicit future command is added. ## `upgrade-pack.yml` ```yaml program_id: "<PROGRAM_ID>" expected_upgrade_authority: "<PUBKEY_OR_NONE>" expected_buffer_authority: "<PUBKEY>" required_checks: - program_account - upgrade_authority - binary_hash - executable_flag - configured_idl_hash - smoke_transaction smoke_transaction: command: " pnpm test:smoke " ``` ## Evidence captured - Timestamp and selected cluster - CLI/tool versions - Program account metadata - Upgrade and buffer authority observations - Local binary hash - Optional IDL/configuration hashes - Redacted command arguments - Smoke-test exit code and output - Per-check status: `pass`, `fail`, or `not_run` - A final JSON manifest with a hash of every evidence file Secrets, private keys, and full environment variables are excluded by default. ## Safety rules - Never print private keys or seed phrases. - Require confirmation before using any signer. - Fail closed when an expected authority is missing or mismatched. - Mark unavailable checks as `not_run`, never as passing. - Support offline verification of an existing evidence pack. ## Example output ```text Preflight: FAILED PASS program account is executable PASS binary hash matches expected FAIL upgrade authority differs from configured value WARN smoke transaction not run Evidence: ./evidence/preflight-2025-01-01/ Manifest: manifest.json ``` ## Acceptance criteria - Produces deterministic JSON suitable for CI artifacts. - Exits nonzero on failed required checks. - Redacts configured sensitive values. - Allows a reviewer to verify results without rerunning the original command. - Includes unit tests for hash comparison, authority mismatch, redaction, and missing-check handling. ## Future extensions - GitHub Actions annotation output - Signed reviewer approval files - Diff view between two evidence packs - Pluggable smoke-test adapters for Anchor, web3.js, and Rust clients