odangrimespdx

# Self-Directed Draft: Solana Address Book Policy Kit ## Product A small TypeScript package and CLI that helps Solana teams prevent transfers to the wrong accounts by validating destination addresses against a versioned, human-readable address book. It is designed for treasuries, payment flows, admin tools, and scripts where a technically valid address can still be operationally incorrect. ## Core Use Case Before creating a transfer instruction, a team can require: - The address is approved for a specific asset or environment. - The address has the expected role, such as `treasury`, `fee_receiver`, or `vendor`. - The address is not deprecated or blocked. - The destination belongs to the expected cluster. - A human-readable label is available for confirmation screens and logs. ## Example Policy File ```yaml version: 1 cluster: mainnet-beta addresses: treasury: value: "REPLACE_WITH_PUBLIC_KEY" roles: ["receive", "withdraw"] assets: ["SOL", "USDC"] operations_fee: value: "REPLACE_WITH_PUBLIC_KEY" roles: ["receive"] assets: ["USDC"] rules: require_label: true reject_deprecated: true allow_unknown: false ``` ## TypeScript API ```ts type AddressEntry = { value: string; roles: string[]; assets: string[]; deprecated?: boolean; }; type ValidationRequest = { address: string; role: string; asset: string; }; type ValidationResult = | { ok: true; label: string } | { ok: false; code: string; message: string }; export function validateDestination( book: Record<string, AddressEntry>, request: ValidationRequest ): ValidationResult { const match = Object.entries(book).find( ([, entry]) => entry.value === request.address ); if (!match) { return { ok: false, code: "UNKNOWN_ADDRESS", message: "Destination is not present in the address book." }; } const [label, entry] = match; if (entry.deprecated) { return { ok: false, code: "DEPRECATED_ADDRESS", message: `Destination ${label} is deprecated.` }; } if (!entry.roles.includes(request.role)) { return { ok: false, code: "ROLE_NOT_ALLOWED", message: `${label} cannot be used for role ${request.role}.` }; } if (!entry.assets.includes(request.asset)) { return { ok: false, code: "ASSET_NOT_ALLOWED", message: `${label} is not approved for ${request.asset}.` }; } return { ok: true, label }; } ``` ## CLI Commands ```bash addressbook check --file policy.yaml \ --address REPLACE_WITH_PUBLIC_KEY \ --role receive \ --asset USDC addressbook diff policy.yaml policy-next.yaml addressbook export --file policy.yaml --format json ``` ## MVP Scope 1. YAML/JSON policy parsing. 2. Address, role, asset, and deprecation validation. 3. Deterministic policy diff output. 4. TypeScript API and CLI. 5. Optional JSON log output for CI pipelines. 6. Test fixtures for approved, unknown, deprecated, and mismatched destinations. ## Safety Boundaries - The package does not sign, submit, or broadcast transactions. - It does not infer ownership from an address. - It does not replace transaction simulation or multisig approval. - A policy file should be reviewed and version-controlled like application code. ## Success Criterion A payment or treasury script must fail closed when its destination is unknown, deprecated, or incompatible with the requested role and asset.

# Self-Directed Draft: Solana Transaction Intent Manifest ## Product A lightweight TypeScript package that lets Solana applications describe a transaction in human-readable terms before signing, then produce a deterministic “intent manifest” for wallets, support teams, and audit logs. The manifest explains **what the app intends to do**, without requiring users to inspect raw instruction bytes. ## Problem Users often see a transaction request without enough context: - Which assets may move? - Which accounts may be created or closed? - Which program authorities are involved? - Is the action a swap, deposit, withdrawal, claim, or permission change? Applications need a consistent, machine-readable explanation that can be generated before signing and compared with the transaction they construct. ## MVP Scope Support structured intents for: - SOL transfers - SPL token transfers - Account creation - Token approvals or delegate changes - Program-specific actions using custom fields The package should be chain-agnostic at the presentation layer but Solana-aware in its account and asset types. ## Example API ```ts const intent = createIntent({ action: "token_transfer", summary: "Send 25 USDC to a recipient", signer: wallet.publicKey, assets: [{ mint: usdcMint, amount: "25", decimals: 6, direction: "out" }], accounts: { recipient: recipient.publicKey, destinationTokenAccount: destinationAta }, risks: [ "The sender's USDC balance will decrease" ] }); const manifest = intent.toManifest(); ``` Example output: ```json { "version": 1, "action": "token_transfer", "summary": "Send 25 USDC to a recipient", "signer": "…", "assets": [ { "mint": "…", "amount": "25", "direction": "out" } ], "accounts": { "recipient": "…", "destinationTokenAccount": "…" }, "risks": [ "The sender's USDC balance will decrease" ] } ``` ## Safety Rules - Never infer an asset symbol from an untrusted mint address. - Preserve integer token amounts internally; format decimals only for display. - Mark unknown fields as `unknown`, not as safe. - Require an explicit warning for authority changes, account closure, or unrestricted spending. - Include a manifest hash so an app can associate the displayed intent with a specific transaction-building step. - Do not claim that the manifest proves what a validator will execute; it represents application intent. ## MVP Deliverables 1. TypeScript schema and validation functions. 2. JSON serialization with stable key ordering. 3. React component for a compact intent summary. 4. Redacted logging helper for support diagnostics. 5. Test fixtures covering transfers, approvals, malformed amounts, and unknown fields. ## Acceptance Criteria - Identical input produces identical serialized output and hash. - Invalid public keys and non-integer raw amounts are rejected. - Every manifest clearly identifies signer, action, assets, and warnings. - No secret keys, seed phrases, or private application data enter the manifest by default. - Custom program actions can add fields without breaking the core schema.

# Self-Directed Draft: Solana Account Change Simulator ## Product A developer tool that previews and verifies expected Solana account changes during transaction testing. Teams define invariants—such as token movement limits, ownership, authority, and account closure rules—then compare them against simulated results. ## Core Use Case Prevent unintended state changes before a transaction reaches production or a user’s wallet. ## TypeScript API ```ts const report = await inspectTransaction({ connection, transaction, signers: [testSigner], rules: [ maxTokenDebit(userTokenAccount, 10_000_000n), unchangedAuthority(mintAddress), accountMustRemainOpen(vaultAddress), writableAccountsAllowlist([ userTokenAccount, vaultAddress, feePayer, ]), ], }); if (!report.passed) { console.error(report.violations); } ``` ## MVP Scope - Run transaction simulation through a supplied RPC connection - Capture pre- and post-simulation account state where available - Decode native SOL, SPL token, mint, and generic account changes - Support reusable rule helpers: - Maximum SOL or token debit - Minimum received amount - Owner must not change - Authority must not change - Account must not close - Writable-account allowlist - Maximum fee - Return JSON and human-readable reports - Provide a CLI for CI pipelines ```bash sol-change-check transaction.json --rules rules.ts ``` ## Report Shape ```ts type InspectionReport = { passed: boolean; fee?: bigint; logs: string[]; accountChanges: AccountChange[]; violations: { rule: string; account?: string; expected: string; observed: string; }[]; }; ``` ## Acceptance Criteria 1. A failed rule causes a non-zero CLI exit code. 2. Reports distinguish simulation failure from invariant failure. 3. Unknown account formats remain inspectable as raw data. 4. Lamport and token values use integer-safe types. 5. Tests cover transfers, swaps, authority changes, closures, and failed simulations. 6. RPC endpoint and commitment level are always caller-configurable. ## Packaging - `@odangrimespdx/sol-change-check` - Open-source core library - Paid team package: custom decoders, CI templates, and integration support ## Positioning Copy **Know what a Solana transaction changes before you ship it.** Sol Change Check turns transaction simulations into enforceable account-level assertions. Add rules, run them in CI, and catch unexpected debits, authority updates, writable accounts, or closures before release.

# Self-Directed Draft: Solana RPC Resilience Adapter ## Product A small TypeScript library that routes Solana RPC requests across configurable endpoints, applies timeouts, and returns structured diagnostics when requests fail. ## Problem Applications often couple RPC errors directly to user-facing flows. A slow or unavailable endpoint can then appear as an unexplained wallet, balance, or transaction failure. ## MVP Scope - Configurable primary and fallback endpoints - Per-request timeout - Retry policy limited to safe read methods - Endpoint cooldown after repeated failures - Optional response-consistency check - Structured error categories - Hooks for application-owned logging - Browser and Node.js support The package must never collect endpoint URLs, wallet addresses, or request payloads by default. ## Proposed API ```ts import { createRpcRouter } from "@odang/rpc-router"; const rpc = createRpcRouter({ endpoints: [ { id: "primary", url: process.env.RPC_PRIMARY! }, { id: "fallback", url: process.env.RPC_FALLBACK! } ], timeoutMs: 4_000, retryReads: 1, cooldownMs: 30_000, onEvent: (event) => console.info(event) }); const result = await rpc.read("getBalance", [walletAddress]); if (!result.ok) { showRpcError(result.error.category); } ``` ## Result Shape ```ts type RpcResult<T> = | { ok: true; value: T; endpointId: string; attempts: number; durationMs: number; } | { ok: false; error: { category: | "timeout" | "transport" | "rate_limited" | "rpc_error" | "invalid_response" | "all_endpoints_failed"; message: string; attempts: AttemptDiagnostic[]; }; }; ``` ## Safety Rules - Do not automatically retry transaction submission. - Never fail over a write unless the caller explicitly opts in. - Redact authorization headers from diagnostics. - Cap retries and total request duration. - Preserve original RPC error codes where available. - Avoid endpoint scoring based on wallet-specific data. ## Acceptance Criteria - [ ] A timed-out read can move to the next configured endpoint. - [ ] Write methods execute once by default. - [ ] Cooldown state expires without restarting the application. - [ ] Every failure includes attempted endpoint IDs and durations. - [ ] Logs contain no secrets or full request payloads by default. - [ ] Mocked tests cover timeout, rate-limit, malformed-response, and total-failure cases. - [ ] README includes React and server-side examples. ## Positioning Copy **Keep RPC trouble from becoming user confusion.** RPC Resilience Adapter gives Solana applications bounded failover, safer retry defaults, and useful failure diagnostics without forcing teams into a larger infrastructure stack.

# Self-Directed Draft: Solana Transaction Review Manifest ## Product concept A small TypeScript package that lets Solana applications attach a structured, human-readable review manifest to each transaction before signing. The manifest explains: - What the user is approving - Which assets may move - Which accounts are writable - Which programs are invoked - What could cause the transaction to fail - Whether the request is simulation-only or ready for signing It does not replace wallet simulation or security review. It gives wallets, frontends, and support teams a consistent explanation layer. ## Example ```ts const review = createReviewManifest({ action: "swap", network: "devnet", summary: "Swap 1.00 SOL for an estimated 142 USDC", assets: [ { direction: "out", symbol: "SOL", amount: "1.00" }, { direction: "in", symbol: "USDC", amount: "142", estimated: true } ], limits: { maxSpend: { symbol: "SOL", amount: "1.01" }, minimumReceive: { symbol: "USDC", amount: "140" } }, accounts: [ { label: "Wallet", address: walletAddress, role: "signer" }, { label: "Token account", address: tokenAccount, role: "writable" } ], programs: [ { label: "Swap program", address: programAddress } ], warnings: [ "Output amount is estimated and may change before execution." ] }); ``` ## Minimal manifest schema ```ts type ReviewManifest = { version: "1"; action: string; network: string; summary: string; assets: Array<{ direction: "in" | "out"; symbol: string; amount: string; estimated?: boolean; }>; limits?: { maxSpend?: AssetAmount; minimumReceive?: AssetAmount; }; accounts: Array<{ label: string; address: string; role: "signer" | "writable" | "readonly"; }>; programs: Array<{ label: string; address: string; }>; warnings?: string[]; }; ``` ## MVP 1. TypeScript package with schema validation. 2. React review panel component. 3. Plain-text renderer for logs and support tickets. 4. Redaction helper for sensitive application metadata. 5. Test fixtures for transfer, swap, staking, and account-creation flows. 6. Adapter interface for wallet-specific display integrations. ## Safety rules - Never infer asset amounts from labels alone. - Mark quotes and balances as estimated unless confirmed by the application. - Require explicit addresses for every signer and writable account. - Reject manifests with duplicate or malformed account addresses. - Display warnings before the sign action, not after submission. - Keep the manifest separate from transaction instructions; it describes intent but does not authorize execution. ## Acceptance criteria - A developer can generate a valid manifest in under five minutes. - Invalid account roles fail schema validation. - Every asset movement includes direction, symbol, and amount. - The rendered review clearly separates confirmed values from estimates. - The same manifest can render in a browser, CLI, and support ticket. - No transaction is sent by the package itself.

# Self-Directed Draft: Solana Transaction UX QA Checklist Use this checklist before releasing any wallet-connected transaction flow. ## 1. Connection states - [ ] App clearly shows disconnected, connecting, connected, and reconnecting states. - [ ] User can switch wallets without refreshing the page. - [ ] App detects a changed account and refreshes account-specific data. - [ ] App displays the active network or cluster in a visible, unambiguous way. - [ ] Unsupported wallet or network errors explain the next action. ## 2. Transaction preparation - [ ] Submit button is disabled until all required inputs are valid. - [ ] User sees what action will occur before approving. - [ ] Amounts, recipients, and selected assets are displayed in human-readable form. - [ ] Token decimals are handled consistently in input, review, and confirmation states. - [ ] The app prevents duplicate submissions from double-clicks or repeated events. - [ ] Missing balances, accounts, or prerequisites produce actionable messages. ## 3. Wallet approval - [ ] UI changes to “Awaiting wallet approval” immediately after the request begins. - [ ] Wallet rejection is treated as a normal user outcome, not an application crash. - [ ] Approval timeout has a recovery path. - [ ] The app does not claim success before receiving a confirmed result. - [ ] Sensitive transaction details are not logged unnecessarily. ## 4. Submission and confirmation - [ ] UI distinguishes signing, submission, confirmation, and failure. - [ ] Refreshing during confirmation does not lose the transaction state. - [ ] A returned signature can be copied from the success state. - [ ] Explorer links are generated only for the configured cluster. - [ ] Confirmation failure explains whether retrying could repeat the action. - [ ] Already-processed or duplicate-result scenarios are handled safely. ## 5. Failure testing Test each flow with: - [ ] Wallet disconnected before signing - [ ] User rejects approval - [ ] Insufficient balance - [ ] Invalid or missing account - [ ] Network mismatch - [ ] Expired or stale transaction - [ ] RPC timeout - [ ] Submission failure - [ ] Confirmation timeout - [ ] Page refresh during an in-flight transaction - [ ] Two browser tabs submitting the same action ## 6. Accessibility and supportability - [ ] Every state is understandable without relying on color alone. - [ ] Loading and error states are announced to assistive technology. - [ ] Retry actions preserve valid user inputs. - [ ] Support instructions include a correlation ID or transaction signature when available. - [ ] Error messages avoid raw stack traces and expose useful next steps. ## Release gate Ship only when every critical path has: 1. A visible state for each lifecycle stage 2. A tested recovery path 3. A clear distinction between rejection, failure, and success 4. A reproducible test case for each known error condition

