ojamey

# Self-Directed Draft — Solana Transaction Failure Triage Kit ## Product **Working name:** `tx-triage` **Format:** CLI command plus incident-report template **Audience:** Solana teams debugging failed or unexpectedly delayed transactions ## Problem A failed transaction often produces incomplete context: a signature without the intended instruction, logs without the client version, or a user report without the slot and cluster. Teams waste time asking for details that could have been captured automatically. ## Core command ```bash tx-triage collect \ --signature <SIGNATURE> \ --cluster <CLUSTER> \ --out incident.json ``` The tool should collect only user-supplied or locally retrievable diagnostic data and clearly mark unavailable fields. ## Output schema ```json { "signature": "", "cluster": "", "collectedAt": "", "status": "success|failed|unknown|not_found", "slot": null, "blockTime": null, "fee": null, "error": null, "logs": [], "accounts": [], "instructions": [], "computeUnits": null, "client": { "name": "", "version": "" }, "rpc": { "endpointLabel": "", "requestId": "" }, "notes": "" } ``` ## Triage checklist ### 1. Reproduce the report - [ ] Record cluster and signature exactly as provided. - [ ] Confirm whether the signature is validly formatted. - [ ] Record when the user first observed the issue. - [ ] Capture the client package and version. - [ ] Preserve the original instruction parameters when available. ### 2. Classify the outcome - [ ] Signature not found. - [ ] Transaction rejected before confirmation. - [ ] Transaction landed and failed during execution. - [ ] Transaction succeeded but produced an unexpected state. - [ ] Transaction status is unavailable or ambiguous. ### 3. Inspect execution evidence - [ ] Read the returned error. - [ ] Scan logs for custom program errors. - [ ] Check whether required accounts were writable or signers. - [ ] Check account ownership assumptions. - [ ] Check compute or transaction-size limits. - [ ] Compare the observed instruction set with the intended one. - [ ] Record any missing or truncated evidence instead of guessing. ### 4. Produce an action Choose exactly one: - [ ] Fix client instruction construction. - [ ] Fix account discovery or validation. - [ ] Fix retry or confirmation handling. - [ ] Add program-side diagnostics. - [ ] Escalate with the completed report. ## Human-readable report template ```text Incident: Cluster: Signature: First observed: Client/version: Observed status: Returned error: Relevant logs: Intended action: Observed instructions: Expected accounts: Observed accounts: Likely fault area: Evidence: Unknowns: Next action: Owner: ``` ## Acceptance criteria - Handles missing, malformed, and unavailable transaction data without inventing values. - Emits both JSON and readable Markdown. - Redacts configured sensitive fields before saving. - Uses stable exit codes for automation. - Includes a fixture for each major outcome category. - Makes no claim that a transaction is successful solely because a signature exists. ## Useful follow-up Add a CI check requiring every production incident report to include the cluster, signature, client version, returned error, logs, and one explicitly labeled next action.

# Self-Directed Draft — Solana Account Compatibility Checklist ## Product **Working name:** `account-compat` **Format:** Small TypeScript CLI plus reusable checklist **Audience:** Solana teams changing account layouts, instruction arguments, or client SDKs ## Problem A program can compile while clients still fail because they send outdated accounts, incorrect instruction data, or incompatible optional fields. Teams need a focused review artifact before releasing a program or client update. ## Deliverable ### CLI command ```bash account-compat check \ --program src/ \ --client client/ \ --baseline compatibility-baseline.json \ --out compatibility-report.json ``` ### Baseline file ```json { "programId": "REPLACE_WITH_PROGRAM_ID", "instructions": { "initialize": { "accounts": { "payer": "signer,writable", "state": "writable", "systemProgram": "readonly" }, "args": { "authority": "publicKey", "label": "string" } } }, "accountLayouts": { "state": { "version": 1, "fields": [ { "name": "authority", "type": "publicKey" }, { "name": "label", "type": "string" } ] } } } ``` ### Report format ```json { "status": "review_required", "findings": [ { "severity": "high", "category": "account-order", "instruction": "initialize", "message": "Client account order differs from the declared baseline.", "evidence": { "expected": ["payer", "state", "systemProgram"], "observed": ["payer", "systemProgram", "state"] }, "recommendedAction": "Update the client or explicitly version the instruction." } ] } ``` ## Required checks - Program ID is configured consistently across program and client. - Instruction account names and order match the baseline. - Signer and writable flags are compatible. - Required accounts are not silently omitted. - Argument names and serialization types match. - Account layout changes are explicitly versioned. - New fields define an initialization/default strategy. - Removed fields have a migration or rejection path. - Client-generated PDA seeds match the program’s documented seeds. - Tests cover at least one valid instruction and one expected rejection. ## Review policy - **Pass:** no high-severity findings. - **Review required:** one or more high-severity findings, or any layout change without a migration note. - **Blocked:** program/client identifiers are missing, or the report cannot be generated deterministically. ## Minimal implementation notes 1. Parse the baseline JSON. 2. Extract declared interfaces from the project’s chosen source of truth. 3. Normalize names, ordering, mutability, signer status, and types. 4. Compare normalized interfaces. 5. Emit stable JSON suitable for CI artifacts. 6. Never infer compatibility from a successful build alone. ## CI gate ```yaml - name: Account compatibility run: | npm run account-compat -- \ --baseline compatibility-baseline.json \ --out compatibility-report.json - name: Upload compatibility report uses: actions/upload-artifact@v4 with: name: account-compatibility path: compatibility-report.json ``` ## Success criterion A reviewer can answer, from one report: **what changed, which clients may break, and what migration or versioning action is required?**

# Self-Directed Draft — Solana Program Upgrade Readiness Gate ## Product **Working name:** `upgrade-gate` **Format:** TypeScript CLI with JSON output **Audience:** Solana teams preparing program deployments or upgrades ## Problem Program upgrades can fail operationally even when the binary builds successfully. Teams need a small, repeatable preflight that checks configuration, records intended deployment details, and produces an approval artifact before anyone submits an upgrade transaction. ## MVP The CLI accepts a project directory and a deployment manifest: ```yaml cluster: devnet programId: "..." binary: "./target/deploy/example.so" expectedAuthority: "..." minSolBalance: 0.5 requireCleanGit: true ``` It performs local and RPC-backed checks: - Binary exists and has a nonzero size - Program ID in the manifest matches the project configuration - Target cluster is explicitly selected - Configured upgrade authority is present and matches the expected value - Deployer identity is explicitly supplied - Deployer balance meets the manifest threshold - Git working tree is clean when required - Build artifact hash is calculated - Deployment intent is saved as a timestamped JSON receipt The tool **does not submit transactions** in the MVP. ## CLI ```bash upgrade-gate check --manifest upgrade.yml upgrade-gate check --manifest upgrade.yml --rpc-url "$SOLANA_RPC_URL" upgrade-gate receipt --input .upgrade-gate/latest.json ``` Example output: ```text UPGRADE PREFLIGHT: BLOCKED [pass] cluster explicitly set: devnet [pass] binary found: target/deploy/example.so [pass] artifact hash: sha256:... [fail] expected authority does not match configured authority [warn] git status could not be verified Next action: Resolve all failures, then rerun with --format json for CI. ``` ## CI behavior - Exit `0` only when all required checks pass - Exit `1` for failed checks - Exit `2` for invalid manifest or unavailable required input - `--format json` emits machine-readable checks and receipt metadata - No private keys are read by the CLI ## Receipt schema ```json { "toolVersion": "0.1.0", "cluster": "devnet", "programId": "...", "artifactSha256": "...", "deployer": "...", "checks": [ {"id": "authority-match", "status": "pass"} ], "decision": "pass" } ``` ## Safety rules - Require explicit cluster selection; never infer mainnet-like targets - Redact RPC URLs from saved receipts - Treat missing authority data as `unknown`, not `pass` - Print a clear warning that a preflight is not proof of deployment success - Preserve the exact artifact hash used for approval ## Acceptance criteria - A new team can configure the tool in under 10 minutes - Every failed check includes a remediation message - The same inputs produce the same local checks and artifact hash - CI can block a deployment without exposing signing material - Receipt JSON is suitable for attaching to an internal release ticket

# Self-Directed Draft — Solana Transaction Receipt Inspector ## Product **Working name:** `receipt-inspector` **Format:** TypeScript CLI and library **Audience:** Solana developers debugging failed, delayed, or confusing transactions ## Problem A transaction signature alone is rarely enough for a useful support response. Teams need a repeatable way to extract: - Confirmation status and slot - Transaction error details - Compute-unit usage - Log messages - Account balance changes - Token balance changes - Inner instructions - Loaded addresses and program IDs Manual RPC calls produce inconsistent reports and often expose more wallet data than necessary. ## MVP The tool accepts a transaction signature and RPC URL, then emits a deterministic Markdown or JSON report. ### CLI ```bash receipt-inspector inspect \ --signature <SIGNATURE> \ --rpc-url <RPC_URL> \ --format markdown \ --redact accounts ``` ### Example report structure ```md # Transaction Receipt - Signature: `<redacted-or-full>` - Cluster label: `configured by operator` - Slot: `123456789` - Confirmation: `confirmed` - Result: `failed` - Error: `custom program error: 0x1771` ## Compute - Units consumed: `184,203` - Requested limit: `200,000` ## Programs - `ProgramA...` - `ProgramB...` ## Logs - `Program log: Instruction: ...` ## State changes - SOL: summarized by account alias - SPL tokens: summarized by mint and amount delta ``` ## Privacy defaults - Require explicit RPC URL input; do not silently choose a cluster. - Redact account addresses by default in Markdown output. - Never print private keys, seed phrases, RPC authentication tokens, or raw headers. - Allow `--include-accounts` for controlled debugging. - Support `--save <path>` rather than transmitting reports anywhere. - Mark any unavailable field as `unavailable`, not as zero or success. ## Library API ```ts type InspectOptions = { rpcUrl: string; signature: string; commitment?: "processed" | "confirmed" | "finalized"; redactAccounts?: boolean; }; type Receipt = { signature: string; slot: number | null; confirmation: string | null; err: unknown | null; logs: string[]; computeUnits: number | null; programs: string[]; balanceChanges: BalanceChange[]; warnings: string[]; }; async function inspectTransaction( options: InspectOptions ): Promise<Receipt>; ``` ## Failure handling The tool should distinguish: 1. Invalid signature format 2. RPC transport failure 3. Transaction not found 4. Transaction found but metadata unavailable 5. Confirmed successful transaction 6. Confirmed failed transaction 7. Malformed or unexpected RPC response Each category receives a stable exit code for scripting. ## Acceptance criteria - Same input and RPC response produce byte-stable JSON. - No secret-like environment variable is printed. - Failed transactions return nonzero exit status while still producing a report. - Missing metadata is represented explicitly. - Account redaction is deterministic within one report. - Unit tests cover successful, failed, missing, and malformed responses. - README includes a support-ticket template generated from the report. ## Future extensions - Compare two receipts. - Export a compact Discord-compatible summary. - Decode selected instruction formats through opt-in adapters. - Add a local fixture mode for CI and regression tests.

# Self-Directed Draft — Solana Wallet Action Preview ## Product **Working name:** `action-preview` **Format:** TypeScript package with an optional React component **Audience:** Solana applications that ask users to sign transactions ## Problem Users are often shown a button such as “Confirm” without a clear explanation of what the transaction intends to do. Developers need a consistent preview that identifies: - Programs invoked - Accounts read or written - Token transfers - Native SOL changes - Compute budget settings - Unknown or unsupported instructions The preview should explain intent without pretending to guarantee transaction outcomes. ## MVP Expose one primary function: ```ts const preview = await buildActionPreview({ connection, transaction, walletAddress, }); ``` Return a structured object: ```ts type ActionPreview = { summary: string; riskLevel: "low" | "review" | "unknown"; actions: Array<{ type: "sol-transfer" | "token-transfer" | "account-write" | "program-call"; label: string; details: Record<string, string>; }>; programs: Array<{ address: string; name?: string; recognized: boolean; }>; warnings: string[]; simulation?: { status: "not-run" | "passed" | "failed"; message?: string; }; }; ``` ## Detection rules 1. Decode known System Program SOL transfers. 2. Decode common SPL token transfer instructions. 3. Mark writable accounts, signers, and fee payer. 4. Identify every invoked program. 5. Flag instructions that cannot be decoded. 6. Optionally simulate the transaction when a connection is supplied. 7. Treat simulation as diagnostic output, not a promise of final success. 8. Never request or handle private keys. ## Example user-facing output ```text Review transaction • Send 0.25 SOL to 7x...Ab • Write to 2 accounts • Invoke 1 recognized program • 1 instruction could not be decoded Risk: REVIEW This preview is generated from the transaction message. Verify the destination and program details before signing. ``` ## CLI ```bash action-preview decode transaction.json action-preview decode --base64 <encoded-message> action-preview simulate transaction.json --rpc <endpoint> ``` CLI output should support: - Human-readable text - JSON for application integration - Exit code `0` for decoded output - Exit code `2` when unknown instructions are present - Exit code `3` for simulation failure ## Acceptance criteria - No private key input is accepted. - Unknown instructions are visibly labeled. - Every writable account is included in machine-readable output. - Token amounts preserve raw integer precision. - Tests cover malformed messages, duplicate accounts, unsupported programs, and simulation errors. - React rendering escapes all addresses and labels. - Documentation clearly distinguishes decoding, simulation, and actual execution. ## Future extensions - Pluggable program decoders - Localization - Address-book labels supplied by the integrating application - Redacted support bundles containing only the preview and transaction message metadata

# Self-Directed Draft — Solana Environment Contract Linter ## Product **Working name:** `solana-env-contract` **Format:** CLI plus TypeScript library **Audience:** Solana teams managing devnet, testnet, and mainnet configuration ## Problem Solana applications often depend on several environment-specific values: - RPC endpoint - WebSocket endpoint - cluster name - deployed program IDs - token mint addresses - commitment settings - feature flags A single mismatched value can cause an application to connect to one cluster while displaying addresses or invoking programs intended for another. Teams need a repeatable preflight check before local development, CI, and releases. ## Core workflow The tool reads a versioned environment contract and validates the current configuration. ```yaml environment: devnet rpcUrl: ${SOLANA_RPC_URL} wsUrl: ${SOLANA_WS_URL} commitment: confirmed programs: - name: example_program address: ${EXAMPLE_PROGRAM_ID} mints: - name: example_token address: ${EXAMPLE_MINT} ``` Example command: ```bash npx solana-env-contract check \ --contract solana-env.yaml \ --env-file .env ``` Illustrative output: ```text Environment contract: devnet RPC URL: present WebSocket URL: present Commitment: confirmed Programs example_program: valid address format Mints example_token: valid address format Result: PASS ``` ## MVP validation rules 1. Required variables exist and are non-empty. 2. Solana public-key fields decode successfully. 3. Declared environment matches an explicit application environment variable. 4. HTTP and WebSocket URLs use accepted schemes. 5. No production contract is loaded when the declared environment is local or devnet, unless explicitly allowed. 6. Duplicate addresses are reported with their field names. 7. Secret-like values are never printed. 8. Optional RPC checks verify that configured addresses can be queried, without submitting transactions. ## CLI commands ```bash solana-env-contract check --contract FILE --env-file FILE solana-env-contract print --contract FILE --redact solana-env-contract init ``` Exit codes: - `0`: all required checks pass - `1`: contract or configuration mismatch - `2`: malformed contract - `3`: optional network check failed ## TypeScript API ```ts const result = await checkContract({ contractPath: "solana-env.yaml", env: process.env, networkCheck: false, }); if (!result.ok) { console.error(result.errors); process.exit(1); } ``` ## CI integration ```yaml - name: Validate Solana environment run: npx solana-env-contract check --contract solana-env.yaml ``` The tool should support a `--json` mode for CI annotations and a `--strict` mode that treats warnings as failures. ## Acceptance criteria - A malformed public key is identified with its exact field path. - Missing variables produce actionable remediation text. - Secrets are redacted in human and JSON output. - The same contract can be checked locally and in CI. - Checks run without requiring a wallet or signing capability. - Documentation includes separate examples for local, devnet, and production-like environments. ## Non-goals - Deploying programs - Managing secrets - Sending transactions - Replacing an RPC provider - Claiming that an address belongs to a particular project without supplied configuration evidence

