onullbnd

# Self-Directed Draft: Solana IDL Compatibility Diff Tool **Format:** Product specification **Status:** Proposed; not built or validated **Audience:** Solana teams maintaining clients, SDKs, and on-chain programs ## Problem Program changes can silently break clients when instruction arguments, account requirements, types, or errors change. Teams need a fast, review-friendly way to identify compatibility risks before publishing a new release. ## Product A command-line tool that compares two IDL files and produces: 1. A machine-readable diff. 2. A human-readable Markdown report. 3. A compatibility classification for each change. ### Example command ```bash idl-diff old.json new.json --format markdown --out compatibility.md ``` ## Change Classification - **Breaking:** Existing clients may fail or require code changes. - **Potentially breaking:** Behavior or validation may change depending on usage. - **Compatible:** Additive or non-disruptive change. - **Unknown:** Requires human review. ## Checks ### Instructions - Added or removed instruction. - Renamed instruction. - Argument added, removed, reordered, or type-changed. - Mutability or signer requirement changed. - Account added, removed, reordered, or constraint metadata changed. ### Types - Struct field added, removed, reordered, or type-changed. - Enum variant added, removed, or reordered. - Optionality changed. - Numeric width or serialization representation changed. ### Errors - Error added or removed. - Error code changed. - Error name or message changed. ### Metadata - Program address changed. - IDL version changed. - Missing or malformed definitions. ## Report Example ```markdown ## Compatibility Summary - Breaking: 2 - Potentially breaking: 1 - Compatible: 3 - Unknown: 0 ### Breaking Changes - `deposit.amount`: `u64` → `u128` - Existing clients must update serialization. - `withdraw.user`: signer requirement removed - Authorization assumptions require review. ### Compatible Changes - Added instruction: `quote` - Added error: `SlippageExceeded` ``` ## Exit Codes - `0`: No breaking changes. - `1`: Breaking changes detected. - `2`: Invalid input or comparison failure. - `3`: Unknown changes require review. ## MVP Scope - JSON IDL inputs. - Deterministic sorting. - Instruction, account, type, error, and metadata comparisons. - Markdown and JSON output. - Unit tests using fixture IDLs. - No network access and no claims about deployed program state. ## Acceptance Criteria - Identical files produce an empty diff. - Every detected change includes a path, old value, new value, and classification. - Output remains stable across repeated runs. - A CI job can fail on breaking changes. - Malformed IDLs return actionable error messages.

# Self-Directed Draft: Solana Program Release Readiness Checklist **Format:** Reusable checklist **Status:** Proposed; not validated **Audience:** Solana program teams preparing a release ## Code and Build - [ ] Program builds reproducibly from a clean checkout. - [ ] Compiler, framework, and dependency versions are pinned. - [ ] Review diff includes only intended changes. - [ ] Clippy, formatting, and project tests pass. - [ ] Release artifact is generated and recorded for review. - [ ] Upgrade authority and deployment permissions are documented. ## Program Safety - [ ] All instruction paths validate signer, owner, PDA, and authority assumptions. - [ ] Arithmetic has explicit overflow and underflow handling. - [ ] Account initialization and reallocation paths are tested. - [ ] Closing accounts cannot redirect funds or leave unsafe state. - [ ] CPI targets and privilege propagation are intentional. - [ ] Errors are specific enough for client-side diagnosis. - [ ] Compute-unit and account-count limits are tested near expected maximums. ## State and Migration - [ ] State schema changes are identified. - [ ] Existing accounts remain readable, or a migration exists. - [ ] Migration is resumable and safe to rerun where applicable. - [ ] New defaults and nullable fields are defined. - [ ] Rollback or pause behavior is documented. ## Client Integration - [ ] Client builders use the release IDL or interface definition. - [ ] Instruction arguments and account ordering are reviewed. - [ ] All required signers and writable accounts are explicit. - [ ] Clients handle custom errors and confirmation failures. - [ ] Transaction simulation is available before submission. - [ ] Versioned transaction and address lookup table assumptions are documented. ## Testing - [ ] Unit tests cover success and rejection paths. - [ ] Integration tests cover realistic account graphs. - [ ] Property or fuzz tests cover malformed inputs. - [ ] Tests include duplicate accounts, missing signatures, stale state, and boundary values. - [ ] Upgrade and migration tests run against representative prior state. - [ ] Observability captures instruction name, outcome, and actionable error context without exposing secrets. ## Operational Handoff - [ ] Deployment steps are written in order. - [ ] Required environment variables and key roles are listed. - [ ] Verification steps are defined after deployment. - [ ] Pause, upgrade, and incident contacts are documented. - [ ] Known limitations and unresolved risks are recorded. - [ ] Release owner signs off on code, migration, and client compatibility. **Release gate:** Do not proceed until every unchecked item has an owner, rationale, and explicit risk acceptance.

# Self-Directed Draft: Solana Transaction Failure Triage Kit **Format:** Product specification **Status:** Proposed; not built or validated **Audience:** Solana developers debugging failed transactions ## Problem Transaction failures often expose a low-level error without preserving enough context to identify the failing instruction, relevant accounts, or likely remediation. Teams need a repeatable, redaction-safe way to turn simulation and execution output into actionable debugging notes. ## Product A local CLI that accepts transaction logs, instruction metadata, and optional simulation output, then produces a structured failure report. ### Example command ```bash txtriage analyze \ --logs ./transaction.log \ --instructions ./instructions.json \ --output report.md ``` ### Report sections - **Summary:** success/failure and failure location - **Instruction map:** index, program identifier, and label if supplied - **Detected signals:** custom errors, log keywords, compute-unit messages, missing account clues - **Evidence:** exact log lines with line numbers - **Hypotheses:** ranked possible causes, explicitly marked as unverified - **Next checks:** concrete commands or code locations to inspect - **Redaction notice:** fields removed or omitted from output ## Input schema ```json { "logs": ["Program ... invoke [1]", "..."], "instructions": [ {"index": 0, "program": "...", "label": "create"} ], "simulation": { "err": null, "unitsConsumed": 0 } } ``` All fields are optional except `logs`. ## Safety and scope - Never submit, sign, resend, or modify transactions. - Never infer private keys or expose secret-like values. - Treat decoded addresses and payloads as sensitive; support configurable redaction. - Label pattern-based interpretations as hypotheses, not facts. - Operate offline by default. ## MVP 1. Parse common log structures. 2. Associate logs with instruction nesting where possible. 3. Detect explicit error strings and numeric error codes. 4. Generate Markdown and JSON reports. 5. Add deterministic redaction for configured addresses and byte sequences. 6. Include fixture-based tests for successful, nested, and failed transactions. ## Acceptance criteria - Re-running the same inputs produces identical output. - Every conclusion links to one or more source lines. - Unknown errors remain marked “unclassified.” - Redacted values never appear in generated reports. - The tool works without network access. ## Future extensions - Pluggable error-code dictionaries supplied by users. - CI mode that fails when new failure signatures appear. - Editor integration linking report evidence to source files.

# Self-Directed Draft: Solana Account Compatibility Linter **Format:** Product specification **Status:** Proposed; not built or validated **Audience:** Solana program and client teams ## Problem A client can break when an account’s expected owner, discriminator, size, writable status, or signer requirement differs from the program’s assumptions. These mismatches are often discovered only during integration testing. ## Product A command-line linter that checks declared account requirements against fixtures, generated client code, and optional program metadata. ## Example Usage ```bash account-lint check \ --fixture tests/accounts/*.json \ --rules account-rules.yaml ``` ## Rule Format ```yaml - instruction: deposit accounts: vault: owner: VaultProgram writable: true signer: false min_size: 128 authority: signer: true writable: false ``` ## MVP Checks - Required account is present. - Account is writable when mutation is expected. - Signer status matches the rule. - Owner matches the expected program or system owner. - Serialized data meets minimum size. - Optional PDA seeds produce the expected address. - Duplicate accounts are flagged where distinct accounts are required. ## Output Human-readable output: ```text FAIL deposit.authority expected: signer=true received: signer=false WARN deposit.vault data length 96 is below required minimum 128 ``` Machine-readable output: ```json { "status": "failed", "errors": 1, "warnings": 1, "checks": [] } ``` ## Design Constraints - Run locally and in CI. - Never require private keys. - Accept fixture data without submitting transactions. - Keep rules independent from any single client framework. - Exit code `0` for pass, `1` for rule failures, `2` for malformed input. ## Suggested Repository Layout ```text account-lint/ src/ rules/ fixtures/ examples/ README.md account-rules.schema.json ``` ## Acceptance Criteria - A fixture with one missing signer fails deterministically. - A wrong owner is reported with expected and received values. - Valid fixtures produce no errors. - JSON output is stable enough for CI annotations. - Rule files receive schema validation errors before lint execution. ## Future Extensions - Compare account rules with generated TypeScript or Rust clients. - Add Anchor-compatible account extraction. - Emit GitHub Actions annotations. - Support snapshots for intentional schema changes.

# Self-Directed Draft: Solana IDL Drift Guard **Format:** Product specification **Status:** Proposed; not built or validated **Audience:** Solana program teams maintaining clients, SDKs, and IDLs ## Problem A program’s deployed instruction layouts and account schemas can diverge from the repository’s IDL. This may cause clients to encode incorrect arguments, derive incompatible accounts, or fail only after deployment. ## Product A local command-line tool that compares two Anchor-style IDLs—or an IDL and captured instruction fixtures—and reports potentially breaking changes. ## Core Commands ```bash idlguard compare old.json new.json idlguard check-fixtures ./fixtures --idl ./target/idl/app.json idlguard report --format markdown ``` ## Detection Rules Flag changes to: - Instruction names - Argument order, type, or optionality - Required accounts and mutability - Signer requirements - Account field types and constraints - Enum variants and discriminant-sensitive ordering - Struct fields added without compatibility handling - Removed instructions, accounts, or types Classify findings as: - **Breaking:** existing clients may fail or encode different data - **Risk:** behavior may change depending on usage - **Informational:** additive or documentation-only change ## Example Output ```text BREAKING initialize.args[1] u64 -> u128 BREAKING withdraw.accounts.authority signer=true -> signer=false RISK Position.fields[3] Added field: liquidation_threshold Existing serialized data may require migration ``` ## Fixture Check Fixtures contain: ```json { "instruction": "withdraw", "args": {"amount": 1000}, "accounts": ["..."], "expected_result": "success" } ``` The tool validates that each fixture still resolves against the current IDL and reports missing, extra, or type-incompatible fields. ## MVP Requirements - Deterministic JSON comparison - Stable exit codes for CI - Markdown and JSON output - Ignore lists for intentionally incompatible changes - No network dependency - Clear source-location references when available ## Acceptance Criteria - Identical IDLs produce zero findings. - Removed instructions are reported as breaking. - Argument type changes identify the exact instruction and index. - CI exits nonzero when breaking findings exist. - Output remains readable without requiring Solana RPC access. ## Non-Goals - Proving deployed bytecode matches an IDL - Automatically migrating accounts - Publishing reports or modifying repositories ## Suggested Repository Layout ```text idlguard/ src/ diff.ts fixture-check.ts rules.ts report.ts fixtures/ tests/ README.md ```

# Self-Directed Draft: Solana Transaction Failure Explainer **Format:** Product specification **Status:** Proposed; not built or validated **Audience:** Solana developers and support engineers ## Purpose Turn a failed transaction’s logs, instruction data, and account metadata into a compact explanation that helps a developer reproduce and fix the issue. ## Core Workflow 1. User supplies a transaction signature, simulation output, or pasted logs. 2. Tool groups messages by instruction. 3. It extracts: - Program IDs - Return and custom error codes - Compute-unit usage - Writable and signer accounts - Log sequence 4. It produces: - A chronological failure summary - The first suspected failing instruction - Evidence supporting the suspicion - Unknowns requiring manual inspection - A copyable bug-report template ## Example Output ```text Status: Failed Likely failing instruction: #2 Program: <program id> Observed signal: custom error 6003 Evidence: - Invocation began at log line 14 - Error appeared before instruction #3 - Account X was writable but lacked signer status Unknown: - Error 6003 meaning is not available locally Next checks: [ ] Confirm error-code mapping in the program source [ ] Verify account metas and signer flags [ ] Re-run with simulation logs attached ``` ## MVP - Local CLI accepting pasted logs and JSON transaction data - Deterministic parser with no opaque diagnosis - Pluggable error-code mappings from a local configuration file - Markdown and JSON output - Redaction of account addresses through optional aliases - Fixture-based tests for successful, failed, nested, and truncated logs ## Non-Goals - Automatically submitting transactions - Claiming certainty about an error’s cause - Replacing source-level debugging - Storing transaction data remotely by default ## Acceptance Criteria - Every conclusion links to an observed log, field, or explicit user mapping. - Unknown error codes remain labeled unknown. - Malformed input returns actionable parser errors. - The same input produces identical output. - Output can be pasted directly into an issue tracker. ## Suggested Configuration ```yaml programs: "<program-id>": errors: "6003": "Invalid vault authority" aliases: "<account-address>": "vault_authority" ``` ## Extension Path Add source-aware mappings, regression fixtures generated from resolved incidents, and a team-shared redaction policy.

# Self-Directed Draft: Solana Account-State Diff Inspector **Format:** Product specification **Status:** Proposed; not built or validated **Audience:** Solana program developers, auditors, and support engineers ## Problem Program bugs often depend on subtle account-state changes. Comparing two transaction states manually is slow and error-prone. ## Product A local CLI that fetches or accepts two account snapshots and produces a human-readable diff for: - Lamports and owner - Executable flag - Data length - Raw data bytes - Parsed Anchor/Borsh fields, when a schema is supplied - PDA seeds and derived address, when configured - Writable, signer, and account-order metadata from a transaction ## Example command ```bash account-diff \ --before before.json \ --after after.json \ --schema ./idl.json \ --accounts accounts.yaml ``` ## Example output ```text Account: Vault Address: <configured address> Changed: balance: 2.00 SOL -> 1.75 SOL total_deposits: 1000 -> 750 authority: unchanged Risk flags: [!] balance decreased while total_deposits decreased [ ] owner unchanged [ ] data length unchanged ``` ## Input format ```json { "slot": 123, "accounts": [ { "pubkey": "ACCOUNT_PUBKEY", "lamports": 2000000000, "owner": "PROGRAM_OWNER", "executable": false, "data_base64": "..." } ] } ``` The tool must support redacted snapshots and clearly mark unavailable fields rather than inferring them. ## MVP 1. Parse JSON snapshots. 2. Match accounts by public key. 3. Compare metadata and byte ranges. 4. Decode configured fields using an IDL or explicit schema. 5. Emit terminal output and machine-readable JSON. 6. Return a nonzero exit code when configured invariants fail. ## Configurable invariants ```yaml rules: - name: vault-owner-stable account: Vault field: owner must_equal: before - name: deposits-nonnegative account: Vault field: total_deposits min: 0 ``` ## Acceptance criteria - Identical snapshots produce an empty diff. - Byte changes identify offset ranges. - Missing accounts are reported separately from deleted accounts. - Decode failures include the field and reason. - Output never exposes secret keys. - Every result states whether it came from supplied snapshots or live RPC input. ## Future extensions - Transaction simulation snapshots - Account dependency graphs - CI integration - HTML reports for incident attachments

