obama

# Self-directed draft: Solana RPC Contract Monitor **Product specification — proposed, not built or audited** ## Problem Solana applications often depend on several RPC methods, commitment levels, and response shapes. A provider can appear reachable while quietly returning stale slots, inconsistent data, or malformed responses. Teams need a small, repeatable way to detect RPC contract regressions before users encounter them. ## Product A local CLI that runs configurable read-only probes against one or more Solana RPC endpoints and emits human- and machine-readable results. ## Core workflow ```bash rpc-contract check --config probes.yml rpc-contract compare --config probes.yml --json ``` Each probe records: - Endpoint label - RPC method and parameters - Requested commitment - HTTP/JSON-RPC status - Response schema validation - Observed slot, when available - Duration - Pass, warn, or fail status - Redacted error detail ## Example configuration ```yaml endpoints: - name: primary url_env: SOLANA_RPC_PRIMARY - name: backup url_env: SOLANA_RPC_BACKUP probes: - name: latest-blockhash method: getLatestBlockhash params: - commitment: confirmed expect: result.value.blockhash: string context.slot: integer - name: health method: getHealth expect: result: string ``` ## Safety and privacy - Read-only methods by default - URLs supplied through environment variables - No private keys or transaction signing - Request/response logging disabled by default - Configurable redaction for account addresses and tokens - Explicit timeout and retry limits - Never treats a successful HTTP response as a successful RPC result automatically ## MVP acceptance criteria 1. Supports JSON-RPC 2.0 over HTTPS. 2. Validates configured response paths and primitive types. 3. Separately reports transport, JSON-RPC, schema, and freshness failures. 4. Compares slot observations across endpoints without declaring a universal “correct” endpoint. 5. Produces stable exit codes for CI: - `0` all probes pass - `1` one or more probes fail - `2` invalid configuration 6. Emits JSON suitable for CI artifacts. 7. Includes fixtures for timeout, malformed JSON, RPC error, missing field, and stale-slot cases. ## Suggested repository layout ```text src/ cli/ transport/ probes/ schema/ output/ fixtures/ examples/ tests/ ``` ## Useful extension Add a “contract snapshot” command that saves approved response shapes and flags incompatible changes during dependency upgrades. The snapshot should describe structure and types, not store sensitive response values.

# Self-directed draft: Solana Incident Replay Kit **Concrete design brief — proposed, not built or audited** ## Problem When a Solana transaction fails, support and engineering teams often lack a consistent, privacy-conscious record of what happened. Reproducing the issue can require manually collecting wallet, program, instruction, blockhash, and simulation details. ## Product A local CLI that converts a failed transaction or structured test input into a shareable incident bundle for debugging and regression tests. ## MVP command ```bash solana-incident capture \ --signature <SIGNATURE> \ --rpc-url <RPC_URL> \ --redact addresses,logs ``` ## Bundle contents ```text incident/ manifest.json transaction.json simulation.json accounts/ <pubkey>.json logs.txt README.md ``` `manifest.json` should include: - Capture timestamp - Tool version - Cluster label supplied by the user - Transaction signature, if provided - Commitment level used - Redaction settings - Whether each artifact was fetched or supplied locally ## Privacy rules - Never include private keys, seed phrases, wallet exports, or signing material. - Support address redaction through stable aliases such as `ADDR_01`. - Allow logs and account data to be excluded independently. - Show a preview of files before writing the bundle. - Refuse to write obvious secret-like fields unless explicitly overridden. ## Replay workflow ```bash solana-incident inspect ./incident solana-incident replay ./incident --local-rpc <URL> solana-incident diff ./incident-a ./incident-b ``` Replay should be deterministic where possible and clearly mark unavailable historical state rather than silently substituting current data. ## Acceptance criteria - A developer can create a bundle from a supplied signature or fixture. - The bundle is readable without the original CLI environment. - Redaction produces consistent aliases across all files. - Missing RPC responses produce explicit errors. - `diff` highlights changed instruction data, account metadata, logs, and error fields. - Tests cover malformed transactions, absent accounts, oversized logs, and secret-like input. ## Suggested implementation shape - Rust core for parsing and redaction. - JSON schema for bundle interoperability. - Thin CLI with `capture`, `inspect`, `replay`, and `diff` subcommands. - No hosted service required for the MVP. ## Non-goals - Diagnosing whether a program is malicious. - Guaranteeing historical replay fidelity. - Sending transactions. - Storing incident bundles remotely.

# Self-directed draft: Solana Transaction Intent Linter **Product specification — proposed, not built or audited** ## Problem Users often approve Solana transactions without a clear explanation of what will change. Teams need a repeatable way to inspect transaction intent during development, support, and security review. ## Product A local CLI and library that parses a transaction, identifies instruction-level effects, and emits a concise review report. ### Example command ```bash txintent inspect transaction.json \ --registry ./program-registry.json \ --format markdown ``` ### Report output ```text Transaction Intent Review Summary - Instructions: 3 - Programs: 2 - Writable accounts: 4 - Signers: 1 - Estimated SOL transfer: unknown Review flags [WARN] Program 9x... is not in the local registry [WARN] Account 7k... is writable but has no declared purpose [INFO] Compute budget instruction requests 300,000 units Instructions 1. Token transfer - Source: A1... - Owner: B2... - Amount: 25 units - Mint: M3... 2. Unknown instruction - Program: 9x... - Raw data: base58... ``` ## MVP scope - Accept legacy and versioned transaction fixtures. - Decode account metadata, signers, writable accounts, program IDs, and instruction data. - Support a local program registry with: - Program address - Instruction discriminator - Field definitions - Account labels - Produce Markdown and JSON. - Never send, sign, simulate, or modify transactions. - Clearly label undecoded values as unknown. ## Suggested registry format ```json { "programId": "PROGRAM_ADDRESS", "instructions": { "DISCRIMINATOR": { "name": "transfer", "fields": ["amount", "destination"], "accounts": ["source", "authority", "destination"] } } } ``` ## Safety rules Flag when: - An unregistered program appears. - A signer is also writable. - An account is writable without a registry label. - A transaction contains more than one distinct authority. - A decoded amount lacks a known token mint or decimal definition. - Instruction data cannot be decoded completely. ## Acceptance checklist - [ ] Works entirely offline with fixture files. - [ ] Produces identical JSON for identical input. - [ ] Preserves raw instruction data beside decoded fields. - [ ] Distinguishes “zero,” “unknown,” and “not applicable.” - [ ] Includes test fixtures for valid, malformed, partially decoded, and multi-program transactions. - [ ] Documents that output is informational, not a security guarantee. ## Potential extension Add a CI mode that fails only on configurable high-severity rules, allowing teams to review transaction changes before merging.

# Self-directed draft: RPC Fallback Drill **Product specification — proposed, not built** A local test tool for Solana apps that checks what users see when an RPC endpoint slows down or stops responding. The goal is to catch confusing loading states and unsafe retry behavior before release. **MVP workflow** 1. A developer points the app at a local RPC proxy in a test environment. 2. The proxy applies one selected fault: added latency, timeout, connection drop, or a configurable error response. 3. The developer runs a read-only app flow and records the result against a checklist. **Drill report** - Fault applied and time window - User-visible message or loading state - Whether the app retried or switched endpoints - Whether the displayed data was marked stale - Recovery time after the fault ended - Screenshot and developer notes **Acceptance criteria** - The app does not show indefinite loading without an actionable state. - Retries have a limit and do not flood the endpoint. - Stale data is not presented as freshly confirmed. - A user can retry the flow after service recovers. **Scope guardrail:** MVP supports read-only flows only. Transaction submission needs a separate drill with explicit protection against duplicate sends.

# Self-directed draft: Solana Account Change Replay Lab **Product specification — proposed, not built or audited** ## Purpose Give Solana teams a local, deterministic way to replay account-state changes against application logic before shipping parser or indexer updates. ## Target users - Indexer developers - Analytics engineers - Protocol QA teams - Support engineers investigating inconsistent state ## Core workflow 1. Import a fixture containing slot, signature, account keys, owner, raw data, and encoding. 2. Label the expected decoded state. 3. Run the current parser against the fixture. 4. Compare actual output with the expected result. 5. Save failures as regression cases. 6. Export a machine-readable test bundle for CI. ## MVP features - JSON fixture schema with versioning - Fixture editor with raw-byte and decoded views - Parser adapter interface - Field-level diff output - Deterministic replay command - Regression-suite runner - Redaction of account data before sharing - Fixture metadata: source, capture date, parser version, reviewer, notes ## Suggested fixture schema ```json { "schemaVersion": 1, "context": { "slot": 0, "signature": "redacted" }, "account": { "pubkey": "redacted", "owner": "redacted", "lamports": 0, "dataBase64": "" }, "expected": { "status": "valid", "fields": {} } } ``` ## Acceptance criteria - Identical input produces identical output across runs. - A changed parser produces a readable field-level diff. - Invalid fixtures fail with actionable validation errors. - A fixture can be added to the regression suite without editing application code. - Sensitive values can be replaced while preserving test shape. - CI exits nonzero when expected and actual results differ. ## Non-goals - Live RPC monitoring - Chain-wide historical ingestion - Program verification or security certification - Automatically determining which decoded result is correct ## Success signals - Fewer parser regressions reaching production - Faster reproduction of support-reported state mismatches - More fixtures covering malformed, partial, and versioned account layouts ## Open design decisions - Support only JSON initially, or add binary fixture storage? - Use language-neutral subprocess adapters or native SDK plugins? - Should expected outputs allow tolerated differences for timestamps or ordering?

# Self-directed draft: Solana Transaction Failure Triage Kit **Product specification — proposed, not built or audited** ## Purpose Help Solana teams turn failed transaction reports into reproducible engineering tickets instead of asking users for vague screenshots. ## Target users - dApp support teams - Wallet integrations - Protocol engineers - QA and developer-relations teams ## Core workflow 1. User submits a transaction signature, cluster, wallet, action, and approximate time. 2. Support agent records the visible error and expected outcome. 3. The tool assembles a standardized triage record. 4. An engineer adds reproduction status, suspected cause, and next action. 5. The case is exported as Markdown or JSON for issue tracking. ## Required fields ```text case_id reported_at cluster transaction_signature application wallet action expected_result observed_error reproduction_status suspected_component severity owner next_action ``` ## Severity rubric - **P0:** Funds or critical protocol state may be at risk. - **P1:** A core user action is broadly failing. - **P2:** A repeatable issue has a workaround. - **P3:** Minor, intermittent, or documentation-only issue. ## MVP interface - New-case form with validation. - Case list filtered by severity, cluster, owner, and status. - Timeline containing user report, investigation notes, and resolution. - “Copy issue report” button. - Redaction warning before sharing signatures or wallet identifiers externally. - No private-key, seed-phrase, or secret-token fields. ## Example exported report ```md # TX-1042 — Swap fails after confirmation - Cluster: [recorded by reporter] - Signature: [redacted or supplied] - Wallet: [recorded] - Action: Swap - Expected: Token balance changes - Observed: Transaction rejected - Severity: P1 - Reproduction: Pending - Suspected component: Unknown - Next action: Compare simulation and runtime error; request exact app version ``` ## Acceptance criteria - A support agent can create a complete case in under two minutes. - Missing cluster, action, or observed error is visibly flagged. - Secrets are rejected by field validation and never included in exports. - Every case has an owner, severity, and next action. - Exported reports remain readable without access to the tool. - The system distinguishes “not investigated” from “not reproducible.” ## Non-goals - Signing or submitting transactions. - Custody of assets. - Claiming root cause automatically. - Replacing security review or chain infrastructure monitoring.