# Self-Directed Draft: Solana Account Fixture Kit ## Product concept An open-source CLI that captures selected Solana accounts as portable fixtures, then serves them through a lightweight mock JSON-RPC endpoint. Frontend teams can develop and test deterministic wallet, token, and program-account states without depending on live RPC data. ## Target users - Solana frontend and SDK teams - Developers reproducing account-state bugs - CI pipelines testing transaction-building logic ## Core workflow ```bash # Capture accounts from a configurable RPC endpoint safk capture \ --account <PUBKEY> \ --account <PUBKEY> \ --output fixtures/funded-wallet.json # Start a local mock RPC server safk serve fixtures/funded-wallet.json --port 8899 # Verify fixture integrity safk validate fixtures/funded-wallet.json ``` Applications point their RPC client to `http://localhost:8899`. ## MVP scope ### Capture Support these RPC methods: - `getAccountInfo` - `getMultipleAccounts` - `getBalance` - `getTokenAccountBalance` - `getTokenAccountsByOwner` Store: - Cluster label and capture timestamp - Public key, owner, lamports, executable flag, rent epoch - Base64 account data - Slot/context information - CLI version and fixture schema version ### Replay The local server returns deterministic responses for: - Captured account lookups - Balance queries derived from fixtures - Token-account queries filtered by owner and mint - `getLatestBlockhash`, using explicit synthetic values marked in configuration Unknown accounts return a configurable null response or strict error. ### Mutation Allow tests to derive new states without recapturing: ```bash safk mutate funded-wallet.json \ --set-lamports <PUBKEY>:0 \ --output empty-wallet.json ``` Initial mutation support: - Lamport balance - Account deletion - Owner replacement - Raw base64 data replacement ## Fixture format ```json { "schemaVersion": 1, "network": "custom", "capturedAt": "ISO-8601 timestamp", "context": { "slot": 0 }, "accounts": { "<PUBKEY>": { "lamports": 0, "owner": "<PROGRAM_ID>", "executable": false, "rentEpoch": 0, "data": ["<BASE64>", "base64"] } } } ``` ## Safety and privacy - Require explicit account addresses; no wallet discovery by default. - Display a warning before saving account data. - Never capture private keys, seed phrases, or signer material. - Redact configured JSON fields from decoded account exports. - Bind the replay server to localhost unless the user explicitly overrides it. ## Acceptance criteria - A captured account produces the same `getAccountInfo` payload across repeated local runs. - Missing accounts behave according to strict/null configuration. - Fixtures validate offline with useful path-specific errors. - CI can install, serve, test, and terminate the tool non-interactively. - Corrupt or unsupported fixture versions fail before the server starts. - README includes examples for `@solana/web3.js` and a generic HTTP client. ## Suggested implementation TypeScript, a minimal HTTP server, Zod-based schema validation, and Vitest integration tests. Publish as an npm package with both `safk` CLI and a programmatic fixture-server API.

# Self-Directed Draft: Solana RPC Budget Guard ## Product concept A CI-friendly tool that estimates and limits a Solana app’s RPC usage before code reaches production. Teams define request budgets for common user flows; the tool runs scripted scenarios against a configurable endpoint and fails when call count, payload size, latency, or retry thresholds are exceeded. ## Target users - Solana frontend and backend teams - Wallet and bot developers - Teams migrating between RPC providers - Maintainers diagnosing excessive polling or duplicate requests ## Core workflow ```bash rpc-guard record --scenario wallet-load --command "pnpm test:wallet" rpc-guard inspect .rpc-guard/wallet-load.json rpc-guard check --config rpc-guard.yaml ``` Example configuration: ```yaml scenarios: wallet-load: maxRequests: 12 maxResponseBytes: 500000 maxP95LatencyMs: 900 maxRetries: 1 rules: getProgramAccounts: maxCalls: 1 getLatestBlockhash: dedupeWithinMs: 1000 ``` Example report: ```text FAIL wallet-load Requests: 17 / 12 Response bytes: 431 KB / 500 KB P95 latency: 640 ms / 900 ms Retries: 3 / 1 Largest issue: getTokenAccountBalance called 6 times with identical parameters Suggestion: Cache the response for the duration of the wallet-load flow. ``` ## MVP scope 1. Local HTTP proxy for recording JSON-RPC traffic. 2. Scenario-based request budgets. 3. Detection of duplicate calls and aggressive polling. 4. Terminal, JSON, and Markdown reports. 5. Nonzero exit codes for CI enforcement. 6. Redaction of authorization headers and configurable JSON fields. 7. Comparison against a committed baseline. ## Non-goals - Operating an RPC endpoint - Guaranteeing provider costs - Sending transactions - Storing private keys - Production traffic interception ## Acceptance criteria - Works with any RPC URL supplied by the user. - Records method, timing, request size, response size, status, and retries. - Never writes headers or request bodies marked sensitive. - Produces deterministic pass/fail results from saved recordings. - Adds less than 50 ms of local proxy overhead per request in a basic benchmark. - Includes fixtures for successful responses, RPC errors, timeouts, and batch calls. ## Initial paid offer **RPC Usage Audit — fixed-scope delivery** Customer supplies one repository and up to three reproducible flows. Deliverables: - Recorded baseline - Duplicate-call and polling report - Proposed request budgets - CI configuration - Prioritized remediation checklist The CLI can remain open source, while audits, custom rules, and CI integration provide the paid service path.

# Self-Directed Draft: Solana CPI Safety Linter ## Product concept A local command-line tool that reviews Solana programs for common cross-program invocation (CPI) hazards before deployment. It analyzes Rust/Anchor source plus optional IDL and emits actionable findings with file locations, severity, and suggested tests. ## Target users - Solana program teams writing or reviewing CPI-heavy code - Auditors preparing an initial review - Developers maintaining Anchor programs with multiple authorities and token flows ## MVP command ```bash cpi-lint ./programs --idl target/idl --format markdown ``` Optional configuration: ```toml [policy] fail_on = "high" allow_programs = [] ``` ## Initial rules ### Authority and signer flow - PDA seeds used in `invoke_signed` do not visibly match the derived authority - A CPI expects a signer, but the supplied account is not marked or documented as one - User-controlled account data influences signer-seed selection without an explicit validation path ### Account permissions - Accounts passed as writable to a CPI without a documented mutation need - An account marked writable in the outer instruction is forwarded unnecessarily as writable - Program-owned accounts are passed to a CPI without an ownership check ### Program identity - CPI target is supplied dynamically without an allowlist or explicit validation - Hard-coded program IDs differ across source, configuration, or IDL references ### Token and asset flows - Authority, source, destination, and mint relationships are not validated before a token CPI - Close-account or transfer logic lacks a visible destination/authority relationship ## Report format Each finding includes: ```text [HIGH] CPI-003 Dynamic program account is not allowlisted Location: programs/vault/src/instructions/withdraw.rs:84 Why it matters: The caller may select an unintended program. Suggested fix: Validate the account against an expected program ID. Test idea: Pass a different executable account and assert rejection. ``` The report should separate: - **Confirmed pattern:** directly matched by a rule - **Review prompt:** suspicious pattern requiring human judgment - **Suppressed finding:** ignored by an inline annotation with a required reason ## MVP architecture 1. Parse Rust with a syntax-aware parser. 2. Build a lightweight instruction/account graph. 3. Detect CPI calls, account metadata, seeds, and nearby validation checks. 4. Parse IDL and configuration when provided. 5. Render terminal, JSON, and Markdown output. 6. Never submit transactions or contact an RPC endpoint. ## Acceptance criteria - Runs offline on a small Anchor workspace. - Produces stable output suitable for CI diffs. - Includes source spans for every finding. - Supports baseline files so existing findings do not block new work. - Has fixture tests for each rule, including false-positive cases. - Exits nonzero only when configured severity thresholds are exceeded. ## Non-goals - Replacing a security audit - Proving program correctness - Simulating every runtime behavior - Signing, deploying, or interacting with on-chain programs ## Suggested first deliverable A repository containing 10 rules, 20 positive/negative fixtures, JSON output, GitHub Actions documentation, and a short “how to interpret findings” guide.

# Self-Directed Draft: Solana Transaction Failure Triage Kit ## Product concept A small CLI and web-free report generator that turns a failed Solana transaction into a structured debugging packet. It accepts a transaction signature, RPC response, or pasted logs and produces likely failure categories, relevant instruction boundaries, and next diagnostic steps. ## Target users - Solana dApp developers - Protocol support engineers - QA and integration teams - SDK maintainers ## Core workflow ```text Input → Normalize → Segment instructions → Classify symptoms → Generate report ``` ### Inputs - Transaction signature - Raw program logs - RPC simulation output - Optional source-level metadata: - Program IDs - Instruction names - Known custom error mappings - Repository commit or build identifier ### Output report ```md # Transaction Triage Report ## Summary - Status: failed | simulated-failure | incomplete-input - Primary suspected layer: client | account validation | CPI | compute | authority - Confidence: low | medium | high ## Evidence - Relevant log lines - Error codes or returned data - Instruction index - Program IDs observed ## Hypotheses 1. ... 2. ... ## Next checks - [ ] Confirm account ownership - [ ] Confirm signer and writable flags - [ ] Decode custom error using the supplied mapping - [ ] Simulate with the same compute budget - [ ] Reproduce against the same program build ## Reproduction packet - Input fixture - Sanitized logs - Expected observation - Actual observation ``` ## Classification rules - **Account validation:** ownership, PDA, discriminator, signer, writable, or constraint-related messages. - **CPI failure:** a nested invocation fails after a parent instruction begins. - **Compute pressure:** logs indicate compute exhaustion or budget-related failure. - **Client encoding:** malformed instruction data, missing accounts, or serialization mismatch. - **Authority/state:** unauthorized signer, incorrect authority, or invalid state transition. - **Unknown:** insufficient evidence; avoid presenting a guess as a diagnosis. ## MVP commands ```bash triage logs.txt --program ./program-map.json triage signature <SIGNATURE> --rpc <RPC_URL> triage report.json --format markdown triage compare before.json after.json ``` ## Safety and privacy requirements - Never transmit logs unless the user explicitly configures a remote endpoint. - Redact configured public-key patterns, tokens, and environment-variable values. - Preserve raw input separately from the interpreted report. - Mark every conclusion as evidence-backed, heuristic, or unknown. - Do not infer private keys, user identity, or transaction intent. ## Acceptance criteria - Produces a report from pasted logs without network access. - Identifies instruction boundaries when invocation markers are present. - Keeps unknown errors explicitly unresolved. - Supports a user-provided custom error map. - Generates a deterministic report for identical inputs. - Includes the exact evidence supporting each hypothesis. ## Future extensions - Framework-specific adapters - CI mode for regression fixtures - Local log-diff visualization - Export to an issue template - Plugin interface for protocol-specific diagnoses

# Self-Directed Draft: Solana Account Migration Verifier ## Product concept A local developer tool that checks whether a proposed Solana account-layout migration is safe before deployment. It compares the old and new serializers, generates representative accounts, and reports compatibility risks. ## Target users - Anchor and native Solana program teams - Developers adding fields to existing accounts - Auditors reviewing migration logic - Maintainers of client SDKs ## Core problem Account changes can create subtle failures: incorrect discriminator handling, altered field order, truncated data, invalid defaults, or migrations that cannot be safely retried. Teams need a repeatable pre-deployment check instead of relying on manual inspection. ## MVP workflow ```text migration-check --old-schema ./schemas/v1.json --new-schema ./schemas/v2.json --fixture ./fixtures/accounts.json --migration ./tests/migrate.ts ``` The tool should: 1. Parse old and new schema definitions. 2. Detect additions, removals, reordering, type changes, and size changes. 3. Generate test accounts from supplied fixtures. 4. Run the migration function in a local test environment. 5. Re-read each migrated account using the new schema. 6. Run the migration a second time to test idempotency. 7. Emit a human-readable report and machine-readable JSON. ## Example report ```text Account: Position Status: REVIEW REQUIRED Changes: - Added field: risk_limit (u64) - Serialized size: 80 -> 88 bytes - Existing account allocation is too small Migration checks: [PASS] Existing fields preserved [PASS] New field receives an explicit default [FAIL] Reallocation path missing [WARN] Migration is not proven idempotent Suggested action: Add an authority-gated realloc step and rerun the fixture suite. ``` ## Safety rules - Never mutate a real cluster by default. - Require an explicit test adapter for migration execution. - Treat missing defaults as errors. - Treat field reordering and type changes as errors unless a custom decoder is supplied. - Require a repeat-run test for every migration. - Preserve the original fixture set for before/after comparison. ## MVP implementation - TypeScript CLI - JSON schema format first; add Anchor IDL support later - Adapter interface for custom serializers and migrations - Jest or Vitest test runner integration - Exit code `0` for pass, `1` for review required, `2` for invalid input - Markdown and JSON output ## Acceptance criteria - A developer can validate a migration using one command. - The tool identifies every changed field and serialized-size delta. - A fixture that cannot be decoded after migration fails clearly. - A non-idempotent migration is reported. - CI can fail on configured severity levels. - No network access is needed for the MVP. ## Future extensions - Anchor IDL import - PDA fixture generation - Migration cost estimates - GitHub Actions template - Suggested migration code for common append-only changes

# Self-Directed Draft: Solana Program Upgrade Readiness Checklist A reusable checklist for teams preparing a program deployment or upgrade. ## 1. Change definition - [ ] Record the program ID and intended upgrade authority. - [ ] Summarize the code change in one paragraph. - [ ] Identify affected instructions, accounts, PDAs, CPIs, and errors. - [ ] Note whether account layouts, instruction arguments, or serialized data change. - [ ] Define rollback or pause behavior before deployment. ## 2. Build reproducibility - [ ] Pin Rust, Solana CLI, Anchor, and dependency versions. - [ ] Generate the program binary from a clean checkout. - [ ] Save the commit identifier with the release artifact. - [ ] Confirm the deployed artifact matches the locally reviewed artifact. - [ ] Record build commands and required environment variables. ## 3. Test coverage - [ ] Run unit tests for changed logic. - [ ] Run integration tests against a local validator. - [ ] Test valid and invalid instruction inputs. - [ ] Test signer, owner, PDA-seed, and authority checks. - [ ] Test insufficient funds, duplicate calls, and replay-like scenarios. - [ ] Test account initialization and already-initialized accounts. - [ ] Test behavior with existing accounts created by the previous version. - [ ] Test CPI success and CPI failure paths. - [ ] Test compute-unit and transaction-size boundaries where relevant. ## 4. State compatibility - [ ] Compare old and new account layouts field by field. - [ ] Confirm serialization remains compatible, or define migration steps. - [ ] List every account requiring migration. - [ ] Specify whether migration is automatic, permissioned, or operator-run. - [ ] Verify rent and space requirements for newly created accounts. - [ ] Prepare a read-only inspection script for critical state. ## 5. Authority and safety - [ ] Confirm the upgrade authority is the intended signer or multisig. - [ ] Verify no test keys or local endpoints are present in deployment scripts. - [ ] Review privileged instructions for authorization and replay protection. - [ ] Confirm emergency controls have clear access rules. - [ ] Define who can approve, execute, and verify the upgrade. - [ ] Store sensitive credentials outside source control. ## 6. Release procedure - [ ] Announce a maintenance window internally. - [ ] Freeze unrelated releases during the upgrade. - [ ] Capture pre-upgrade program and critical account information. - [ ] Deploy using a written command sequence. - [ ] Verify the deployed program and upgrade authority. - [ ] Run a smoke test covering the primary user flow. - [ ] Compare expected and observed account changes. - [ ] Record transaction signatures and operator notes. ## 7. Post-upgrade review - [ ] Monitor error logs and failed transaction patterns. - [ ] Confirm dependent clients use the correct IDL or interface version. - [ ] Check indexers, relayers, and automation for compatibility. - [ ] Reconcile critical balances and counters. - [ ] Document anomalies and follow-up fixes. - [ ] Archive the release artifact, commit, test results, and approval record. ## Go/No-Go rule Do not proceed if any item involving authority, account compatibility, rollback behavior, or artifact verification is unresolved.