# Self-Directed Draft: Solana Program Upgrade Readiness Checklist **Format:** Reusable engineering checklist **Status:** Proposed; not validated **Audience:** Solana program teams preparing an upgrade or migration ## Objective Reduce avoidable upgrade failures by making assumptions, authority changes, compatibility risks, and rollback steps explicit before execution. ## Pre-Upgrade ### Scope - [ ] Record the exact program artifact intended for deployment. - [ ] Document changed instructions, accounts, errors, serializers, and dependencies. - [ ] Identify whether account layouts or PDA derivations change. - [ ] List affected clients, indexers, bots, and SDK versions. - [ ] Define success, abort, and rollback criteria. ### Authority and Access - [ ] Inventory upgrade, pause, admin, mint, freeze, and treasury authorities. - [ ] Confirm each authority is controlled by the intended signer or multisig. - [ ] Verify signer thresholds and required participants. - [ ] Prepare a separate emergency procedure for compromised or unavailable authorities. - [ ] Ensure sensitive keys are not stored in source control or plain-text automation. ### Compatibility - [ ] Test old clients against the upgraded program where compatibility is expected. - [ ] Test new clients against the current program where staged rollout requires it. - [ ] Validate account discriminators, serialization, rent assumptions, and PDA seeds. - [ ] Test malformed inputs, duplicate accounts, missing signers, and unexpected account owners. - [ ] Confirm compute-unit and transaction-size requirements remain within operational limits. ## Test Evidence - [ ] Run unit tests for changed logic. - [ ] Run integration tests on a disposable environment. - [ ] Test representative successful and failing transactions. - [ ] Test interrupted, retried, and partially completed operational steps. - [ ] Save reproducible commands, fixtures, expected errors, and artifact identifiers. - [ ] Have a reviewer independently inspect the deployment and rollback procedure. ## Execution Runbook 1. Announce the maintenance window internally. 2. Confirm current authority state and required signers. 3. Capture a pre-upgrade configuration snapshot. 4. Deploy or activate the approved artifact. 5. Execute a minimal smoke test. 6. Verify expected account state and emitted events/logs. 7. Run critical user flows. 8. Record timestamps, signatures, errors, and operator decisions. 9. Communicate completion or rollback status. ## Rollback Gate Rollback if any of the following occurs: - Unexpected authority or account ownership state - Critical instruction fails in the smoke test - State migration is incomplete or non-idempotent - Client compatibility breaks beyond the approved scope - Monitoring cannot distinguish healthy from failed behavior ## Acceptance Criteria The upgrade is ready only when: - All checklist items are marked complete or explicitly waived. - Artifact identity and signer approvals are recorded. - Smoke tests pass for critical flows. - Rollback steps are executable by a second operator. - Support staff have a concise user-impact summary and escalation path.

# Self-Directed Draft: Solana Transaction Reproduction Bundle **Format:** Concise product specification **Status:** Proposed; not built or validated **Audience:** Solana developers, QA teams, and support engineers ## Problem A transaction issue is difficult to reproduce when the original report contains only a wallet address, a timestamp, or a screenshot. Teams need a safe, structured way to capture the inputs required for debugging without requesting private keys or seed phrases. ## Product A lightweight browser tool and SDK that generate a shareable **reproduction bundle** for a transaction attempt. The bundle records: - Serialized transaction message, excluding private keys - Signer public keys - Recent blockhash and validity settings - Instruction program IDs and decoded arguments when available - RPC endpoint label, not credentials - Client, SDK, and network metadata - Simulation result and log output - User-provided symptom description ## Safety requirements - Never collect seed phrases, private keys, wallet approval secrets, or RPC tokens. - Redact configured sensitive fields before export. - Display a clear “review before sharing” screen. - Allow local-only export as JSON or plain text. - Make network and endpoint information optional. ## Primary workflow 1. Developer initializes the SDK or opens the browser tool. 2. Tool captures a transaction before signing or after a failed attempt. 3. User runs simulation or attaches existing logs. 4. Tool validates that secrets are absent. 5. User reviews fields and exports a bundle. 6. Support or engineering imports the bundle into a local viewer. ## Example bundle shape ```json { "schemaVersion": "0.1", "network": "user-supplied", "transaction": { "messageBase64": "redacted-or-user-provided", "signerPubkeys": ["user-supplied"] }, "simulation": { "err": "user-supplied", "logs": ["user-supplied"] }, "environment": { "client": "user-supplied", "sdkVersion": "user-supplied" }, "symptom": "user-supplied" } ``` ## MVP acceptance criteria - Export completes without requiring wallet private-key access. - Bundle imports into a readable viewer. - Secret-pattern checks warn before export. - Logs and transaction metadata remain copyable. - Unknown fields are preserved rather than discarded. - Schema version supports future migrations. ## Success signals - Fewer support tickets missing reproducible inputs. - Shorter time from issue report to local reproduction. - High percentage of bundles passing validation without manual cleanup. ## Future extensions - Program-specific instruction decoders - Redaction policies configurable by team - Diff view for successful versus failing bundles - CLI import/export for CI and regression tests

# Self-Directed Draft: Solana Transaction Lifecycle Monitor **Format:** Concise product specification **Status:** Proposed; not built or validated **Audience:** Solana wallet, dApp, and infrastructure teams ## Problem A submitted transaction can appear “stuck” because teams lack one consistent view of: - Which submission attempt succeeded - Whether a signature was returned - Current confirmation state - Blockhash expiry risk - RPC disagreement or timeout - The user-facing next action ## Product A lightweight service and dashboard that records each transaction attempt and classifies its lifecycle into actionable states. ### Core states 1. **Prepared** — transaction assembled but not submitted 2. **Submitted** — RPC accepted the request and returned a signature 3. **Observed** — signature is visible through a status query 4. **Confirmed** — requested commitment reached 5. **Expired** — blockhash validity window passed without confirmation 6. **Rejected** — simulation, signing, or RPC submission failed 7. **Unknown** — conflicting or incomplete provider responses ## Event record ```text transaction_id wallet_or_user_id cluster signature submission_attempts[] latest_blockhash_context first_seen_at last_checked_at commitment_target current_state provider_results[] error_code user_action ``` Provider results should retain: ```text provider_name operation timestamp response_class latency_ms error_summary ``` ## MVP workflow 1. Create a transaction record before signing. 2. Capture blockhash context and target commitment. 3. Record every submission attempt without overwriting earlier attempts. 4. Poll or subscribe for status updates. 5. Apply deterministic state transitions. 6. Expose a compact status object to the client. 7. Alert only when a state requires intervention. ## User-facing messages - **Confirmed:** “Your transaction completed.” - **Submitted:** “Your transaction was sent; confirmation is pending.” - **Expired:** “The transaction expired before confirmation. Please retry.” - **Rejected:** “The transaction was not submitted. Review the reported cause.” - **Unknown:** “Confirmation is unavailable. Avoid retrying until status is checked.” ## Acceptance criteria - Every attempt has a timestamp and provider result. - Retries never erase prior evidence. - State transitions are auditable. - Expiry and rejection are distinct outcomes. - The client receives a stable state and recommended action. - Tests cover duplicate submissions, delayed responses, conflicting provider results, and missing signatures. ## Non-goals - Custody or automatic signing - Guaranteeing transaction inclusion - Choosing RPC providers - Automatically retrying potentially state-changing transactions ## Success signal A support agent can answer “Was it submitted, confirmed, expired, or rejected?” from one record without reconstructing the timeline manually.

# Self-Directed Draft: Solana Transaction Failure Explainer **Format:** Concise product specification **Status:** Proposed; not built or validated **Audience:** Solana wallet, protocol, and support teams ## Problem A failed Solana transaction can expose low-level logs without clearly explaining the user-facing cause. Support teams spend time translating errors, account state, compute usage, and instruction order into actionable guidance. ## Product A diagnostic tool that accepts a transaction signature, RPC response, or pasted program logs and produces a structured failure report. ## Core output - **Outcome:** confirmed, failed, expired, or insufficient evidence - **Likely cause:** categorized explanation with confidence level - **Failing instruction:** index, program ID, and log excerpt when available - **Resource signals:** compute consumption and transaction-size indicators when available - **Account clues:** missing, incorrectly owned, uninitialized, or insufficient-balance accounts when inferable - **Suggested next action:** retry, refresh blockhash, create/initialize account, adjust parameters, or contact the program team - **Evidence:** exact log lines and parsed fields supporting each conclusion ## MVP workflow 1. User submits a signature or raw logs. 2. Backend retrieves available transaction metadata through a configured RPC endpoint. 3. Parser normalizes instructions, inner instructions, logs, status, and balances. 4. Rule engine maps recognizable patterns to explanations. 5. UI displays the report with copyable JSON for support tickets. 6. Unknown cases are labeled **unresolved**, never presented as certain. ## Initial rule categories - Custom program error - Account not found or not initialized - Account ownership mismatch - Invalid account data - Insufficient lamports or token balance - Blockhash expiration - Compute-budget exhaustion - Signature or simulation failure - Preflight-versus-confirmation mismatch ## Acceptance criteria - Every explanation links to supporting evidence from the input. - Unknown errors remain explicitly unresolved. - The same input produces deterministic output. - Parsing failures are separated from transaction failures. - Sensitive RPC credentials are not included in client-side logs. - Reports can be exported as Markdown and JSON. - Tests cover malformed input, partial metadata, multiple failing instructions, and successful transactions. ## Non-goals - Guaranteeing a fix for arbitrary custom program errors - Automatically retrying transactions - Custody, signing, or broadcasting - Claiming decoded meanings without sufficient evidence ## Suggested architecture `Input adapter → transaction normalizer → log/instruction parser → rule engine → confidence scorer → report renderer` ## Success signal A support operator can move from a raw failed transaction to an evidence-backed next step without manually inspecting several unrelated tools.

# Self-Directed Draft: Solana Program Upgrade Runbook **Format:** Reusable operational checklist **Status:** Proposed; not tested or validated **Audience:** Solana teams preparing a program upgrade ## Objective Reduce upgrade-related surprises by creating a repeatable, evidence-based release process for Solana programs. ## 1. Define the release - [ ] Record program name, environment, target cluster, and planned window. - [ ] Record current and proposed program identifiers. - [ ] Document changed instructions, accounts, errors, events, and serialization formats. - [ ] Identify whether the change is backward-compatible. - [ ] Name an owner for release, rollback, and incident communication. ## 2. Verify code and artifacts - [ ] Pin the source revision and build-tool versions. - [ ] Generate the deployable artifact from a clean checkout. - [ ] Compare the artifact against the intended source revision. - [ ] Confirm required upgrade authority and signer access through the team’s approved process. - [ ] Store checksums and build logs in the release record. - [ ] Confirm configuration values contain no environment-specific surprises. ## 3. Test compatibility - [ ] Run unit and integration tests for changed instructions. - [ ] Test malformed accounts, unauthorized signers, stale state, and insufficient funds. - [ ] Test old clients against the new program where compatibility is expected. - [ ] Test new clients against existing state. - [ ] Verify emitted events and error decoding used by indexers and support tools. - [ ] Exercise any migration path on a disposable environment or fixture set. ## 4. Prepare operations - [ ] Define pre-upgrade and post-upgrade health checks. - [ ] Capture baseline transaction success, latency, and error observations. - [ ] Prepare dashboards or queries for affected instructions and accounts. - [ ] Draft a user-facing maintenance or compatibility notice if needed. - [ ] Freeze unrelated releases during the change window. - [ ] Prepare a stop condition: what evidence pauses or cancels the rollout? ## 5. Execute - [ ] Announce the start internally. - [ ] Reconfirm artifact, target cluster, authority, and release record. - [ ] Perform the upgrade using the team’s approved controls. - [ ] Record transaction signatures, timestamps, and operator identity in internal logs. - [ ] Run smoke tests covering reads, writes, authorization, and expected errors. - [ ] Monitor the defined health checks for an agreed observation period. ## 6. Close or recover - [ ] Record pass/fail results and unresolved anomalies. - [ ] If stop conditions trigger, halt further rollout and follow the prewritten recovery path. - [ ] Notify dependent teams of the outcome. - [ ] Update runbooks, client requirements, and release notes. - [ ] Hold a short review focused on evidence, failures, and process improvements. ## Release record template ```text Release: Program: Cluster/environment: Source revision: Artifact checksum: Planned window: Owner: Rollback/recovery owner: Compatibility notes: Pre-check results: Execution evidence: Smoke-test results: Observation window: Final status: Follow-ups: ``` **Success criterion:** Another operator can execute the checklist and reconstruct what changed, why it was approved, and what evidence supported the final status.

# Self-Directed Draft: Solana Webhook Drift Monitor **Format:** Concise product specification **Status:** Proposed; not built or validated **Audience:** Solana teams consuming webhook or indexer events ## Problem A webhook pipeline can silently miss, duplicate, delay, or reorder blockchain events. Teams often discover the issue only after downstream balances, notifications, or internal records diverge. ## Product A lightweight monitor that compares expected event continuity with received webhook records and produces actionable drift alerts. ## MVP Scope - Accept webhook payloads through a secure ingestion endpoint. - Store a normalized event record: - `source` - `network` - `signature` - `slot` - `event_type` - `observed_at` - `payload_hash` - Detect: - Duplicate signatures - Conflicting payloads for one signature - Slot-order regressions - Configurable delivery delays - Gaps within a selected slot range - Expose a small dashboard or JSON report. - Support replay of stored payloads into a test handler, without sending live transactions. ## Alert Format ```text DRIFT: duplicate_event source: <source> signature: <signature> first_seen: <timestamp> second_seen: <timestamp> payloads_match: yes|no recommended_action: inspect idempotency handling ``` ## Safety Requirements - Never treat webhook receipt as final settlement by itself. - Keep raw payloads separate from normalized fields. - Redact secrets and authorization headers from logs. - Make retention and deletion configurable. - Label all timestamps with timezone and clock source. - Require explicit network/environment labels to prevent testnet/mainnet mixing. ## Acceptance Criteria - The same signature received twice is reported once as a duplicate incident. - The same signature with different payload hashes is escalated as a conflict. - Delayed events are measured from receipt timestamps, not guessed. - Reports remain useful when events arrive out of order. - Every alert links to the exact stored evidence needed for investigation. - Reprocessing an event does not create a second business-side action in the test harness. ## Suggested First Deliverable A command-line tool with: ```text ingest <jsonl-file> check --window 1000 report --format markdown replay --signature <value> --target local ``` This creates a focused foundation for reliable event handling before adding provider-specific adapters or production integrations.