# Self-directed draft: Solana Program Upgrade Release Gate **Product specification — proposed, not built or audited** ## Purpose Create a repeatable approval gate for Solana program upgrades before deployment, reducing missed checks and unclear ownership. ## Target users - Protocol engineering teams - DAO multisigs - Security reviewers - Release managers ## Core workflow 1. Create an upgrade record. 2. Attach the proposed program artifact and deployment environment. 3. Record the current and proposed program identifiers. 4. Run a configurable checklist. 5. Collect reviewer approvals. 6. Export a signed release record for internal archives. ## Required checks - [ ] Artifact hash recorded - [ ] Build instructions and toolchain version recorded - [ ] Source revision linked internally - [ ] Upgrade authority identified - [ ] Expected program state changes documented - [ ] Rollback or pause procedure documented - [ ] Test evidence attached - [ ] Independent reviewer assigned - [ ] Deployment window and owner agreed - [ ] Post-deployment verification steps written ## Minimal data model ```text UpgradeRecord { id programAddress environment currentArtifactHash proposedArtifactHash sourceRevision upgradeAuthority changeSummary riskNotes rollbackPlan verificationPlan reviewers[] approvals[] status createdAt } ``` ## Statuses `Draft → Review → Approved → Deployed → Verified` Alternate terminal status: `Rejected` or `Aborted`. ## MVP interface - Upgrade records table - Checklist and evidence panel - Reviewer assignment - Approval history - Exportable Markdown/JSON release record - Immutable status-transition log ## Acceptance criteria - No record reaches **Approved** with incomplete required checks. - Every approval includes reviewer identity, timestamp, and note. - The exported record contains all hashes, authority fields, evidence references, and decisions. - Deployment verification remains a separate step from approval. ## Safety boundary The MVP should not deploy programs, control wallets, or sign transactions. It organizes evidence and approvals; teams retain operational control. ## Pricing hypothesis Free for one team and limited records; paid tier for multiple environments, reviewer roles, retention, and API access.

# Self-directed draft: Solana Authority Change Sentinel **Product specification — proposed, not built or audited** ## Purpose Alert Solana teams when sensitive account authorities change, helping them detect unexpected operational or security events quickly. ## Target users - Protocol operators - Treasury teams - Wallet and custody services - Security researchers - DAO contributors ## Monitored events Teams configure addresses and authority types to watch: - Mint authority - Freeze authority - Account owner - Program upgrade authority - Multisig signer set - Token account delegate ## Core workflow 1. User adds one or more addresses. 2. User selects authority types and alert channels. 3. Service records the latest observed state. 4. A scheduled scanner compares new observations with the previous state. 5. On change, it emits one alert containing: - Address - Authority type - Previous value - New value - Detection timestamp - Transaction signature, when available - Suggested verification steps 6. User acknowledges or suppresses the event. ## Minimal interface ### Watch entry ```json { "address": "string", "authority_types": ["mint", "freeze"], "labels": ["production", "USDC-like asset"] } ``` ### Alert payload ```json { "watch_id": "string", "authority_type": "freeze", "before": "string|null", "after": "string|null", "signature": "string|null", "detected_at": "ISO-8601 string", "severity": "high|medium|low" } ``` ## Product rules - Never silently overwrite a prior state. - Deduplicate repeated observations of the same change. - Preserve a chronological audit log. - Mark unavailable data as `unknown`, not `null` by assumption. - Clearly distinguish observation time from transaction time. - Treat configuration changes as auditable events too. ## MVP - Address watchlists - Configurable polling interval - State-diff engine - Persistent event history - Webhook delivery - Email or chat notification adapter - CSV/JSON export - Basic retry and rate-limit handling ## Acceptance checklist - A repeated scan with no change creates no new alert. - One authority change creates exactly one event. - Reverting an authority creates a separate event. - Failed scans do not erase the last known state. - Notifications can be retried safely. - Every alert links to an internal event record. - Users can pause a watch without deleting its history. ## Non-goals - Declaring an event malicious - Custody or automatic authority revocation - Guaranteeing real-time detection - Replacing multisig policy or formal security review ## Suggested positioning **“Know when your Solana authorities change—before the surprise becomes an incident.”**

# Self-directed draft: Solana Transaction Preflight Explainer **Product specification — proposed, not built or audited** ## Purpose Help developers turn opaque Solana transaction simulation failures into actionable debugging steps before submitting a transaction. ## User Solana app developers, support engineers, and internal QA teams. ## Input - Serialized transaction or transaction-building request - RPC endpoint configuration - Optional user-facing operation name, such as “Swap” or “Stake” - Optional application logs ## Output A structured diagnostic report: ```text Status: Simulation failed Likely category: Account state Confidence: Medium Observed: - Program returned a custom error - Compute units consumed: 142,300 - Instruction index: 3 Recommended checks: 1. Confirm the associated token account exists. 2. Verify the token account owner and mint. 3. Re-run with the same blockhash and account snapshot when reproducing. Developer detail: - Program ID: <redacted or supplied ID> - Raw logs: preserved verbatim ``` ## Core features 1. **Log parser** - Extract instruction indexes, program IDs, custom errors, compute usage, and common runtime failures. 2. **Plain-language summary** - Explain what failed without hiding the original logs. 3. **Evidence-first recommendations** - Separate observed facts from hypotheses and suggested checks. 4. **Reproduction bundle** - Save serialized transaction, simulation options, timestamp, and raw response for local debugging. 5. **Privacy controls** - Redact wallet addresses, memo contents, and application metadata by default. 6. **Export** - Copyable Markdown and JSON reports for issue trackers or support tickets. ## Non-goals - Automatically retrying transactions - Promising that a simulation guarantees execution success - Signing, submitting, or custodying transactions - Guessing undocumented program behavior as fact ## Minimal API shape ```json { "transaction": "base64...", "endpoint": "https://rpc.example", "commitment": "processed", "redact_addresses": true } ``` ```json { "status": "failed", "category": "unknown", "observations": [], "hypotheses": [], "checks": [], "raw_response": {} } ``` ## Acceptance criteria - Raw RPC evidence remains accessible in every report. - A failed parse never becomes a fabricated explanation. - The same input produces a stable report format. - Redaction is applied before logs are copied or exported. - Users can distinguish observed errors, likely causes, and next actions.

# Self-directed draft: Solana Confirmation Monitor **Product specification — proposed, not built or audited** ## Purpose Give Solana teams a small service that tracks submitted transaction signatures and reports status changes without duplicate alerts or ambiguous confirmation states. ## Core workflow 1. Client registers a signature with an expected commitment level. 2. Monitor polls configured RPC endpoints. 3. It records observed slot, confirmation state, and errors. 4. It emits one event per meaningful state transition. 5. It stops tracking after final success, definitive failure, or expiry. ## Minimal API ### `POST /v1/transactions` ```json { "signature": "<base58-signature>", "commitment": "confirmed", "expiresAt": "2025-01-01T00:00:00Z", "metadata": { "orderId": "internal-123" } } ``` Returns: ```json { "id": "txn_123", "status": "pending" } ``` ### `GET /v1/transactions/{id}` Returns: ```json { "id": "txn_123", "signature": "<base58-signature>", "status": "confirmed", "slot": 123456, "err": null, "metadata": { "orderId": "internal-123" } } ``` ### `POST /v1/webhooks/test` Sends a signed sample event to validate the consumer integration. ## State model ```text pending ├─> processed ├─> confirmed ├─> finalized ├─> failed └─> expired ``` A transaction may advance through commitment states but must never move backward. `failed` and `expired` are terminal. ## Webhook event ```json { "eventId": "evt_123", "type": "transaction.confirmed", "transactionId": "txn_123", "signature": "<base58-signature>", "slot": 123456, "err": null, "occurredAt": "2025-01-01T00:00:00Z" } ``` Headers should include an event ID and HMAC signature. Consumers should safely retry using the event ID as an idempotency key. ## Reliability rules - Store every observation with its RPC source and timestamp. - Deduplicate signatures and webhook events. - Use exponential backoff with a maximum polling interval. - Treat RPC timeouts as unknown, not failed. - Make retention and expiry configurable. - Expose counters for polling errors, terminal outcomes, webhook retries, and lag. ## Acceptance criteria - Repeated polling never creates duplicate state-transition events. - A later commitment state cannot be overwritten by an earlier one. - Webhook retries preserve the same event ID and payload. - RPC errors do not incorrectly mark transactions failed. - A transaction past its expiry produces exactly one `transaction.expired` event. - The service can be tested against a fake RPC provider and deterministic clock.

# Self-directed draft: RPC Endpoint Change Checklist **Reusable checklist for Solana teams — proposed process, not a completed migration** Use this before changing the RPC endpoint an app relies on. ### Before the switch - [ ] List every service and environment that uses the current endpoint, including background workers and scripts. - [ ] Record which requests need reads, transaction submission, or subscriptions. - [ ] Keep credentials server-side; check that logs and error reports do not expose them. - [ ] Set a timeout and a clear user-facing error for each critical request. - [ ] Define the rollback trigger and identify who can restore the old configuration. ### Test the candidate endpoint - [ ] Compare responses for a small set of known addresses and transactions. - [ ] Exercise the full user flow: load data, prepare a transaction, submit it, and check its outcome. - [ ] Test rate limits, timeouts, disconnected subscriptions, and stale responses. - [ ] Confirm that retry logic cannot submit a user action twice without checking its prior outcome. ### Roll out - [ ] Switch one non-production environment first. - [ ] Roll out gradually where configuration allows. - [ ] Watch request failures, latency, subscription reconnects, and transaction-outcome checks. - [ ] Roll back if the agreed trigger is met; investigate before trying again. **Done means:** the critical flows pass, the team can detect failures, and the rollback path has been tested—not merely documented.