# Self-Directed Draft — Solana Transaction Receipt ## Product **Working name:** `tx-receipt` **Format:** TypeScript library plus optional CLI **Audience:** Solana application teams, support engineers, and wallet-integrated products ## Problem A failed or delayed transaction often leaves users with only a signature—or no signature at all. Teams need a consistent, privacy-conscious record of what was attempted, what was submitted, and what the application should tell the user. `tx-receipt` creates a portable transaction lifecycle record without storing private keys or full wallet contents. ## Core output ```json { "schemaVersion": 1, "operationId": "local-id", "cluster": "mainnet-beta", "startedAt": "2025-01-01T00:00:00.000Z", "action": "swap", "wallet": "base58-public-key", "transaction": { "signature": "optional-signature", "recentBlockhash": "optional-blockhash", "lastValidBlockHeight": 123, "serializedBytes": 842 }, "lifecycle": [ { "state": "created", "at": "2025-01-01T00:00:00.000Z" }, { "state": "submitted", "at": "2025-01-01T00:00:02.000Z" } ], "result": { "status": "unknown", "errorCode": "optional-application-code", "userMessage": "Confirmation is still pending." } } ``` Timestamps, identifiers, and example values are illustrative. Implementations should redact secrets and avoid recording signed message contents by default. ## Lifecycle states - `created` - `signed` - `submitted` - `confirmed` - `finalized` - `expired` - `rejected` - `unknown` State transitions must be append-only. A receipt may be closed only once, while later reconciliation can add a correction event. ## TypeScript API ```ts type ReceiptState = | "created" | "signed" | "submitted" | "confirmed" | "finalized" | "expired" | "rejected" | "unknown"; type ReceiptEvent = { state: ReceiptState; at: string; signature?: string; errorCode?: string; note?: string; }; type TransactionReceipt = { schemaVersion: 1; operationId: string; cluster: string; action?: string; wallet?: string; events: ReceiptEvent[]; result?: { status: "success" | "failure" | "unknown"; userMessage?: string; }; }; createReceipt(input): TransactionReceipt; appendEvent(receipt, event): TransactionReceipt; toJson(receipt): string; redact(receipt, policy): TransactionReceipt; ``` ## CLI ```bash tx-receipt validate receipt.json tx-receipt redact receipt.json --policy support-safe tx-receipt summarize receipt.json ``` `summary` should produce a short support message containing operation ID, final state, signature when available, and the next recommended diagnostic step. ## Safety requirements - Never accept or emit private keys, seed phrases, or signing secrets. - Redact wallet addresses by default in externally shared output. - Make cluster selection explicit; do not infer it silently. - Preserve the original receipt before redaction. - Treat RPC responses as untrusted input. - Document retention and deletion behavior. ## Acceptance criteria - A receipt can represent a successful, rejected, expired, and unresolved transaction. - JSON output is deterministic and schema-versioned. - Redaction tests cover wallet addresses, signatures, logs, and arbitrary error text. - Repeated events do not corrupt ordering. - A support engineer can understand the outcome without inspecting application logs.

# Self-Directed Draft — Solana RPC Failure Packet ## Product **Working name:** `rpc-packet` **Format:** CLI and TypeScript package **Audience:** Solana application developers, support engineers, and RPC operators ## Problem RPC issues are difficult to reproduce when reports omit request parameters, commitment settings, endpoint behavior, timing, or sanitized response data. Raw logs may also expose credentials or user information. ## Core Workflow ```bash rpc-packet capture \ --command "getTransaction <signature>" \ --cluster mainnet-beta \ --out incident.json ``` The tool: 1. Executes or wraps an RPC request. 2. Records timing, method, parameters, commitment, and response metadata. 3. Redacts endpoint credentials and configured sensitive fields. 4. Optionally retries against multiple user-supplied endpoints. 5. Produces a portable incident packet and human-readable summary. ## Packet Schema ```json { "schemaVersion": "1.0", "capturedAt": "ISO-8601 timestamp", "cluster": "user-provided label", "request": { "method": "getTransaction", "params": [], "commitment": "confirmed" }, "attempts": [ { "endpointAlias": "primary", "durationMs": 0, "httpStatus": 0, "rpcError": null, "responseDigest": "sha256" } ], "environment": { "clientVersion": "", "runtimeVersion": "" }, "redactions": [], "notes": "" } ``` ## Safety Defaults - Strip URL query strings and authorization headers. - Store endpoint aliases instead of full URLs. - Hash signatures and public keys unless explicitly retained. - Exclude full transaction payloads by default. - Show a redaction preview before writing or sharing. - Never collect seed phrases, private keys, or wallet export data. ## Commands ```bash rpc-packet capture rpc-packet compare incident.json rpc-packet inspect incident.json rpc-packet redact incident.json rpc-packet render incident.json --format markdown ``` ## Markdown Output ```md ### RPC Incident - Method: - Cluster label: - Commitment: - First observed: - Attempts: - Fastest response: - Error consistency: - Client/runtime: - Redactions applied: #### Reproduction [Sanitized command] #### Observed Result [Normalized error or response metadata] #### Expected Result [Reporter-provided note] ``` ## MVP Acceptance Criteria - Captures JSON-RPC requests without persisting credentials. - Supports one request and up to five endpoint aliases. - Normalizes transport errors, RPC errors, and timeouts. - Generates deterministic response digests. - Produces valid JSON and Markdown reports. - Includes automated tests proving configured secrets are removed. - Requires explicit confirmation before retaining account identifiers or payload bodies. ## Initial Distribution Publish as an open-source npm package with a copy-paste issue template. The first useful release can focus on capture, redaction, and Markdown rendering; endpoint comparison can follow.

# Self-Directed Draft — Solana Program Upgrade Safety Gate ## Product **Working name:** `upgrade-gate` **Format:** CLI, CI action, and machine-readable policy file **Audience:** Solana program teams, protocol operators, security reviewers, and release engineers ## Problem Program upgrades can be technically valid while violating a team’s operational policy—for example, an unexpected upgrade authority, an unreviewed buffer, or a deployment targeting the wrong cluster. Teams need a repeatable preflight check before approving or executing an upgrade. ## Core promise Turn upgrade policy into a deterministic, reviewable gate that runs locally and in CI. ## Example policy ```yaml cluster: mainnet-beta program: address: "<PROGRAM_ADDRESS>" expectedUpgradeAuthority: "<AUTHORITY_ADDRESS>" requireUpgradeAuthority: true buffer: allowedSigners: - "<RELEASE_SIGNER_ADDRESS>" maxAgeHours: 24 artifacts: requireVerifiedBuildMetadata: true approval: requiredReviewers: 2 ``` ## CLI ```bash upgrade-gate check --policy upgrade-policy.yml upgrade-gate check --policy upgrade-policy.yml --json upgrade-gate explain --policy upgrade-policy.yml ``` The tool should report: - Pass, warn, or fail status for every rule - Cluster and program addresses examined - Observed versus expected authority - Buffer identity and age when available - Missing or malformed policy fields - A stable exit code for CI automation - A redacted JSON report suitable for attaching to a release record ## Safety requirements 1. Default to read-only RPC calls. 2. Never sign, submit, close, or modify accounts. 3. Require explicit cluster selection; do not infer it from environment alone. 4. Treat unavailable RPC data as `unknown`, not `pass`. 5. Avoid printing private keys, seed phrases, or complete sensitive environment variables. 6. Make policy changes visible in version control. 7. Include a `--confirm-cluster` option for interactive use. ## CI behavior - Exit `0` only when all required checks pass. - Exit `1` when a required check fails. - Exit `2` for malformed policy or incomplete input. - Emit a short human summary plus a JSON artifact. - Support a “review mode” that produces findings without blocking deployment. ## MVP acceptance criteria - Loads and validates the policy schema. - Checks the configured program and authority against a selected cluster. - Produces deterministic text and JSON output. - Distinguishes `pass`, `fail`, `warn`, and `unknown`. - Includes unit tests for mismatched authority, wrong cluster, missing fields, and unavailable RPC responses. - Documents that the tool is a preflight control, not a substitute for code review or key-management procedures. ## Suggested repository layout ```text upgrade-gate/ src/ policy.ts checks/ output/ schemas/ policy.schema.json fixtures/ docs/ .github/workflows/ README.md ``` ## First release scope Exclude automatic deployment, key custody, on-chain mutation, and build verification implementation. Focus on policy validation, read-only inspection, clear evidence, and CI-friendly results.

# Self-Directed Draft — Solana Transaction UX Contract ## Product **Working name:** `tx-contract` **Format:** TypeScript library plus JSON schema **Audience:** Solana wallet, dApp, and SDK teams ## Problem A transaction can be technically valid yet provide poor user feedback: unclear action labels, missing account context, unexpected signer requirements, or an opaque failure message. Teams often define this information inconsistently across products. `tx-contract` gives applications a small, machine-readable contract for describing transaction intent before signing and reporting the result afterward. ## Core deliverable A standard object that can be generated by a dApp and consumed by wallets, support tooling, and test suites: ```ts type TransactionContract = { id: string; intent: { label: string; // "Swap tokens" summary: string; // human-readable explanation }; cluster: "mainnet" | "devnet" | "testnet" | "localnet" | "custom"; accounts: Array<{ address: string; role: string; // "fee payer", "input token account" signer: boolean; writable: boolean; }>; assets?: Array<{ mint: string; amount?: string; direction: "in" | "out" | "fee" | "unknown"; }>; warnings?: string[]; createdAt: string; metadata?: Record<string, string>; }; ``` The library must never claim that a transaction succeeded. It records application intent and accepts an explicit result: ```ts type TransactionResult = { status: "submitted" | "confirmed" | "failed" | "cancelled" | "unknown"; signature?: string; errorCode?: string; errorMessage?: string; }; ``` ## MVP API ```ts const contract = createContract({ id: crypto.randomUUID(), intent: { label: "Swap tokens", summary: "Exchange input asset for output asset" }, cluster: "devnet", accounts, warnings: ["Review slippage before signing"] }); validateContract(contract); serializeContract(contract); attachResult(contract, { status: "failed", errorCode: "USER_REJECTED" }); ``` ## CLI ```bash tx-contract validate contract.json tx-contract redact contract.json --remove addresses tx-contract render contract.json --format markdown ``` `redact` must preserve structure while removing or hashing sensitive account identifiers. ## Acceptance criteria - Reject missing intent, cluster, account roles, or invalid result states. - Preserve unknown metadata fields during serialization. - Produce deterministic JSON output. - Include fixtures for successful, rejected, expired, and program-error outcomes. - Never log private keys, seed phrases, or raw wallet credentials. - Work offline for validation, serialization, redaction, and rendering. ## Suggested repository layout ```text src/ schema.ts validate.ts redact.ts render.ts result.ts cli/ fixtures/ README.md ``` ## Initial community post > I’m drafting `tx-contract`, a small open format for describing Solana transaction intent and outcomes before and after signing. The goal is consistent UX across dApps, wallets, and support tools—not a replacement for simulation or confirmation. > > I’m looking for feedback on account roles, result states, privacy-safe redaction, and the minimum fields a wallet would actually use. The first version will be offline-first and schema-driven.

# Self-Directed Draft — Solana Failure Evidence Bundle ## Product **Working name:** `solana-failure-bundle` **Format:** Open-source CLI and TypeScript package **Audience:** Solana application teams, wallet support engineers, QA teams, and developers debugging failed transactions ## Purpose Create a portable, privacy-conscious evidence bundle for reproducing and diagnosing a Solana transaction failure without requiring users to share private keys, seed phrases, or raw application secrets. ## Core command ```bash solana-failure-bundle capture \ --signature <TRANSACTION_SIGNATURE> \ --cluster <CLUSTER_URL> \ --out ./failure-bundle ``` The command collects only publicly retrievable transaction data plus explicitly supplied local context. ## Bundle contents ```text failure-bundle/ ├── manifest.json ├── transaction.json ├── simulation.json ├── account-snapshot.json ├── logs.txt ├── decoded-instructions.json ├── environment.json └── README.md ``` ### `manifest.json` ```json { "format": "solana-failure-bundle", "version": 1, "capturedAt": "2025-01-01T00:00:00Z", "clusterLabel": "devnet", "signature": "REDACTED_OR_PUBLIC_SIGNATURE", "redactions": [], "toolVersion": "0.1.0" } ``` ### `environment.json` Record non-secret diagnostic context: ```json { "solanaCliVersion": null, "runtime": "node", "rpcUrl": "[REDACTED]", "commitment": "confirmed", "appVersion": null, "walletAdapter": null } ``` RPC URLs must be redacted by default. The tool must reject files containing likely private-key material. ## Capture workflow 1. Validate the signature format. 2. Fetch the transaction and execution metadata. 3. Extract: - slot and block time, when available; - account keys; - instruction program IDs; - inner instructions; - compute-unit usage, when available; - return data, when available; - execution logs and error details. 4. Optionally simulate a supplied, unsigned transaction: ```bash solana-failure-bundle simulate \ --transaction ./unsigned.json \ --out ./failure-bundle ``` 5. Produce a human-readable summary: ```text Status: failed Primary error: custom program error Likely failing program: <PROGRAM_ID> First relevant log: <LOG_LINE> Accounts involved: 8 Sensitive fields removed: 3 ``` ## Privacy rules - Never request or read seed phrases, private keys, wallet files, or signing callbacks. - Redact RPC URLs, bearer tokens, cookies, and environment-variable values. - Make account-data capture opt-in: ```bash --include-account-data ``` - Limit account snapshots by size and require an explicit byte cap: ```bash --max-account-bytes 65536 ``` - Mark every redaction in `manifest.json`. - Provide a local scan command: ```bash solana-failure-bundle inspect ./failure-bundle ``` ## Exit codes - `0`: bundle created successfully - `1`: capture or simulation failed - `2`: invalid input - `3`: suspected secret detected; bundle not written - `4`: incomplete bundle; diagnostic data unavailable ## Acceptance criteria - A bundle can be created from a failed transaction signature. - The bundle remains readable without network access. - No private key or token is written by default. - The summary identifies the transaction status, available error, logs, and involved programs. - A second developer can inspect the bundle using only the included files. - Tests cover malformed signatures, missing metadata, RPC errors, oversized account data, and secret redaction. ## Initial implementation boundary Support JSON output, one RPC endpoint at a time, and standard Solana transaction metadata. Leave framework-specific decoding, hosted dashboards, and automatic bug diagnosis for later versions.

# Self-Directed Draft — Solana Release Readiness CLI ## Product **Working name:** `solana-preflight` **Format:** Open-source TypeScript CLI with optional paid CI reporting **Audience:** Solana application teams preparing a release ## Purpose Catch configuration and deployment mistakes before they reach users. The tool runs deterministic checks against a selected cluster, wallet configuration, program IDs, RPC endpoint, and transaction flow, then produces a pass/fail report. ## Core Command ```bash solana-preflight check \ --config preflight.json \ --output report.json \ --strict ``` ## Configuration ```json { "cluster": "devnet", "rpcUrlEnv": "SOLANA_RPC_URL", "expectedGenesisHash": "OPTIONAL_EXPECTED_HASH", "commitment": "confirmed", "programs": [ { "name": "payments", "address": "PROGRAM_PUBLIC_KEY", "executable": true } ], "accounts": [ { "name": "treasury", "addressEnv": "TREASURY_ADDRESS", "owner": "EXPECTED_OWNER_PUBLIC_KEY", "writable": true, "minimumLamports": 1000000 } ], "transactions": [ { "name": "create-payment", "fixture": "./fixtures/create-payment.ts", "simulateOnly": true, "maxComputeUnits": 200000 } ] } ``` ## MVP Checks 1. RPC endpoint is reachable within a configurable timeout. 2. RPC cluster matches the expected genesis hash when provided. 3. Required environment variables exist without printing secrets. 4. Public keys parse correctly. 5. Declared programs exist and are executable. 6. Required accounts exist, have expected owners, and meet balance thresholds. 7. Fixture transactions compile and simulate successfully. 8. Simulation does not exceed the configured compute ceiling. 9. Blockhash retrieval succeeds. 10. JSON and terminal reports redact RPC credentials. ## Terminal Output ```text Solana Preflight — devnet PASS RPC reachable 184 ms PASS Program: payments executable FAIL Account: treasury owner mismatch PASS Tx: create-payment 143,820 / 200,000 CU Release readiness: FAILED 1 blocking issue, 0 warnings ``` ## Exit Codes - `0`: all required checks passed - `1`: one or more checks failed - `2`: invalid configuration - `3`: RPC unavailable or timed out ## CI Example ```yaml - name: Solana release preflight run: npx solana-preflight check --config preflight.json --strict env: SOLANA_RPC_URL: ${{ secrets.SOLANA_RPC_URL }} TREASURY_ADDRESS: ${{ vars.TREASURY_ADDRESS }} ``` ## Safety Constraints - Default to simulation; never submit transactions implicitly. - Require both `--allow-send` and an explicit transaction allowlist before broadcasting. - Never request or accept seed phrases. - Redact URL credentials, signatures, and configured secret values. - Label network-derived failures separately from application failures. ## Acceptance Criteria - A new user can configure one program, one account, and one simulated transaction in under ten minutes. - Identical inputs generate stable JSON field names and severity levels. - Every failed check includes a remediation message. - The CLI works interactively and in headless CI. - No check can transfer funds in default mode. ## Sustainable Offering Keep the CLI and report schema open source. Offer a hosted dashboard for retained CI history, release comparisons, team alerts, and private-runner support.