# Self-Directed Draft: Solana RPC Failure Triage CLI ## Concept A local TypeScript CLI that runs the same transaction simulation against multiple configured RPC endpoints and produces a normalized comparison report. ## User Problem When simulation results differ or fail unexpectedly, developers need a quick way to distinguish transaction issues from endpoint-specific behavior without manually repeating requests and comparing raw JSON. ## Core Command ```bash sol-triage simulate \ --transaction ./fixtures/swap.base64 \ --rpc dev=https://example-rpc-a \ --rpc backup=https://example-rpc-b \ --output ./reports/simulation.json ``` ## MVP Requirements - Accept a base64-encoded serialized transaction from a file or stdin. - Support multiple named RPC endpoints. - Allow optional endpoint headers through environment variables. - Request transaction simulation from every endpoint concurrently. - Apply a configurable timeout per request. - Redact endpoint credentials from logs and reports. - Normalize and compare: - request duration - RPC error code and message - simulation error - program logs - compute units consumed, when returned - replacement blockhash, when returned - returned account data, when requested - Emit human-readable terminal output and machine-readable JSON. - Exit nonzero when endpoints disagree or all requests fail. ## Example Terminal Report ```text RPC SIMULATION TRIAGE dev 184 ms OK units=42,810 backup 691 ms FAILED InstructionError[2] DIFFERENCES - Result status differs - backup log diverges at line 7 - Compute-unit comparison unavailable Credentials redacted: yes Report written: ./reports/simulation.json ``` ## Safety Defaults - Never sign, submit, or modify transactions. - Reject endpoint URLs containing inline credentials unless explicitly allowed. - Omit full transaction bytes from reports by default. - Limit stored log length and mark truncation. - Keep configuration and reports local. ## Suggested Package Layout ```text src/ cli.ts config.ts simulate.ts normalize.ts compare.ts redact.ts reporters/ terminal.ts json.ts ``` ## Acceptance Criteria - Two mocked endpoints with equivalent responses produce no differences. - Divergent errors identify the affected endpoint and response field. - A timed-out endpoint does not block remaining results. - Secrets supplied through headers never appear in output. - JSON output remains stable enough for CI assertions. - The CLI performs no transaction-submission RPC call. ## Follow-On Feature Add a `capture` mode that saves sanitized simulation fixtures for regression testing without requiring live endpoints.

# Self-Directed Draft: Solana Account Diff CLI ## Product specification ### Concept A TypeScript CLI that captures Solana account state before and after a transaction, then generates a readable diff for testing and review. ### Problem Transaction signatures confirm submission but do not clearly explain resulting state changes. Developers often inspect balances, owners, raw bytes, and decoded fields manually across several accounts. ### Command Design ```bash sol-diff capture --cluster devnet --accounts accounts.json --out before.json sol-diff capture --cluster devnet --accounts accounts.json --out after.json sol-diff compare before.json after.json --format markdown ``` Optional transaction workflow: ```bash sol-diff watch \ --accounts accounts.json \ --command "npm run execute-test" \ --out report.md ``` ### Input ```json { "accounts": [ { "address": "<PUBLIC_KEY>", "label": "Treasury", "decoder": "system" }, { "address": "<PUBLIC_KEY>", "label": "Position", "decoder": "./decoders/position.ts" } ] } ``` ### Report Output ```md ## Position - Lamports: 2,039,280 → 2,044,280 (+5,000) - Owner: unchanged - Data length: 96 → 104 bytes ### Decoded fields | Field | Before | After | |---|---:|---:| | status | pending | active | | collateral | 1000000 | 1250000 | | updatedSlot | 120 | 124 | ``` ### MVP Requirements - Capture account address, lamports, owner, executable status, rent epoch, and base64 data. - Record cluster, RPC URL alias, slot, timestamp, and commitment. - Compare added, removed, and modified accounts. - Highlight lamport, ownership, data-length, and raw-data changes. - Support pluggable TypeScript decoders. - Export JSON and Markdown. - Redact configured decoded fields. - Return a nonzero exit code when declared assertions fail. ### Assertion File ```json { "assertions": [ { "account": "Treasury", "field": "lamports", "change": "decrease" }, { "account": "Position", "field": "status", "equals": "active" } ] } ``` ### Safety Boundaries - Read-only RPC access. - Never request seed phrases or private keys. - Omit RPC credentials from generated reports. - Warn when snapshots use different clusters or commitments. - Preserve integer values as strings when JSON number precision may be unsafe. ### Definition of Done - Works against local validator and configurable RPC endpoints. - Includes fixture-based decoder tests. - Produces deterministic diffs from identical snapshots. - Documents custom decoder and CI usage. - Ships with an example account list, snapshots, assertions, and report.

# Self-Directed Draft: Solana Program Upgrade Checklist A reusable release gate for teams upgrading an existing onchain program. ## 1. Change Review - [ ] Release commit and version are recorded. - [ ] Program ID and target cluster are explicitly confirmed. - [ ] Binary is built from a clean, documented environment. - [ ] Build output is reproducible by a second team member or CI. - [ ] New instructions, accounts, errors, and events are documented. - [ ] Account layout changes include a migration strategy. - [ ] Compute, transaction size, and fee impacts are tested. - [ ] Security-sensitive changes receive independent review. ## 2. Compatibility - [ ] Existing accounts deserialize under the new program. - [ ] Existing instructions retain expected behavior or are versioned. - [ ] SDK, IDL, API, and UI changes are prepared together. - [ ] Indexers and automation can process new data formats. - [ ] Deprecated behavior has a communicated removal path. - [ ] Tests cover old clients interacting with the upgraded program. ## 3. Upgrade Controls - [ ] Upgrade authority is identified and accessible. - [ ] Required signer availability is confirmed without sharing secrets. - [ ] Multisig proposal and approval steps are rehearsed, if applicable. - [ ] Treasury has sufficient SOL for deployment-related costs. - [ ] Current deployed binary, IDL, and configuration are archived. - [ ] Rollback binary and operator instructions are ready. - [ ] A stop condition and final decision owner are named. ## 4. Preflight - [ ] Upgrade is tested on the intended non-production environment. - [ ] Critical user journeys pass end-to-end. - [ ] Failure cases and unauthorized calls are tested. - [ ] Monitoring queries and alerts are prepared. - [ ] RPC dependencies and fallback procedures are documented. - [ ] Support copy explains expected user-visible changes. - [ ] Upgrade window avoids known internal operational conflicts. ## 5. Execution - [ ] Operators verify cluster, program ID, binary hash, and authority aloud. - [ ] Team pauses unrelated production changes. - [ ] Upgrade transaction result is independently checked. - [ ] Program data and authority state are verified after deployment. - [ ] Smoke tests cover every critical instruction. - [ ] Logs and error rates are monitored during the observation window. ## 6. Closeout - [ ] Release artifact records commit, binary hash, transaction signature, and time. - [ ] SDK, IDL, documentation, and UI releases are synchronized. - [ ] Any temporary permissions or operational controls are removed. - [ ] Incidents and unexpected behavior are documented. - [ ] Upgrade authority changes are completed if planned. - [ ] Team records a clear **ship / rollback / investigate** decision. ## Release Record ```text Version: Cluster: Program ID: Commit: Binary hash: Upgrade authority: Operator: Approver: Upgrade signature: Started: Completed: Decision: Notes: ```

# Self-Directed Draft: Solana Transaction Support Bundle ## Product specification ### Concept An open-source TypeScript utility that turns failed Solana transaction attempts into a sanitized, copyable diagnostic bundle for support teams. ### Problem “Transaction failed” reports often omit the details developers need: cluster, wallet type, signature status, RPC response, simulation logs, and application version. Reproducing the issue becomes a lengthy support exchange. ### User promise **Give support useful debugging context without exposing private keys, seed phrases, or unnecessary wallet data.** ### Target users - Solana dApp developers - Customer support teams - Wallet integration engineers - QA testers ## MVP workflow 1. The app records structured context around a transaction attempt. 2. Sensitive fields are removed or masked. 3. The user reviews the resulting bundle. 4. The user copies or downloads it for a support ticket. ## Proposed API ```ts const bundle = await createSupportBundle({ connection, transaction, signature, error, context: { cluster: "mainnet-beta", appVersion: "1.4.2", action: "stake" } }); const safeBundle = bundle.redact({ walletAddress: "partial", transactionMessage: "include" }); await safeBundle.copy(); ``` ## Bundle schema ```ts type SupportBundle = { createdAt: string; cluster?: string; rpcHost?: string; appVersion?: string; action?: string; wallet?: { adapter?: string; address?: string; }; transaction?: { signature?: string; recentBlockhash?: string; simulationLogs?: string[]; confirmationStatus?: string; }; error: { name?: string; message: string; code?: string | number; }; environment?: { browser?: string; os?: string; }; redactions: string[]; }; ``` ## Required safeguards - Never collect seed phrases, private keys, cookies, or authorization headers. - Require explicit review before copying or downloading. - Mask wallet addresses by default. - Remove query parameters and credentials from RPC URLs. - Keep bundle generation local unless the host app explicitly adds transport. - Label simulation output as diagnostic rather than authoritative. ## UI component ```tsx <TransactionSupportButton transaction={transaction} error={error} label="Create support report" /> ``` The review screen should show: - Included fields - Redacted fields - Plain-language privacy warning - **Copy JSON** and **Download JSON** actions - Optional “Start over” action ## MVP acceptance criteria - Works with legacy and versioned transactions. - Produces valid, versioned JSON. - Handles missing signatures and unsuccessful simulations. - Redacts configured fields deterministically. - Includes no automatic upload behavior. - Provides unit tests for redaction and URL sanitization. - Includes an integration example using a common wallet-adapter flow. ## Suggested package layout ```text packages/core packages/react examples/wallet-adapter docs/privacy-model.md docs/support-workflow.md ``` ## Initial positioning copy **Stop asking users for screenshots of “Transaction failed.”** Generate a reviewable Solana support bundle containing the transaction context, simulation logs, environment details, and sanitized error data your team needs to investigate—without collecting wallet secrets.

# Self-Directed Draft: Solana Wallet Action Preview ## Product specification ### One-line concept A lightweight SDK that converts a planned Solana wallet action into a human-readable preview before the user signs. ### User promise **“Know what this transaction is intended to do before approving it.”** ### Target users - Solana dApp teams building swaps, mints, claims, staking, and account-management flows - Wallet-integrated products that need clearer signing UX - Support teams handling “I didn’t know what I approved” complaints ### Core workflow 1. The dApp creates a transaction or instruction set. 2. The SDK extracts relevant intent data. 3. The UI displays a preview: - Action type - Programs involved - Assets expected to leave the wallet - Assets expected to arrive - Account creations or closures - Estimated network fee, when available - Warnings for unknown or unsupported instructions 4. The user chooses **Approve**, **Cancel**, or **View details**. 5. The dApp records a privacy-safe preview ID for support diagnostics. ### MVP scope Support a normalized intent model: ```ts type WalletActionPreview = { title: string; network: "mainnet" | "devnet" | "testnet" | "unknown"; actions: Array<{ kind: "transfer" | "swap" | "mint" | "stake" | "account-change" | "unknown"; source?: string; destination?: string; asset?: string; amount?: string; direction?: "in" | "out"; confidence: "high" | "medium" | "low"; }>; programs: Array<{ address: string; label?: string; recognized: boolean; }>; warnings: string[]; }; ``` ### Safety rules - Never request or store private keys. - Never present decoded data as certain when parsing is incomplete. - Display truncated addresses with a copy-to-view-full option. - Label unknown programs and instructions clearly. - Treat token metadata as untrusted display data. - Require explicit confirmation when an action cannot be classified. ### Suggested package structure ```text wallet-action-preview/ src/parser/ src/normalizers/ src/components/ src/redaction/ tests/fixtures/ docs/integration.md ``` ### Acceptance criteria - Produces a preview from a serialized transaction or instruction list. - Handles multiple instructions in one transaction. - Shows unknown instructions without silently omitting them. - Includes unit fixtures for transfer, swap-like, mint, and unsupported actions. - Provides a React component plus framework-agnostic JSON output. - Redacts public keys in logs by default. - Returns deterministic output for identical input. ### Launch message draft > Signing prompts should explain intent, not just display bytes. > > We’re building a small Solana SDK for readable wallet action previews: assets in/out, programs involved, account changes, and clear warnings when something cannot be decoded. > > The goal is simple: fewer surprises, better support conversations, and more confident approvals—without handling private keys.

# Self-Directed Draft: Solana Integration Readiness Scorecard ## Purpose A reusable checklist for teams preparing a Solana integration for internal testing, beta access, or public release. It helps product, engineering, and support teams identify missing decisions before users encounter them. ## Completion rule Mark each item: - **Ready** — implemented and tested - **Needs work** — known gap with an owner - **Not applicable** — documented reason A release should not proceed with unexplained “Needs work” items in security, transaction clarity, or recovery. --- ## 1. User flow - [ ] The user can connect and disconnect a wallet. - [ ] The app explains why wallet access is requested. - [ ] Every transaction has a clear human-readable purpose. - [ ] The user can review the intended asset, amount, destination, and fee context. - [ ] Loading, approval, success, and failure states are distinct. - [ ] Refreshing the page does not create accidental duplicate actions. - [ ] The app explains what the user should do after closing or rejecting a wallet prompt. ## 2. Transaction behavior - [ ] The app handles rejected wallet signatures. - [ ] The app handles expired or otherwise invalid transactions. - [ ] The UI distinguishes “submission unknown” from confirmed failure. - [ ] Repeated clicks cannot unintentionally submit duplicate actions. - [ ] Confirmation status is derived from a documented policy. - [ ] The app provides a safe way to retry when retrying is appropriate. - [ ] Transaction details shown to the user match the actual instruction intent. ## 3. Asset and account handling - [ ] Unsupported assets are blocked with an actionable message. - [ ] Decimal precision and rounding rules are documented. - [ ] Insufficient balance is detected before signing where practical. - [ ] Missing token-account or program-account conditions have a user-facing path. - [ ] Address fields are validated and displayed consistently. - [ ] The app does not request unnecessary wallet permissions or data. ## 4. Safety and privacy - [ ] No secret keys, seed phrases, or signing material enter application logs. - [ ] Sensitive payloads are excluded from analytics by default. - [ ] External links and destinations are clearly labeled. - [ ] Admin or operator actions require explicit authorization. - [ ] Error messages avoid exposing secrets, internal credentials, or private user data. - [ ] A security contact and incident-handling owner are documented internally. ## 5. Testing evidence - [ ] Tests cover approval, rejection, timeout, retry, and refresh scenarios. - [ ] Tests cover a new user and a returning user. - [ ] Tests cover small, zero, maximum, and invalid input values where relevant. - [ ] At least one test verifies the displayed transaction intent against constructed instructions. - [ ] Mobile wallet behavior is tested if mobile users are supported. - [ ] Each known limitation has a reproducible example and owner. ## 6. Support handoff - [ ] Support can identify the user’s current flow state without requesting secrets. - [ ] A diagnostic template captures app version, wallet type, action, timestamp, and sanitized error text. - [ ] Support instructions explain when not to ask a user to retry. - [ ] Known issues and workarounds are versioned. - [ ] Release notes describe user-visible behavior changes. ## Release note template **Release:** **Scope:** **Ready items:** **Known limitations:** **User impact:** **Rollback or disable path:** **Owner:** **Next review date:**

# Self-Directed Draft: Solana Transaction Failure Triage Kit ## Product specification A small TypeScript library and CLI that turns failed Solana transaction attempts into privacy-safe, actionable diagnostic reports for developers and support teams. ### User promise **“Give me the likely cause of a failed transaction without exposing user keys or raw application data.”** ### Problem When a transaction fails, teams often need to correlate: - The client-side error - Instruction and account metadata - Simulation output - Blockhash and fee-payer state - Retry history - Program logs Copying raw transactions into chat or tickets can expose sensitive information and still leave engineers with an unstructured debugging process. ### Target users - Solana application engineers - Wallet and support teams - QA engineers testing transaction flows - SDK maintainers handling user-reported failures ## MVP scope ### Library API ```ts const report = await diagnoseTransaction({ connection, transaction, stage: "preflight", error, labels: { appVersion: "local-dev", flow: "token-transfer" } }); ``` The library should: 1. Simulate the transaction when possible. 2. Collect structured logs and error information. 3. Record instruction program IDs and account roles. 4. Redact public-key fields according to configurable rules. 5. Avoid collecting secret keys, seed phrases, signed message contents, or raw account data by default. 6. Emit a stable JSON report. ### CLI ```bash solana-tx-triage report.json solana-tx-triage summarize report.json ``` The `summarize` command produces: - Failure category - Most relevant log lines - Suspected failing instruction - Retry recommendation - Missing-data warnings - A short support-ticket summary ## Initial failure categories - Simulation rejected - Blockhash or expiry issue - Account missing or unreadable - Account ownership mismatch - Signature or authorization failure - Compute or fee-budget concern - Custom program error - RPC response unavailable - Unknown Categories are hypotheses, not guarantees. The report must retain the underlying evidence used for each classification. ## Example output ```json { "status": "failed", "category": "custom_program_error", "confidence": "medium", "failingInstruction": 2, "programId": "[redacted:program]", "evidence": [ "Simulation returned a custom program error", "Program log emitted before failure" ], "nextChecks": [ "Map the custom error code using the deployed IDL or source", "Reproduce with the same account state" ], "redactionsApplied": 4 } ``` ## Non-goals - Automatically retrying or resubmitting transactions - Signing transactions - Sending transactions on behalf of users - Claiming certainty from incomplete logs - Uploading reports to a hosted service ## Acceptance checklist - [ ] No private key material is accepted by the API. - [ ] Default output contains no raw instruction data. - [ ] Redaction behavior is covered by tests. - [ ] Reports remain useful when simulation is unavailable. - [ ] Every classification includes supporting evidence. - [ ] CLI output is readable in a support ticket. - [ ] A fixture suite covers success, simulation failure, timeout, and custom errors. ## Suggested packaging - `@tx-triage/core` - `@tx-triage/cli` - Local-only JSON reports - MIT-licensed starter templates and test fixtures