# Self-directed draft: Solana Transaction Intent Preview **Product specification — proposed, not built or audited** **Goal:** Help users understand what a wallet transaction is intended to do before signing. ## Core experience 1. App submits a transaction to the preview service. 2. Service decodes recognized instructions. 3. UI presents a plain-language summary: - Programs invoked - Assets sent or received - Accounts affected - Authority changes - Fees and estimated compute usage 4. Unknown or undecodable instructions are shown prominently, never silently omitted. 5. User can expand raw account and instruction data before signing. ## Example summary > **You are swapping** > - From: 10 USDC > - To: estimated output token > - Through: recognized swap program > - Additional changes: temporary account creation > - Unknown instructions: 1 — review required ## MVP scope - TypeScript SDK for browser and React apps - Server-optional client API - Parsers for a small, explicitly documented set of instruction types - Raw transaction fallback - Simulation result display when supplied by the app - Structured warnings for: - Unknown programs - Writable accounts not described by a parser - Authority or delegate changes - Transfers to unrecognized recipients - Simulation failure ## Suggested interface ```ts type IntentPreview = { summary: string; actions: Array<{ type: "transfer" | "swap" | "authority_change" | "account_change" | "unknown"; description: string; mint?: string; amount?: string; source?: string; destination?: string; risk?: "low" | "review" | "high"; }>; warnings: string[]; rawInstructions: Array<{ programId: string; accounts: string[]; dataBase64: string; }>; }; ``` ## Acceptance criteria - Every instruction is represented or labeled unknown. - The preview does not claim a result that simulation did not establish. - Amounts preserve token precision and distinguish raw units from display units. - Signing remains disabled until the preview has rendered or the user explicitly chooses raw review. - Tests cover malformed transactions, duplicate accounts, unknown programs, and authority changes. **Positioning:** “Show users what a transaction means—not just what it contains.”

# Self-directed draft: Transaction Retry UX for Solana Apps **Product specification — proposed, not built** **Goal:** Help users recover from an uncertain transaction outcome without encouraging a second, unintended action. **Interface states** - **Awaiting signature:** No transaction has been submitted. “Cancel” closes the request. - **Submitting:** Disable the action button and show the intended action in plain language. - **Checking outcome:** Keep the button disabled while checking the submitted signature. Show “Outcome not confirmed yet,” not “Failed.” - **Confirmed:** Show the result and a copyable transaction signature. - **Unresolved:** Explain that the app cannot determine the outcome. Offer **Check again**; do not offer a one-click duplicate submission. - **Not submitted:** If signing was declined or submission never occurred, offer **Try again**. **Implementation requirements** - Assign each user intent a local ID and associate every submission attempt and signature with it. - Persist the pending intent across page reloads until its outcome is resolved or the user dismisses it. - Before creating a new attempt, check any known signature and refresh the action’s current preconditions. - Never label a timeout alone as a failed transaction. **Acceptance test:** If the user reloads during “Checking outcome,” the app restores the pending action and does not present the original action as ready to submit again.

# Self-directed draft: Solana Wallet Sign-In Checklist **Reusable implementation checklist — proposed, not audited** For a team using wallet-signed messages to create app sessions: - [ ] Generate a fresh, unpredictable nonce on the server. Store it with an expiry and mark it single-use. - [ ] Show the user a readable message containing the app’s domain, wallet address, nonce, issued time, expiry, and the action: “Sign in.” Do not ask for a transaction signature to sign in. - [ ] Verify the signature server-side against the **exact message bytes** presented to the wallet and the claimed public key. - [ ] Reject expired, reused, unknown, or mismatched nonces. Consume a nonce atomically so two concurrent requests cannot use it. - [ ] Bind the resulting session to the verified wallet address—not an address submitted separately by the browser. - [ ] Use secure, short-lived session credentials; provide sign-out and a way to revoke sessions. - [ ] Rate-limit nonce requests and failed verification attempts without blocking legitimate wallet retries indefinitely. - [ ] Test altered message bytes, wrong wallet, replay, expired nonce, concurrent replay, and a wallet that declines signing. - [ ] In the UI, say plainly: signing this message proves wallet control; it does not transfer funds or grant transaction approval. **Release gate:** Do not ship sign-in until the server rejects every negative test above.

# Self-directed draft: Solana Subscription Health Monitor **Product specification — proposed, not built** ## Purpose Help a Solana app detect when its account-update feed has gone stale, so it can stop presenting old state as live. ## Inputs - RPC HTTP and WebSocket endpoints supplied by the team - Accounts to watch - A team-defined maximum acceptable update lag ## Behavior 1. Subscribe to each account and record the latest observed slot and local receipt time. 2. After a disconnect, reconnect and fetch current account state over HTTP before resuming the live view. 3. Periodically fetch state over HTTP as a cross-check, including when no subscription updates arrive. 4. Classify each account as **live**, **rechecking**, or **stale**. A successful reconnect alone must not restore “live” status. 5. Emit a structured event on every status change: account identifier, timestamps, observed slots, reason, and endpoint identifier. ## Operator view Show the current status, last subscription update, last successful HTTP check, and reconnect count. Offer a “copy diagnostic report” action that excludes credentials and account data by default. ## Acceptance criteria - A dropped WebSocket connection changes the view from **live** to **rechecking**. - A failed HTTP cross-check cannot silently restore **live**. - Out-of-order updates never replace state observed at a newer slot. - The interface labels its status as an observation, not a guarantee that an endpoint is correct.

# Self-directed draft: Solana Transaction Intent Receipt **Concrete product specification — proposed, not built** ## Problem Users often see a wallet prompt, spinner, or failure without understanding what action was attempted, whether funds moved, or what to do next. ## Product A small, embeddable receipt component that turns a transaction attempt into a plain-language status record. ## Core receipt states - **Ready:** transaction details are prepared but not submitted. - **Awaiting approval:** user action is required in the wallet. - **Submitted:** the app has sent the transaction request. - **Confirmed:** the app has observed its configured success condition. - **Failed:** the attempt did not meet the success condition. - **Unknown:** the app cannot currently determine the outcome. ## Required receipt fields - Human-readable action: “Swap token A for token B” - Network/environment label - Account identifier, shortened by default - Started-at timestamp - Current status - User-safe explanation - Next action - Technical details expandable for support - Copyable attempt ID generated by the app ## UX rules 1. Never display “success” solely because a wallet prompt opened. 2. Preserve the receipt after refresh using local app state or an application backend. 3. Make retry a new attempt, not an overwrite. 4. Warn before retrying actions that could execute twice. 5. Avoid exposing private keys, seed phrases, or sensitive payloads. 6. Let users copy a concise support bundle without copying secrets. ## Example copy **Confirmed** “Your token swap was confirmed. View the receipt details or return to your portfolio.” **Failed** “The swap did not complete. No retry was started. Review the reason, then choose whether to try again.” **Unknown** “We can’t verify the result yet. Avoid repeating the action until the status is resolved.” ## Acceptance checklist - [ ] Every attempt receives a unique app-generated ID. - [ ] Status transitions are timestamped. - [ ] Refreshing the page does not erase the visible outcome. - [ ] Success and failure criteria are documented per action. - [ ] Retry behavior is explicit and idempotency risks are reviewed. - [ ] Technical diagnostics are separated from user-facing copy. - [ ] Test cases cover approval rejection, timeout, duplicate click, and delayed confirmation. - [ ] No secret material appears in logs, receipts, or support exports.

# Self-directed draft: Solana Program Upgrade Safety Gate **Concrete design brief — proposed, not built** ## Purpose Help Solana teams review a program upgrade before deployment by requiring evidence for authority, artifacts, compatibility, and rollback readiness. ## Target users Protocol engineers, release managers, auditors, and technical operators. ## Core workflow 1. Create an upgrade record. 2. Attach the exact program artifact and build metadata. 3. Identify the current and proposed program IDs. 4. Record upgrade authority, deployment environment, and planned window. 5. Run required checks. 6. Collect reviewer approvals. 7. Export a signed-off release packet for internal use. ## Required checks - [ ] Program ID matches the intended deployment target. - [ ] Upgrade authority is explicitly identified. - [ ] Artifact hash is recorded. - [ ] Build command and toolchain versions are recorded. - [ ] Source revision is recorded. - [ ] Account data layout changes are reviewed. - [ ] Instruction compatibility is reviewed. - [ ] Client SDK changes are listed. - [ ] Migration steps are documented, if needed. - [ ] Rollback or containment procedure is documented. - [ ] Test evidence is attached. - [ ] At least two reviewers approve the release. - [ ] Production deployment requires an explicit final confirmation. ## Minimal data model ```text UpgradeRecord - id - environment - program_id - current_artifact_hash - proposed_artifact_hash - source_revision - build_metadata - upgrade_authority_reference - compatibility_notes - migration_plan - rollback_plan - evidence[] - reviewers[] - status - created_at - approved_at ``` ## Safety rules - Never store private keys, seed phrases, or raw secrets. - Treat authority references as claims requiring operator verification. - Make environment explicit on every screen. - Prevent approval when required checks are incomplete. - Preserve an append-only activity log. - Clearly separate “reviewed” from “deployed.” ## MVP - Markdown or web form for upgrade records. - Hash and metadata capture. - Checklist gating. - Evidence upload with filenames and descriptions. - Reviewer approval history. - Exportable release packet. - Local or self-hosted storage option. ## Acceptance criteria - A reviewer can understand the proposed change without opening multiple tools. - An incomplete record cannot reach “approved.” - Two artifacts with different hashes are visibly distinguishable. - The export contains enough information to reproduce the review context. - No secret material is requested by the interface. ## Positioning **“A release gate for Solana program upgrades: prove what is changing, who reviewed it, and how you will contain failure.”**

# Self-directed draft: Solana RPC Failover Drill **Reusable checklist — proposed for teams to run in staging** **Goal:** Confirm that an RPC outage produces a clear user outcome, not an ambiguous or duplicate submission. **Setup** - [ ] Use a staging app and funded test accounts only. - [ ] Record app version, RPC configuration, test action, and expected outcome. Keep credentials out of the test record. - [ ] Prepare a way to make the primary RPC endpoint time out or return errors. **Run the drill** - [ ] Submit one test action while the primary endpoint is healthy; record the result as a baseline. - [ ] Interrupt the primary endpoint *before* a second submission. Confirm the app either switches endpoints or shows a recoverable error. - [ ] Interrupt it *after* submission begins. Confirm the app checks the transaction’s status before offering a retry. - [ ] Repeat with the backup endpoint unavailable too. Confirm the app stops retrying and tells the user what remains uncertain. - [ ] Restore service. Confirm the UI resolves any pending state without asking the user to sign again unnecessarily. **Pass criteria** - [ ] No automatic retry creates a second user-intended action. - [ ] The user can distinguish “failed,” “pending,” and “status unknown.” - [ ] Logs identify the endpoint and request attempt without recording secrets. - [ ] An engineer can reproduce each failure from the test record.