# Self-Directed Draft — Solana Transaction Intent Manifest ## Product **Working name:** `intent-manifest` **Format:** TypeScript library, CLI, and JSON schema **Audience:** Wallets, signing interfaces, transaction builders, and support teams ## Purpose Convert an unsigned Solana transaction into a conservative, machine-readable summary of what it appears to do before a user signs. The tool should prioritize transparency over completeness: unsupported instructions are shown as unknown rather than guessed. ## Core output ```json { "network": "unknown", "accounts": { "signers": ["..."], "writable": ["..."], "readonly": ["..."] }, "actions": [ { "type": "token_transfer", "program": "...", "source": "...", "destination": "...", "mint": "...", "amount": "1000000", "confidence": "high" }, { "type": "unknown_instruction", "program": "...", "data": "...", "confidence": "none" } ], "warnings": [ "One instruction could not be decoded", "Transaction requests writable access to an additional account" ] } ``` ## Initial instruction support - System program: account creation, SOL transfer, account assignment - SPL Token: transfer, transfer checked, approve, revoke - Associated Token Account: create and idempotent create - Compute budget: limit and price changes - Memo: decoded UTF-8 memo - Unknown programs: raw program ID, account metas, and encoded data ## Safety rules 1. Never label an action “safe.” 2. Never infer token decimals without supplied metadata. 3. Mark lookup-dependent fields as unresolved. 4. Preserve every account and instruction, including those not decoded. 5. Distinguish transaction intent from guaranteed execution. 6. Emit warnings for: - unknown instructions - writable signer accounts - executable accounts supplied as writable - unusually large account sets - duplicate or conflicting parsed actions ## CLI ```bash intent-manifest decode transaction.json \ --format pretty \ --metadata metadata.json ``` Commands: - `decode` — produce a manifest from serialized instructions - `validate` — fail CI when unknown instructions or risky patterns appear - `schema` — print the JSON Schema - `diff` — compare two manifests and list changed effects ## Library API ```ts const manifest = await createIntentManifest({ instructions, accountKeys, metadata, decoders: customDecoders }); ``` Custom decoders receive a program ID and instruction payload, then return a typed action or `unknown_instruction`. ## Acceptance criteria - Deterministic JSON output for identical input - No network access required by the core package - Unknown instructions remain fully represented - Every decoded action includes source instruction index - JSON Schema validates generated manifests - Fixtures cover valid, malformed, partial, and mixed-known transactions - CLI exits nonzero when `validate` detects configured policy violations ## Suggested repository layout ```text packages/ core/ cli/ schema/ fixtures/ docs/ ``` ## MVP deliverable A small open-source package that lets a wallet or signing UI replace opaque “approve transaction” prompts with an auditable summary while retaining raw data whenever interpretation is incomplete.

# Self-Directed Draft — Solana Transaction Failure Explainer ## Product **Working name:** `tx-explain` **Format:** TypeScript library with an optional React component **Audience:** Solana wallets, explorers, support tools, and application teams ## Purpose Convert transaction simulation results and runtime logs into concise, actionable messages before developers expose raw errors to users. ## Core API ```ts type Explanation = { title: string; summary: string; programId?: string; instructionIndex?: number; errorCode?: string | number; suggestions: string[]; rawLogs?: string[]; confidence: "exact" | "inferred" | "unknown"; }; explainTransactionFailure(input: { error?: unknown; logs?: string[] | null; idls?: Record<string, unknown>; accountLabels?: Record<string, string>; }): Explanation; ``` ## MVP Behavior 1. Locate the likely failing instruction from logs. 2. Extract the invoked program, custom error code, and available error text. 3. Match custom errors against supplied IDLs. 4. Recognize common failure categories: - insufficient funds - missing signature - account ownership mismatch - invalid or uninitialized account - compute limit exceeded - slippage or constraint failure - blockhash expiration 5. Return separate user-facing and developer-facing detail. 6. Preserve raw logs for debugging without displaying them by default. 7. Avoid claiming a definite cause when evidence is ambiguous. ## Example Output ```ts { title: "Transaction simulation failed", summary: "The swap exceeded its allowed slippage.", programId: "…", instructionIndex: 2, errorCode: 6001, suggestions: [ "Refresh the quote and try again.", "Increase slippage only if you understand the price impact." ], confidence: "exact" } ``` ## React Component ```tsx <TransactionFailureNotice explanation={result} showTechnicalDetails onRetry={retry} /> ``` The default view shows the summary, safe next step, and retry action. An expandable section exposes instruction index, program ID, error code, and logs. ## Safety Rules - Never recommend repeated retries for signature, balance, or deterministic program errors. - Label heuristic interpretations as inferred. - Redact configurable log patterns before telemetry or display. - Do not submit, sign, or modify transactions. - Do not silently increase slippage, fees, or compute limits. ## Acceptance Checklist - [ ] Works without an IDL - [ ] Decodes supplied Anchor-style error definitions - [ ] Handles missing and malformed logs - [ ] Produces deterministic output for fixtures - [ ] Includes browser and Node builds - [ ] Has no RPC dependency - [ ] Supports custom error resolvers - [ ] Includes redaction tests - [ ] Keeps minified core bundle under 20 KB - [ ] Ships fixtures for at least eight failure categories ## Initial Package Layout ```text packages/core packages/react examples/simulation-panel fixtures/logs ``` **Commercial extension:** hosted error aggregation with release-based regression reports, while keeping local explanation open-source.

# Self-Directed Draft — Solana IDL Change Reporter ## Product **Working name:** `idl-change-report` **Format:** Open-source CLI and CI action **Audience:** Solana program teams publishing Anchor-compatible IDLs ## Problem IDL updates are difficult for integrators to review quickly. A small change to an account, instruction, argument, or error can break clients without being obvious in a raw JSON diff. ## Core Command ```bash idl-change-report \ --base ./idl/v1.json \ --head ./idl/v2.json \ --out ./idl-report.md \ --fail-on breaking ``` ## Required Output The generated Markdown report contains: 1. **Verdict:** breaking, additive, or metadata-only 2. **Instruction changes** 3. **Account changes** 4. **Type and enum changes** 5. **Error-code changes** 6. **Suggested integrator actions** 7. **Machine-readable summary** Example: ```md # IDL Change Report Verdict: BREAKING ## Instructions - `deposit` - Added required argument: `referrer: publicKey` - Account `vault` changed from writable to read-only ## Types - `Position` - Removed field: `rewardsOwed: u64` ## Integrator Actions - Update every `deposit` instruction builder. - Remove reads of `Position.rewardsOwed`. - Regenerate the client before release. ``` ## Classification Rules **Breaking** - Remove or rename an instruction - Add a required instruction argument - Change argument order or type - Remove, rename, reorder, or change an account constraint - Remove a struct field or enum variant - Change a field’s type - Reassign an existing error code **Additive** - Add an instruction - Add an error code - Add a type not referenced by existing instructions - Add an optional field where the IDL format supports it **Metadata-only** - Documentation changes - Formatting changes - Non-functional metadata updates Ambiguous changes must be labeled `REVIEW_REQUIRED`, not guessed. ## Machine-Readable Contract ```json { "verdict": "breaking", "counts": { "breaking": 2, "additive": 0, "reviewRequired": 1 }, "changes": [ { "path": "instructions.deposit.args.referrer", "kind": "required_argument_added", "severity": "breaking" } ] } ``` ## MVP Acceptance Checklist - [ ] Accept two local IDL JSON files - [ ] Validate inputs before comparison - [ ] Produce deterministic Markdown and JSON - [ ] Return exit code `1` at the configured failure threshold - [ ] Explain every breaking classification - [ ] Ignore key ordering and formatting - [ ] Include fixture tests for each classification rule - [ ] Redact nothing because no keys or transaction data are required - [ ] Run without network access ## Launch Copy **Review Solana IDL changes without reading raw JSON diffs.** `idl-change-report` turns two IDLs into a release-ready compatibility report. It flags breaking instruction, account, type, enum, and error-code changes, then tells integrators what requires attention. Designed for local use and CI. Deterministic output, explicit rules, no RPC connection required.

# Self-Directed Draft — Solana RPC Resilience Layer ## Product **Working name:** `rpc-resilience` **Format:** A small TypeScript package that standardizes RPC selection, health checks, retries, and user-safe error states for Solana applications. **Audience:** Solana frontend and backend teams using one or more RPC endpoints. ## Problem Apps often treat RPC calls as interchangeable and immediately retry failures. This can create duplicate requests, confusing UI states, rate-limit pressure, and difficult-to-debug incidents. `rpc-resilience` provides a predictable policy layer without hiding the underlying error. ## Core API ```ts type RpcEndpoint = { id: string; url: string; timeoutMs: number; enabled?: boolean; }; type RpcPolicy = { maxAttempts: number; backoffMs: number[]; healthTtlMs: number; }; type RpcResult<T> = | { ok: true; value: T; endpointId: string; attempts: number } | { ok: false; code: "TIMEOUT" | "RATE_LIMITED" | "UNAVAILABLE" | "INVALID_RESPONSE"; endpointId?: string; attempts: number; retryable: boolean; }; class ResilientRpc { request<T>( method: string, params: unknown[], ): Promise<RpcResult<T>>; health(): Promise<Record<string, "healthy" | "degraded" | "offline">>; } ``` ## Required behavior 1. Apply a timeout to every request. 2. Retry only errors marked retryable. 3. Use bounded backoff rather than an unbounded loop. 4. Avoid retrying non-idempotent application actions automatically. 5. Track endpoint ID, attempt count, latency, and failure code. 6. Keep health status separate from transaction confirmation status. 7. Permit manual endpoint disablement through configuration. 8. Never log wallet secrets, private keys, or full sensitive payloads. ## User-facing state mapping | Internal condition | Suggested UI copy | |---|---| | Temporary RPC failure | “The network connection is temporarily unavailable. Try again.” | | Rate limited | “Too many requests were sent. Please wait a moment.” | | Timeout | “The request took too long to complete.” | | Invalid response | “The service returned an unexpected response.” | | Successful request | Continue normally; do not expose endpoint details by default. | ## Minimal observability event ```json { "event": "rpc_request", "method": "getBalance", "endpointId": "primary", "attempts": 2, "latencyMs": 840, "result": "success" } ``` Implementations should hash or omit account identifiers unless operational debugging explicitly requires them. ## Acceptance checklist - [ ] Every request has a timeout. - [ ] Retry policy is configurable and bounded. - [ ] Non-retryable errors stop immediately. - [ ] Endpoint health can be inspected independently. - [ ] Logs contain no secrets. - [ ] Tests cover timeout, rate limit, malformed response, and endpoint fallback. - [ ] UI copy avoids claiming a transaction succeeded merely because an RPC request succeeded. - [ ] Configuration supports disabling fallback in development.

# Self-Directed Draft — Solana Transaction Recovery Kit ## Product **Working name:** `tx-recovery-kit` **Format:** A reusable frontend component, state machine, and copy set for helping users recover from unclear or failed Solana transactions. **Audience:** Solana apps that submit wallet-signed transactions. ## Problem A transaction can appear stuck, rejected, expired, or completed without the application receiving a clear result. Generic “Something went wrong” messages leave users unsure whether to retry, wait, or avoid repeating an action. ## Core behavior Represent each submission with an explicit state: ```ts type TxState = | "draft" | "awaiting_wallet" | "signed" | "submitted" | "confirming" | "confirmed" | "rejected_by_wallet" | "expired" | "failed" | "unknown"; ``` Every state should expose: ```ts type TxRecoveryView = { state: TxState; title: string; explanation: string; primaryAction?: "retry" | "check_status" | "refresh" | "close"; secondaryAction?: "copy_signature" | "contact_support"; signature?: string; retryPolicy?: "safe" | "review_first" | "do_not_retry"; }; ``` ## Safety rules - Never label a transaction successful based only on wallet approval or local submission. - Never encourage automatic retries for actions that may have executed. - Show the transaction signature when available. - Preserve the user’s original action parameters for review before retrying. - Distinguish wallet rejection, submission failure, confirmation timeout, and confirmed program failure. - Require a fresh status check before offering a retry after an ambiguous result. - Make duplicate-action risk visible for transfers, purchases, and other irreversible actions. ## Suggested copy | State | User-facing copy | |---|---| | Awaiting wallet | “Approve this action in your wallet.” | | Rejected | “Your wallet rejected the request. Nothing was submitted by this app.” | | Submitted | “Your transaction was submitted. We’re checking its result.” | | Confirming | “The network is still processing this transaction.” | | Confirmed | “Transaction confirmed.” | | Expired | “This transaction expired before confirmation. Review the action before retrying.” | | Failed | “The transaction reached the network but did not complete. No retry has been started.” | | Unknown | “We can’t confirm the result yet. Check status before trying again.” | ## Recovery flow 1. Capture the user’s intended action before signing. 2. Record wallet response and signature, if returned. 3. Poll or refresh status using bounded retries. 4. On timeout, move to `unknown`, not `failed`. 5. Provide “Check status” before “Retry.” 6. If retrying, require explicit confirmation and display the action summary again. 7. Keep a small local event log for debugging: - action ID - timestamps - wallet response - signature - observed status - final UI state ## Acceptance checklist - [ ] Every terminal state has human-readable copy. - [ ] Ambiguous outcomes cannot trigger an automatic retry. - [ ] Signature copying works when a signature exists. - [ ] Retry displays the original action for review. - [ ] Wallet rejection is separated from on-network failure. - [ ] Loading states include a clear next step. - [ ] The component works without exposing private keys or sensitive wallet data.

# Self-Directed Draft — Solana Account Change Diff ## Product **Working name:** `account-diff` **Format:** A reusable component and data contract that explains how a Solana account changed after an action. **Audience:** Solana apps involving token transfers, staking, swaps, NFTs, or program interactions. ## Problem Transaction status alone does not explain the user-visible result. Users need a simple comparison of relevant balances and ownership before versus after an action. ## Core Experience After confirmation, show: 1. **What changed** - SOL balance - SPL token balances - NFT or compressed-asset ownership, when supported by the app - Newly created or closed accounts, when relevant 2. **Expected vs. observed** - “You expected to receive 100 TOKEN.” - “Observed: 100 TOKEN received.” - If the app cannot verify a field, label it **Unavailable**, not zero. 3. **Fees and costs** - Network fee - App-defined fee, if known - Rent-related account change, if known 4. **Action state** - Completed - Partially reflected - Could not verify - Failed ## Data Contract ```ts type AssetChange = { mint?: string; symbol?: string; decimals: number; before?: string; after?: string; delta?: string; direction: "increased" | "decreased" | "unchanged" | "unknown"; verification: "observed" | "estimated" | "unavailable"; }; type AccountDiff = { actionLabel: string; status: "complete" | "partial" | "unverified" | "failed"; observedAt?: string; slot?: number; signature?: string; sol?: AssetChange; assets: AssetChange[]; fees: AssetChange[]; notes: string[]; }; ``` ## UI Copy Rules - Use plain language: **“Your balance decreased by…”** - Never describe an unavailable value as zero. - Distinguish **submitted**, **confirmed**, and **observed in the app’s data source**. - If a token symbol is missing, display a shortened mint address. - Put the signature and technical identifiers behind **Details**. - Avoid promising reversibility or finality unless the app has explicitly verified it. ## Example > **Swap complete** > You received **24.8 TOKEN** and spent **0.5 SOL**. > Network fee: **0.000005 SOL** > Status: **Observed** > [View details] ## Acceptance Checklist - [ ] Before/after values use the same decimals. - [ ] Unknown data is represented as unavailable. - [ ] Fees are separated from transfer amounts. - [ ] The UI works when metadata is missing. - [ ] A technical details view includes the signature when available. - [ ] Refreshing the page does not duplicate the diff. - [ ] The component supports partial verification without claiming success.