# Self-Directed Draft: Solana RPC Resilience Harness ## Product specification A CLI that runs repeatable fault scenarios against a Solana application’s RPC client configuration to verify fallback, retry, timeout, and duplicate-submission behavior. ### User promise **“Know how your app behaves when its RPC provider becomes slow, stale, or unavailable.”** ### Problem RPC failure handling is difficult to validate consistently. A configuration may appear reliable during normal development but behave poorly when requests time out, return errors, or reach endpoints with differing response times. ### Target users - Wallet and dApp engineering teams - Trading and automation developers - Infrastructure teams operating multiple RPC endpoints - SDK maintainers testing transport behavior ### MVP workflow ```bash npm install -D rpc-resilience-harness npx rrh init npx rrh run --scenario timeout-failover ``` `rrh init` creates: ```yaml endpoints: - name: primary url: ${PRIMARY_RPC_URL} - name: fallback url: ${FALLBACK_RPC_URL} policy: timeoutMs: 1500 maxRetries: 2 assertions: maxRecoveryMs: 4000 requireFallback: true preventDuplicateSend: true ``` ### Initial scenarios 1. **Timeout failover** — delay the primary endpoint and confirm fallback occurs. 2. **HTTP error burst** — inject temporary 429 or 5xx responses. 3. **Malformed response** — return invalid JSON-RPC payloads. 4. **Stale-read simulation** — serve an older recorded response for selected read methods. 5. **Submission ambiguity** — interrupt `sendTransaction` after forwarding it, then detect unsafe resubmission. 6. **Total outage** — make every configured endpoint unavailable and verify the surfaced application error. ### Output ```text PASS timeout-failover fallback selected: fallback recovery: 1,842 ms duplicate submissions: 0 FAIL submission-ambiguity transaction forwarded: yes client retried sendTransaction: 2 times expected: no duplicate submission ``` The CLI exits nonzero when an assertion fails and writes a JSON report for CI. ### Architecture - Local JSON-RPC proxy placed between the application and configured endpoints - Scenario engine for delays, errors, disconnections, and recorded responses - Request correlation that hashes transaction payloads to identify repeated submissions - Adapter interface for custom assertions - Secrets read from environment variables and excluded from reports ### Acceptance criteria - Runs locally with one command after configuration. - Supports HTTP JSON-RPC traffic without requiring application code changes beyond the endpoint URL. - Produces deterministic scenario results from a seed. - Redacts endpoint credentials in console and JSON output. - Detects identical transaction payloads sent more than once during a scenario. - Works in CI and returns documented exit codes. ### Scope boundaries The MVP does not emulate consensus, guarantee transaction outcomes, benchmark provider quality, or send transactions unless the user explicitly targets a live endpoint. ### Packaging - Open-source CLI: core proxy, built-in scenarios, JSON reports - Paid team edition: shared scenario packs, historical CI reports, and policy enforcement ### Landing-page copy **Your fallback RPC is not a resilience strategy until it has been tested.** Inject timeouts, error bursts, stale reads, and ambiguous submissions into your Solana RPC flow. Catch unsafe retries and slow recovery before users encounter them.

# Self-Directed Draft: Solana Account Compatibility Scanner ## Product specification A CLI that checks whether a proposed Solana program release can safely read existing accounts and identifies schema-compatibility risks before deployment. ### User promise **“Find account migration hazards before your upgrade reaches users.”** ### Problem Program upgrades may change account layouts, discriminators, enum variants, or required fields. Teams need a repeatable way to compare an expected schema with representative account data and flag potentially unsafe changes. ### MVP Command: ```bash account-compat scan \ --old-schema ./schemas/v1.json \ --new-schema ./schemas/v2.json \ --fixtures ./accounts/ ``` Output: ```text PASS unchanged fields: 8 WARN added field: rewards_debt FAIL field removed: authority FAIL type changed: amount u64 -> u128 WARN enum variant added: Paused ``` ### Input format A small JSON schema describing: - Account name - Discriminator - Field order - Field types - Optional or required status - Enum variants - Expected byte length, where fixed Fixtures are sanitized account byte arrays or decoded JSON representations supplied by the developer. ### Rules - Flag removed fields as breaking. - Flag reordered fields as breaking for positional layouts. - Flag type changes as breaking unless an explicit compatibility rule exists. - Flag added required fields as migration-required. - Flag added optional or trailing fields as review-required. - Flag discriminator changes as breaking. - Report fixed-size length changes. - Allow a checked-in exceptions file with a required explanation. ### Deliverables - Rust CLI - JSON schema format - Human-readable terminal report - Machine-readable JSON report for CI - GitHub Actions example - Five fixture-based test cases covering safe, breaking, and migration-required changes ### CI behavior Exit codes: - `0`: no blocking findings - `1`: compatibility failures - `2`: invalid input or malformed schema Example workflow step: ```yaml - name: Check account compatibility run: | account-compat scan \ --old-schema schemas/v1.json \ --new-schema schemas/v2.json \ --fixtures test/accounts \ --format json \ --output compatibility.json ``` ### Non-goals - Deploying programs - Performing migrations - Guessing runtime behavior from source code - Treating all schema changes as automatically safe ### Definition of done A team can place two schema files and representative account fixtures in a repository, run one command locally or in CI, and receive deterministic findings that explain which account changes require review or migration.

# Self-Directed Draft: Solana Transaction Fixture Kit ## Product specification A developer tool that captures sanitized Solana transaction simulations as portable fixtures, then replays assertions locally or in CI. ### User promise **“Turn hard-to-reproduce transaction failures into regression tests.”** ### Problem Transaction bugs often depend on a specific combination of: - Instructions and account ordering - Serialized instruction data - Compute limits - Program logs - RPC simulation responses - Wallet or client configuration Sharing raw logs is incomplete, while repeatedly querying an RPC makes tests slow and nondeterministic. ### Core workflow ```bash # Capture a simulation sol-fixture capture --transaction ./tx.base64 --out fixtures/swap-failure.json # Remove or replace sensitive addresses sol-fixture sanitize fixtures/swap-failure.json --map addresses.json # Add expected behavior sol-fixture expect fixtures/swap-failure.json \ --error "Custom:6001" \ --log "slippage exceeded" \ --max-compute 180000 # Run in CI without RPC access sol-fixture test fixtures/ ``` ### Fixture contents - Transaction encoding and message version - Instruction program IDs, account indexes, and data - Simulation configuration - Resulting error - Program logs - Compute units consumed - Return data - Optional account snapshots - Explicit schema version - User-defined assertions Private keys and wallet seed material must never be accepted or stored. ### MVP commands | Command | Purpose | |---|---| | `capture` | Simulate through a configured RPC and save the response | | `sanitize` | Redact or deterministically alias addresses and data fields | | `inspect` | Print a readable instruction, log, and compute summary | | `expect` | Attach assertions to a fixture | | `test` | Validate fixtures without making network requests | | `schema` | Print fixture JSON Schema for integrations | ### Initial assertions - Simulation succeeds or returns an expected error - Log contains or excludes text - Program invocation count matches - Compute consumption stays below a threshold - Return data matches an encoded value - Required instruction or program ID is present ### Design constraints - JSON fixtures must remain human-reviewable. - Offline tests must produce identical results from identical fixtures. - Unknown fields must be preserved during format upgrades. - Captured addresses are public by default but clearly marked as potentially sensitive. - Exit codes must be stable and CI-friendly. ### Acceptance criteria 1. A developer can capture and inspect one simulation with two commands. 2. `test` performs no network requests. 3. A failed assertion identifies the fixture, expected value, and observed value. 4. Sanitization produces consistent aliases across multiple fixtures. 5. Fixtures validate against a published local JSON Schema. 6. Corrupt or incompatible fixtures fail with actionable messages. ### Packaging Implement as a TypeScript CLI with a library API: ```ts import { loadFixture, assertFixture } from "@sol-fixture/core"; const fixture = await loadFixture("fixtures/swap-failure.json"); assertFixture(fixture); ``` ### Scope boundary The MVP records simulation artifacts; it does not emulate the Solana runtime, execute programs locally, manage keys, or guarantee that a previously captured result still reflects current onchain state.

# Self-Directed Draft: Solana RPC Resilience Harness ## Product specification A local CLI that tests a Solana application’s RPC failover behavior by simulating timeouts, rate limits, stale blockhashes, malformed responses, and inconsistent endpoints. ### User promise **“Prove your app survives RPC failures before users encounter them.”** ### Problem Applications often depend on retry and fallback logic that is difficult to test safely. Common failure paths may remain untested until an endpoint becomes slow, unavailable, or inconsistent. ### Target users - Wallet and trading interface developers - Solana backend teams - SDK maintainers - QA and reliability engineers ### Core workflow ```bash rpc-harness proxy \ --upstream "$SOLANA_RPC_URL" \ --port 8899 \ --scenario scenarios/degraded.yaml ``` The application points to `http://localhost:8899`. The proxy forwards requests while injecting configured failures and recording recovery behavior. ### Scenario format ```yaml name: degraded-primary seed: 42 rules: - method: getLatestBlockhash occurrence: [1, 2] action: type: timeout delay_ms: 5000 - method: sendTransaction probability: 0.25 action: type: rpc_error code: -32002 message: simulated preflight failure - method: getSignatureStatuses action: type: latency delay_ms: 1200 assertions: max_unhandled_errors: 0 max_retry_attempts: 4 recovery_within_ms: 10000 ``` ### MVP commands ```bash rpc-harness proxy --upstream URL --scenario FILE rpc-harness validate FILE rpc-harness report run.json rpc-harness init ``` ### MVP failure actions - Fixed or randomized latency - Connection timeout - HTTP 429 or 503 - JSON-RPC error response - Dropped connection - Repeated stale response - Failure on a specific request occurrence - Seeded probabilistic failure ### Run report Each run produces JSON plus a terminal summary: ```text Scenario: degraded-primary Requests: 38 Injected failures: 5 Retries observed: 4 Unhandled failures: 0 Recovery time: 3.8s Result: PASS ``` Request bodies containing signed transactions should be redacted by default. Logging full payloads requires an explicit flag. ### Exit codes - `0`: all assertions passed - `1`: scenario assertion failed - `2`: invalid configuration - `3`: proxy or upstream setup failure ### Non-goals for MVP - Hosting a public proxy - Inspecting private keys - Mainnet load testing - Automatically judging transaction correctness - Replacing full integration tests ### Acceptance criteria 1. Proxy supports standard JSON-RPC POST traffic. 2. Identical seeds produce identical injected-failure decisions. 3. Rules can target RPC method and request occurrence. 4. Reports distinguish upstream failures from injected failures. 5. Sensitive transaction payloads are redacted by default. 6. CLI exits nonzero when an assertion fails. 7. A sample application can run the harness in CI without external services beyond its configured RPC endpoint. ### Suggested implementation - TypeScript CLI - Node HTTP proxy - YAML scenario parser with schema validation - JSON Lines event log - Vitest integration suite using a mock upstream server ### Initial package boundary - `@rpc-harness/core`: rule engine and event model - `@rpc-harness/cli`: proxy, validation, and reports - `@rpc-harness/scenarios`: reusable example scenarios

# Self-Directed Draft: Solana IDL Compatibility Gate ## Product specification A CI-ready CLI that compares two Anchor IDL files and flags changes likely to break clients, generated SDKs, or transaction builders. ### User promise **“Know whether an IDL update is backward-compatible before merging it.”** ### Problem Program changes can silently disrupt integrations when they: - Rename or remove instructions - Reorder instruction accounts - Change signer or writable requirements - Modify argument or account-field types - Remove errors, events, or defined types - Change PDA seed definitions Reviewing large IDL diffs manually is slow and inconsistent. ### Proposed interface ```bash idl-gate compare ./main.json ./candidate.json idl-gate compare ./main.json ./candidate.json --format json idl-gate compare ./main.json ./candidate.json --fail-on risky ``` Example output: ```text IDL Compatibility Report BREAKING - instruction `deposit`: account `vault` moved from position 2 to 3 - instruction `withdraw`: argument `amount` changed u64 -> u128 - account `Position`: field `authority` removed RISKY - instruction `claim`: `payer` is now writable - PDA `vault`: seed order changed SAFE - error `MathOverflow` added - instruction `pause` added Result: FAILED (3 breaking, 2 risky, 2 safe) ``` ### Classification rules **Breaking** - Existing instruction, account, type, event, or field removed - Instruction argument order or type changed - Instruction account order changed - Account signer requirement changed - Enum variant removed or reordered - Struct field type changed - PDA seed removed, reordered, or type-changed **Risky** - Account becomes writable - Optional account becomes required - New field added to a serialized account type - Error code or enum discriminant changes - Defined type changes size **Safe** - New instruction, error, event, or standalone type added - Documentation-only changes - Required account becomes optional - Non-serialized metadata changes ### Configuration ```yaml fail_on: breaking ignore: - docs allow: removed_errors: - LegacyFailure overrides: "instructions.initialize.accounts.payer.writable": safe ``` Overrides must include a reviewer-visible reason: ```yaml overrides: "types.Mode.variants": severity: safe reason: "Program has not shipped this enum." ``` ### Machine-readable result ```json { "compatible": false, "summary": {"breaking": 3, "risky": 2, "safe": 2}, "changes": [{ "path": "instructions.deposit.accounts.vault.index", "severity": "breaking", "before": 2, "after": 3 }] } ``` ### MVP acceptance criteria - Accept Anchor IDL JSON files without network access - Produce deterministic text and JSON reports - Exit nonzero according to configurable severity - Detect instruction, account, argument, type, event, error, and PDA changes - Support path-specific overrides with required reasons - Include fixture-based tests for every classification rule - Run as a standalone binary or CI command ### Non-goals - Proving on-chain program safety - Comparing compiled binaries - Automatically rewriting client code - Claiming compatibility for custom serializers absent from the IDL ### Suggested positioning **IDL Gate — semantic compatibility checks for Solana program interfaces.**

# Self-Directed Draft: Solana Transaction Intent Linter ## Product specification A local CLI and library that checks whether a transaction’s declared instructions match an explicit human-readable intent before signing. ### User promise **“Make every transaction’s purpose inspectable before approval.”** ### Problem Solana transactions can contain multiple instructions, writable accounts, signers, and opaque byte payloads. Wallet prompts and code review may not clearly communicate: - Which accounts can be changed - Which accounts authorize the action - Whether unexpected instructions are present - Whether the transaction matches the application’s intended operation ### Target users - Wallet and dApp developers - Protocol QA engineers - Security reviewers - Teams building transaction-generation SDKs ## MVP scope ### 1. Intent manifest Define an expected transaction in YAML or JSON: ```yaml name: deposit instructions: - program: "PROGRAM_PUBKEY" discriminator: "BASE58_OR_HEX" accounts: writable: - "USER_TOKEN_ACCOUNT" - "VAULT_ACCOUNT" signers: - "USER" args: amount: type: u64 min: 1 ``` ### 2. Transaction inspection Given a serialized transaction or instruction list, report: - Instruction count and order - Program IDs - Writable accounts - Signers - Unrecognized programs - Argument values that violate declared constraints - Missing, extra, or incorrectly ordered instructions ### 3. CI and local usage ```bash txlint check --manifest deposit.yaml --transaction tx.json ``` Exit nonzero when the transaction violates the manifest. ### 4. Human-readable report ```text FAIL: deposit Unexpected program: index 1: PROGRAM_PUBKEY_X Unexpected writable account: index 0: ACCOUNT_X Argument violation: amount = 0; minimum = 1 ``` ## Design constraints - Never sign, submit, or broadcast transactions - Treat unknown instruction data as opaque unless a decoder is configured - Make strictness configurable per field - Support partially specified manifests for incremental adoption - Keep private keys and RPC credentials out of the tool ## Suggested architecture - **Parser:** serialized transaction and instruction normalizer - **Manifest loader:** schema validation and defaults - **Matcher:** ordered instruction and account comparison - **Decoder registry:** optional program-specific argument decoders - **Reporter:** terminal, JSON, and GitHub-style annotations - **Library API:** reusable from TypeScript test suites ## Acceptance criteria - Detects an unexpected program ID - Detects an unexpected signer or writable account - Detects missing and extra instructions - Validates numeric argument bounds when a decoder exists - Produces deterministic JSON output - Returns a nonzero exit code on failure - Includes fixtures for passing, missing-instruction, reordered-instruction, and privilege-escalation cases ## Future extensions - Generate manifests from approved transaction fixtures - Compare pre- and post-simulation account metadata - Add redaction controls for logs - Provide editor diagnostics for manifest errors - Support policy packs for common transaction patterns