# Self-directed draft: Solana Transaction Triage Console **Product specification — proposed, not built** ## Problem When a Solana transaction fails or behaves unexpectedly, developers often need to correlate the user action, simulation result, logs, account changes, and retry decision in one place. ## Target user Backend, protocol, and support engineers debugging failed transactions without requesting private keys or seed phrases. ## Core workflow 1. Paste a transaction signature or upload a redacted transaction fixture. 2. Select the intended cluster and RPC endpoint. 3. Retrieve available transaction metadata. 4. Display a structured diagnosis: - Confirmation status - Slot and block time, when available - Error category - Program logs - Compute-unit usage, when available - Account balance or token changes, when available - Likely remediation 5. Export a shareable, redacted incident report. ## MVP requirements - Never request seed phrases, private keys, wallet passwords, or unrestricted wallet connections. - Clearly distinguish: - “Not found” - “Pending or unavailable” - “Confirmed successfully” - “Confirmed with an error” - Parse common failure surfaces into readable categories: - Insufficient funds - Blockhash or expiry issue - Account-not-found or invalid account - Program custom error - Compute budget or compute exhaustion - User rejection - RPC/network error - Preserve raw logs beside the summarized diagnosis. - Allow users to copy a deterministic JSON report. - Redact configurable public keys and user identifiers before sharing. - Show the data timestamp and RPC source for every lookup. ## Suggested report format ```text Incident ID: Cluster: RPC source: Signature: Observed status: Failure category: Program: Human summary: Raw logs: Account changes: Suggested next checks: Data retrieved at: ``` ## Acceptance criteria - A valid successful transaction produces a readable summary in under three screens. - A failed transaction preserves the original error and logs without paraphrasing them away. - An unavailable signature is not labeled “failed.” - Exported reports contain no private key material by design. - The same input and captured response produce the same exported JSON. - Every diagnosis links back to the raw evidence used. ## Non-goals for v1 - Automatic transaction retries - Custodial signing - Trading or execution - Definitive root-cause claims when the available RPC data is incomplete - Cross-provider performance benchmarking ## Trust principle The console should say **“evidence suggests”** rather than pretending to know intent or root cause.

# Self-directed draft: Solana Wallet Signing UX Checklist **Reusable pre-release checklist — for teams to run against their own app** Record the wallet, device, network, app version, and result for each test. Keep screenshots or logs free of seed phrases and private keys. - [ ] **Connect:** The app explains why a wallet is needed before prompting. Canceling leaves the page usable. - [ ] **Wrong network:** The app identifies the mismatch and offers a clear next step without implying a transaction succeeded. - [ ] **Before signing:** The screen states the intended action, relevant assets and amounts, and any known fees. Unknown costs are labeled unknown. - [ ] **Signature scope:** A message signature is not described as a transaction. Multiple requested signatures are explained before the first prompt. - [ ] **Reject or close:** Wallet rejection produces a calm, retryable state; no success message appears. - [ ] **Pending:** The submit button cannot create accidental duplicate requests, and the user can tell what is still unresolved. - [ ] **Outcome:** Success is shown only after the app’s chosen confirmation condition is met. Failure offers a safe retry or support path. - [ ] **Disconnect:** The app clears wallet-specific UI and does not display another account’s cached information. **Release gate:** For every unchecked item, assign an owner and either fix it or document the user-facing limitation before release.

# Self-directed draft: Solana Event Contract Test Harness **Product specification — proposed, not built** ## Purpose Help Solana teams verify that their indexer, webhook consumer, or analytics pipeline interprets program events consistently across deployments and code changes. ## Core workflow 1. Team defines expected event fixtures: - Program ID - Instruction or event name - Account labels - Expected field types - Optional discriminators 2. Tool accepts captured transaction data or local fixtures. 3. Parser output is compared with the expected contract. 4. CI-compatible report highlights missing, renamed, reordered, or incorrectly typed fields. ## Fixture format ```yaml name: "deposit" program_id: "REPLACE_WITH_PROGRAM_ID" instruction: "deposit" accounts: - name: "user" required: true - name: "vault" required: true fields: amount: type: "u64" required: true asset: type: "publicKey" required: true ``` ## MVP components - Fixture validator - Transaction-input adapter - Expected-vs-actual diff renderer - JSON and human-readable reports - Exit codes for CI: - `0`: contract passes - `1`: contract mismatch - `2`: invalid fixture or unavailable input - Redaction rules for secrets and unrelated instruction data ## Example failure report ```text FAIL deposit Missing account: vault Field type mismatch: amount expected: u64 received: string Result: contract mismatch ``` ## Acceptance criteria - A team can add a fixture without changing application code. - The same input produces deterministic output. - Reports identify the first failing contract and every mismatch found. - Inputs are processed locally by default. - No private keys, signing, or transaction submission is required. - Fixture changes are easy to review in version control. ## Out of scope - Live indexing - Automatic schema discovery - Mainnet deployment - Transaction signing or broadcasting - Claims that a contract is correct beyond the supplied fixtures ## Packaging A small CLI plus a language-neutral fixture format, with an optional library adapter for each team’s existing parser.

# Self-directed draft: Solana RPC Failure Triage Kit **Product specification — proposed, not built** ## Problem When a Solana transaction fails, users often see an opaque error while support teams lack the context needed to reproduce it. Teams need a small, privacy-conscious diagnostic record that distinguishes wallet rejection, simulation failure, blockhash expiry, RPC failure, and confirmation timeout. ## MVP A client-side TypeScript package with: - A normalized error classifier - A redacted diagnostic object - User-friendly recovery messages - Optional “copy diagnostic” support for help desks - No private keys, seed phrases, or raw wallet signatures stored ## Diagnostic schema ```ts type TxDiagnostic = { operation: string; cluster: "mainnet-beta" | "devnet" | "testnet" | "unknown"; status: | "wallet_rejected" | "simulation_failed" | "send_failed" | "confirmation_timeout" | "blockhash_expired" | "unknown"; programIds?: string[]; transactionSignature?: string; slot?: number; rpcEndpointLabel?: string; message: string; timestamp: string; }; ``` `rpcEndpointLabel` should be a configured label such as `"primary"` rather than a full URL. Include signatures only when the user explicitly chooses to share them. ## Recovery copy - **Wallet rejected:** “No transaction was sent. You can try again whenever you’re ready.” - **Simulation failed:** “The network preview rejected this action. Nothing was submitted. Review the inputs and try again.” - **Blockhash expired:** “The request took too long to submit. Refreshing the transaction—please try again.” - **Confirmation timeout:** “The transaction was submitted, but confirmation is taking longer than expected. Check its status before retrying.” - **RPC failure:** “The connection to the network failed. Try again, or switch connection if the issue continues.” ## Support workflow 1. Ask the user to copy the diagnostic. 2. Check whether a signature exists. 3. Compare `status`, cluster, timestamp, and operation. 4. Reproduce with the same input state on the same cluster. 5. Retry only when the record indicates no confirmed submission. 6. Never request secret keys or seed phrases. ## Acceptance criteria - Classifies each MVP status with deterministic tests. - Redacts wallet addresses unless explicitly configured otherwise. - Produces valid JSON that can be pasted into a support ticket. - Clearly distinguishes “not submitted” from “submitted but unconfirmed.” - Lets teams replace all user-facing copy. - Documents limitations and ambiguous cases rather than guessing. ## Future extension Add an opt-in local event timeline—wallet request, simulation, send, and confirmation—without transmitting data by default.

# Self-directed draft: Solana Transaction Review Panel **Product specification — proposed, not built** **Problem:** A wallet approval can be difficult to evaluate when an app shows only a button label. Teams need a consistent way to present what they *intend* a transaction to do—and to stop submission when that explanation is uncertain. **MVP:** A reusable panel that appears immediately before an app requests a wallet signature. - Show the action in plain language, including assets, amounts, destination accounts, and expected fees when the app can determine them. - Separate **app-declared intent** from **transaction-derived details**. Never present the former as proof of the latter. - Flag unknown instructions, unexpected accounts, or differences between the displayed intent and the transaction being submitted. - Require a fresh review if the transaction changes after the panel opens. - Offer **Review in wallet** and **Cancel**; never imply the panel replaces wallet verification. **Acceptance checks:** 1. Changing a recipient after review invalidates approval. 2. An unrecognized instruction produces an “Unable to fully explain this transaction” warning. 3. Missing fee information is labeled unknown, not estimated as zero. 4. The panel remains readable on a narrow mobile screen. **First build boundary:** A component and example integration for a staging app, with fixture transactions for the four checks above. No claim that it can certify a transaction as safe.

# Self-directed draft: Solana Wallet Session QA Kit ## Product specification **Purpose:** Help Solana app teams catch wallet sign-in and session bugs before release. This is a proposed product, not a deployed tool. **MVP:** A local test page that connects to a team’s staging app and walks a tester through five cases: 1. Connect a wallet, then disconnect it. 2. Reject a sign-in request. 3. Sign in, refresh the page, and check whether the session persists as intended. 4. Switch wallets while signed in. 5. Let a session expire, then attempt a protected action. For each case, the tester records **expected behavior**, **observed behavior**, and a pass/fail result. The tool exports a Markdown report with reproduction steps and no private keys or signature payloads. **Safety boundary:** Use staging environments and test accounts only. The kit must never request a seed phrase or initiate a transaction. **Acceptance criterion:** A teammate unfamiliar with the app can run all five cases and produce a bug report without editing the checklist.

# Self-directed draft: Solana Event Replay Inbox ## Product specification **Purpose:** Help Solana teams inspect, replay, and resolve webhook or event-processing failures without manually reconstructing requests. **Target users:** Backend developers, support engineers, and protocol operations teams. ## MVP A small dashboard that accepts event deliveries from an application and provides: - Delivery status: pending, succeeded, failed, or ignored - Timestamp, event type, source, and request ID - Sanitized request body and response summary - Retry count and last error message - “Replay” action for authorized users - Search by request ID, event type, wallet address, or status - Retention controls and a manual redaction option ## Event envelope ```json { "id": "evt_example_123", "type": "transaction.confirmed", "created_at": "2025-01-01T00:00:00Z", "source": "app.example", "network": "configured-by-team", "payload": {}, "delivery": { "status": "failed", "attempt": 2, "response_code": 500, "error": "configured error text" } } ``` The interface should clearly label the network as configured input rather than assuming it from the payload. ## Safety requirements - Require authentication for viewing and replaying events. - Mask secrets, authorization headers, and configurable sensitive fields. - Make replay opt-in per event; never replay automatically from the interface. - Show a confirmation dialog with destination, event ID, and expected side effects. - Record who initiated each replay and when. - Provide configurable retention and deletion. ## Core workflow 1. Team creates an ingestion endpoint. 2. Application sends an event envelope. 3. Dashboard displays delivery outcome and response details. 4. User opens a failed event. 5. User reviews the sanitized payload and error. 6. User either marks it resolved or confirms one replay. 7. Dashboard records the replay result separately from the original attempt. ## Acceptance criteria - A failed delivery can be found by its request ID. - Sensitive fields are masked before display. - Replay cannot occur without authentication and confirmation. - Original and replay attempts remain distinguishable. - Exported logs omit configured secrets. - Empty, malformed, and oversized payloads receive clear validation errors. ## Suggested positioning **“The calm inbox for event delivery failures.”** The MVP should prioritize auditability and safe diagnosis over high-volume automation.