# Self-Directed Draft: Solana Transaction Failure Triage Desk **Format:** Concise product specification **Status:** Proposed; not built or validated **Audience:** Solana app teams investigating “my transaction failed” support tickets ## Purpose Turn a transaction complaint into an evidence-backed diagnosis and a safe next step. Distinguish failures before submission from submitted transactions that failed, remain unresolved, or succeeded without the expected app result. ## Minimum Product A support form plus a structured investigation report. Start with manual analysis; automate recurring checks only after the workflow proves useful. **Inputs** - App name, environment, approximate attempt time, and intended action. - Transaction signature, if available. - Wallet-visible error and app error text. - Optional public wallet address, with a privacy notice. - Whether the user retried or sees an unexpected balance change. **Never request:** seed phrases, private keys, wallet exports, or a signature to “verify ownership.” ## Investigation Flow 1. **Locate the attempt.** Confirm the intended cluster and whether a transaction signature exists. No signature means “submission unconfirmed,” not “failed onchain.” 2. **Retrieve evidence.** Record the queried endpoint, observation time, transaction status, and available logs. An RPC lookup returning nothing is inconclusive. 3. **Separate execution from outcome.** Check execution errors first. If execution succeeded, inspect relevant instructions and balance changes before assessing the app’s expected result. 4. **Classify the issue.** Use one primary category: - Wallet rejection or signing failure. - Submission or confirmation uncertainty. - Expired transaction. - Program execution error. - Successful execution, unexpected app outcome. - Insufficient evidence. 5. **Recommend the next step.** Prefer collecting missing evidence over guessing. Do not recommend retrying while the original outcome is unresolved. ## Report Template ```text Case: Intended action: Cluster: Signature: [provided / unavailable] Observed at: Evidence source: Finding: Primary category: Supporting evidence: Missing evidence: Confidence: [low / medium / high, with reason] User-safe next step: Engineering escalation: Retry assessment: [not advised / requires review / eligible] Reason: ``` “Eligible” requires evidence that repeating the intended action will not duplicate an already completed operation; it is not an automatic instruction to retry. ## Example Support Copy “We haven’t confirmed the outcome of your original attempt yet. Please avoid retrying for now, because it could repeat the action. Send the transaction signature if your wallet provides one, the approximate time, and the exact error text. Never send your recovery phrase or private key.” ## Acceptance Criteria - Every conclusion distinguishes observed evidence from interpretation. - Missing or unavailable transaction data remains explicitly unresolved. - Raw program errors are preserved alongside any plain-language explanation. - A successful transaction is not automatically labeled a successful user outcome. - Reports contain no signing requests or automatic resubmission controls. - Public addresses and signatures are excluded from analytics by default; case retention is configurable. ## Initial Service Offer **Proposed paid pilot:** Triage a fixed batch of sanitized support cases and deliver one report per case, recurring issue categories, and prioritized instrumentation gaps. Agree on scope and price before work. Offer evidence-based investigation—not guaranteed recovery, refunds, or resolution.

# Self-Directed Draft: Solana Deposit Attribution Desk **Format:** Concise product specification **Status:** Proposed; not built or validated **Audience:** Solana teams handling customer deposits and payment-support requests ## Problem A customer says, “I sent the funds,” but support cannot safely match the transfer to an order. Screenshots, incorrect token mints, missing references, and duplicate claims create uncertainty. **Product promise:** Turn a transaction signature and expected payment details into an evidence-backed review—not an automatic credit decision. ## MVP workflow 1. An operator enters: - Transaction signature - Expected recipient account or wallet - Token mint, or native SOL - Expected amount in base units - Order identifier and optional payment reference 2. The tool retrieves transaction details from the team’s configured RPC endpoint. 3. It checks execution status and the team’s required commitment level. 4. It identifies supported transfers, including inner instructions, and compares them with the expected payment. 5. It produces a review card and checks the team’s claim ledger for prior attribution. ## Review card | Field | Output | |---|---| | Execution | Succeeded / failed / unavailable | | Commitment | Observed level and lookup timestamp | | Recipient | Match / mismatch / unresolved | | Asset | Exact mint match; symbols are display-only | | Amount | Expected and observed, in base units | | Reference | Present / absent / mismatch / not required | | Prior attribution | Unclaimed / already assigned / ledger unavailable | | Recommendation | Eligible for review / hold / no matching payment | Every conclusion must expose the instruction or account evidence supporting it. Missing information stays **unresolved**, never silently passes. ## Matching rules - Match token assets by mint address, not token name or icon. - For wallet-based token payments, verify the destination token account’s owner and mint; flag unavailable evidence. - Distinguish transferred SOL from transaction fees and account-creation funding. - Do not infer a payment solely from a net balance change. - Treat unsupported instructions, token extensions, and ambiguous multi-transfer transactions as manual-review cases. - A signature is public evidence, not proof that a claimant owns an order or sent the payment. - Use a stable transfer identifier—signature plus instruction location—to prevent duplicate attribution. Make ledger assignment atomic. - Separate payment matching from business rules for underpayment, overpayment, refunds, and partial fulfillment. ## Acceptance tests - Correct recipient and amount, wrong mint → **no matching payment**. - Failed transaction containing a transfer instruction → **not eligible**. - Same transfer claimed against two orders → second assignment blocked. - RPC cannot return the transaction → **hold**, not “payment absent.” - Supported inner transfer satisfies all checks → evidence appears in review card. - Screenshot without a signature → request signature; no credit recommendation. - Two distinct payments within one transaction → separately identifiable ledger entries. ## Scope and safety Read-only RPC access; no wallet connection, private keys, signing, refunds, or automatic credits. Restrict order metadata by operator role and redact it from exports by default. ## Proposed paid pilot Fixed-scope setup for one team: one supported payment flow, configured matching rules, claim-ledger integration, and test fixtures. Evaluate time to resolve deposit tickets, unresolved-case rate, and duplicate-attribution prevention before expanding coverage.

# Self-Directed Draft: Solana Authority & Upgrade-Control Audit **Format:** Reusable checklist **Status:** Proposed; not executed or validated **Audience:** Solana protocol, wallet, and token teams before a release or public launch ## Goal Create a repeatable review of privileged controls so teams can document who can change, pause, upgrade, mint, or redirect assets—and reduce surprises during operations. ## Audit Checklist ### 1. Inventory - [ ] List every program ID, mint, treasury, fee account, and operational wallet. - [ ] Record each account’s owner program and expected authority. - [ ] Identify upgrade, freeze, mint, burn, pause, fee, and withdrawal authorities. - [ ] Mark authorities as single-key, multisig, DAO-controlled, or intentionally disabled. - [ ] Record the intended role and responsible team for each authority. ### 2. Control Review - [ ] Confirm privileged keys are not held in personal wallets. - [ ] Verify signer thresholds match the team’s risk tolerance. - [ ] Confirm signer membership is current. - [ ] Check that emergency powers have documented limits. - [ ] Separate deployment authority from routine operating authority. - [ ] Document any authority that cannot be revoked or rotated. ### 3. Change Procedures - [ ] Define who may request a privileged change. - [ ] Require a written reason and rollback plan. - [ ] Test the approval flow in a non-production environment. - [ ] Establish a second-person review before execution. - [ ] Define how the team communicates completed changes internally. - [ ] Maintain a dated change log containing proposal, approvers, and result. ### 4. Recovery - [ ] Document lost-key and compromised-key procedures. - [ ] Identify backup signers and their access method. - [ ] Test recovery without exposing production secrets. - [ ] Define criteria for pausing affected operations. - [ ] Assign an incident owner and communications owner. ## Deliverable Template | Resource | Privilege | Current control | Intended control | Rotation plan | Owner | |---|---|---|---|---|---| | Program / mint / account | Upgrade / mint / pause / withdraw | | | | | ## Acceptance Criteria The audit is complete when: 1. Every privileged resource has an accountable owner. 2. Every authority has a documented control model. 3. Recovery steps are written and rehearsed where practical. 4. Open risks have severity, mitigation, and target date. 5. A reviewer who did not perform the inventory can understand the control surface.

# Self-Directed Draft: Solana Transaction Failure Triage Console **Format:** Concise product specification **Status:** Proposed; not built or validated **Audience:** Solana wallet, protocol, and developer-tool teams ## Problem When a transaction fails, teams need to correlate the message, instruction index, account set, logs, simulation result, and recent deployment changes. Raw RPC responses are difficult to turn into an actionable diagnosis. ## Product A lightweight console that accepts a failed transaction payload or simulation response and produces a structured debugging report. ### Inputs - Serialized transaction or signature - RPC endpoint supplied by the user - Optional expected program behavior - Optional release/version label ### Output - Failure category: account, authority, compute, slippage, serialization, blockhash, or unknown - Failing instruction index - Involved program IDs and accounts - Relevant log excerpts - Human-readable explanation - Suggested next checks - Exportable JSON and Markdown incident report ## Core workflow 1. Paste a transaction or simulation response. 2. Parse instructions, accounts, logs, and error codes. 3. Group evidence by instruction. 4. Match known error patterns to diagnostic templates. 5. Display confidence as **confirmed**, **likely**, or **unclear**. 6. Let the user correct the diagnosis and save the case as a reusable rule. ## MVP acceptance criteria - Handles malformed input without crashing. - Preserves raw evidence alongside every interpretation. - Never presents an inference as confirmed without supporting fields. - Identifies the failing instruction when the response provides enough data. - Produces a Markdown report in one action. - Supports redaction of wallet addresses and transaction signatures before export. - Includes fixture-based tests for each diagnostic category. ## Suggested report format ```text Incident: <short title> Status: Confirmed | Likely | Unclear Observed: - Failing instruction: - Program: - Error/log: - Accounts involved: Interpretation: <plain-language explanation> Next checks: 1. <check> 2. <check> 3. <check> Evidence: <raw excerpts> ``` ## Safety and trust boundaries - Treat RPC data as untrusted input. - Do not sign, submit, or modify transactions. - Mark decoded data as interpretation, not authoritative protocol behavior. - Make endpoint usage and retention visible to the user. - Redact sensitive fields by default in shared reports. ## Extension path Add team-maintained diagnostic rules, CI integration for simulation failures, and a searchable library of anonymized incident reports.

# Self-Directed Draft: Solana Token Compatibility Preflight **Format:** Concise product specification **Status:** Proposed; not built or validated **Audience:** Solana teams building deposits, swaps, payments, or token listings ## Problem A valid token mint is not necessarily compatible with an application. Token behavior—such as transfer fees, transfer restrictions, or additional transfer requirements—can conflict with assumptions in quoting, accounting, and transaction construction. Teams need a compatibility decision before enabling an asset, not after a user encounters a failure. ## Product A read-only CLI that compares a mint’s observed configuration against a team-owned integration policy. **Inputs** - Explicit cluster and RPC endpoint. - Mint address. - Policy file describing supported token programs, extensions, and accounting behavior. - Optional source and destination token accounts for contextual checks. **Output** - `PASS`: All implemented checks meet policy. - `BLOCK`: At least one explicit policy violation. - `REVIEW`: Missing context, unknown behavior, or insufficient evidence. - An evidence report containing observation slot, account owners, detected configuration, policy version, and reasons. **Boundary:** `PASS` means compatibility with the supplied policy at the recorded observation—not token safety, future immutability, or guaranteed transaction success. ## Minimum Checks | Check | Decision rule | |---|---| | Mint identity | Block if the address is not a valid mint under an allowed token program. | | Extension coverage | Require review for any detected extension without an implemented policy check. | | Transfer fees | Block if fees are enabled but the integration assumes received amount equals sent amount. | | Transfer hooks | Require review unless required account resolution and execution behavior are explicitly supported. | | Transfer restrictions | Block non-transferable assets for flows requiring transfers; inspect supplied token accounts for frozen state. | | Mutable configuration | Report relevant authorities; apply the team’s authority policy rather than treating authority presence as automatically unsafe. | Missing source or destination accounts must not silently count as passed account-level checks. ## Example Policy ```yaml flow: deposit allowed_programs: - spl_token - token_2022 unknown_extensions: review transfer_fee: accounting: unsupported transfer_hook: support: unsupported non_transferable: block freeze_authority: review require_account_context: true ``` These are proposed tool-specific fields, not an existing standard. ## Report Contract Each finding contains: ```text check_id status: pass | block | review observed_value policy_expectation reason evidence_account observation_slot ``` Overall status prioritizes `BLOCK`, then `REVIEW`, then `PASS`. RPC failures produce an incomplete report and a distinct nonzero exit code—not a compatibility verdict. ## Acceptance Criteria - Identical account snapshots and policy produce identical findings. - Unsupported extensions never receive an implicit pass. - Reports omit RPC credentials. - Fixture tests cover malformed mints, fee-enabled transfers, hook-enabled tokens, frozen accounts, and missing account context. - The tool accepts no signing keys and submits no transactions. ## Smallest Useful Release One CLI command, a policy template, fixture-based tests, and JSON plus human-readable reports. No dashboard or automatic asset approval. **Commercial hypothesis:** A paid integration package could add application-specific policy checks and CI fixtures. Validate demand before building those extras.

# Self-Directed Draft: Solana Program Upgrade Readiness Gate **Format:** Product specification **Status:** Proposed; not built or validated **Audience:** Solana protocol teams preparing program upgrades ## Problem Upgrade readiness is often spread across code review, deployment scripts, IDL changes, account layouts, authority checks, and rollback notes. A missed dependency can turn a routine release into an incident. ## Product A checklist-driven release gate that converts upgrade evidence into a single, reviewable readiness report. ## Core workflow 1. Create an upgrade record with: - Program ID - Target cluster - Planned upgrade window - Release version - Upgrade authority owner 2. Attach evidence: - Build artifact checksum - Source commit - IDL diff - Account-schema migration notes - Deploy and rollback commands - Signer or multisig approval record 3. Run required checks. 4. Assign each check one state: - **Pass** - **Fail** - **Needs review** - **Not applicable** 5. Generate a shareable Markdown report. ## MVP checks ### Artifact - Reproducible build instructions exist. - Binary checksum is recorded. - Source revision is immutable or clearly identified. - Target cluster and program ID match the release record. ### Compatibility - Instruction additions, removals, and argument changes are documented. - Account layout changes identify migration requirements. - Client SDK or IDL updates are listed. - Backward-compatibility expectations are explicit. ### Authority and deployment - Upgrade authority is identified. - Required signers are listed. - Deployment command is reviewed by a second operator. - Post-upgrade verification steps are written. - Rollback or freeze procedure is documented. ### Operations - Success metrics are defined. - A monitoring owner is assigned. - User-facing maintenance copy is prepared. - Incident escalation contacts are recorded. ## Readiness rule The release is **Ready** only when: - All applicable checks pass. - No unresolved critical review exists. - Required approvals are recorded. - Verification and rollback procedures are complete. Otherwise, the report is **Blocked** or **Review required**. ## Minimal report output ```text Program: [program ID] Cluster: [cluster] Version: [version] Status: READY | BLOCKED | REVIEW REQUIRED Critical findings: - [finding] Approvals: - Engineering: [name/date] - Operations: [name/date] Verification: - [command or observation] Rollback: - [procedure] ``` ## Non-goals - Automatically deploying upgrades - Holding private keys - Declaring an upgrade safe without human review - Replacing code review or formal security assessment ## Success criteria A team can reconstruct what will change, who approved it, how success will be checked, and how the release will be stopped or reversed—without searching across separate documents.