# Self-Directed Draft: Solana Account Lifecycle Auditor ## Product specification A local CLI and test helper that checks whether Solana accounts are safely initialized, resized, closed, and authority-managed across program instructions. ### User promise **“Find unsafe account lifecycle transitions before they reach production.”** ### Problem Account bugs often appear at state boundaries: - Re-initializing an existing account - Closing an account without clearing dependent state - Reallocating without preserving data or funding rent needs - Leaving an authority transition incomplete - Accepting stale or unexpected account ownership These issues can be difficult to spot in isolated instruction tests. ### Target users - Solana program teams - Anchor developers - Security reviewers - QA engineers maintaining local validator test suites ## MVP ### 1. Lifecycle manifest Developers declare expected transitions in a small TOML file: ```toml [[accounts]] name = "Vault" create = ["initialize"] mutate = ["deposit", "withdraw"] resize = ["migrate"] close = ["close_vault"] authority = "owner" ``` ### 2. Test instrumentation A helper records account snapshots before and after each test instruction: - Owner program - Lamport balance - Data length - Selected authority fields - Discriminator or type marker - Writable/signing context - Existence before and after execution ### 3. Rule engine Initial checks: - Creation must reject an already initialized account - Mutations must reject wrong ownership or unexpected type - Close must remove or invalidate the account as declared - Resize must preserve specified fields - Authority changes must be explicit and test-covered - Repeated execution must be classified as safe, rejected, or idempotent ### 4. Report Example: ```text FAIL Vault.close_vault - Account was closed, but dependent Position records remain active - Expected authority transition test: owner -> none - Re-run with: lifecycle check --case close_vault ``` Reports should support terminal text and JSON for CI. ## Proposed commands ```bash lifecycle init lifecycle check lifecycle check --case close_vault lifecycle report --format json ``` ## Acceptance criteria - Runs entirely against a local validator or test harness - Produces deterministic results from the same test inputs - Never sends transactions to a network - Distinguishes confirmed failures from missing coverage - Allows teams to mark intentional exceptions with a reason - Exits nonzero when a declared invariant fails ## Non-goals for MVP - Proving economic correctness - Replacing formal audits - Inferring every invariant automatically - Supporting every framework on day one ## Distribution Open-source CLI with a paid optional CI dashboard later. The first useful release should be installable by one command and demonstrate value on a small fixture program.

# Self-Directed Draft: Solana IDL Drift Guard ## Product specification A CI tool that detects potentially breaking differences between a committed Solana program interface and the interface expected by client code. ### User promise **“Catch client–program interface drift before release.”** ### Problem Solana applications can break when instruction names, account requirements, argument types, error codes, or return data change without coordinated client updates. Code review may miss these changes when generated artifacts are committed separately from program source. ### Target users - Solana program teams using Anchor or another IDL-producing framework - Frontend and SDK maintainers - Teams reviewing upgrade or release pull requests ### Core workflow ```text idl-drift check \ --base ./idl/previous.json \ --head ./idl/current.json \ --policy ./idl-drift.yml ``` The tool emits: 1. A human-readable change report 2. A machine-readable JSON report 3. A CI exit code based on configured severity ### Change categories | Change | Default severity | |---|---:| | Removed instruction | breaking | | Renamed instruction | breaking | | Removed account from an instruction | breaking | | Added required signer | breaking | | Changed argument type | breaking | | Changed account mutability | warning | | Changed account address constraint | warning | | Added instruction | compatible | | Added optional account | compatible | | Added error code or message | compatible | The policy file can override severity and allow intentional changes by name or version. ### Example report ```text BREAKING swap argument[1] amount: u64 -> u128 BREAKING withdraw account authority: signer requirement added WARNING deposit account vault: writable flag changed Result: 2 breaking, 1 warning Exit code: 1 ``` ### Minimal policy format ```yaml breaking_on: - removed_instruction - changed_argument_type - added_required_signer allow: - instruction: initialize_v2 reason: "New versioned entrypoint" ``` ### MVP scope - Compare JSON IDLs - Normalize ordering before comparison - Detect instruction, account, argument, signer, mutability, type, and error changes - Produce terminal and JSON output - Provide GitHub Actions-compatible exit codes - Include fixture-based tests for each change category ### Explicit non-goals - Proving program behavior is safe - Verifying deployed bytecode - Inferring compatibility from arbitrary client source - Automatically approving upgrades ### Suggested implementation - Language: Rust or TypeScript - Comparison engine: normalized intermediate representation - CLI commands: `check`, `explain`, `init-policy` - CI integration: standard output plus exit status - Determinism: stable sorting and canonical JSON serialization ### Acceptance criteria - Identical IDLs produce no findings. - Reordered JSON fields do not create findings. - Every detected change includes a path, old value, new value, and severity. - A policy override is visible in the report. - The tool exits nonzero when configured breaking changes are present. - Fixtures cover additions, removals, type changes, signer changes, mutability changes, and renamed items.

# Self-Directed Draft: Solana RPC Resilience Tester ## Product specification A local CLI that tests whether a Solana application behaves safely when RPC requests are slow, rate-limited, inconsistent, or unavailable. ### User promise **“Find fragile RPC behavior before users do.”** ### Problem Applications may rely on one endpoint, retry writes unsafely, accept stale reads, or display ambiguous transaction states. These weaknesses are difficult to reproduce during normal development. ### Core workflow ```bash rpc-resilience run \ --command "npm run dev" \ --rpc-port 8899 \ --scenario scenarios/degraded.yaml ``` The application points to the CLI’s local proxy. The proxy forwards requests to a configured RPC endpoint while applying controlled faults. ### Scenario format ```yaml name: degraded-checkout rules: - method: getLatestBlockhash delayMs: 2500 probability: 0.5 - method: sendTransaction error: code: 429 message: rate limited attempts: [1, 2] - method: getSignatureStatuses returnNull: true durationMs: 10000 ``` ### MVP features - JSON-RPC forwarding proxy - Per-method latency and error injection - HTTP 429 and timeout simulation - Temporary null or stale read responses - Request timeline with redacted parameters - Machine-readable JSON results - Markdown readiness report - Deterministic scenarios using a supplied seed ### Report checks - Does the interface expose loading, retrying, failed, and unknown states? - Are transaction submissions retried automatically? - Can a delayed confirmation cause duplicate user actions? - Does the app recover after endpoint availability returns? - Are read failures distinguished from confirmed onchain failure? - Are sensitive request fields excluded from logs? ### Safety defaults - Bind only to localhost. - Never modify signed transaction bytes. - Disable live transaction forwarding unless explicitly enabled. - Redact authorization headers and configurable JSON fields. - Display a persistent warning when fault injection is active. ### Suggested commands ```bash rpc-resilience init rpc-resilience proxy --upstream "$RPC_URL" rpc-resilience run --scenario degraded.yaml --seed 42 rpc-resilience report --format markdown ``` ### Acceptance criteria 1. A developer can initialize and run a scenario in under five commands. 2. The same seed produces the same fault sequence. 3. Reports identify each affected RPC method and observed recovery time. 4. Secrets are absent from default logs and reports. 5. Interrupted tests restore normal proxy behavior without manual cleanup. ### Initial distribution copy > Your app works when RPC works. What happens when confirmation stalls, reads return null, or rate limits arrive mid-flow? > > **RPC Resilience Tester** is a local fault-injection proxy for rehearsing those failures with repeatable scenarios—before shipping.

# Self-Directed Draft: Solana Transaction Permission Manifest ## Product specification A developer tool that converts a Solana instruction definition into a reviewable manifest of accounts, signer requirements, mutability, PDA seeds, and expected program calls. ### User promise **“Review what an instruction can touch before integrating it.”** ### Problem Transaction code often hides important permission details inside account metas, wrappers, and generated clients. Reviewers need a compact artifact they can inspect alongside a pull request. ### Target users - Solana program teams - Wallet and transaction-builder developers - Security reviewers - Teams maintaining generated clients or SDKs ## MVP Input: - A local instruction schema or IDL - Optional account metadata - Optional expected instruction fixtures Output: ```text Instruction: withdraw Accounts: user signer=true writable=false vault signer=false writable=true destination signer=false writable=true config signer=false writable=false Derived addresses: vault = PDA(seeds: ["vault", config]) External calls: none declared Review flags: - destination is writable - vault and destination may alias - no fixture verifies rejection of an unauthorized signer ``` ## Core commands ```bash perm-manifest init perm-manifest inspect instruction.json perm-manifest compare old.json new.json perm-manifest check fixtures/ ``` `compare` should highlight: - Newly required signers - Accounts changing from read-only to writable - Added or removed accounts - Changed PDA seed descriptions - Newly introduced external program calls ## Design principles - Treat unknown metadata as **unknown**, not safe. - Never infer security from account names alone. - Keep output deterministic for pull-request diffs. - Support JSON for automation and Markdown for human review. - Redact private keys and transaction payloads from generated artifacts. ## MVP acceptance criteria - Produces stable JSON and Markdown from the same input. - Fails clearly when required account metadata is missing. - Detects permission changes between two manifests. - Supports fixture checks for signer and writable-account expectations. - Includes an exit code suitable for CI. - Documents limitations around dynamic CPIs and wrapper instructions. ## Suggested repository layout ```text perm-manifest/ src/ fixtures/ valid/ invalid/ examples/ README.md schema/ manifest.schema.json ``` ## First usable artifact Ship a schema, one parser, one Markdown renderer, and five fixtures covering: 1. Read-only instruction 2. Multiple signers 3. PDA-derived account 4. Writable-account escalation 5. Undeclared external call ### Positioning copy **Permission clarity for Solana instructions.** Generate a compact manifest, review changes as diffs, and make account permissions explicit before code reaches users.

# Self-Directed Draft: Solana Incident Handoff Kit ## Product specification A small CLI that captures a Solana application’s debugging context into a sanitized Markdown report teams can share internally. ### User promise **“Turn a failed transaction into a useful incident report in one command.”** ### Problem Bug reports often omit the cluster, transaction signature, program logs, wallet state, build version, or reproduction steps. Engineers then spend time requesting context instead of investigating. ### Command ```bash solana-handoff capture \ --signature <TX_SIGNATURE> \ --cluster <RPC_URL> \ --app-version <VERSION> \ --output incident.md ``` ### Generated report ```md # Transaction Incident - Captured at: - App version: - Cluster: - Transaction signature: - Status: - Slot: ## Error [normalized error] ## Program Logs [sanitized logs] ## Programs Invoked - [program address] ## Reproduction 1. 2. 3. ## Expected Result ## Actual Result ## Reporter Notes ## Redactions - RPC credentials removed - Local file paths removed - Configured wallet addresses masked ``` ### MVP requirements - Fetch transaction status, metadata, logs, and invoked program addresses. - Accept manual context through interactive prompts. - Redact RPC query strings and user-configured address patterns. - Never collect seed phrases, private keys, or signed transaction payloads. - Work without telemetry by default. - Export deterministic Markdown and JSON. - Return a nonzero exit code when capture fails. - Include the tool version and capture timestamp. ### Configuration ```json { "maskAddresses": true, "includeBalances": false, "includeInstructionData": false, "redactPatterns": ["API_KEY=.*"], "telemetry": false } ``` ### Acceptance criteria 1. A developer can generate a report from a transaction signature. 2. Reports contain enough structured context to compare two failures. 3. Secrets embedded in RPC URLs are absent from output. 4. Missing or unavailable transaction data is clearly labeled. 5. The CLI displays a preview and requires confirmation before writing sensitive fields. ### Initial distribution Publish as an npm package with a copy-paste issue template: > **Need help debugging?** Attach a report generated with `solana-handoff capture`. Review the redaction preview before sharing.

# Self-Directed Draft: Solana Integration Release Gate ## Product specification A CLI and CI action that checks a Solana application’s critical transaction flows before release. ### User promise **“Catch broken instructions, stale addresses, and unsafe configuration before users do.”** ### Target users - Solana application teams - Program developers - Agencies maintaining multiple deployments ## Core workflow Teams define important flows in `solana-gate.yml`: ```yaml cluster: devnet rpc_url_env: SOLANA_RPC_URL checks: - name: create-order fixture: fixtures/create-order.json expected: simulation_success: true max_compute_units: 180000 required_logs: - "Program log: order created" - name: cancel-order fixture: fixtures/cancel-order.json expected: simulation_success: true forbidden_writable_accounts: - treasury ``` Run locally or in CI: ```bash npx solana-release-gate check ``` Example output: ```text PASS create-order Simulation succeeded Compute: 142,810 / 180,000 Required log found FAIL cancel-order Unexpected writable account: treasury Release gate failed: 1 of 2 checks failed ``` ## MVP checks 1. RPC connectivity and configured cluster 2. Program IDs matching an approved manifest 3. Transaction simulation success 4. Compute-unit ceiling 5. Required and forbidden log patterns 6. Expected signer and writable-account sets 7. Account ownership assertions 8. Machine-readable JSON report 9. Nonzero exit code on failure ## Fixture format Fixtures contain serialized transaction inputs, test wallet public keys, and expected account conditions. Secret keys must not be stored in fixtures. Signing-dependent tests should use an explicitly configured disposable test wallet. ## Commands ```bash solana-release-gate init solana-release-gate check solana-release-gate check --only create-order solana-release-gate inspect fixtures/create-order.json ``` ## Acceptance criteria - One command works locally and in CI. - Failed assertions identify the exact flow and condition. - Logs redact configured RPC credentials. - Results are deterministic when fixtures and referenced account state are unchanged. - Documentation includes a minimal example application. - No production transaction is submitted by default. ## Business model - Open-source CLI with core checks - Paid hosted reports, history, and team notifications - Paid setup package for converting an application’s key flows into fixtures ## Positioning copy **Ship Solana transaction flows with a release gate.** Define the behavior your application expects, simulate critical transactions in CI, and block releases when program IDs, account permissions, logs, or compute usage drift.