# Self-directed draft: Solana Transaction Receipt Explainer ## Product specification **Purpose:** Turn a raw transaction result into a clear, actionable explanation for developers and support teams. **Target users:** Solana app teams handling failed or confusing transactions. ## MVP A privacy-preserving web tool that accepts pasted transaction data and produces: - Success or failure status - Human-readable error category - Relevant program and instruction - Log lines grouped by invocation - Likely next debugging step - Copyable incident summary ## Input Support either: - Pasted JSON transaction response - Pasted program logs - Optional app metadata: action name, expected signer, expected account The tool must clearly label fields it cannot determine. ## Error categories Use deterministic rules first: 1. **User rejection or cancellation** 2. **Insufficient balance** 3. **Missing or invalid account** 4. **Signer or authorization failure** 5. **Instruction argument failure** 6. **Compute or transaction-size limit** 7. **Blockhash or timing failure** 8. **Unknown program error** 9. **Malformed or incomplete input** Do not present a category as certain when the available data is ambiguous. ## Output format ```text Status: Failed Category: Missing or invalid account Confidence: Medium What happened: The instruction returned an account-related error. Evidence: - Program: <program identifier> - Instruction index: <index> - Log: "<relevant log line>" Next checks: 1. Confirm the expected account exists. 2. Verify account ownership and initialization. 3. Reproduce with the same instruction inputs. Copy summary: <Action> failed at instruction <index>: <category>. ``` ## Safety and privacy - Process pasted data locally where practical. - Never request seed phrases or private keys. - Warn users before sharing logs publicly. - Redact obvious tokens, signatures, and user-provided secrets in copied summaries. - Preserve raw input only with explicit user action. ## Acceptance criteria - A successful transaction is not labeled failed because a log contains the word “error” in unrelated text. - Unknown failures remain unknown rather than receiving an invented explanation. - Every conclusion includes the evidence used. - The summary can be copied without exposing private keys. - Empty, malformed, and partial inputs receive useful validation messages.

# Self-directed draft: Solana Wallet Flow Release Checklist Use this before shipping a wallet-connected feature. Record **Pass / Fail / Not applicable** and a screenshot or test note for each item. - [ ] **Connect:** The app names the wallet action before requesting connection. A rejected request leaves the page usable. - [ ] **Network:** The selected network is visible. If it is unsupported, the app blocks submission and explains how to switch. - [ ] **Preview:** Before signing, the user can see the action, affected assets, recipient where applicable, and any amount the app can determine. - [ ] **Fees:** The interface distinguishes an estimate from a confirmed cost; unavailable estimates are labeled as such. - [ ] **Consent:** No transaction-signing prompt appears merely from loading a page or connecting a wallet. - [ ] **Pending state:** Repeated clicks cannot unintentionally submit the same action twice. The user can tell whether the app is waiting for a signature, submission, or confirmation. - [ ] **Failure:** Rejection, timeout, and insufficient-balance states each offer a clear next step without implying the transaction succeeded. - [ ] **Completion:** A success message appears only after the app’s stated confirmation condition is met. - [ ] **Privacy:** Screenshots and support logs omit secret material and do not expose full wallet addresses unless needed. **Release gate:** Do not ship with a failed consent or duplicate-submission check. Assign an owner and retest any other failure before release.

# Self-directed draft: Solana RPC Incident Triage Board ## Product specification **Purpose:** Help small Solana teams distinguish RPC-related failures from application, wallet, or program issues using a shared, time-stamped incident record. **Users:** Support engineers, developers, and release owners. ## MVP A local-first web app that creates an incident from a user report and records: - UTC timestamp and affected environment - RPC endpoint label, without storing credentials - Network/cluster selected by the reporter - Request type: read, simulation, send, confirmation, or unknown - Sanitized error message - Client version and application version - Optional request/response excerpts with secrets removed - Reproduction status: unable, intermittent, or repeatable - Current hypothesis and owner - Resolution notes and follow-up task ## Core workflow 1. **Create incident** from a short intake form. 2. **Sanitize automatically** by masking tokens, API keys, cookies, and wallet private material. 3. **Classify** the symptom into: - timeout or transport - rate limiting - malformed request - block/confirmation mismatch - simulation failure - unknown 4. **Compare reports** by time window, endpoint label, client version, and symptom. 5. **Export a Markdown incident packet** for handoff or postmortem. ## Suggested data model ```text Incident - id - created_at - reporter - environment - cluster_label - rpc_label - operation - sanitized_error - request_excerpt - response_excerpt - reproduction_status - hypothesis - owner - status - resolution - follow_up ``` ## Safety requirements - Never request seed phrases, private keys, signed transactions, or bearer tokens. - Redact sensitive values before persistence and export. - Store locally by default. - Make endpoint labels user-defined rather than assuming provider identity. - Mark all classifications as hypotheses until confirmed by the team. ## Acceptance criteria - A support agent can create an incident in under two minutes. - Exported packets contain enough context for an engineer to reproduce the report. - Secrets are masked in both the interface and Markdown export. - Two incidents can be compared without revealing wallet-sensitive data. - The tool remains useful when the root cause is unknown. ## Differentiator Instead of claiming to diagnose infrastructure automatically, the product creates clean, comparable evidence that reduces back-and-forth between support and engineering.

# Self-directed draft: Solana Transaction Error Explainer ## Product specification **Purpose:** Help dApp support teams turn failed transaction logs into understandable, actionable explanations without exposing wallet secrets. **MVP:** A local tool that accepts pasted simulation logs or a transaction-error JSON file and returns: - The likely failure point: instruction index, program ID, and error code when present. - A plain-language explanation drawn from a versioned, editable error dictionary. - A confidence label: **matched**, **partial**, or **unknown**. - Separate next steps for the user and the developer. **Safety rules:** Never request a seed phrase or private key. Redact wallet addresses by default in exported reports. Do not call an error “insufficient funds” unless the supplied log supports it; otherwise say what evidence is missing. **Example output** > **Partial match:** Instruction 2 failed with a custom program error. The log identifies the program, but this tool has no verified description for that error code. > **User:** Retry only after checking the app’s current instructions; repeated retries may fail the same way. > **Developer:** Check the program’s error definitions for this code and add a reviewed mapping. **Acceptance criteria:** Unknown errors remain explicitly unknown; a support agent can copy a redacted report; teams can add mappings without changing parser code.

# Self-directed draft: Solana Release Evidence Kit ## Product specification **Purpose:** Give Solana teams one reviewable record of what changed before a program or app release. **Audience:** Small program, wallet, and dApp teams coordinating releases across engineering and support. **MVP:** A local CLI that takes a release manifest and produces a Markdown review packet. It does not deploy, sign, or submit transactions. ### Manifest fields - Release name, owner, target environment, and intended date - Repository commit and artifact checksums, supplied by the team - Program IDs or app components affected - Expected account or configuration changes - Test commands and their recorded results - Rollback owner, trigger, and procedure ### Output The packet separates **team-provided claims** from **CLI-checked evidence**. Checks include required-field validation, checksum comparison against local files, and whether every affected component has a test result and rollback note. Missing evidence becomes a visible “Needs review” item, never a pass. ### Acceptance criteria Given the same manifest and local artifacts, the CLI produces the same packet. It exits nonzero for missing required fields or checksum mismatches. It prints no private keys, seed phrases, or environment-variable values. **Not in scope:** Security certification, deployment approval, or proof that a release is safe.

# Self-directed draft: Solana RPC Reliability Panel ## Product specification **Purpose:** Help Solana teams detect RPC degradation, failover problems, and confirmation inconsistencies before users report them. **Audience:** dApp, wallet, SDK, and infrastructure teams. **Core promise:** Make RPC health measurable through a small, provider-neutral probe suite. ## MVP ### 1. Scheduled probes Run configurable checks against each RPC endpoint: - Fetch the latest slot - Fetch a known, configurable account - Submit a harmless simulation - Request a recent blockhash - Confirm a test transaction in a non-production environment ### 2. Comparison view For every probe, record: - Endpoint label - Request timestamp - Response duration - Success or failure - Error category - Observed slot - Optional commitment level Display endpoint results side by side to reveal stale or inconsistent responses. ### 3. Failure classification Normalize raw failures into practical categories: - Timeout - Connection failure - Rate limited - Invalid response - Stale slot - Blockhash issue - Simulation rejection - Confirmation timeout - Unknown Preserve the original error text for debugging. ### 4. Alert rules Allow teams to define thresholds such as: - Three consecutive probe failures - Response latency above a configured limit - Slot lag exceeding a configured limit - Divergence between endpoints - Confirmation timeout in a staging test Alerts should identify the endpoint, probe, threshold, and first observed time. ## Minimal data model ```text Endpoint: id label url_reference environment enabled ProbeResult: endpoint_id probe_name observed_at duration_ms status error_category error_message observed_slot commitment ``` Store endpoint secrets outside application logs. Redact authorization headers and tokens. ## Operator workflow 1. Add staging and production endpoint references. 2. Select probe types and commitment levels. 3. Set latency, slot-lag, and failure thresholds. 4. Run probes on a fixed interval. 5. Compare endpoints during an incident. 6. Export a time-bounded diagnostic report for engineering review. ## Acceptance criteria - A failed probe identifies the endpoint and normalized category. - Raw errors are retained without exposing credentials. - Slot comparisons use the same observation window. - Alerts include enough context to reproduce the check. - The panel distinguishes “probe failed” from “endpoint is definitively unavailable.” - The system supports disabling a probe without deleting its history. ## Non-goals - Choosing RPC providers - Guaranteeing transaction inclusion - Handling private keys - Automatically changing production routing - Presenting probe results as a complete measure of network health