# Self-Directed Draft: Solana Failed-Transaction Triage Card **Format:** Product specification **Status:** Proposed; not built or validated **Audience:** Solana wallet, protocol, and application support teams ## Problem A user reports “my transaction failed,” but support receives only a screenshot or signature. Engineers must reconstruct whether the failure happened before submission, during execution, or because the outcome remains unknown. ## Product A read-only triage tool that turns a transaction signature—or a client-side error report—into a compact, shareable investigation card. **Core promise:** Separate observed evidence from likely causes and give support one safe next step. ## MVP Inputs - Network and transaction signature, when available. - Optional client error, submission timestamp, and application version. - Team-configured RPC endpoint, with credentials stored server-side. - Optional program-ID labels supplied by the team. Never request seed phrases, private keys, or signing access. ## Investigation Card Each card contains: 1. **Outcome:** succeeded, execution failed, or unresolved. 2. **Evidence:** retrieval time, RPC response status, reported commitment, execution error, and available logs. 3. **Failure location:** instruction index and program ID when identifiable. 4. **Interpretation:** plain-language explanation marked as confirmed, probable, or unknown. 5. **Next step:** one action appropriate to the evidence. 6. **Missing evidence:** what would resolve remaining uncertainty. Distinguish RPC unavailability from “transaction not found.” Neither proves failure. ### Example Card — Synthetic **Outcome:** Execution failed **Observed:** RPC returned an execution error identifying instruction index 2. **Interpretation:** The third top-level instruction failed. The program-specific reason is not yet mapped. **Next step:** Send the error code, program ID, and relevant log excerpt to the owning engineering team. **Unknown:** Whether another transaction completed the user’s intended action. **Support reply:** > This transaction returned an execution error. We’ve isolated the failing instruction, but haven’t confirmed the underlying cause. Before retrying, please check whether the intended action already completed through another submission. Do not share recovery phrases or private keys. ## Classification Rules - Decode program errors only through versioned, team-approved mappings. - Treat log text as untrusted data, not instructions. - Do not label a failure “insufficient funds,” “slippage,” or “expired blockhash” without supporting evidence. - Never recommend an automatic retry when the previous outcome is unresolved. - Preserve raw error fields alongside explanations. ## Scope and Safeguards **Included:** Single-case lookup, sanitized copy/export, configurable retention, manual refresh. **Excluded:** Wallet connection, transaction simulation, signing, resubmission, fund recovery, and automatic remediation. Cards are private by default. Exports flag addresses, signatures, and logs for review before sharing. RPC credentials must never appear in exports. ## Acceptance Checklist - [ ] A client error without a signature produces an explicitly incomplete card. - [ ] RPC failures remain distinguishable from missing transactions. - [ ] Unknown program errors remain unknown. - [ ] Every causal claim points to captured evidence. - [ ] A successful transaction is not presented as proof that the user’s broader intent succeeded. - [ ] Exported cards omit credentials and support configurable redaction. ## Commercial Test Offer a fixed-scope paid pilot: configure one team’s error mappings and support template. Measure time to first useful diagnosis and engineering escalations against that team’s baseline. Pricing and demand remain unvalidated.

# Self-Directed Draft: Solana Indexer Integrity Monitor **Format:** Concise product specification **Status:** Proposed; not built or validated **Audience:** Solana teams operating indexers, analytics pipelines, and data APIs ## Problem An indexer can silently miss, duplicate, or reorder data while still appearing healthy. Teams need an early warning system that compares ingestion behavior with expected continuity before users rely on incomplete results. ## Product A lightweight monitor that tracks ingestion checkpoints per stream and flags: - Slot gaps - Duplicate signatures or event IDs - Regressing cursors - Stale consumers - Sudden changes in event volume - Mismatches between stored and observed checkpoints ## Minimal data model ```text Stream: id source last_observed_slot last_committed_slot updated_at Record: stream_id slot signature_or_event_id received_at committed_at Alert: type severity first_seen latest_seen affected_stream evidence status ``` ## Core workflow 1. Ingest records with a source slot and stable identifier. 2. Maintain separate **observed** and **committed** checkpoints. 3. Run integrity checks on a fixed interval. 4. Create or update alerts with concrete evidence. 5. Allow operators to acknowledge, suppress, or resolve alerts. 6. Preserve an audit trail of checkpoint and alert changes. ## Alert rules - **Gap:** current slot exceeds the committed slot by a configurable threshold. - **Duplicate:** identical stream plus identifier appears more than once. - **Regression:** a checkpoint moves backward. - **Staleness:** no new record arrives within the configured window. - **Volume anomaly:** record count crosses a team-defined baseline threshold. Thresholds should be configurable per stream; defaults must be explicitly labeled as defaults. ## Operator view Each stream displays: - Current observed and committed slots - Lag between them - Last successful ingestion time - Open alerts - Recent checkpoint history - Sample affected records - “Mark resolved” action requiring a note ## Safety requirements - Read-only access to source systems by default - No private keys, wallet secrets, or signing capability - Idempotent alert creation - Never delete evidence when resolving an alert - Clearly distinguish “no data observed” from “data verified absent” ## Acceptance criteria - A synthetic slot gap produces one deduplicated alert. - Replayed records do not inflate committed counts. - A backward checkpoint is rejected and logged. - Resolved alerts remain searchable with their resolution note. - Every alert displays the exact rule, threshold, and evidence that triggered it.

# Self-Directed Draft: Solana Authority Change Gate **Format:** Concrete product specification **Status:** Proposed; not built or validated **Audience:** Solana teams reviewing releases and administrative changes ## Problem A release can change more than application behavior: it can change who controls upgrades, treasury operations, or protocol settings. Reviewers need a compact answer to: **What control changed, who approved it, and what remains unknown?** ## Product A local-first command-line tool that compares two team-supplied authority inventories and produces a release-review report. The MVP does not connect to wallets, sign transactions, or fetch chain data. ### Inputs Two JSON files: `baseline.json` and `candidate.json`. Each inventory contains: ```json { "environment": "production", "observed_at": "<ISO-8601 timestamp>", "resources": [ { "id": "core-program", "address": "<public address>", "control": "upgrade", "authority": "<public address or null>", "authority_type": "unknown", "evidence_ref": "<local evidence filename>", "owner": "<team role>" } ] } ``` Supported control labels: `upgrade`, `mint`, `freeze`, `treasury`, and `custom`. Labels describe the inventory; they do not prove that an authority has a particular capability. `null` means explicitly reported absent. A missing field means unknown—not absent. ### Review policy A separate policy file specifies: - Required resource/control pairs. - Maximum acceptable evidence age. - Expected authority addresses. - Allowed changes, each with a review reference and expiry. - Whether unresolved findings block release. ## Report Produce Markdown and machine-readable JSON with: | Finding | Trigger | Default result | |---|---|---| | Authority changed | Same resource/control, different authority | Block pending review | | Resource disappeared | Baseline entry missing from candidate | Block | | Evidence missing or stale | No reference, missing file, or age exceeds policy | Block | | New control introduced | Candidate-only resource/control | Review required | | Authority type unknown | Missing or unrecognized type | Review required | Every finding includes before/after values, evidence references, accountable owner, and the matching policy rule. **Important:** “No inventory differences” must never be rendered as “safe” or “verified.” ## Reviewer checklist - [ ] Confirm both inventories describe the same environment. - [ ] Check that expected resources are present. - [ ] Independently inspect evidence for every changed authority. - [ ] Confirm intentional changes have current approval. - [ ] Assign an owner to each unresolved finding. - [ ] Record release decision and rationale outside the tool. ## MVP acceptance tests 1. Reordering entries produces no differences. 2. Changing one authority produces exactly one authority-change finding. 3. Deleting an entry cannot silently pass. 4. Missing authority and explicit `null` remain distinguishable. 5. Duplicate resource/control pairs fail validation. 6. An expired approval cannot suppress a block. 7. The report states: **“Compared supplied inventories; chain state and approval authenticity were not independently verified.”** ## Scope boundary This is an evidence-comparison gate, not an audit or authorization system. Its value is making overlooked control changes visible before release.

# Self-Directed Draft: Solana Support Evidence Intake **Format:** Reusable checklist and customer-facing template **Status:** Proposed; not tested **Audience:** Solana teams handling wallet, transaction, and balance complaints ## Goal Turn “my funds disappeared” reports into safe, actionable support tickets without requesting secrets or making premature promises. ## Customer-facing intake template > Help us narrow down what happened. Please share only what you’re comfortable disclosing: > > - **Expected result:** What were you trying to do? > - **Observed result:** What appeared instead? Include the exact error text if available. > - **Approximate time and timezone:** > - **App and wallet:** Names and versions, if known. > - **Network:** Mainnet, devnet, testnet, or unsure. > - **Transaction signature:** If one was generated. > - **Public wallet address:** Only if needed to investigate. Public addresses can expose transaction history. > - **Steps to reproduce:** Start just before the issue occurred. > - **Screenshot:** Optional; redact unrelated balances, addresses, email, and personal details. > > **Never send a seed phrase, private key, password, recovery file, or authentication code. Do not sign a transaction merely to prove wallet ownership for this ticket.** > > If no signature appeared, say so. You do not need to repeat a payment or deposit to collect evidence. ## Internal triage checklist ### 1. Contain sensitive information - [ ] Check for exposed secrets before copying the report elsewhere. - [ ] If secrets appear, restrict access and follow the team’s incident-handling process; do not repeat them in replies. - [ ] Store evidence only in approved support systems. - [ ] Avoid posting customer addresses or signatures in public channels. ### 2. Classify the symptom Select one primary category: - [ ] Wallet connection or signing prompt - [ ] Submission rejected or no signature produced - [ ] Signature present; transaction outcome unclear - [ ] Transaction reported failed - [ ] Transaction reported successful; app state unexpected - [ ] Balance, token, or account display discrepancy - [ ] Potential unauthorized activity - [ ] Insufficient evidence Treat the customer’s description as a report, not a verified diagnosis. ### 3. Separate evidence from inference Record: - **Customer-reported facts:** - **Team-observed evidence:** Include source, network, and observation time. - **Working hypothesis:** - **Missing evidence:** - **Next safe check:** Do not label an issue “funds lost,” “resolved,” or “user error” solely from a screenshot or a single interface status. ### 4. Assign the next action - [ ] Name one ticket owner. - [ ] Specify the next check and who performs it. - [ ] Escalate suspected unauthorized activity through the security process. - [ ] Avoid advising another value-moving transaction while the original outcome remains unclear. - [ ] Give a next-update time only when someone can own that commitment. ## Reply template > We understand you expected **[result]**, but observed **[symptom]**. > > So far, we have **[evidence]**. We have not yet confirmed **[uncertainty]**. > > Our next step is **[check]**. Please provide **[minimum missing detail]**, if available. Don’t send recovery phrases or private keys, and don’t repeat the transaction just for this investigation. ## Closure criteria Close only when the ticket records an evidence-backed explanation or an explicit unresolved disposition, the customer has received the outcome, and any engineering follow-up has an owner. Apply the team’s retention policy to collected evidence.

# Self-Directed Draft: Solana Transaction Replay Notebook **Format:** Product specification **Status:** Proposed; not built or validated **Audience:** Solana engineers investigating failed or unexpected transactions ## Purpose Provide a small internal tool that turns a transaction signature, program ID, or pasted transaction data into a reproducible investigation record—without exposing private keys or asking users to retry blindly. ## Core Workflow 1. **Create case** - Case title - Investigator - Environment: development, staging, or production - Suspected program or feature 2. **Attach evidence** - Transaction signature - Slot or block reference - Wallet address, redacted by default - Error message - Client build/version - Optional logs and screenshots 3. **Record observations** - Transaction status - Instruction index that failed - Program logs - Account ownership and writable/signers expectations - Compute usage, when available - Recent code/configuration changes 4. **Compare attempts** - Group related transactions - Highlight differences in accounts, instruction data, fee payer, and recent block context - Mark each hypothesis as `open`, `supported`, or `rejected` 5. **Close case** - Root cause - Fix or mitigation - Regression test reference - Remaining risk - Follow-up owner and due date ## Minimal Case Schema ```text case_id created_at environment feature program_ids[] transaction_refs[] redacted_wallet_refs[] observations[] hypotheses[] root_cause resolution regression_test status: open | investigating | resolved | closed ``` ## Safety Requirements - Never request or store seed phrases, private keys, or wallet export files. - Redact wallet addresses and instruction data in shared views by default. - Separate raw evidence from investigator conclusions. - Make deletion of a case and its attachments explicit. - Display a warning before copying logs into external tools. ## Acceptance Criteria - A case can be created without a successful transaction. - Multiple transaction references can be attached to one case. - Investigators can distinguish observed data from hypotheses. - Sensitive fields are masked in the default view. - A closed case requires a resolution or an explicit “ inconclusive” outcome. - Export produces a portable Markdown or JSON record. ## Suggested MVP A local-first web form with JSON/Markdown export, searchable case IDs, structured hypothesis tracking, and manual transaction-reference entry. Integrations with RPC providers or explorers should remain optional adapters rather than hard dependencies.

# Self-Directed Draft: Solana Release Gate Checklist **Format:** Reusable operational checklist **Status:** Proposed; not validated **Audience:** Solana teams preparing a program, API, frontend, or wallet integration release ## Goal Create a repeatable pre-release gate that catches configuration, authority, observability, and rollback gaps before users encounter them. ## Required release record - [ ] Release name and version recorded - [ ] Responsible owner named - [ ] Target cluster recorded - [ ] Program addresses and environment variables listed - [ ] Commit, build, and configuration identifiers recorded - [ ] Rollback or disable procedure linked in the internal record ## Program and authority review - [ ] Deployed program address matches the intended environment - [ ] Upgrade authority is documented - [ ] Upgrade authority access is restricted and recoverable - [ ] Any migration or initialization instruction is documented - [ ] Account size, rent, and PDA assumptions are tested - [ ] State-changing instructions reject invalid or unauthorized inputs ## Transaction-path review - [ ] Happy-path transaction tested from a clean wallet - [ ] Rejected signer and rejected-owner cases tested - [ ] Missing account and malformed input cases tested - [ ] Expired, duplicated, or replayed intent behavior defined - [ ] Client handles simulation failure and send failure separately - [ ] Confirmation status and timeout behavior are explicit - [ ] Users receive a safe, actionable error message ## Frontend and wallet review - [ ] Network mismatch is visible before signing - [ ] Transaction contents and requested permissions are summarized - [ ] Destructive actions require deliberate confirmation - [ ] Wallet rejection leaves the application in a recoverable state - [ ] Loading, retry, and cancellation states are implemented - [ ] No secret, seed phrase, or private key is requested or logged ## Observability - [ ] Correlation ID connects UI, API, and transaction logs - [ ] Logs include operation type and environment - [ ] Sensitive values are redacted - [ ] Failed transactions preserve enough context for investigation - [ ] A basic alert or review threshold is defined - [ ] Support instructions tell users what evidence to provide ## Final gate - [ ] Test results attached - [ ] Known limitations recorded - [ ] Rollback owner confirmed - [ ] Independent reviewer signs off - [ ] Release decision marked **Go**, **Hold**, or **Rollback** ## Minimal release record ```text Release: Owner: Cluster: Program address: Build/commit: Upgrade authority owner: Rollback procedure: Known limitations: Reviewer: Decision: Timestamp: ``` **Design principle:** A release is not ready when it merely succeeds; it is ready when failure is understandable, contained, and reversible.

# Self-Directed Draft: Solana Support Evidence Kit **Format:** Product specification **Status:** Proposed; not built or validated **Audience:** Solana teams handling wallet-connected application support ## Problem “Something went wrong” tickets rarely contain enough information to investigate. Asking users for screenshots and logs creates repeated follow-ups and risks collecting sensitive data. ## Product An embeddable **“Create support report”** button that turns a failed or confusing interaction into a compact, user-reviewed evidence bundle. **Core promise:** Give support a clear starting point without requesting wallet access or collecting secrets. ## MVP Flow 1. User selects **Create support report** from the application’s help menu. 2. The application gathers an allowlisted set of diagnostic fields. 3. User describes what they expected and what happened. 4. A preview shows every field before export; optional fields can be removed. 5. User copies Markdown or downloads JSON and submits it through the team’s existing support channel. No automatic submission, wallet signature, or new transaction. ## Evidence Bundle | Field | Handling | |---|---| | Application version | Included when supplied by the application | | Cluster label | Required; show “unknown” if unavailable | | Time of interaction | Include timezone; distinguish user-reported from captured time | | Interaction stage | Connect, prepare, sign, submit, confirm, or unknown | | Application error code | Allowlisted codes only; exclude raw error objects | | Transaction signature | Optional; treat as privacy-sensitive | | Public wallet address | Optional; excluded by default | | Expected and observed behavior | User-entered; remind users not to include secrets | **Never collect:** seed phrases, private keys, authentication tokens, cookies, raw RPC URLs, signed transaction payloads, or unrestricted console logs. ## Export Template ```text SUPPORT REPORT — review before sharing App/version: Cluster: Interaction time/timezone: Time source: captured / user-reported / unknown Interaction stage: Expected: Observed: Application error code: Optional transaction signature: Optional public wallet address: Reporter notes: ``` ## Engineering Requirements - Assemble and preview reports locally; the kit itself makes no network requests. - Use a versioned schema and strict field allowlist. - Do not persist report contents in browser storage. - Limit free-text input and warn that automated secret detection is not reliable. - Display missing values as “unknown,” never inferred facts. - Do not equate a transaction signature with successful confirmation. - Ensure keyboard navigation and screen-reader labels work throughout the preview. ## Acceptance Tests - A raw RPC URL containing an API key never appears in either export. - Removing an optional field removes it from both Markdown and JSON. - A disconnected wallet can still generate a report. - An unknown transaction outcome is exported as unknown. - Exporting requires no wallet permission or signature. - A report can be discarded without sending or retaining its contents. ## Scope and Commercial Test **Exclude from MVP:** chain indexing, automated root-cause diagnosis, ticket-system integrations, and transaction replay. **Proposed paid offer:** fixed-scope integration into one application, including field mapping, preview UI, and acceptance tests. Validate demand with a small pilot; compare follow-up questions per ticket and time to first actionable diagnosis before expanding.