# Self-Directed Draft — Solana Transaction Intent Receipt ## Product **Working name:** `intent-receipt` **Format:** A reusable UI and data specification for showing users what a Solana transaction is intended to do before and after submission. **Audience:** Wallet-connected Solana apps, especially swaps, mints, staking, and account-management flows. ## Problem A signature prompt exposes transaction mechanics, while the app often fails to clearly state the user’s intended outcome. After signing, users need a compact record of: - What they approved - Which account was used - What changed - Whether the app is still waiting, completed, or needs attention This is separate from raw transaction-error handling: the receipt is an understandable record of intent and outcome. ## Core UX ### 1. Pre-signing summary Display: - **Action:** “Stake SOL,” “Buy 2 items,” or another plain-language verb - **Source account:** shortened address plus wallet label, if available - **Assets involved:** token symbol and amount, with exact value available on expand - **Destination or program purpose:** human-readable label when known - **Estimated network fee:** clearly marked as an estimate - **Risk note:** “Review the wallet prompt before approving” Primary button: **Review in wallet** Secondary action: **Cancel** ### 2. Pending state After submission, show: - Action name - Submission status: `Preparing`, `Awaiting signature`, `Submitted`, or `Confirming` - Copyable transaction identifier when available - A non-blocking option to continue browsing, if the app supports it Avoid claiming success before the application’s chosen confirmation condition is met. ### 3. Completed state Show: - **Completed** badge - Plain-language outcome - Relevant balance or ownership change, if the app can read it - Copyable transaction identifier - **View details** and **Done** actions ### 4. Needs-attention state Show: - What stage stopped - A neutral explanation - Safe next action: retry, reconnect, refresh state, or contact support - The original intent and transaction identifier, if available Do not present a failed attempt as a completed action. ## Suggested data contract ```ts type IntentReceipt = { intentId: string; actionLabel: string; status: | "draft" | "awaiting_signature" | "submitted" | "confirming" | "completed" | "needs_attention" | "cancelled"; sourceAddress?: string; assets?: Array<{ symbol?: string; amount?: string; direction: "in" | "out"; }>; transactionId?: string; createdAt: string; updatedAt: string; nextAction?: string; userMessage?: string; }; ``` ## Acceptance checklist - [ ] Intent is understandable without reading program or instruction names. - [ ] Exact amounts remain accessible without overcrowding the primary view. - [ ] Wallet approval and application confirmation are separate states. - [ ] Every state has one clear next action. - [ ] Transaction identifiers are copyable. - [ ] Success is not shown solely because submission returned. - [ ] Sensitive addresses are shortened visually but preserved for copying. - [ ] The component works on narrow screens. - [ ] The UI remains usable when metadata is unavailable. - [ ] Status updates are accessible to screen readers. ## Recommended microcopy > You’re approving **Stake 1.00 SOL** from **7xK…pQ2**. Review the wallet request before signing. > Submitted. We’re checking whether the action completed. > The action needs attention. No completion was shown. You can refresh the account state or try again.

# Self-Directed Draft — Solana Transaction Failure Triage Panel ## Product **Working name:** `tx-triage-panel` **Format:** Embeddable UI component and error-handling specification **Audience:** Solana dApps that submit user transactions ## User Problem A failed transaction often leaves users unsure whether to retry, reconnect, adjust inputs, or wait. The app should translate technical failure signals into a clear next action without exposing sensitive transaction data. ## Core Experience After submission, show a compact status panel with four states: 1. **Preparing** — transaction is being built or simulated. 2. **Awaiting signature** — user action is required in the wallet. 3. **Processing** — transaction was submitted; confirmation is pending. 4. **Action needed** — the app has identified a likely recovery step. ### Example action messages | Signal | User-facing message | Primary action | |---|---|---| | User rejected signature | “Signature canceled.” | `Try again` | | Blockhash expired | “The request took too long and expired.” | `Build a fresh transaction` | | Insufficient balance | “Your balance may not cover this transaction and its fee.” | `Review balance` | | Account/input missing | “This account is not ready for this action.” | `Refresh and retry` | | Confirmation timeout | “We’re still waiting for network confirmation.” | `Check status` | | Unknown error | “Something went wrong while processing this request.” | `Retry safely` | ## Component Requirements - Display a short status label and plain-language explanation. - Preserve the user’s intended action where safe, but rebuild transactions before retrying when recent block data may be stale. - Disable duplicate submission while a request is in flight. - Provide a details disclosure containing: - operation name, - current stage, - sanitized error category, - request timestamp, - optional transaction signature. - Never expose private keys, seed phrases, or raw wallet payloads. - Keep error copy stable enough for support documentation and localization. ## Retry Rules - **Safe retry:** user rejection, temporary confirmation timeout, expired blockhash. - **Confirm before retry:** insufficient funds, invalid amount, missing account, program rejection. - **Do not loop automatically:** unknown errors or repeated failures. - After two failed retries, suggest checking the app status or contacting support rather than repeating indefinitely. ## Acceptance Checklist - [ ] Every transaction stage has a visible state. - [ ] Wallet rejection is distinct from program failure. - [ ] Duplicate clicks cannot submit the same intent concurrently. - [ ] Expired transactions are rebuilt, not blindly resent. - [ ] Technical details are available without overwhelming the default view. - [ ] Retry behavior is tested for slow, rejected, and failed requests. - [ ] Error messages avoid claiming success before confirmation. - [ ] The panel works on mobile wallet browsers.

# Self-Directed Draft — Solana RPC Failure UX Specification ## Product **Working name:** `rpc-resilience-kit` **Format:** Frontend component pattern plus implementation checklist **Audience:** Solana wallet-connected apps, dashboards, and transaction flows ## Problem When an RPC request fails, users often see a generic error even though the cause may be temporary network latency, a stale blockhash, rate limiting, or an unavailable endpoint. Teams need a consistent way to explain failures without exposing sensitive data or pretending a transaction succeeded. ## Core Behavior The component receives: ```ts type RpcFailureState = { operation: "read" | "simulate" | "send" | "confirm"; message: string; retryable: boolean; signature?: string; requestId?: string; occurredAt: string; }; ``` It renders: 1. **Plain-language status** - “We couldn’t load this data.” - “Your transaction was not confirmed yet.” - “The wallet request was rejected.” 2. **Next action** - Retry - Reconnect wallet - Check transaction status - Copy diagnostic details - Contact support 3. **Safety boundary** - Never display “Success” solely because a transaction was submitted. - Never ask users to resubmit when the first transaction’s final state is unknown without first offering a status check. - Never expose private keys, seed phrases, or full wallet payloads. ## Recommended State Model ```text idle → requesting → submitted → confirming → confirmed requesting → failed_retryable requesting → failed_terminal submitted → confirmation_unknown confirming → confirmation_unknown ``` `confirmation_unknown` must provide a status-check action before showing a resubmit action. ## Diagnostic Copy **Retryable read failure** > This data could not be loaded. Try again, or reconnect your wallet if the problem continues. **Unknown transaction result** > We sent the transaction request, but confirmation is taking longer than expected. Check its status before trying again. **Terminal failure** > The transaction was not completed. Review the wallet message and try again only if the details are correct. **Copy diagnostics** > Copy non-sensitive details for support Include only: ```json { "operation": "confirm", "clusterLabel": "configured by the app", "requestId": "optional", "signature": "optional", "errorCode": "app-defined", "timestamp": "ISO-8601" } ``` ## Acceptance Checklist - [ ] Every RPC action has loading, success, and failure states. - [ ] Unknown confirmation status is distinct from failure. - [ ] Retry behavior prevents accidental duplicate submissions. - [ ] Errors include a user action, not only a technical message. - [ ] Diagnostic output excludes secrets and raw authorization payloads. - [ ] Copy works with keyboard navigation and screen readers. - [ ] App logs correlate errors using a non-sensitive request ID. - [ ] The UI can be tested with mocked timeout, rejection, and delayed-confirmation cases. - [ ] Cluster/environment labeling comes from configuration, not guessed text. ## Success Criterion A first-time user can tell whether to retry, wait, reconnect, or check transaction status without needing an engineer to interpret the error.

# Self-Directed Draft — Solana Wallet Integration QA Checklist ## Purpose A reusable pre-release checklist for applications that connect to Solana wallets, request signatures, submit transactions, and display confirmation status. ## Release Gate Ship only when every **blocking** item is checked or explicitly waived by the owner. ### 1. Connection - [ ] App identifies the active wallet and public key. - [ ] Disconnecting the wallet clears account-specific UI state. - [ ] Reconnecting restores the correct account state. - [ ] Switching accounts refreshes balances, permissions, and available actions. - [ ] Unsupported wallet states show a recoverable message. - [ ] The app does not assume a wallet is available before checking. ### 2. Network and Cluster - [ ] The app displays the intended Solana cluster or environment. - [ ] Wallet network mismatch is detected before signing. - [ ] Cluster-dependent addresses and configuration are environment-specific. - [ ] Test and production configuration cannot be selected accidentally. - [ ] RPC errors do not get presented as wallet rejection messages. ### 3. Transaction Construction - [ ] Every transaction has an explicit fee payer. - [ ] Recent blockhash or durable nonce handling is defined. - [ ] Required accounts are validated before prompting for a signature. - [ ] Amounts use integer base units internally. - [ ] User-facing amounts are formatted without changing transaction values. - [ ] The app prevents duplicate submission from repeated clicks. - [ ] Transaction size and compute requirements are tested for representative cases. ### 4. User Consent - [ ] The UI explains the intended action before signing. - [ ] Token, SOL, account, and recipient details are shown where applicable. - [ ] Sign and submit actions are visually distinct when both are used. - [ ] Rejected signatures return the user to a safe, usable state. - [ ] No signature request occurs from an unexpected navigation or background event. ### 5. Submission and Confirmation - [ ] Submission status distinguishes: not started, signing, submitted, confirming, confirmed, failed, and unknown. - [ ] A signature is preserved for support and status lookup. - [ ] Confirmation uses an explicitly chosen commitment level. - [ ] Timeouts do not automatically imply failure. - [ ] Retry behavior cannot create unintended duplicate actions. - [ ] The UI provides a safe recovery path for an unknown result. ### 6. Error Handling - [ ] Wallet rejection, insufficient funds, expired blockhash, simulation failure, RPC failure, and program error have separate user-facing messages. - [ ] Raw technical details are available for support without overwhelming users. - [ ] Sensitive wallet or account data is not logged. - [ ] Error messages include the next action the user can take. - [ ] Failed attempts leave no stale “success” state in the UI. ### 7. Testing Matrix Test at minimum: - [ ] Fresh connection - [ ] Reconnection after refresh - [ ] Account switch - [ ] Wallet rejection - [ ] Insufficient balance - [ ] Expired transaction - [ ] RPC timeout - [ ] Program-level failure - [ ] Double-click or repeated submission - [ ] Mobile or narrow-screen layout - [ ] Production-like configuration with test funds only ## Release Record - **Application/version:** - **Cluster/environment:** - **Wallets tested:** - **Known limitations:** - **Blocking waivers:** - **Owner:** - **Test date:** - **Evidence links or artifacts:**

# Self-Directed Draft — Solana Transaction Debug Bundle Specification ## Product **Working name:** `tx-bundle` **Format:** Open-source CLI and JSON schema **Audience:** Solana application developers and support teams ## Problem Transaction incidents often arrive as screenshots or vague reports. Engineers then spend time requesting signatures, cluster details, wallet versions, logs, and reproduction steps. Raw diagnostics may also expose RPC credentials or user data. ## Proposed CLI ```bash tx-bundle collect \ --signature <SIGNATURE> \ --rpc <RPC_URL> \ --output incident.zip ``` The tool creates a portable, sanitized evidence bundle for debugging one transaction. ## Bundle Contents ```text incident.zip ├── manifest.json ├── transaction.json ├── status.json ├── logs.txt ├── environment.json ├── reproduction.md └── redaction-report.json ``` ### `manifest.json` ```json { "schemaVersion": "1.0.0", "createdAt": "<ISO-8601>", "cluster": "<user-supplied-or-detected>", "signature": "<transaction-signature>", "collectionStatus": "complete|partial|failed", "missingArtifacts": [] } ``` ### `environment.json` Include only explicitly supplied data: - Application name and version - Wallet name and version - Browser, operating system, or runtime - Expected user action - Whether the issue is reproducible - Optional incident identifier ## Required Behavior 1. Fetch transaction, status, and available execution logs. 2. Preserve raw RPC responses without interpreting the root cause. 3. Remove RPC query strings, authorization headers, cookies, file paths, and configured secrets. 4. Never request or store seed phrases, private keys, or signing material. 5. Mark unavailable artifacts instead of silently omitting them. 6. Generate a human-editable reproduction template. 7. Work in offline assembly mode for teams that provide saved JSON manually. ## Safety Defaults - Display the files to be included before archive creation. - Require confirmation when unknown fields resemble credentials. - Replace redacted values with typed markers such as `<REDACTED_RPC_TOKEN>`. - Record each redaction category, but not the removed value. - Warn that account addresses and transaction signatures may still be public identifiers. ## Example `reproduction.md` ```md # Incident Summary Expected result: Actual result: ## Steps 1. 2. 3. ## Frequency [ ] Once [ ] Intermittent [ ] Every attempt ## Additional Context Wallet: Application version: Approximate local time: ``` ## Acceptance Criteria - A developer can create a bundle with one command and a signature. - Partial RPC results still produce a valid archive. - Automated tests confirm configured secrets never appear in output. - The manifest validates against a published JSON Schema. - Exit codes distinguish collection failure, validation failure, and successful partial collection. - The archive can be inspected without running the tool. ## Initial Scope Boundary Do not diagnose failures, replay transactions, sign messages, modify accounts, or upload bundles. The first release should focus on deterministic collection, redaction, and handoff.

# Self-Directed Draft — Solana RPC Changeover Runbook ## Purpose A reusable runbook for changing Solana RPC providers, endpoints, or routing policies without silently degrading reads, transaction submission, confirmations, or observability. ## Scope Use this before: - Replacing a primary RPC endpoint - Adding a fallback provider - Moving between public and private infrastructure - Changing commitment, timeout, or retry settings - Introducing geographic or workload-based routing ## Change record - **Change owner:** - **Planned window:** - **Affected environments:** dev / staging / production - **Current endpoint configuration:** - **New endpoint configuration:** - **Rollback method:** - **Escalation contact:** ## Pre-change checklist ### Configuration - [ ] Endpoint URLs and credentials are stored outside source code. - [ ] The application can distinguish read failures from submission failures. - [ ] Timeouts are explicit and documented. - [ ] Retry behavior uses bounded attempts and backoff. - [ ] Retries do not blindly duplicate transaction submissions. - [ ] Commitment levels are documented for each critical read. - [ ] Rate limits and request quotas are recorded. - [ ] The rollback configuration is prepared and tested. ### Compatibility - [ ] `getLatestBlockhash` and related expiration handling are supported. - [ ] Transaction simulation works with the new endpoint. - [ ] Versioned transactions and address lookup tables are supported if required. - [ ] WebSocket subscriptions are tested separately from HTTP requests. - [ ] The application handles provider-specific error formats. - [ ] Health checks verify useful Solana responses, not merely TCP connectivity. ### Test plan Record results for both the current and new endpoint: | Test | Result | Notes | |---|---|---| | Fetch cluster health | | | | Fetch recent blockhash | | | | Read a known account | | | | Simulate a representative transaction | | | | Submit a controlled test transaction | | | | Confirm the transaction | | | | Open and close a WebSocket subscription | | | | Exercise timeout and retry behavior | | | ## Change procedure 1. Enable endpoint selection through configuration or a feature flag. 2. Route a limited, observable portion of traffic to the new endpoint. 3. Compare request errors, latency, blockhash freshness, simulation results, and confirmation outcomes. 4. Increase traffic only after the predefined acceptance thresholds are met. 5. Keep the previous endpoint available during the observation period. 6. Record timestamps, configuration versions, and unexpected behavior. ## Rollback triggers Rollback when any of these occur: - Sustained request failures exceed the team’s defined threshold. - Transaction submission succeeds inconsistently across endpoints. - Confirmation handling produces false failures or duplicate attempts. - Required account or program data is stale, incomplete, or unavailable. - Rate limiting materially affects critical workflows. - WebSocket-dependent features fail without an acceptable fallback. ## Post-change review - [ ] Final endpoint configuration is documented. - [ ] Old credentials and unused routes are removed or disabled. - [ ] Dashboards and alerts reference the active route. - [ ] Runbook results and anomalies are archived. - [ ] Rollback remains possible until the change is formally closed. - [ ] Follow-up actions have owners and due dates. ## Definition of done The change is complete when critical read, simulate, submit, confirm, subscription, timeout, and rollback paths have documented results, and the team can identify the active endpoint and restore the previous configuration without code changes.

# Self-Directed Draft — Solana Failure-Signal Dictionary ## Product specification **Working name:** `solana-failure-signals` **Format:** Versioned Markdown file with optional JSON representation **Audience:** Solana developers, support teams, QA engineers, and observability-tool builders ### Problem Solana failures are often described with inconsistent labels such as “reverted,” “stuck,” or “RPC error.” A shared vocabulary can make dashboards, tickets, and runbooks easier to interpret without hiding the underlying evidence. ### Core artifact Each signal entry uses this schema: ```yaml id: string canonical_label: string plain_language: string layer: client | rpc | transaction | program | wallet | unknown evidence_to_capture: - string do_not_infer: - string next_action: - string severity: informational | warning | blocking owner: client | infrastructure | program | wallet | unknown ``` ### Starter dictionary ```yaml - id: submission_no_result canonical_label: Submission outcome unknown plain_language: The client sent a request but does not yet have a confirmed outcome. layer: client evidence_to_capture: - client timestamp - request identifier, if available - raw error or timeout text - whether retry occurred do_not_infer: - that the transaction failed - that the transaction was accepted next_action: - check the client and RPC request logs - avoid duplicate submission until status is clarified severity: warning owner: client - id: simulation_rejected canonical_label: Simulation rejected plain_language: Preflight simulation returned an error before normal submission flow completed. layer: transaction evidence_to_capture: - complete simulation error - logs, if returned - transaction message or instruction summary - simulation configuration do_not_infer: - that the same result would occur under every execution context - that funds were moved next_action: - preserve the raw simulation response - isolate the failing instruction or account assumption severity: blocking owner: client - id: program_error_unclassified canonical_label: Program error — classification pending plain_language: A program-related error was observed, but its meaning has not been mapped to a known program-specific condition. layer: program evidence_to_capture: - raw logs - program identifier - instruction index - decoded error, if available do_not_infer: - the user-facing cause from the numeric code alone next_action: - consult the program’s documented error mapping - attach the raw evidence to the issue severity: blocking owner: program ``` ### Operating rules 1. Store the raw signal beside the canonical label. 2. Never replace “unknown” with a guessed cause. 3. Add a program-specific mapping only with source-code, documentation, or team confirmation. 4. Record timestamps and environment details consistently. 5. Version dictionary changes so support reports remain interpretable. ### Acceptance criteria - Every label has an explicit evidence list. - Unknown outcomes remain distinguishable from confirmed failures. - Entries identify a likely owner without assigning blame. - The Markdown and JSON forms produce equivalent fields. - A reviewer can classify a new incident without deleting raw error text.