# Self-Directed Draft: Solana Transaction Intent Preview ## Product specification A lightweight UI component that explains what a Solana transaction is intended to do before the user approves it. ### User promise **“Understand the action before signing.”** ### Problem Transaction prompts can feel opaque, especially when several instructions, accounts, or token movements are involved. Users need a plain-language summary without exposing secret keys or requiring them to interpret raw transaction data. ## Core experience Before wallet approval, show an **Intent Preview** containing: - **Action:** e.g. “Swap,” “Send,” “Stake,” or “Create account” - **Assets involved:** token symbols and displayed amounts - **Destination:** shortened address plus optional verified app label - **Estimated network fee:** clearly marked as an estimate - **Account changes:** accounts created, closed, or modified - **Warnings:** unusual permissions, missing metadata, or unsupported instructions - **Expandable details:** program IDs, instruction count, and raw account list The component must distinguish between: - **Decoded information** - **App-provided labels** - **Unresolved or unknown data** ## Suggested interface copy **Review transaction** > You are about to approve an action requested by **[app name]**. **This will:** - Send **[amount] [token]** to **[short address]** - Use approximately **[fee estimate]** in network fees - [Create / modify / close] **[account description]** **Before continuing:** - Confirm the destination address. - Check that the token and amount are expected. - Do not approve if the request differs from your intended action. Buttons: - **Approve in wallet** - **Cancel** - **Show technical details** ## Safety and privacy requirements - Never request or display private keys, seed phrases, or wallet secrets. - Do not imply that an address is trusted unless the app has an explicit verification source. - Label estimates and unresolved fields. - Fail closed when decoding is incomplete: show “Unknown instruction” rather than guessing. - Keep the raw transaction available for technical support. ## Minimal API shape ```ts type IntentPreview = { title: string; actions: Array<{ verb: string; asset?: string; amount?: string; destination?: string; }>; feeEstimate?: string; accountChanges: string[]; warnings: string[]; unresolvedInstructions: number; rawDetailsUrl?: string; }; ``` ## Acceptance criteria - A user can identify the primary action within five seconds. - Every displayed amount is traceable to decoded transaction data. - Unknown instructions are visibly marked. - The component renders safely when metadata is missing. - No secret material enters logs, analytics, or error reports. - Teams can customize labels without changing the underlying transaction data.

# Self-Directed Draft: Solana Wallet Debug Bundle ## Product specification A small SDK and UI component that lets users generate a privacy-conscious diagnostic bundle when a Solana app transaction fails. Teams receive structured evidence instead of vague “wallet didn’t work” reports. ### User promise **“Create a useful support report without exposing private keys or secret recovery phrases.”** ## Trigger Display **Create debug report** after: - Wallet connection failure - Transaction simulation failure - Signature rejection - Confirmation timeout - Program error - Unexpected balance or account-state response ## Bundle schema ```ts type SolanaDebugBundle = { bundleVersion: "1.0"; createdAt: string; app: { name: string; version?: string; route?: string; }; environment: { cluster: "mainnet-beta" | "devnet" | "testnet" | "localnet" | "custom"; walletName?: string; browserFamily?: string; deviceType?: "desktop" | "mobile" | "unknown"; }; transaction?: { signature?: string; recentBlockhash?: string; instructionProgramIds?: string[]; simulationLogs?: string[]; errorCode?: string | number; errorMessage?: string; }; rpc: { endpointLabel?: string; latencyMs?: number; slot?: number; responseError?: string; }; timeline: Array<{ timestamp: string; event: string; detail?: string; }>; }; ``` ## Privacy rules Never collect: - Seed phrases or private keys - Raw signing payloads by default - Authentication tokens - Cookies or local-storage contents - Full RPC URLs containing credentials - Unrelated wallet addresses or balances Public keys, signatures, logs, and routes must be shown in a preview before export. Users can remove individual fields. ## Interface copy **Transaction failed** You can create a diagnostic report to help support identify the problem. Review everything before copying or downloading it. Buttons: - **Preview report** - **Copy JSON** - **Download JSON** - **Start over** Warning: > This report should never contain a recovery phrase or private key. Support will never ask for either. ## Implementation API ```ts const debuggerClient = createSolanaDebugger({ appName: "Example App", appVersion: "1.4.0", cluster: "mainnet-beta", redactRpcCredentials: true, captureSimulationLogs: true, maxTimelineEvents: 50 }); debuggerClient.record("wallet_connected", { walletName: "User-selected wallet" }); debuggerClient.recordError(error); const bundle = debuggerClient.export(); ``` ## Acceptance criteria - A report can be generated in two clicks after failure. - Exported JSON validates against a versioned schema. - RPC credentials are redacted automatically. - Users can preview and delete fields before export. - The component makes no network request unless the host app explicitly enables submission. - The bundle captures enough context to distinguish wallet rejection, RPC failure, simulation error, and confirmation timeout. - Automated tests verify that common secret formats never appear in exports. ## Initial scope Ship as a framework-neutral TypeScript package plus a React panel. Keep ticket-system integrations and automatic uploads out of the first release.

# Self-Directed Draft: Solana App Release Readiness Checklist A reusable pre-release checklist for teams shipping a Solana wallet flow, token feature, program interaction, or frontend update. ## Release goal Ship a change that is understandable to users, observable by the team, and safe to roll back or disable. ## 1. User flow - [ ] The primary user action is stated in one sentence. - [ ] Wallet connection, network selection, and account state are clearly shown. - [ ] Every signing step explains what the user is being asked to approve. - [ ] Loading, success, rejection, timeout, and failure states have designed UI. - [ ] Users can retry without accidentally duplicating an action. - [ ] Mobile layout and wallet handoff behavior are tested. - [ ] Unsupported wallets or account types receive a useful message. ## 2. Transaction behavior - [ ] The app distinguishes unsigned, submitted, confirmed, and failed states. - [ ] Transaction errors are converted into plain-language next steps. - [ ] The interface does not display success before the intended confirmation condition. - [ ] Fees, required accounts, and expected asset changes are presented where relevant. - [ ] Duplicate clicks and repeated submissions are handled safely. - [ ] A transaction identifier can be copied for support investigation. - [ ] The team has tested insufficient balance, rejected signatures, stale state, and expired transactions. ## 3. Program and data safety - [ ] Inputs are validated on both client and program/API boundaries. - [ ] Authorization checks cover the intended signer and account relationships. - [ ] Untrusted account data is not treated as verified business state. - [ ] Upgrade, pause, admin, and emergency controls are documented internally. - [ ] Sensitive keys, seed phrases, and private configuration never enter logs. - [ ] Any irreversible action has an explicit confirmation step. ## 4. Observability - [ ] Each critical flow has a correlation or attempt identifier. - [ ] Logs capture useful error context without exposing secrets. - [ ] The team can separate wallet rejection, client error, RPC error, program error, and confirmation timeout. - [ ] Alerts or review thresholds exist for unusual failure rates. - [ ] A support runbook explains what information to request from a user. - [ ] The release has a defined owner and rollback/disable procedure. ## 5. Documentation and support - [ ] Setup instructions work from a clean environment. - [ ] Required configuration variables are listed with safe example values. - [ ] Known limitations and unsupported cases are explicit. - [ ] User-facing error messages avoid unexplained codes where possible. - [ ] A short FAQ covers connection, signing, pending, and failed states. - [ ] Changelog notes include behavior changes that affect users or integrators. ## 6. Ship gate Do not release until: 1. A new user can complete the main flow without internal guidance. 2. A rejected signature produces a clear recovery path. 3. A failed or pending transaction cannot be mistaken for success. 4. The team can diagnose a reported failure from available context. 5. One person who did not implement the change has completed the checklist. ## Suggested handoff artifact ```text Release: __________________ Owner: ___________________ Date: ____________________ Main user action: ________________________________________ Known limitations: ________________________________________ Rollback or disable method: ________________________________________ Support contact/process: ________________________________________ Final reviewer: ________________________ Decision: [ ] Ship [ ] Hold Reason: __________________________________ ```

# Self-Directed Draft: Solana Transaction Safety Preview ## Product brief A reusable pre-signing panel that translates a proposed Solana transaction into plain language. It helps users understand expected asset changes, permissions, fees, and uncertainty before approving a wallet request. ## User promise **“Know what this transaction may change before you sign.”** ## Core experience The component receives a serialized transaction and RPC connection, simulates it when possible, then displays: - Assets likely sent and received - SOL balance change, including estimated fees - Programs the transaction invokes - New token approvals or authority changes - Accounts created or closed - Simulation warnings and errors - Unknown effects that could not be decoded The interface must distinguish between: - **Expected:** successfully decoded or simulated - **Warning:** unusual authority, balance, or account changes - **Unknown:** incomplete decoding or failed simulation ## Suggested API ```ts type SafetyPreviewProps = { transaction: string; rpcUrl: string; expectedWallet: string; knownPrograms?: Record<string, string>; onResult?: (result: PreviewResult) => void; }; ``` ```ts type PreviewResult = { status: "clear" | "warning" | "unknown" | "failed"; summary: string; balanceChanges: BalanceChange[]; invokedPrograms: ProgramReference[]; authorityChanges: AuthorityChange[]; warnings: Warning[]; simulationError?: string; }; ``` ## Safety rules 1. Never label a transaction “safe.” 2. Never treat successful simulation as a guarantee. 3. Show unknown programs by address rather than hiding them. 4. Warn when the signing wallet differs from the expected wallet. 5. Keep raw transaction data available behind an advanced-details toggle. 6. Do not transmit transaction contents to analytics services by default. ## MVP screens 1. **Loading:** “Inspecting transaction…” 2. **Clear summary:** Human-readable effects with expandable details. 3. **Warning:** Highlight sensitive changes before the signing action. 4. **Unknown:** Explain which effects could not be interpreted. 5. **Failure:** Show a sanitized simulation error and retry option. ## Acceptance criteria - Produces a preview without requesting a signature. - Handles versioned and unsupported transactions without crashing. - Displays every invoked program, including undecoded programs. - Separates estimated fees from asset transfers. - Provides accessible warning text without relying only on color. - Returns a structured result usable by custom wallet or dApp interfaces. - Includes fixtures for transfer, swap-like, authority-change, failed-simulation, and unknown-program scenarios. ## Monetization path Offer the core package as open source, with paid hosted decoding rules, team-maintained program labels, custom policy checks, and support.

# Self-Directed Draft: Solana Network Health Status Card ## Product concept A small embeddable status component that explains whether a Solana application’s transaction problem is likely local, application-specific, or network-related—without exposing sensitive wallet data. The component gives users a plain-language next step instead of leaving them at a generic “transaction failed” screen. ## User promise “Know what to try next when a transaction does not go through.” ## Intended users - Solana dApp teams - Wallet-connected web applications - Support and operations teams - Developers building transaction-heavy interfaces ## MVP scope ### 1. Status inputs The host application supplies: - Current RPC request result - Error category - Whether a wallet signature was requested - Whether a transaction signature was returned - Optional recent retry count - Optional application incident message No private keys, seed phrases, or raw wallet balances are required. ### 2. User-facing states | State | Suggested message | Action | |---|---|---| | Wallet rejected | “The wallet request was canceled.” | Try again when ready | | Blockhash expired | “The transaction took too long to submit.” | Refresh and retry | | Simulation failed | “The application rejected this transaction before signing.” | Review the highlighted details | | RPC unavailable | “The connection is having trouble responding.” | Wait briefly or switch connection | | Submitted, confirmation pending | “Your transaction was sent; confirmation is pending.” | Check status before retrying | | Unknown | “We could not classify this error.” | Copy diagnostic summary | ### 3. Copy diagnostic button Generates a sanitized support summary: ```text Transaction support summary Time: [local timestamp] Stage: [wallet / simulation / submission / confirmation] Category: [error category] Retry count: [number] Transaction signature: [included only if available] Application version: [optional] ``` The user can review the summary before copying it. ## Suggested interface A compact card with: - Status icon and short headline - One-sentence explanation - Primary next action - “Copy support summary” secondary action - Expandable “Technical details” section - Optional link or button supplied by the host app Avoid claiming that a transaction is finalized unless the host application has an explicit confirmation result. ## Minimal integration shape ```ts type TransactionStatusCardProps = { stage: "wallet" | "simulation" | "submission" | "confirmation"; category: string; message?: string; signature?: string; retryCount?: number; appVersion?: string; onRetry?: () => void; }; ``` ## Acceptance criteria - A user can understand the current state without reading a stack trace. - Every state offers a clear next action. - Diagnostic output excludes secret material by design. - A pending confirmation state does not imply success. - Teams can provide custom support instructions without modifying the component. - The component remains useful when no transaction signature exists. ## Future extensions - Localization-ready message catalog - Copyable JSON export for support teams - Host-configured severity levels - Optional telemetry controlled by explicit user consent - Adapter examples for common Solana wallet and transaction libraries

# Self-Directed Draft: Solana Wallet Issue Reproduction Kit ## Product concept A lightweight form and export tool that helps users turn vague wallet or dApp complaints into actionable bug reports. Instead of “my transaction failed,” a team receives a structured reproduction packet containing the relevant context, user steps, and optional sanitized technical details. ## User promise “Give your team the information needed to reproduce wallet issues without a long support thread.” ## Intended users - Solana dApp support teams - Wallet and SDK integrators - Protocol teams handling failed actions - Community moderators ## MVP workflow 1. Team creates a branded issue form. 2. User selects an issue category: - Transaction failed - Balance or token display problem - Connection issue - Signing prompt confusion - Unexpected application behavior 3. Form asks only relevant follow-up questions. 4. User provides: - What they attempted - Exact sequence of actions - Device and browser - Wallet name and app version, if known - Approximate time of occurrence - Public address, only if they consent - Transaction or error identifier, if available - Screenshot or screen recording, optionally 5. Tool generates: - Human-readable support ticket - Copyable Markdown report - JSON export for issue trackers ## Report template ```text Title: Category: Severity: User goal: Expected result: Actual result: Steps to reproduce: 1. 2. 3. Environment: - Device: - OS: - Browser: - Wallet: - App version: Identifiers voluntarily provided: - Public address: - Transaction/signature: - Error text: Attachments: User consent: ``` ## Privacy guardrails - Clearly label public addresses and transaction identifiers as optional. - Warn users never to submit seed phrases, private keys, recovery phrases, or secret tokens. - Provide a “remove sensitive details” review step before submission. - Allow anonymous reports. - Make retention and deletion settings visible to team administrators. ## Team features - Custom categories and questions - Duplicate detection by matching error text and identifiers - Status labels: New, Needs info, Reproducible, Escalated, Resolved - Internal notes separated from user-visible replies - Export to CSV, Markdown, or webhook payload - Basic analytics: issue category counts and median time to triage ## Acceptance criteria - A user can submit a report in under three minutes. - A support agent can understand the reproduction attempt without requesting the initial details again. - Secret-value warnings appear before submission. - Every report includes a clear consent record for submitted optional data. - The exported report remains readable without access to the product. ## Possible pricing model - Free tier for one form and limited monthly submissions - Paid tier for multiple forms, exports, retention controls, and team roles - Self-hosted option for teams requiring internal data handling

# Self-Directed Draft: Solana Transaction Readiness Checklist ## Product concept A reusable pre-release checklist that helps Solana teams verify a transaction flow before sharing it with users, integrators, or support teams. ## User promise “Catch confusing transaction failures before users do.” ## Intended users - Solana dApp teams - Wallet and SDK integrators - Protocol teams preparing a new instruction - Developer advocates writing integration guides ## Checklist ### 1. Transaction construction - [ ] Instruction accounts are listed in the expected order. - [ ] Writable and signer requirements are documented. - [ ] Required program IDs and address derivation inputs are recorded. - [ ] Default values and optional accounts are explicit. - [ ] The client rejects obviously incomplete inputs before submission. ### 2. Environment control - [ ] The target cluster is clearly labeled. - [ ] Program IDs are configurable rather than hard-coded across the client. - [ ] Test keys, URLs, and sample addresses are visibly non-production. - [ ] The team has recorded the program/client version used for testing. ### 3. Simulation and confirmation - [ ] The transaction is simulated before submission where appropriate. - [ ] Simulation errors are surfaced in readable language. - [ ] Blockhash expiry is handled with a retry or recovery path. - [ ] Confirmation status is shown separately from wallet approval. - [ ] The UI does not imply success before confirmation is received. ### 4. Failure messaging For every expected failure, document: - Trigger - Raw error or code - User-facing explanation - Recommended next action - Whether retrying is safe Example: > **Insufficient balance** > This wallet does not have enough of the required asset to complete the transaction. Add funds, then try again. ### 5. Observability - [ ] A support-safe transaction identifier is displayed after submission. - [ ] Client logs include cluster, instruction name, and error category. - [ ] Sensitive key material and private user data are excluded from logs. - [ ] Failed transactions can be correlated with a release or client version. ## Minimal acceptance test A transaction flow is ready for release when a tester can: 1. Complete the happy path. 2. Trigger at least three expected failures. 3. Understand each failure without reading developer logs. 4. Retry safely after a recoverable failure. 5. Provide support with enough context to reproduce the issue. ## Suggested deliverable format Create one Markdown file per transaction flow: ```md # Transaction: <name> Cluster: Program/client version: Required accounts: Expected success state: ## Known failures | Trigger | User message | Retry safe? | Recovery | |---|---|---|---| ## Test evidence - Happy path: - Failure cases: - Confirmation behavior: - Support identifier: ``` ## MVP packaging Offer this as a downloadable template bundle containing: - The checklist - A transaction-flow Markdown template - A failure-message worksheet - A one-page release sign-off form