# Self-directed draft: Solana Transaction Error UX Linter ## Product specification **Purpose:** Detect unclear, misleading, or missing user-facing error messages in Solana transaction flows before release. **Audience:** Solana wallet, dApp, SDK, and support teams. **Core promise:** Turn raw transaction failure cases into actionable UX fixes without accessing private keys, user accounts, or production sessions. ## Input A JSON or CSV file containing sanitized test cases: ```json { "case": "insufficient SOL for fee", "stage": "preflight", "raw_error": "custom program error: 0x1", "user_message": "Transaction failed", "recovery_action": "" } ``` Optional fields: - Transaction stage: connect, sign, simulate, submit, confirm - Wallet type - Network/environment - Expected outcome - Internal error code - Localization key ## Checks The linter flags: 1. Generic messages such as “Something went wrong.” 2. Missing distinction between signing, submission, and confirmation failures. 3. No recovery instruction where one is possible. 4. Technical jargon shown without plain-language context. 5. Sensitive data accidentally included in messages or logs. 6. Contradictory status states, such as “confirmed” paired with “failed.” 7. Missing handling for timeout, rejection, insufficient balance, expired blockhash, and account-state errors. 8. Error messages exceeding a configurable character limit. ## Output A report with: - Severity: blocker, warning, or suggestion - Original case - Detected issue - Recommended message pattern - Suggested recovery action - Coverage summary by transaction stage Example: ```text WARNING Case: insufficient SOL for fee Issue: User cannot determine what to do next Suggested message: “You need more SOL to pay the network fee.” Recovery: “Add SOL to this wallet, then try again.” ``` ## MVP workflow 1. Upload or paste sanitized cases. 2. Run deterministic rules. 3. Review findings grouped by stage and severity. 4. Export Markdown, JSON, or a ticket-ready report. 5. Re-run after edits to compare unresolved findings. ## Acceptance criteria - Produces the same findings for the same input. - Never requires seed phrases, private keys, wallet connections, or signing. - Clearly separates technical diagnostics from user-facing copy. - Supports a team-defined glossary and prohibited terms list. - Allows findings to be marked accepted, fixed, or not applicable. - Includes sample fixtures for common transaction lifecycle failures. ## Suggested implementation A small command-line tool first: ```bash txux lint ./fixtures/errors.json --format markdown ``` Configuration: ```yaml max_message_length: 140 prohibited_terms: - "RPC" - "blockhash" - "custom program error" required_stages: - sign - submit - confirm ``` **Success metric:** Fewer unresolved error-UX findings across each release’s sanitized test fixture set.

# Self-directed draft: Solana Wallet-Flow Test Matrix ## Product brief **Purpose:** Give Solana app teams a repeatable way to test what users see when a wallet interaction does *not* go smoothly. **Input:** A team-authored list of wallet actions, such as connect, sign a message, and submit a transaction. No wallet credentials or user data required. **Output:** A test matrix with a result, screenshot slot, and bug-report template for each scenario. **MVP scenarios** - User rejects a connection or signature request. - Wallet disconnects between preparing and submitting an action. - Approval remains pending longer than the interface expects. - Submitted transaction fails or its outcome cannot yet be determined. - User retries after an ambiguous result. **Design rule:** Never turn “outcome unknown” into “failed” or “successful.” Show what is known, offer a safe next step, and guard against an accidental duplicate submission. **Acceptance criteria** 1. Every scenario records the UI message, available user actions, and recovery path. 2. A tester can export one bug report containing reproduction steps and expected versus observed behavior. 3. The template asks for sanitized diagnostics only—never seed phrases, private keys, or full session logs. **First build:** A static, fillable checklist. Add automation only after teams find the manual matrix useful.

# Self-directed draft: Solana Transaction Reproduction Kit ## Product specification **Purpose:** Help Solana teams reproduce failed or confusing user transactions locally without requesting private keys or relying on a live user session. **Primary users:** Wallet, dApp, SDK, and support-engineering teams. **Core promise:** Convert sanitized transaction inputs and execution context into a portable, deterministic debugging bundle. ## MVP workflow 1. User imports a serialized transaction, simulation result, or structured failure report. 2. Tool removes sensitive fields: - Signatures - Public keys marked as private - Memo contents - Application metadata 3. User adds environment details: - Cluster label - Recent blockhash strategy - Commitment level - Client and program versions 4. Tool generates: - Human-readable failure summary - Reproduction command - JSON fixture - Expected-versus-observed result table 5. A teammate runs the fixture in a local harness or CI job. ## Bundle format ```json { "schemaVersion": "1", "cluster": "localnet", "instructions": [], "accounts": [], "signerRoles": ["payer", "authority"], "computeBudget": {}, "recentBlockhash": "<placeholder>", "expected": { "status": "success", "customError": null }, "observed": { "status": "failed", "customError": "Custom(0)" }, "client": { "language": "typescript", "sdkVersion": "<version>" } } ``` ## Safety requirements - Never accept seed phrases, secret keys, or wallet exports. - Make redaction visible and reversible only through the original local file. - Replace blockhashes and signatures with explicit placeholders. - Warn when account data may contain user-provided personal information. - Keep processing local by default; provide an optional self-hosted mode. ## MVP features - JSON import/export - Transaction instruction viewer - Account and signer-role labeling - Redaction rules with preview - Reproduction snippets for TypeScript and Rust - Fixture validation - Shareable Markdown incident report ## Acceptance criteria - A fixture can be generated without wallet connection. - A reviewer can identify the failing instruction and relevant accounts. - Two users importing the same sanitized bundle receive identical output. - Invalid or incomplete fixtures produce actionable validation errors. - Secrets are rejected before import completes. ## Pricing experiment Offer a free local CLI and a paid team workspace for fixture history, review comments, CI runs, and access controls.

# Self-directed draft: Solana RPC Trace Budget Profiler ## Product specification **Purpose:** Help Solana applications identify slow, redundant, or fragile RPC request patterns before release. **Primary users:** Frontend, wallet, indexer, and backend teams building Solana clients. **Core promise:** Turn a captured JSON-RPC request log into an actionable performance report—without wallet access or live network calls. ## MVP ### Input A newline-delimited JSON file containing captured requests and responses: ```json {"method":"getAccountInfo","params":["..."],"duration_ms":182,"status":200} ``` Optional fields: - `route` or `screen` - `commitment` - `cache_hit` - `retry_number` - `response_bytes` - `timestamp` ### Analysis The tool detects: - Duplicate requests within a configurable time window - Repeated polling with no apparent state change - High-latency methods by route - Retry bursts and retry amplification - Mixed commitment settings within one workflow - Large responses that may be narrowed with encoding or filters - Requests made sequentially when they could be grouped by workflow design ### Output Generate Markdown and JSON reports containing: 1. **Executive summary** - Total requests - Total captured duration - Duplicate-request ratio - Retry count 2. **Top findings** - Severity: `high`, `medium`, or `low` - Evidence from the trace - Suggested remediation 3. **Route breakdown** 4. **Method breakdown** 5. **Before/after comparison** for two trace files ## CLI sketch ```bash rpc-profiler analyze trace.ndjson --out report.md rpc-profiler compare before.ndjson after.ndjson --out diff.md rpc-profiler rules list ``` ## Example finding > **Medium — repeated account fetches** > `getAccountInfo` was requested 14 times for the same address within 900 ms on `dashboard`. > Consider request coalescing, a short-lived cache, or fetching once at the workflow boundary. ## Guardrails - Redact public keys and request parameters by default. - Never store private keys, signing payloads, or authorization headers. - Treat logs as sensitive; provide local-only processing. - Label suggestions as heuristics, not guaranteed fixes. - Preserve raw evidence alongside every finding so developers can verify it. ## Success criteria A developer can: - Capture a representative trace. - Run one command without network credentials. - Find the top three avoidable RPC patterns. - Compare two application versions using a stable report format. - Export findings into an issue tracker manually.

# Self-directed draft: Solana Error Contract Linter ## Product specification **Purpose:** Help Solana teams keep on-chain errors understandable and consistent across programs, SDKs, and documentation. **Primary users:** Solana program maintainers and client-library developers. ## MVP workflow 1. Upload an Anchor IDL or structured error manifest. 2. Optionally provide SDK error mappings and a Markdown error reference. 3. Run checks. 4. Export a review report and machine-readable JSON. ## Checks - Duplicate error codes or names. - Missing messages for declared errors. - Error codes outside the configured range. - Renamed errors without an explicit migration note. - SDK mappings that reference unknown errors. - Documentation entries missing code, name, or recovery guidance. - Inconsistent terminology such as `authority` vs. `admin`. - Messages that expose implementation details or sensitive values. - Unchanged errors whose client-facing text changed unexpectedly. ## Report format Each finding includes: ```text Severity: error | warning | info Source: IDL | SDK | docs Location: file and line, when available Finding: concise explanation Suggested fix: concrete remediation ``` Example: ```text ERROR — SDK mapping references unknown error 6007. Suggested fix: add the error to the IDL or remove the stale client mapping. ``` ## Design requirements - Local-first processing; uploaded files are not required for the core lint run. - Deterministic output suitable for CI. - Configurable naming rules and error-code ranges. - Supports SARIF, JSON, and Markdown output. - Never assumes an error is safe to retry; retry guidance must be explicitly supplied. - Treats numeric error codes as stable identifiers unless a migration rule says otherwise. ## Suggested CLI ```bash solana-error-lint \ --idl target/idl/program.json \ --sdk src/errors.ts \ --docs docs/errors.md \ --format markdown ``` Exit codes: - `0`: no errors. - `1`: one or more errors. - `2`: invalid input or configuration. ## Acceptance criteria - A fixture with duplicate codes produces a failing result. - A fixture with a stale SDK mapping identifies the unknown code. - Markdown output contains every finding’s severity, source, and fix. - Identical inputs produce byte-identical JSON. - A clean fixture exits with code `0`.

# Self-directed draft: Solana IDL Compatibility Diff ## Product specification **Purpose:** Help a Solana program team review how an IDL change may affect existing clients before publishing a new SDK. **Input:** Two IDL files: the version clients currently use and a proposed version. No wallet connection or RPC access required. **Output:** A Markdown report with: - Added, removed, and renamed instructions, accounts, arguments, and events - Changes to argument order, types, and account requirements - A severity label for each change: **likely breaking**, **review needed**, or **additive** - A short migration note the reviewer can edit **Key design rule:** The tool compares declared interfaces, not runtime behavior. It must say “not assessed” for program logic, account data migration, and deployed-program compatibility. **MVP acceptance test:** Given two fixture IDLs where an instruction gains a required account and another gains an optional event, the report flags the account change as likely breaking and the event addition as additive, with the relevant instruction names shown.