# Self-Directed Draft — Solana Transaction Reproduction Card ## Product specification **Working name:** `tx-repro-card` **Format:** Markdown template plus optional JSON export **Audience:** Solana support teams, QA engineers, wallet developers, and users reporting failed transactions ### Problem Transaction reports often omit the exact inputs needed to reproduce a failure. Teams lose time asking for signatures, screenshots, wallet versions, cluster details, and expected outcomes one message at a time. `tx-repro-card` turns a report into a compact, privacy-aware handoff artifact. ## Required fields ```yaml report_id: "" reported_at_utc: "" reporter_contact: "" cluster: "mainnet-beta | devnet | testnet | localnet | unknown" transaction_signature: "" wallet_or_client: "" wallet_version: "" app_name: "" app_version: "" action_attempted: "" expected_result: "" observed_result: "" user_visible_error: "" rpc_endpoint_label: "" reproduction_frequency: "always | intermittent | once | unknown" ``` ## Evidence fields ```yaml preflight_simulation_attempted: false simulation_result: "" simulation_logs: [] confirmed_transaction_status: "" transaction_error: "" account_or_program_addresses: - "" relevant_slot: "" screenshots_or_recordings: - filename: "" redacted: false additional_notes: "" ``` ## Privacy rules Before sharing a card: - Remove seed phrases, private keys, access tokens, cookies, and auth headers. - Redact personal names, email addresses, IP addresses, and private RPC URLs. - Share only addresses and signatures needed to investigate. - Mark screenshots as `redacted: true` only after reviewing them manually. - Never request a user’s secret recovery phrase. ## Copy-ready report template ```markdown ## Transaction Reproduction Card - Report ID: - Reported at (UTC): - Cluster: - App / version: - Wallet / version: - Action attempted: - Expected result: - Observed result: - Exact user-visible error: - Transaction signature: - Reproduction frequency: - Simulation attempted: - Simulation result: - Transaction status: - Transaction error: - Relevant program/account addresses: - Relevant slot: - Attached evidence: - Redactions completed: - Investigator notes: ``` ## Triage labels Use one primary label: - `INPUT_MISMATCH` — supplied values differ from the expected interface - `ACCOUNT_STATE` — required account data is missing or incompatible - `AUTHORIZATION` — signer or permission requirement failed - `COMPUTE_OR_SIZE` — execution budget or transaction size issue - `RPC_OR_TRANSPORT` — submission or availability issue - `PROGRAM_ERROR` — program returned an application-level error - `UNCLASSIFIED` — insufficient evidence ## Acceptance criteria A card is ready for engineering review when it contains: 1. Cluster and app/client version. 2. Action attempted and expected outcome. 3. Exact observed error or status. 4. Signature, if a transaction was submitted. 5. Reproduction frequency. 6. Confirmation that secrets and private data were removed. ## Suggested workflow 1. Reporter fills the card from the app’s error state. 2. Support validates redactions and assigns a triage label. 3. Engineering reproduces using the recorded cluster, versions, inputs, and evidence. 4. Any conclusion is appended under **Investigator notes** with its evidence source. 5. The final card is stored with the issue for future regression testing.

# Self-Directed Draft — Solana Integration Compatibility Manifest ## Product specification **Working name:** `solana-compat-manifest` **Format:** A versioned Markdown/JSON artifact generated and reviewed alongside each Solana program integration **Audience:** Solana app teams, SDK maintainers, QA engineers, and support staff ### Problem An integration can break even when a program deploys successfully: account layouts change, required signers shift, instruction arguments are renamed, or clients rely on an outdated program ID. Teams need a compact, reviewable record of what an integration expects and what changed between releases. ### Core deliverable Each integration owns a manifest with: ```yaml manifestVersion: 1 integration: "example-feature" program: address: "<program-id>" cluster: "devnet|testnet|mainnet-beta" sourceRef: "<commit-or-release>" interfaceRef: "<idl-or-interface-version>" instructions: - name: "exampleInstruction" accounts: - name: "authority" signer: true writable: false - name: "state" signer: false writable: true arguments: - name: "amount" type: "u64" expectedErrors: - "Unauthorized" computeBudget: expectedUnits: "<number-or-unknown>" accounts: - name: "state" owner: "<program-id>" sizeBytes: "<number-or-variable>" seeds: ["state", "<authority>"] compatibility: breakingChanges: [] migrationRequired: false verification: generatedAt: "<timestamp>" reviewedBy: "<team-or-role>" ``` ### Review rules A pull request must be flagged for review when it changes: - Program address or cluster - Instruction account order, signer status, or writability - Argument names, order, or types - PDA seeds, bump handling, or account ownership - Account size or serialization format - Expected error codes - Compute-budget assumptions - Interface or source reference ### CI checks 1. Parse the manifest. 2. Compare it with the previous version. 3. Produce a human-readable diff. 4. Label changes as **non-breaking**, **review-required**, or **migration-required**. 5. Fail only when a breaking change lacks an explicit migration note. 6. Store the manifest with the client release artifact. ### Acceptance criteria - A new engineer can identify the program, cluster, interface version, and required signers in under two minutes. - Every instruction lists accounts in the order supplied by the client. - Any changed PDA seed or account layout produces a visible warning. - The same manifest can render as Markdown for review and JSON for tooling. - Unknown values are marked `unknown`, never silently omitted. - The artifact contains no private keys, seed phrases, or user wallet data. ### Suggested output ```text Compatibility report ──────────────────── Status: REVIEW REQUIRED Changed: state account size Migration note: MISSING Changed: authority signer flag Risk: client authorization behavior may differ Action: add migration guidance and obtain reviewer approval ``` ### Minimal rollout Start with one integration and manual manifest maintenance. Add automated comparison after the schema stabilizes. The first success metric is not deployment volume; it is whether reviewers can detect interface drift before a client release.

# Self-Directed Draft — Solana Instruction Contract Review Sheet **Purpose:** A reusable worksheet for reviewing a client’s interaction with a Solana program before release. Focuses on instruction arguments, account metadata, PDA derivation, and failure-safe behavior. ## Review record - **Feature / instruction:** ____________________ - **Client package or module:** ____________________ - **Program ID source:** ____________________ - **IDL or interface version:** ____________________ - **Reviewer / date:** ____________________ ## 1. Instruction contract - [ ] Instruction name is identical across client code, interface definitions, and documentation. - [ ] Every argument has an explicit type, serialization format, and example value. - [ ] Integer widths and signedness are documented. - [ ] Optional values define how “missing” is encoded. - [ ] Enum variants are listed in a stable order. - [ ] Client rejects invalid arguments before building a transaction. - [ ] Amount fields state their unit and decimal handling. ## 2. Account metadata For every account, record: | Account | Signer? | Writable? | PDA? | Expected owner | Creation path | |---|---:|---:|---:|---|---| | __________ | ☐ | ☐ | ☐ | __________ | __________ | Acceptance checks: - [ ] Account order matches the program interface. - [ ] Signer and writable flags are intentional. - [ ] Required accounts cannot silently be substituted. - [ ] Optional accounts have a defined behavior when omitted. - [ ] Client-side checks identify missing or incorrectly typed accounts. - [ ] Newly created accounts specify payer, space, and ownership expectations. ## 3. PDA derivation For each PDA: - **Label:** ____________________ - **Seeds, in order:** ____________________ - **Byte encoding per seed:** ____________________ - **Program ID used:** ____________________ - **Bump handling:** ____________________ - [ ] Seed ordering is covered by a test. - [ ] Text seeds use a documented encoding. - [ ] Public keys are converted to bytes consistently. - [ ] Numeric seeds define endianness and width. - [ ] The client does not hard-code a PDA that should be derived. - [ ] A wrong-network or wrong-program configuration cannot produce a misleading address. ## 4. Transaction construction - [ ] Recent block reference is acquired at submission time. - [ ] Compute-budget instructions, if used, are explicit and configurable. - [ ] Fee payer is clearly identified. - [ ] Multiple instructions document ordering requirements. - [ ] Duplicate instructions are prevented where unsafe. - [ ] The client exposes the assembled transaction for debugging before signing. - [ ] Retry behavior distinguishes rebuilding from resubmitting an unchanged transaction. ## 5. Test cases - [ ] Valid instruction with minimum permitted values. - [ ] Valid instruction with representative larger values. - [ ] Missing required account. - [ ] Incorrect signer flag. - [ ] Incorrect writable flag. - [ ] Wrong PDA seed or bump. - [ ] Invalid argument type or boundary value. - [ ] User rejects signing. - [ ] Submission response is delayed or unavailable. - [ ] Confirmation is unresolved and the UI avoids claiming success. ## Release gate **Approve only if:** 1. Every account and argument is documented. 2. PDA derivation has deterministic tests. 3. Invalid inputs fail before signing. 4. Transaction status messages distinguish built, signed, submitted, confirmed, and failed states. 5. The review record is attached to the feature or release ticket. **Open risks / follow-ups:** __________________________________________________ __________________________________________________

# Self-Directed Draft — Solana Transaction Failure Triage Panel ## Product specification **Working name:** `tx-lens` **Format:** Lightweight SDK component plus optional CLI report **Audience:** Solana app teams, support engineers, and QA contributors ### Problem When a Solana transaction fails, users often see only a generic error. Teams need a consistent way to capture the transaction lifecycle, classify likely failure points, and provide a safe next action without exposing secrets or pretending that a retry will succeed. ### Goal Turn opaque transaction errors into a structured, user-readable report based only on locally available request, simulation, and submission data. ## Core workflow 1. Record transaction intent: - Network label configured by the app - Fee payer public key - Recent blockhash presence - Instruction labels supplied by the app - Transaction version 2. Optionally run a simulation before submission. 3. Submit the transaction. 4. Poll or fetch status using the app’s configured commitment. 5. Render a failure classification and recommended next step. ## Failure categories - **Wallet/signing:** user rejected, wallet unavailable, or signature missing - **Build/serialization:** malformed instruction, unsupported transaction format, or encoding failure - **Simulation:** program error, insufficient balance, invalid account state, or compute-related failure - **Submission:** RPC request rejected, timeout, or transport interruption - **Confirmation:** submitted but not confirmed within the configured wait window - **Unknown:** insufficient evidence; show raw redacted diagnostics ## Required report fields ```text status category human_message next_action transaction_signature (if available) fee_payer instruction_labels simulation_logs (redacted) rpc_error_code (if available) attempted_at ``` Never collect private keys, seed phrases, wallet adapter secrets, or full authorization headers. ## UX copy **Simulation failure** “Your transaction was checked but could not execute. Review the highlighted instruction or try again after updating the account state.” **Confirmation timeout** “The submission did not reach the expected confirmation window. Check transaction status before retrying to avoid duplicate actions.” **Insufficient evidence** “We couldn’t determine the cause from the available response. Copy diagnostics for the support team.” ## Acceptance checklist - [ ] Every failure maps to one primary category. - [ ] Raw errors are preserved separately from user-facing copy. - [ ] Sensitive fields are redacted before logging. - [ ] Retry controls explain what will be retried. - [ ] A timeout does not automatically imply failure. - [ ] Reports can be exported as JSON. - [ ] Tests cover rejected signing, simulation failure, RPC timeout, and delayed confirmation. - [ ] The component works when simulation data is unavailable. ## Success measure A support engineer can receive one exported report and identify whether the next step is to correct the transaction, inspect account state, check the endpoint, or avoid an unsafe retry.

# Self-Directed Draft — Solana Wallet Integration Acceptance Checklist **Use case:** A reusable review sheet for teams integrating wallet connection, signing, and transaction submission into a Solana application. ## 1. Connection and account state - [ ] App clearly shows whether a wallet is connected. - [ ] Public key is displayed in a shortened, copyable format. - [ ] Account changes refresh balances, permissions, and displayed ownership. - [ ] Disconnecting removes session-specific UI state. - [ ] The app handles a wallet becoming unavailable mid-session. - [ ] Network or cluster configuration is visible to the user. - [ ] The app does not treat a displayed public key as proof that a signature was produced. ## 2. Transaction construction - [ ] Every instruction has an explicit purpose documented in code. - [ ] Account roles are identified as signer, writable, or read-only. - [ ] User-controlled values are validated before instruction creation. - [ ] Amounts use integer base units rather than floating-point arithmetic. - [ ] The app checks that the intended owner or authority matches the connected account. - [ ] Transactions are rebuilt when required blockhash or fee metadata expires. - [ ] Unsupported transaction versions fail with an actionable message. ## 3. User consent - [ ] The confirmation screen states what action will occur. - [ ] Destination accounts and token amounts are visible where applicable. - [ ] Fees or expected costs are presented before signing when available. - [ ] The app does not request a signature merely to load ordinary page content. - [ ] Rejected signatures return the user to a recoverable state. - [ ] The UI distinguishes “signature rejected,” “submission failed,” and “confirmation pending.” ## 4. Submission and confirmation - [ ] The signed payload is submitted only to the configured endpoint. - [ ] Submission errors preserve enough context for support diagnostics without exposing secrets. - [ ] Confirmation uses an explicit commitment policy selected by the product. - [ ] Timeouts do not automatically imply that a transaction failed. - [ ] The app provides a retry path that avoids accidental duplicate actions. - [ ] Final UI state is based on fetched chain state, not only local optimism. - [ ] A transaction identifier is shown only after the application receives one. ## 5. Safety and privacy - [ ] Private keys, seed phrases, and raw signing material never enter application logs. - [ ] Sensitive payloads are excluded from analytics and error-reporting events. - [ ] Explorer or RPC URLs are configurable rather than silently hard-coded. - [ ] External links are generated from validated transaction identifiers. - [ ] The app warns before irreversible or high-impact actions. - [ ] Error messages avoid instructing users to paste secrets into support channels. ## 6. Test matrix Run each scenario against the supported wallet and cluster combinations: - [ ] No wallet installed - [ ] Wallet locked - [ ] User rejects connection - [ ] User rejects signing - [ ] Account changes before signing - [ ] Network mismatch - [ ] Expired blockhash - [ ] Insufficient funds - [ ] Duplicate submission - [ ] RPC timeout - [ ] Confirmation delay - [ ] Malformed or unexpected account data ## Release gate Ship only when every unchecked item has either: 1. a documented reason it does not apply, or 2. an assigned owner and tracked remediation. **Suggested artifact:** store completed checklists beside the integration code, with wallet, cluster, application version, and test date recorded.

# Self-Directed Draft — Solana RPC Compatibility Probe ## Product Specification **Working name:** `rpc-ready` **Format:** TypeScript CLI with JSON output **Audience:** Solana application, wallet, infrastructure, and QA teams ### Problem Applications may rely on RPC methods, transaction versions, commitment levels, or response fields that differ across endpoints. Misconfigurations are often discovered only after release. ### Product `rpc-ready` runs a configurable, non-destructive compatibility suite against a Solana RPC endpoint and produces a machine-readable readiness report. ```bash npx rpc-ready \ --endpoint "$SOLANA_RPC_URL" \ --profile wallet \ --output report.json ``` ### MVP Checks - Endpoint connectivity and request timeout - `getHealth` response - Genesis hash matches an expected value, when configured - Supported transaction-version behavior - Required RPC methods respond without “method not found” - Configured commitment levels are accepted - Batch-request support - WebSocket connection and subscription setup - Response-shape validation for required fields - Optional latency sampling across five requests - Secret-safe reporting that excludes endpoint query parameters No check should submit transactions or modify chain state. ### Configuration ```yaml profile: wallet timeoutMs: 5000 expectedGenesisHash: null requiredMethods: - getLatestBlockhash - getBalance - getTokenAccountBalance commitments: - confirmed requireWebSocket: true maxP95LatencyMs: 800 ``` ### Output Contract ```json { "status": "fail", "endpoint": "https://rpc.example/[redacted]", "startedAt": "2026-01-01T12:00:00Z", "checks": [ { "id": "rpc.getLatestBlockhash", "status": "pass", "latencyMs": 142, "message": "Method returned the required response shape" }, { "id": "websocket.connect", "status": "fail", "message": "Connection exceeded 5000 ms" } ], "summary": { "passed": 8, "warned": 1, "failed": 1 } } ``` ### Exit Codes - `0`: all required checks passed - `1`: one or more required checks failed - `2`: invalid configuration or CLI usage - `3`: probe could not start ### Safety Requirements - Redact credentials, tokens, and URL query strings. - Never print full RPC responses by default. - Use read-only methods in the built-in profiles. - Cap retries and overall execution time. - Mark latency results as samples, not guarantees. ### Acceptance Criteria 1. A user can run the probe with only an endpoint. 2. CI can fail based on the process exit code. 3. JSON output conforms to a published schema. 4. Each failure identifies the check, reason, and suggested remediation. 5. Unit tests mock all network requests. 6. Integration tests can target a user-supplied endpoint. 7. The default run performs no signing or state changes. ### Initial Profiles - **wallet:** balances, blockhashes, token-account reads, WebSocket - **indexer:** block and transaction retrieval methods - **minimal:** health, identity, version, and latency - **custom:** configuration-defined method requirements ### Positioning Copy > Validate an RPC endpoint before your users do. `rpc-ready` turns application requirements into a repeatable, secret-safe preflight check for local development and CI.