# Self-Directed Draft: Solana Release Diff Brief ## Product concept A small tool that turns two versions of a Solana program or SDK into a clear release brief: what changed, who is affected, and what must be updated before rollout. ## User promise “Compare two releases and get a migration-ready brief in minutes.” ## Target users - Solana program teams shipping upgrades - SDK maintainers - Integrators maintaining clients, scripts, or frontends - Reviewers who need a focused change summary ## Inputs - Previous and current IDL, when available - Previous and current generated client/API surface - Manually supplied changelog notes - Optional configuration: - Release name - Target cluster - Upgrade window - Deprecation policy ## Output ### 1. Executive summary - Release title - One-sentence purpose - Affected components - Risk level: `Low`, `Medium`, or `High` - Recommended rollout action ### 2. Structured change list Each change receives: - Category: `Added`, `Changed`, `Removed`, or `Deprecated` - Surface: instruction, account, argument, error, event, SDK method, config - Compatibility: `Compatible`, `Requires migration`, or `Needs review` - Evidence: source file, diff section, or author note - Owner - Status ### 3. Migration checklist ```md - [ ] Update client dependency - [ ] Regenerate bindings - [ ] Review changed instruction arguments - [ ] Review account constraints and permissions - [ ] Update error handling - [ ] Update frontend transaction builders - [ ] Run integration tests against the target cluster - [ ] Record rollback or pause procedure ``` ### 4. Integrator notice A copy-ready message: ```md ## Release: <name> ### What changed <2–4 plain-language bullets> ### Action required <Who must update what, and by when> ### Compatibility <Compatible / migration required / review required> ### Validation <Commands, test cases, or confirmation steps> ### Questions <Contact or issue reference> ``` ## MVP workflow 1. Upload or paste two version snapshots. 2. Normalize names and compare public surfaces. 3. Let the author confirm or correct detected changes. 4. Assign risk and owners. 5. Export Markdown and JSON. 6. Save an immutable release brief with version and timestamp. ## Suggested JSON shape ```json { "release": "v0.0.0", "risk": "medium", "changes": [ { "type": "changed", "surface": "instruction", "name": "example", "compatibility": "requires_migration", "owner": "team" } ], "checklist": [], "approved": false } ``` ## Acceptance criteria - A reviewer can identify breaking changes without reading the full diff. - Every flagged change links to evidence or an author note. - The export contains both human-readable Markdown and machine-readable JSON. - The tool never labels an uncertain change as safe without reviewer confirmation. - A release cannot be marked approved while unresolved high-risk items remain. ## Positioning A release-notes generator is passive. This is a migration-control artifact: one concise brief for engineers, reviewers, and integrators before a Solana release moves forward.

# Self-Directed Draft: Solana Support Triage Kit ## Purpose A lightweight intake and triage system for Solana teams that turns vague support messages into reproducible technical cases, clear ownership, and user-facing updates. ## Product promise “Give us the transaction, expected result, and observed result. We’ll turn it into an actionable case.” ## Intake form Required fields: - **Contact handle:** - **Issue category:** transaction failure / account state / wallet UX / SDK or RPC / indexing / other - **Cluster:** mainnet-beta / devnet / testnet / localnet / unknown - **Transaction signature:** optional, but strongly requested - **Program ID or app name:** - **Approximate time:** - **Expected result:** - **Observed result:** - **Exact error text:** - **Steps to reproduce:** - **Amount or asset involved:** never request seed phrases or private keys - **Attachments:** screenshots, logs, serialized instruction data ## Triage states 1. **New** — intake received; no assessment yet 2. **Needs details** — missing signature, cluster, logs, or reproduction steps 3. **Reproducible** — issue can be recreated or confirmed from supplied evidence 4. **Root cause identified** — likely cause documented with confidence level 5. **Workaround ready** — temporary mitigation is available 6. **Fix pending** — owner has an implementation task 7. **Resolved** — resolution communicated and case closed 8. **Closed: insufficient evidence** — no further progress without new information ## Case record ```text Case ID: Opened: Reporter: Owner: Severity: low / medium / high / critical State: Cluster: Program or app: Transaction signature: Observed error: Reproduction: Evidence reviewed: Hypothesis: Confidence: low / medium / high User impact: Workaround: Permanent fix: Next update due: Resolution summary: ``` ## Severity guide - **Critical:** funds may be lost, inaccessible, or repeatedly misdirected - **High:** a core flow is blocked for multiple users or a production integration - **Medium:** workaround exists; limited scope or intermittent impact - **Low:** documentation, cosmetic, or isolated usability issue Severity describes user impact, not how difficult the bug is to fix. ## First-response template > Thanks for reporting this. We’ve opened case **[ID]**. > To investigate, please provide **[missing item]** and confirm the cluster (**[cluster]**). > Do not send seed phrases, private keys, or wallet recovery material. > Current status: **[state]**. We’ll update the case when we confirm the cause or have a workaround. ## Resolution template > Case **[ID]** is resolved. > **Cause:** [plain-language explanation] > **Action taken:** [fix, configuration change, or documentation update] > **User action:** [required step, or “none”] > **Scope:** [affected cluster/version/flow] > **Verification:** [how the result was confirmed] ## Acceptance criteria - Every case has an owner, state, severity, and next action. - Sensitive wallet credentials are explicitly prohibited. - A responder can request missing evidence using one reusable template. - Closed cases retain the cause, resolution, and affected scope. - Repeated cases can be grouped under one known issue. - The system can be operated from a spreadsheet, issue tracker, or simple database without custom infrastructure.

# Self-Directed Draft: Solana Integration Contract Card ## Purpose A compact, versioned document that lets an integrator understand how to call a Solana program safely without reading the entire codebase. ## Template ### 1. Identity - **Program name:** - **Program ID:** - **Contract version:** - **Maintainer:** - **Last reviewed:** - **Supported clusters:** ### 2. Instruction: `[name]` **Purpose:** One sentence describing what the instruction does. **Accounts** | Name | Mutability | Signer | PDA/derived rule | Ownership expectation | |---|---:|---:|---|---| | `authority` | No | Yes | None | Wallet | | `state` | Yes | No | `[seeds and bump source]` | This program | | `system_program` | No | No | Fixed address | System program | **Arguments** | Name | Type | Required | Constraints | |---|---|---:|---| | `amount` | `u64` | Yes | Must be greater than zero | | `memo` | `bytes` | No | Maximum length: `[n]` | **Effects** - Accounts created, closed, or resized: - Lamports moved: - Tokens moved: - State fields changed: - Events/logs emitted: **Failure cases** | Condition | Error name/code | Integrator action | |---|---|---| | Missing signer | `[error]` | Request signature from authority | | Invalid PDA | `[error]` | Derive address using the stated seeds | | Insufficient balance | `[error]` | Check funds before submission | ### 3. Transaction requirements - Recent blockhash required: Yes / No - Required signers: - Compute budget guidance: - Priority-fee guidance: - Maximum expected account list: - Safe retry behavior: - Idempotency rule: - Confirmation commitment expected: ### 4. Client example ```ts const ix = await program.methods .instructionName(amount, memo) .accounts({ authority, state, systemProgram, }) .instruction(); const tx = new Transaction().add(ix); ``` Replace the example with the client framework actually supported by the project. Do not publish placeholder account names or constraints. ### 5. Verification checklist Before release, the maintainer confirms: - [ ] Every account is classified as signer and/or writable. - [ ] PDA seeds and bump behavior are documented. - [ ] Ownership and executable-account expectations are explicit. - [ ] Argument limits match implementation. - [ ] Error codes map to actionable remediation. - [ ] Effects describe lamport, token, and state changes. - [ ] Retry and idempotency behavior has a tested answer. - [ ] Example code was tested against the stated program version. - [ ] A version change is recorded when the contract changes. ## Definition of done An engineer unfamiliar with the program can construct a valid instruction, identify required signers, predict principal failure modes, and determine whether retrying is safe using only this card plus the project’s standard client setup.

# Self-Directed Draft: Solana Program Release Gate Checklist A reusable pre-release checklist for teams shipping a Solana program, client update, or migration. It is designed to catch operational gaps before users encounter them. ## 1. Scope and compatibility - [ ] Release purpose is written in one sentence. - [ ] Changed instructions, accounts, arguments, errors, and emitted data are listed. - [ ] Backward compatibility expectations are documented. - [ ] Any required client, IDL, SDK, or frontend changes are identified. - [ ] Migration steps exist for existing accounts and user state. - [ ] Rollback or pause behavior is defined. ## 2. Program validation - [ ] Unit tests cover the changed logic. - [ ] Tests cover invalid signers, missing accounts, wrong account ownership, and malformed input. - [ ] Tests cover boundary values and repeated execution. - [ ] Tests cover expected custom errors. - [ ] A clean environment can build the program from the documented commands. - [ ] The program identifier and deployment target are explicitly recorded. - [ ] Upgrade authority or immutability status is confirmed by the responsible operator. ## 3. Client validation - [ ] The client uses the intended program identifier. - [ ] Generated types or instruction builders are refreshed. - [ ] Account ordering and mutability flags are reviewed. - [ ] Signer requirements are reviewed. - [ ] Transaction simulation or preflight errors are shown in actionable form. - [ ] Users receive a clear message for rejected, expired, or already-completed actions. - [ ] Duplicate submission behavior is handled safely. ## 4. Data and migration safety - [ ] Every changed account layout has a versioning strategy. - [ ] Existing data is tested against the new reader. - [ ] Migration is idempotent or has an explicit recovery procedure. - [ ] Derived addresses and seed inputs are unchanged or intentionally migrated. - [ ] Rent, funding, and closing behavior are documented. - [ ] No destructive operation is reachable without an explicit authorization path. ## 5. Observability and support - [ ] Release identifier is recorded in the changelog. - [ ] Important instructions emit enough context for support diagnosis. - [ ] Expected transaction signatures, logs, and error codes are documented. - [ ] A support template requests network, wallet, action, timestamp, and signature when available. - [ ] Known limitations and recovery steps are published internally. - [ ] An owner is assigned for release-day questions. ## 6. Final approval Record the following before release: ```text Release: Program identifier: Target environment: Commit or build identifier: Migration required: yes / no Rollback or pause procedure: Program owner: Client owner: Approver: Release window: Open risks: ``` ### Stop conditions Do not release if: - the migration cannot be rehearsed or reversed; - client and program interfaces disagree; - account-layout changes lack a version strategy; - signer or authority behavior is not tested; - no person owns recovery from a failed rollout.

# Self-Directed Draft: Solana Transaction Repro Pack ## Product **Transaction Repro Pack** is a CLI tool that turns a failed Solana transaction into a shareable, deterministic debugging bundle. ## Problem Transaction failures are often reported as “it didn’t work,” with incomplete logs, missing account context, or an unclear signer setup. Engineers then spend time reconstructing the original request before they can diagnose it. ## Core workflow ```bash repro-pack capture <signature> --rpc $RPC_URL --out ./repro repro-pack inspect ./repro repro-pack redact ./repro --remove-keys repro-pack replay ./repro --rpc $DEVNET_RPC_URL ``` The bundle should contain: - Transaction signature and cluster label - Slot, block time, and confirmation status when available - Compiled message details - Account addresses and writable/signer flags - Program IDs invoked - Instruction data in encoded and decoded form when an IDL/parser is supplied - Simulation logs and returned error - Compute-unit usage when exposed - Environment metadata: CLI version, cluster, and capture timestamp - A human-readable `REPORT.md` - A machine-readable `repro.json` ## Privacy and safety defaults - Never export private keys, seed phrases, or raw signer material. - Replace known sensitive addresses with stable labels such as `SIGNER_1` and `TREASURY_1`. - Require an explicit `--include-addresses` flag to preserve public keys. - Mark replay as **simulation only** by default. - Refuse any command that could submit a transaction unless a future version adds an explicit, separate execution mode. ## MVP 1. Fetch a transaction by signature. 2. Fetch referenced account metadata. 3. Parse logs, instruction boundaries, and program errors. 4. Produce Markdown and JSON output. 5. Support redaction of addresses and arbitrary metadata fields. 6. Allow a local parser plugin for Anchor IDLs or custom instruction formats. 7. Add fixture-based tests for successful, program-error, and blockhash-expired transactions. ## Example report ```text Status: Failed Cluster: devnet Signature: redacted Primary program: PROGRAM_1 Error: Custom(6003) Compute units: 184,220 Likely investigation points: - Instruction 2 returned the custom error. - Account ACCOUNT_4 was writable but did not match the expected owner. - Replay requires replacing the original recent blockhash. ``` “Likely investigation points” must be explicitly labeled as heuristics, not verified explanations. ## Acceptance criteria - A captured bundle can be inspected without network access. - Redaction produces stable labels across all files. - No secret-looking fields are written to disk. - The report identifies the failing instruction when logs provide enough information. - Missing RPC data produces a warning rather than a fabricated value. - Every generated bundle includes the tool version and capture timestamp. ## Possible pricing shape - Free local CLI - Paid team features later: private bundle storage, shared annotations, CI links, and retention controls ## Positioning line **Give every failed Solana transaction a reproducible case file.**

# Self-Directed Draft: Solana IDL Drift Guard ## Product **IDL Drift Guard** is a CI check that detects mismatches between a Solana program’s deployed interface, checked-in IDL, generated client, and application usage. ## Problem A program can compile successfully while clients still use outdated instruction names, argument layouts, account requirements, or custom error codes. These failures often appear only during integration or runtime testing. ## MVP Deliverable A command-line tool: ```bash idl-drift check \ --idl target/idl/example.json \ --client src/generated \ --usage src ``` It exits nonzero when configured compatibility rules fail. ## Inputs - Program IDL file - Generated client directory - Optional previous IDL - Application source directory - Configuration file Example: ```yaml programIdl: target/idl/example.json clientDir: src/generated usageDirs: - src rules: forbidRemovedInstructions: true forbidChangedAccountOrder: true requireErrorCodeMapping: true requireProgramIdMatch: true ``` ## Checks 1. **Instruction presence** - Every configured client instruction exists in the current IDL. - Removed instructions are reported. 2. **Account compatibility** - Account names and ordering are compared. - Required versus optional accounts are flagged when changed. 3. **Argument compatibility** - Argument names and serialized types are compared. - Potentially breaking changes receive an explicit severity. 4. **Error mapping** - Custom program errors have client-readable names or mappings. - Unknown numeric errors are listed separately. 5. **Program identity** - The configured program ID is consistent across IDL, client configuration, and application configuration. 6. **Generated-client freshness** - A deterministic regeneration command may be run in a temporary directory. - The command reports whether generated output differs from the checked-in version. ## Output Human-readable output: ```text IDL Drift Guard: FAILED BREAKING - Instruction `withdraw`: account `vault` moved from position 2 to 3 - Argument `amount`: type changed from u64 to u128 WARNING - Error code 6007 has no client label Files: - target/idl/example.json - src/generated/example.ts ``` Optional machine-readable output: ```bash idl-drift check --format json > drift-report.json ``` ## CI Policy - `breaking` findings fail CI. - `warning` findings do not fail CI unless configured. - Reports include file paths and stable rule identifiers. - No private keys, transactions, or network writes are required. ## Non-Goals - Deploying programs - Automatically changing an IDL - Proving behavioral compatibility - Replacing integration tests - Inspecting undocumented off-chain assumptions ## Acceptance Criteria - Detects a removed instruction. - Detects an account-order change. - Detects an argument type change. - Detects stale generated client output. - Produces deterministic results on repeated runs. - Returns distinct exit codes for success, warnings, and breaking changes. - Runs entirely against local repository inputs. ## Suggested Repository Layout ```text idl-drift/ src/ commands/check.ts rules/instructions.ts rules/accounts.ts rules/arguments.ts rules/errors.ts rules/program-id.ts fixtures/ compatible/ breaking-account-order/ breaking-argument-type/ docs/ configuration.md rule-severity.md ``` ## One-Sentence Positioning **Catch Solana client/program interface drift in CI before users encounter an instruction failure.**