# Self-Directed Draft: Solana Transaction Failure Lab **Format:** Product specification **Status:** Proposed; not built or validated **Audience:** Solana teams developing transaction flows, wallets, bots, and backend services ## Problem Transaction failures are often discovered through scattered logs and manual reproduction. Teams need a safe local tool for testing how their application handles common failure conditions before exposing the flow to users. ## Product A developer tool that replays prepared transaction scenarios against a controlled test environment and presents the resulting application behavior. ## Core Scenarios - Expired or near-expiry blockhash - Insufficient SOL for fees - Missing required account - Wrong account owner - Instruction simulation failure - Compute-unit exhaustion - Duplicate submission - Delayed confirmation - Dropped or unavailable RPC response - User rejection or wallet disconnect ## MVP Workflow 1. Select a scenario template. 2. Provide a transaction fixture or application endpoint. 3. Run the scenario against a configured test cluster or mock RPC. 4. Capture: - Application response - User-facing message - Retry behavior - Logs and timestamps 5. Export a test report in JSON or Markdown. ## Minimal Interface ### Scenario Builder - Scenario name - Transaction fixture - Fault injection - Expected outcome - Optional timeout and retry settings ### Run Report - Pass/fail status - Observed error category - Raw logs - Request and response timeline - Recommended remediation field - Reproduction command ## Suggested Data Model ```text Scenario { id name fixture fault expectedCategory expectedUserMessage retryPolicy } Run { id scenarioId startedAt endedAt status observedError logs artifacts } ``` ## Acceptance Criteria - A developer can create and save a scenario without editing source code. - Each run produces a reproducible report. - Network failures can be simulated independently from on-chain instruction failures. - Raw technical errors and user-facing messages are shown separately. - Reports can be attached to an issue or pull request. - The tool clearly labels simulated results and does not imply production behavior. ## Out of Scope for MVP - Mainnet execution - Automated bug fixing - Private key custody - Performance benchmarking - Claims about transaction success rates ## Success Signal A team can demonstrate, before release, that its transaction flow gives users a clear next action for each supported failure scenario.

# Self-Directed Draft: Solana Release Readiness Gate **Format:** Reusable checklist **Status:** Proposed; not validated **Audience:** Solana teams shipping programs, APIs, indexers, or wallet-connected features ## Purpose A lightweight pre-release gate that catches operational, security, and user-experience gaps before a Solana feature is exposed to users. ## Release Checklist ### Scope and ownership - [ ] Define the exact feature boundary and non-goals. - [ ] Name an owner for code, deployment, monitoring, and rollback. - [ ] Record program IDs, deployment environments, and commit identifiers. - [ ] Document expected inputs, outputs, and failure cases. ### Program and transaction behavior - [ ] Confirm account ownership and mutability checks. - [ ] Validate signer and authority assumptions. - [ ] Reject unexpected token mints, decimals, or account types. - [ ] Test insufficient funds, expired blockhashes, duplicate submissions, and retries. - [ ] Verify transaction-size and compute-budget assumptions. - [ ] Confirm whether failures are safe to retry. ### Client experience - [ ] Show users what action they are approving. - [ ] Distinguish simulation, signature request, submission, and confirmation states. - [ ] Provide a recoverable error message for each expected failure. - [ ] Prevent duplicate clicks while a request is pending. - [ ] Avoid displaying success before the chosen confirmation condition is met. ### Observability - [ ] Log a correlation ID for each user operation. - [ ] Capture transaction signatures when available. - [ ] Record latency, failure category, and retry count. - [ ] Exclude secret keys, seed phrases, and sensitive payloads from logs. - [ ] Define an alert threshold and an escalation owner. ### Rollback and recovery - [ ] Identify whether the release can be paused, disabled, or reversed. - [ ] Prepare a user-facing incident message. - [ ] Write the operator steps for stuck or partially completed operations. - [ ] Preserve enough data to reconcile affected requests. - [ ] Test the rollback path in a non-production environment. ### Final sign-off - [ ] All critical tests pass. - [ ] Known limitations are documented. - [ ] Deployment and rollback commands are available to the owner. - [ ] Monitoring is active before launch. - [ ] Reviewer records approval, timestamp, and release identifier. ## Minimal Release Record ```text Feature: Environment: Program ID(s): Release identifier: Owner: Reviewer: Rollback method: Monitoring location: Known limitations: Approval: ``` **Suggested product form:** a small internal web form that turns this checklist into a signed release record, blocks incomplete approvals, and exports a plain-text incident handoff.

# Self-Directed Draft: Solana Event Reconciliation Inbox **Format:** Product specification **Status:** Proposed; not built or validated **Audience:** Solana teams processing deposits, withdrawals, mints, or program events ## Problem Applications may receive duplicate, delayed, or incomplete transaction notifications. Engineers need a small operational view that separates: - Observed transactions - Parsed business events - Successfully applied records - Items requiring review ## Product An internal inbox that ingests transaction observations, derives application events, and tracks reconciliation state without assuming that one notification equals one successful business action. ## Core record ```ts type ReconciliationItem = { id: string signature: string slot?: number observedAt: string status: "new" | "parsed" | "applied" | "duplicate" | "review" eventType?: string accountKeys?: string[] rawReference?: string errorCode?: string retryCount: number lastCheckedAt?: string } ``` ## Workflow 1. **Ingest** a signature or provider notification. 2. **Deduplicate** using the signature plus application event key. 3. **Fetch and parse** transaction data through a configurable adapter. 4. **Classify** the item as parsed, duplicate, or review. 5. **Apply idempotently** using a unique business-event key. 6. **Record evidence** for each state transition. 7. **Expose review actions**: retry parsing, mark duplicate, or escalate. ## Operator view Each row should show: - Signature, truncated by default - Current status - Event type - First observed and last checked times - Retry count - Parser or application error - Link/button to copy the signature - “Needs review” reason Do not display private keys, seed phrases, or sensitive user data. ## Acceptance criteria - Reprocessing the same signature cannot create a duplicate business record. - Parser failures remain visible and retryable. - Every status change includes a timestamp and machine-readable reason. - Operators can export a filtered list for engineering review. - The system distinguishes “not yet observed,” “observed but not parsed,” and “parsed but not applied.” - Tests cover duplicate delivery, delayed parsing, malformed data, and partial application failure. ## Suggested first milestone Build an adapter interface, persistence model, deduplication constraint, and a minimal review table using fixture transactions. Validate behavior locally before connecting any production source.

# Self-Directed Draft: Solana Wallet Approval Receipt **Format:** Concise product specification **Status:** Proposed; not built or validated **Audience:** Solana teams building wallet-connected applications ## Problem A wallet connection is not permission to move assets. Yet users can struggle to distinguish connecting, signing a message, and authorizing a transaction. Support teams need a clear record of what an application requested—not wallet secrets or blanket assurances of safety. ## Product A lightweight SDK and receipt panel that explain each wallet request before approval and preserve a privacy-conscious record afterward. **Core promise:** “See what this app is asking your wallet to do.” ## MVP scope Support three request types: - **Connect:** Explain that the app is requesting a public address, not transaction authorization. - **Sign message:** Show the complete message, its stated purpose, and any readable domain, nonce, or expiration. Warn that a signature can authenticate or authorize actions outside the blockchain. - **Sign transaction:** Show the network, requested signer, fee payer, program IDs, and decoded instructions where supported. Clearly identify unknown instructions. Do not label a request “safe.” Decoded fields and simulation results are evidence, not guarantees. ## User flow 1. Application creates a wallet request. 2. SDK generates a summary bound to the exact message or transaction bytes. 3. User reviews the summary and opens the wallet approval prompt. 4. SDK records whether the application observed approval, rejection, or an error. 5. User can export a redacted receipt for support. If the request bytes change after review, invalidate the summary and require another review. ## Receipt schema ```text receipt_id created_at app_origin request_type network_or_cluster request_digest decoder_version decoded_summary unknown_instruction_count simulation_status: not_run | succeeded | failed | unavailable wallet_result: pending | approved | rejected | error submission_status: not_observed | submitted confirmation_status: not_checked | confirmed | failed | unknown ``` Approval must never be displayed as proof of submission or confirmation. ## Example panel > **Review transaction request** > Network: supplied by the application > Requested signer: [public address] > Recognized instructions: [decoded list] > Unknown instructions: [count] > Simulation: not run > > This summary may be incomplete. Check the wallet’s own preview. Signing authorizes the transaction; it does not prove that the transaction will succeed. Placeholders are interface examples, not observed activity. ## Privacy and security requirements - Never request seed phrases, private keys, or wallet recovery files. - Keep receipts local by default; no automatic analytics upload. - Exclude signed payloads and raw authentication messages from support exports by default. - Let users inspect and redact every export. - Render message content as plain text, never executable markup. - Label application-provided descriptions separately from decoded evidence. ## Acceptance checklist - [ ] Connection requests cannot be mislabeled as transactions. - [ ] Unknown instructions remain conspicuous. - [ ] Changed request bytes invalidate prior review. - [ ] Rejected requests never appear approved. - [ ] Unavailable simulation never appears successful. - [ ] Export preview reveals exactly what will be shared. - [ ] Automated tests cover unsupported programs and malformed messages. ## Commercial hypothesis Offer the local receipt component freely; test demand for paid decoder maintenance and team-controlled support integrations. Validate willingness to pay before building hosted storage.

# Self-Directed Draft: Solana Transaction Failure Triage Card **Format:** Reusable incident checklist **Audience:** Solana app engineers and support leads **Status:** Draft; not tested against a live incident ## Purpose Turn a “transaction failed” report into a reproducible engineering handoff without requesting wallet secrets or encouraging unsafe retries. ## 1. Capture the report ```text Incident ID: Reported time + timezone: App release: Cluster: User action: Expected outcome: Observed outcome: Transaction signature, if available: Wallet application + version: Error text, verbatim: Scope: one user / several users / unknown Assigned owner: ``` Request only necessary public addresses. Never request seed phrases, private keys, authentication tokens, or signed transactions that could still be submitted. ## 2. Locate the failure boundary Choose one; mark **unknown** when evidence is missing. - [ ] **Before wallet prompt:** UI validation, connection, or transaction construction. - [ ] **During wallet interaction:** rejection, unsupported signing flow, or wallet error. - [ ] **During submission:** RPC rejection, transport failure, or preflight failure. - [ ] **After submission:** transaction execution error or uncertain confirmation. - [ ] **After confirmation:** application display or indexing disagrees with chain state. **Rule:** An app timeout does not prove transaction failure. Check status before suggesting another attempt. ## 3. Collect evidence - [ ] Record the cluster and RPC provider; redact endpoint credentials. - [ ] Check signature status and transaction details, if available. - [ ] Record commitment level and time of each observation. - [ ] Preserve relevant logs and the failing instruction index. - [ ] Identify the program responsible for the reported error. - [ ] Decode custom errors against the matching program version, when available. - [ ] Check required signers, account ownership, writable flags, balances, and token-account requirements. - [ ] Check compute-budget errors and blockhash validity where relevant. - [ ] Separate observed facts from suspected causes. **Guardrail:** A missing RPC result is not sufficient evidence that a transaction never landed. A successful simulation is not a guarantee of successful execution. ## 4. Decide the next action | Evidence | Next action | |---|---| | Explicit wallet rejection | Explain that signing was declined; ask whether the user intended to proceed. | | Confirmed execution error | Investigate the failing instruction before recommending a retry. | | Submission outcome uncertain | Reconcile status and expected account changes; avoid blind retries. | | Confirmed success, stale UI | Investigate read commitment, caching, or indexing. | | Insufficient evidence | Request the smallest missing artifact; keep cause unresolved. | For value-moving or non-idempotent actions, require an explicit duplicate-action risk check before rebuilding or retrying. ## 5. Engineering handoff ```text Failure boundary: Observed facts: Suspected cause: Confidence: low / medium / high Supporting evidence: Missing evidence: Minimal reproduction: Retry safety: safe / unsafe / unresolved Recommended fix or next diagnostic: Owner: Next update due: ``` ## User-facing update template > We’re investigating your reported **[action]** issue. We have confirmed **[observation]**; **[uncertainty]** remains unresolved. Please **[specific safe next step]**. Do not share recovery phrases or private keys. ## Closure criteria Close only when the outcome is reconciled, the user has a safe next step, and the cause is either documented or explicitly marked unresolved with an owner. **Potential paid package:** A fixed-scope triage setup covering this intake card, an app-specific error taxonomy, and a handoff workflow. Validate demand before building automation.

# Self-Directed Draft: Solana Program Upgrade Safety Gate **Format:** Product specification **Status:** Proposed; not built or validated **Audience:** Solana teams managing upgradeable programs ## Problem Program upgrades can fail operationally even when the new code compiles: the wrong program ID may be targeted, upgrade authority may be unclear, required buffers may be missing, or deployment artifacts may not match the intended release. ## Product concept A command-line preflight tool that checks an upgrade package before any deployment action. It produces a deterministic report and exits nonzero when required checks fail. ## Example command ```bash solana-upgrade-gate \ --program-id ./release/program-id.txt \ --buffer ./release/program.so \ --idl ./release/program.json \ --manifest ./release/upgrade.yaml ``` ## Manifest fields ```yaml program_id: "<explicit public key>" expected_cluster: "devnet" release_commit: "<git commit>" authority_source: "local-keypair-or-external-signer" required_idl_version: "1.4.0" approved_upgrade_window: "2025-01-01T00:00:00Z/2025-01-01T02:00:00Z" ``` ## Preflight checks - Program ID exists and matches the release manifest. - Target cluster is explicitly selected. - Binary, IDL, and release commit are present. - Binary hash is recorded in the report. - IDL version matches the manifest. - Upgrade authority is identified without printing private key material. - Upgrade buffer is associated with the intended program, where inspectable. - Upgrade window is valid. - Required reviewer approvals are present in a local approvals file. - No production action is performed by the tool. ## Report output ```text UPGRADE PREFLIGHT: BLOCKED [PASS] Program ID format [PASS] Cluster explicitly selected [PASS] Binary hash recorded [FAIL] IDL version mismatch [WARN] Approval file has one reviewer; two required Action: resolve 1 failure and 1 warning before deployment. Report: upgrade-report.json ``` The JSON report should include check IDs, severity, inputs used, timestamps, and remediation text. It must redact secrets and avoid storing private key contents. ## MVP 1. YAML manifest parser 2. Artifact presence and hash checks 3. Program-ID and cluster validation 4. IDL/version consistency check 5. Human-readable and JSON reports 6. CI exit codes: `0` pass, `1` warning, `2` failure 7. Dry-run only; no deployment or onchain mutation ## Acceptance criteria - A malformed or incomplete manifest fails clearly. - Every failed check includes a concrete remediation message. - The same inputs produce the same check results. - Secrets never appear in stdout or report files. - CI can block a release using only the exit code. ## Non-goals - Deploying programs - Managing upgrade authorities - Replacing code review - Guaranteeing program correctness or runtime safety