# Self-Directed Draft — Solana Transaction Fixture Kit ## Product Specification **Working name:** `tx-fixture` **Format:** TypeScript package and CLI **Audience:** Solana wallet, application, SDK, and QA teams ### Problem Transaction tests often depend on live RPC state, temporary blockhashes, and mutable accounts. This makes failures difficult to reproduce and CI suites unreliable. ### Product `tx-fixture` captures the inputs required to reconstruct a transaction test locally, sanitizes sensitive fields, and stores them as a portable JSON fixture. It does not retain private keys or submit transactions. ### Core Commands ```bash # Capture public account state and transaction structure tx-fixture capture \ --transaction ./unsigned.tx \ --rpc "$SOLANA_RPC_URL" \ --out fixtures/swap.json # Inspect fixture contents tx-fixture inspect fixtures/swap.json # Validate schema and integrity hashes tx-fixture verify fixtures/swap.json # Load fixture into a test tx-fixture generate-test fixtures/swap.json \ --framework vitest \ --out tests/swap.fixture.test.ts ``` ### Fixture Schema ```json { "version": 1, "clusterHint": "custom", "capturedAt": "ISO-8601 timestamp", "transaction": { "encoding": "base64", "data": "<unsigned-or-sanitized-transaction>", "recentBlockhash": "<replaceable>" }, "accounts": [ { "address": "<public-key>", "owner": "<program-id>", "lamports": 0, "executable": false, "rentEpoch": 0, "data": { "encoding": "base64", "value": "<account-data>" } } ], "programs": ["<program-id>"], "redactions": [], "integrity": { "algorithm": "sha256", "digest": "<fixture-digest>" } } ``` ### Required Behavior - Reject transactions containing embedded secret-key material. - Capture only accounts referenced by the transaction unless explicitly added. - Replace expired blockhashes during test setup. - Preserve account owner, data, lamports, and executable status. - Sort accounts deterministically before hashing. - Support a `--redact ADDRESS` option that substitutes a stable placeholder. - Never broadcast, sign, or modify remote state. - Produce actionable errors for missing accounts, malformed data, and unsupported transaction versions. ### TypeScript API ```ts import { loadFixture, createTestContext } from "tx-fixture"; const fixture = await loadFixture("fixtures/swap.json"); const context = await createTestContext(fixture); const result = await context.simulate(); expect(result.err).toBeNull(); ``` ### MVP Acceptance Checklist - [ ] Legacy and versioned transaction parsing - [ ] Address lookup table account capture - [ ] Deterministic fixture serialization - [ ] Integrity verification - [ ] Secret-pattern safety scan - [ ] Vitest test generator - [ ] Offline inspection mode - [ ] Clear documentation for fixture review and redaction - [ ] Example fixtures using synthetic accounts only - [ ] CI exits nonzero when a fixture is invalid ### Positioning Copy > Turn fragile Solana transaction tests into reviewable, repeatable fixtures. Capture public inputs once, sanitize them, and reproduce failures without depending on live account state.

# Self-Directed Draft — Solana Error Decoder Registry ## Product Specification **Working name:** `solerr` **Format:** Open-source package, CLI, and generated JSON registry **Audience:** Solana application, SDK, support, and developer-relations teams ### Problem Solana transaction failures often expose numeric custom program errors without a useful explanation. Developers must locate the correct program source or IDL, translate hexadecimal values, and determine whether the message applies to the deployed version. ### Product `solerr` converts raw transaction errors into structured, actionable diagnostics using local IDLs and a versionable community registry. ```bash solerr decode \ --program <PROGRAM_ID> \ --error "custom program error: 0x1771" ``` Example output: ```text Program: <PROGRAM_ID> Code: 6001 (0x1771) Name: SlippageExceeded Message: Swap output did not meet the configured minimum. Suggested checks: - Compare quoted and submitted minimum output. - Check token decimals. - Refresh stale route or price inputs. Source: local IDL Confidence: exact ``` ### MVP Requirements 1. Parse decimal, hexadecimal, JSON-RPC, simulation, and common log error formats. 2. Match errors by program address—not error code alone. 3. Load Anchor-compatible IDLs from a file or directory. 4. Return human-readable text and machine-readable JSON. 5. Report source and confidence: - `exact`: program and code matched - `inferred`: code found without verified program match - `unknown`: no registry entry 6. Never present inferred explanations as authoritative. 7. Work offline once registry data is installed. ### Commands ```bash solerr decode --program <ADDRESS> --error <VALUE> solerr logs ./simulation.log solerr idl add ./program.json --program <ADDRESS> solerr registry validate ./registry solerr registry build ./registry --out errors.json ``` ### Registry Entry ```json { "program": "<PROGRAM_ID>", "code": 6001, "name": "SlippageExceeded", "message": "Minimum output was not met.", "remediation": [ "Refresh the quote.", "Verify token decimals and slippage settings." ], "source": { "type": "idl", "reference": "program.json" } } ``` ### Safety Rules - Reject duplicate program-and-code pairs during validation. - Keep remediation text separate from canonical program messages. - Display the program address in every result. - Allow registry entries to declare deployment or IDL versions. - Do not guess causes from error names alone. ### Acceptance Criteria - A fixture suite covers decimal, hex, nested RPC, and log inputs. - CLI exits nonzero for malformed input, but not for valid unknown errors. - JSON output remains stable and documented. - Registry validation identifies duplicates and missing required fields. - All decoding tests run without network access. ### Launch Copy **Stop searching source trees for `0x1771`.** `solerr` is a local-first decoder for Solana custom program errors. Point it at an error and program address to get the decimal code, IDL name, explanation, remediation notes, source, and confidence level. The first release should prioritize reliable decoding over registry size. Contributions can add IDLs and error definitions through validated, reviewable files.

# Self-Directed Draft — Solana Privilege Map ## Product Specification **Working name:** `privilege-map` **Format:** Local CLI with CI support **Audience:** Solana application, wallet, and program teams ### Problem A transaction may request more authority than its interface communicates. Users and reviewers need a readable summary of signers, writable accounts, program calls, token movements, and authority changes before release. ### Product `privilege-map` statically inspects serialized transactions or transaction-building test cases and produces a deterministic privilege report. It does not submit or sign transactions. ### Core Commands ```bash # Inspect a base64-encoded transaction privilege-map inspect --transaction tx.txt # Compare transaction privileges against an approved policy privilege-map check --transaction tx.txt --policy privilege-policy.json # Compare two builds privilege-map diff old-tx.txt new-tx.txt ``` ### Report Format ```text Transaction Privilege Report Required signatures: - fee_payer - user_authority Writable accounts: - user_token_account - destination_token_account Program invocations: - System Program - Token Program - Unknown: <program-id> Detected effects: - SOL transfer: fee_payer -> recipient - Token transfer: user_token_account -> destination_token_account - Authority change: none detected Warnings: - Unknown program receives one writable account - Destination address is not allowlisted ``` ### Policy File ```json { "maxSigners": 2, "allowUnknownPrograms": false, "allowedPrograms": ["<program-id>"], "allowedWritableAccounts": ["<address-or-label>"], "allowAuthorityChanges": false, "allowTokenAccountClosure": false, "maxLamportsTransferred": "10000000" } ``` ### CI Behavior Exit codes: - `0`: transaction satisfies policy - `1`: policy violation - `2`: malformed or unsupported input - `3`: unresolved address lookup table or incomplete account data CI output must identify the exact added privilege: ```text FAIL: signer count increased from 1 to 2 FAIL: unapproved writable account: <address> FAIL: authority-changing instruction detected ``` ### MVP Scope - Legacy and versioned transaction decoding - Static signer and writable-account extraction - Program invocation inventory - Address lookup table resolution from supplied fixtures - Recognition of common System and Token Program instructions - JSON, Markdown, and terminal output - Policy enforcement and transaction-to-transaction diffing - Fully offline operation when all fixtures are provided ### Non-Goals - Simulating arbitrary program behavior - Guaranteeing transaction safety - Signing, broadcasting, or modifying transactions - Automatically approving unknown instructions ### Acceptance Criteria 1. Identical inputs always generate identical reports. 2. Missing lookup-table data produces an explicit unresolved result. 3. A newly added signer, writable account, or program causes `diff` to fail when configured. 4. Unknown instructions are preserved as raw program ID and data metadata rather than guessed. 5. Reports never display private keys or secret environment values. 6. The CLI can run in CI without network access. ### Launch Cut Ship a TypeScript CLI with five fixture transactions, a documented policy schema, GitHub Actions example, and redacted Markdown reports suitable for security review.

# Self-Directed Draft — Solana Transaction Fixture Lab ## Product Specification **Working name:** `tx-fixture` **Format:** Local CLI and CI utility **Audience:** Solana program, SDK, and application teams ### Problem Transaction-building changes can silently alter account ordering, signer requirements, instruction data, compute usage, or expected failures. Tests tied to live infrastructure are often difficult to reproduce. ### Product `tx-fixture` captures sanitized transaction simulations as deterministic fixtures, then compares future simulations against approved expectations. ### Core Workflow ```bash # Record a fixture from a transaction builder tx-fixture record --script ./tests/create-order.ts --out fixtures/create-order.json # Re-run and compare tx-fixture check fixtures/create-order.json # Review intentional changes tx-fixture update fixtures/create-order.json ``` ### Fixture Format ```json { "name": "create-order", "cluster": "local", "expected": { "success": true, "error": null, "logPatterns": ["Program log: order created"], "computeUnits": { "max": 180000 }, "accountChanges": [ { "alias": "order", "owner": "$PROGRAM_ID", "lamportsDelta": { "min": 1 }, "dataHashChanged": true } ] } } ``` Fixtures must not store private keys. Addresses can be replaced with stable aliases. Volatile fields such as blockhashes, signatures, slot numbers, and exact fees are excluded by default. ### Commands - `record`: Execute a transaction-builder script and create a fixture. - `check`: Simulate and produce a field-level diff. - `update`: Rewrite expectations after explicit confirmation. - `sanitize`: Remove signatures and replace configured addresses with aliases. - `lint`: Detect secrets, unstable fields, and overly broad assertions. ### Comparison Rules - Ordered comparison for instruction program IDs and account metas. - Exact or pattern-based matching for logs and errors. - Threshold matching for compute units and balance deltas. - Optional hashes for account data before and after simulation. - Per-field ignore rules with a required explanation. ### CI Output ```text FAIL create-order instruction[0].accounts[3].isWritable: false -> true computeUnits: 142,810 -> 191,204 (maximum: 180,000) missing log pattern: "Program log: order created" ``` Exit codes: - `0`: all fixtures pass - `1`: behavioral difference - `2`: invalid fixture or configuration - `3`: simulation unavailable ### MVP Boundaries - TypeScript transaction-builder adapter - Local validator and configurable RPC simulation - JSON fixtures committed to source control - Human-readable and JSON diff reports - No transaction submission - No key generation or custody ### Acceptance Criteria 1. A user can record and replay one fixture with three commands or fewer. 2. Output identifies the exact changed instruction, account meta, log, or threshold. 3. Fixture files contain no signatures or secret-key material. 4. Identical inputs produce no diff after volatile-field normalization. 5. CI can consume both exit codes and machine-readable reports.

# Self-Directed Draft — Solana Account Schema Diff ## Product Specification **Working name:** `account-diff` **Format:** Local CLI for release checks **Audience:** Solana teams maintaining programs, indexers, dashboards, and client SDKs ### Problem A program upgrade can alter account layouts, discriminators, enum variants, or instruction arguments. Downstream clients may continue compiling while silently decoding data incorrectly. Teams need a deterministic comparison before publishing a new program build or IDL. ### Proposed solution `account-diff` compares two local interface snapshots and produces a compatibility report. Inputs may include: - Anchor IDL JSON files - Borsh schema descriptions - Manually defined account schemas - Instruction argument definitions The tool classifies each change as: - **Safe:** additive optional metadata or documentation-only changes - **Review:** new fields, reordered declarations, changed defaults - **Breaking:** removed fields, changed field types, discriminator changes, enum variant changes, instruction argument changes ### Example commands ```bash account-diff old/idl.json new/idl.json account-diff old/schema.yaml new/schema.yaml --format markdown account-diff old/idl.json new/idl.json --fail-on breaking ``` ### Example output ```text BREAKING account Position field "size": u64 -> u128 REVIEW account User added field "referrer": Option<Pubkey> SAFE instruction close_position documentation changed Result: 1 breaking, 1 review, 1 safe ``` ### MVP requirements 1. Parse two supported schema formats. 2. Normalize field names, types, optionality, enums, and instruction arguments. 3. Detect additions, removals, reordering, and type changes. 4. Emit terminal, JSON, and Markdown reports. 5. Return nonzero exit codes for configurable severity thresholds. 6. Include an ignore file for intentional changes. 7. Never access a wallet, submit transactions, or require network access. ### Suggested compatibility rules - Removing or renaming a field: **breaking** - Changing a field type or optionality: **breaking** - Reordering serialized fields: **breaking** - Adding a required serialized field: **breaking** - Adding an optional field: **review** - Adding an enum variant: **review**, configurable as breaking - Documentation-only changes: **safe** - Instruction argument changes: **breaking** by default ### Release checklist - [ ] Compare the previous published schema with the candidate schema. - [ ] Review every non-safe change. - [ ] Record migration steps for breaking changes. - [ ] Run downstream decoder tests. - [ ] Store the generated report with the release artifact. - [ ] Require an explicit override for intentional breaking changes. ### Success criterion A reviewer can run one command and identify whether a proposed Solana interface change is safe to release, requires review, or needs a migration.

# Self-Directed Draft — Solana RPC Readiness Probe ## Product Specification **Working name:** `rpc-ready` **Format:** Open-source CLI and CI action **Audience:** Solana application, infrastructure, and release teams ### Problem Applications may depend on RPC methods, transaction versions, commitment levels, or response fields that are unavailable or configured differently across endpoints. These incompatibilities are often discovered after deployment. ### Product `rpc-ready` runs a configurable suite of read-only checks against one or more Solana RPC endpoints and returns a portable compatibility report. It never requests private keys or submits transactions. ### Example Configuration ```yaml endpoints: - name: primary url_env: PRIMARY_RPC_URL - name: fallback url_env: FALLBACK_RPC_URL checks: - rpc_health - genesis_hash - latest_blockhash - block_height - prioritization_fees - versioned_transaction_support requirements: max_latency_ms: 1500 same_genesis_hash: true required_methods: - getLatestBlockhash - getRecentPrioritizationFees ``` ### CLI ```bash rpc-ready check --config rpc-ready.yml rpc-ready check --config rpc-ready.yml --json report.json rpc-ready compare primary fallback ``` ### Report Shape ```json { "status": "fail", "endpoints": [ { "name": "primary", "reachable": true, "latency_ms": 284, "checks": { "rpc_health": "pass", "latest_blockhash": "pass", "prioritization_fees": "fail" } } ], "violations": [ { "rule": "required_methods", "endpoint": "primary", "detail": "getRecentPrioritizationFees unavailable" } ] } ``` ### Exit Codes - `0`: all requirements passed - `1`: compatibility requirement failed - `2`: invalid configuration - `3`: no endpoint was reachable ### Safety and Privacy - Read-only JSON-RPC requests - Endpoint URLs loaded from environment variables - Credentials redacted from logs and reports - Configurable timeouts and concurrency limits - No transaction signing, simulation, or submission ### MVP Acceptance Criteria - Supports multiple endpoints and deterministic checks - Produces human-readable and JSON output - Detects endpoint disagreement on genesis hash - Identifies missing required RPC methods - Measures request latency without presenting it as a service-level guarantee - Redacts URL credentials in every output path - Works locally and returns CI-friendly exit codes - Includes mocked tests for success, timeout, malformed response, and method-not-found cases ### Initial Positioning Copy **Know whether your Solana RPC endpoints support your app before release.** `rpc-ready` turns infrastructure assumptions into repeatable checks. Define the RPC capabilities your application needs, test primary and fallback endpoints, and block releases when required behavior is missing—all without signing or sending a transaction.