# Self-directed draft: Solana Release Safety Gate ## Product specification **Purpose:** Give Solana teams a repeatable pre-release check for program upgrades, client releases, and configuration changes. **Primary users:** Program maintainers, SDK owners, and release reviewers. **Core workflow:** 1. Create a release record. 2. Attach the intended changes and test evidence. 3. Run the checklist below. 4. Require an explicit reviewer decision: **ship**, **hold**, or **rollback**. 5. Preserve the record with the release artifact. ## Release record template ```yaml release_id: scope: program_id: client_versions: target_environment: change_summary: backward_compatibility: migration_required: false rollback_method: owner: reviewer: decision: hold evidence: tests: simulations: upgrade_dry_run: monitoring_queries: open_risks: ``` ## Safety checklist ### Scope and authority - [ ] Exact program, client, and configuration changes are listed. - [ ] Upgrade authority and required signers are identified. - [ ] The intended deployment environment is explicit. - [ ] No unrelated changes are bundled into the release. ### State and compatibility - [ ] Existing account data remains readable, or a migration is documented. - [ ] New accounts, seeds, ownership, and executable permissions are specified. - [ ] Client instruction encoding matches the released program interface. - [ ] Removed fields, accounts, or instructions have a compatibility decision. - [ ] Rent, compute, and transaction-size changes are assessed. ### Failure handling - [ ] A failed upgrade leaves a known safe state. - [ ] Rollback limitations are documented; “rollback” is not assumed to mean state reversal. - [ ] Migration interruption and retry behavior are tested. - [ ] Operational keys and secrets are not stored in logs or release notes. - [ ] A halt condition is defined for unexpected errors. ### Verification - [ ] Tests cover success, authorization failure, malformed input, and repeated execution. - [ ] Simulations or local test runs cover the migration path. - [ ] Expected logs and error codes are recorded. - [ ] Post-release checks have named owners and time limits. - [ ] The reviewer has inspected evidence rather than only the code diff. ## Decision policy - **Ship:** All blocking checks pass and rollback limitations are understood. - **Hold:** Any authority, migration, compatibility, or failure-path question is unresolved. - **Rollback/mitigate:** The release produces an unexpected state or violates a defined halt condition. ## Minimal acceptance criteria A release is not ready until it has: - one completed release record, - one independent review, - one tested failure path, - a documented migration or explicit “no migration” decision, - and a concrete post-release verification procedure.

# Self-directed draft: Solana Transaction Failure Reproducer ## Product specification **Purpose:** Help a Solana team turn a failed transaction into a small, shareable reproduction without exposing private keys or relying on a mutable live account state. **User:** A developer debugging a client integration or program test. **Input:** A failed transaction’s message, simulation logs, program versions, and the account data needed to reproduce the failure. Secrets and signer material are never accepted. **Output:** A local test fixture containing the instruction sequence, sanitized account snapshots, expected failure, and a README with the command to rerun it. If reproduction is incomplete, the tool lists missing accounts or environmental assumptions instead of claiming success. ### MVP workflow 1. Import a failed transaction from a local file. 2. Show the accounts and data proposed for inclusion; require the user to review and redact them. 3. Generate a fixture for a local validator and an assertion for the observed error. 4. Run the fixture twice and report whether both runs produce the same failure. ### Acceptance criteria - The generated fixture contains no private keys, seed phrases, or signer files. - An account whose data was omitted is identified as a dependency, not silently replaced with an empty account. - The README distinguishes the **original failure** from the **locally reproduced failure**. - A nondeterministic result is reported as such; it is not packaged as a confirmed reproduction. **First-release boundary:** Local files only. No transaction fetching, hosted uploads, or automatic sharing.

# Self-directed draft: Solana Account Compatibility Contract ## Product specification **Purpose:** Prevent client and program releases from silently disagreeing about account layout, instruction arguments, or required accounts. ### Target users Solana teams maintaining an on-chain program alongside one or more TypeScript, Rust, or mobile clients. ### Problem A client can compile successfully while sending incorrectly ordered accounts, stale instruction data, or incompatible serialized values. These failures are often discovered only during integration testing. ### Core workflow 1. The developer provides: - Program Interface Definition Language (IDL), if available - Rust account and instruction declarations - Client instruction builders - A version label 2. The tool extracts: - Instruction names and argument types - Account order, mutability, signer requirements, and optionality - Account field names and serialized types 3. It compares two versions or two sources. 4. It produces: - A human-readable compatibility report - A machine-readable JSON report - Generated test cases for changed instructions ### Compatibility rules Flag as **breaking**: - Reordered instruction arguments - Changed serialized argument types - Reordered required accounts - Changed signer or writable requirements - Removed account fields without an explicit migration - Changed enum variants or discriminant ordering Flag as **review required**: - Added optional accounts - Added instruction arguments with defaults - Renamed fields without layout changes - Client builders that omit newly required accounts Mark as **compatible**: - Documentation-only changes - Client naming changes that preserve wire format - Added read-only helpers that do not alter existing instructions ### MVP interface ```text compat-check \ --baseline ./contracts/v1 \ --candidate ./contracts/v2 \ --client ./clients \ --out ./compat-report ``` Report example: ```text BREAKING: initialize.account[2] baseline: payer, writable=false, signer=true candidate: payer, writable=true, signer=true REVIEW: create_order argument `expiry` Added u64 argument; existing clients may omit it. ``` ### Deliverables - CLI scanner - JSON schema for findings - Markdown report renderer - CI exit codes: - `0`: no findings - `1`: review-required findings - `2`: breaking findings - Framework adapter boundary so parsing logic can be extended without changing report formats ### Acceptance criteria - Detects every listed breaking rule in fixture repositories - Produces stable output for identical inputs - Includes source file and line references where available - Never modifies source files - Runs locally without requiring private keys, transaction submission, or network access ### Future extensions - Pull-request annotations - Migration checklist generation - Compatibility badges for published client packages - Property-based serialization tests for changed instructions

# Self-directed draft: Solana Authority Inventory ## Product specification **Purpose:** Give Solana teams a clear, non-custodial map of program upgrade authorities, mint authorities, freeze authorities, multisig relationships, and operational signers. ### Target user Protocol engineers, security reviewers, and operations teams preparing a launch, migration, or permission review. ### Core workflow 1. Import public addresses and program IDs. 2. Read permitted public account metadata from a configured RPC endpoint. 3. Classify each authority: - Upgrade authority - Mint authority - Freeze authority - Close authority - Admin/config authority - Multisig or PDA-controlled authority 4. Attach an owner, environment, and review status to each item. 5. Export a human-readable report and machine-readable JSON. ### MVP scope - Read-only operation; never request or store private keys. - Support manually entered addresses and CSV import. - Show: - Address - Authority type - Referenced program or mint - Current controller - Last review date - Reviewer notes - Flag: - Missing authority owners - Authorities controlled by unexpected addresses - Unreviewed items - Authority values that are present when the team expects them to be disabled - Provide a change log based on repeated snapshots supplied by the user. ### Suggested data model ```text Asset { id environment address kind authority expectedController owner reviewStatus reviewedAt notes } ``` ### Safety and trust boundaries - Public-key-only inputs. - No signing, transaction construction, custody, or automated authority changes. - Display the RPC endpoint and snapshot timestamp in every report. - Treat decoded metadata as untrusted input and label uncertain classifications. - Require explicit confirmation before marking an authority as reviewed. ### Acceptance criteria - A user can create an inventory without connecting a wallet. - Every displayed authority links to its source address and classification method. - Exported JSON can recreate the report. - A second snapshot highlights additions, removals, and controller changes. - The interface clearly distinguishes “unknown,” “unset,” and “not checked.” ### Possible name **Keyline** — a read-only authority map for Solana operations.

# Self-directed draft: Solana Transaction Failure Reproducer ## Product specification **Purpose:** Turn a failed Solana transaction into a deterministic, shareable test fixture that helps teams reproduce and fix bugs locally. ### Target user Solana developers debugging failed instructions, account constraints, compute exhaustion, or client/program mismatches. ### Core workflow 1. Paste a serialized transaction, instruction payload, or structured failure report. 2. Record the relevant program IDs, account addresses, signer roles, instruction data, and expected result. 3. Generate a fixture containing: - Human-readable test name - Account metadata and writable/signer flags - Instruction ordering - Encoded instruction data - Expected failure category - Optional redacted account snapshots 4. Export a framework-neutral JSON fixture plus a suggested test skeleton. 5. Re-run the fixture against a local validator or test harness and mark the result as reproduced, fixed, or inconclusive. ### MVP scope - JSON import/export - Explicit account-role capture - Instruction ordering preservation - Redaction of signer secrets and configurable address masking - Failure-category tagging: - Invalid account - Missing signer - Constraint failure - Program error - Compute/resource failure - Client encoding mismatch - Generated TypeScript test scaffold - Fixture validation with clear missing-field errors ### Example fixture ```json { "name": "rejects_unapproved_recipient", "programId": "<PROGRAM_ID>", "accounts": [ {"name": "authority", "address": "<ADDRESS>", "signer": true, "writable": false}, {"name": "recipient", "address": "<ADDRESS>", "signer": false, "writable": true} ], "instructions": [ { "programId": "<PROGRAM_ID>", "dataBase64": "<ENCODED_DATA>", "accountOrder": ["authority", "recipient"] } ], "expected": { "status": "failure", "category": "program_error", "errorCode": "<ERROR_CODE>" } } ``` ### UX principles - Never request or store private keys. - Make account ordering visible. - Preserve raw encoded data alongside decoded labels. - Treat “not reproduced” as a valid result, not a hidden failure. - Show a copyable diagnostic summary suitable for an issue tracker. ### Success criteria A developer can create a fixture in under five minutes, hand it to another engineer, and receive the same intended test setup without reconstructing the original debugging session.

# Self-directed draft: Solana Instruction Contract Linter ## Product specification **Purpose:** Catch mismatches between a Solana instruction’s declared accounts, signer requirements, PDA seeds, and client invocation before they become runtime failures. ### Target user Solana program developers and client engineers working across Rust/Anchor programs and TypeScript clients. ### Core workflow 1. Provide a program source path and client invocation examples. 2. Extract each instruction’s expected: - Account names and mutability - Signer requirements - PDA seeds and bump usage - Optional accounts - Argument names and types 3. Compare the declarations with client-side account maps and argument payloads. 4. Produce a machine-readable report plus concise terminal output. ### Example output ```text Instruction: withdraw ERROR accounts.user: Program requires a signer, but client marks this account as readonly. ERROR accounts.vault: PDA seed order differs: program: ["vault", user] client: ["user", "vault"] WARN args.amount: Client sends number; expected u64-compatible integer. ``` ### MVP scope - TypeScript CLI - Anchor IDL input - Rust source annotations where available - Client fixture files containing account maps and arguments - Static checks only; no transaction submission - JSON and human-readable reports - Exit code `1` when errors exist, `0` when only warnings or no findings ### Proposed command interface ```bash sol-contract-lint \ --idl ./target/idl/app.json \ --fixtures ./tests/instructions \ --out ./artifacts/contract-report.json ``` Fixture format: ```json { "instruction": "withdraw", "accounts": { "user": { "signer": true, "writable": true }, "vault": { "pdaSeeds": ["user", "vault"] } }, "args": { "amount": "1000" } } ``` ### Rules - `SIGNER_MISSING` - `WRITABLE_MISMATCH` - `PDA_SEED_ORDER_MISMATCH` - `PDA_BUMP_MISMATCH` - `ACCOUNT_MISSING` - `UNEXPECTED_ACCOUNT` - `ARGUMENT_MISSING` - `ARGUMENT_TYPE_SUSPECT` - `OPTIONAL_ACCOUNT_MISMATCH` ### Acceptance criteria - Detects every deliberately injected fixture error. - Produces stable error codes suitable for CI annotations. - Never submits transactions or requires private keys. - Handles multiple instructions in one run. - Includes source location or fixture path for each finding. - Documents limitations for dynamically derived seeds and custom serialization. ### Extension path Add adapters for non-Anchor instruction schemas, editor diagnostics, and a CI status summary that groups failures by instruction rather than by file.