# Self-Directed Draft: Solana Environment Drift Auditor **Format:** Product specification **Status:** Proposed; not built or validated **Audience:** Solana teams maintaining devnet, testnet, staging, and mainnet deployments ## Problem Teams can accidentally ship inconsistent configuration across environments: wrong program IDs, stale IDLs, mismatched RPC endpoints, unsupported feature flags, or missing deployed accounts. These errors often surface only when a user performs a specific action. ## Product concept A command-line auditor that compares a repository’s declared Solana configuration with observed cluster state and produces a reviewable drift report. ## MVP workflow ```bash sol-env-audit \ --config environments.yaml \ --repo ./app \ --output drift-report.json ``` The tool: 1. Loads named environments from a local configuration file. 2. Extracts expected program IDs, clusters, account addresses, and IDL versions. 3. Queries only the configured RPC endpoints. 4. Checks whether expected programs and accounts exist. 5. Compares environment values for accidental overlap or mismatch. 6. Emits machine-readable JSON plus a concise Markdown summary. 7. Exits nonzero when configured blocking rules fail. ## Example configuration ```yaml environments: devnet: cluster: devnet rpc_url: ${DEVNET_RPC_URL} programs: - name: example address: EXAMPLE_PROGRAM_ID idl_version: "0.4.0" mainnet: cluster: mainnet-beta rpc_url: ${MAINNET_RPC_URL} programs: - name: example address: MAINNET_PROGRAM_ID idl_version: "0.4.0" ``` ## Report categories - **Missing:** expected program or account is not found. - **Mismatch:** repository and environment values disagree. - **Suspicious overlap:** devnet and mainnet unexpectedly share an address. - **Stale metadata:** deployed program metadata differs from the declared version. - **Uncheckable:** RPC access or required configuration is unavailable. Each finding includes severity, environment, resource name, expected value, observed value, and a remediation hint. Private keys and full RPC credentials must never appear in output. ## Acceptance criteria - Supports JSON and Markdown output. - Redacts secrets before writing reports. - Returns exit code `0` for clean results and nonzero for blocking findings. - Allows teams to mark individual checks as warnings. - Includes fixture-based tests for clean, missing, mismatched, and unavailable-RPC cases. - Documents that observations depend on RPC availability and may require human review. ## Future extensions - CI pull-request annotations. - IDL compatibility checks. - Program upgrade-authority review. - Scheduled reports with locally controlled storage. - Custom organization policies.

# Self-Directed Draft: Solana Wallet Failure Report **Format:** Product specification **Status:** Proposed; not built or validated **Audience:** Solana app teams and their users ## Problem When a wallet action fails, users often report only “transaction failed.” Developers then lack the context needed to reproduce the issue without exposing sensitive wallet data. ## Product concept A lightweight, client-side “Report this failure” flow that creates a sanitized diagnostic bundle for support or issue tracking. ## User flow 1. A wallet action fails. 2. The app displays a concise explanation and a **Copy diagnostic report** button. 3. The user reviews the fields. 4. The app copies a text or JSON report to the clipboard. 5. The user pastes it into support chat or an issue form. ## Diagnostic fields ```json { "appVersion": "string", "environment": "devnet | testnet | mainnet-beta | unknown", "action": "string", "walletAdapter": "string", "cluster": "string", "recentBlockhashAvailable": "yes | no | unknown", "simulationStatus": "passed | failed | not-run | unknown", "errorName": "string", "errorMessage": "string", "instructionSummary": ["string"], "timestamp": "ISO-8601 string", "reproductionSteps": ["string"] } ``` ## Privacy rules - Never include seed phrases, private keys, signed message contents, or secret environment variables. - Mask full public keys unless the user explicitly chooses to include them. - Remove access tokens and query parameters from endpoint URLs. - Let users inspect the report before copying. - Keep raw logs out of the default report. ## Suggested interface copy **Heading:** “Something went wrong” **Body:** “We couldn’t complete this wallet action. You can copy a safe diagnostic report to help the team investigate.” **Buttons:** - `Copy diagnostic report` - `Try again` - `Close` **Confirmation:** “Diagnostic report copied. It does not include your private keys or seed phrase.” ## Acceptance criteria - Report generation works without a server request. - Sensitive-field redaction occurs before display and clipboard copy. - Empty or unavailable fields use `unknown`, not fabricated values. - The report remains readable as plain text. - Developers can add an internal correlation ID without exposing user secrets. - The failure UI provides a retry path without forcing a wallet reconnect. ## Implementation note Expose one reusable function: ```ts createWalletFailureReport(input): { text: string; json: Record<string, unknown>; } ``` Keep collection, redaction, formatting, and UI rendering as separate modules so teams can adopt the diagnostic generator without replacing their existing error interface.

# Self-Directed Draft: Solana Release Readiness Checklist **Format:** Reusable operational checklist **Status:** Proposed template; not validated **Audience:** Solana teams shipping programs, web apps, APIs, or wallet flows ## 1. Release scope - [ ] Release owner and reviewer identified - [ ] Exact changes documented - [ ] Supported clusters and environments listed - [ ] User-visible behavior described - [ ] Out-of-scope behavior recorded - [ ] Rollback or disable path defined ## 2. Program and transaction safety - [ ] Program upgrades require the intended authority - [ ] Upgrade authority handling is documented - [ ] Account ownership and PDA derivations are checked - [ ] Signer and writable-account requirements are reviewed - [ ] Transaction instructions are simulated before submission - [ ] Compute-unit and priority-fee settings are configurable - [ ] Failed transactions produce actionable error categories - [ ] No private keys or seed phrases enter logs, analytics, or support forms ## 3. Frontend and wallet flow - [ ] Network or cluster is visible to the user - [ ] Users can review destination, amount, and key effects - [ ] Wallet rejection is handled separately from transaction failure - [ ] Pending, confirmed, expired, and unknown states are distinct - [ ] Retry behavior cannot unintentionally duplicate an action - [ ] Explorer links are generated only when a signature exists - [ ] Mobile and disconnected-wallet states are tested ## 4. RPC and reliability - [ ] RPC endpoint configuration is environment-specific - [ ] Rate-limit and timeout behavior is defined - [ ] Requests have bounded retries with backoff - [ ] Fallback behavior is documented, if available - [ ] Blockhash expiration is handled explicitly - [ ] Health checks avoid treating one successful request as full availability - [ ] Logs include request IDs without exposing sensitive data ## 5. Testing - [ ] Unit tests cover validation and error mapping - [ ] Integration tests cover successful and failed transactions - [ ] Tests cover insufficient balance and missing accounts - [ ] Tests cover wallet rejection and stale blockhashes - [ ] Tests cover duplicate submission attempts - [ ] Upgrade or migration steps are tested in a disposable environment - [ ] A manual reviewer completes one end-to-end flow ## 6. Observability Record these fields for each relevant operation: - `request_id` - `environment` - `cluster` - `operation` - `wallet_public_key` (only when appropriate) - `transaction_signature` (when available) - `program_error_code` (when available) - `duration_ms` - `final_status` - [ ] Alerts have an owner and response procedure - [ ] Dashboards distinguish app errors, wallet errors, RPC errors, and chain-confirmation errors - [ ] Logs have retention and access rules ## 7. Go/no-go review **Release:** **Owner:** **Reviewer:** **Planned time:** **Rollback trigger:** **Rollback action:** - [ ] Critical checks complete - [ ] Known risks accepted explicitly - [ ] Support copy prepared - [ ] Release notes written - [ ] Post-release verification steps assigned **Decision:** ☐ Go ☐ Hold ☐ Roll back

# Self-Directed Draft: Solana Transaction Intent Preview **Format:** Product specification **Status:** Proposed; not built or validated **Audience:** Solana wallet-connected apps ## Purpose Give users a plain-language preview of a transaction before wallet approval, reducing confusion around what the application is asking them to sign. ## Core experience Before invoking the wallet: 1. The app displays a human-readable intent. 2. The user expands technical details if needed. 3. The user explicitly chooses **Continue to wallet** or **Cancel**. 4. The app preserves the displayed intent while the wallet prompt is open. ## Preview card Required fields: - **Action:** “Swap,” “Mint,” “Deposit,” or “Approve” - **Assets involved:** token names, amounts, and decimals - **Destination:** shortened address with copy control - **Network:** selected cluster/environment - **Estimated fees:** shown only when available; otherwise “Not available” - **Permissions:** whether the transaction grants, changes, or revokes authority - **Irreversibility warning:** displayed for transfers, approvals, burns, and other permanent actions Technical disclosure: - Full account addresses - Program identifiers - Instruction count - Raw serialized transaction or JSON view - Blockhash/expiry information when relevant ## Safety rules - Never label an unknown account as a trusted brand or person. - Never describe an action as “free” when fee data is unavailable. - Never hide a destination behind a symbol alone. - Require a fresh preview whenever transaction parameters change. - Disable the approval button until the preview is generated successfully. - Show a visible mismatch warning if the wallet-returned request differs from the preview. ## Minimal interface copy **Review transaction** You are about to: > Deposit **[amount] [token]** into **[destination]** **This may:** - Move funds from your wallet - Grant permission to **[program/account]** - Cost an estimated **[fee]**, if available **[View technical details] [Cancel] [Continue to wallet]** ## MVP acceptance checklist - [ ] Preview is generated from the exact transaction payload to be signed. - [ ] Amounts use correct decimal formatting. - [ ] Destination addresses can be copied and fully inspected. - [ ] Unknown metadata is marked unknown, not guessed. - [ ] Parameter changes invalidate the previous preview. - [ ] Cancel returns the user to a safe, unchanged state. - [ ] The interface works without relying on color alone. - [ ] Test cases cover transfer, approval, failed simulation, and unavailable fee data. **Success criterion:** A user can explain what the transaction does, where assets go, and what permissions change before opening the wallet prompt.

# Self-Directed Draft: Solana Support Evidence Kit **Format:** MVP product specification **Status:** Proposed; not built or validated **Audience:** Solana teams handling transaction-related support tickets ## Problem “Something went wrong” reports often omit the transaction signature, cluster, or application error. Support teams must request more information while users may overshare sensitive data. ## Product A client-side **Copy support report** button that assembles a readable, privacy-reviewed incident report. Users preview and edit it before copying; nothing is uploaded automatically. ### Entry points Show the button on: - Transaction error screens. - Pending-transaction views. - Transaction history details. Keep it available when submission produced no signature. ## Report template ```text SUPPORT REPORT App version: Time (UTC): Cluster: mainnet-beta / devnet / testnet / custom / unknown Action attempted: App-observed stage: preparing / awaiting wallet / submitting / checking status Transaction signature: [if available; optional to include] Last observed status: Status source and observation time: App error code: Sanitized error message: Wallet application: [optional; name only] Browser family: [optional] User description: Note: This report records application observations, not a guarantee of transaction outcome. ``` ## Privacy rules - Build reports from an explicit field allowlist—not raw logs. - Never collect seed phrases, private keys, authentication headers, cookies, or signed transaction payloads. - Exclude wallet addresses by default. - Explain that a transaction signature can reveal publicly associated activity; require opt-in to include it. - Do not include full RPC URLs, query strings, or provider credentials. Represent custom endpoints as `custom`. - Map known errors to safe messages. For unknown errors, use a generic description rather than copying arbitrary error text. - Warn users not to paste secrets into the description. ## Interaction copy **Button:** “Copy support report” **Preview heading:** “Review what you share” **Privacy notice:** “This report stays in your browser until you copy it. Remove anything you do not want to share. Never include a recovery phrase or private key.” **Signature option:** “Include transaction signature. This may reveal associated public activity.” **Success:** “Report copied. Paste it into your team’s official support channel.” **Clipboard failure:** “Couldn’t copy automatically. Select and copy the report below.” ## Acceptance criteria 1. A report can be generated without a connected wallet or transaction signature. 2. Generating a report makes no network request and emits no report contents to analytics. 3. A submission timeout appears as an uncertain outcome—not “transaction failed.” 4. Missing or stale status observations are explicitly labeled. 5. Fixtures containing API keys in RPC URLs, nested errors, and headers produce no leaked credentials. 6. Signature inclusion is unchecked on each new report. 7. Preview, editing, and copying work with keyboard navigation. 8. The copied report matches the edited preview exactly. ## Scope boundary No ticket backend, wallet connection requirement, automatic diagnosis, or recovery transaction suggestions. First version exports plain text only. **Validation target:** In a small simulated support exercise, determine whether an agent can identify the attempted action, cluster, and last observed stage without requesting another screenshot. Record missing fields before expanding scope.

# Self-Directed Draft: Solana RPC Failover Drill **Format:** Reusable checklist **Status:** Proposed; not executed or validated **For:** Solana teams preparing a wallet-connected application for release ## Goal Test whether an application handles RPC disruption without misleading users, losing transaction state, or creating duplicate actions. **Scope:** Run in a controlled test environment with test wallets. Do not inject faults into public infrastructure or production traffic. ## Preparation - [ ] Assign a drill owner and a stop authority. - [ ] Configure primary and fallback RPC endpoints for the same cluster. - [ ] Keep provider credentials server-side where required; redact them from logs. - [ ] Choose one read flow and one transaction flow. - [ ] Record normal response times as a local baseline. - [ ] Set explicit request timeouts and bounded retry limits. - [ ] Confirm logs distinguish transaction preparation, wallet signing, submission, and confirmation. - [ ] Choose a harmless test transaction and a maximum test budget. ## Fault Matrix Inject faults through a local proxy or mocked RPC adapter. | Injected condition | Required behavior | |---|---| | Primary read request times out | Switch or retry within configured limits; show loading or degraded state rather than an empty balance. | | Primary returns rate-limit errors | Back off; avoid a retry storm; preserve the user's current form. | | Fallback reports a different cluster identity | Reject it; do not silently continue. | | Fallback returns older account state | Keep freshness metadata; do not silently replace newer displayed data with older data. | | Submission response is lost after sending | Retain the signed transaction’s signature; check its status before offering another attempt. | | Transaction validity expires without a known result | Reconcile signature status and relevant application state; rebuilding must require a new signing step. | | All providers are unavailable | Clearly report degraded service; preserve inputs and provide a bounded manual retry. | ## Duplicate-Action Guard - [ ] Separate **rebroadcasting the same signed bytes** from **building a new transaction**. - [ ] Do not automatically rebuild a transaction after an ambiguous submission. - [ ] Prevent repeated clicks while submission or reconciliation is active. - [ ] Use application-level operation identifiers where supported. - [ ] Never label an action “failed” solely because one RPC request timed out. - [ ] Show confirmation level explicitly; do not treat receipt of a signature as final success. ## Suggested User Copy **Read disruption:** “We can’t refresh this data right now. Previously loaded values may be out of date.” **Submission uncertain:** “We haven’t confirmed the result yet. We’re checking the transaction you signed. Avoid repeating this action until its status is resolved.” **New signature needed:** “This transaction can no longer be submitted as prepared. Check the previous attempt before reviewing and signing a new one.” ## Evidence Sheet For each scenario, capture: ```text Scenario: Injected fault: Configured timeout / retry limit: Observed provider switch: Transaction signature, if applicable: User-visible state: Recovery time: Unexpected new signatures requested: Pass / fail: Fix owner: ``` Exclude secrets and signed transaction payloads from shared reports. ## Release Gate Pass only when every scenario has evidence, retries stay bounded, ambiguous submissions remain distinguishable from failures, and no automatic failover requests an unintended new signature. **Deliverable for a team:** A completed drill sheet, redacted event trace, and prioritized fixes—not a claim that failover eliminates transaction risk.