# Self-Directed Draft — Solana Transaction Failure Packager ## Product Specification **Working name:** `tx-case` **Format:** Local CLI **Audience:** Solana application, wallet, and support teams ### Problem Failed transactions are often reported with incomplete context: a screenshot, an error string, or a signature without the transaction inputs needed to reproduce the issue. Sensitive fields may also be copied into public tickets accidentally. ### Product `tx-case` creates a sanitized, portable debugging bundle from locally supplied transaction data and optional simulation output. ```bash tx-case pack \ --transaction ./failed-tx.json \ --simulation ./simulation.json \ --out ./case.zip tx-case inspect ./case.zip tx-case verify ./case.zip ``` ### Bundle Contents ```text manifest.json transaction.json simulation.json logs.txt accounts-summary.json README.md ``` `manifest.json` records: - Bundle schema version - Cluster label supplied by the user - Creation timestamp - Transaction encoding - Redaction rules applied - SHA-256 digest for each included file ### Default Sanitization The tool should: - Remove RPC URLs and authorization headers - Exclude keypair files and secret-key-shaped arrays - Replace user-selected public keys with stable aliases - Truncate oversized account data unless explicitly retained - Warn before packaging memo text or arbitrary instruction data - Never submit, sign, or broadcast transactions ### MVP Commands - `pack`: Create a case bundle - `inspect`: Print instructions, account roles, logs, and errors - `verify`: Validate file digests and schema - `redact`: Preview and configure sanitization - `unpack`: Extract a bundle for local debugging ### Configuration ```yaml cluster: devnet aliases: "ExamplePublicKey": "USER_WALLET" retain: instruction_data: true account_data: false limits: max_log_lines: 500 max_file_kb: 1024 ``` ### Acceptance Criteria 1. Identical inputs and configuration produce equivalent bundle contents, excluding timestamps. 2. `pack` refuses files containing detected secret-key material unless removed. 3. `inspect` works without network access. 4. `verify` reports modified or missing files. 5. Every redaction is listed in the manifest without exposing the removed value. 6. Invalid transaction encodings return actionable errors and a nonzero exit code. ### Initial Positioning Copy **Turn an incomplete “transaction failed” report into a reproducible case.** `tx-case` packages transaction inputs, simulation results, logs, and account roles into one sanitized bundle. Share useful debugging context without sharing RPC credentials or secret keys.

# Self-Directed Draft — Solana Privilege Surface Auditor ## Product Specification **Working name:** `account-lint` **Format:** CLI and CI check **Audience:** Solana program and SDK teams ### Problem Instruction changes can unintentionally expand transaction privileges—for example, making an account writable or requiring an additional signer. These changes increase risk and may break wallet, multisig, or integration flows. ### Product `account-lint` compares an instruction’s expected account privileges against a committed policy file. CI fails when signer, writable, ownership, or optional-account requirements drift without explicit approval. ### Policy Format ```yaml program: treasury instructions: withdraw: accounts: authority: signer: true writable: false vault: signer: false writable: true owner: self destination: signer: false writable: true max_signers: 1 remaining_accounts: deny ``` ### CLI ```bash account-lint init ./target/idl/treasury.json account-lint check ./target/idl/treasury.json account-lint diff old-idl.json new-idl.json ``` Example output: ```text FAIL withdraw.destination writable: false → true FAIL withdraw signer count: 1 → 2 PASS deposit 2 unapproved privilege changes found. ``` ### Core Rules - Detect newly writable accounts. - Detect newly required signers. - Detect removed ownership constraints represented in the IDL. - Flag newly permitted remaining accounts. - Flag required/optional account changes. - Enforce per-instruction signer limits. - Ignore ordering-only changes. - Support an explicit approval command: ```bash account-lint approve --instruction withdraw --reason "Destination now receives lamports" ``` Approvals update the policy and append a human-readable changelog entry. ### CI Contract - Exit `0`: policy matches. - Exit `1`: unapproved privilege drift. - Exit `2`: invalid IDL or policy. - Emit text and JSON reports. - Never submit transactions or require private keys. ### MVP Scope 1. Parse Anchor IDLs. 2. Generate a baseline policy. 3. Compare account metadata by instruction and account name. 4. Produce terminal and JSON diffs. 5. Provide a GitHub Actions example. 6. Add fixtures covering signer, writable, optional, and account-removal changes. ### Acceptance Criteria - A newly writable account causes a nonzero exit. - Account reordering produces no warning. - Every finding identifies the instruction, account, old value, and new value. - Invalid policies fail closed. - A repository can adopt the tool with one generated policy file and one CI command. ### Positioning Copy **Catch privilege creep before deployment.** `account-lint` turns Solana instruction account permissions into a reviewable CI policy, highlighting unexpected signer and writable-account changes before they reach users.

# Self-Directed Draft — Solana IDL Drift Sentinel ## Product Specification **Working name:** `idl-drift` **Format:** Local CLI and CI check **Audience:** Solana teams maintaining Anchor programs, SDKs, and client integrations ### Problem A program’s generated IDL, committed IDL, and client-facing types can diverge. This creates confusing failures: renamed instructions, changed account layouts, missing arguments, or clients calling an outdated interface. ### Core promise Detect interface drift before it reaches an integration environment by comparing two IDL files or an IDL against a generated artifact. ## MVP ### Command ```bash idl-drift check \ --expected ./idl/expected.json \ --actual ./target/idl/program.json \ --format text ``` ### Checks - Instruction added or removed - Instruction argument added, removed, reordered, or type-changed - Account field added, removed, reordered, or type-changed - Account mutability or signer requirement changed - Type or enum variant changed - Error code or name changed - Program address changed, when present - Metadata/version mismatch, reported separately from breaking changes ### Severity model - **BREAKING:** Existing clients may fail or decode data incorrectly - **WARNING:** Review required, but compatibility may be preserved - **INFO:** Non-functional metadata or documentation change ### Example output ```text BREAKING instructions.deposit.args[1] amount: u64 -> u128 BREAKING accounts.deposit.vault isMut: false -> true WARNING errors[6003] name: VaultPaused -> DepositsPaused Summary: 2 breaking, 1 warning, 0 info ``` ## Compatibility rules The tool should support a repository configuration file: ```toml [compatibility] allow_instruction_additions = true allow_account_field_additions = false allow_error_renames = false ``` Defaults should favor safety. Every finding should include a stable path so teams can suppress or review a specific change. ## Repository layout ```text idl-drift/ ├── src/ ├── fixtures/ │ ├── compatible/ │ ├── breaking/ │ └── malformed/ ├── README.md └── Cargo.toml ``` ## Acceptance criteria - Exits `0` when no breaking findings exist. - Exits nonzero when a breaking finding exists. - Emits deterministic output suitable for CI logs. - Handles malformed JSON with a clear file-and-line error. - Produces JSON output for annotations and downstream tooling. - Includes fixture tests for each check listed above. - Never treats array ordering as meaningful where the IDL format defines entries by name; preserves ordering checks only for positional arguments and fields where decoding depends on order. ## Suggested CI usage ```yaml - name: Check IDL compatibility run: | idl-drift check \ --expected ./idl/committed.json \ --actual ./target/idl/program.json \ --format github ``` ## Future extensions - Compare IDL against a TypeScript client schema. - Generate a human-readable migration report. - Track approved breaking changes in a versioned policy file. - Add a machine-readable compatibility score without hiding individual findings.

# Self-Directed Draft — Solana Transaction Reproduction Bundle ## Product Specification **Working name:** `tx-repro` **Format:** Open-source CLI **Audience:** Solana program developers debugging failed or unexpected transactions ### Problem Bug reports often contain only a transaction signature. Reproducing the issue later requires manually collecting the transaction, logs, account states, program versions, and runtime context. ### Product `tx-repro` creates a portable, sanitized debugging bundle from a supplied RPC endpoint and transaction signature. ```bash tx-repro capture <SIGNATURE> \ --rpc <RPC_URL> \ --output ./repro-case tx-repro inspect ./repro-case tx-repro redact ./repro-case --config redactions.toml ``` ### Bundle Structure ```text repro-case/ ├── manifest.json ├── transaction.json ├── metadata.json ├── logs.txt ├── accounts/ │ ├── <address>.json │ └── <address>.bin ├── programs.json ├── redactions.json └── README.md ``` ### MVP Requirements - Fetch the confirmed transaction and metadata. - Preserve message bytes, signatures, instructions, balances, logs, and errors. - Extract every referenced account address. - Fetch current account data while clearly labeling it as **capture-time state**, not transaction-time state. - Record RPC URL hostname, cluster identity response, capture timestamp, slot, CLI version, and file hashes. - Decode Anchor instructions when a local IDL is supplied. - Produce a human-readable summary of invoked programs and failing instruction index. - Support deterministic JSON output for clean diffs. - Redact configured addresses, log patterns, and account payloads. - Never upload bundles automatically. ### Manifest Example ```json { "schemaVersion": 1, "signature": "<SIGNATURE>", "transactionSlot": 0, "captureTime": "<ISO-8601>", "captureSlot": 0, "accountStateBasis": "capture-time", "files": [ { "path": "transaction.json", "sha256": "<HASH>" } ] } ``` ### Safety Rules - Warn that public-key redaction does not guarantee anonymity. - Store RPC credentials neither in output nor command history suggestions. - Mark unavailable or pruned data explicitly; never substitute guessed values. - Require `--include-account-data` before saving raw account bytes. - Display bundle contents before archive creation. ### Acceptance Criteria 1. Repeated captures of identical RPC responses produce identical normalized files. 2. Partial RPC failures leave a valid bundle with an error inventory. 3. Secrets matching configured patterns do not appear in the redacted archive. 4. `inspect` works offline. 5. Exit codes distinguish complete capture, partial capture, invalid input, and RPC failure. ### Initial Scope Boundary The MVP packages evidence; it does not claim deterministic replay. Local validator import, historical account reconstruction, and automated root-cause diagnosis remain future work.

# Self-Directed Draft — Solana CPI Boundary Linter ## Product Specification **Working name:** `cpi-guard` **Format:** CLI that analyzes Rust Anchor/native Solana programs and emits CI-friendly findings **Audience:** Solana teams reviewing cross-program invocations before merge ### Problem CPI integrations often fail because the caller and callee disagree about account mutability, signer requirements, PDA derivation, or instruction data. These issues are usually discovered during integration tests rather than code review. ### MVP Analyze a configured set of CPI call sites and produce: - A human-readable terminal report - JSON findings for CI annotations - A machine-readable account contract for each invocation - A review checklist for unresolved assumptions ### Inputs ```text cpi-guard.toml src/ tests/ optional: IDL or interface definitions ``` Example configuration: ```toml [project] name = "example-program" [[target]] file = "programs/example/src/instructions/swap.rs" function = "execute_swap" callee = "target_program" ``` ### Detection Rules | Rule | Severity | Finding | |---|---:|---| | `CPI001` | Error | Account marked writable by caller but not expected by the declared interface | | `CPI002` | Error | Required signer is absent from the CPI account metas | | `CPI003` | Error | PDA signer seeds are incomplete, mismatched, or not documented | | `CPI004` | Warning | Account ordering is derived indirectly and lacks an explicit contract | | `CPI005` | Warning | CPI instruction data is assembled from unvalidated user input | | `CPI006` | Info | Remaining accounts are forwarded without an allowlist or rationale | | `CPI007` | Warning | Account is unnecessarily writable | | `CPI008` | Error | Program ID is supplied dynamically without an explicit validation rule | ### Output Terminal example: ```text CPI contract: execute_swap -> target_program ERROR CPI002: `vault_authority` is required to sign but no signer meta was found. WARN CPI007: `token_program` is writable but the call contract marks it read-only. INFO CPI006: 2 remaining accounts forwarded; add an allowlist or justification. Result: 2 errors, 1 warning, 1 info ``` JSON finding schema: ```json { "rule": "CPI002", "severity": "error", "file": "programs/example/src/instructions/swap.rs", "line": 84, "callee": "target_program", "account": "vault_authority", "message": "Required signer is absent from CPI account metas.", "remediation": "Add the signer meta or document why the callee does not require it." } ``` ### Safety Boundaries - Never submit transactions. - Never modify source files automatically in MVP. - Treat unresolved interface details as findings, not as proven vulnerabilities. - Require explicit configuration when static analysis cannot infer account ownership or PDA seeds. ### Acceptance Criteria 1. Exits non-zero when any `Error` finding is present. 2. Produces deterministic JSON for identical inputs. 3. Includes source file and line for every code-derived finding. 4. Supports a baseline file so existing findings can be reviewed without being silently ignored. 5. Includes fixture tests for signer mismatch, writable mismatch, dynamic program ID, and remaining accounts. ### Suggested First Milestone Implement the configuration parser, finding schema, baseline comparison, and four rules: `CPI001`, `CPI002`, `CPI006`, and `CPI008`.

# Self-Directed Draft — Solana Program Upgrade Go/No-Go Checklist **Purpose:** A reusable release gate for teams upgrading a Solana program. Copy into each release issue and attach evidence where requested. ## Release Record - Program: - Cluster: - Current program ID: - Upgrade authority: - Release commit: - Build artifact hash: - Proposed deployment slot/time: - Release owner: - Rollback owner: ## 1. Build Integrity - [ ] Release commit is reviewed and immutable. - [ ] Build uses pinned toolchain and dependency versions. - [ ] Artifact was produced from the recorded commit. - [ ] Artifact hash is recorded independently by two team members. - [ ] Deployed program ID is hard-coded or validated in client configuration. - [ ] IDL/API changes are documented. **Evidence:** commit, build command, toolchain versions, artifact hash. ## 2. Test Gates - [ ] Unit and integration suites pass. - [ ] Upgrade was rehearsed against a local validator or designated test environment. - [ ] Tests cover account migrations and backward compatibility. - [ ] Privileged instructions reject unauthorized signers. - [ ] Expected failures return recognizable errors. - [ ] Compute usage and transaction size remain within the team’s operating thresholds. - [ ] Client and indexer behavior was tested against the candidate release. **Evidence:** test output and rehearsal transaction references. ## 3. State and Migration Safety - [ ] Every changed account layout has an explicit migration path. - [ ] Migration can resume safely after partial completion. - [ ] Existing accounts remain readable until migrated. - [ ] Rent, reallocations, ownership, and signer requirements were reviewed. - [ ] Affected accounts and estimated migration batches are listed. - [ ] Pre-upgrade state snapshots or recovery inputs are stored securely. ## 4. Authority Controls - [ ] Upgrade authority address was verified through a second channel. - [ ] Required multisig approvals and signer availability are confirmed. - [ ] No private keys appear in scripts, logs, tickets, or shell history. - [ ] Deployment commands specify the intended cluster and program ID explicitly. - [ ] Authority transfer or revocation, if planned, has a separate reviewed procedure. ## 5. Operations - [ ] Deployment and migration commands were peer-reviewed. - [ ] RPC endpoint and fallback endpoint are configured. - [ ] Monitoring covers errors, failed transactions, migration progress, and critical state changes. - [ ] User-facing maintenance copy is prepared. - [ ] Support owner and incident channel are assigned. - [ ] Stop conditions are written before deployment. **Stop conditions:** 1. 2. 3. ## 6. Recovery Plan - [ ] Previous artifact and source commit are available. - [ ] Team has documented whether rollback is technically possible. - [ ] Forward-fix procedure exists where rollback cannot restore changed state. - [ ] Migration halt procedure is tested. - [ ] Decision-maker for rollback or forward-fix is named. ## Final Approval - [ ] Engineering: **GO / NO-GO** - [ ] Security: **GO / NO-GO** - [ ] Operations: **GO / NO-GO** - [ ] Release owner: **GO / NO-GO** **Decision:** **Time:** **Approvers:** **Open risks accepted:**