# Self-Directed Draft: Solana Signer Role Map ## Product **Signer Role Map** is a repository-level manifest that documents every signing authority used by a Solana application, what it may approve, and how it is intended to be handled. ## Problem Teams often have multiple authorities—upgrade authority, fee payer, treasury signer, mint authority, delegate, deployer, and admin keys—but their purpose and handling are scattered across scripts and internal notes. A compact, reviewable manifest can make risky authority changes easier to detect. ## Deliverable Add `security/signer-roles.yml`: ```yaml version: 1 roles: - id: program-upgrade label: Program upgrade authority required_for: - deploying approved program releases allowed_environments: - staging - production storage: multisig-or-hardware-wallet rotation_trigger: - signer membership changes - suspected key exposure prohibited: - routine application transactions - id: fee-payer label: Transaction fee payer required_for: - submitting application transactions allowed_environments: - development - staging - production storage: restricted-service-signer spending_limit: daily_sol: null prohibited: - signing authority-management instructions - id: treasury label: Treasury authority required_for: - approved fund transfers allowed_environments: - production storage: multisig-or-hardware-wallet approval_required: two-person-review prohibited: - automated unsupervised transfers ``` Add a review table to `security/SIGNER_REVIEW.md`: | Role | Public key | Environment | Owner | Last reviewed | Next action | |---|---|---|---|---|---| | program-upgrade | `<record separately>` | production | `<team/person>` | `<date>` | `<retain/rotate/revoke>` | ## Review Rules Before merging a signer-related change: - Every signer has exactly one role or an explicitly documented combination. - Production authorities are separated from development credentials. - No secret keys, seed phrases, or private key material appear in the repository. - Authority-changing instructions identify the expected current and resulting authority. - Treasury and upgrade actions require an approval path. - Removed team members and vendors are considered during rotation review. - The public key in deployment configuration matches the reviewed role entry. - A rollback or recovery owner is named for each critical authority. ## Acceptance Criteria A team can answer, from this manifest alone: 1. Which authorities exist? 2. What can each authority approve? 3. Where may each authority be used? 4. Who owns the review? 5. What event triggers rotation? 6. Which actions are forbidden? ## Optional CI Check Reject pull requests when: - `signer-roles.yml` is missing or invalid YAML. - A production role lacks `storage`, `owner`, or `rotation_trigger`. - A role contains private-key-like fields. - A changed public key lacks a corresponding review note.

# Self-Directed Draft: Solana RPC Resilience Contract ## Purpose A small, implementation-neutral contract for making Solana applications predictable when RPC requests fail, time out, return stale data, or encounter rate limits. ## Deliverable Teams can copy this checklist into a repository as `docs/rpc-resilience.md`. ```md # RPC Resilience Checklist ## Request classification Every RPC request is labeled: - [ ] read-only and safe to retry - [ ] read-only but slot-sensitive - [ ] simulation - [ ] transaction submission - [ ] confirmation/status lookup ## Required request metadata For each request, record: - [ ] operation name - [ ] endpoint identifier - [ ] client-side request ID - [ ] attempt number - [ ] timeout duration - [ ] observed slot, when available - [ ] normalized error category ## Retry policy - [ ] Read-only requests use bounded retries with backoff. - [ ] Slot-sensitive reads define acceptable staleness. - [ ] Simulations are retried only when the failure is transport-related. - [ ] Transaction submissions do not blindly retry an unknown outcome. - [ ] Confirmation checks may continue after submission ambiguity. - [ ] Every retry has a maximum attempt count and total time budget. ## Error categories Normalize provider-specific errors into: - `TIMEOUT` - `RATE_LIMITED` - `UNAVAILABLE` - `STALE_DATA` - `INVALID_REQUEST` - `SIMULATION_REJECTED` - `SUBMISSION_REJECTED` - `OUTCOME_UNKNOWN` ## User-facing behavior - [ ] Show progress for operations that may take longer than one request. - [ ] Explain whether the transaction was rejected, still processing, or has an unknown outcome. - [ ] Never tell the user to retry submission when the outcome is unknown without checking status first. - [ ] Provide a recovery action appropriate to the error category. - [ ] Preserve enough context for support without exposing private data. ## Test cases - [ ] endpoint timeout - [ ] rate-limit response - [ ] temporary endpoint outage - [ ] stale blockhash or slot context - [ ] simulation failure - [ ] submission accepted but response lost - [ ] confirmation timeout - [ ] malformed provider response ``` ## Minimal API shape ```ts type RpcErrorKind = | "TIMEOUT" | "RATE_LIMITED" | "UNAVAILABLE" | "STALE_DATA" | "INVALID_REQUEST" | "SIMULATION_REJECTED" | "SUBMISSION_REJECTED" | "OUTCOME_UNKNOWN"; type RpcResult<T> = | { ok: true; value: T; slot?: number; requestId: string } | { ok: false; kind: RpcErrorKind; requestId: string; retryable: boolean; message: string; }; ``` ## Acceptance criteria A Solana integration passes this gate when: 1. Every RPC call has a named operation and request ID. 2. Retry behavior is explicit per request class. 3. Submission ambiguity is handled separately from rejection. 4. Errors map to stable application categories. 5. Tests cover transport failure and lost-response scenarios. 6. User messaging distinguishes “failed,” “processing,” and “unknown outcome.” ## Product positioning **RPC Resilience Contract** is a lightweight review artifact and TypeScript type definition that helps Solana teams prevent duplicate submissions, misleading error messages, and unbounded retry loops without requiring a specific RPC provider.

# Self-Directed Draft: Solana Transaction Intent Manifest ## Product **Intent Manifest** — a small TypeScript schema that lets Solana apps describe a transaction in human-readable terms before requesting a signature. ## Problem Wallet prompts may not communicate the application’s intended outcome. Teams need a consistent way to show users what should happen, warn about important conditions, and preserve context for support. ## Proposed Interface ```ts type TransactionIntent = { version: "1"; action: string; // "Swap 10 USDC for SOL" network: "mainnet-beta" | "devnet" | "testnet" | "localnet"; feePayer: string; expectedChanges: AssetChange[]; warnings?: string[]; references?: { orderId?: string; supportCode?: string; }; }; type AssetChange = { owner: string; asset: { kind: "native" | "spl-token" | "nft" | "unknown"; mint?: string; symbol?: string; // Display-only; never trusted for validation }; direction: "debit" | "credit"; amount?: string; // Base-unit integer string maximumAmount?: string; }; ``` ## Example ```json { "version": "1", "action": "Swap up to 10000000 USDC base units for SOL", "network": "mainnet-beta", "feePayer": "USER_PUBLIC_KEY", "expectedChanges": [ { "owner": "USER_PUBLIC_KEY", "asset": { "kind": "spl-token", "mint": "USDC_MINT" }, "direction": "debit", "maximumAmount": "10000000" }, { "owner": "USER_PUBLIC_KEY", "asset": { "kind": "native" }, "direction": "credit" } ], "warnings": [ "Final output may change before execution." ], "references": { "supportCode": "SWAP-LOCAL-001" } } ``` ## Integration Rules - Generate the manifest from the same application state used to build the transaction. - Treat symbols and action text as display metadata, not security assertions. - Use mint addresses and base-unit integer strings for asset identification and amounts. - Display maximum debit amounts before signing. - Reject a signing request if the manifest network differs from the active connection. - Do not imply that the manifest proves on-chain execution. - After confirmation, compare observed balance changes with expected changes and clearly label mismatches. ## Acceptance Checklist - [ ] User can identify the requested action. - [ ] Network and fee payer are visible. - [ ] Every expected debit identifies its owner and asset. - [ ] Variable debits include a maximum. - [ ] Unknown assets are labeled as unknown. - [ ] The app stores the manifest with local support context. - [ ] Cancellation leaves no “completed” state. - [ ] Confirmation UI distinguishes intended, submitted, confirmed, and failed states. ## MVP Boundary The first version is an app-side convention and reusable UI component. It does not require a new program, token, wallet standard, or on-chain storage.

# Self-Directed Draft: Solana Integration Readiness Gate ## Product **`solana-ready`** — a repository checklist and CI-friendly review template for validating a Solana integration before release. ## Problem A feature can appear complete while key integration details remain unverified: signer behavior, account assumptions, transaction simulation, confirmation handling, and user-facing recovery paths. ## First Version A plain-text checklist that produces one of three outcomes: - **PASS** — required checks have evidence - **BLOCKED** — a required check failed or lacks evidence - **NOT APPLICABLE** — explicitly justified ## Deliverable ```md # Solana Integration Readiness Gate Release / PR: Owner: Date: Commit: ## 1. Instruction Construction - [ ] Program ID is configured from the intended environment. - [ ] Account metas are ordered and flagged as intended. - [ ] Required signers are identified before signing. - [ ] Writable accounts are limited to those actually needed. - [ ] Optional accounts have an explicit absent/present behavior. - Evidence: ## 2. Wallet and Signing - [ ] The UI explains what the user is being asked to sign. - [ ] Wallet rejection has a recoverable user path. - [ ] The app does not assume the wallet is connected after a failed request. - [ ] Signer ownership is tested with the intended wallet type. - Evidence: ## 3. Simulation and Submission - [ ] Simulation is run where appropriate before submission. - [ ] Simulation errors are retained in logs or diagnostics. - [ ] Submission and confirmation are treated as separate states. - [ ] A timeout does not silently become “success.” - [ ] Retry behavior cannot unintentionally duplicate an action. - Evidence: ## 4. Account and State Handling - [ ] Missing accounts have a defined creation or recovery path. - [ ] Existing accounts are checked for expected ownership. - [ ] Client decoding failures are surfaced distinctly from empty data. - [ ] State is refreshed after a confirmed write. - Evidence: ## 5. Failure UX - [ ] Users see a human-readable next step. - [ ] Raw error details remain available for support/debugging. - [ ] Failure messages avoid claiming success before confirmation. - [ ] The app records a correlation ID or local attempt ID. - Evidence: ## 6. Environment Safety - [ ] Target cluster/environment is visible before signing. - [ ] Test fixtures cannot accidentally point at production settings. - [ ] Configuration is documented for a clean-machine setup. - Evidence: ## Gate Result Status: PASS / BLOCKED / NOT APPLICABLE Blocking items: Follow-up owner: Follow-up deadline: ``` ## Operating Rule No release is marked **PASS** when a required item is unchecked or supported only by assumption. Evidence may be a test name, log excerpt, screenshot, fixture, or code location. ## Success Signal The tool is useful when a reviewer can identify the highest-risk unchecked integration assumption in under five minutes.

# Self-Directed Draft: Solana Transaction Failure Triage Kit A reusable incident worksheet for quickly separating client, transaction-construction, program, and network-related failures. ## Purpose Help a Solana team turn a failed transaction report into a reproducible diagnosis with clear next steps—without guessing from a wallet error message alone. ## Intake Template ```text Incident ID: Reporter: UTC time: Environment: local / testnet / mainnet / other Client version: RPC endpoint/provider: Wallet or signer type: Transaction signature, if created: Program ID(s): Expected action: Observed error: ``` ## Triage Flow ### 1. Was a transaction signature created? - **No** → Inspect wallet connection, signer availability, transaction construction, simulation output, and fee-payer configuration. - **Yes** → Retrieve the transaction details and continue. ### 2. Did the transaction reach the expected commitment state? Record: ```text Signature: Requested commitment: Observed status: Slot: Confirmation error: ``` - If it never reached the expected state, inspect blockhash lifetime, submission response, retries, and RPC consistency. - If it finalized or otherwise reached the expected state, inspect instruction-level execution. ### 3. Which instruction failed? For each instruction, record: ```text Index: Program ID: Accounts passed: Writable/signers expected: Compute budget settings: Program log excerpt: Returned error code/message: ``` Prioritize the first failing instruction; later instructions may only reflect an earlier failure. ### 4. Classify the failure | Category | Common evidence | Next action | |---|---|---| | Client construction | Missing account, wrong signer, malformed data | Compare generated instruction with the program interface | | Authorization | Missing or unexpected signer/authority | Verify signer set and authority derivation | | Account state | Wrong owner, discriminator, seed, or initialization state | Inspect account metadata and expected state | | Program logic | Explicit custom error or assertion | Map error to source-level condition | | Compute/resources | Compute exhaustion or insufficient fee budget | Measure simulation usage and review instruction composition | | Submission/RPC | No signature, inconsistent status, expired blockhash | Reproduce against a controlled RPC path | | Configuration | Wrong cluster, program ID, or environment variable | Print resolved network and addresses before signing | ## Evidence Standard Do not close the incident with only a wallet-facing message. Attach at least: - Reproduction steps - Serialized instruction inputs or a safe redacted equivalent - Account addresses and metadata - Simulation result, when available - Transaction logs, when a signature exists - Client and program commit/version identifiers - Whether the issue reproduces in a clean environment ## Minimal Reproduction Record ```text Given: cluster/environment = program = payer/authority role = account state = instruction arguments = When: the client builds and submits [instruction] Then: expected result = actual result = stable reproduction? yes/no ``` ## Exit Criteria An incident is ready to close only when one of these is documented: 1. Root cause identified and fix verified. 2. Reproduction is unavailable, with the missing evidence explicitly listed. 3. Failure is classified as external or environment-specific, with a tested workaround. 4. The report is invalidated by a clearly documented mismatch in expectations or configuration. ## Suggested Repository Location ```text docs/operations/transaction-failure-triage.md templates/transaction-incident.md ```

# Self-Directed Draft: Solana Account Compatibility Scanner ## Product **`account-compat`** — a local CLI that compares expected Solana account layouts against observed account data and flags compatibility risks before a client or program release. ## User Problem Teams can change account schemas, instruction requirements, or serialization assumptions without noticing that: - Existing accounts may no longer deserialize safely. - Clients and programs may disagree about field order or types. - Optional fields may be treated inconsistently. - Migration requirements are undocumented. ## Core Workflow ```bash account-compat scan \ --schema ./schemas \ --fixtures ./fixtures \ --output ./compat-report.json ``` The scanner: 1. Loads versioned schema definitions. 2. Reads local account fixtures or decoded test output. 3. Compares field order, types, widths, optionality, and discriminators. 4. Produces a human-readable report plus machine-readable JSON. 5. Returns a nonzero exit code when a blocking incompatibility is found. ## Example Report ```text Account: UserProfile From: v1 To: v2 BLOCKING - Field `authority` moved from offset 8 to offset 40. - Existing accounts cannot be decoded with the v2 layout. REVIEW - Field `display_name` changed from fixed bytes to variable-length data. - Migration or dual-decoding behavior is required. PASS - Discriminator unchanged. - Account size increased only through an explicitly marked extension. ``` ## Schema Format A minimal YAML definition: ```yaml name: UserProfile version: 2 discriminator: "UserProfile" fields: - name: authority type: pubkey required: true - name: display_name type: string required: false ``` Each schema should support: - Account name and version - Discriminator - Ordered fields - Serialization type - Required/optional status - Explicit migration notes - Allowed compatibility exceptions ## MVP Scope ### Include - YAML or JSON schema input - Static layout comparison - Fixture-based decoding checks - Human-readable terminal output - JSON output for CI - Exit codes: - `0`: compatible or informational findings only - `1`: review required - `2`: blocking incompatibility ### Exclude Initially - On-chain account discovery - Automatic migrations - RPC access - Language-specific code generation - Claims about runtime behavior beyond supplied schemas and fixtures ## Acceptance Criteria - Detects field reorderings and type changes. - Detects discriminator changes. - Detects account-size changes. - Distinguishes blocking findings from review findings. - Produces deterministic output for identical inputs. - Can run without network access. - Fails clearly when schemas are incomplete or malformed. ## Suggested Repository Layout ```text account-compat/ ├── schemas/ ├── fixtures/ ├── src/ ├── tests/ ├── examples/ └── README.md ``` ## Positioning Copy > Catch account-layout incompatibilities before they become release-day surprises. `account-compat` turns versioned schemas and local fixtures into a CI-friendly compatibility report.