# Self-Directed Draft: Solana Signing Intent Card **Format:** Product specification **Status:** Proposed; not built or validated **Audience:** Solana teams building wallet-connected applications ## Purpose Give users a readable summary of a transaction **before** opening their wallet. Make the requested action, permissions, and uncertainties visible without implying a security guarantee. ## MVP A reusable frontend component plus a transaction-to-summary adapter. ```ts type IntentCard = { action: string; network: string; feePayer: string; programs: { address: string; label?: string }[]; assetChanges: { mint: string; symbol?: string; direction: "in" | "out"; amount: string; basis: "instruction" | "simulation" | "unknown"; }[]; permissions: { description: string; authority: string; scope: string; }[]; estimatedNetworkFeeLamports?: string; warnings: string[]; coverage: "complete" | "partial" | "unknown"; }; ``` Addresses remain inspectable even when labels are available. Asset amounts use strings to avoid floating-point loss. Token symbols are display hints, not asset identifiers. ## Card Layout 1. **Action:** Plain-language intent supplied by the application. 2. **Network and payer:** Explicit network label and fee-paying address. 3. **Expected changes:** Assets entering or leaving the wallet, with each estimate’s basis. 4. **Permission changes:** Delegation, authority changes, or account closure when recognized. 5. **Fees:** Estimated network fee separately from application charges and other SOL movements. 6. **Unknowns:** Unsupported instructions or unavailable estimates. 7. **Controls:** “Cancel” and “Continue to wallet.” Always show: **“Review the wallet request too. This summary is not a security guarantee.”** ## Behavior Rules - Decode the prepared transaction, not only the application’s intended action. - Resolve address lookup tables before reporting full coverage; otherwise mark the summary partial. - List every invoked top-level program; describe simulation-observed inner calls separately. - Never translate missing data into zero cost or no asset movement. - If simulation is unavailable, say so and preserve instruction-derived information. - Treat application labels and third-party metadata as untrusted display text. - Invalidate the card whenever the prepared transaction changes. Require renewed review before opening the wallet. - Bind the reviewed summary to the serialized message submitted for signing. If a wallet changes that message, require review again where the integration supports it; otherwise disclose that limitation. ## Acceptance Checklist - [ ] A simple transfer displays recipient, mint/address, amount, and payer. - [ ] A delegation displays delegate address and decoded scope. - [ ] An unsupported instruction produces a prominent uncertainty notice. - [ ] An unresolved lookup table prevents “complete” coverage. - [ ] A failed simulation shows “Estimate unavailable,” not “No changes.” - [ ] A changed transaction invalidates the previous approval. - [ ] Network fees and application charges are not conflated. - [ ] All essential fields and controls work with keyboard navigation. - [ ] No seed phrase, private key, or signing credential is requested or logged. ## Scope and Commercial Test **Exclude:** Risk scores, token endorsements, automatic approvals, and claims that a transaction is safe. **Potential paid package:** Component integration, one application-specific decoder, and fixture-based tests. Start with one signing flow; measure summary coverage and user comprehension before expanding. No demand or revenue is assumed.

# Self-Directed Draft: Solana Transaction Replay Pack **Format:** Product specification **Status:** Proposed; not built or validated **Audience:** Solana application teams debugging failed or unexpected transactions ## Problem Transaction failures are often reported as screenshots or vague wallet errors. Engineers need a compact, shareable record that reproduces the failure without exposing private keys or user-sensitive data. ## Product A developer tool that converts a transaction attempt into a sanitized replay bundle for local diagnosis and regression tests. ## Bundle contents - Cluster label and RPC URL hostname - Recent blockhash and validity settings - Serialized transaction or message - Signer public keys and writable account metadata - Program IDs and instruction summaries - Simulation result - Runtime logs and return data - Compute-unit usage, when available - Account snapshots required for replay - Tool version and capture timestamp - Redaction report Private keys, seed phrases, access tokens, and raw authorization headers must never be included. ## Primary workflow 1. Wrap the application’s transaction-build and simulation path. 2. Capture a failed or suspicious attempt. 3. Replace sensitive account data with explicit placeholders where possible. 4. Export a JSON bundle plus human-readable Markdown summary. 5. Replay against a configured local test environment or mocked RPC fixture. 6. Turn the case into a regression test after diagnosis. ## Suggested CLI ```text sol-replay capture --input attempt.json --out ./cases/case-001 sol-replay inspect ./cases/case-001 sol-replay redact ./cases/case-001 --policy strict sol-replay replay ./cases/case-001 --endpoint http://localhost:8899 sol-replay test ./cases/case-001 ``` ## Safety requirements - Refuse to export detected secret-like values. - Make redaction visible rather than silently altering data. - Require explicit confirmation before sending any transaction. - Default all replay actions to simulation or local environments. - Preserve original and sanitized hashes for internal comparison, without exposing sensitive payloads. - Mark bundles as incomplete when required account state was unavailable. ## Acceptance checklist - [ ] Capture succeeds for legacy and versioned transaction formats. - [ ] Bundle can be inspected without proprietary tooling. - [ ] Secrets are blocked by automated checks. - [ ] Missing account state is reported clearly. - [ ] Replay output identifies divergence from the original result. - [ ] A captured case can become a repeatable CI test. - [ ] Documentation explains data-retention and sharing risks. ## MVP deliverables 1. TypeScript capture library. 2. JSON schema for replay bundles. 3. CLI inspection and strict-redaction commands. 4. Markdown report generator. 5. Three synthetic failure fixtures for testing. 6. Example CI step that replays stored fixtures.

# Self-Directed Draft: Solana Wallet Error Taxonomy Kit **Format:** Reusable implementation checklist **Status:** Proposed; not built or validated **Audience:** Solana application teams designing wallet-connected flows ## Objective Create consistent, actionable wallet and transaction errors so users know what to do next and engineers can diagnose failures quickly. ## Error categories Use stable internal codes, rather than matching raw provider messages: - `WALLET_NOT_CONNECTED` - `WALLET_REJECTED` - `WALLET_LOCKED` - `NETWORK_MISMATCH` - `INSUFFICIENT_BALANCE` - `TRANSACTION_EXPIRED` - `BLOCKHASH_NOT_FOUND` - `SIMULATION_FAILED` - `SIGNATURE_TIMEOUT` - `CONFIRMATION_FAILED` - `UNKNOWN_PROVIDER_ERROR` ## Error object ```ts type AppError = { code: string; userMessage: string; recoveryAction?: string; retryable: boolean; technicalMessage?: string; context?: { operation?: string; cluster?: string; walletType?: string; }; }; ``` Do not place secret keys, seed phrases, full signed transactions, or unnecessary personal data in logs. ## User-message checklist For every error, verify: - The message explains what happened in plain language. - The next action is specific: connect, switch network, add funds, retry, or contact support. - “Try again” appears only when retrying is reasonably safe. - A rejected signature is described as a user choice, not a system failure. - The UI distinguishes submission from confirmation. - Loading states can be exited without refreshing the page. - Repeated clicks cannot submit duplicate operations. - Mobile layouts expose the recovery action clearly. ## Engineering checklist - Map wallet-adapter/provider errors into the stable codes. - Preserve the original error privately for debugging. - Attach an operation identifier to each attempted action. - Record stage transitions: `created`, `signed`, `submitted`, `confirmed`, `failed`. - Define a timeout for each asynchronous stage. - Make retry behavior explicit and idempotent where possible. - Test wallet disconnects during signing and confirmation. - Test rejected signatures, stale blockhashes, insufficient funds, and wrong clusters. - Ensure errors remain understandable when RPC or provider wording changes. ## Acceptance criteria A release candidate passes when: 1. Every tested failure maps to one stable internal code. 2. Each code has a user message and recovery action. 3. No error path leaves an indefinite spinner. 4. A rejected signature does not trigger an automatic retry. 5. Support can identify the operation, stage, and error code from a privacy-safe report. 6. The same error renders consistently across desktop and mobile. **Suggested deliverable:** one shared error-mapping module, one copy table, and one test matrix covering wallet, signing, submission, and confirmation stages.

# Self-Directed Draft: Solana Wallet Flow Contract Checker **Format:** Product specification **Status:** Proposed; not built or validated **Audience:** Solana teams shipping wallet-connected web applications ## Purpose Catch common transaction-flow integration mistakes before release by checking a documented contract between the frontend, wallet adapter, RPC endpoint, and transaction builder. ## Core Problem Transaction failures are often caused by mismatched assumptions: - The UI targets a different cluster than the RPC endpoint. - A transaction is built for the wrong fee payer. - Required accounts are not identified before signing. - Simulation, signing, sending, and confirmation use inconsistent settings. - Users receive raw errors instead of actionable recovery steps. ## MVP A CLI or small web tool accepts a project configuration file: ```yaml cluster: devnet rpcUrl: https://example.invalid commitment: confirmed walletRequired: true transactionFlows: - name: create-item requiredAccounts: - wallet - programState simulationRequired: true confirmationRequired: true retryPolicy: rebuild ``` It produces: 1. **Contract checks** - Cluster and RPC configuration are explicitly declared. - Every flow names its required accounts. - Fee payer and signer expectations are documented. - Simulation and confirmation behavior are specified. - Retry behavior distinguishes rebuilding from resending. 2. **Human-readable report** - Pass, warning, or failure per rule. - Source location or configuration field. - Suggested remediation. - Privacy-safe diagnostic output. 3. **Machine-readable JSON** - Suitable for CI pipelines. - Stable rule identifiers. - Configurable failure thresholds. ## Example Rule Output ```text WARN W012: create-item has no user-facing recovery message. Suggested action: define messages for rejected signature, expired blockhash, insufficient balance, and failed simulation. ``` ## Initial Rule Set - `C001`: Cluster is declared. - `C002`: RPC endpoint is not silently selected from multiple environments. - `F001`: Every flow defines a fee-payer policy. - `F002`: Required accounts are listed. - `S001`: Simulation behavior is explicit. - `S002`: Confirmation commitment is explicit. - `R001`: Retry strategy states whether the transaction is rebuilt. - `U001`: Common wallet outcomes map to user-facing messages. - `P001`: Logs redact wallet or transaction identifiers unless explicitly enabled. ## Acceptance Criteria - A team can configure one transaction flow in under ten minutes. - CI exits nonzero when configured blocking rules fail. - Reports identify the exact rule and remediation. - The tool never requires private keys or signing authority. - The same input produces deterministic output. ## Possible Extensions - Framework adapters for common Solana frontend patterns. - A generated transaction-flow documentation page. - Test prompts for wallet rejection and expired blockhash scenarios. - A review mode that compares configuration changes between pull requests.

# Self-Directed Draft: Solana Transaction Support Packet **Format:** Concise product specification **Status:** Proposed; not built or validated **Audience:** Solana application teams handling “my transaction failed” support requests ## Purpose Turn a confusing transaction incident into a compact, privacy-conscious report that support and engineering can investigate without repeatedly asking the user for context. ## MVP An embeddable **“Copy support report”** button on transaction error screens. The application supplies its own transaction lifecycle events. The packet generator formats those events locally; it does not require wallet access, external lookups, or a hosted service. ### Required inputs - Application version and environment - Cluster label, including `unknown` - Intended action, expressed as a developer-defined label - Last observed stage: preparing, wallet approval, submitted, or confirmation checking - Application error code, if available - Sanitized error summary - Observation timestamp ### Optional inputs - Transaction signature, explicitly approved by the user for inclusion - Recent blockhash expiry context, if recorded by the application - Sanitized simulation error and relevant log excerpt - Ordered lifecycle events with relative timestamps Never include seed phrases, private keys, authentication headers, cookies, raw RPC URLs, or arbitrary application state. Do not collect wallet addresses by default. Warn that an included signature can reveal public account activity. ## User flow 1. The user opens **Transaction details** after an error. 2. A preview shows the exact report and any omitted fields. 3. The user optionally includes the transaction signature. 4. **Copy support report** writes plain text to the clipboard. 5. The interface says: “Copied. Nothing was sent automatically.” If clipboard access fails, show selectable report text instead. ## Example output *Illustrative values only; no actual transaction represented.* ```text TRANSACTION SUPPORT PACKET — schema 1 App version: example-build Environment: staging Cluster: devnet Action: deposit Last observed stage: confirmation checking Outcome: unknown App error: CONFIRMATION_TIMEOUT Summary: Confirmation was not observed before the app timeout. Signature: omitted by user Timeline: +0ms transaction prepared +850ms wallet approval received +1100ms submission acknowledged +31100ms confirmation check timed out Caution: A timeout does not establish transaction failure. Check transaction status before attempting this action again. ``` ## Interpretation rules - Report observations separately from conclusions. - A submission acknowledgment is not confirmation. - A confirmation timeout produces **outcome unknown**, not **failed**. - Missing evidence stays `unknown`; never infer a signature or error. - Preserve commitment level when reporting an observed confirmation. - Never recommend automatic retries for actions with potential duplicate effects. ## Safety and acceptance criteria - Packet generation makes no network requests. - Use an allowlisted schema; exclude unrecognized fields. - Free-text errors and logs are excluded by default. If enabled, sanitize, truncate, and require preview before copying. - Changing signature consent immediately updates the preview. - Tests cover rejected wallet approval, simulation errors, submission errors, timeouts, and unavailable clipboard access. - Unknown error codes still produce a readable packet. - The same supplied events produce the same report, excluding explicitly supplied timestamps. ## Scope boundary and commercial hypothesis **Exclude from MVP:** automatic diagnosis, transaction retries, explorer integrations, ticket submission, and analytics collection. A potential paid offering is a fixed-scope integration plus an application-specific error-label map. Validate demand with a working local demo and sanitized sample incidents before building a hosted product.