# Self-directed draft: Solana Account State Diff Inspector ## Product specification **Purpose:** Help Solana developers compare program-owned account state before and after an instruction, making unexpected mutations easier to spot. ### Target user A developer debugging account layout, PDA derivation, instruction behavior, or state migrations. ### Core workflow 1. Enter a cluster/RPC endpoint. 2. Provide: - Transaction signature, or - Two slot/block references 3. Select one or more account addresses. 4. Fetch account data at both points. 5. Display a structured diff. ### Diff view For each account, show: - Address - Owner program - Lamports before/after and delta - Data length before/after - Executable flag - Rent-related metadata, if available - Raw byte diff with offsets - Optional decoded fields using a user-supplied schema - “Created,” “closed,” “resized,” and “owner changed” markers ### Safety boundaries - Read-only by default - Never requests a wallet signature - Never sends transactions - Clearly labels unavailable historical state instead of guessing - Shows the source RPC and retrieval timestamp - Treats decoded fields as user-provided interpretations, not verified truth ### MVP acceptance criteria - A user can compare at least two account snapshots. - Byte changes are shown with hexadecimal offsets. - Added, removed, and changed accounts are separated. - Failed RPC requests include actionable error text. - The export contains enough context to reproduce the investigation: - Cluster label - RPC identifier entered by the user - Reference points - Account addresses - Retrieval times - Diff results ### Suggested interface **Header:** `Account State Diff` **Inputs:** `Reference A` · `Reference B` · `Account addresses` · `Decode schema (optional)` **Results tabs:** - Overview - Account changes - Byte diff - Decoded fields - Export ### Export format Produce Markdown and JSON. Example Markdown summary: ```text Account: <address> Owner: <program address> Status: resized Lamports: <before> → <after> Data length: 128 → 160 bytes Changed ranges: 0x20–0x27, 0x80–0x9F Decoder: user-supplied schema ``` ### Future extensions - Compare all accounts touched by a transaction - Save named investigation sessions - Add Anchor-compatible schema input - Generate a review-ready incident summary - Support side-by-side instruction logs when supplied by the user

# Self-directed draft: Solana Release Readiness Console ## Product brief A small internal dashboard that helps Solana teams verify whether a release is safe to test, stage, or ship. It converts scattered checks—program builds, environment configuration, migrations, transaction simulations, and rollback steps—into an auditable release record. ## Primary user A developer or technical lead preparing an on-chain program or client release. ## Core workflow 1. Create a release record with: - Release name and version - Repository commit identifier - Target cluster - Program IDs - Owner and reviewer 2. Complete categorized checks. 3. Attach evidence such as logs, test output, or transaction signatures. 4. Record unresolved risks. 5. Mark the release as **Draft**, **Ready for review**, **Approved**, or **Blocked**. 6. Export a compact Markdown release note. ## Check categories ### Build - [ ] Reproducible build completed - [ ] Program binary compared with the intended artifact - [ ] Dependencies reviewed - [ ] Upgrade authority identified and access checked ### Test - [ ] Unit tests pass - [ ] Integration tests pass - [ ] Negative and authorization cases tested - [ ] Compute-unit and account-size behavior reviewed - [ ] Client compatibility checked ### Environment - [ ] Cluster and commitment settings recorded - [ ] RPC configuration is present without exposing secrets - [ ] Required keypairs or signers are available - [ ] Environment-specific program addresses verified ### Change safety - [ ] Data or account layout changes documented - [ ] Migration procedure tested - [ ] Backward compatibility decision recorded - [ ] Rollback or pause procedure documented ### Observability - [ ] Expected success and failure signals defined - [ ] Error messages are actionable - [ ] A post-release smoke test is written - [ ] An owner is assigned for the first monitoring window ## Minimal data model ```text Release - id - name - version - commit - target_cluster - status - owner - reviewer - created_at - checks[] - risks[] - evidence[] - rollback_plan ``` ## Acceptance criteria - A release cannot become **Approved** while required checks are incomplete. - Secrets are rejected from text fields and excluded from exports. - Every check records status, owner, timestamp, and optional evidence. - The exported release note contains only the selected cluster, program IDs, commit, decisions, risks, and rollback plan. - Any status change is recorded in an append-only activity log. ## Suggested MVP A web form backed by a simple database, with Markdown export and no automatic transaction execution. Keep signing, deployment, and authority changes outside the product until the review workflow proves useful.

# Self-directed draft: Solana Transaction Failure Triage Card **Purpose:** Help developers turn a failed transaction into an actionable bug report within minutes. ## Capture - [ ] Network and cluster - [ ] Program ID(s) - [ ] Transaction signature, if created - [ ] Wallet or test signer used - [ ] Commitment level - [ ] Recent code/config changes - [ ] Whether failure occurs locally, in CI, or in production ## Classify the failure **A. No signature created** - Check client-side validation. - Confirm all required accounts are supplied. - Confirm instruction data encoding. - Log the exact instruction builder inputs. **B. Signature exists but transaction failed** - Inspect simulation or transaction logs. - Find the first program error, not only the final wrapper error. - Record custom error codes verbatim. - Compare account ownership, signer status, writability, and expected PDA derivation. **C. Transaction confirms but state is unexpected** - Read the affected account at the same commitment level. - Verify the client decoded the correct account layout. - Check whether another instruction or retry altered state. - Record pre- and post-transaction account snapshots where safe. ## Minimal bug report template ```text Title: Cluster: Program ID: Transaction signature: Reproduction command/test: Expected result: Observed result: First relevant log line: Custom error code: Instruction accounts: Recent change: Smallest suspected cause: ``` ## Engineering rule Do not “fix” a failure by adding retries, changing commitment, or switching endpoints until the underlying error is captured. Those changes may alter symptoms without resolving the program or client defect.

# Self-directed draft: Solana RPC Cutover Checklist **Use case:** A team is switching its application to a new RPC endpoint and wants a reversible cutover without mistaking endpoint differences for application bugs. - [ ] **Inventory calls.** List the RPC methods the app uses, required commitment levels, subscriptions, and expected request volume. Keep credentials out of the document. - [ ] **Prepare a switch.** Put the endpoint behind configuration so the team can restore the previous endpoint without a code release. - [ ] **Run read-only checks.** Against both endpoints, request the same known accounts and recent transaction signatures. Record response status, context slot where available, latency, and errors. Treat results from different slots as *inconclusive*, not divergent. - [ ] **Test app flows in staging.** Cover initial load, refresh, subscriptions reconnecting, and error handling. Do not send production transactions as a probe. - [ ] **Set cutover gates.** Before switching, define acceptable error rate and latency, plus who can call a rollback. Record the baseline and observation window. - [ ] **Cut over gradually.** Start with a small share of traffic if routing permits. Watch app errors and RPC responses together; stop increasing traffic if a gate fails. - [ ] **Practice rollback.** Restore the prior configuration and confirm reads and subscriptions recover. - [ ] **Close the drill.** Record the decision, observed issues, and the configuration needed to repeat or reverse the switch.

# Self-directed draft: Solana IDL Compatibility Checker **Product spec:** A CLI that detects breaking changes between two Solana program IDL files before release. **Problem:** Client applications can fail when instruction names, account requirements, argument types, or return types change unexpectedly. **MVP command** ```bash idl-guard check old.json new.json --policy semver ``` **Output** ```text Breaking changes found: ✖ Removed instruction: withdraw ✖ Account became mandatory: deposit.vault ⚠ Argument type changed: swap.amount u64 → u128 Suggested version: MAJOR Exit code: 1 ``` **Rules** - Removing an instruction: breaking. - Removing an account or argument: breaking. - Adding a required account or argument: breaking. - Changing an argument, account, or return type: breaking. - Adding an optional account or instruction: non-breaking. - Documentation-only changes: non-breaking. - Emit machine-readable JSON with `--format json`. - Support an allowlist for intentional migrations. **Repository layout** ```text idl-guard/ src/ load.ts diff.ts rules.ts render.ts fixtures/ old.json new.json package.json README.md ``` **Acceptance checklist** - [ ] Compares instructions by name. - [ ] Compares account mutability and signer requirements. - [ ] Compares argument and return types recursively. - [ ] Produces stable output for CI review. - [ ] Returns nonzero status only for policy violations. - [ ] Includes fixture tests for additions, removals, and type changes. - [ ] Never requires network access or wallet credentials. **Best first customer:** Teams maintaining SDKs or multiple client applications against one Solana program. **Expansion:** Generate a migration report mapping each breaking change to affected client methods.

# Self-directed draft: Solana Transaction Repro Bundle **Product spec:** A developer tool that turns a failed Solana transaction test into a shareable, local-only reproduction bundle. **User problem:** An error message alone often leaves a teammate guessing which instruction, accounts, and test conditions produced the failure. **MVP workflow** 1. Wrap a test transaction with a `captureOnFailure()` helper. 2. If the test fails, save a bundle containing the instruction names, program IDs, account addresses and roles, redacted logs, error, and the command used to run the test. 3. Generate a `README.md` with the expected result, actual result, and exact local replay command. 4. Let the developer review the bundle before sharing it. **Safety defaults:** Never export private keys, seed phrases, environment variables, or full keypair files. Flag any captured account data for manual review. Keep bundles on disk; do not upload them automatically. **Acceptance criteria** - A teammate can reproduce a failing fixture from the bundle without requesting missing test inputs. - The bundle identifies the failing instruction when the test harness can determine it. - A scan finds no secrets in a sample bundle. - If the failure depends on unavailable external state, the README says so rather than promising deterministic replay.

# Self-directed draft: Solana Compute Regression Gate **Product spec:** A CI check that flags unexpected increases in compute-unit usage for a team’s Solana instruction tests. **Workflow** 1. Run named test fixtures against a local validator. 2. Record each successful instruction’s compute units in a committed baseline file. 3. On a pull request, rerun the same fixtures and report the absolute and percentage change. 4. Fail CI only when a fixture exceeds its configured threshold. **Example report** | Fixture | Baseline | Current | Change | Result | |---|---:|---:|---:|---| | `create_vault` | 42,000 | 48,000 | +14.3% | Review | **First-version requirements:** Support per-fixture thresholds, a command to deliberately update the baseline, and a readable diff in CI logs. Treat failed tests and missing fixtures as errors, not as zero-cost results. **Boundary:** This checks reproducible local test runs. It does not predict production fees or guarantee performance under every account state.