# Self-Directed Draft — Solana Transaction Failure Reproducer ## Product Specification **Working name:** `tx-repro` **Format:** Local CLI plus versioned JSON fixture **Audience:** Solana program teams, SDK maintainers, and bug reporters ### Problem A failed transaction is hard to reproduce from a chat message or explorer URL alone. Teams need a shareable fixture containing the exact instruction inputs, account metadata, transaction settings, and observed simulation result—without requiring private keys or live network access. ### Core promise Turn a captured transaction attempt into a deterministic, redacted reproduction bundle that can be inspected and replayed against a chosen RPC endpoint. ## CLI ```bash tx-repro capture --signature <SIG> --rpc <URL> --out repro.json tx-repro redact repro.json --out safe-repro.json tx-repro inspect safe-repro.json tx-repro simulate safe-repro.json --rpc <URL> tx-repro diff before.json after.json ``` ## Fixture schema ```json { "schemaVersion": 1, "cluster": "custom", "blockhash": "<optional>", "lastValidBlockHeight": 0, "message": { "version": "legacy", "instructions": [ { "programId": "<address>", "accounts": [ { "pubkey": "<address>", "isSigner": false, "isWritable": true, "label": "user_state" } ], "dataBase64": "<bytes>" } ] }, "signers": [ { "pubkey": "<address>", "secretKey": null } ], "observed": { "err": null, "logs": [], "unitsConsumed": null, "returnData": null }, "notes": [] } ``` ## Safety requirements - Never export secret keys by default. - Replace signer secrets with `null` during capture. - Redact configured addresses and instruction data ranges. - Warn when fixtures contain token amounts, memo text, or identifiable accounts. - Treat fixture files as sensitive until explicitly sanitized. - Simulation must not submit a transaction. ## Validation rules `inspect` should report: - Missing or malformed public keys. - Duplicate account metas. - Signer accounts without a corresponding signer entry. - Writable accounts that changed from a baseline fixture. - Unsupported transaction versions. - Invalid base64 instruction data. - Absent simulation results. ## Acceptance criteria - A fixture can be generated without private-key access. - The sanitized fixture is valid JSON and self-contained. - Two fixtures produce a readable account-meta and instruction-data diff. - Simulation output preserves logs, error details, and compute usage when supplied by the RPC. - The tool clearly labels fields that are captured observations versus user annotations. ## Initial implementation 1. Define the JSON schema and TypeScript types. 2. Implement fixture validation and redaction. 3. Add transaction-message decoding. 4. Add RPC simulation adapter. 5. Add stable Markdown rendering for issue templates. 6. Test against hand-written fixtures for legacy and versioned messages.

# Self-Directed Draft — Solana Account Fixture Builder ## Product Specification **Working name:** `account-fixtures` **Format:** Local CLI and small TypeScript library **Audience:** Solana program teams, SDK authors, and integration-test maintainers ### Problem Program tests often depend on difficult-to-recreate account state. Teams need a repeatable way to turn selected account data into safe, versioned fixtures without embedding private keys, live RPC dependencies, or undocumented setup steps. ### Core promise Create deterministic account fixtures from supplied account data, validate them locally, and load them into tests with one reusable interface. ## MVP ### CLI commands ```bash account-fixtures init ./fixtures account-fixtures add \ --address <PUBKEY> \ --owner <PROGRAM_ID> \ --lamports <NUMBER> \ --executable false \ --data-base64 <BASE64> account-fixtures validate ./fixtures account-fixtures export ./fixtures --format json ``` ### Fixture format ```json { "schemaVersion": 1, "label": "example-state", "accounts": [ { "address": "PUBLIC_KEY", "owner": "PROGRAM_ID", "lamports": 1000000, "executable": false, "rentEpoch": 0, "dataEncoding": "base64", "data": "BASE64_BYTES" } ] } ``` ### Library API ```ts import { loadFixtures, getAccount } from "account-fixtures"; const store = await loadFixtures("./fixtures/example-state.json"); const account = getAccount(store, "PUBLIC_KEY"); ``` The library should return explicit errors for missing accounts, malformed public keys, invalid base64, duplicate addresses, and unsupported schema versions. ## Safety requirements - Never accept or store secret keys. - Warn when fixture metadata contains likely sensitive labels. - Preserve bytes exactly; do not silently normalize account data. - Include a human-readable manifest listing source, date, and operator-provided notes. - Make network access opt-in and disabled by default. ## Acceptance criteria - Identical input produces identical output. - Validation catches malformed addresses, duplicate accounts, and invalid encodings. - Fixtures can be loaded in unit tests without an RPC connection. - A fixture diff shows account additions, removals, metadata changes, and byte-level data changes. - Documentation includes a redaction checklist before committing fixtures. ## Suggested repository layout ```text account-fixtures/ src/ cli.ts schema.ts validate.ts loader.ts diff.ts test/ examples/ README.md ``` ## First implementation slice 1. Define the JSON schema. 2. Implement `init`, `add`, and `validate`. 3. Add deterministic serialization. 4. Add TypeScript loading helpers. 5. Provide one example fixture and tests for invalid input. 6. Add a pre-commit example that runs fixture validation. **Positioning:** a small, offline-first fixture tool that makes Solana account state portable, reviewable, and testable.

# Self-Directed Draft — Solana Instruction Contract Linter ## Product Specification **Working name:** `ix-contract` **Format:** Local CLI with JSON and Markdown output **Audience:** Solana program teams, SDK maintainers, and integrators ### Problem Client integrations can break when an instruction’s accounts, arguments, signer requirements, or writable permissions change without a clear review. Existing tests may catch failures only after an SDK or frontend has been updated. ### Core concept Compare two instruction-contract snapshots and report breaking, risky, and non-breaking changes before they reach downstream consumers. A contract snapshot records: ```json { "program": "ExampleProgram", "instructions": [ { "name": "create_item", "accounts": [ {"name": "payer", "signer": true, "writable": true}, {"name": "item", "signer": false, "writable": true} ], "args": [ {"name": "title", "type": "string"} ] } ] } ``` ### MVP commands ```bash ix-contract snapshot --source ./idl.json --out contract.json ix-contract diff old-contract.json new-contract.json ix-contract check contract.json --policy policy.yaml ix-contract report contract.json --format markdown ``` ### Change classification **Breaking** - Instruction removed or renamed - Required account removed - Account changes from optional to required - Signer requirement added - Argument removed, reordered, or type changed - Writable account becomes read-only when clients may rely on mutation **Risky** - New required account - Writable permission added - New argument without a declared default strategy - Account order changed - Discriminator or instruction identifier changed **Non-breaking** - Optional account added - Documentation or display labels changed - New instruction added - Read-only account becomes optional Teams can override classifications in `policy.yaml`: ```yaml fail_on: - breaking - risky ignore: - writable_permission_added ``` ### Output example ```text Contract diff: v1 -> v2 BREAKING create_item.args[0] title: string -> bytes RISKY create_item.accounts[2] added required account: metadata Result: FAILED (1 breaking, 1 risky) ``` ### CI behavior - Exit `0` when all changes pass policy - Exit `1` when configured violations are found - Emit JSON for automated review comments - Emit Markdown suitable for pull-request artifacts - Never access a cluster or submit transactions ### Acceptance criteria - Detects the listed change classes with fixture-based tests - Produces deterministic output - Handles missing optional fields explicitly - Supports a baseline contract committed to version control - Explains every violation with old and new values - Includes a documented escape hatch requiring a reason ### Suggested repository layout ```text ix-contract/ src/ fixtures/ compatible/ breaking/ risky/ policies/ README.md CHANGELOG.md tests/ ``` ### Extension path Add adapters for generated client types, human-readable compatibility reports, and a review template that asks maintainers to confirm account ordering, signer behavior, argument encoding, and migration guidance.

# Self-Directed Draft — Solana Transaction Failure Triage Kit ## Product Specification **Working name:** `tx-triage` **Format:** Local CLI with optional CI artifact output **Audience:** Solana developers and support engineers investigating failed transactions ### Problem A failed transaction often produces scattered evidence: signature, logs, instruction index, program error, account keys, and recent code changes. Teams waste time manually collecting and formatting this information before debugging. ### Product `tx-triage` accepts a transaction signature or a saved JSON response, gathers available diagnostic data from a user-supplied RPC endpoint, and emits a concise, shareable incident report. ### Core command ```bash tx-triage inspect \ --signature <SIGNATURE> \ --rpc-url "$SOLANA_RPC_URL" \ --out triage-report.json ``` Offline mode: ```bash tx-triage inspect --input failed-transaction.json --format markdown ``` ### Report contents ```text Transaction: <signature> Status: failed | confirmed | unavailable Slot: <slot or unknown> Block time: <time or unknown> Failure summary: - First failing instruction: <index or unknown> - Program: <program ID or unknown> - Error: <custom code/name or raw message> - Log excerpt: <relevant lines> Accounts: - Writable accounts involved - Signer accounts involved - Program IDs invoked Suggested checks: - Confirm the expected program ID and deployed build - Compare account ownership and executable flags - Verify signer presence and account mutability - Re-run against the same cluster with matching commitment ``` The tool must label unknown or unavailable fields rather than infer them. ### MVP requirements 1. Accept signatures and JSON fixtures. 2. Support configurable RPC URL and commitment. 3. Parse common Solana RPC transaction response shapes. 4. Extract: - transaction status, - slot, - logs, - instruction index where identifiable, - invoked program IDs, - account indexes and signer/writable metadata. 5. Preserve raw response data in the output. 6. Produce Markdown and JSON. 7. Exit nonzero when the transaction is confirmed failed or required input is invalid. 8. Redact configurable account values from shared reports. ### Suggested project layout ```text src/ cli.ts rpc.ts parser.ts report.ts redaction.ts fixtures/ failed-transaction.json tests/ parser.test.ts report.test.ts ``` ### Acceptance criteria - A fixture with nested inner instructions produces a stable instruction tree. - Missing logs, metadata, or block time produce `unknown`, not fabricated values. - The same input yields deterministic JSON ordering. - Markdown output contains the signature and every raw error line. - Redaction tests prove configured public keys are replaced consistently. - No private keys, seed phrases, or transaction signing functionality exists in the tool. ### Future extensions - Decoder plugins for team-owned program errors. - Diff mode for two transactions. - GitHub issue template export. - Local rules file mapping error codes to troubleshooting steps.

# Self-Directed Draft — Solana Deployment Manifest ## Product Specification **Working name:** `deploy-manifest` **Format:** Local CLI with CI-friendly output **Audience:** Solana program teams managing devnet, testnet, and mainnet releases ### Problem Deployment mistakes are often configuration mistakes: the wrong cluster, program ID, buffer account, upgrade authority, or build artifact. Teams need a reviewable release record before sending a deployment command. ### Product `deploy-manifest` validates a declarative release file and produces a human-readable deployment checklist plus machine-readable results. It does not deploy programs or handle private keys. ### Example manifest ```yaml release: payments-v0.8.0 cluster: mainnet-beta program: id: "<PROGRAM_PUBKEY>" artifact: target/deploy/payments.so expected_sha256: "<ARTIFACT_HASH>" upgrade_authority: mode: multisig address: "<AUTHORITY_PUBKEY>" checks: require_clean_git: true require_simulation: true require_rollback_note: true ``` ### Core commands ```bash deploy-manifest check release.yaml deploy-manifest report release.yaml --format markdown deploy-manifest ci release.yaml --strict ``` ### Validation rules - Confirm the selected cluster is explicitly named. - Confirm the program ID matches the locally configured deployment target. - Hash the artifact and compare it with `expected_sha256`. - Warn when the working tree contains uncommitted changes. - Require an explicit upgrade-authority policy. - Require simulation evidence or a documented exception. - Require rollback or recovery notes. - Redact keypaths, environment variables, and secret values from output. - Exit nonzero in CI when a required check fails. ### Generated report ```markdown # Release Review: payments-v0.8.0 - Cluster: mainnet-beta - Artifact: PASS - Program ID: REVIEW REQUIRED - Upgrade authority policy: PASS - Clean git tree: FAIL - Simulation evidence: PASS - Rollback note: PASS ## Decision DO NOT DEPLOY until all required checks pass. ``` ### MVP acceptance criteria 1. A manifest can be validated locally without network access. 2. CI receives deterministic exit codes. 3. Reports never print secret material. 4. Every failed check includes a remediation message. 5. Teams can store the manifest and report beside a release tag. 6. The tool supports JSON output for custom dashboards. ### Useful extension Add a post-deployment verification mode that accepts operator-supplied public identifiers and compares observed state against the manifest, without initiating any transaction.

# Self-Directed Draft — Solana IDL Compatibility Gate ## Product Specification **Working name:** `idl-guard` **Format:** TypeScript CLI and GitHub Action **Audience:** Solana program teams publishing Anchor IDLs or client SDKs ### Problem An IDL change can silently break clients by renaming instructions, reordering accounts, changing argument types, or removing error definitions. Reviewers need a fast way to distinguish compatible additions from breaking interface changes. ### Core Command ```bash idl-guard compare \ --base ./idl/released.json \ --head ./target/idl/program.json \ --format markdown \ --fail-on breaking ``` ### MVP Behavior Compare two IDL files and classify changes: **Breaking** - Instruction removed or renamed - Instruction argument removed, reordered, or type-changed - Required account removed, reordered, renamed, or signer/writable status changed - Account or type field removed, reordered, or type-changed - Enum variant removed or structurally changed - Existing error code reassigned **Non-breaking** - New instruction - New account/type definition - New error appended with a unique code - Documentation-only edits **Review required** - Program address or metadata changed - Optional account added - Enum variant added - Unsupported or ambiguous IDL structure encountered ### Example Report ```md ## IDL Compatibility Report Result: ❌ Breaking changes detected ### Breaking - `deposit.accounts[2]`: `vault` changed from writable to read-only - `withdraw.args`: `amount: u64` changed to `amount: u128` - Error code `6003`: renamed from `Unauthorized` to `InvalidOwner` ### Non-breaking - Added instruction `pause` - Added error `6012: DepositsPaused` ``` ### Machine-Readable Output ```json { "result": "breaking", "counts": { "breaking": 3, "reviewRequired": 0, "nonBreaking": 2 }, "changes": [ { "severity": "breaking", "path": "instructions.withdraw.args.amount", "rule": "argument-type-changed", "before": "u64", "after": "u128" } ] } ``` ### Configuration ```json { "failOn": ["breaking"], "ignore": ["metadata.docs"], "treatAddedEnumVariantsAs": "review-required" } ``` ### Acceptance Criteria - Deterministic output for identical inputs - Nonzero exit code when configured severity is found - Markdown, JSON, and terminal output modes - Explicit handling of unsupported IDL versions - No network access required - Fixtures covering every classification rule - CI annotations identify the changed JSON path ### Launch Copy > Catch client-breaking Solana IDL changes before merge. `idl-guard` compares released and proposed IDLs, classifies compatibility risks, and produces CI-ready Markdown or JSON reports.

# Self-Directed Draft — Solana Transaction Reproduction Bundle ## Product Specification **Working name:** `tx-case` **Format:** TypeScript CLI **Audience:** Solana developers debugging failed or inconsistent transactions ### Problem Transaction reports often omit crucial context: cluster, slot, logs, account state, simulation settings, and client versions. This makes failures difficult to reproduce and share safely. ### Core Workflow ```bash tx-case capture \ --signature <SIGNATURE> \ --rpc <RPC_URL> \ --out case.json tx-case simulate case.json tx-case redact case.json --out case.public.json tx-case inspect case.json ``` The CLI may also capture an unsigned serialized transaction: ```bash tx-case capture --transaction tx.base64 --out case.json ``` ### Bundle Schema ```ts interface TransactionCase { schemaVersion: "1"; createdAt: string; source: { cluster?: string; rpcAlias?: string; // Never store RPC credentials signature?: string; slot?: number; }; transaction: { encoding: "base64"; data: string; recentBlockhash?: string; lastValidBlockHeight?: number; }; execution: { error?: unknown; logs: string[]; unitsConsumed?: number; returnData?: unknown; }; accounts: Array<{ address: string; owner?: string; lamports?: string; executable?: boolean; dataHash?: string; dataBase64?: string; }>; environment: { cliVersion: string; web3Version?: string; commitment?: string; }; redactions: string[]; } ``` ### Safety Defaults - Strip RPC query parameters and authentication headers. - Exclude account data unless `--include-account-data` is provided. - Detect likely secrets in logs and metadata. - Require `--allow-signatures` before retaining transaction signatures. - Never request, store, or reconstruct private keys. - Mark simulations that use replaced blockhashes or disabled signature checks. ### Inspection Output ```text Case: failed swap simulation Slot: 000000 Result: custom program error Programs invoked: 3 Log lines: 28 Captured accounts: 7 metadata-only Replay fidelity: PARTIAL Warnings: - Recent blockhash replaced - One account unavailable ``` ### Exit Codes - `0`: capture or simulation completed - `1`: transaction execution failed as recorded - `2`: malformed bundle - `3`: RPC or account-data retrieval failure - `4`: redaction policy violation ### MVP Acceptance Criteria - Accept a signature or base64 transaction. - Emit deterministic, schema-valid JSON. - Replay through RPC simulation with explicit fidelity warnings. - Produce a shareable redacted bundle. - Compare recorded and replayed errors, logs, and compute usage. - Run non-interactively in CI. - Include fixtures for success, program error, expired blockhash, and missing account cases. ### Initial Positioning Copy **Turn “the transaction failed” into a portable bug report.** `tx-case` captures transaction context, simulation logs, and selected account metadata in one redaction-aware JSON bundle—so Solana teams can inspect, replay, and compare failures without passing around private RPC URLs or signing keys.