# Self-Directed Draft: Solana Instruction Fixture Lab **Format:** Product specification **Status:** Proposed; not built or validated **Audience:** Solana application teams building and testing transaction flows ## Problem Teams often test transaction builders with scattered scripts and manually created accounts. This makes regressions difficult to reproduce, compare, and review—especially when a change affects account ordering, instruction data, compute settings, or expected errors. ## Product A small local tool for storing, replaying, and comparing Solana instruction fixtures. Each fixture records: - Human-readable scenario name - Program and instruction identifiers - Account metadata and ordering - Encoded instruction data - Transaction-level settings - Expected outcome - Optional redacted input and output snapshots The tool should run entirely against a developer-selected local or test environment. It must not require private keys or persist secret material. ## Core workflow 1. Create a fixture from a test case or structured file. 2. Run the fixture against a configured endpoint. 3. Capture success, failure, logs, and relevant resource measurements. 4. Compare the result with the stored expectation. 5. Produce a compact diff suitable for a pull request. ## MVP commands ```text fixture init <name> fixture run <name> --endpoint <url> fixture check <name> fixture diff <name> <baseline> fixture redact <input> ``` ## Suggested fixture format ```yaml name: create-account-minimal program: "<program-id>" accounts: - label: payer signer: true writable: true instructions: - data: "<encoded-data>" settings: commitment: confirmed expect: outcome: success required_log: "<stable-log-fragment>" ``` Program IDs and encoded values remain placeholders until supplied by the team. ## Safety requirements - Never store seed phrases, private keys, or raw signing material. - Redact signatures, wallet addresses, and user identifiers by default in shared output. - Require explicit confirmation before sending any non-local transaction. - Mark endpoint configuration and captured results as environment-specific. - Treat logs as untrusted input when rendering reports. ## Acceptance criteria - A developer can add a fixture without modifying application source. - A failed fixture identifies the first meaningful mismatch. - Re-running the same fixture produces a stable, readable report where possible. - Secrets are rejected or masked before fixture persistence. - A team can review fixture changes as ordinary text files. ## Future extensions - CI integration - Fixture generators for common account layouts - Compute-budget comparison - Snapshot expiration and refresh workflow - Adapters for Anchor or custom instruction builders

# Self-Directed Draft: Solana Release Readiness Checklist **Format:** Reusable checklist **Status:** Proposed; not validated **Audience:** Solana teams preparing an application or program release ## Goal Give a small team a repeatable way to review a release before exposing it to users. ## Checklist ### Scope and ownership - [ ] Define the release goal in one sentence. - [ ] Name an owner for code, deployment, monitoring, and rollback. - [ ] Record the exact commit, build configuration, and target cluster. - [ ] List expected user-visible changes and known limitations. ### Program and configuration - [ ] Review changed instructions, accounts, authorities, and validation rules. - [ ] Confirm PDA seeds, account sizing, and rent assumptions where applicable. - [ ] Check upgrade authority and emergency-control procedures. - [ ] Verify environment-specific program IDs, mints, RPC endpoints, and feature flags. - [ ] Ensure secrets and private keys are excluded from source, logs, and client bundles. ### Tests - [ ] Cover valid, invalid, boundary, and repeated-call behavior. - [ ] Test unauthorized signers and unexpected account owners. - [ ] Test stale, missing, oversized, and incorrectly ordered accounts. - [ ] Exercise failure handling and retry behavior. - [ ] Run a clean-environment build from the recorded commit. - [ ] Review test output for warnings treated as errors. ### Client and user experience - [ ] Confirm the client encodes instruction data exactly as the program expects. - [ ] Display network, account, amount, and fee details before signing. - [ ] Provide actionable errors without exposing sensitive internals. - [ ] Define behavior for rejected, expired, duplicated, or interrupted transactions. - [ ] Update user-facing documentation and support response templates. ### Operations - [ ] Prepare deployment and rollback commands with a second-person review. - [ ] Record required account migrations and their order. - [ ] Add logs or metrics for critical instruction outcomes. - [ ] Define alert thresholds and an incident contact path. - [ ] Decide what evidence must be captured during an incident. ### Go/no-go review - [ ] Every unchecked item has an owner and documented exception. - [ ] A reviewer who did not implement the change has examined it. - [ ] Rollback or disablement has been rehearsed at an appropriate scope. - [ ] Release notes identify risks, dependencies, and recovery steps. - [ ] Approvers record: **Go / No-go / Go with exceptions**. ## Minimal release record ```text Release: Commit/build: Target cluster: Program IDs: Owner: Reviewer: Known risks: Rollback method: Open exceptions: Decision: Decision timestamp: ```

# Self-Directed Draft: Solana Transaction Failure Triage Kit **Format:** Product specification **Status:** Proposed; not built or validated **Audience:** Solana application teams, support engineers, and protocol operators ## Problem When a user reports a failed or stuck transaction, support teams often lack a consistent way to collect the signature, identify the failure stage, and provide a useful response. Investigation becomes repetitive and dependent on individual expertise. ## Product A small internal web tool that turns a transaction signature into a structured investigation record. ### Core workflow 1. Paste a transaction signature and select the intended cluster. 2. Confirm signature format and cluster before querying. 3. Retrieve available transaction and status data through a configured RPC endpoint. 4. Classify the result: - Not found - Pending or unknown - Confirmed successfully - Failed during simulation or execution - Expired or blockhash-related - Insufficient balance or compute budget - Program-level error 5. Display a human-readable summary with raw evidence expandable below it. 6. Copy a support-safe response containing no private keys or sensitive environment data. 7. Save an optional case note with owner, status, and follow-up action. ## Key screens ### Lookup - Signature field - Cluster selector - RPC health indicator - Search timestamp - Clear validation errors ### Investigation - Final status and confirmation level - Slot and block time, when available - Fee and account balance changes, when available - Instruction/program list - Log messages - Parsed error category - “Evidence unavailable” labels instead of guessed values ### Case record - Case ID - Customer or ticket reference - Signature and cluster - Classification - Owner - Notes - Resolution status - Created and updated timestamps ## Safety requirements - Never request or store seed phrases, private keys, or wallet export data. - Redact configured secrets from logs and copied output. - Treat RPC responses as untrusted input. - Make cluster explicit in every result. - Distinguish “not found” from “failed.” - Preserve raw response data only if retention is enabled by an administrator. - Add rate limits and authentication for shared deployments. ## Minimal data model ```text Case { id, signature, cluster, classification, evidence_summary, raw_evidence_ref?, owner?, notes?, status, created_at, updated_at } ``` ## Acceptance criteria - A valid signature can be queried against the selected cluster. - Invalid input produces an actionable error without making a request. - Every classification links to visible supporting evidence. - Unknown or incomplete RPC data is clearly marked. - A support response can be copied in under two clicks. - No secret material is accepted in any input field. - Tests cover successful, failed, pending, not-found, malformed, and RPC-error cases. ## Future extensions - Compare multiple signatures from the same incident. - Add program-specific error dictionaries. - Export sanitized case records. - Integrate with an existing ticketing system without exposing customer secrets.

# Self-Directed Draft: Solana Transfer Review Queue **Format:** Product specification **Status:** Proposed; not built or validated **Audience:** Solana teams managing treasury, grants, payroll, or operational transfers ## Problem Transfer requests often arrive through chat or spreadsheets, making it difficult to verify destination addresses, approvals, token details, and execution status. A review queue can separate request, approval, and execution without custodying funds. ## Product concept A small internal dashboard where a requester submits a transfer intent and authorized reviewers approve or reject it. An executor later performs the transfer using the team’s existing wallet workflow and records the resulting transaction reference. ## Core workflow 1. **Create request** - Asset and network - Amount and decimals - Destination address - Purpose and cost center - Requested execution date - Supporting note or attachment 2. **Validate** - Address format check - Required fields - Duplicate or unusually similar destination warning - Optional allowlist match - Optional second-person confirmation for pasted addresses 3. **Review** - Reviewer comments - Approve, reject, or request changes - Configurable approval threshold - Immutable activity log 4. **Execute** - Executor marks “in progress” - Existing wallet signs externally - Transaction reference is attached manually - Final status becomes completed or failed ## Minimal data model - `request_id` - `requester` - `asset` - `amount` - `destination` - `purpose` - `approvers` - `status` - `created_at` - `review_events` - `execution_reference` - `failure_reason` ## Safety boundaries - Never store seed phrases or private keys. - Never sign transactions inside the first version. - Display the full destination address, not only a shortened form. - Require explicit confirmation immediately before execution. - Keep rejected and cancelled requests visible for audit. - Treat transaction references as user-provided until independently checked. ## MVP acceptance criteria - A requester can submit a complete transfer intent. - A reviewer can approve, reject, or return it for edits. - The system prevents execution of unapproved requests. - Every state change records actor, timestamp, and comment. - An executor can attach an external transaction reference. - Export produces a readable CSV for reconciliation. - The interface clearly distinguishes requested, approved, executed, and failed states. ## Success signal Teams can answer, for every transfer: **who requested it, who approved it, what was intended, who executed it, and what reference records the outcome**—without moving signing authority into the product.

# Self-Directed Draft: Solana Release Readiness Console **Format:** Product specification **Status:** Proposed; not built or validated **Audience:** Solana teams preparing a program, frontend, or configuration release ## Problem Release checks are often distributed across code review, deployment notes, environment variables, UI flows, and rollback instructions. A lightweight console can turn these checks into a repeatable, auditable release packet. ## MVP A web form that creates a release record with: - Release name and owner - Target cluster/environment - Commit or build identifier - Programs, accounts, and frontend surfaces affected - Configuration changes - Migration steps - Rollback steps - Required reviewers - Pre-release checklist - Post-release verification checklist - Open risks and explicit unknowns ## Core workflow 1. Create a release record from a reusable template. 2. Assign checklist items to named reviewers. 3. Attach notes, screenshots, or text evidence. 4. Block approval when required items remain incomplete. 5. Export a concise Markdown release packet. 6. Archive the record for future comparison. ## Suggested checklist ### Scope - [ ] Change summary is written in plain language. - [ ] Affected programs, instructions, accounts, and UI flows are listed. - [ ] In-scope and out-of-scope changes are separated. ### Safety - [ ] Upgrade authority and signer responsibilities are documented. - [ ] Configuration changes are reviewed. - [ ] Migration order and dependencies are documented. - [ ] Rollback conditions and owner are explicit. - [ ] No secret keys, seed phrases, or private credentials are included. ### Verification - [ ] Fresh-user path is tested. - [ ] Existing-user path is tested. - [ ] Expected transaction outcomes are defined. - [ ] Error messages and recovery actions are reviewed. - [ ] Monitoring or manual observation steps are assigned. ### Approval - [ ] Engineering reviewer approved. - [ ] Product or operations reviewer approved. - [ ] Release window recorded. - [ ] Post-release owner assigned. ## Data model ```text Release - id - title - environment - owner - version_reference - affected_components[] - checklist_items[] - risks[] - approvals[] - rollback_plan - verification_plan - created_at - updated_at ``` ## Acceptance criteria - A user can create a release packet in under five minutes. - Required checklist items cannot be silently skipped. - Exported packets contain status, owners, risks, approvals, and rollback steps. - Secrets are rejected or visibly warned against in text fields. - Templates can be duplicated for recurring release types. ## Possible paid offering Sell setup and customization to teams that need their own release templates, approval roles, and documentation format. Keep the base checklist generic; charge for workflow integration and tailored operational playbooks.

# Self-Directed Draft: Solana Incident Timeline Builder **Format:** Product specification **Status:** Proposed; not built or validated **Audience:** Solana engineering, support, and operations teams ## Problem Incident notes are often scattered across chat, dashboards, RPC logs, and deployment records. Teams need a consistent way to reconstruct what happened, identify unknowns, and hand off a concise incident record without exposing secrets. ## Product concept A local-first tool that converts timestamped observations into a structured Solana incident timeline. ## MVP ### Inputs - Incident title and severity - Cluster and environment - Time zone - Manually entered events - Pasted log excerpts - Optional transaction signatures, program IDs, and slot numbers - Links to internal dashboards or tickets ### Event fields - Timestamp - Source - Event type: symptom, observation, action, decision, or recovery - Description - Confidence: confirmed, likely, or unknown - Owner - Evidence reference - Sensitive-content flag ### Outputs 1. Chronological incident timeline 2. Executive summary 3. “What we know / what we do not know” section 4. Action-item list with owners 5. Markdown and JSON export 6. Redacted sharing view ## Guardrails - Never request seed phrases, private keys, wallet authentication, or signing authority. - Warn before exporting raw logs that may contain sensitive data. - Preserve original evidence separately from edited summaries. - Treat transaction signatures and program IDs as identifiers, not proof of causality. - Label inferred ordering when timestamps are incomplete. - Require users to verify cluster, timestamps, and event ownership. ## Example record ```text [2025-01-01 14:03 UTC] Observation Source: application logs Description: Error rate increased after a client configuration change. Confidence: likely Evidence: log excerpt A-17 Owner: backend team ``` ## Acceptance criteria - A user can create an incident and add an event in under one minute. - Exported Markdown includes all events in chronological order. - Every summary statement links to one or more evidence references. - Unknown or conflicting timestamps remain visibly marked. - Redaction removes flagged fields from the shareable export. - The tool works without submitting data to an external service in local mode. ## Future extensions - Import structured logs and monitoring alerts - Compare timelines across incidents - Templates for RPC, program, frontend, and indexer incidents - Automated detection of timestamp gaps and contradictory entries - Read-only integrations configured by the team’s administrators

# Self-Directed Draft: Solana Transaction Failure Intake Kit **Format:** Product specification **Status:** Proposed; not built or validated **Intended users:** Solana application support and engineering teams ## Purpose Turn “my transaction failed” reports into structured, privacy-conscious engineering tickets—without requesting wallet secrets or requiring users to retry blindly. ## MVP A reusable intake form and ticket formatter. No wallet connection, transaction submission, or automatic chain lookup. ### User-facing form **Title:** Help us investigate your transaction **Safety notice:** Never submit a seed phrase, private key, recovery code, or wallet export. Transaction signatures and wallet addresses may reveal public activity; share only what you are comfortable disclosing. **Required** - **What were you trying to do?** Short description. - **What happened instead?** Rejected, pending, error displayed, unexpected result, or unsure. - **Approximate time and timezone** - **Network:** Mainnet-beta, devnet, testnet, custom, or unsure. **Optional** - Transaction signature, if available. - Exact error text, with sensitive details removed. - Application page or feature; exclude URL query strings. - Wallet application and version. - Device/browser. - Whether the wallet displayed an approval request. - Whether this was a repeat attempt. - Redacted screenshot. **Submission confirmation:** “Your report is ready for review. Avoid repeating the action until you check its status; an unclear result does not necessarily mean nothing happened.” ## Triage Rules Assign an **intake category**, not a confirmed diagnosis: | Reported condition | Category | Next investigation | |---|---|---| | No approval request appeared | Before signing | Inspect app flow and wallet connection | | User declined approval | User cancellation | Confirm intent; do not suggest automatic retry | | Approval occurred, no signature available | Submission unclear | Inspect application submission records | | Signature available | Status investigation | Check the correct network and commitment context | | Result differs from expectation | Outcome mismatch | Compare intended action with available execution evidence | Never infer success or failure solely from a signature, timeout, or interface message. ## Generated Ticket ```text Title: [Feature] — [Reported symptom] Report ID: Reported network: Approximate occurrence time: User intent: Observed behavior: Approval request shown: Transaction signature: [optional] Error text: [optional] Environment: Repeat attempt: [yes/no/unknown] Intake category: Evidence supplied: Unknowns: Next investigation: Assigned owner: Resolution and supporting evidence: ``` Keep user statements separate from investigator findings. Missing fields remain **unknown**, not guessed. ## Privacy and Abuse Controls - Do not collect wallet secrets or require wallet addresses. - Warn users to redact screenshots and error messages. - Treat submitted text as untrusted content; escape it in ticket previews. - Restrict report access to designated team members. - Require a configured retention period before enabling collection. - Exclude signatures, screenshots, and report bodies from product analytics. ## Acceptance Criteria - A user can submit a useful report without a signature or wallet address. - Every report preserves network and time uncertainty. - Generated tickets distinguish reported symptoms from confirmed findings. - No workflow prompts signing, payment, or automatic retries. - Retention and deletion behavior are documented and testable. ## Proposed Paid Package Offer the form schema, ticket template, triage guide, and one team-specific workflow configuration as a fixed-scope support tooling package. Validate demand through team interviews before adding integrations or automated diagnostics.